rl-workspaces 0.6.0 → 0.7.0

package/README.md

@@ -6,31 +6,41 @@ Create a workspace, start an agent, and keep task notes and sessions together.
 Switch projects, prepare local dependencies, check PRs, and merge finished work
 without losing your place.
 
-Requires macOS or Linux, Git, zsh, and Node.js 22+. Bash users can use the Bash
-integration. Install `fzf` for pickers, `gh` for PR commands, and whichever agent
-you use.
+Requires macOS or Linux and Node.js 22+. Global npm installation sets up Git,
+zsh, fzf, GitHub CLI and integration for your zsh or bash terminal.
 
 ## Install
 
 Install from npm:
 
 ```sh
-npm install --global rl-workspaces
+npm install --global rl-workspaces --foreground-scripts
 ```
 
 See Development below to build and try unpublished changes.
 
-Add one line to your shell configuration, then open a new terminal:
+The installer installs missing tools through your package manager, preserves
+your shell settings, and registers one RL integration block. Open a new terminal
+after installation; bare `rl` can then select a workspace and change directory.
+For the terminal that ran the install, use the activation command printed by the
+installer, or:
 
 ```sh
-eval "$(command rl setup shell zsh)"   # ~/.zshrc
+eval "$(command rl setup shell zsh)"
 # or
-eval "$(command rl setup shell bash)"  # ~/.bashrc
+eval "$(command rl setup shell bash)"
 ```
 
-Shell integration lets `rl` change your terminal's directory. Direct executable
-calls print the selected path. The integration loads the current runtime on
-each call, so an npm upgrade does not leave you using old commands.
+This activates the setup already registered for future terminals. Shell
+integration is what lets `rl` change the calling terminal's directory; an
+executable by itself can only print the selected path. The integration loads
+the current runtime on each call, including after npm upgrades.
+
+Tool installation needs Homebrew on macOS, or Homebrew/APT/DNF/Yum/Pacman/APK
+on Linux, with permission to install packages. A failed setup reports the command
+to finish in your terminal. If lifecycle scripts were disabled, run
+`rl setup install` to complete everything. `rl setup dependencies --check`
+checks tools without changing them. GitHub PR commands require `gh auth login`.
 
 ## Get started
 
@@ -81,13 +91,17 @@ under `rl agent`, cleanup under `rl storage`, and project/shell setup under
 | `rl delete` | Remove workspaces |
 | `rl storage` | Inspect disk usage and clean generated files |
 
-`rl help switch` also documents the specialized `new`, `open`, and `path`
-helpers. `rl help exec` describes running an arbitrary command in a workspace.
+`rl switch <branch>` opens an existing checkout or creates a managed workspace
+for an existing local or origin branch. Remote branches are tracked automatically.
+`rl switch -c <branch>` creates a feature workspace from the configured base and
+refuses an already checked-out branch. Both use nested branch names as directory
+paths. Switching installs hooks and preserves existing notes. A checkout that RL
+adopts outside its usual worktree folder also appears in the open picker and can
+be selected by directory name or branch. Unadopted outside checkouts stay hidden;
+the delete picker remains restricted to the managed worktree folder.
 
-Switching installs hooks and preserves existing notes. Creation validates names
-and refuses path escapes or an already checked-out branch. `switch -c` requires a
-new checkout; `new` and `open` can reopen an existing checkout. `open` flattens
-slashes in directory names; `new` and `switch -c` retain nested names.
+`rl help path` documents printing workspace paths, and `rl help exec` describes
+running a command with a workspace's configured environment.
 
 Pickers show cached PR state, commits ahead/behind the base, and recent use.
 The `COMMITS + / −` column counts commits ahead/behind, rather than changed lines.
@@ -210,7 +224,6 @@ rl pr                     # open this branch's PR in your browser
 rl pr sync                # save this branch's PR state
 rl pr show                # readable saved snapshot with the full PR link
 rl pr show --json         # saved metadata for scripts
-rl pr checks [--json]     # query checks and preserve gh's exit status
 rl pr checkout 123        # new managed pr-123 workspace
 rl pr checkout 123 --name review/login
 rl pr update --base test   # select your RL session PRs behind test, then update them
@@ -224,7 +237,8 @@ refresh output. `rl pr show` works offline. `rl pr` uses the saved URL when
 available; if the browser cannot open, that link remains in its output. With no
 saved PR, it looks up the current branch through `gh pr view --web`.
 
-Opening, refreshing, checks, and checkout require authenticated `gh`. Checkout verifies the origin repository,
+Opening, refreshing, and checkout require authenticated `gh`. Use `gh pr checks`
+to inspect CI results. Checkout verifies the origin repository,
 PR identity, and fetched commit before creating a workspace. Fork PR checkout
 is currently rejected. It does not change your current branch, publish, or merge
 a PR. Failed refreshes retain the previous snapshot.
@@ -336,7 +350,7 @@ used matching session directly.
 `rl continue` still resumes the exact session saved in its task handoff.
 
 Run Codex normally in an adopted RL workspace, including in the Codex app.
-`rl status`, `rl list`, `rl instances`, `rl agent sessions`, and `rl resume` / `rl resume codex`
+`rl status`, `rl list`, `rl agent sessions`, and `rl resume` / `rl resume codex`
 automatically discover and save matching sessions through Codex's
 [`thread/list` API](https://learn.chatgpt.com/docs/app-server#list-threads-with-pagination--filters).
 Discovery filters by the exact workspace directory, excludes subagents and
@@ -387,6 +401,14 @@ creates and controls its native children. RL supplies their editable roles,
 handoff rules, review policy and durable run records. RL never launches a
 provider CLI, model API or check process for a workflow.
 
+Use your normal agent session in the workspace. RL's hooks advertise discovery
+automatically; a special launcher or pasted workflow prompt is unnecessary.
+An agent can run `rl workflow context --json` through its ordinary shell tool.
+The response includes active definitions plus `protocol.tools`: each operation's
+input schema, CLI command, positional/flag mappings and JSON stdin requirements.
+The same schemas are advertised through MCP, so an agent can use either connection.
+Native subagent support still comes from the current session's host.
+
 The default team starts together and stays available for the task:
 
 - **Writer** implements scoped changes. Before adding a function, it asks DRY
@@ -600,27 +622,30 @@ the server does not inherit it. Claude requires an explicit UUID.
 Append tools take `{"text":"..."}`. They share the same locked document updates
 as the CLI and expose no arbitrary command, deletion, or filesystem tool.
 
-In the adopted workspace, add an entry to its trusted `.codex/config.toml`:
-
-```toml
-[mcp_servers.rl]
-command = "rl"
-args = ["agent", "mcp"]
-```
+From an adopted RL workspace, connect your current agent with:
 
-For Claude, merge this entry into the workspace's `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "rl": { "type": "stdio", "command": "rl", "args": ["agent", "mcp"] }
-  }
-}
+```sh
+rl setup mcp
 ```
 
-The client must launch the server in this workspace with `rl` on PATH.
-With custom state settings, pass the same `RL_STATE_DIR` in the server environment.
-Review project trust/server approval normally. Configuration follows the official
+This configures both `.codex/config.toml` and `.mcp.json` in the current checkout.
+Pass `codex` or `claude` to select one client, or `--dry-run` to preview changes.
+Setup preserves other servers and settings, including Codex comments. It updates
+RL-managed entries on later runs and leaves a conflicting manually configured
+`rl` entry for you to resolve. Both files are validated before writing either.
+
+The client starts the installed Node and RL entry point directly. The server is
+bound to this checkout, repository and RL state directory, even when the client
+starts it elsewhere or has no `rl` executable on PATH. Entries contain local
+installation/workspace paths: run setup in each checkout and rerun after moving
+Node or RL. Setup changes only this workspace's configuration.
+
+Reload the client and review its normal project trust/MCP approval. The server
+supplies discovery, consultations and rated reviews to your existing session;
+the host supplies native agent creation and messaging. CLI discovery remains
+available without an MCP connection. The stdio server can also be launched with
+`rl agent mcp`, or `rl agent mcp --workspace <absolute-path>` when the repository
+has been selected explicitly. Configuration follows the official
 [Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) and
 [Claude MCP guide](https://code.claude.com/docs/en/mcp).
 RL does not modify global client settings or relax agent sandbox permissions.
@@ -697,22 +722,6 @@ Environment variables can also come from trusted zsh configuration selected by
 [config.example.zsh](config.example.zsh). Registration supplies repository/base
 settings; `rl help` and individual `--help` show command options.
 
-## Compatibility aliases
-
-Existing commands keep their behavior. They are omitted from the main help to
-keep one primary spelling for each operation:
-
-| Previous command | Primary command |
-| --- | --- |
-| `rl merge` | `rl git merge` |
-| `rl context/progress show/set/append/path` | `rl notes show/set/append/path context/progress` |
-| `rl summary` | `rl notes summary` |
-| `rl session list/save/add` | `rl agent sessions/save` |
-| `rl handoff`, `rl mcp` | `rl agent handoff`, `rl agent mcp` |
-| `rl clean` | `rl storage clean` |
-| `rl config init/show`, `rl adopt`, `rl init` | `rl setup init/show`, `rl setup adopt`, `rl setup shell` |
-| `rl status --list`, `rl status --all` | `rl list`, `rl list --all` |
-
 ## Development
 
 ```sh

package/bin/rl

@@ -1,54 +1,2 @@
-#!/bin/zsh -f
-emulate -L zsh
-readonly rl_home="${${(%):-%x}:A:h:h}"
-if [[ "$1" == __hook ]]; then
-  # Hooks resolve the installed CLI on PATH, not a version-specific package path.
-  # Their explicit repository/state arguments must not be replaced by user config.
-  shift
-  exec node "$rl_home/dist/cli.js" state "$@"
-fi
-if [[ "$1" == --version || "$1" == -V ]]; then
-  exec node -p 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).version' "$rl_home/package.json"
-fi
-if [[ "$1" == init ]]; then
-  if (( $# == 1 )); then
-    exec node "$rl_home/dist/help.js" init
-  fi
-  for argument in "$@"; do
-    [[ "$argument" == -- ]] && break
-    if [[ "$argument" == --help || "$argument" == -h ]]; then
-      exec node "$rl_home/dist/help.js" "$@"
-    fi
-  done
-  if [[ "$2" != zsh && "$2" != bash || $# != 2 ]]; then
-    print -u2 'Usage: rl setup shell <zsh|bash>'
-    exit 1
-  fi
-  if [[ "$2" == zsh ]]; then
-    print -r -- "source ${(q)rl_home}/shell/rl.zsh"
-  else
-    print -r -- "_rl_executable=${(qq)rl_home}/bin/rl"
-    cat <<'BASH'
-rl() {
-  local destination_file destination result previous="$PWD"
-  local -a arguments=("$@")
-  if [[ "$1" == switch && "${2:-}" == - ]]; then
-    [[ -n "${RL_PREVIOUS_WORKSPACE:-}" ]] || { printf '%s\n' 'No previous workspace in this shell' >&2; return 1; }
-    arguments[1]="$RL_PREVIOUS_WORKSPACE"
-  fi
-  destination_file=$(mktemp "${TMPDIR:-/tmp}/rl-shell.XXXXXXXX") || return 1
-  if RL_SHELL_OUTPUT="$destination_file" command "$_rl_executable" "${arguments[@]}"; then result=0; else result=$?; fi
-  destination=$(cat -- "$destination_file")
-  rm -f -- "$destination_file"
-  if [[ -n "$destination" ]]; then
-    builtin cd -- "$destination" || return 1
-    RL_PREVIOUS_WORKSPACE="$previous"
-  fi
-  return "$result"
-}
-BASH
-  fi
-  exit 0
-fi
-source "$rl_home/lib/rl.zsh" || exit 1
-_rl_main "$@"
+#!/usr/bin/env node
+await import('../dist/bootstrap.js');

package/dist/agent-launch.js

@@ -53,7 +53,7 @@ export async function main(argv) {
         if (extra.length ||
             values.prompt !== undefined ||
             (values.stdout && values.output !== undefined))
-            throw new Error("Usage: rl handoff [agent] [--stdout | --output path]");
+            throw new Error("Usage: rl agent handoff [agent] [--stdout | --output path]");
         const text = await handoff(context.store, name, target.path);
         if (typeof values.output === "string")
             fs.writeFileSync(values.output, text, { flag: "wx", mode: 0o600 });

package/dist/agent-resume.js

@@ -19,7 +19,7 @@ export async function resumeSessions(store, kind, options = {}) {
                 : a.agent.localeCompare(b.agent) || a.id.localeCompare(b.id);
     });
     if (!choices.length)
-        throw new Error(`No ${kind ? `${kind} ` : ""}session recorded for ${data.id}. Use 'rl session save' to save a session first`);
+        throw new Error(`No ${kind ? `${kind} ` : ""}session recorded for ${data.id}. Use 'rl agent save' to save a session first`);
     let selected = choices[0];
     if (choices.length > 1 && !options.latest) {
         const visible = (value) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
@@ -70,7 +70,7 @@ export async function resumeAgent(store, kind, options = {}) {
             ? sessions.find((item) => item.id === sessionId(options.sessionId))
             : sessions.reduce((a, b) => !a || timestamp(b.lastUsedAt) > timestamp(a.lastUsedAt) ? b : a, undefined);
         if (!item)
-            throw new Error(`No ${kind} session recorded for ${data.id}. Use 'rl session save ${kind}${kind === "claude" ? " <UUID>" : ""}'`);
+            throw new Error(`No ${kind} session recorded for ${data.id}. Use 'rl agent save ${kind}${kind === "claude" ? " <UUID>" : ""}'`);
         return [file, data, sessionId(item.id)];
     });
     const stamp = now();

package/dist/bootstrap.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { findExecutable, setupDependencies } from "./dependencies.js";
+import { installRl } from "./install.js";
+import { explicitHelp } from "./help.js";
+const argv = process.argv.slice(2);
+const selected = argv[0] === "--repo"
+    ? argv.slice(2)
+    : argv[0]?.startsWith("--repo=")
+        ? argv.slice(1)
+        : argv;
+if (selected[0] === "setup" &&
+    ["dependencies", "install"].includes(selected[1])) {
+    try {
+        if (selected.includes("--help") || selected.includes("-h"))
+            console.log(explicitHelp(selected));
+        else
+            process.exitCode =
+                selected[1] === "install"
+                    ? await installRl(selected.slice(2))
+                    : await setupDependencies(selected.slice(2));
+    }
+    catch (error) {
+        console.error(`rl: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}
+else if (argv[0] === "--version" || argv[0] === "-V") {
+    console.log(JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+}
+else {
+    const zsh = findExecutable("zsh");
+    if (!zsh) {
+        console.error("rl: zsh is required. Run 'rl setup dependencies' to install the RL toolchain.");
+        process.exitCode = 1;
+    }
+    else {
+        const child = spawn(zsh, [
+            "-f",
+            fileURLToPath(new URL("../lib/entry.zsh", import.meta.url)),
+            ...argv,
+        ], {
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                PATH: `${process.env.PATH ? process.env.PATH + path.delimiter : ""}${path.dirname(process.execPath)}`,
+            },
+        });
+        const interrupt = () => child.kill("SIGINT");
+        const terminate = () => child.kill("SIGTERM");
+        process.on("SIGINT", interrupt);
+        process.on("SIGTERM", terminate);
+        await new Promise((resolve) => {
+            const cleanup = () => {
+                process.off("SIGINT", interrupt);
+                process.off("SIGTERM", terminate);
+            };
+            child.on("error", (error) => {
+                cleanup();
+                console.error(`rl: ${error.message}`);
+                process.exitCode = 1;
+                resolve();
+            });
+            child.on("close", (code, signal) => {
+                cleanup();
+                process.exitCode =
+                    code ?? (signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1);
+                resolve();
+            });
+        });
+    }
+}

package/dist/cli.js

@@ -10,6 +10,7 @@ import { main as git } from "./git-workflow.js";
 import { main as pr } from "./pr-workflow.js";
 import { main as agent } from "./agent-launch.js";
 import { main as mcp } from "./mcp.js";
+import { main as mcpSetup } from "./mcp-setup.js";
 import { main as task } from "./task.js";
 import { main as storage } from "./storage.js";
 import { main as prUpdate } from "./pr-update.js";
@@ -25,6 +26,7 @@ const commands = {
     pr,
     agent,
     mcp,
+    "mcp-setup": mcpSetup,
     task,
     storage,
     "pr-update": prUpdate,

package/dist/command-context.js

@@ -49,7 +49,7 @@ export function resolveWorkspace(context, selector) {
         const [root, branch] = context.store.worktree(context.repo);
         return { path: root, name: "@", branch };
     }
-    const choices = candidates(context.repo, context.managedDir);
+    const choices = candidates(context.repo, context.managedDir, context.store);
     const matches = choices.filter((item) => item.name === selector ||
         item.branch === selector ||
         (path.isAbsolute(selector) && item.path === canonical(selector)));

package/dist/common.js

@@ -6,6 +6,7 @@ import { spawnSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import lockfile from "proper-lockfile";
 import { readJsonObject } from "./json.js";
+import { executableError } from "./dependencies.js";
 export const now = () => new Date().toISOString();
 export const message = (error) => error instanceof Error ? error.message : String(error);
 export const json = (data) => console.log(JSON.stringify(data, null, 2));
@@ -54,7 +55,7 @@ export function run(argv, cwd, raw = false) {
         maxBuffer: 32 * 1024 * 1024,
     });
     if (result.error)
-        throw result.error;
+        throw executableError(result.error, argv[0], cwd);
     if (result.status !== 0)
         throw new Error(result.stderr.trim() || `Command failed: ${argv.join(" ")}`);
     return raw ? result.stdout : result.stdout.trim();
@@ -130,7 +131,7 @@ export async function execute(argv, cwd, options = {}) {
         };
         child.on("error", (error) => {
             cleanup();
-            reject(error);
+            reject(executableError(error, argv[0], cwd));
         });
         child.on("close", (code, signal) => {
             cleanup();

package/dist/dependencies.js

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+export const TOOL_NAMES = ["git", "zsh", "fzf", "gh"];
+export function findExecutable(name, env = process.env) {
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const file = path.resolve(directory, name);
+        try {
+            fs.accessSync(file, fs.constants.X_OK);
+            if (fs.statSync(file).isFile())
+                return file;
+        }
+        catch {
+            /* Try the next PATH entry. */
+        }
+    }
+    return null;
+}
+export function inspectDependencies(env = process.env) {
+    return TOOL_NAMES.map((name) => {
+        const executable = findExecutable(name, env);
+        const probe = executable
+            ? spawnSync(executable, ["--version"], {
+                env,
+                encoding: "utf8",
+                timeout: 5000,
+            })
+            : undefined;
+        return {
+            name,
+            path: executable,
+            available: probe?.status === 0,
+            version: probe?.status === 0
+                ? (probe.stdout.trim().split(/\r?\n/)[0]?.slice(0, 200) ?? null)
+                : null,
+        };
+    });
+}
+function installPlan(missing, host, interactive) {
+    const env = host.env ?? process.env;
+    const platform = host.platform ?? process.platform;
+    const brew = findExecutable("brew", env);
+    if (brew)
+        return [{ executable: brew, args: ["install", ...missing] }];
+    if (platform === "darwin")
+        throw new Error("Homebrew is required to install missing RL tools on macOS. Install it from https://brew.sh, then run 'rl setup dependencies'.");
+    if (platform !== "linux")
+        throw new Error("RL supports macOS and Linux");
+    const managers = [
+        { name: "apt-get", args: ["install", "-y"], packages: missing },
+        { name: "dnf", args: ["install", "-y"], packages: missing },
+        { name: "yum", args: ["install", "-y"], packages: missing },
+        {
+            name: "pacman",
+            args: ["-S", "--needed", "--noconfirm"],
+            packages: missing.map((name) => (name === "gh" ? "github-cli" : name)),
+        },
+        {
+            name: "apk",
+            args: ["add"],
+            packages: missing.map((name) => (name === "gh" ? "github-cli" : name)),
+        },
+    ];
+    for (const manager of managers) {
+        const executable = findExecutable(manager.name, env);
+        if (!executable)
+            continue;
+        const commands = manager.name === "apt-get"
+            ? [
+                { executable, args: ["update"] },
+                { executable, args: [...manager.args, ...manager.packages] },
+            ]
+            : [{ executable, args: [...manager.args, ...manager.packages] }];
+        const uid = host.uid ?? process.getuid?.();
+        if (uid === 0)
+            return commands;
+        const sudo = findExecutable("sudo", env);
+        if (!sudo)
+            throw new Error(`Installing missing RL tools requires administrator access. Run: sudo ${manager.name} ${[...manager.args, ...manager.packages].join(" ")}`);
+        return commands.map((command) => ({
+            executable: sudo,
+            args: [
+                ...(interactive ? [] : ["-n"]),
+                command.executable,
+                ...command.args,
+            ],
+        }));
+    }
+    throw new Error("No supported package manager found. Install Git, zsh, fzf and gh, then run 'rl setup dependencies --check'.");
+}
+export async function setupDependencies(argv, host = {}) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            install: { type: "boolean" },
+            check: { type: "boolean" },
+            "dry-run": { type: "boolean" },
+            json: { type: "boolean" },
+        },
+    });
+    if (positionals.length ||
+        (values.check && (values.install || values["dry-run"])))
+        throw new Error("Usage: rl setup dependencies [--check | --dry-run] [--json]");
+    const env = host.env ?? process.env;
+    let tools = inspectDependencies(env);
+    const missing = tools
+        .filter((tool) => !tool.available)
+        .map((tool) => tool.name);
+    let commands = [];
+    let error;
+    const interactive = !!process.stdin.isTTY && !!process.stdout.isTTY && !values.json;
+    if (missing.length && !values.check) {
+        try {
+            commands = installPlan(missing, host, interactive);
+            if (!values["dry-run"]) {
+                console.error(`RL: installing missing tools: ${missing.join(", ")}`);
+                for (const command of commands) {
+                    const result = spawnSync(command.executable, command.args, {
+                        env: {
+                            ...env,
+                            HOMEBREW_NO_AUTO_UPDATE: "1",
+                            ...(interactive ? {} : { NONINTERACTIVE: "1" }),
+                        },
+                        stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
+                        encoding: "utf8",
+                        maxBuffer: 8 * 1024 * 1024,
+                    });
+                    if (!interactive) {
+                        if (result.stdout)
+                            process.stderr.write(result.stdout);
+                        if (result.stderr)
+                            process.stderr.write(result.stderr);
+                    }
+                    if (result.error || result.status !== 0)
+                        throw new Error(`Could not install RL tools. Run '${command.executable} ${command.args.filter((arg) => arg !== "-n").join(" ")}' in your terminal, then rerun 'rl setup dependencies'.`);
+                }
+                tools = inspectDependencies(env);
+                const remaining = tools
+                    .filter((tool) => !tool.available)
+                    .map((tool) => tool.name);
+                if (remaining.length)
+                    throw new Error(`Tools still unavailable on PATH: ${remaining.join(", ")}. Add the package manager's bin directory to PATH, then rerun 'rl setup dependencies'.`);
+            }
+        }
+        catch (failure) {
+            error = failure instanceof Error ? failure.message : String(failure);
+        }
+    }
+    const ready = tools.every((tool) => tool.available);
+    const report = {
+        ready,
+        dryRun: !!values["dry-run"],
+        tools,
+        commands,
+        ...(error ? { error } : {}),
+    };
+    if (values.json)
+        console.log(JSON.stringify(report, null, 2));
+    else {
+        for (const tool of tools)
+            console.log(`${tool.name}: ${tool.available ? (tool.version ?? "installed") : "missing or not working"}`);
+        if (values["dry-run"])
+            for (const command of commands)
+                console.log(`Would run: ${command.executable} ${command.args.join(" ")}`);
+        if (error)
+            console.error(`RL: ${error}`);
+        else if (!ready && values.check)
+            console.error("Run 'rl setup dependencies' to install missing tools.");
+    }
+    return error ? 1 : values["dry-run"] || ready ? 0 : 1;
+}
+export function executableError(error, executable, cwd) {
+    if (error.code !== "ENOENT")
+        return error;
+    if (!fs.existsSync(cwd))
+        return new Error(`Working directory does not exist: ${cwd}`, {
+            cause: error,
+        });
+    if (TOOL_NAMES.includes(path.basename(executable)))
+        return new Error(`Missing required tool ${path.basename(executable)}. Run 'rl setup dependencies' to install Git, zsh, fzf and gh.`, { cause: error });
+    return error;
+}
+if (process.argv[1] &&
+    path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        process.exitCode = await setupDependencies(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(`RL: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}

package/dist/doctor.js

@@ -126,7 +126,7 @@ export async function doctor(store, selected, asJson = false) {
             console.log(`  CLI: ${item.executablePath ?? "not on PATH"}; launch flags: ${item.launchVerified ? "verified in installed help" : "unverified"}; hook trust: unknown`);
             console.log(`  Last received event: ${item.lastSuccess ? `${item.lastSuccess.event} at ${item.lastSuccess.at}` : "none"}`);
             if (item.missingEvents.length)
-                console.log(`  Missing hooks: ${item.missingEvents.join(", ")}. Run rl adopt.`);
+                console.log(`  Missing hooks: ${item.missingEvents.join(", ")}. Run rl setup adopt.`);
             if (item.configError)
                 console.log(`  Configuration error: ${item.configError}`);
             if (item.cliError)