VCS Helper Reference

Smithers exports a small VCS helper surface for applications that inspect or manage Jujutsu state directly:

every helper accepts an optional cwd to target a specific repository
spawn failures are normalized instead of thrown, safe to call even without jj installed
workspace helpers try a few command shapes to tolerate JJ version drift
JJ command helpers return Effect values; direct callers must supply an Effect ChildProcessSpawner service

Import

The root smthrs facade exports the main JJ helpers:

import {
  runJj,
  getJjPointer,
  revertToJjPointer,
  isJjRepo,
  workspaceAdd,
  workspaceList,
  workspaceClose,
} from "smthrs";

The lower-level VCS package also exports repository discovery, binary resolution, tooling preflight, and snapshot capture helpers:

import {
  captureWorkspaceSnapshot,
  findVcsRoot,
  resolveGitBinary,
  resolveJjBinary,
  vcsToolingStatus,
  createIsolatedClone,
  listGitRefs,
  gitDirtyPaths,
} from "@smthrs/vcs";

createIsolatedClone, listGitRefs, and gitDirtyPaths are also exported by the root smthrs facade.

Isolated clone and bundle handoff

createIsolatedClone({ repo, at, destination? }) creates a standalone, detached clone at exactly at^{commit}. It removes remotes and refs, rejects Git alternates, writes a nonce ownership marker, and will only clean a clone whose marker still matches.

const clone = await createIsolatedClone({ repo: sharedRepo, at: expectedHead });
try {
  await clone.run("pnpm", ["test"]);
  const handoff = await clone.emitBundle({ outputDir: artifacts, name: "wave-2" });
} finally {
  await clone.cleanup();
}

The hot-tree contract is deliberately narrow: expectedHead^{commit} must be readable while the clone is created. The source working tree, index, refs, JJ bookmarks, object inventory, and later HEAD movement may change; they are not quiescence gates. The clone is the isolation boundary. The emitted patch, bundle, and JSON manifest are adoption evidence, and emitBundle() verifies them in a fresh repository before returning. Land a handoff into a shared tree only in a short serialized adoption step. clone.run() always uses the clone root as cwd. It inherits only PATH, HOME, temp-directory, user/shell, and locale variables, plus explicit env overrides. Ambient GIT_*, SMITHERS_HOME, and other SMITHERS_* variables are absent unless explicitly supplied.

Large Git inventories

listGitRefs(repo) and gitDirtyPaths(repo) use streamed child-process output, so they do not have Node’s synchronous 1 MB maxBuffer ceiling. This matters for JJ-colocated repositories, where tens of thousands of refs can produce multi-megabyte output. Do not replace these helpers with execFileSync("git", ["for-each-ref"]) using its default buffer.

const refs = await listGitRefs(repo);
const dirtyPaths = await gitDirtyPaths(repo);

Direct JJ helper calls need a platform layer:

import type * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
import * as BunServices from "@effect/platform-bun/BunServices";
import { Effect } from "effect";

type VcsEffect<A> = Effect.Effect<A, never, ChildProcessSpawner.ChildProcessSpawner>;

const runVcs = <A,>(effect: VcsEffect<A>) =>
  Effect.runPromise(effect.pipe(Effect.provide(BunServices.layer)));

Install @effect/platform-bun for the Bun snippet, or provide the equivalent ChildProcessSpawner service for another runtime.

`runJj(args, opts?)`

Run an arbitrary jj command and capture its output.

const result = await runVcs(runJj(["status"], { cwd: "/path/to/repo" }));

type RunJjOptions = {
  cwd?: string;
};

type RunJjResult = {
  code: number;
  stdout: string;
  stderr: string;
};

function runJj(args: string[], opts?: RunJjOptions): VcsEffect<RunJjResult>;

Notes:

normalizes process failures instead of throwing, e.g. { code: 127, stdout: "", stderr: "..." } when jj cannot be started
a raw escape hatch beneath the higher-level helpers below

`getJjPointer(cwd?)`

Returns the current workspace commit_id for @ (null if JJ is unavailable or the directory isn’t a JJ repo). The immutable commit ID pins the exact working-copy snapshot even as later writes amend the same JJ change.

const pointer = await runVcs(getJjPointer("/path/to/repo"));

function getJjPointer(cwd?: string): VcsEffect<string | null>;

Smithers uses the same pointer model for revert support and cache invalidation.

`revertToJjPointer(pointer, cwd?)`

Restore the working copy from a recorded JJ pointer (a commit_id string, as returned by getJjPointer).

const result = await runVcs(
  revertToJjPointer("0123456789abcdef0123456789abcdef01234567", "/path/to/repo"),
);

type JjRevertResult = {
  success: boolean;
  error?: string;
};

function revertToJjPointer(pointer: string, cwd?: string): VcsEffect<JjRevertResult>;

Wraps jj restore --from <pointer>.

`isJjRepo(cwd?)`

Detect whether a directory is a readable JJ repository.

const enabled = await runVcs(isJjRepo("/path/to/repo"));

function isJjRepo(cwd?: string): VcsEffect<boolean>;

Use this before showing JJ-specific UI or attempting a revert flow.

`workspaceAdd(name, path, opts?)`

Create a JJ workspace with a friendly name at a target filesystem path.

const result = await runVcs(
  workspaceAdd("feature-auth", "/tmp/wt-feature-auth", {
    cwd: "/path/to/repo",
    atRev: "@",
  }),
);

type WorkspaceAddOptions = {
  cwd?: string;
  atRev?: string;
};

type WorkspaceResult = {
  success: boolean;
  error?: string;
};

function workspaceAdd(name: string, path: string, opts?: WorkspaceAddOptions): VcsEffect<WorkspaceResult>;

Behavior notes:

removes any existing workspace with the same name and its target directory if present before retrying, creating the parent directory if needed
tries multiple jj workspace add syntaxes to work across JJ versions

`workspaceList(cwd?)`

List known workspaces for the current JJ repo.

const workspaces = await runVcs(workspaceList("/path/to/repo"));

type WorkspaceInfo = {
  name: string;
  path: string | null;
  selected: boolean;
};

function workspaceList(cwd?: string): VcsEffect<WorkspaceInfo[]>;

Prefers template output when supported, falls back to parsing the human-readable jj workspace list output.

`workspaceClose(name, opts?)`

Forget a JJ workspace by name.

const result = await runVcs(
  workspaceClose("feature-auth", {
    cwd: "/path/to/repo",
  }),
);

function workspaceClose(
  name: string,
  opts?: { cwd?: string },
): VcsEffect<WorkspaceResult>;

Wraps jj workspace forget <name>.

`captureWorkspaceSnapshot(cwd?)`

Capture the current JJ working-copy state as a restorable handle. This helper is exported by @smthrs/vcs, not by the root facade.

const snapshot = await runVcs(captureWorkspaceSnapshot("/path/to/repo"));

type WorkspaceSnapshot = {
  commitId: string;
  changeId: string;
  operationId: string;
};

function captureWorkspaceSnapshot(cwd?: string): VcsEffect<WorkspaceSnapshot | null>;

Returns null on failures and timeouts, including non-JJ directories. Smithers uses commitId and operationId for workspace durability checkpoints.

`findVcsRoot(startDir)`

Walk upward from a directory and return the nearest .jj or .git root. JJ wins when both markers exist in the same directory.

const root = findVcsRoot(process.cwd());

type VcsRoot =
  | { type: "jj"; root: string }
  | { type: "git"; root: string };

function findVcsRoot(startDir: string): VcsRoot | null;

`resolveGitBinary()` and `resolveJjBinary()`

Resolve the executable Smithers will spawn for VCS commands.

const git = resolveGitBinary();
const jj = resolveJjBinary();

type ResolvedBinary = {
  path: string;
  source: "env" | "bundled" | "path";
};

function resolveGitBinary(): ResolvedBinary;
function resolveJjBinary(): ResolvedBinary;

resolveGitBinary() checks SMITHERS_GIT_PATH, then git on PATH. resolveJjBinary() checks SMITHERS_JJ_PATH, then a bundled @smthrs/jj-<platform> package, then jj on PATH.

`vcsToolingStatus()`

Probe whether the resolved VCS binaries are usable on the current host.

const status = vcsToolingStatus();

type VcsToolingStatus = {
  jj: ResolvedBinary | null;
  git: ResolvedBinary | null;
  ok: boolean;
};

function vcsToolingStatus(): VcsToolingStatus;

Synchronous and best-effort: runs version probes with a short timeout and powers the CLI’s VCS preflight checks.

When To Use These Helpers

Use these helpers when your application needs to:

show whether JJ-backed revert is available
record or inspect a pointer outside the Smithers engine
manage JJ workspaces directly from an app or integration layer
check whether JJ or Git tooling is available before starting worktree logic

For workflow-level revert behavior, prefer the runtime and CLI docs:

Overview

Core API

Runtime

Types & errors

Gateway RPC

VCS Helper Reference

Import

Isolated clone and bundle handoff

Large Git inventories

`runJj(args, opts?)`

`getJjPointer(cwd?)`

`revertToJjPointer(pointer, cwd?)`

`isJjRepo(cwd?)`

`workspaceAdd(name, path, opts?)`

`workspaceList(cwd?)`

`workspaceClose(name, opts?)`

`captureWorkspaceSnapshot(cwd?)`

`findVcsRoot(startDir)`

`resolveGitBinary()` and `resolveJjBinary()`

`vcsToolingStatus()`

When To Use These Helpers

​Import

​Isolated clone and bundle handoff

​Large Git inventories

​runJj(args, opts?)

​getJjPointer(cwd?)

​revertToJjPointer(pointer, cwd?)

​isJjRepo(cwd?)

​workspaceAdd(name, path, opts?)

​workspaceList(cwd?)

​workspaceClose(name, opts?)

​captureWorkspaceSnapshot(cwd?)

​findVcsRoot(startDir)

​resolveGitBinary() and resolveJjBinary()

​vcsToolingStatus()

​When To Use These Helpers

Import

Isolated clone and bundle handoff

Large Git inventories

`runJj(args, opts?)`

`getJjPointer(cwd?)`

`revertToJjPointer(pointer, cwd?)`

`isJjRepo(cwd?)`

`workspaceAdd(name, path, opts?)`

`workspaceList(cwd?)`

`workspaceClose(name, opts?)`

`captureWorkspaceSnapshot(cwd?)`

`findVcsRoot(startDir)`

`resolveGitBinary()` and `resolveJjBinary()`

`vcsToolingStatus()`

When To Use These Helpers