riftri 0.5.0 → 0.6.0

package/README.md

@@ -73,11 +73,6 @@ Or install through npm, which fetches the binary for your platform:
 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
 
 For an interactive walkthrough (v0.3.1 and later), run

package/bin/riftri.js

@@ -3,6 +3,7 @@
 "use strict";
 
 const { spawn } = require("node:child_process");
+const tty = require("node:tty");
 const { resolveBinary } = require("../lib/platform.js");
 const { signalExitCode } = require("../lib/signals.js");
 
@@ -18,11 +19,6 @@ try {
   fail(error instanceof Error ? error.message : String(error));
 }
 
-const child = spawn(binary, process.argv.slice(2), {
-  stdio: "inherit",
-  windowsHide: false,
-});
-
 // Mirror the termination contract of native `riftri exec` (docs/cli.md) while
 // the native process runs. The launcher survives SIGINT (Ctrl-C) and SIGQUIT
 // (Ctrl-\): a terminal delivers both to the whole foreground process group,
@@ -34,13 +30,37 @@ const child = spawn(binary, process.argv.slice(2), {
 // same contract downstream to the scoped command. Windows has no equivalent
 // to preserve: the console already delivers Ctrl-C events to every attached
 // process, and a hard TerminateProcess cannot be intercepted.
-const ignoredSignals = ["SIGINT", "SIGQUIT"];
-const forwardedSignals = ["SIGTERM", "SIGHUP"];
+//
+// Without a terminal (an agent harness, CI, or a script), native `riftri
+// exec` forwards SIGINT and SIGQUIT as well and runs its child in its own
+// process group. The launcher does the same there: otherwise a PID-directed
+// SIGINT was ignored outright and the command ran on, where the native binary
+// would have stopped it. The native process gets its own group so that a
+// signal sent to the caller's whole group reaches it once, through here, and
+// not a second time directly. `isatty` is used rather than `process.stdin`,
+// whose initialization can switch the inherited descriptor to non-blocking.
+const supervised =
+  process.platform !== "win32" && ![0, 1, 2].some((descriptor) => tty.isatty(descriptor));
+const ignoredSignals = supervised ? [] : ["SIGINT", "SIGQUIT"];
+const forwardedSignals = supervised
+  ? ["SIGTERM", "SIGHUP", "SIGINT", "SIGQUIT"]
+  : ["SIGTERM", "SIGHUP"];
 const ignoreSignal = () => {};
+let child;
+const pendingForwardedSignals = [];
 const forwardSignal = (signal) => {
+  if (child === undefined) {
+    pendingForwardedSignals.push(signal);
+    return;
+  }
   child.kill(signal);
 };
 
+// Arm the policy before starting the child. A fast child can write to the
+// inherited terminal before `spawn` returns in the launcher process; callers
+// commonly treat that output as readiness and may immediately signal the
+// foreground process group. Installing these handlers after `spawn` left a
+// window where that SIGINT still had its default, fatal disposition.
 if (process.platform !== "win32") {
   for (const signal of ignoredSignals) {
     process.on(signal, ignoreSignal);
@@ -50,6 +70,16 @@ if (process.platform !== "win32") {
   }
 }
 
+child = spawn(binary, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: false,
+  detached: supervised,
+});
+for (const signal of pendingForwardedSignals) {
+  child.kill(signal);
+}
+pendingForwardedSignals.length = 0;
+
 // 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

package/lib/client.d.ts

@@ -9,14 +9,21 @@ export const EXIT_POLICY: 3;
 export interface FailureReceipt {
   schemaVersion: number;
   outcome: "failed";
-  operation: string;
+  /** Null for a usage error: parsing failed before a command was chosen. */
+  operation: string | null;
   code: string;
-  category: "policy" | "operational";
+  /** Mirrors the exit code: 1 operational, 2 usage, 3 policy. */
+  category: "policy" | "operational" | "usage";
   message: string;
   phase: string | null;
   cleanup: string;
   recovery: "required" | "not-required" | "retry" | "inspect" | "unknown";
   nextCommand: string | null;
+  repository: string | null;
+  repositoryNativeHex: string | null;
+  stateDirectory: string | null;
+  stateDirectoryNativeHex: string | null;
+  nativePathEncoding: string;
 }
 
 export class RiftriError extends Error {
@@ -36,6 +43,8 @@ export class RiftriError extends Error {
   readonly isUsageError: boolean;
   /** A live process holds the lock; waiting and retrying is correct. */
   readonly isBusy: boolean;
+  /** Free space on the affected volume before following recovery guidance. */
+  readonly isStorageFull: boolean;
   /** Run `receipt.nextCommand` before continuing. */
   readonly needsRepair: boolean;
 }
@@ -69,6 +78,8 @@ export interface AddReport {
   base_path: string;
   /** False when this add materialized a new immutable base. */
   reused_base: boolean;
+  /** The `post-checkout` hook Git would run, or null when there is none. */
+  post_checkout: { hook: string; started: boolean; exit_code: number | null } | null;
   journal_path: string;
   native_path_encoding: string;
 }
@@ -131,7 +142,10 @@ export interface AddOptions {
 export interface RiftriOptions {
   /** Working directory for every command. Defaults to `process.cwd()`. */
   repository?: string;
-  /** Explicit executable; defaults to the installed platform binary. */
+  /**
+   * Explicit executable; defaults to the installed platform binary. A
+   * relative path is relative to `process.cwd()`, not `repository`.
+   */
   binary?: string;
   /** Passed as `--state-dir` where the command supports it. */
   stateDir?: string;

package/lib/client.js

@@ -8,6 +8,7 @@
 // failure. Nothing here reimplements Riftri behaviour.
 
 const { spawn } = require("node:child_process");
+const path = require("node:path");
 const { resolveBinary } = require("./platform.js");
 const { signalExitCode } = require("./signals.js");
 
@@ -62,6 +63,11 @@ class RiftriError extends Error {
     return this.receipt?.code === "worktree-busy";
   }
 
+  /** The affected volume needs free space before recovery can proceed. */
+  get isStorageFull() {
+    return this.receipt?.code === "storage-full";
+  }
+
   /** Run `nextCommand` (usually `riftri repair`) before continuing. */
   get needsRepair() {
     return this.receipt?.recovery === "required";
@@ -85,9 +91,11 @@ function flagsFor(options) {
   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()}`)}`;
+    // `--flag=value`, so a value that starts with `-` (a branch, a path) is
+    // never parsed as another flag.
     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));
+    else if (Array.isArray(value)) for (const item of value) flags.push(`${flag}=${item}`);
+    else flags.push(`${flag}=${value}`);
   }
   return flags;
 }
@@ -101,7 +109,11 @@ class Riftri {
    */
   constructor(options = {}) {
     this.repository = options.repository ?? process.cwd();
-    this.binary = options.binary ?? null;
+    // A relative path is relative to this process, as RIFTRI_BINARY is.
+    // Otherwise spawn resolves it against `repository`, the child's cwd. A
+    // bare name is still looked up on PATH.
+    const binary = options.binary ?? null;
+    this.binary = binary && /[\\/]/.test(binary) ? path.resolve(binary) : binary;
     this.stateDir = options.stateDir ?? null;
     this.worktree = {
       add: this.#worktreeAdd.bind(this),
@@ -171,11 +183,18 @@ class Riftri {
           }
           return;
         }
+        // The receipt is one JSON line at the end of stderr. Anything else a
+        // child wrote there first (a hook's output, a Git warning) must not
+        // cost the caller the receipt's code and category.
         let receipt = null;
-        try {
-          receipt = JSON.parse(stderr);
-        } catch {
-          // Usage errors come from the argument parser and carry no receipt.
+        const lines = stderr.trimEnd().split("\n");
+        for (const candidate of [lines.at(-1), stderr]) {
+          try {
+            receipt = JSON.parse(candidate);
+            break;
+          } catch {
+            // Plain text, as from a binary that predates usage receipts.
+          }
         }
         reject(new RiftriError(exitCode, receipt, stderr));
       });
@@ -183,7 +202,7 @@ class Riftri {
   }
 
   #stateFlag() {
-    return this.stateDir ? ["--state-dir", this.stateDir] : [];
+    return this.stateDir ? [`--state-dir=${this.stateDir}`] : [];
   }
 
   /** Inspect Git and storage without creating anything. */
@@ -193,7 +212,7 @@ class Riftri {
 
   /** Probe storage backends for a destination volume. */
   backends(pathOrOptions = {}) {
-    const target = typeof pathOrOptions === "string" ? [pathOrOptions] : [];
+    const target = typeof pathOrOptions === "string" ? ["--", pathOrOptions] : [];
     return this.run(["backends", ...target]);
   }
 
@@ -249,29 +268,34 @@ class Riftri {
     return this.run(args);
   }
 
+  // Paths and revisions follow `--`: a relative path such as `-scratch` was
+  // otherwise parsed as flags and the call failed as a usage error.
   #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()]);
+    const positionals = ["--", destination];
+    if (revision) positionals.push(revision);
+    return this.run(["worktree", "add", ...flagsFor(rest), ...this.#stateFlag(), ...positionals]);
   }
 
   #worktreeList(options = {}) {
-    return this.run(["worktree", "list", ...flagsFor(options), ...this.#stateFlag()]);
+    // `--all-states` already covers the configured state directory, and Riftri
+    // rejects it alongside `--state-dir` as a usage error.
+    const state = options.allStates ? [] : this.#stateFlag();
+    return this.run(["worktree", "list", ...flagsFor(options), ...state]);
   }
 
   #worktreeRemove(destination, { force = false } = {}) {
-    const args = ["worktree", "remove", destination];
+    const args = ["worktree", "remove"];
     if (force) args.push("--force", "--yes");
-    return this.run([...args, ...this.#stateFlag()]);
+    return this.run([...args, ...this.#stateFlag(), "--", destination]);
   }
 
   #worktreeMove(source, destination) {
-    return this.run(["worktree", "move", source, destination, ...this.#stateFlag()]);
+    return this.run(["worktree", "move", ...this.#stateFlag(), "--", source, destination]);
   }
 
   #worktreeCompact(destination) {
-    return this.run(["worktree", "compact", destination, ...this.#stateFlag()]);
+    return this.run(["worktree", "compact", ...this.#stateFlag(), "--", destination]);
   }
 
   #worktreePrune() {

package/lib/platform.js

@@ -14,15 +14,6 @@ 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";
@@ -111,13 +102,8 @@ 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(
-      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`,
+      `the optional native package ${packageName} is missing; reinstall without --omit=optional, or build Riftri from source`,
     );
   }
 
@@ -139,7 +125,6 @@ function resolveBinary(options = {}) {
 
 module.exports = {
   PLATFORM_PACKAGES,
-  UNPUBLISHED_PACKAGES,
   assertCompatiblePackageManifest,
   binaryName,
   detectLinuxLibc,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riftri",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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.5.0",
-    "riftri-darwin-x64": "0.5.0",
-    "riftri-linux-arm64-gnu": "0.5.0",
-    "riftri-linux-arm64-musl": "0.5.0",
-    "riftri-linux-x64-gnu": "0.5.0",
-    "riftri-linux-x64-musl": "0.5.0",
-    "riftri-win32-arm64": "0.5.0",
-    "riftri-win32-x64": "0.5.0"
+    "riftri-darwin-arm64": "0.6.0",
+    "riftri-darwin-x64": "0.6.0",
+    "riftri-linux-arm64-gnu": "0.6.0",
+    "riftri-linux-arm64-musl": "0.6.0",
+    "riftri-linux-x64-gnu": "0.6.0",
+    "riftri-linux-x64-musl": "0.6.0",
+    "riftri-win32-arm64": "0.6.0",
+    "riftri-win32-x64": "0.6.0"
   },
   "repository": {
     "type": "git",