rl-workspaces 0.0.0-stage → 0.5.0

package/dist/automation-config.js

@@ -0,0 +1,242 @@
+import fs from "node:fs";
+import path from "node:path";
+import { object, writeJson } from "./common.js";
+import { readJsonObject } from "./json.js";
+import { PRESET } from "./agent-presets.js";
+export const CONFIG_FILES = {
+    agents: ".rl/agents.json",
+    policies: ".rl/policies.json",
+    workflows: ".rl/agent-workflows.json",
+};
+export const SEVERITIES = ["critical", "high", "medium", "low"];
+const ID = /^[a-z][a-z0-9_-]{0,63}$/;
+export function identifier(value) {
+    if (typeof value !== "string" ||
+        !ID.test(value) ||
+        value === "constructor" ||
+        value.startsWith("followup-"))
+        throw new Error("Expected an identifier using lowercase letters, numbers, hyphens or underscores");
+}
+export function fields(value, allowed, required = allowed) {
+    if (!object(value) ||
+        Object.keys(value).some((key) => !allowed.includes(key)) ||
+        required.some((key) => !(key in value)))
+        throw new Error(`Expected fields: ${allowed.join(", ")}`);
+}
+function nonempty(value) {
+    if (typeof value !== "string" ||
+        !value.trim() ||
+        value.includes("\0") ||
+        value.length > 64000)
+        throw new Error("Expected nonempty text (up to 64000 characters)");
+}
+function integer(value, min, max) {
+    if (!Number.isInteger(value) || Number(value) < min || Number(value) > max)
+        throw new Error(`Expected an integer from ${min} to ${max}`);
+}
+export function validateAutomation(value) {
+    fields(value, ["agents", "policies", "workflows"]);
+    for (const kind of ["agents", "policies", "workflows"]) {
+        const entries = value[kind];
+        if (!object(entries) ||
+            !Object.keys(entries).length ||
+            Object.keys(entries).length > 64)
+            throw new Error(`Expected 1–64 ${kind}`);
+        for (const [name, item] of Object.entries(entries)) {
+            identifier(name);
+            if (kind === "agents") {
+                fields(item, [
+                    "provider",
+                    "description",
+                    "instructions",
+                    "model",
+                    "reasoning",
+                    "access",
+                ], ["description", "instructions"]);
+                if (item.provider !== undefined &&
+                    !["inherit", "codex", "claude"].includes(String(item.provider)))
+                    throw new Error("Agent provider must be inherit, codex or claude");
+                nonempty(item.description);
+                nonempty(item.instructions);
+                if (item.access !== undefined &&
+                    item.access !== "read-only" &&
+                    item.access !== "workspace-write")
+                    throw new Error("Agent access must be read-only or workspace-write");
+                if (item.model !== undefined) {
+                    nonempty(item.model);
+                    if (item.model.startsWith("-"))
+                        throw new Error("Invalid model");
+                }
+                if (item.reasoning !== undefined &&
+                    !(item.provider !== "claude"
+                        ? ["low", "medium", "high", "xhigh"]
+                        : ["low", "medium", "high", "max"]).includes(String(item.reasoning)))
+                    throw new Error("Unsupported reasoning setting for this provider");
+            }
+            else if (kind === "policies") {
+                fields(item, [
+                    "instructions",
+                    "weights",
+                    "minimumScore",
+                    "blockRequired",
+                ]);
+                nonempty(item.instructions);
+                fields(item.weights, [...SEVERITIES]);
+                for (const weight of Object.values(item.weights))
+                    integer(weight, 0, 100);
+                integer(item.minimumScore, 0, 100);
+                if (typeof item.blockRequired !== "boolean")
+                    throw new Error("blockRequired must be boolean");
+            }
+            else {
+                fields(item, [
+                    "description",
+                    "policy",
+                    "concurrency",
+                    "retries",
+                    "timeoutSeconds",
+                    "steps",
+                    "triggers",
+                ], [
+                    "description",
+                    "policy",
+                    "concurrency",
+                    "retries",
+                    "timeoutSeconds",
+                    "steps",
+                ]);
+                if (item.triggers !== undefined) {
+                    if (!Array.isArray(item.triggers) || item.triggers.length > 32)
+                        throw new Error("Expected up to 32 workflow triggers");
+                    for (const trigger of item.triggers) {
+                        fields(trigger, ["event", "tools", "paths", "changes"], ["event"]);
+                        nonempty(trigger.event);
+                        if (!/^[a-z][a-z0-9_.-]{0,63}$/.test(trigger.event))
+                            throw new Error("Invalid trigger event");
+                        for (const key of ["tools", "paths"])
+                            if (trigger[key] !== undefined &&
+                                (!Array.isArray(trigger[key]) ||
+                                    !trigger[key].length ||
+                                    trigger[key].length > 64 ||
+                                    trigger[key].some((text) => typeof text !== "string" ||
+                                        !text ||
+                                        text.length > 512 ||
+                                        /[\x00-\x1f]/.test(text))))
+                                throw new Error(`Invalid trigger ${key}`);
+                        if (trigger.changes !== undefined &&
+                            typeof trigger.changes !== "boolean")
+                            throw new Error("Trigger changes must be boolean");
+                    }
+                }
+                nonempty(item.description);
+                identifier(item.policy);
+                if (!object(value.policies) ||
+                    !Object.hasOwn(value.policies, item.policy))
+                    throw new Error(`Unknown policy: ${item.policy}`);
+                integer(item.concurrency, 1, 8);
+                integer(item.retries, 0, 3);
+                integer(item.timeoutSeconds, 1, 3600);
+                if (!Array.isArray(item.steps) ||
+                    !item.steps.length ||
+                    item.steps.length > 32)
+                    throw new Error("Expected 1–32 workflow steps");
+                const ids = new Set();
+                for (const step of item.steps) {
+                    fields(step, ["id", "after", "agent", "command"], ["id", "after"]);
+                    identifier(step.id);
+                    if (ids.has(step.id))
+                        throw new Error(`Duplicate step: ${step.id}`);
+                    ids.add(step.id);
+                    if (!Array.isArray(step.after) ||
+                        step.after.some((dep) => typeof dep !== "string") ||
+                        new Set(step.after).size !== step.after.length)
+                        throw new Error("Step after must contain unique step names");
+                    if ((step.agent !== undefined) === (step.command !== undefined))
+                        throw new Error("Each step requires exactly one agent or command");
+                    if (step.agent !== undefined &&
+                        (!object(value.agents) ||
+                            typeof step.agent !== "string" ||
+                            !Object.hasOwn(value.agents, step.agent)))
+                        throw new Error(`Unknown agent: ${step.agent}`);
+                    if (step.command !== undefined &&
+                        (!Array.isArray(step.command) ||
+                            !step.command.length ||
+                            step.command.some((arg) => typeof arg !== "string" || arg.includes("\0")) ||
+                            !step.command[0]))
+                        throw new Error("Commands must be nonempty argv arrays");
+                }
+                const remaining = new Map(item.steps.map((step) => [String(step.id), step.after]));
+                const done = new Set();
+                while (remaining.size) {
+                    const ready = [...remaining].filter(([, deps]) => deps.every((dep) => done.has(dep)));
+                    if (!ready.length)
+                        throw new Error("Workflow dependencies contain a cycle or unknown step");
+                    for (const [id] of ready) {
+                        remaining.delete(id);
+                        done.add(id);
+                    }
+                }
+            }
+        }
+    }
+}
+function configPath(root, relative) {
+    const directory = path.join(root, ".rl"), file = path.join(root, relative);
+    if (fs.lstatSync(directory, { throwIfNoEntry: false })?.isSymbolicLink() ||
+        fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink())
+        throw new Error("Agent configuration must not be a symlink");
+    return file;
+}
+export function readAutomation(root) {
+    const result = {};
+    for (const [kind, relative] of Object.entries(CONFIG_FILES)) {
+        const file = configPath(root, relative);
+        if (!fs.existsSync(file))
+            result[kind] = structuredClone(PRESET[kind]);
+        else {
+            const data = readJsonObject(file);
+            fields(data, ["version", kind]);
+            if (data.version !== 1)
+                throw new Error("Unsupported agent configuration version");
+            result[kind] = data[kind];
+        }
+    }
+    validateAutomation(result);
+    return result;
+}
+export function initAutomation(root, provider) {
+    const paths = Object.values(CONFIG_FILES).map((file) => configPath(root, file));
+    if (paths.some((file) => fs.existsSync(file)))
+        throw new Error("Agent configuration already exists; edit the existing files");
+    const preset = structuredClone(PRESET);
+    for (const profile of Object.values(preset.agents)) {
+        profile.provider = provider;
+        if (provider === "claude")
+            profile.reasoning = "high";
+    }
+    for (const [kind, relative] of Object.entries(CONFIG_FILES))
+        writeJson(configPath(root, relative), {
+            version: 1,
+            [kind]: preset[kind],
+        });
+}
+export function hasAutomation(root) {
+    return Object.values(CONFIG_FILES).some((relative) => fs.existsSync(configPath(root, relative)));
+}
+export function setAutomation(root, kind, name, value, addOnly = false) {
+    identifier(name);
+    const config = readAutomation(root);
+    if (addOnly && Object.hasOwn(config[kind], name))
+        throw new Error(`${name} already exists; use set to update it`);
+    Object.defineProperty(config[kind], name, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+    validateAutomation(config);
+    writeJson(configPath(root, CONFIG_FILES[kind]), {
+        version: 1,
+        [kind]: config[kind],
+    });
+}

package/dist/base.js

@@ -0,0 +1,66 @@
+import { git } from "./common.js";
+/** Resolve cached refs only; never fetch or infer a base from a feature's upstream. */
+export function resolveBase(repo, requested) {
+    const refs = [
+        requested,
+        requested.startsWith("origin/")
+            ? requested.slice(7)
+            : "origin/" + requested,
+    ];
+    for (const ref of refs) {
+        try {
+            return {
+                ref,
+                oid: git(repo, "rev-parse", "--verify", "--end-of-options", ref + "^{commit}"),
+            };
+        }
+        catch {
+            /* Try the corresponding local or remote ref. */
+        }
+    }
+    return null;
+}
+export function repositoryBase(repo, configured) {
+    const configuredBase = resolveBase(repo, configured);
+    if (configuredBase)
+        return configuredBase;
+    try {
+        const head = git(repo, "symbolic-ref", "--short", "refs/remotes/origin/HEAD");
+        const resolved = resolveBase(repo, head);
+        if (resolved)
+            return resolved;
+    }
+    catch {
+        /* A local clone may not have origin/HEAD. */
+    }
+    for (const ref of ["origin/main", "origin/master", "origin/develop"]) {
+        const resolved = resolveBase(repo, ref);
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+/** A PR target is a branch, not a tag or the feature branch's upstream. */
+export function pullRequestBase(repo, pr) {
+    if (typeof pr?.baseRefName !== "string" || !pr.baseRefName)
+        return null;
+    const target = pr.baseRefName;
+    for (const [ref, fullRef] of [
+        [`origin/${target}`, `refs/remotes/origin/${target}`],
+        [target, `refs/heads/${target}`],
+    ]) {
+        try {
+            return {
+                target,
+                resolved: {
+                    ref,
+                    oid: git(repo, "rev-parse", "--verify", "--end-of-options", `${fullRef}^{commit}`),
+                },
+            };
+        }
+        catch {
+            /* The local target branch can exist without a cached remote ref. */
+        }
+    }
+    return { target, resolved: null };
+}

package/dist/cleanup-path.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+/** Metadata, credentials, and task instructions are never cleanup targets. */
+export function protectedCleanupName(name) {
+    return ([
+        ".git",
+        ".rl",
+        ".codex",
+        ".claude",
+        ".ssh",
+        ".aws",
+        ".azure",
+        ".config",
+        ".npmrc",
+        ".yarnrc",
+        ".yarnrc.yml",
+        ".pypirc",
+        ".netrc",
+        "agents.md",
+        "claude.md",
+    ].includes(name.toLowerCase()) ||
+        /^(?:\.env(?:\.|$)|credentials(?:\.|$)|secrets(?:\.|$)|\.rl-clean-)/i.test(name));
+}
+export function validateCleanupPath(value) {
+    if (typeof value !== "string" ||
+        !value ||
+        value.trim() !== value ||
+        path.isAbsolute(value) ||
+        /[\x00-\x1f\x7f\\*?\[\]{}]/.test(value) ||
+        value
+            .split("/")
+            .some((part) => !part || part === "." || part === ".." || protectedCleanupName(part)))
+        throw new Error(`Unsafe cleanup path: ${String(value)}`);
+}

package/dist/cli.js

@@ -0,0 +1,57 @@
+import { message } from "./common.js";
+import { invocation, topicHelp, usageHint } from "./help.js";
+import { main as state } from "./state.js";
+import { main as repos } from "./repos.js";
+import { main as remove } from "./delete.js";
+import { main as summary } from "./summary.js";
+import { main as picker } from "./picker.js";
+import { main as workflow } from "./workflow.js";
+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 task } from "./task.js";
+import { main as storage } from "./storage.js";
+import { main as prUpdate } from "./pr-update.js";
+import { main as agentWorkflows } from "./agent-workflows.js";
+const commands = {
+    state,
+    repos,
+    delete: remove,
+    summary,
+    picker,
+    workflow,
+    git,
+    pr,
+    agent,
+    mcp,
+    task,
+    storage,
+    "pr-update": prUpdate,
+    automation: agentWorkflows,
+};
+try {
+    const [command, ...argv] = process.argv.slice(2);
+    if (!Object.hasOwn(commands, command))
+        throw new Error("Unknown internal command");
+    const separator = argv.indexOf("--");
+    const options = separator < 0 ? argv : argv.slice(0, separator);
+    if (options.includes("--help") || options.includes("-h")) {
+        console.log(topicHelp(invocation(command, options.filter((arg) => arg !== "--help" && arg !== "-h"))));
+    }
+    else {
+        process.exitCode = await commands[command](argv);
+    }
+}
+catch (error) {
+    const detail = message(error).replace("; run rl --help", "");
+    console.error(`rl: ${detail.startsWith("Usage:") ? "Invalid command arguments" : detail}`);
+    const parseError = typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        String(error.code).startsWith("ERR_PARSE_ARGS_");
+    const argumentsError = parseError ||
+        /^(?:Usage:|Invalid command arguments|Unknown option|Missing --|Expected|Unsupported .*option|--.*(?:require|supported|accept))/.test(detail);
+    console.error(usageHint(process.argv[2] ?? "", process.argv.slice(3), argumentsError));
+    process.exitCode = 1;
+}

package/dist/codex-sessions.js

@@ -0,0 +1,188 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { canonical, object, sessionId, timestamp } from "./common.js";
+const SOURCES = ["cli", "vscode", "exec", "appServer"];
+// Ask Codex for workspace-filtered metadata only. Never read transcripts or
+// request a model turn, and never fall back to an unfiltered history query.
+async function discover(cwd, roots) {
+    const child = spawn("codex", ["app-server"], {
+        cwd,
+        stdio: ["pipe", "pipe", "ignore"],
+    });
+    const lines = createInterface({ input: child.stdout });
+    let requestId = 0;
+    let pending;
+    let failure;
+    let bytes = 0;
+    const fail = (error) => {
+        failure = error;
+        pending?.reject(error);
+        pending = undefined;
+        child.kill();
+    };
+    const timer = setTimeout(() => fail(new Error("Codex session discovery timed out")), 3000);
+    child.on("error", fail);
+    child.on("close", () => fail(new Error("Codex session discovery closed")));
+    child.stdin.on("error", fail);
+    child.stdout.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 8 * 1024 * 1024)
+            fail(new Error("Codex session metadata is too large"));
+    });
+    lines.on("line", (line) => {
+        try {
+            const reply = JSON.parse(line);
+            if (!object(reply) || reply.id !== pending?.id || !pending)
+                return;
+            if (reply.error !== undefined || !object(reply.result))
+                throw new Error("Codex rejected session discovery");
+            const request = pending;
+            pending = undefined;
+            request.resolve(reply.result);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+    const request = (method, params) => new Promise((resolve, reject) => {
+        if (failure)
+            return reject(failure);
+        pending = { id: ++requestId, resolve, reject };
+        child.stdin.write(JSON.stringify({ id: requestId, method, params }) + "\n");
+    });
+    try {
+        await request("initialize", { clientInfo: { name: "rl", version: "1" } });
+        child.stdin.write(JSON.stringify({ method: "initialized" }) + "\n");
+        const sessions = [];
+        // A string cwd also works with older app-server versions.
+        for (const root of roots) {
+            let cursor;
+            const cursors = new Set();
+            do {
+                const result = await request("thread/list", {
+                    cwd: root,
+                    useStateDbOnly: true,
+                    sourceKinds: SOURCES,
+                    limit: 100,
+                    ...(cursor ? { cursor } : {}),
+                });
+                if (!Array.isArray(result.data))
+                    throw new Error("Invalid Codex thread list");
+                for (const thread of result.data) {
+                    if (!object(thread) ||
+                        thread.ephemeral === true ||
+                        (thread.source !== undefined &&
+                            (typeof thread.source !== "string" ||
+                                !SOURCES.includes(thread.source))) ||
+                        typeof thread.cwd !== "string" ||
+                        canonical(thread.cwd) !== root)
+                        continue;
+                    // Only UUIDs can be passed unambiguously to the installed resume CLI.
+                    try {
+                        if (typeof thread.createdAt !== "number" ||
+                            typeof thread.updatedAt !== "number")
+                            continue;
+                        const createdAt = new Date(thread.createdAt * 1000).toISOString();
+                        const lastUsedAt = new Date(thread.updatedAt * 1000).toISOString();
+                        sessions.push({
+                            id: sessionId(thread.id),
+                            cwd: root,
+                            createdAt,
+                            lastUsedAt,
+                            branch: object(thread.gitInfo) &&
+                                typeof thread.gitInfo.branch === "string"
+                                ? thread.gitInfo.branch
+                                : undefined,
+                        });
+                    }
+                    catch {
+                        /* Unsupported identifiers or invalid timestamps are not resume targets. */
+                    }
+                }
+                if (result.nextCursor !== null &&
+                    result.nextCursor !== undefined &&
+                    typeof result.nextCursor !== "string")
+                    throw new Error("Invalid Codex thread cursor");
+                cursor = result.nextCursor;
+                if (cursor && cursors.has(cursor))
+                    throw new Error("Repeated Codex thread cursor");
+                if (cursor)
+                    cursors.add(cursor);
+            } while (cursor);
+        }
+        return sessions;
+    }
+    finally {
+        clearTimeout(timer);
+        lines.close();
+        child.stdin.end();
+        child.kill();
+    }
+}
+export async function syncCodexSessions(store, cwd) {
+    const records = await store.locked(() => cwd
+        ? [store.current(cwd)]
+        : store.records().filter(([, data]) => data.status === "active"));
+    const eligible = records.filter(([, data]) => {
+        try {
+            return store.current(data.worktree)[1].key === data.key;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!eligible.length)
+        return;
+    let sessions;
+    try {
+        sessions = await discover(eligible[0][1].worktree, eligible.map(([, data]) => data.worktree));
+    }
+    catch {
+        // Missing/older Codex or a temporarily unavailable server must not hide RL
+        // status or erase already saved sessions. Hooks/manual save still work.
+        return;
+    }
+    await store.locked(() => {
+        for (const [file, snapshot] of eligible) {
+            let current;
+            try {
+                current = store.current(snapshot.worktree);
+            }
+            catch {
+                continue;
+            }
+            const [currentFile, data] = current;
+            if (currentFile !== file || data.key !== snapshot.key)
+                continue;
+            let changed = false;
+            for (const session of sessions) {
+                if (session.cwd !== data.worktree ||
+                    (session.branch !== undefined && session.branch !== data.branch) ||
+                    (session.branch === undefined &&
+                        timestamp(session.createdAt) < timestamp(data.createdAt)))
+                    continue;
+                try {
+                    store.assertSessionOwner(file, "codex", session.id);
+                }
+                catch {
+                    continue;
+                }
+                const saved = data.sessions.codex.find((item) => item.id === session.id);
+                if (!saved) {
+                    data.sessions.codex.push({
+                        id: session.id,
+                        createdAt: session.createdAt,
+                        lastUsedAt: session.lastUsedAt,
+                    });
+                    changed = true;
+                }
+                else if (timestamp(session.lastUsedAt) > timestamp(saved.lastUsedAt)) {
+                    saved.lastUsedAt = session.lastUsedAt;
+                    changed = true;
+                }
+            }
+            if (changed)
+                store.save(file, data);
+        }
+    });
+}

package/dist/command-context.js

@@ -0,0 +1,67 @@
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { canonical, inside, required } from "./common.js";
+import { candidates } from "./picker.js";
+import { Store } from "./store.js";
+export const contextOptions = ["repo", "state-dir", "base-dir", "default-base"];
+export function writeWorkspaceOutput(workspace, output) {
+    if (output === undefined) {
+        console.log(workspace);
+        return;
+    }
+    const target = path.resolve(output);
+    if (!inside(canonical(target), canonical(os.tmpdir())))
+        throw new Error("Shell output file must be inside the temporary directory");
+    const fd = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size !== 0 || stat.nlink !== 1)
+            throw new Error("Shell output file must be an empty regular file");
+        fs.writeFileSync(fd, workspace);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Settings have already been selected by the public CLI's repository router. */
+export function commandContext(values) {
+    const repo = required(values, "repo"), stateDir = required(values, "state-dir"), managedDir = required(values, "base-dir");
+    if (![repo, stateDir, managedDir].every((value) => path.isAbsolute(value)))
+        throw new Error("Repository, state and managed workspace paths must be absolute");
+    const store = new Store(repo, stateDir);
+    return {
+        repo: store.repo,
+        stateDir: store.stateDir,
+        managedDir: canonical(managedDir),
+        defaultBase: String(values["default-base"] ?? "origin/test"),
+        store,
+    };
+}
+/** Resolve only the current checkout or registered managed worktrees, never scan. */
+export function resolveWorkspace(context, selector) {
+    if (!selector) {
+        const [root, branch] = context.store.worktree(process.cwd());
+        return { path: root, name: path.basename(root), branch };
+    }
+    if (selector === "@" ||
+        (path.isAbsolute(selector) && canonical(selector) === context.repo)) {
+        const [root, branch] = context.store.worktree(context.repo);
+        return { path: root, name: "@", branch };
+    }
+    const choices = candidates(context.repo, context.managedDir);
+    const matches = choices.filter((item) => item.name === selector ||
+        item.branch === selector ||
+        (path.isAbsolute(selector) && item.path === canonical(selector)));
+    if (matches.length !== 1)
+        throw new Error(matches.length
+            ? `Ambiguous workspace: ${selector}; use its managed directory name`
+            : `Workspace not found: ${selector}. Use rl list or rl switch --create.`);
+    const item = matches[0];
+    // Revalidate repository identity and branch. Worktree metadata alone can be
+    // stale after the directory has been removed or replaced.
+    const [root, branch] = context.store.worktree(item.path);
+    if (branch !== item.branch)
+        throw new Error("Workspace branch changed during selection; retry the command");
+    return { path: root, name: item.name, branch };
+}