Skip to content

Commit b72b7dc

Browse files
yzx9yzx9
committed
Add public API for checking environment staleness
Add isUpToDate() and checkUpToDate() to Builder and Environment, enabling applications to check whether an environment needs syncing without triggering a build. The fast isUpToDate() compares against appose.json; checkUpToDate() may additionally invoke tool-specific verification (e.g., uv sync --dry-run) and returns a CheckResult with a verified() flag.
1 parent e8521f0 commit b72b7dc

13 files changed

Lines changed: 614 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,10 +65,14 @@ mvn clean package
6565
- **Environment**: Interface representing a configured environment
6666
- Core methods: `base()`, `binPaths()`, `launchArgs()`
6767
- Worker creation: `python()`, `groovy()`, `java()`, `service()`
68+
- Status methods: `isUpToDate()`, `checkUpToDate()`
6869
- **Builder**: Interface for environment builders
6970
- Implementations: `PixiBuilder`, `MambaBuilder`, `UvBuilder`, `SimpleBuilder`, `DynamicBuilder`
7071
- Core terminator method: `build()`
72+
- Status methods: `isUpToDate()`, `checkUpToDate()`
7173
- Subscription methods: `subscribeProgress()`, `subscribeOutput()`, `subscribeError()`, `logDebug()`
74+
- **CheckResult**: Result of an environment up-to-date check
75+
- Methods: `isUpToDate()`, `description()`, `verified()`
7276
- **BuilderFactory**: Factory for creating and discovering builders
7377
- Factory method: `createBuilder()`
7478
- Discovery methods: `name()`, `supportsScheme(scheme)`, `canWrap(File)`, `priority()`
@@ -114,6 +118,20 @@ Builders are type-safe and builder-specific:
114118
- Default environment location: `~/.local/share/appose/<env-name>`
115119
- Builders can wrap existing environments or create new ones
116120

121+
### Environment Status API
122+
123+
Several related methods answer different questions about environment state:
124+
125+
| Method | On | Question it answers |
126+
|--------|----|---------------------|
127+
| `BuilderFactory.canWrap(File)` | Factory | "Can this factory recognize this directory as a valid environment of its type?" |
128+
| `Builder.wrap(File)` | Builder | "Create an Environment from this existing directory?" |
129+
| `Builder.isUpToDate()` | Builder | "Has the builder's configuration changed since the last build?" (fast, reads `appose.json`) |
130+
| `Builder.checkUpToDate()` | Builder | "Is the environment actually in sync with its declared configuration?" (may run tool verification) |
131+
| `Builder.build()` | Builder | "Ensure the environment exists and is up-to-date, building if needed." |
132+
133+
`isUpToDate()` is fast (<0.01s) — it compares the builder's configuration against the stored `appose.json` snapshot. `checkUpToDate()` returns a `CheckResult` that may additionally invoke tool-specific verification (e.g., `uv sync --dry-run`) to detect environment drift beyond configuration changes. When `CheckResult.verified()` is `true`, a real tool was invoked; when `false`, only the config comparison was done.
134+
117135
### Worker Communication
118136
- **Request types**: EXECUTE (run script), CANCEL (stop execution)
119137
- **Response types**: LAUNCH, UPDATE, COMPLETION, CANCELATION, FAILURE, CRASH
@@ -240,6 +258,16 @@ Environment env = Appose.wrap("/path/to/existing/env");
240258

241259
// System environment
242260
Environment env = Appose.system();
261+
262+
// Fast config check — skip rebuild if unchanged
263+
if (!env.isUpToDate()) { env.rebuild(); }
264+
265+
// Verified check with details
266+
CheckResult result = env.checkUpToDate();
267+
if (!result.isUpToDate()) {
268+
System.out.println(result.description());
269+
if (result.verified()) { /* tool confirmed drift */ }
270+
}
243271
```
244272

245273
### Builder Discovery

‎src/main/java/org/apposed/appose/Builder.java‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,40 @@ default Environment rebuild() throws BuildException {
112112
*/
113113
void delete() throws IOException;
114114

115+
/**
116+
* Checks whether the environment is up-to-date based on configuration state.
117+
* <p>
118+
* This is a fast check that compares the builder's current configuration
119+
* against the previously recorded state in {@code appose.json}. No build
120+
* is triggered and no external tools are invoked.
121+
* </p>
122+
* <p>
123+
* Returns {@code false} if no environment has been built yet, or if the
124+
* builder's configuration has changed since the last build.
125+
* </p>
126+
*
127+
* @return {@code true} if the environment directory exists and its recorded
128+
* state matches the current builder configuration.
129+
* @throws BuildException if the environment directory cannot be resolved.
130+
*/
131+
boolean isUpToDate() throws BuildException;
132+
133+
/**
134+
* Checks whether the environment is up-to-date, optionally using
135+
* tool-specific verification to detect environment drift beyond
136+
* configuration changes (e.g., manually modified packages, corrupted builds).
137+
* <p>
138+
* If the underlying tool supports a verification command (e.g.,
139+
* {@code uv sync --dry-run}), it will be invoked and
140+
* {@link CheckResult#verified()} will return {@code true}.
141+
* Otherwise, falls back to the fast config-level check.
142+
* </p>
143+
*
144+
* @return A {@link CheckResult} describing the staleness state.
145+
* @throws BuildException if the environment directory cannot be resolved.
146+
*/
147+
CheckResult checkUpToDate() throws BuildException;
148+
115149
/**
116150
* Wraps an existing environment directory, detecting and using any
117151
* configuration files present for future rebuild() calls.

‎src/main/java/org/apposed/appose/CheckResult.java‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
/*-
2+
* #%L
3+
* Appose: multi-language interprocess cooperation with shared memory.
4+
* %%
5+
* Copyright (C) 2023 - 2026 Appose developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.apposed.appose;
31+
32+
/**
33+
* Result of an environment up-to-date check.
34+
*
35+
* @see Builder#checkUpToDate()
36+
* @see Environment#checkUpToDate()
37+
*/
38+
public interface CheckResult {
39+
40+
/**
41+
* Whether the environment is up-to-date.
42+
*/
43+
boolean isUpToDate();
44+
45+
/**
46+
* Human-readable description of the check result.
47+
* Explains why the environment is (or is not) up-to-date.
48+
*/
49+
String description();
50+
51+
/**
52+
* Whether a real tool verification was performed
53+
* (as opposed to a fast config-level comparison).
54+
* <p>
55+
* When {@code true}, the underlying package manager was actually invoked
56+
* to verify the environment is in sync. When {@code false}, only a fast
57+
* comparison of the builder configuration against the stored state was done.
58+
* </p>
59+
*/
60+
boolean verified();
61+
62+
// -- Factory methods --
63+
64+
/**
65+
* Creates a CheckResult indicating the environment is up-to-date.
66+
*
67+
* @param description Human-readable explanation of the check result.
68+
* @param verified Whether a real tool verification was performed.
69+
* @return A CheckResult with {@link #isUpToDate()} returning {@code true}.
70+
*/
71+
static CheckResult upToDate(final String description, final boolean verified) {
72+
return new CheckResult() {
73+
@Override public boolean isUpToDate() { return true; }
74+
@Override public String description() { return description; }
75+
@Override public boolean verified() { return verified; }
76+
};
77+
}
78+
79+
/**
80+
* Creates a CheckResult indicating the environment is stale.
81+
*
82+
* @param description Human-readable explanation of why the environment is stale.
83+
* @param verified Whether a real tool verification was performed.
84+
* @return A CheckResult with {@link #isUpToDate()} returning {@code false}.
85+
*/
86+
static CheckResult stale(final String description, final boolean verified) {
87+
return new CheckResult() {
88+
@Override public boolean isUpToDate() { return false; }
89+
@Override public String description() { return description; }
90+
@Override public boolean verified() { return verified; }
91+
};
92+
}
93+
}

‎src/main/java/org/apposed/appose/Environment.java‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,29 @@ default Environment delete() throws BuildException {
122122
return this;
123123
}
124124

125+
/**
126+
* Checks whether this environment's configuration is up-to-date.
127+
* Delegates to {@link Builder#isUpToDate()}.
128+
*
129+
* @return {@code true} if the environment is up-to-date.
130+
* @throws BuildException if the check cannot be performed.
131+
*/
132+
default boolean isUpToDate() throws BuildException {
133+
return builder().isUpToDate();
134+
}
135+
136+
/**
137+
* Checks whether this environment is up-to-date, optionally using
138+
* tool-specific verification to detect environment drift.
139+
* Delegates to {@link Builder#checkUpToDate()}.
140+
*
141+
* @return A {@link CheckResult} describing the staleness state.
142+
* @throws BuildException if the check cannot be performed.
143+
*/
144+
default CheckResult checkUpToDate() throws BuildException {
145+
return builder().checkUpToDate();
146+
}
147+
125148
/**
126149
* Creates a Python script service.
127150
* <p>

‎src/main/java/org/apposed/appose/builder/BaseBuilder.java‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131

3232
import org.apposed.appose.BuildException;
3333
import org.apposed.appose.Builder;
34+
import org.apposed.appose.CheckResult;
3435
import org.apposed.appose.Environment;
3536
import org.apposed.appose.Scheme;
3637
import org.apposed.appose.util.Environments;
@@ -83,6 +84,53 @@ public void delete() throws IOException {
8384
if (dir.exists()) FilePaths.deleteRecursively(dir);
8485
}
8586

87+
@Override
88+
public boolean isUpToDate() throws BuildException {
89+
File dir = resolveEnvDir();
90+
if (dir == null || !dir.isDirectory()) return false;
91+
try {
92+
return isUpToDate(dir);
93+
}
94+
catch (IOException e) {
95+
throw new BuildException(this, e);
96+
}
97+
}
98+
99+
@Override
100+
public CheckResult checkUpToDate() throws BuildException {
101+
File dir = resolveEnvDir();
102+
if (dir == null || !dir.isDirectory()) {
103+
return CheckResult.stale(
104+
"Environment directory does not exist: " + dir, false);
105+
}
106+
try {
107+
if (!isUpToDate(dir)) {
108+
return CheckResult.stale(
109+
"Configuration has changed since last build", false);
110+
}
111+
return verifyUpToDate(dir);
112+
}
113+
catch (IOException e) {
114+
return CheckResult.stale("Check failed: " + e.getMessage(), false);
115+
}
116+
}
117+
118+
/**
119+
* Performs a tool-specific verification that the environment is up-to-date.
120+
* Subclasses should override this to invoke their tool's dry-run or check command.
121+
* The default implementation returns a config-level-only result.
122+
*
123+
* @param envDir The environment directory to check.
124+
* @return A CheckResult indicating whether the environment is up-to-date.
125+
* @throws IOException If the check command fails.
126+
*/
127+
protected CheckResult verifyUpToDate(File envDir) throws IOException {
128+
return CheckResult.upToDate(
129+
"Config-level check passed; " + envType() +
130+
" does not support tool-level verification",
131+
false);
132+
}
133+
86134
@Override
87135
public Environment wrap(File envDir) throws BuildException {
88136
try {

‎src/main/java/org/apposed/appose/builder/DynamicBuilder.java‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
import org.apposed.appose.BuildException;
3333
import org.apposed.appose.Builder;
3434
import org.apposed.appose.BuilderFactory;
35+
import org.apposed.appose.CheckResult;
3536
import org.apposed.appose.Environment;
3637
import org.apposed.appose.Scheme;
3738

@@ -79,6 +80,20 @@ public Environment rebuild() throws BuildException {
7980
return delegate.rebuild();
8081
}
8182

83+
@Override
84+
public boolean isUpToDate() throws BuildException {
85+
Builder<?> delegate = createBuilder();
86+
copyConfigToDelegate(delegate);
87+
return delegate.isUpToDate();
88+
}
89+
90+
@Override
91+
public CheckResult checkUpToDate() throws BuildException {
92+
Builder<?> delegate = createBuilder();
93+
copyConfigToDelegate(delegate);
94+
return delegate.checkUpToDate();
95+
}
96+
8297
// -- Helper methods --
8398

8499
private void copyConfigToDelegate(Builder<?> delegate) {

‎src/main/java/org/apposed/appose/builder/MambaBuilder.java‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
package org.apposed.appose.builder;
3131

3232
import org.apposed.appose.BuildException;
33+
import org.apposed.appose.CheckResult;
3334
import org.apposed.appose.Environment;
3435
import org.apposed.appose.util.FilePaths;
3536
import org.apposed.appose.scheme.Schemes;
@@ -158,6 +159,13 @@ public Environment wrap(File envDir) throws BuildException {
158159
return build();
159160
}
160161

162+
@Override
163+
protected CheckResult verifyUpToDate(File envDir) throws IOException {
164+
// Micromamba has no dry-run for env update. Fallback to config-level.
165+
return CheckResult.upToDate(
166+
"Config-level check passed; mamba does not support tool-level verification", false);
167+
}
168+
161169
private Environment createEnvironment(Mamba mamba, File envDir) {
162170
String base = envDir.getAbsolutePath();
163171
List<String> launchArgs = Arrays.asList(mamba.command, "run", "-p", base);

‎src/main/java/org/apposed/appose/builder/PixiBuilder.java‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
package org.apposed.appose.builder;
3131

3232
import org.apposed.appose.BuildException;
33+
import org.apposed.appose.CheckResult;
3334
import org.apposed.appose.Environment;
3435
import org.apposed.appose.util.FilePaths;
3536
import org.apposed.appose.scheme.Schemes;
@@ -254,6 +255,13 @@ public Environment wrap(File envDir) throws BuildException {
254255

255256
// -- Helper methods --
256257

258+
@Override
259+
protected CheckResult verifyUpToDate(File envDir) throws IOException {
260+
// Pixi has no --dry-run flag for install. Fallback to config-level.
261+
return CheckResult.upToDate(
262+
"Config-level check passed; pixi does not support tool-level verification", false);
263+
}
264+
257265
/** Returns a new list with an additional flag appended. */
258266
private static List<String> withFlag(List<String> flags, String flag) {
259267
List<String> result = new ArrayList<>(flags);

‎src/main/java/org/apposed/appose/builder/SimpleBuilder.java‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131

3232
import org.apposed.appose.BuildException;
3333
import org.apposed.appose.Builder;
34+
import org.apposed.appose.CheckResult;
3435
import org.apposed.appose.Environment;
3536
import org.apposed.appose.util.Environments;
3637

@@ -122,6 +123,17 @@ public String envType() {
122123
return "custom";
123124
}
124125

126+
@Override
127+
public boolean isUpToDate() throws BuildException {
128+
return true;
129+
}
130+
131+
@Override
132+
public CheckResult checkUpToDate() throws BuildException {
133+
return CheckResult.upToDate(
134+
"Simple environments have no package management", false);
135+
}
136+
125137
@Override
126138
public Environment build() throws BuildException {
127139
File base = resolveEnvDir();

0 commit comments

Comments
 (0)