rl-workspaces 0.5.0 → 0.7.0

package/dist/help.js

@@ -21,7 +21,7 @@ const topics = {
         options: [
             "-c, --create          Create a new branch workspace",
             "-b, --base <ref>      Creation base (default: origin/test unless configured)",
-            "--no-fetch           Use cached refs when creating",
+            "--no-fetch           Use cached refs when opening or creating",
             "--setup              Run configured project setup",
             "--agent codex|claude  Start an agent after switching",
             "-- <agent args>      Forward options to the selected agent",
@@ -30,13 +30,13 @@ const topics = {
             "Use rl checkout [repository] to switch repositories in your shell.",
             "@ opens the main checkout; - returns to the previous workspace.",
             "Shell integration changes your terminal's directory.",
-            "Related creation helpers: new reopens existing workspaces; open requires an existing branch.",
+            "An existing branch without a checkout gets a managed workspace; origin branches are tracked.",
         ],
         examples: [
             "rl switch feature/login",
             "rl switch feature/login -c --base origin/test",
         ],
-        related: ["new", "open", "path"],
+        related: ["path"],
     },
     list: {
         group: "Workspaces",
@@ -64,9 +64,9 @@ const topics = {
         notes: [
             "Shows repository selection, checkout path, base, workspaces and saved session counts.",
             "--workspace includes Git changes, PR, sessions, task handoff and latest workflow.",
-            "Use rl list for workspace overviews; status --list and --all remain supported.",
+            "Use rl list for workspace overviews and --include-deleted for archived records.",
         ],
-        related: ["list", "instances"],
+        related: ["list"],
     },
     delete: {
         group: "Workspaces",
@@ -122,6 +122,9 @@ const topics = {
         description: "Configure native agent roles and saved sessions",
         usage: "rl agent <command>",
         related: ["resume", "workflow", "policy"],
+        notes: [
+            "Existing agent sessions discover their workflow with rl workflow context --json. A special launcher or MCP connection is not required.",
+        ],
     },
     "agent start": {
         description: "Start an interactive agent",
@@ -149,6 +152,9 @@ const topics = {
     "agent set": {
         description: "Save an agent profile",
         usage: "rl agent set <name> --file <profile.json|->",
+        notes: [
+            "Use --instructions <file|-> to change instructions while preserving the profile's access, model and other settings.",
+        ],
     },
     "agent show": {
         description: "Inspect a workflow agent profile",
@@ -177,8 +183,11 @@ const topics = {
     },
     "agent mcp": {
         description: "Serve workspace context and notes through MCP",
-        usage: "rl agent mcp",
-        notes: ["Uses stdio. Start the server in the adopted workspace."],
+        usage: "rl agent mcp [--workspace <absolute-path>]",
+        notes: [
+            "Uses stdio. Start the server in the adopted workspace, or bind one explicitly with --workspace.",
+        ],
+        related: ["setup mcp"],
     },
     workflow: {
         group: "Agents and tasks",
@@ -196,7 +205,7 @@ const topics = {
         notes: [
             "Creates .rl/agents.json, .rl/policies.json and .rl/agent-workflows.json.",
             "Existing configuration is never overwritten.",
-            "Roles inherit the current session by default. The preset queues a review before finishing changed work.",
+            "Adopted workspaces use built-in writer/reviewer/DRY roles immediately. Init writes editable copies of their profiles, policy and workflow.",
         ],
     },
     "workflow list": {
@@ -220,22 +229,25 @@ const topics = {
             "--request <UUID>     Start a queued workflow request instead of choosing a name",
         ],
         notes: [
-            "Default workflow: triple-review. RL never launches workflow agent or check processes.",
+            "Default workflow: writer-reviewer-dry. The parent spawns all three native peers in parallel and binds their handles; RL never launches agent processes.",
             "The parent claims ready steps, spawns native subagents and reports evidence. RL applies the policy; provider usage is parent-reported.",
         ],
         examples: ["rl workflow run --base origin/test --dry-run"],
     },
     "workflow add": {
         description: "Add a workflow with dependencies and spawn triggers",
-        usage: "rl workflow add <name> --file <workflow.json|->",
+        usage: "rl workflow add <name> --file <workflow.json|-> [--default]",
     },
     "workflow set": {
         description: "Save a workflow definition and trigger rules",
-        usage: "rl workflow set <name> --file <workflow.json|->",
+        usage: "rl workflow set <name> --file <workflow.json|-> [--default]",
     },
     "workflow context": {
         description: "Discover profiles, policies, workflows and trigger rules",
         usage: "rl workflow context [--json]",
+        notes: [
+            "For an existing agent session: --json includes profiles, policies, workflows, and protocol.tools with every CLI command and input schema. Use your normal shell tool; MCP and rl agent start are optional.",
+        ],
     },
     "workflow pending": {
         description: "Read queued workflows for the parent session",
@@ -257,6 +269,30 @@ const topics = {
         description: "Dismiss an unavailable workflow with a reason",
         usage: "rl workflow dismiss --file <dismissal.json|-> [--agent codex|claude] [--session <UUID>]",
     },
+    "workflow bind": {
+        description: "Bind a role to the native peer spawned by this session",
+        usage: "rl workflow bind <run> --file <binding.json|-> [--agent codex|claude] [--session <UUID>]",
+    },
+    "workflow inbox": {
+        description: "Read a peer's requests, review checkpoints and ratings",
+        usage: "rl workflow inbox <run> --step <step> --claim <token> [--agent codex|claude] [--session <UUID>]",
+    },
+    "workflow consult": {
+        description: "Ask an existing peer through a configured workflow route",
+        usage: "rl workflow consult <run> --file <consultation.json|-> [--agent codex|claude] [--session <UUID>]",
+    },
+    "workflow answer": {
+        description: "Return reuse or duplication evidence to a requesting peer",
+        usage: "rl workflow answer <run> --file <answer.json|-> [--agent codex|claude] [--session <UUID>]",
+    },
+    "workflow submit": {
+        description: "Submit writer work to the existing reviewer",
+        usage: "rl workflow submit <run> --file <submission.json|-> [--agent codex|claude] [--session <UUID>]",
+    },
+    "workflow review": {
+        description: "Return a rating and evidence for a stable writer checkpoint",
+        usage: "rl workflow review <run> --file <review.json|-> [--agent codex|claude] [--session <UUID>]",
+    },
     "workflow status": {
         description: "Inspect a saved run",
         usage: "rl workflow status [UUID|latest] [--json]",
@@ -338,33 +374,9 @@ const topics = {
     },
     git: {
         group: "Code and reviews",
-        description: "Inspect and integrate branch changes",
+        description: "Integrate changes across workspaces",
         usage: "rl git <command>",
     },
-    "git diff": {
-        description: "Show workspace changes against the base",
-        usage: "rl git diff [--base <ref>] [-- <display options> [-- paths...]]",
-        examples: ["rl git diff -- --stat"],
-    },
-    "git log": {
-        description: "Show feature commits",
-        usage: "rl git log [--base <ref>] [-- <display options>]",
-        examples: ["rl git log -- --graph"],
-    },
-    "git commit": {
-        description: "Commit staged changes",
-        usage: "rl git commit -m <message> [--all] [--dry-run]",
-        notes: ["--all includes modified tracked files."],
-    },
-    "git rebase": {
-        description: "Rebase onto the base branch",
-        usage: "rl git rebase [--base <ref>] [--dry-run]",
-    },
-    "git squash": {
-        description: "Squash feature commits",
-        usage: "rl git squash -m <message> [--base <ref>] [--dry-run]",
-        notes: ["The original HEAD is retained under a printed backup ref."],
-    },
     "git merge": {
         description: "Integrate into a checked-out base branch",
         usage: "rl git merge [target] [--squash -m <message>] [--cleanup] [--dry-run]",
@@ -394,10 +406,6 @@ const topics = {
         description: "Refresh the saved PR snapshot",
         usage: "rl pr sync [number|URL] [--json]",
     },
-    "pr checks": {
-        description: "Show GitHub check results",
-        usage: "rl pr checks [--json]",
-    },
     "pr checkout": {
         description: "Create a workspace for a PR",
         usage: "rl pr checkout <number> [--name <branch>]",
@@ -510,6 +518,34 @@ const topics = {
         usage: "rl setup adopt [--extended-hooks]",
         notes: ["Preserves existing hooks. Review Codex hook trust with /hooks."],
     },
+    "setup mcp": {
+        description: "Connect this workspace's RL MCP server to your agent",
+        usage: "rl setup mcp [codex|claude] [--dry-run] [--json]",
+        notes: [
+            "Configures both clients by default: .codex/config.toml and .mcp.json in this adopted workspace.",
+            "Preserves other settings and servers. Existing unmanaged entries named rl require manual resolution.",
+            "Launches the installed Node/RL directly, with this workspace and its RL state bound explicitly. Rerun after moving the installation.",
+            "Reload your client and review its normal project trust/MCP approval. Your existing session creates native subagents.",
+        ],
+    },
+    "setup dependencies": {
+        description: "Install or check Git, zsh, fzf and GitHub CLI",
+        usage: "rl setup dependencies [--check | --dry-run] [--json]",
+        notes: [
+            "npm installation installs missing tools through an existing package manager. This command repairs skipped or failed dependency setup.",
+            "Uses Homebrew on macOS, and Homebrew, APT, DNF, Yum, Pacman or APK on Linux. Administrator access may be required on Linux.",
+            "Runs directly with Node, so it also works before zsh or a repository is available.",
+        ],
+    },
+    "setup install": {
+        description: "Complete or repair RL installation and shell integration",
+        usage: "rl setup install [--shell zsh|bash]",
+        notes: [
+            "Global npm installation runs this automatically: missing Git, zsh, fzf and gh are installed, then your shell startup file is updated.",
+            "Preserves your settings and updates one RL-owned block. New terminals load RL automatically; reload the installing terminal once.",
+            "Use this command after an install with lifecycle scripts disabled, or to repair setup.",
+        ],
+    },
     "setup shell": {
         description: "Print shell integration",
         usage: "rl setup shell <zsh|bash>",
@@ -524,16 +560,6 @@ const topics = {
             "--repair reinstalls this workspace's RL hooks.",
         ],
     },
-    new: {
-        description: "Create or reopen a branch workspace",
-        usage: "rl new <branch> [--base <ref>] [--no-fetch] [--setup]",
-        related: ["switch"],
-    },
-    open: {
-        description: "Open an existing local or origin branch",
-        usage: "rl open --branch <branch> [--setup] [--no-fetch]",
-        related: ["switch"],
-    },
     path: {
         description: "Print a workspace path",
         usage: "rl path [name|branch|@]",
@@ -544,55 +570,7 @@ const topics = {
         usage: "rl exec [--workspace <name>] -- <command> [args...]",
         related: ["setup run"],
     },
-    instances: {
-        description: "Inspect active and archived instance records",
-        usage: "rl instances",
-        related: ["status", "list"],
-    },
 };
-const aliases = [
-    [["step"], ["git"]],
-    [["diff"], ["git", "diff"]],
-    [["log"], ["git", "log"]],
-    [["merge"], ["git", "merge"]],
-    [["clean"], ["storage", "clean"]],
-    [["summary"], ["notes", "summary"]],
-    [["handoff"], ["agent", "handoff"]],
-    [["mcp"], ["agent", "mcp"]],
-    [
-        ["session", "list"],
-        ["agent", "sessions"],
-    ],
-    [
-        ["session", "save"],
-        ["agent", "save"],
-    ],
-    [
-        ["session", "add"],
-        ["agent", "save"],
-    ],
-    [["session"], ["agent"]],
-    [
-        ["config", "init"],
-        ["setup", "init"],
-    ],
-    [
-        ["config", "show"],
-        ["setup", "show"],
-    ],
-    [["config"], ["setup"]],
-    [["adopt"], ["setup", "adopt"]],
-    [["init"], ["setup", "shell"]],
-];
-function canonical(words) {
-    if (words[0] === "status" &&
-        words.some((word) => word === "--all" || word === "--list"))
-        return ["list", ...words.slice(1)];
-    if (["context", "progress"].includes(words[0]))
-        return ["notes", words[1] ?? "show", words[0], ...words.slice(2)];
-    const alias = aliases.find(([from]) => from.every((word, i) => words[i] === word));
-    return alias ? [...alias[1], ...words.slice(alias[0].length)] : words;
-}
 const children = (name) => Object.entries(topics).filter(([key]) => key.startsWith(name + " ") &&
     key.split(" ").length === name.split(" ").length + 1);
 const safe = (value) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
@@ -625,9 +603,8 @@ function match(words) {
 export function topicHelp(words) {
     if (!words.length)
         return mainHelp();
-    const normalized = canonical(words), name = match(normalized);
-    if (!name ||
-        (children(name).length && normalized.length > name.split(" ").length))
+    const name = match(words);
+    if (!name || (children(name).length && words.length > name.split(" ").length))
         throw new Error(`Unknown help topic: ${safe(words.join(" "))}`);
     const topic = topics[name];
     const lines = [topic.description, "", `Usage: ${topic.usage}`];
@@ -666,28 +643,48 @@ export function invocation(module, argv) {
     while (argv[index]?.startsWith("--") && CONTEXT.has(argv[index].slice(2)))
         index += 2;
     const rest = argv.slice(index);
-    const prefix = {
-        delete: ["delete"],
-        summary: ["summary"],
-        mcp: ["mcp"],
-        picker: [],
-    };
-    const words = Object.hasOwn(prefix, module)
-        ? [...prefix[module], ...rest]
-        : module === "agent" && rest[0] !== "handoff"
-            ? ["agent", ...rest]
-            : rest;
+    if (module === "summary")
+        return ["notes", "summary", ...rest];
+    if (module === "mcp")
+        return ["agent", "mcp", ...rest];
+    if (module === "mcp-setup")
+        return ["setup", "mcp", ...rest];
+    if (module === "delete")
+        return ["delete", ...rest];
+    if (module === "picker")
+        return [];
+    if (module === "agent")
+        return ["agent", ...rest];
+    if (module === "git")
+        return ["git", ...rest];
+    if (module === "storage")
+        return rest[0] === "clean" ? ["storage", ...rest] : rest;
+    if (module === "workflow" && rest[0] === "config")
+        return ["setup", ...rest.slice(1)];
+    if (module === "state") {
+        if (rest[0] === "session")
+            return [
+                "agent",
+                rest[1] === "list" ? "sessions" : "save",
+                ...rest.slice(2),
+            ];
+        if (rest[0] === "adopt")
+            return ["setup", ...rest];
+        if (["context", "progress"].includes(rest[0]))
+            return ["notes", rest[1] ?? "show", rest[0], ...rest.slice(2)];
+    }
+    if (module === "repos" &&
+        rest[0] === "status" &&
+        rest.some((word) => word === "--all" || word === "--list"))
+        return ["list", ...rest.slice(1)];
     const defaults = {
         state: "status",
         repos: "repo",
         workflow: "switch",
-        git: "git",
-        agent: "agent",
         automation: "workflow",
-        storage: "storage",
         "pr-update": "pr",
     };
-    return canonical(words.length ? words : defaults[module] ? [defaults[module]] : []);
+    return rest.length ? rest : defaults[module] ? [defaults[module]] : [];
 }
 export function usageHint(module, argv, details = false) {
     const words = invocation(module, argv), name = match(words);

package/dist/hooks.js

@@ -21,7 +21,7 @@ export async function handleHook(store, key, name) {
         // cannot change the original instance or the destination instance.
         const [file, data] = store.instanceForWorktree(root, git(root, "branch", "--show-current"));
         if (data.key !== key)
-            throw new Error("Hook belongs to a different RL instance; run 'rl adopt' to repair it");
+            throw new Error("Hook belongs to a different RL instance; run 'rl setup adopt' to repair it");
         try {
             const event = adapter.parse(payload);
             // Workflow workers are ephemeral. Supply task context without turning a

package/dist/install.js

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { atomicWrite, canonical, inside, shellQuote } from "./common.js";
+import { inspectDependencies, setupDependencies } from "./dependencies.js";
+const BEGIN = "# >>> rl shell integration >>>";
+const END = "# <<< rl shell integration <<<";
+const SHIM = "#!/bin/sh\n# Managed by RL installation\n";
+function profileChange(home, requested, after) {
+    const file = canonical(requested);
+    if (!inside(file, home))
+        throw new Error(`Shell setup path must stay in your home directory: ${requested}`);
+    const stat = fs.statSync(file, { throwIfNoEntry: false });
+    if (stat && (!stat.isFile() || stat.size > 1024 * 1024))
+        throw new Error(`Expected a shell setup file up to 1 MiB: ${requested}`);
+    const before = stat ? fs.readFileSync(file, "utf8") : undefined;
+    return {
+        file,
+        before,
+        after: after(before ?? ""),
+        ...(stat ? { mode: stat.mode & 0o777 } : {}),
+    };
+}
+function integration(text, block, shell) {
+    const lines = text.split(/\r?\n/);
+    const starts = lines.flatMap((line, index) => line === BEGIN ? [index] : []);
+    const ends = lines.flatMap((line, index) => (line === END ? [index] : []));
+    if (starts.length || ends.length) {
+        if (starts.length !== 1 || ends.length !== 1 || starts[0] >= ends[0])
+            throw new Error("Malformed RL shell integration block; preserve your settings and repair its markers before reinstalling");
+        const prefix = lines.slice(0, starts[0]).join("\n");
+        const suffix = lines.slice(ends[0] + 1).join("\n");
+        return (prefix ? prefix + "\n" : "") + block + "\n" + suffix;
+    }
+    const existing = lines.findIndex((line) => [
+        `eval "$(rl setup shell ${shell})"`,
+        `eval "$(command rl setup shell ${shell})"`,
+        `eval "$(rl init ${shell})"`,
+        `eval "$(command rl init ${shell})"`,
+    ].includes(line.trim()));
+    if (existing >= 0) {
+        lines[existing] = block;
+        return lines.join("\n");
+    }
+    return (text + (text ? (text.endsWith("\n") ? "\n" : "\n\n") : "") + block + "\n");
+}
+export function configureShell(host, requestedShell) {
+    const env = host.env ?? process.env;
+    const home = canonical(host.home ?? os.homedir());
+    const shell = requestedShell ??
+        path.basename(env.SHELL ??
+            ((host.platform ?? process.platform) === "darwin" ? "zsh" : "bash"));
+    if (shell !== "zsh" && shell !== "bash")
+        throw new Error(`Automatic RL shell setup supports zsh and bash. Run 'rl setup install --shell zsh' or '--shell bash' for the shell you use.`);
+    const root = host.packageRoot ?? fileURLToPath(new URL("..", import.meta.url));
+    const node = host.node ?? process.execPath;
+    const executable = path.join(root, "bin/rl");
+    const shimDirectory = path.join(home, ".local/share/rl/bin");
+    const shim = profileChange(home, path.join(shimDirectory, "rl"), (before) => {
+        if (before && !before.startsWith(SHIM))
+            throw new Error("The RL installation shim already contains an unmanaged command; it was not replaced");
+        return `${SHIM}exec ${shellQuote(node)} ${shellQuote(executable)} "$@"\n`;
+    });
+    shim.mode = 0o755;
+    const toolDirectories = [
+        ...new Set([
+            path.dirname(node),
+            ...inspectDependencies(env).flatMap((tool) => tool.path ? [path.dirname(tool.path)] : []),
+        ]),
+    ];
+    const block = [
+        BEGIN,
+        `export PATH=${shellQuote(shimDirectory)}:"$PATH":${toolDirectories.map(shellQuote).join(":")}`,
+        `eval "$(${shellQuote(node)} ${shellQuote(executable)} setup shell ${shell})"`,
+        END,
+    ].join("\n");
+    const targets = [
+        path.join(shell === "zsh" && env.ZDOTDIR ? path.resolve(home, env.ZDOTDIR) : home, shell === "zsh" ? ".zshrc" : ".bashrc"),
+    ];
+    if (shell === "bash") {
+        const login = [".bash_profile", ".bash_login", ".profile"]
+            .map((name) => path.join(home, name))
+            .find((file) => fs.existsSync(file));
+        targets.push(login ?? path.join(home, ".bash_profile"));
+    }
+    const profiles = targets.map((file) => profileChange(home, file, (text) => integration(text, block, shell)));
+    const changes = [
+        ...new Map([shim, ...profiles].map((change) => [change.file, change])).values(),
+    ];
+    for (const change of changes) {
+        const current = fs.existsSync(change.file)
+            ? fs.readFileSync(change.file, "utf8")
+            : undefined;
+        if (current !== change.before)
+            throw new Error("Shell configuration changed during installation; retry");
+    }
+    for (const change of changes) {
+        if (change.before !== change.after)
+            atomicWrite(change.file, change.after);
+        if (change.mode !== undefined)
+            fs.chmodSync(change.file, change.mode);
+    }
+    return {
+        shell,
+        profiles: profiles.map((change) => change.file),
+        shim: shim.file,
+    };
+}
+export async function installRl(argv, host = {}) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: { shell: { type: "string" } },
+        allowPositionals: true,
+    });
+    if (positionals.length)
+        throw new Error("Usage: rl setup install [--shell zsh|bash]");
+    const env = host.env ?? process.env;
+    if (env.npm_lifecycle_event === "postinstall" &&
+        env.npm_config_global !== "true") {
+        console.log("RL checkout installed. Run 'rl setup install' to install system tools and register shell integration.");
+        return 0;
+    }
+    const code = await setupDependencies([], host);
+    if (code)
+        return code;
+    const configured = configureShell(host, values.shell);
+    console.log(`RL shell integration installed in ${configured.profiles.join(", ")}.`);
+    console.log("New terminals can use rl directly. To activate directory switching in this terminal now, run:");
+    console.log(`  eval "$(${shellQuote(configured.shim)} setup shell ${configured.shell})"`);
+    return 0;
+}
+if (process.argv[1] &&
+    path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        process.exitCode = await installRl(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(`RL installation: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}