riftri 0.5.1 → 0.6.1

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");
 
@@ -29,8 +30,21 @@ try {
 // 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 = [];
@@ -59,6 +73,7 @@ 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);

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 {
@@ -71,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;
 }
@@ -93,18 +102,74 @@ export interface ManagedWorktree {
 }
 
 export interface WorktreeInventory {
-  schema_version: number;
+  schema_version: 1;
   state_directory: string;
+  state_directory_native_hex: string;
   worktrees: ManagedWorktree[];
+  diagnostic_issues: StateDiagnosticIssue[];
   native_path_encoding: string;
 }
 
+export interface StateDiagnosticIssue {
+  path: string;
+  path_native_hex: string;
+  reason: string;
+  may_hide_base_reference: boolean;
+}
+
+export interface AllStatesManagedWorktree extends ManagedWorktree {
+  state_directory: string;
+  state_directory_native_hex: string;
+}
+
+export interface AllStatesDiagnosticIssue extends StateDiagnosticIssue {
+  /** Null for a registration issue that belongs to no usable state directory. */
+  state_directory: string | null;
+  state_directory_native_hex: string | null;
+}
+
+export interface AllStatesWorktreeInventory {
+  schema_version: 2;
+  scope: "all-registered-states";
+  state_directories: {
+    path: string;
+    path_native_hex: string;
+    source: "default" | "registered";
+  }[];
+  worktrees: AllStatesManagedWorktree[];
+  diagnostic_issues: AllStatesDiagnosticIssue[];
+  native_path_encoding: string;
+}
+
+/** Lifecycle counters; lower bounds when StatusReport.counts_complete is false. */
+export interface StatusOperations {
+  active_views: number;
+  pending_adds: number;
+  completed_removals: number;
+  cancelled_removals: number;
+  pending_removals: number;
+  completed_moves: number;
+  cancelled_moves: number;
+  pending_moves: number;
+  completed_compactions: number;
+  cancelled_compactions: number;
+  pending_compactions: number;
+  completed_prunes: number;
+  pending_prunes: number;
+  completed_collections: number;
+  cancelled_collections: number;
+  pending_collections: number;
+  coordination_locks: number;
+}
+
 export interface StatusReport {
   schema_version: number;
   state_directory: string;
   bases: unknown[];
   worktrees: unknown[];
-  operations: unknown[];
+  /** False when unreadable journals make operation counts lower bounds. */
+  counts_complete: boolean;
+  operations: StatusOperations;
   diagnostic_issues: unknown[];
   total_allocated_bytes: number;
   total_logical_bytes: number;
@@ -133,7 +198,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;
@@ -171,7 +239,10 @@ export class Riftri {
 
   readonly worktree: {
     add(destination: string, options?: AddOptions): Promise<AddReport>;
-    list(options?: { allStates?: boolean }): Promise<WorktreeInventory>;
+    list(options: { allStates: true }): Promise<AllStatesWorktreeInventory>;
+    list(options?: { allStates?: false }): Promise<WorktreeInventory>;
+    /** Narrow schema_version when allStates is a runtime boolean. */
+    list(options?: { allStates?: boolean }): Promise<WorktreeInventory | AllStatesWorktreeInventory>;
     /** Refuses a dirty worktree unless `force` is set. */
     remove(destination: string, options?: { force?: boolean }): Promise<unknown>;
     move(source: string, destination: string): Promise<unknown>;

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");
 
@@ -30,7 +31,9 @@ const REPORTING = new Set([
 class RiftriError extends Error {
   constructor(exitCode, receipt, stderr, signal = null) {
     super(
-      receipt?.message ||
+      // JSON is not a guarantee of a valid receipt. Coercing an object here
+      // can throw inside the child close handler instead of rejecting run().
+      (typeof receipt?.message === "string" ? receipt.message : "") ||
         stderr.trim() ||
         (signal ? `riftri terminated by ${signal}` : `riftri exited ${exitCode}`),
     );
@@ -90,9 +93,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;
 }
@@ -106,7 +111,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),
@@ -144,7 +153,18 @@ class Riftri {
       }
       let stdout = "";
       let stderr = "";
-      child.stdout.on("data", (chunk) => (stdout += chunk));
+      // Pipe chunks need not end on a UTF-8 character boundary. Let each
+      // stream retain incomplete bytes between chunks (and flush at EOF).
+      if (json) {
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => (stdout += chunk));
+      } else {
+        // The API returns null for non-reporting commands. Drain their output
+        // without decoding or retaining it, so verbose children cannot grow
+        // the host heap in proportion to output that will be discarded.
+        child.stdout.resume();
+      }
+      child.stderr.setEncoding("utf8");
       child.stderr.on("data", (chunk) => (stderr += chunk));
       child.on("error", reject);
       child.on("close", (exitCode, signal) => {
@@ -156,7 +176,7 @@ class Riftri {
           return;
         }
         if (exitCode === EXIT_SUCCESS) {
-          if (!json || !stdout.trim()) {
+          if (!json) {
             resolve(null);
             return;
           }
@@ -176,11 +196,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));
       });
@@ -188,7 +215,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. */
@@ -198,7 +225,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]);
   }
 
@@ -254,29 +281,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.1",
+  "version": "0.6.1",
   "description": "Experimental lightweight Git workspaces for parallel development",
   "license": "MIT",
   "author": "Assistant UI contributors",
@@ -17,15 +17,19 @@
   "engines": {
     "node": ">=18.18"
   },
+  "devDependencies": {
+    "@types/node": "18.19.130",
+    "typescript": "5.9.3"
+  },
   "optionalDependencies": {
-    "riftri-darwin-arm64": "0.5.1",
-    "riftri-darwin-x64": "0.5.1",
-    "riftri-linux-arm64-gnu": "0.5.1",
-    "riftri-linux-arm64-musl": "0.5.1",
-    "riftri-linux-x64-gnu": "0.5.1",
-    "riftri-linux-x64-musl": "0.5.1",
-    "riftri-win32-arm64": "0.5.1",
-    "riftri-win32-x64": "0.5.1"
+    "riftri-darwin-arm64": "0.6.1",
+    "riftri-darwin-x64": "0.6.1",
+    "riftri-linux-arm64-gnu": "0.6.1",
+    "riftri-linux-arm64-musl": "0.6.1",
+    "riftri-linux-x64-gnu": "0.6.1",
+    "riftri-linux-x64-musl": "0.6.1",
+    "riftri-win32-arm64": "0.6.1",
+    "riftri-win32-x64": "0.6.1"
   },
   "repository": {
     "type": "git",