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,
} from "@smthrs/vcs";

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

`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

​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

`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