riftri 0.3.5 → 0.4.1

package/README.md

@@ -67,9 +67,16 @@ The interactive `riftri setup` terminal UI is behind an off-by-default `tui`
 feature; add `--features tui` to build it in (the published binaries do). The
 default build keeps `setup` working through plain text prompts.
 
-The npm launcher is a separate distribution channel. It is not currently
-available because the initial publication is incomplete; use the verified
-standalone installer or GitHub release assets for now.
+Or install through npm, which fetches the binary for your platform:
+
+```sh
+npm install --global riftri
+```
+
+> **Windows on ARM64 is not yet available through npm.** Its platform package
+> is held up in registry review, so npm installs there resolve without a
+> binary. Use the PowerShell installer above until that clears. Every other
+> platform — macOS, Linux, and Windows x64 — installs normally.
 
 ## Quick start
 
@@ -155,9 +162,11 @@ $ sudo riftri overlayfs install-helper
 ```
 
 **Riftri fails closed.** When a checkout cannot be reproduced exactly — custom
-filters, sparse checkout, submodules, external attributes, checkout hooks, or non-canonical
-[Git LFS](docs/git-lfs.md) setups — it stops before changing anything rather
-than silently falling back to a full copy. See
+filters, a repository's own sparse-checkout profile, submodules, external
+attributes, checkout hooks, or non-canonical [Git LFS](docs/git-lfs.md) setups
+— it stops before changing anything rather than silently falling back to a full
+copy. Sparse worktrees are supported when you ask for them explicitly, with
+[`--sparse-dir` cone selection](docs/sparse-checkout.md). See
 [how Riftri stays safe](docs/safety.md).
 
 ## Common commands

package/bin/riftri.js

@@ -50,22 +50,18 @@ if (process.platform !== "win32") {
   }
 }
 
-function releaseSignals() {
-  for (const signal of ignoredSignals) {
-    process.removeListener(signal, ignoreSignal);
-  }
-  for (const signal of forwardedSignals) {
-    process.removeListener(signal, forwardSignal);
-  }
-}
+// The handlers deliberately stay installed until the process exits. Removing
+// the last listener for a signal restores its default disposition, so a SIGINT
+// still in flight — the common case, since the terminal sent it to the whole
+// foreground group — would kill the launcher in the window before
+// `process.exit`, losing the command's real status. `process.exit` does not
+// need them removed.
 
 child.on("error", (error) => {
-  releaseSignals();
   fail(`could not start the native executable at ${binary}: ${error.message}`);
 });
 
 child.on("exit", (code, signal) => {
-  releaseSignals();
   if (signal !== null) {
     const exitCode = signalExitCode(signal);
     if (exitCode === null) {

package/lib/client.d.ts

@@ -0,0 +1,179 @@
+/** Programmatic API for the Riftri CLI. */
+
+export const EXIT_SUCCESS: 0;
+export const EXIT_OPERATIONAL: 1;
+export const EXIT_USAGE: 2;
+export const EXIT_POLICY: 3;
+
+/** One versioned failure receipt, as emitted by `--json-errors`. */
+export interface FailureReceipt {
+  schemaVersion: number;
+  outcome: "failed";
+  operation: string;
+  code: string;
+  category: "policy" | "operational";
+  message: string;
+  phase: string | null;
+  cleanup: string;
+  recovery: "required" | "not-required" | "retry" | "inspect" | "unknown";
+  nextCommand: string | null;
+}
+
+export class RiftriError extends Error {
+  /**
+   * Always a number. A process killed by a signal reports 128 plus the signal
+   * number, the convention native `riftri exec` uses for its own children.
+   */
+  readonly exitCode: number;
+  /** The signal that killed the process, or null if it exited on its own. */
+  readonly signal: NodeJS.Signals | null;
+  /** The process was killed rather than exiting on its own. */
+  readonly wasSignalled: boolean;
+  readonly receipt: FailureReceipt | null;
+  /** Riftri declined before touching anything; falling back is safe. */
+  readonly isPolicyRefusal: boolean;
+  /** The request was malformed; never retry it unchanged. */
+  readonly isUsageError: boolean;
+  /** A live process holds the lock; waiting and retrying is correct. */
+  readonly isBusy: boolean;
+  /** Run `receipt.nextCommand` before continuing. */
+  readonly needsRepair: boolean;
+}
+
+export interface DoctorReport {
+  project_stage: string;
+  operating_system: string;
+  architecture: string;
+  /** Whether a usable copy-on-write backend exists here. */
+  cow_backend_active: boolean;
+  /** Whether this repository has opted in with `enable()`. */
+  repository_enabled: boolean;
+  git_shim_active: boolean;
+  destination_readiness: {
+    destination: string;
+    status: string;
+    backend: string | null;
+    copy_on_write: boolean;
+  };
+  storage_capabilities: unknown[];
+  [key: string]: unknown;
+}
+
+export interface AddReport {
+  schema_version: number;
+  backend: string;
+  destination: string;
+  destination_native_hex: string;
+  commit: string;
+  tree: string;
+  base_path: string;
+  /** False when this add materialized a new immutable base. */
+  reused_base: boolean;
+  journal_path: string;
+  native_path_encoding: string;
+}
+
+export interface ManagedWorktree {
+  path: string;
+  path_native_hex: string;
+  repository: string;
+  head: string;
+  branch: string | null;
+  detached: boolean;
+  backend: string;
+  base_path: string;
+  /** Filesystem-accounted bytes this worktree actually occupies. */
+  allocated_bytes: number;
+  /** Bytes the same content would occupy without sharing. */
+  logical_bytes: number;
+  locked_reason: string | null;
+  prunable_reason: string | null;
+}
+
+export interface WorktreeInventory {
+  schema_version: number;
+  state_directory: string;
+  worktrees: ManagedWorktree[];
+  native_path_encoding: string;
+}
+
+export interface StatusReport {
+  schema_version: number;
+  state_directory: string;
+  bases: unknown[];
+  worktrees: unknown[];
+  operations: unknown[];
+  diagnostic_issues: unknown[];
+  total_allocated_bytes: number;
+  total_logical_bytes: number;
+  [key: string]: unknown;
+}
+
+export interface RepairReport {
+  schema_version: number;
+  scanned: number;
+  active: number;
+  errors: unknown[];
+  [key: string]: unknown;
+}
+
+export interface AddOptions {
+  /** Create and check out a new branch. */
+  branch?: string;
+  /** Create a detached worktree instead of a branch. */
+  detach?: boolean;
+  /** Commit-ish to start from; defaults to HEAD. */
+  revision?: string;
+  /** Cone-mode sparse directories to include. */
+  sparseDir?: string[];
+}
+
+export interface RiftriOptions {
+  /** Working directory for every command. Defaults to `process.cwd()`. */
+  repository?: string;
+  /** Explicit executable; defaults to the installed platform binary. */
+  binary?: string;
+  /** Passed as `--state-dir` where the command supports it. */
+  stateDir?: string;
+}
+
+export class Riftri {
+  constructor(options?: RiftriOptions);
+  repository: string;
+
+  /** Inspect Git and storage. Creates nothing. */
+  doctor(options?: { destination?: string }): Promise<DoctorReport>;
+  backends(path?: string): Promise<unknown>;
+  /**
+   * True when this destination can be optimized.
+   *
+   * Resolves `false` only when Riftri answers the question: no active
+   * copy-on-write backend, a destination Riftri reports as `blocked`, or an
+   * outright refusal. A missing or non-executable binary, an unreadable
+   * repository, or output that is not JSON rejects instead.
+   *
+   * A `needs-activation` destination is optimizable: `worktree.add` works
+   * without `enable()`, which only gates Git interception.
+   */
+  isOptimizable(destination?: string): Promise<boolean>;
+
+  enable(): Promise<null>;
+  disable(): Promise<null>;
+
+  status(): Promise<StatusReport>;
+  repair(): Promise<RepairReport>;
+  gc(options?: { apply?: boolean }): Promise<unknown>;
+
+  /** Escape hatch: run any command and parse its report. */
+  run(args: string[], options?: { json?: boolean; cwd?: string }): Promise<unknown>;
+
+  readonly worktree: {
+    add(destination: string, options?: AddOptions): Promise<AddReport>;
+    list(options?: { allStates?: boolean }): Promise<WorktreeInventory>;
+    /** Refuses a dirty worktree unless `force` is set. */
+    remove(destination: string, options?: { force?: boolean }): Promise<unknown>;
+    move(source: string, destination: string): Promise<unknown>;
+    compact(destination: string): Promise<unknown>;
+    prune(): Promise<unknown>;
+  };
+}

package/lib/client.js

@@ -0,0 +1,289 @@
+"use strict";
+
+// Programmatic API for the Riftri CLI.
+//
+// The binary is the implementation; this is a typed, promise-returning wrapper
+// around it. Every method runs one command, returns its parsed `--json` report,
+// and throws a RiftriError carrying the parsed `--json-errors` receipt on
+// failure. Nothing here reimplements Riftri behaviour.
+
+const { spawn } = require("node:child_process");
+const { resolveBinary } = require("./platform.js");
+const { signalExitCode } = require("./signals.js");
+
+/** Process exit codes. Documented in docs/cli.md. */
+const EXIT_SUCCESS = 0;
+const EXIT_OPERATIONAL = 1;
+const EXIT_USAGE = 2;
+const EXIT_POLICY = 3;
+
+/** Commands that accept `--json`. The rest print human text on success. */
+const REPORTING = new Set([
+  "doctor",
+  "backends",
+  "status",
+  "repair",
+  "gc",
+  "worktree",
+]);
+
+class RiftriError extends Error {
+  constructor(exitCode, receipt, stderr, signal = null) {
+    super(
+      receipt?.message ||
+        stderr.trim() ||
+        (signal ? `riftri terminated by ${signal}` : `riftri exited ${exitCode}`),
+    );
+    this.name = "RiftriError";
+    // Always a number. A signalled process reports 128 + the signal number,
+    // the convention native `riftri exec` already uses for its own children.
+    this.exitCode = exitCode;
+    this.signal = signal;
+    this.receipt = receipt ?? null;
+  }
+
+  /** The process was killed rather than exiting on its own. */
+  get wasSignalled() {
+    return this.signal !== null;
+  }
+
+  /** Riftri declined before touching anything. Falling back is safe. */
+  get isPolicyRefusal() {
+    return this.exitCode === EXIT_POLICY;
+  }
+
+  /** The request itself was malformed. Never retry unchanged. */
+  get isUsageError() {
+    return this.exitCode === EXIT_USAGE;
+  }
+
+  /** A live process holds the lock; unlike a refusal, waiting helps. */
+  get isBusy() {
+    return this.receipt?.code === "worktree-busy";
+  }
+
+  /** Run `nextCommand` (usually `riftri repair`) before continuing. */
+  get needsRepair() {
+    return this.receipt?.recovery === "required";
+  }
+}
+
+/**
+ * Place Riftri's own flags before any `--`. Appending them instead puts them
+ * inside the payload `riftri exec` hands to the child, which then fails on a
+ * flag meant for Riftri.
+ */
+function withRiftriFlags(args, flags) {
+  if (flags.length === 0) return [...args];
+  const boundary = args.indexOf("--");
+  if (boundary === -1) return [...args, ...flags];
+  return [...args.slice(0, boundary), ...flags, ...args.slice(boundary)];
+}
+
+function flagsFor(options) {
+  const flags = [];
+  for (const [key, value] of Object.entries(options)) {
+    if (value === undefined || value === null || value === false) continue;
+    const flag = `--${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+    if (value === true) flags.push(flag);
+    else if (Array.isArray(value)) for (const item of value) flags.push(flag, String(item));
+    else flags.push(flag, String(value));
+  }
+  return flags;
+}
+
+class Riftri {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.repository] working directory for every command
+   * @param {string} [options.binary] explicit riftri executable
+   * @param {string} [options.stateDir] passed as --state-dir where supported
+   */
+  constructor(options = {}) {
+    this.repository = options.repository ?? process.cwd();
+    this.binary = options.binary ?? null;
+    this.stateDir = options.stateDir ?? null;
+    this.worktree = {
+      add: this.#worktreeAdd.bind(this),
+      list: this.#worktreeList.bind(this),
+      remove: this.#worktreeRemove.bind(this),
+      move: this.#worktreeMove.bind(this),
+      compact: this.#worktreeCompact.bind(this),
+      prune: this.#worktreePrune.bind(this),
+    };
+  }
+
+  /** Resolve the executable: explicit, else the installed platform package. */
+  #executable() {
+    if (this.binary) return this.binary;
+    this.binary = resolveBinary();
+    return this.binary;
+  }
+
+  /**
+   * Run one command and resolve with its parsed report, or null when the
+   * command does not support `--json`.
+   */
+  run(args, { json = REPORTING.has(args[0]), cwd = this.repository } = {}) {
+    const flags = json ? ["--json", "--json-errors"] : ["--json-errors"];
+    return new Promise((resolve, reject) => {
+      let child;
+      try {
+        child = spawn(this.#executable(), withRiftriFlags(args, flags), {
+          cwd,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+      } catch (error) {
+        reject(error); // no installed binary for this platform
+        return;
+      }
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (chunk) => (stdout += chunk));
+      child.stderr.on("data", (chunk) => (stderr += chunk));
+      child.on("error", reject);
+      child.on("close", (exitCode, signal) => {
+        // A signalled child reports a null exit code. Translate it rather than
+        // letting `null` reach callers through a field typed as a number.
+        if (signal) {
+          const code = signalExitCode(signal) ?? EXIT_OPERATIONAL;
+          reject(new RiftriError(code, null, stderr, signal));
+          return;
+        }
+        if (exitCode === EXIT_SUCCESS) {
+          if (!json || !stdout.trim()) {
+            resolve(null);
+            return;
+          }
+          try {
+            resolve(JSON.parse(stdout));
+          } catch (error) {
+            // Thrown from a close handler this would be uncatchable and would
+            // take the host process down, so it has to reject instead.
+            reject(
+              new RiftriError(
+                EXIT_OPERATIONAL,
+                null,
+                `riftri ${args.join(" ")} returned output that is not JSON: ` +
+                  `${error.message}\n${stdout.slice(0, 2000)}`,
+              ),
+            );
+          }
+          return;
+        }
+        let receipt = null;
+        try {
+          receipt = JSON.parse(stderr);
+        } catch {
+          // Usage errors come from the argument parser and carry no receipt.
+        }
+        reject(new RiftriError(exitCode, receipt, stderr));
+      });
+    });
+  }
+
+  #stateFlag() {
+    return this.stateDir ? ["--state-dir", this.stateDir] : [];
+  }
+
+  /** Inspect Git and storage without creating anything. */
+  doctor(options = {}) {
+    return this.run(["doctor", ...flagsFor(options)]);
+  }
+
+  /** Probe storage backends for a destination volume. */
+  backends(pathOrOptions = {}) {
+    const target = typeof pathOrOptions === "string" ? [pathOrOptions] : [];
+    return this.run(["backends", ...target]);
+  }
+
+  /**
+   * True when this destination can get an optimized worktree.
+   *
+   * `false` is an answer from Riftri: either the report says no backend is
+   * active, or Riftri refused this destination outright. A broken
+   * installation, an unreadable repository, or any other unexpected failure
+   * rejects instead, so a caller can tell "not supported here" apart from
+   * "this client cannot run at all".
+   */
+  async isOptimizable(destination) {
+    try {
+      const report = await this.doctor(destination ? { destination } : {});
+      if (!report?.cow_backend_active) return false;
+      // cow_backend_active is a fact about the volume, not about this
+      // destination. Outside a Git repository it is still true while
+      // `worktree add` cannot possibly succeed, so the readiness verdict
+      // decides. `needs-activation` stays optimizable: the explicit interface
+      // works without `enable`, which only gates Git interception.
+      const readiness = report.destination_readiness?.status;
+      return readiness === undefined || readiness !== "blocked";
+    } catch (error) {
+      if (error instanceof RiftriError && error.isPolicyRefusal) return false;
+      throw error;
+    }
+  }
+
+  /** Opt one repository in. Required before interception applies. */
+  enable() {
+    return this.run(["enable"], { json: false });
+  }
+
+  disable() {
+    return this.run(["disable"], { json: false });
+  }
+
+  /** Bases, reference counts, storage use, and pending operations. */
+  status() {
+    return this.run(["status", ...this.#stateFlag()]);
+  }
+
+  /** Resume or roll back interrupted operations. Safe to run repeatedly. */
+  repair() {
+    return this.run(["repair", ...this.#stateFlag()]);
+  }
+
+  /** Plan base collection; pass `{ apply: true }` to delete. */
+  gc({ apply = false } = {}) {
+    const args = ["gc", ...this.#stateFlag()];
+    if (apply) args.push("--apply", "--yes");
+    return this.run(args);
+  }
+
+  #worktreeAdd(destination, options = {}) {
+    const { revision, ...rest } = options;
+    const args = ["worktree", "add", destination];
+    if (revision) args.push(revision);
+    return this.run([...args, ...flagsFor(rest), ...this.#stateFlag()]);
+  }
+
+  #worktreeList(options = {}) {
+    return this.run(["worktree", "list", ...flagsFor(options), ...this.#stateFlag()]);
+  }
+
+  #worktreeRemove(destination, { force = false } = {}) {
+    const args = ["worktree", "remove", destination];
+    if (force) args.push("--force", "--yes");
+    return this.run([...args, ...this.#stateFlag()]);
+  }
+
+  #worktreeMove(source, destination) {
+    return this.run(["worktree", "move", source, destination, ...this.#stateFlag()]);
+  }
+
+  #worktreeCompact(destination) {
+    return this.run(["worktree", "compact", destination, ...this.#stateFlag()]);
+  }
+
+  #worktreePrune() {
+    return this.run(["worktree", "prune", ...this.#stateFlag()]);
+  }
+}
+
+module.exports = {
+  Riftri,
+  RiftriError,
+  EXIT_SUCCESS,
+  EXIT_OPERATIONAL,
+  EXIT_USAGE,
+  EXIT_POLICY,
+};

package/lib/platform.js

@@ -14,6 +14,15 @@ const PLATFORM_PACKAGES = Object.freeze({
   "win32-x64": "riftri-win32-x64",
 });
 
+// Native packages the registry has refused, mapped to the route that does work.
+// A name only belongs here while it is genuinely absent from npm; remove the
+// entry in the release that first publishes it.
+const UNPUBLISHED_PACKAGES = Object.freeze({
+  "riftri-win32-arm64":
+    "install it with the PowerShell installer instead: " +
+    "https://riftri.dev/docs/installation",
+});
+
 function detectLinuxLibc(report = process.report) {
   if (!report || typeof report.getReport !== "function") {
     return "unknown";
@@ -102,8 +111,13 @@ function resolveBinary(options = {}) {
   try {
     packageJson = require.resolve(`${packageName}/package.json`);
   } catch {
+    // Reinstalling cannot help when the package was never published, so say so
+    // instead of sending the user around the same loop.
+    const unpublished = UNPUBLISHED_PACKAGES[packageName];
     throw new Error(
-      `the optional native package ${packageName} is missing; reinstall without --omit=optional, or build Riftri from source`,
+      unpublished
+        ? `${packageName} is not published to npm, so riftri cannot run on this platform through npm; ${unpublished}`
+        : `the optional native package ${packageName} is missing; reinstall without --omit=optional, or build Riftri from source`,
     );
   }
 
@@ -125,6 +139,7 @@ function resolveBinary(options = {}) {
 
 module.exports = {
   PLATFORM_PACKAGES,
+  UNPUBLISHED_PACKAGES,
   assertCompatiblePackageManifest,
   binaryName,
   detectLinuxLibc,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riftri",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Experimental lightweight Git workspaces for parallel development",
   "license": "MIT",
   "author": "Assistant UI contributors",
@@ -18,14 +18,14 @@
     "node": ">=18.18"
   },
   "optionalDependencies": {
-    "riftri-darwin-arm64": "0.3.5",
-    "riftri-darwin-x64": "0.3.5",
-    "riftri-linux-arm64-gnu": "0.3.5",
-    "riftri-linux-arm64-musl": "0.3.5",
-    "riftri-linux-x64-gnu": "0.3.5",
-    "riftri-linux-x64-musl": "0.3.5",
-    "riftri-win32-arm64": "0.3.5",
-    "riftri-win32-x64": "0.3.5"
+    "riftri-darwin-arm64": "0.4.1",
+    "riftri-darwin-x64": "0.4.1",
+    "riftri-linux-arm64-gnu": "0.4.1",
+    "riftri-linux-arm64-musl": "0.4.1",
+    "riftri-linux-x64-gnu": "0.4.1",
+    "riftri-linux-x64-musl": "0.4.1",
+    "riftri-win32-arm64": "0.4.1",
+    "riftri-win32-x64": "0.4.1"
   },
   "repository": {
     "type": "git",
@@ -45,5 +45,14 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "main": "lib/client.js",
+  "types": "lib/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/client.d.ts",
+      "require": "./lib/client.js",
+      "default": "./lib/client.js"
+    }
   }
 }