@smithers-orchestrator/vcs 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/vcs",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "VCS discovery and jj workspace operations for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -22,15 +22,22 @@
   "dependencies": {
     "@effect/platform": "^0.96.0",
     "effect": "^3.21.1",
-    "@smithers-orchestrator/observability": "0.22.0"
+    "@smithers-orchestrator/observability": "0.24.0"
   },
   "devDependencies": {
     "@effect/platform-bun": "^0.89.0",
     "@types/bun": "latest",
     "typescript": "~5.9.3"
   },
+  "optionalDependencies": {
+    "@smithers-orchestrator/jj-darwin-x64": "0.24.0",
+    "@smithers-orchestrator/jj-darwin-arm64": "0.24.0",
+    "@smithers-orchestrator/jj-linux-x64": "0.24.0",
+    "@smithers-orchestrator/jj-linux-arm64": "0.24.0",
+    "@smithers-orchestrator/jj-win32-x64": "0.24.0"
+  },
   "scripts": {
-    "build": "tsup --dts-only",
+    "build": "rm -f src/index.d.ts && tsup --dts-only",
     "test": "bun test tests",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }

package/src/ResolvedBinary.ts

@@ -0,0 +1,11 @@
+/**
+ * A resolved VCS executable plus where Smithers found it.
+ *
+ * - `env`: an explicit override (e.g. `SMITHERS_JJ_PATH`)
+ * - `bundled`: a binary shipped inside a `@smithers-orchestrator/jj-<platform>` package
+ * - `path`: the bare command name, left for the OS to resolve against `PATH`
+ */
+export type ResolvedBinary = {
+	path: string;
+	source: "env" | "bundled" | "path";
+};

package/src/WorkspaceSnapshot.ts

@@ -0,0 +1,16 @@
+export type WorkspaceSnapshot = {
+  /**
+   * Working-copy commit id at this snapshot. Advances on every snapshot, so it
+   * addresses an individual working-copy state (unlike `changeId`, which is
+   * stable across edits to the same working copy).
+   */
+  commitId: string;
+  /** Change id of `@`. Stable across edits to one working copy; grouping metadata only. */
+  changeId: string;
+  /**
+   * jj operation id for this snapshot. The durable restore handle: the commit id
+   * of an abandoned working-copy commit can be garbage-collected, while the
+   * operation log is retained under the configured gc policy.
+   */
+  operationId: string;
+};

package/src/index.d.ts

@@ -65,6 +65,19 @@ declare function runJj(args: string[], opts?: RunJjOptions): Effect.Effect<RunJj
  * @returns {Effect.Effect<string | null, never, import("@effect/platform/CommandExecutor").CommandExecutor>}
  */
 declare function getJjPointer(cwd?: string): Effect.Effect<string | null, never, _effect_platform_CommandExecutor.CommandExecutor>;
+/**
+ * Capture the current working-copy state as a restorable handle.
+ *
+ * Step 1 (`jj log -r @`) forces exactly one working-copy snapshot and returns the
+ * resulting `commit_id` and `change_id`. Step 2 reads the latest operation id
+ * WITHOUT taking a second snapshot (`--ignore-working-copy`), so both ids describe
+ * the same snapshot from step 1. Returns null on any failure or timeout (a
+ * durability gap the caller records); it never throws into the agent path.
+ *
+ * @param {string} [cwd]
+ * @returns {Effect.Effect<WorkspaceSnapshot | null, never, import("@effect/platform/CommandExecutor").CommandExecutor>}
+ */
+declare function captureWorkspaceSnapshot(cwd?: string): Effect.Effect<WorkspaceSnapshot | null, never, _effect_platform_CommandExecutor.CommandExecutor>;
 /**
  * Restore the working copy to a previously recorded jujutsu `change_id`.
  * Used by the engine to revert attempts within the correct repo/worktree (via `cwd`).
@@ -115,5 +128,92 @@ type RunJjResult = RunJjResult$1;
 type WorkspaceAddOptions = WorkspaceAddOptions$1;
 type WorkspaceInfo = WorkspaceInfo$1;
 type WorkspaceResult = WorkspaceResult$1;
+type WorkspaceSnapshot = {
+    /**
+     * Working-copy commit id for this snapshot.
+     */
+    commitId: string;
+    /**
+     * Stable JJ change id for the working copy.
+     */
+    changeId: string;
+    /**
+     * JJ operation id for the snapshot.
+     */
+    operationId: string;
+};
+
+/**
+ * A resolved VCS executable plus where Smithers found it.
+ *
+ * - `env`: an explicit override (e.g. `SMITHERS_JJ_PATH`)
+ * - `bundled`: a binary shipped inside a `@smithers-orchestrator/jj-<platform>` package
+ * - `path`: the bare command name, left for the OS to resolve against `PATH`
+ */
+type ResolvedBinary = {
+    path: string;
+    source: "env" | "bundled" | "path";
+};
+
+/**
+ * Resolve the `git` executable Smithers should spawn.
+ *
+ * Order of preference:
+ *   1. `SMITHERS_GIT_PATH` — an explicit override pointing at a real file.
+ *   2. The bare `"git"`, left for the OS to resolve against `PATH`.
+ *
+ * Git is never bundled (only jj is); this mirrors {@link resolveJjBinary} so the
+ * override and the tooling preflight share one source of truth for where git is.
+ *
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
+ */
+declare function resolveGitBinary(): ResolvedBinary;
+
+/**
+ * Resolve the `jj` executable Smithers should spawn.
+ *
+ * Order of preference:
+ *   1. `SMITHERS_JJ_PATH` — an explicit override pointing at a real file.
+ *   2. A binary bundled via `@smithers-orchestrator/jj-<platform>`.
+ *   3. The bare `"jj"`, left for the OS to resolve against `PATH`.
+ *
+ * Always returns a spawnable command. When jj is genuinely absent the bare
+ * `"jj"` simply fails to spawn, which `runJj` already normalizes to exit code
+ * 127, so callers keep their soft-failure behavior.
+ *
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
+ */
+declare function resolveJjBinary(): ResolvedBinary;
+
+/**
+ * Probe whether a usable `jj` and/or `git` exists for the current host, using
+ * the override → bundled → PATH resolution for jj and override → PATH for git.
+ *
+ * Synchronous and best-effort: used by `smithers doctor` and run preflights to
+ * tell the user — before a run fails deep in worktree creation — that no VCS
+ * tooling is installed, and which knob (bundled package, PATH install, or
+ * `SMITHERS_JJ_PATH`) would fix it.
+ *
+ * @returns {VcsToolingStatus}
+ */
+declare function vcsToolingStatus(): VcsToolingStatus;
+/**
+ * Whether a usable `jj` and/or `git` exists for the current host. Each field is
+ * the resolved binary when `<bin> --version` runs, or null when it does not.
+ */
+type VcsToolingStatus = {
+    /**
+     * a usable jj (override, bundled, or PATH), else null
+     */
+    jj: ResolvedBinary | null;
+    /**
+     * a usable git (override or PATH), else null
+     */
+    git: ResolvedBinary | null;
+    /**
+     * true when at least one of jj or git is usable
+     */
+    ok: boolean;
+};
 
-export { findVcsRoot, getJjPointer, isJjRepo, revertToJjPointer, runJj, workspaceAdd, workspaceClose, workspaceList };
+export { type JjRevertResult, type RunJjOptions, type RunJjResult, type VcsToolingStatus, type WorkspaceAddOptions, type WorkspaceInfo, type WorkspaceResult, type WorkspaceSnapshot, captureWorkspaceSnapshot, findVcsRoot, getJjPointer, isJjRepo, resolveGitBinary, resolveJjBinary, revertToJjPointer, runJj, vcsToolingStatus, workspaceAdd, workspaceClose, workspaceList };

package/src/index.js

@@ -1,8 +1,5 @@
 export * from "./find-root.js";
 export * from "./jj.js";
-export * from "./JjRevertResult.js";
-export * from "./RunJjOptions.js";
-export * from "./RunJjResult.js";
-export * from "./WorkspaceAddOptions.js";
-export * from "./WorkspaceInfo.js";
-export * from "./WorkspaceResult.js";
+export * from "./resolveGitBinary.js";
+export * from "./resolveJjBinary.js";
+export * from "./vcsToolingStatus.js";

package/src/jj.js

@@ -5,13 +5,21 @@
 /** @typedef {import("./WorkspaceAddOptions.js").WorkspaceAddOptions} WorkspaceAddOptions */
 /** @typedef {import("./WorkspaceInfo.js").WorkspaceInfo} WorkspaceInfo */
 /** @typedef {import("./WorkspaceResult.js").WorkspaceResult} WorkspaceResult */
+/**
+ * @typedef {object} WorkspaceSnapshot
+ * @property {string} commitId Working-copy commit id for this snapshot.
+ * @property {string} changeId Stable JJ change id for the working copy.
+ * @property {string} operationId JJ operation id for the snapshot.
+ */
 // @smithers-type-exports-end
 
 import * as Command from "@effect/platform/Command";
 import { Duration, Effect, Fiber, Metric, Stream } from "effect";
 import { vcsDuration } from "@smithers-orchestrator/observability/metrics";
+import { resolveJjBinary } from "./resolveJjBinary.js";
 
 const JJ_POINTER_TIMEOUT_MS = 1_500;
+const WORKSPACE_SNAPSHOT_TIMEOUT_MS = 1_500;
 /**
  * @param {Stream.Stream<Uint8Array, unknown, never>} stream
  * @returns {Effect.Effect<string, unknown, never>}
@@ -29,7 +37,7 @@ function collectUtf8(stream) {
  * @returns {Effect.Effect<RunJjResult, never, import("@effect/platform/CommandExecutor").CommandExecutor>}
  */
 export function runJj(args, opts = {}) {
-    let command = Command.make("jj", ...args);
+    let command = Command.make(resolveJjBinary().path, ...args);
     if (opts.cwd) {
         command = Command.workingDirectory(command, opts.cwd);
     }
@@ -88,6 +96,55 @@ export function getJjPointer(cwd) {
         return out ? out : null;
     }), Effect.annotateLogs({ cwd: cwd ?? "" }), Effect.withLogSpan("vcs:jj-pointer"));
 }
+/**
+ * Wrap a snapshot jj call with a bounded timeout so a slow or hung jj cannot
+ * block the agent. On timeout it returns a sentinel non-zero result, which the
+ * caller treats as a durability gap rather than a value.
+ *
+ * @param {Effect.Effect<RunJjResult, never, import("@effect/platform/CommandExecutor").CommandExecutor>} effect
+ * @param {string} label
+ * @returns {Effect.Effect<RunJjResult, never, import("@effect/platform/CommandExecutor").CommandExecutor>}
+ */
+function withSnapshotTimeout(effect, label) {
+    return effect.pipe(Effect.timeoutTo({
+        duration: Duration.millis(WORKSPACE_SNAPSHOT_TIMEOUT_MS),
+        onSuccess: (res) => res,
+        onTimeout: () => ({
+            code: 124,
+            stdout: "",
+            stderr: `${label} timed out after ${WORKSPACE_SNAPSHOT_TIMEOUT_MS}ms`,
+        }),
+    }));
+}
+/**
+ * Capture the current working-copy state as a restorable handle.
+ *
+ * Step 1 (`jj log -r @`) forces exactly one working-copy snapshot and returns the
+ * resulting `commit_id` and `change_id`. Step 2 reads the latest operation id
+ * WITHOUT taking a second snapshot (`--ignore-working-copy`), so both ids describe
+ * the same snapshot from step 1. Returns null on any failure or timeout (a
+ * durability gap the caller records); it never throws into the agent path.
+ *
+ * @param {string} [cwd]
+ * @returns {Effect.Effect<WorkspaceSnapshot | null, never, import("@effect/platform/CommandExecutor").CommandExecutor>}
+ */
+export function captureWorkspaceSnapshot(cwd) {
+    return Effect.gen(function* () {
+        const logRes = yield* withSnapshotTimeout(runJj(["log", "-r", "@", "--no-graph", "-T", 'commit_id ++ "\\n" ++ change_id'], { cwd }), "jj snapshot log");
+        if (logRes.code !== 0)
+            return null;
+        const [commitId, changeId] = logRes.stdout.split("\n").map((part) => part.trim());
+        if (!commitId)
+            return null;
+        const opRes = yield* withSnapshotTimeout(runJj(["--ignore-working-copy", "operation", "log", "--no-graph", "--limit", "1", "-T", "self.id()"], { cwd }), "jj snapshot op");
+        if (opRes.code !== 0)
+            return null;
+        const operationId = opRes.stdout.trim();
+        if (!operationId)
+            return null;
+        return { commitId, changeId: changeId ?? "", operationId };
+    }).pipe(Effect.annotateLogs({ cwd: cwd ?? "" }), Effect.withLogSpan("vcs:jj-snapshot"));
+}
 /**
  * Restore the working copy to a previously recorded jujutsu `change_id`.
  * Used by the engine to revert attempts within the correct repo/worktree (via `cwd`).

package/src/resolveGitBinary.js

@@ -0,0 +1,19 @@
+import { existsSync } from "node:fs";
+
+/**
+ * Resolve the `git` executable Smithers should spawn.
+ *
+ * Order of preference:
+ *   1. `SMITHERS_GIT_PATH` — an explicit override pointing at a real file.
+ *   2. The bare `"git"`, left for the OS to resolve against `PATH`.
+ *
+ * Git is never bundled (only jj is); this mirrors {@link resolveJjBinary} so the
+ * override and the tooling preflight share one source of truth for where git is.
+ *
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
+ */
+export function resolveGitBinary() {
+	const override = process.env.SMITHERS_GIT_PATH;
+	if (override && existsSync(override)) return { path: override, source: "env" };
+	return { path: "git", source: "path" };
+}

package/src/resolveJjBinary.js

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * `${process.platform}-${process.arch}` → the npm package that vendors a `jj`
+ * binary for that target. Each package carries `os`/`cpu` fields so a package
+ * manager only installs the one matching the host, and exposes the binary at
+ * `bin/jj` (`bin/jj.exe` on Windows).
+ *
+ * Kept in sync with the platform packages under `packages/jj-binaries/` and the
+ * `optionalDependencies` of `@smithers-orchestrator/vcs`.
+ *
+ * @type {Record<string, string>}
+ */
+const BUNDLED_PACKAGES = {
+	"darwin-arm64": "@smithers-orchestrator/jj-darwin-arm64",
+	"darwin-x64": "@smithers-orchestrator/jj-darwin-x64",
+	"linux-arm64": "@smithers-orchestrator/jj-linux-arm64",
+	"linux-x64": "@smithers-orchestrator/jj-linux-x64",
+	"win32-x64": "@smithers-orchestrator/jj-win32-x64",
+};
+
+/**
+ * Locate the bundled `jj` binary for the current host, or null when no platform
+ * package is installed (unsupported target, `--no-optional` install, or not yet
+ * published). Resolution goes through the package's `package.json` so it works
+ * regardless of hoisting layout.
+ *
+ * @returns {string | null}
+ */
+function bundledJjPath() {
+	const pkg = BUNDLED_PACKAGES[`${process.platform}-${process.arch}`];
+	if (!pkg) return null;
+	const binary = process.platform === "win32" ? "jj.exe" : "jj";
+	try {
+		const manifest = require.resolve(`${pkg}/package.json`);
+		const candidate = join(manifest, "..", "bin", binary);
+		return existsSync(candidate) ? candidate : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve the `jj` executable Smithers should spawn.
+ *
+ * Order of preference:
+ *   1. `SMITHERS_JJ_PATH` — an explicit override pointing at a real file.
+ *   2. A binary bundled via `@smithers-orchestrator/jj-<platform>`.
+ *   3. The bare `"jj"`, left for the OS to resolve against `PATH`.
+ *
+ * Always returns a spawnable command. When jj is genuinely absent the bare
+ * `"jj"` simply fails to spawn, which `runJj` already normalizes to exit code
+ * 127, so callers keep their soft-failure behavior.
+ *
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
+ */
+export function resolveJjBinary() {
+	const override = process.env.SMITHERS_JJ_PATH;
+	if (override && existsSync(override)) return { path: override, source: "env" };
+	const bundled = bundledJjPath();
+	if (bundled) return { path: bundled, source: "bundled" };
+	return { path: "jj", source: "path" };
+}

package/src/vcsToolingStatus.js

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import { resolveJjBinary } from "./resolveJjBinary.js";
+import { resolveGitBinary } from "./resolveGitBinary.js";
+
+/**
+ * Whether a usable `jj` and/or `git` exists for the current host. Each field is
+ * the resolved binary when `<bin> --version` runs, or null when it does not.
+ *
+ * @typedef {object} VcsToolingStatus
+ * @property {import("./ResolvedBinary.js").ResolvedBinary | null} jj a usable jj (override, bundled, or PATH), else null
+ * @property {import("./ResolvedBinary.js").ResolvedBinary | null} git a usable git (override or PATH), else null
+ * @property {boolean} ok true when at least one of jj or git is usable
+ */
+
+const VERSION_PROBE_TIMEOUT_MS = 2_000;
+
+/**
+ * Whether `<bin> --version` exits 0. Best-effort: a missing binary, a non-zero
+ * exit, or a spawn error all read as "not usable".
+ *
+ * @param {import("./ResolvedBinary.js").ResolvedBinary} bin
+ * @returns {boolean}
+ */
+function runsVersion(bin) {
+	try {
+		const res = spawnSync(bin.path, ["--version"], {
+			stdio: "ignore",
+			timeout: VERSION_PROBE_TIMEOUT_MS,
+		});
+		return res.status === 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Probe whether a usable `jj` and/or `git` exists for the current host, using
+ * the override → bundled → PATH resolution for jj and override → PATH for git.
+ *
+ * Synchronous and best-effort: used by `smithers doctor` and run preflights to
+ * tell the user — before a run fails deep in worktree creation — that no VCS
+ * tooling is installed, and which knob (bundled package, PATH install, or
+ * `SMITHERS_JJ_PATH`) would fix it.
+ *
+ * @returns {VcsToolingStatus}
+ */
+export function vcsToolingStatus() {
+	const jjBin = resolveJjBinary();
+	const gitBin = resolveGitBinary();
+	const jj = runsVersion(jjBin) ? jjBin : null;
+	const git = runsVersion(gitBin) ? gitBin : null;
+	return { jj, git, ok: Boolean(jj || git) };
+}