@oh-my-pi/pi-natives 18.0.8 → 18.0.10

package/native/index.d.ts

@@ -331,6 +331,203 @@ export declare class TtyWriter {
   stop(flushTimeoutMs: number): void
 }
 
+/** In-process Git repository handle. */
+export declare class VcsGitRepo {
+  /** Repository metadata. */
+  info(): VcsGitRepoInfo
+  /** Primary checkout root. */
+  primaryRoot(): string
+  /** Linked-worktree metadata. */
+  linkedWorktree(): VcsLinkedWorktree | null
+  /** Resolve HEAD synchronously. */
+  headSync(): VcsHeadState
+  /** Worktree-relative prefix of a directory. */
+  prefixOf(dir: string): string | null
+  /** Resolve HEAD. */
+  head(signal?: unknown | undefined | null): Promise<VcsHeadState>
+  /** Resolve HEAD SHA. */
+  headSha(signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Current branch. */
+  currentBranch(signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Default remote branch. */
+  defaultBranch(signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Resolve a revision. */
+  resolveRef(name: string, signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Test revision existence. */
+  refExists(name: string, signal?: unknown | undefined | null): Promise<boolean>
+  /** Tags pointing at a revision. */
+  tagsAt(rev: string, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** List branches. */
+  listBranches(all: boolean, signal?: unknown | undefined | null): Promise<Array<string>>
+  /**
+   * Whether default porcelain status reports a staged, unstaged, or untracked
+   * change.
+   */
+  isDirty(signal?: unknown | undefined | null): Promise<boolean>
+  /** Porcelain status. */
+  statusPorcelain(options: VcsStatusOptions, signal?: unknown | undefined | null): Promise<string>
+  /** Status counts. */
+  statusSummary(signal?: unknown | undefined | null): Promise<VcsStatusSummary>
+  /** Read config. */
+  configGet(key: string, signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Set config. */
+  configSet(key: string, value: string, signal?: unknown | undefined | null): Promise<undefined>
+  /** List remotes. */
+  remoteList(signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Remote URL. */
+  remoteUrl(name: string, signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Add remote. */
+  remoteAdd(name: string, url: string, signal?: unknown | undefined | null): Promise<undefined>
+  /** List worktrees. */
+  worktrees(signal?: unknown | undefined | null): Promise<Array<VcsWorktreeEntry>>
+  /** Add worktree. */
+  worktreeAdd(path: string, refName: string, detach: boolean, signal?: unknown | undefined | null): Promise<undefined>
+  /** Remove worktree. */
+  worktreeRemove(path: string, force: boolean, signal?: unknown | undefined | null): Promise<boolean>
+  /** Prune worktrees. */
+  worktreePrune(signal?: unknown | undefined | null): Promise<undefined>
+  /** Recent subjects. */
+  logSubjects(count: number, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Recent one-line commits. */
+  logOnelines(count: number, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Commits in a range. */
+  revListRange(base: string, head: string, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Best common ancestor of two revisions. */
+  mergeBase(a: string, b: string, signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Commits touching a file. */
+  revListTouching(rev: string, file: string, limit: number, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Commit details. */
+  commitDetails(rev: string, signal?: unknown | undefined | null): Promise<VcsCommitDetails>
+  /** List index or untracked paths. */
+  lsFiles(others: boolean, excludeStandard: boolean, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** List tree paths. */
+  lsTree(rev: string, paths: Array<string>, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** List submodule paths. */
+  submodulePaths(signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Read blob bytes. */
+  showBlob(spec: string, maxBytes?: number | undefined | null, signal?: unknown | undefined | null): Promise<VcsShowResult>
+  /** Read commit and patch bytes. */
+  showCommit(rev: string, maxBytes?: number | undefined | null, signal?: unknown | undefined | null): Promise<VcsShowResult>
+  /** Local LFS media directory. */
+  lfsMediaDir(signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Render a patch. */
+  diffText(options: VcsDiffOptions, signal?: unknown | undefined | null): Promise<string>
+  /** Render a no-index patch between two filesystem paths. */
+  diffNoIndex(left: string, right: string, binary: boolean, signal?: unknown | undefined | null): Promise<string>
+  /** Changed paths. */
+  changedFiles(options: VcsDiffOptions, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Per-file line counts. */
+  numstat(options: VcsDiffOptions, signal?: unknown | undefined | null): Promise<Array<VcsNumstatEntry>>
+  /** Test for a diff. */
+  hasDiff(options: VcsDiffOptions, signal?: unknown | undefined | null): Promise<boolean>
+  /** Diff two trees. */
+  diffTree(base: string, head: string, binary: boolean, signal?: unknown | undefined | null): Promise<string>
+  /** Stage paths. */
+  stageFiles(files: Array<string>, signal?: unknown | undefined | null): Promise<undefined>
+  /** Unstage paths. */
+  unstage(files: Array<string>, signal?: unknown | undefined | null): Promise<undefined>
+  /** Stage selected hunks. */
+  stageHunks(selections: Array<VcsHunkSelection>, rawDiff?: string | undefined | null, signal?: unknown | undefined | null): Promise<undefined>
+  /** Create commit. */
+  commitCreate(message: string, options: VcsCommitOptions, signal?: unknown | undefined | null): Promise<string>
+  /** Checkout revision. */
+  checkout(rev: string, signal?: unknown | undefined | null): Promise<undefined>
+  /** Create branch. */
+  createBranch(name: string, start: string, force: boolean, signal?: unknown | undefined | null): Promise<undefined>
+  /** Delete branch. */
+  deleteBranch(name: string, force: boolean, signal?: unknown | undefined | null): Promise<boolean>
+  /** Create and checkout branch. */
+  checkoutNewBranch(name: string, signal?: unknown | undefined | null): Promise<undefined>
+  /** Restore paths. */
+  restore(options: VcsRestoreOptions, signal?: unknown | undefined | null): Promise<undefined>
+  /** Reset repository state. */
+  reset(mode: string, target?: string | undefined | null, signal?: unknown | undefined | null): Promise<undefined>
+  /** Clean untracked paths. */
+  clean(options: VcsCleanOptions, signal?: unknown | undefined | null): Promise<undefined>
+  /** Read tree into index. */
+  readTree(treeish: string, indexPath?: string | undefined | null, signal?: unknown | undefined | null): Promise<undefined>
+  /** Write index tree. */
+  writeTree(indexPath?: string | undefined | null, signal?: unknown | undefined | null): Promise<string>
+  /** Apply patch. */
+  applyPatch(patch: string, options: VcsApplyOptions, signal?: unknown | undefined | null): Promise<undefined>
+  /** Check patch applicability. */
+  canApplyPatch(patch: string, options: VcsApplyOptions, signal?: unknown | undefined | null): Promise<boolean>
+  /** Cherry-pick commit. */
+  cherryPick(rev: string, signal?: unknown | undefined | null): Promise<undefined>
+  /** Abort cherry-pick. */
+  cherryPickAbort(signal?: unknown | undefined | null): Promise<undefined>
+  /** Skip cherry-pick. */
+  cherryPickSkip(signal?: unknown | undefined | null): Promise<undefined>
+  /** Push stash. */
+  stashPush(message?: string | undefined | null, signal?: unknown | undefined | null): Promise<boolean>
+  /** Pop stash if cleanly applicable. */
+  stashTryPop(reinstateIndex: boolean, signal?: unknown | undefined | null): Promise<boolean>
+  /** Push via Git CLI. */
+  push(options: VcsPushOptions, signal?: unknown | undefined | null): Promise<void>
+  /** Fetch a refspec via Git CLI. */
+  fetch(remote: string, source: string, target: string, timeoutMs?: number | undefined | null, signal?: unknown | undefined | null): Promise<void>
+}
+
+/** In-process Jujutsu workspace handle. */
+export declare class VcsJjWorkspace {
+  /** Workspace root. */
+  root(): string
+  /** Shared store directory. */
+  storeDir(): string
+  /** Working-copy label. */
+  workingCopyLabel(signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Status counts. */
+  statusSummary(signal?: unknown | undefined | null): Promise<VcsStatusSummary>
+  /** Render working-copy patch. */
+  diffText(files: Array<string>, snapshot: boolean, signal?: unknown | undefined | null): Promise<string>
+  /** List changed paths. */
+  changedFiles(files: Array<string>, snapshot: boolean, signal?: unknown | undefined | null): Promise<Array<string>>
+}
+
+/** Backend-agnostic repository handle for portable VCS reads. */
+export declare class VcsRepo {
+  /** Backend kind (`"git"` or `"jj"`). */
+  kind(): string
+  /** Checkout or workspace root. */
+  root(): string
+  /** Primary checkout or default workspace root. */
+  primaryRoot(): string
+  /** Worktree-relative prefix of a directory. */
+  prefixOf(dir: string): string | null
+  /** Filesystem target to watch for repository-head changes. */
+  watchTarget(): string
+  /** Whether this backend implements a portable feature. */
+  supports(feature: string): boolean
+  /** Git-specific handle when this repository is backed by Git. */
+  asGit(): VcsGitRepo | null
+  /** Jujutsu-specific handle when this repository is backed by Jujutsu. */
+  asJj(): VcsJjWorkspace | null
+  /** Human label for the working copy. */
+  label(signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Working-copy commit id. */
+  headId(signal?: unknown | undefined | null): Promise<string | undefined | null>
+  /** Status counts. */
+  statusSummary(signal?: unknown | undefined | null): Promise<VcsStatusSummary>
+  /** Porcelain status. */
+  statusPorcelain(options: VcsStatusOptions, signal?: unknown | undefined | null): Promise<string>
+  /** Render a patch. */
+  diffText(options: VcsDiffOptions, signal?: unknown | undefined | null): Promise<string>
+  /** Changed paths. */
+  changedFiles(options: VcsDiffOptions, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Per-file line counts. */
+  numstat(options: VcsDiffOptions, signal?: unknown | undefined | null): Promise<Array<VcsNumstatEntry>>
+  /** Every working-copy change since the last commit. */
+  uncommittedDiff(files: Array<string>, signal?: unknown | undefined | null): Promise<string>
+  /** Recent subjects. */
+  logSubjects(count: number, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Recent one-line commits. */
+  logOnelines(count: number, signal?: unknown | undefined | null): Promise<Array<string>>
+  /** Commit details. */
+  commitDetails(rev: string, signal?: unknown | undefined | null): Promise<VcsCommitDetails>
+  /** List tracked or untracked paths. */
+  lsFiles(others: boolean, excludeStandard: boolean, signal?: unknown | undefined | null): Promise<Array<string>>
+}
+
 /**
  * Install the bounded Tokio runtime napi-rs adopts for async exports and the
  * bounded Rayon global pool used by native parallel iterators.
@@ -376,7 +573,7 @@ export declare function __ompInstallTokioRuntime(): void
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV18_0_8(): void
+export declare function __piNativesV18_0_10(): void
 
 /**
  * Apply ast-grep rewrite rules to matching files; honors `dryRun` and returns
@@ -1009,6 +1206,22 @@ export declare enum Encoding {
   Glm5 = 'Glm5'
 }
 
+/**
+ * Replace the current process image via `execvp(3)`.
+ *
+ * On success this never returns: the kernel tears down every other thread and
+ * the new program takes over this PID, controlling terminal, and inherited
+ * (non-`CLOEXEC`) file descriptors. Callers must flush logs and restore the
+ * terminal first — no JS or native cleanup runs after a successful call.
+ *
+ * # Errors
+ * Returns an error, leaving the process untouched, when `argv` is empty, an
+ * argument contains an interior NUL byte, or the exec itself fails (e.g.
+ * executable not found). Windows has no exec-replace semantics, so this
+ * always errors there; callers fall back to spawn-and-wait.
+ */
+export declare function execReplace(argv: Array<string>): void
+
 /**
  * Execute a brush shell command.
  *
@@ -2213,6 +2426,177 @@ export declare function supportsLanguage(lang: string): boolean
  */
 export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind: Ellipsis | undefined | null, pad: boolean | undefined | null, tabWidth: number): string
 
+/** Patch application options. */
+export interface VcsApplyOptions {
+  cached?: boolean
+  indexPath?: string
+  reverse?: boolean
+  threeWay?: boolean
+}
+
+/** Clean options. */
+export interface VcsCleanOptions {
+  ignoredOnly?: boolean
+  includeIgnored?: boolean
+  paths?: Array<string>
+}
+
+/** Clone options. */
+export interface VcsCloneOptions {
+  refName?: string
+  sha?: string
+  timeoutMs?: number
+}
+
+/** Commit author identity. */
+export interface VcsCommitAuthor {
+  name: string
+  email: string
+  date?: string
+}
+
+/** Commit metadata. */
+export interface VcsCommitDetails {
+  sha: string
+  parents: Array<string>
+  author: VcsCommitAuthor
+  message: string
+}
+
+/** Commit creation options. */
+export interface VcsCommitOptions {
+  author?: VcsCommitAuthor
+  allowEmpty?: boolean
+  amend?: boolean
+  files?: Array<string>
+}
+
+/** Detach copied Git metadata. */
+export declare function vcsDetachGitDir(worktreeRoot: string, sourceCommonDir: string, signal?: unknown | undefined | null): Promise<string>
+
+/** Diff generation options. */
+export interface VcsDiffOptions {
+  cached?: boolean
+  base?: string
+  head?: string
+  files?: Array<string>
+  context?: number
+  binary?: boolean
+}
+
+/** Discover the repository owning a directory. */
+export declare function vcsDiscover(dir: string): VcsRepo | null
+
+/** Clone a Git repository. */
+export declare function vcsGitClone(url: string, target: string, options: VcsCloneOptions, signal?: unknown | undefined | null): Promise<void>
+
+/** Discover the Git checkout containing a directory. */
+export declare function vcsGitDiscover(dir: string): VcsGitRepo | null
+
+/** Discover Git metadata without opening the repository. */
+export declare function vcsGitRepoInfo(dir: string): VcsGitRepoInfo | null
+
+/** Discovered Git repository paths. */
+export interface VcsGitRepoInfo {
+  repoRoot: string
+  gitEntryPath: string
+  gitDir: string
+  commonDir: string
+  headPath: string
+  isReftable: boolean
+}
+
+/** Resolved HEAD state. */
+export interface VcsHeadState {
+  kind: string
+  refName?: string
+  branch?: string
+  commit?: string
+}
+
+/** Selected hunks or line range for a path. */
+export interface VcsHunkSelection {
+  path: string
+  kind: string
+  indices?: Array<number>
+  start?: number
+  end?: number
+}
+
+/** Invalid hunk selection. */
+export interface VcsHunkSelectionError {
+  path: string
+  message: string
+}
+
+/** Test whether a directory is a pure jj workspace. */
+export declare function vcsIsPureJj(dir: string): boolean
+
+/** Discover a Jujutsu workspace. */
+export declare function vcsJjDiscover(dir: string): VcsJjWorkspace | null
+
+/** Join patch fragments. */
+export declare function vcsJoinPatches(parts: Array<string>): string
+
+/** Linked worktree metadata. */
+export interface VcsLinkedWorktree {
+  root: string
+  primaryRoot: string
+}
+
+/** Per-file line counts. */
+export interface VcsNumstatEntry {
+  path: string
+  added?: number
+  removed?: number
+}
+
+/** Push options. */
+export interface VcsPushOptions {
+  remote?: string
+  refspec?: string
+  forceWithLease?: boolean
+}
+
+/** Restore options. */
+export interface VcsRestoreOptions {
+  source?: string
+  staged?: boolean
+  worktree?: boolean
+  files?: Array<string>
+}
+
+/** Bounded object contents. */
+export interface VcsShowResult {
+  data: Buffer
+  truncated: boolean
+}
+
+/** Status query options. */
+export interface VcsStatusOptions {
+  untracked?: string
+  pathspecs?: Array<string>
+  nulTerminated?: boolean
+}
+
+/** Git status counts. */
+export interface VcsStatusSummary {
+  staged: number
+  unstaged: number
+  untracked: number
+}
+
+/** Validate hunk selections. */
+export declare function vcsValidateHunkSelections(rawDiff: string, selections: Array<VcsHunkSelection>): Array<VcsHunkSelectionError>
+
+/** One worktree listing row. */
+export interface VcsWorktreeEntry {
+  path: string
+  head?: string
+  branch?: string
+  detached: boolean
+}
+
 /**
  * Score every row of a normalized `f32` matrix against `query` and return
  * the top `limit` rows.

package/native/index.js

@@ -30,10 +30,13 @@ export const Process = nativeBindings.Process;
 export const PtySession = nativeBindings.PtySession;
 export const Shell = nativeBindings.Shell;
 export const TtyWriter = nativeBindings.TtyWriter;
+export const VcsGitRepo = nativeBindings.VcsGitRepo;
+export const VcsJjWorkspace = nativeBindings.VcsJjWorkspace;
+export const VcsRepo = nativeBindings.VcsRepo;
 
 // functions
 export const __ompInstallTokioRuntime = nativeBindings.__ompInstallTokioRuntime;
-export const __piNativesV18_0_8 = nativeBindings.__piNativesV18_0_8;
+export const __piNativesV18_0_10 = nativeBindings.__piNativesV18_0_10;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;
 export const astMatch = nativeBindings.astMatch;
@@ -48,6 +51,7 @@ export const diffLines = nativeBindings.diffLines;
 export const diffWords = nativeBindings.diffWords;
 export const enclosingBlockBoundaries = nativeBindings.enclosingBlockBoundaries;
 export const encodeSixel = nativeBindings.encodeSixel;
+export const execReplace = nativeBindings.execReplace;
 export const executeShell = nativeBindings.executeShell;
 export const extractSegments = nativeBindings.extractSegments;
 export const fuzzyFind = nativeBindings.fuzzyFind;
@@ -91,6 +95,15 @@ export const structuredPatchHunks = nativeBindings.structuredPatchHunks;
 export const summarizeCode = nativeBindings.summarizeCode;
 export const supportsLanguage = nativeBindings.supportsLanguage;
 export const truncateToWidth = nativeBindings.truncateToWidth;
+export const vcsDetachGitDir = nativeBindings.vcsDetachGitDir;
+export const vcsDiscover = nativeBindings.vcsDiscover;
+export const vcsGitClone = nativeBindings.vcsGitClone;
+export const vcsGitDiscover = nativeBindings.vcsGitDiscover;
+export const vcsGitRepoInfo = nativeBindings.vcsGitRepoInfo;
+export const vcsIsPureJj = nativeBindings.vcsIsPureJj;
+export const vcsJjDiscover = nativeBindings.vcsJjDiscover;
+export const vcsJoinPatches = nativeBindings.vcsJoinPatches;
+export const vcsValidateHunkSelections = nativeBindings.vcsValidateHunkSelections;
 export const vectorIndexTopK = nativeBindings.vectorIndexTopK;
 export const visibleWidth = nativeBindings.visibleWidth;
 export const warmHighlighter = nativeBindings.warmHighlighter;

package/native/vcs.d.ts

@@ -0,0 +1,94 @@
+import type {
+	VcsCloneOptions,
+	VcsGitRepo,
+	VcsGitRepoInfo,
+	VcsHunkSelection,
+	VcsHunkSelectionError,
+	VcsJjWorkspace,
+	VcsRepo,
+} from "./index.js";
+/** Portable capabilities that differ between Git and Jujutsu. */
+export type VcsFeature = "stagedDiff" | "revDiff";
+
+/**
+ * A native VCS failure: a real `Error` constructed by the Rust layer on the
+ * JS thread, carrying a machine-readable `code` and the CLI result fields.
+ * Non-CLI failures synthesize `exitCode: 1` and mirror `message` into
+ * `stderr`. Identify with {@link isVcsError} — `instanceof` cannot work for
+ * foreign-constructed errors.
+ */
+export interface VcsError extends Error {
+	name: "VcsError";
+	code:
+		| "NotARepository"
+		| "RefNotFound"
+		| "ObjectNotFound"
+		| "EmptyCherryPick"
+		| "Conflict"
+		| "PatchFailed"
+		| "Cli"
+		| "CliTimeout"
+		| "Io"
+		| "Backend"
+		| "Canceled"
+		| "Unsupported";
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+}
+
+/** True when `error` is a native VCS failure. */
+export declare function isVcsError(error: unknown): error is VcsError;
+
+/** True when a cherry-pick failed because the commit is already applied. */
+export declare function isEmptyCherryPick(error: unknown): error is VcsError & { code: "EmptyCherryPick" };
+
+/** Discover the git repository containing `dir`; `null` outside any checkout. */
+export declare function git(dir: string): VcsGitRepo | null;
+/** Discover the repository owning `dir`; `null` outside any repository. */
+export declare function repo(dir: string): VcsRepo | null;
+
+/** Like {@link repo}, asserting any requested backend capabilities. */
+export declare function require(dir: string, ...features: VcsFeature[]): VcsRepo;
+
+/** Like {@link git}, but throws a `NotARepository` {@link VcsError}. */
+export declare function requireGit(dir: string): VcsGitRepo;
+
+/** Repository metadata only (cheap fs walk) — for synchronous render paths. */
+export declare function gitInfo(dir: string): VcsGitRepoInfo | null;
+
+/** Discover the Jujutsu workspace containing `dir`; `null` when absent. */
+export declare function jj(dir: string): VcsJjWorkspace | null;
+
+/** Whether jj is the nearest VCS ancestor, making git automation unsafe. */
+export declare function isPureJj(dir: string): boolean;
+
+/** Clone a repository (git CLI under the hood for credential parity). */
+export declare function clone(
+	url: string,
+	target: string,
+	options?: VcsCloneOptions,
+	signal?: AbortSignal,
+): Promise<void>;
+
+/** Sever a copied working tree from shared git metadata. */
+export declare function detachGitDir(
+	worktreeRoot: string,
+	sourceCommonDir: string,
+	signal?: AbortSignal,
+): Promise<"no-git" | "independent" | "detached">;
+
+/** Join patch fragments, preserving each part's trailing newline. */
+export declare function joinPatches(parts: string[]): string;
+
+/** Validate hunk selections against a raw diff. */
+export declare function validateHunkSelections(
+	rawDiff: string,
+	selections: VcsHunkSelection[],
+): VcsHunkSelectionError[];
+
+/** Stat-poll interval for {@link watch}. */
+export declare const HEAD_WATCH_INTERVAL_MS: number;
+
+/** Watch a repository for head changes; returns a disposer. */
+export declare function watch(repo: VcsRepo, onChange: () => void, intervalMs?: number): () => void;

package/native/vcs.js

@@ -0,0 +1,119 @@
+import * as fs from "node:fs";
+import { loadNative } from "./loader-state.js";
+
+let native;
+function api() {
+	native ??= loadNative();
+	return native;
+}
+function vcsError(code, message) {
+	const error = new Error(message);
+	error.name = "VcsError";
+	error.code = code;
+	error.exitCode = 1;
+	error.stdout = "";
+	error.stderr = message;
+	return error;
+}
+
+/**
+ * True when `error` is a native VCS failure. The native layer constructs these
+ * on the JS thread as real `Error` objects with `name: "VcsError"`, a
+ * machine-readable `code`, and `exitCode`/`stdout`/`stderr` properties — an
+ * `instanceof` check is impossible for foreign-constructed errors, so identity
+ * rides on `name`.
+ */
+export function isVcsError(error) {
+	return error instanceof Error && error.name === "VcsError";
+}
+
+/** True when a cherry-pick failed because the commit is already applied. */
+export function isEmptyCherryPick(error) {
+	return isVcsError(error) && error.code === "EmptyCherryPick";
+}
+
+/** Discover the git repository containing `dir`; `null` outside any checkout. */
+export function git(dir) {
+	return api().vcsGitDiscover(dir);
+}
+/** Discover the repository owning `dir`; `null` outside any repository. */
+export function repo(dir) {
+	return api().vcsDiscover(dir);
+}
+
+/** Like {@link repo}, asserting any requested backend capabilities. */
+export function require(dir, ...features) {
+	const discovered = repo(dir);
+	if (!discovered) throw vcsError("NotARepository", `not a repository: ${dir}`);
+	for (const feature of features) {
+		if (!discovered.supports(feature)) {
+			throw vcsError(
+				"Unsupported",
+				`\`${feature}\` is not supported on a ${discovered.kind()} repository`,
+			);
+		}
+	}
+	return discovered;
+}
+
+/** Like {@link git}, but throws a `NotARepository` VcsError. */
+export function requireGit(dir) {
+	const repo = git(dir);
+	if (!repo) {
+		throw vcsError("NotARepository", `not a repository: ${dir}`);
+	}
+	return repo;
+}
+
+/** Repository metadata only (cheap fs walk) — for synchronous render paths. */
+export function gitInfo(dir) {
+	return api().vcsGitRepoInfo(dir);
+}
+
+/** Discover the Jujutsu workspace containing `dir`; `null` when absent. */
+export function jj(dir) {
+	return api().vcsJjDiscover(dir);
+}
+
+/** Whether jj is the nearest VCS ancestor, making git automation unsafe. */
+export function isPureJj(dir) {
+	return api().vcsIsPureJj(dir);
+}
+
+/** Clone a repository (git CLI under the hood for credential parity). */
+export function clone(url, target, options = {}, signal) {
+	return api().vcsGitClone(url, target, options, signal);
+}
+
+/** Sever a copied working tree from shared git metadata. */
+export function detachGitDir(worktreeRoot, sourceCommonDir, signal) {
+	return api().vcsDetachGitDir(worktreeRoot, sourceCommonDir, signal);
+}
+
+/** Join patch fragments, preserving each part's trailing newline. */
+export function joinPatches(parts) {
+	return api().vcsJoinPatches(parts);
+}
+
+/** Validate hunk selections against a raw diff. */
+export function validateHunkSelections(rawDiff, selections) {
+	return api().vcsValidateHunkSelections(rawDiff, selections);
+}
+
+/** Stat-poll interval for {@link watch}. */
+export const HEAD_WATCH_INTERVAL_MS = 1000;
+
+/**
+ * Watch a repository for head changes; returns a disposer.
+ *
+ * Stat-polls via `fs.watchFile` instead of `fs.watch`: backends may atomically
+ * replace the watched entry, permanently silencing inotify-backed watchers.
+ */
+export function watch(repo, onChange, intervalMs = HEAD_WATCH_INTERVAL_MS) {
+	const target = repo.watchTarget();
+	const listener = (curr, prev) => {
+		if (curr.mtimeMs !== prev.mtimeMs || curr.ino !== prev.ino || curr.size !== prev.size) onChange();
+	};
+	fs.watchFile(target, { interval: intervalMs }, listener).unref();
+	return () => fs.unwatchFile(target, listener);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-natives",
-	"version": "18.0.8",
+	"version": "18.0.10",
 	"description": "Native Rust bindings for PDF conversion, audio, WebRTC, grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://omp.sh",
@@ -72,6 +72,8 @@
 		"native/desktop-adapter.d.ts",
 		"native/loader-state.js",
 		"native/loader-state.d.ts",
+		"native/vcs.js",
+		"native/vcs.d.ts",
 		"native/embedded-addon.js",
 		"README.md",
 		"LICENSE",
@@ -89,13 +91,17 @@
 		"./clipboard": {
 			"types": "./native/clipboard.d.ts",
 			"import": "./native/clipboard.js"
+		},
+		"./vcs": {
+			"types": "./native/vcs.d.ts",
+			"import": "./native/vcs.js"
 		}
 	},
 	"optionalDependencies": {
-		"@oh-my-pi/pi-natives-linux-x64": "18.0.8",
-		"@oh-my-pi/pi-natives-linux-arm64": "18.0.8",
-		"@oh-my-pi/pi-natives-darwin-x64": "18.0.8",
-		"@oh-my-pi/pi-natives-darwin-arm64": "18.0.8",
-		"@oh-my-pi/pi-natives-win32-x64": "18.0.8"
+		"@oh-my-pi/pi-natives-linux-x64": "18.0.10",
+		"@oh-my-pi/pi-natives-linux-arm64": "18.0.10",
+		"@oh-my-pi/pi-natives-darwin-x64": "18.0.10",
+		"@oh-my-pi/pi-natives-darwin-arm64": "18.0.10",
+		"@oh-my-pi/pi-natives-win32-x64": "18.0.10"
 	}
 }