riftri 0.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riftri contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# Riftri
+
+**Lightweight Git workspaces for parallel development.**
+
+Riftri creates real Git worktrees without eagerly storing another full physical
+copy of every unchanged project file. It is designed for developers and coding
+agents working on several tasks at once.
+
+[![CI](https://github.com/assistant-ui/riftri/actions/workflows/ci.yml/badge.svg)](https://github.com/assistant-ui/riftri/actions/workflows/ci.yml)
+
+> [!WARNING]
+> Riftri is experimental, pre-release software. Keep important work committed or
+> backed up. Optimized worktrees need APFS on macOS, Btrfs or reflink-enabled
+> XFS or OverlayFS on Linux, or ReFS on Windows — see
+> [what works today](#what-works-today).
+
+## Why Riftri?
+
+Git linked worktrees share repository history, but each worktree normally gets
+its own complete checkout. That can consume significant disk space when several
+developers or agents work on a large repository in parallel.
+
+Riftri keeps normal Git behavior while making those checkouts lightweight:
+
+- Every workspace is a real Git linked worktree.
+- Unchanged files share native copy-on-write storage blocks.
+- Changes remain private to each worktree.
+- Editors, build tools, and agents use ordinary files and Git commands.
+- Interrupted creation and cleanup operations can be recovered safely.
+
+Riftri does not replace Git, manage branches, or sit between applications and
+the filesystem. For how it compares to plain `git worktree`, reference clones,
+manual reflink copies, and per-agent containers, see the
+[comparison with alternatives](docs/comparison.md).
+
+## Install
+
+macOS and Linux:
+
+```sh
+curl -fsSL https://riftri.dev/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+$Installer = Join-Path $env:TEMP 'riftri-install.ps1'
+Invoke-WebRequest https://riftri.dev/install.ps1 -OutFile $Installer
+& $Installer
+```
+
+Both installers verify SHA-256 and the binary version, install to a per-user
+directory, and never use sudo, edit shell profiles, or activate Git
+interception. Node.js is not required. Read
+[`install.sh`](package/install.sh) or [`install.ps1`](package/install.ps1)
+first if you prefer, and see the [installation guide](docs/install.md) for all
+eight targets, manual downloads, and checksum verification.
+
+Or build from source:
+
+```console
+$ cargo build --release -p riftri-cli
+$ ./target/release/riftri doctor
+```
+
+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.
+
+## Quick start
+
+For an interactive walkthrough (v0.3.1 and later), run
+`riftri setup` inside your existing repository. It checks the destination,
+confirms a new worktree at `HEAD`, and then asks whether to open Claude Code,
+Codex, another installed executable, or no agent. Repository enablement and
+agent launch require a separate confirmation. See the
+[setup reference](docs/cli.md#riftri-setup-options).
+
+The explicit commands below work in the current release and in automation.
+
+Check that the repository and destination are compatible — this creates
+nothing:
+
+```console
+$ riftri doctor --destination ../app-auth
+```
+
+Then create a worktree:
+
+```console
+$ riftri worktree add ../app-auth -b feature/auth main
+$ cd ../app-auth
+$ git status
+```
+
+To attach an existing branch instead, drop the `-b` flag:
+
+```console
+$ riftri worktree add ../app-auth feature/auth
+```
+
+The new directory behaves like any other Git worktree.
+
+## Use normal `git worktree` commands
+
+Activate the Git shim in your shell, then opt in each repository:
+
+```console
+$ eval "$(riftri shell hook zsh)"
+$ cd app
+$ riftri enable
+$ git worktree add -b feature/auth ../app-auth main
+```
+
+For a single agent or command tree, skip the shell hook entirely:
+
+```console
+$ riftri enable
+$ riftri exec -- claude
+```
+
+Activating the shell hook does **not** enable Riftri everywhere: `riftri enable`
+is still required per repository, and other repositories go straight to real
+Git. Use `riftri disable` to opt out and `riftri shell status` to inspect
+activation.
+
+PowerShell setup, IDE and container edge cases, and agent harness integration
+are covered in [global activation](docs/global-activation.md) and the
+[agent integration guide](docs/agent-integration.md).
+
+## What works today
+
+| Platform | Backend | Status |
+| --- | --- | --- |
+| macOS | APFS clones | Supported |
+| Linux | Btrfs / reflink-enabled XFS | Supported |
+| Linux | OverlayFS | Experimental |
+| Windows | ReFS block clones | Supported |
+
+On those backends Riftri creates real linked worktrees, intercepts Git per
+repository or per process, removes, moves, prunes, and compacts them, reuses
+immutable bases with disk accounting, and recovers from interruption through
+journaled repair and garbage collection.
+
+OverlayFS additionally needs either a mount-capable namespace or a one-time
+helper. The helper is installed system-wide but intercepts nothing on its own,
+and `riftri enable` remains a separate per-repository choice:
+
+```console
+$ 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
+[how Riftri stays safe](docs/safety.md).
+
+## Common commands
+
+```console
+$ riftri doctor                      # check compatibility
+$ riftri worktree list               # managed worktrees and their disk use
+$ riftri status                      # bases, references, and accounting
+$ riftri worktree compact ../app-auth
+$ riftri repair                      # resume or roll back interrupted work
+$ riftri gc --apply                  # delete unreferenced bases
+```
+
+Explicit lifecycle and diagnostic commands accept `--json` and `--json-errors`
+for structured success and failure receipts, so automation does not have to
+scrape human text. Interactive `setup` is for terminal users, not automation.
+The full reference is in [docs/cli.md](docs/cli.md).
+
+## Optional agent skill
+
+The repository includes a reviewable
+[`riftri-worktrees` skill](skills/riftri-worktrees/SKILL.md) for agents that need
+to create or use Riftri worktrees. It explains explicit creation, process-scoped
+Git interception, and safe cleanup; it is not required for copy-on-write safety
+and does not install Riftri or enable a repository.
+
+Install it through the [skills CLI](https://skills.sh/docs/cli):
+
+```sh
+npx skills add assistant-ui/riftri --skill riftri-worktrees
+```
+
+Review the skill first and choose the agent and installation scope in the CLI.
+The skill files are hosted here on GitHub; [skills.sh](https://skills.sh/docs/faq)
+discovers and ranks skills through CLI installation telemetry. A directory
+listing is not a separate package publication or a guarantee of inclusion.
+
+## Documentation
+
+[docs/README.md](docs/README.md) indexes everything. Start with:
+
+- [Architecture](docs/architecture.md) — immutable bases, transactions, journals
+- [How Riftri stays safe](docs/safety.md) — fail-closed rules and real-filesystem CI
+- [Troubleshooting](docs/troubleshooting.md) — symptom-first fixes
+- [CLI reference](docs/cli.md) · [Installation](docs/install.md) · [Benchmarks](docs/benchmarks.md)
+- [Project definition](PROJECT.md) · [Roadmap](ROADMAP.md) · [Releasing](RELEASING.md)
+
+## Contributing
+
+Run the complete local quality gate before opening a pull request:
+
+```console
+$ cargo fmt --all --check
+$ cargo clippy --workspace --all-targets --all-features -- -D warnings
+$ cargo test --workspace
+$ npm test
+$ npm run smoke:installed
+```
+
+Riftri is licensed under the [MIT License](LICENSE).

package/bin/riftri.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { resolveBinary } = require("../lib/platform.js");
+const { signalExitCode } = require("../lib/signals.js");
+
+function fail(message) {
+  process.stderr.write(`riftri: ${message}\n`);
+  process.exit(1);
+}
+
+let binary;
+try {
+  binary = resolveBinary();
+} catch (error) {
+  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,
+// so the native process receives its own copy and — like a shell waiting on a
+// foreground job — the command alone decides whether the interrupt is fatal.
+// Dying here instead would return the shell prompt while riftri and a command
+// that caught the interrupt keep running on the terminal. PID-directed
+// SIGTERM and SIGHUP are forwarded to the native process, which applies the
+// 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"];
+const ignoreSignal = () => {};
+const forwardSignal = (signal) => {
+  child.kill(signal);
+};
+
+if (process.platform !== "win32") {
+  for (const signal of ignoredSignals) {
+    process.on(signal, ignoreSignal);
+  }
+  for (const signal of forwardedSignals) {
+    process.on(signal, forwardSignal);
+  }
+}
+
+function releaseSignals() {
+  for (const signal of ignoredSignals) {
+    process.removeListener(signal, ignoreSignal);
+  }
+  for (const signal of forwardedSignals) {
+    process.removeListener(signal, forwardSignal);
+  }
+}
+
+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) {
+      fail(`native executable stopped after unknown signal ${signal}`);
+    }
+    process.exit(exitCode);
+  }
+  process.exit(code ?? 1);
+});

package/lib/platform.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PLATFORM_PACKAGES = Object.freeze({
+  "darwin-arm64": "riftri-darwin-arm64",
+  "darwin-x64": "riftri-darwin-x64",
+  "linux-arm64-gnu": "riftri-linux-arm64-gnu",
+  "linux-arm64-musl": "riftri-linux-arm64-musl",
+  "linux-x64-gnu": "riftri-linux-x64-gnu",
+  "linux-x64-musl": "riftri-linux-x64-musl",
+  "win32-arm64": "riftri-win32-arm64",
+  "win32-x64": "riftri-win32-x64",
+});
+
+function detectLinuxLibc(report = process.report) {
+  if (!report || typeof report.getReport !== "function") {
+    return "unknown";
+  }
+
+  const header = report.getReport()?.header;
+  return header?.glibcVersionRuntime ? "gnu" : "musl";
+}
+
+function platformKey(
+  platform = process.platform,
+  architecture = process.arch,
+  report = process.report,
+) {
+  if (platform === "linux") {
+    return `${platform}-${architecture}-${detectLinuxLibc(report)}`;
+  }
+  return `${platform}-${architecture}`;
+}
+
+function packageNameForPlatform(platform, architecture, report) {
+  return PLATFORM_PACKAGES[platformKey(platform, architecture, report)] ?? null;
+}
+
+function binaryName(platform = process.platform) {
+  return platform === "win32" ? "riftri.exe" : "riftri";
+}
+
+function assertUsableBinary(candidate, source) {
+  try {
+    fs.accessSync(
+      candidate,
+      process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK,
+    );
+  } catch {
+    throw new Error(`${source} does not contain an executable Riftri binary: ${candidate}`);
+  }
+  return candidate;
+}
+
+function launcherVersion() {
+  for (const candidate of [
+    path.join(__dirname, "..", "package.json"),
+    path.join(__dirname, "..", "..", "package.json"),
+  ]) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(candidate, "utf8"));
+      if (manifest.name === "riftri" && typeof manifest.version === "string") {
+        return manifest.version;
+      }
+    } catch {
+      // The source and staged package layouts put the root manifest at different depths.
+    }
+  }
+  throw new Error("could not read the riftri launcher version");
+}
+
+function assertCompatiblePackageManifest(manifest, packageName, expectedVersion) {
+  if (manifest.name !== packageName || manifest.version !== expectedVersion) {
+    throw new Error(
+      `the optional native package ${packageName} does not match riftri ${expectedVersion}; reinstall riftri and its optional dependencies together`,
+    );
+  }
+}
+
+function resolveBinary(options = {}) {
+  const environment = options.environment ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const architecture = options.architecture ?? process.arch;
+  const report = options.report ?? process.report;
+
+  if (environment.RIFTRI_BINARY) {
+    const override = path.resolve(environment.RIFTRI_BINARY);
+    return assertUsableBinary(override, "RIFTRI_BINARY");
+  }
+
+  const packageName = packageNameForPlatform(platform, architecture, report);
+  if (!packageName) {
+    const key = platformKey(platform, architecture, report);
+    throw new Error(
+      `no prebuilt native package is available for ${key}; supported packages: ${Object.keys(PLATFORM_PACKAGES).join(", ")}`,
+    );
+  }
+
+  let packageJson;
+  try {
+    packageJson = require.resolve(`${packageName}/package.json`);
+  } catch {
+    throw new Error(
+      `the optional native package ${packageName} is missing; reinstall without --omit=optional, or build Riftri from source`,
+    );
+  }
+
+  let packageManifest;
+  try {
+    packageManifest = JSON.parse(fs.readFileSync(packageJson, "utf8"));
+  } catch {
+    throw new Error(`the optional native package ${packageName} has an invalid manifest`);
+  }
+  assertCompatiblePackageManifest(
+    packageManifest,
+    packageName,
+    options.expectedVersion ?? launcherVersion(),
+  );
+
+  const candidate = path.join(path.dirname(packageJson), "bin", binaryName(platform));
+  return assertUsableBinary(candidate, packageName);
+}
+
+module.exports = {
+  PLATFORM_PACKAGES,
+  assertCompatiblePackageManifest,
+  binaryName,
+  detectLinuxLibc,
+  packageNameForPlatform,
+  platformKey,
+  resolveBinary,
+};

package/lib/signals.js

@@ -0,0 +1,27 @@
+"use strict";
+
+const os = require("node:os");
+
+/**
+ * Exit code the launcher reports for a native process that died from `signal`,
+ * following the shell convention native `riftri exec` itself uses: 128 plus
+ * the signal's number on this platform. The code is computed numerically —
+ * never by re-raising the signal through `process.kill`, which is a silent
+ * no-op for signals Node ignores or reserves (SIGPIPE, SIGUSR1, SIGWINCH,
+ * SIGCHLD, SIGURG) and would turn a killed run into exit 0.
+ *
+ * Returns `null` when the name is not a signal this platform knows, so the
+ * caller can report the failure instead of guessing a number.
+ */
+function signalExitCode(signal) {
+  if (typeof signal !== "string") {
+    return null;
+  }
+  const number = os.constants.signals[signal];
+  if (!Number.isInteger(number) || number <= 0) {
+    return null;
+  }
+  return 128 + number;
+}
+
+module.exports = { signalExitCode };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "riftri",
+  "version": "0.3.5",
+  "description": "Experimental lightweight Git workspaces for parallel development",
+  "license": "MIT",
+  "author": "Assistant UI contributors",
+  "type": "commonjs",
+  "bin": {
+    "riftri": "bin/riftri.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assistant-ui/riftri.git"
+  },
+  "bugs": {
+    "url": "https://github.com/assistant-ui/riftri/issues"
+  },
+  "homepage": "https://riftri.dev",
+  "keywords": [
+    "git",
+    "worktree",
+    "copy-on-write",
+    "developer-tools",
+    "coding-agents"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}