@smithers-orchestrator/vcs 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/vcs",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "VCS discovery and jj workspace operations for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,7 @@
   "dependencies": {
     "@effect/platform": "^0.96.0",
     "effect": "^3.21.1",
-    "@smithers-orchestrator/observability": "0.23.0"
+    "@smithers-orchestrator/observability": "0.24.0"
   },
   "devDependencies": {
     "@effect/platform-bun": "^0.89.0",
@@ -30,14 +30,14 @@
     "typescript": "~5.9.3"
   },
   "optionalDependencies": {
-    "@smithers-orchestrator/jj-darwin-arm64": "0.23.0",
-    "@smithers-orchestrator/jj-darwin-x64": "0.23.0",
-    "@smithers-orchestrator/jj-linux-x64": "0.23.0",
-    "@smithers-orchestrator/jj-win32-x64": "0.23.0",
-    "@smithers-orchestrator/jj-linux-arm64": "0.23.0"
+    "@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/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,6 +128,20 @@ 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.
@@ -123,12 +150,11 @@ type WorkspaceResult = WorkspaceResult$1;
  * - `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$3 = {
+type ResolvedBinary = {
     path: string;
     source: "env" | "bundled" | "path";
 };
 
-/** @typedef {import("./ResolvedBinary.js").ResolvedBinary} ResolvedBinary */
 /**
  * Resolve the `git` executable Smithers should spawn.
  *
@@ -139,10 +165,9 @@ type ResolvedBinary$3 = {
  * 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 {ResolvedBinary}
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
  */
-declare function resolveGitBinary(): ResolvedBinary$2;
-type ResolvedBinary$2 = ResolvedBinary$3;
+declare function resolveGitBinary(): ResolvedBinary;
 
 /**
  * Resolve the `jj` executable Smithers should spawn.
@@ -156,10 +181,9 @@ type ResolvedBinary$2 = ResolvedBinary$3;
  * `"jj"` simply fails to spawn, which `runJj` already normalizes to exit code
  * 127, so callers keep their soft-failure behavior.
  *
- * @returns {ResolvedBinary}
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
  */
-declare function resolveJjBinary(): ResolvedBinary$1;
-type ResolvedBinary$1 = ResolvedBinary$3;
+declare function resolveJjBinary(): ResolvedBinary;
 
 /**
  * Probe whether a usable `jj` and/or `git` exists for the current host, using
@@ -173,7 +197,6 @@ type ResolvedBinary$1 = ResolvedBinary$3;
  * @returns {VcsToolingStatus}
  */
 declare function vcsToolingStatus(): VcsToolingStatus;
-type ResolvedBinary = ResolvedBinary$3;
 /**
  * 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.
@@ -193,4 +216,4 @@ type VcsToolingStatus = {
     ok: boolean;
 };
 
-export { type VcsToolingStatus, findVcsRoot, getJjPointer, isJjRepo, resolveGitBinary, resolveJjBinary, revertToJjPointer, runJj, vcsToolingStatus, 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

@@ -2,12 +2,4 @@ export * from "./find-root.js";
 export * from "./jj.js";
 export * from "./resolveGitBinary.js";
 export * from "./resolveJjBinary.js";
-export * from "./ResolvedBinary.js";
 export * from "./vcsToolingStatus.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 "./WorkspaceSnapshot.js";

package/src/jj.js

@@ -5,7 +5,12 @@
 /** @typedef {import("./WorkspaceAddOptions.js").WorkspaceAddOptions} WorkspaceAddOptions */
 /** @typedef {import("./WorkspaceInfo.js").WorkspaceInfo} WorkspaceInfo */
 /** @typedef {import("./WorkspaceResult.js").WorkspaceResult} WorkspaceResult */
-/** @typedef {import("./WorkspaceSnapshot.js").WorkspaceSnapshot} WorkspaceSnapshot */
+/**
+ * @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";

package/src/resolveGitBinary.js

@@ -1,7 +1,5 @@
 import { existsSync } from "node:fs";
 
-/** @typedef {import("./ResolvedBinary.js").ResolvedBinary} ResolvedBinary */
-
 /**
  * Resolve the `git` executable Smithers should spawn.
  *
@@ -12,7 +10,7 @@ import { existsSync } from "node:fs";
  * 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 {ResolvedBinary}
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
  */
 export function resolveGitBinary() {
 	const override = process.env.SMITHERS_GIT_PATH;

package/src/resolveJjBinary.js

@@ -2,8 +2,6 @@ import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
 
-/** @typedef {import("./ResolvedBinary.js").ResolvedBinary} ResolvedBinary */
-
 const require = createRequire(import.meta.url);
 
 /**
@@ -58,7 +56,7 @@ function bundledJjPath() {
  * `"jj"` simply fails to spawn, which `runJj` already normalizes to exit code
  * 127, so callers keep their soft-failure behavior.
  *
- * @returns {ResolvedBinary}
+ * @returns {import("./ResolvedBinary.js").ResolvedBinary}
  */
 export function resolveJjBinary() {
 	const override = process.env.SMITHERS_JJ_PATH;

package/src/vcsToolingStatus.js

@@ -2,15 +2,13 @@ import { spawnSync } from "node:child_process";
 import { resolveJjBinary } from "./resolveJjBinary.js";
 import { resolveGitBinary } from "./resolveGitBinary.js";
 
-/** @typedef {import("./ResolvedBinary.js").ResolvedBinary} ResolvedBinary */
-
 /**
  * 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 {ResolvedBinary | null} jj a usable jj (override, bundled, or PATH), else null
- * @property {ResolvedBinary | null} git a usable git (override or PATH), else null
+ * @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
  */
 
@@ -20,7 +18,7 @@ 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 {ResolvedBinary} bin
+ * @param {import("./ResolvedBinary.js").ResolvedBinary} bin
  * @returns {boolean}
  */
 function runsVersion(bin) {