Feature Request: Add public API for checking environment staleness #34

A public API on Builder that checks whether an environment is up-to-date without triggering a build or modifying anything. This enables applications to quickly answer "does this environment need syncing?" before committing to an expensive rebuild.

The cost difference matters:

Use Cases

• Background health checks: An application can poll on startup or periodically to show a green/yellow/red environment status indicator, without blocking the user or triggering heavy operations.
• Pre-flight warnings: Before executing a script, quickly check whether the environment is stale and warn: "Environment may be out of sync. Rebuild recommended."
• Lazy sync with progress feedback: Use the check as a fast gate. If stale, show a progress UI and then call build(). The user only waits when a rebuild is actually needed.
• Appose.wrap() validation: After wrapping an existing environment, verify it is consistent before running user code.

Today, applications have no choice but to either always rebuild (slow) or blindly trust the environment (risky). This API removes that tradeoff.

Proposed API

public interface Builder<T extends Builder<T>> {
  // ... existing methods ...

  /**
   * Checks whether the environment at the default directory is up-to-date
   * without modifying anything.
   */
  boolean isUpToDate() throws IOException;

 /**
   * Performs a deeper check using tool-specific verification
   * (e.g., uv sync --check, pixi install --check).
   * Returns a result with details about what is out of sync.
   */
  CheckResult checkUpToDate() throws IOException;
}

public interface CheckResult {
  boolean isUpToDate();
  String description();
}

Two tiers: isUpToDate() for a fast config-level check (current protected api), checkUpToDate() for a deeper tool-level check that catches environment drift.

Existing Implementation

BaseBuilder already has a protected boolean isUpToDate(File envDir) method that compares appose.json against the current builder state. This is a starting point, but it has two problems:

1. Not public: isUpToDate() is protected on BaseBuilder, not declared on the Builder interface. External code cannot call it.
2. Only checks declared configuration: It compares the builder's input parameters (declaration file content, package lists, channels, etc.) against a stored snapshot. It cannot detect manual modifications (pip install/conda remove inside the env), lock file drift, or partial/corrupted builds. The deep check (checkUpToDate()) would need to invoke tool-specific commands to cover these cases.