rl-workspaces 0.0.0-stage → 0.5.0

package/dist/state.js

@@ -0,0 +1,250 @@
+import { agentAdapter } from "./agent-registry.js";
+import { activityView } from "./activity.js";
+import { handleHook } from "./hooks.js";
+import { doctor } from "./doctor.js";
+import { currentSessionId } from "./session.js";
+import { syncCodexSessions } from "./codex-sessions.js";
+import { resumeSessions } from "./agent-resume.js";
+import { workflowSummary } from "./agent-runner.js";
+import { github } from "./pr-workflow.js";
+import { prText, statusText } from "./display.js";
+import fs from "node:fs";
+import path from "node:path";
+import { args, arity, canonical, git, json, message, now, object, required, run, } from "./common.js";
+import { branchStatus, Store } from "./store.js";
+function agent(value) {
+    return agentAdapter(value).name;
+}
+async function syncPr(store, requested, asJson = false) {
+    const [file, data] = await store.locked(() => store.current());
+    const selector = requested || data.pr?.url || data.branch;
+    if (selector.startsWith("-"))
+        throw new Error("PR selector must be a branch, number, or URL");
+    const repository = JSON.parse(run(["gh", "repo", "view", "--json", "nameWithOwner,url"], data.worktree));
+    if (!object(repository) || typeof repository.url !== "string")
+        throw new Error("GitHub returned invalid repository metadata");
+    const repoUrl = repository.url.replace(/\/+$/, ""), parsed = new URL(repoUrl);
+    if (parsed.protocol !== "https:" ||
+        !parsed.host ||
+        !parsed.pathname.replaceAll("/", ""))
+        throw new Error("GitHub returned an invalid repository URL");
+    const prefix = repoUrl + "/pull/";
+    if (selector.includes("://") && !selector.startsWith(prefix))
+        throw new Error("PR URL does not belong to this GitHub repository");
+    const fields = "number,url,state,title,headRefName,baseRefName,isDraft,updatedAt";
+    const pr = JSON.parse(run([
+        "gh",
+        "pr",
+        "view",
+        selector,
+        "--repo",
+        parsed.host + parsed.pathname,
+        "--json",
+        fields,
+    ], data.worktree));
+    if (!object(pr) || fields.split(",").some((field) => !(field in pr)))
+        throw new Error("GitHub returned incomplete PR metadata");
+    if (pr.headRefName !== data.branch)
+        throw new Error("PR head branch does not match the RL instance branch");
+    if (typeof pr.url !== "string" || !pr.url.startsWith(prefix))
+        throw new Error("PR does not belong to this GitHub repository");
+    pr.syncedAt = now();
+    await store.locked(() => {
+        const [currentFile, current] = store.current(data.worktree);
+        if (currentFile !== file)
+            throw new Error("Instance changed while fetching PR state");
+        current.pr = pr;
+        store.save(file, current);
+    });
+    if (asJson)
+        json(pr);
+    else
+        console.log(prText(pr));
+    return 0;
+}
+async function openPr(store, asJson) {
+    const [, data] = await store.locked(() => store.current());
+    if (asJson) {
+        json(data.pr);
+        return 0;
+    }
+    if (data.pr) {
+        const url = new URL(data.pr.url);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            !/\/pull\/[1-9]\d*$/.test(url.pathname))
+            throw new Error("Invalid saved PR URL; run rl pr sync to refresh");
+        console.log(prText(data.pr));
+    }
+    else
+        console.log(`Opening PR for ${data.branch}…`);
+    try {
+        const result = await github(data.worktree, [
+            "pr",
+            "view",
+            data.pr?.url ?? data.branch,
+            "--web",
+        ]);
+        if (result.code)
+            throw new Error(result.stderr.trim() || "Could not open PR in the browser");
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        return 0;
+    }
+    catch (error) {
+        if (!data.pr)
+            throw error;
+        console.error(`Could not open the browser: ${message(error)}. Use the PR link above.`);
+        return 0;
+    }
+}
+export async function main(argv) {
+    const { values, positionals } = args(argv, ["repo", "state-dir", "worktree", "base"], [
+        "quiet",
+        "fetch",
+        "json",
+        "repair",
+        "extended-hooks",
+        "latest",
+        "l",
+        "workspace",
+    ], { latest: "l" });
+    const store = new Store(required(values, "repo"), required(values, "state-dir"));
+    const [command, ...rest] = positionals;
+    if ((values.latest || values.l) && command !== "resume")
+        throw new Error("--latest is only supported by rl resume");
+    if (command === "adopt") {
+        arity(rest, 0);
+        const [file, data] = await store.adopt(String(values.worktree ?? "."), typeof values.base === "string" ? values.base : undefined, values["extended-hooks"] ? true : undefined);
+        if (!values.quiet)
+            console.log(`RL instance: ${data.id}\nState: ${path.dirname(file)}\nSession hooks installed. In Codex, review and trust them with /hooks.`);
+        return 0;
+    }
+    if (command === "resume") {
+        arity(rest, 0, 1);
+        return resumeSessions(store, rest[0] === undefined ? undefined : agent(rest[0]), { latest: !!(values.latest || values.l) });
+    }
+    if (command === "doctor") {
+        arity(rest, 0, 1);
+        if (values.repair) {
+            const [, data] = store.current();
+            await store.adopt(data.worktree);
+        }
+        return doctor(store, rest[0], !!values.json);
+    }
+    if (command === "hook") {
+        arity(rest, 2);
+        return handleHook(store, rest[0], rest[1]);
+    }
+    if (command === "pr" && rest[0] === "sync") {
+        arity(rest, 1, 2);
+        return syncPr(store, rest[1], !!values.json);
+    }
+    if (command === "pr" && (!rest.length || rest[0] === "open")) {
+        arity(rest, 0, rest[0] === "open" ? 1 : 0);
+        return openPr(store, !!values.json);
+    }
+    if (command === "status" || command === "instances")
+        arity(rest, 0);
+    if (command === "session" && rest[0] === "list") {
+        arity(rest, 1, 2);
+        if (rest[1])
+            agent(rest[1]);
+    }
+    if (command === "status" && values.fetch)
+        git(store.repo, "fetch", "--all", "--prune");
+    if (command === "status" ||
+        command === "instances" ||
+        (command === "session" && rest[0] === "list"))
+        await syncCodexSessions(store, command === "instances" ? undefined : process.cwd());
+    let replacement = "";
+    if (["context", "progress"].includes(command) &&
+        ["set", "append"].includes(rest[0])) {
+        arity(rest, 2);
+        replacement = fs.readFileSync(rest[1] === "-" ? 0 : rest[1], "utf8");
+    }
+    return store.locked(() => {
+        if (command === "instances") {
+            arity(rest, 0);
+            json(store.records().map(([, data]) => ({
+                ...data,
+                gitStatus: branchStatus(store.repo, data),
+            })));
+            return 0;
+        }
+        if (command === "archive") {
+            arity(rest, 0);
+            const root = canonical(required(values, "worktree"));
+            store.archiveWorktrees([root]);
+            return 0;
+        }
+        const [file, data] = store.current();
+        if (command === "status") {
+            arity(rest, 0);
+            const status = {
+                ...data,
+                activity: {
+                    codex: activityView(data.activity?.codex),
+                    claude: activityView(data.activity?.claude),
+                },
+                stateDirectory: path.dirname(file),
+                gitStatus: branchStatus(store.repo, data),
+                workflow: workflowSummary(store),
+            };
+            if (values.json)
+                json(status);
+            else
+                console.log(statusText(data, status.gitStatus, status.workflow));
+        }
+        else if (command === "session") {
+            if (rest[0] === "save") {
+                arity(rest, 1, 3);
+                const kind = agent(rest[1] ?? "codex");
+                const sid = currentSessionId(kind, rest[2]);
+                store.recordSession(file, data, kind, sid);
+                if (values.json)
+                    json({ agent: kind, sessionId: sid, instance: data.id });
+                else
+                    console.log(`Saved ${kind} session ${sid} for ${data.id}`);
+            }
+            else if (rest[0] === "add") {
+                arity(rest, 3);
+                const kind = agent(rest[1]);
+                store.recordSession(file, data, kind, rest[2]);
+                console.log(`Associated ${kind} session ${rest[2]} with ${data.id}`);
+            }
+            else if (rest[0] === "list") {
+                arity(rest, 1, 2);
+                json(rest[1] ? data.sessions[agent(rest[1])] : data.sessions);
+            }
+            else
+                throw new Error("Usage: rl session list [agent] | save [agent] [UUID] | add <agent> <UUID>");
+        }
+        else if (command === "context" || command === "progress") {
+            const target = path.join(path.dirname(file), command + ".md"), action = rest[0];
+            if (action === "path" || action === "show") {
+                arity(rest, 1);
+                if (action === "path")
+                    console.log(target);
+                else
+                    process.stdout.write(store.readDocument(file, command));
+            }
+            else if (action === "set" || action === "append") {
+                store.updateDocument(file, data, command, action, replacement);
+            }
+            else
+                throw new Error(`Usage: rl ${command} show|path|set <file>|append <file>`);
+        }
+        else if (command === "pr" && rest[0] === "show") {
+            arity(rest, 1);
+            if (values.json)
+                json(data.pr);
+            else
+                console.log(prText(data.pr));
+        }
+        else
+            throw new Error("Unknown state command");
+        return 0;
+    });
+}

package/dist/storage.js

@@ -0,0 +1,366 @@
+import fs from "node:fs";
+import path from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { args, arity, canonical, git, inside, json, locked, message, } from "./common.js";
+import { commandContext, contextOptions } from "./command-context.js";
+import { lastAccessed } from "./access.js";
+import { protectedCleanupName } from "./cleanup-path.js";
+import { containedPath, readWorkflowConfig } from "./workflow-config.js";
+import { assertReady, GIT_WORKFLOW_DIRECTORY, GIT_WORKFLOW_LOCK, } from "./git-safety.js";
+const DEPENDENCIES = new Set(["node_modules", ".venv", "venv"]);
+const BUILDS = new Set([
+    ".next",
+    ".nuxt",
+    ".turbo",
+    ".cache",
+    "dist",
+    "build",
+    "coverage",
+    ".vite",
+    "out",
+    "target",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".parcel-cache",
+    ".svelte-kit",
+]);
+const visible = (value) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+function size(bytes) {
+    const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+    let i = 0;
+    while (bytes >= 1024 && i < units.length - 1) {
+        bytes /= 1024;
+        i++;
+    }
+    return `${i ? bytes.toFixed(1) : bytes} ${units[i]}`;
+}
+function category(relative, clean) {
+    const parts = relative.split(path.sep);
+    if (parts.some((part) => DEPENDENCIES.has(part)))
+        return "dependenciesBytes";
+    if (parts.some((part) => BUILDS.has(part)) ||
+        clean.some((item) => relative === item || relative.startsWith(item + path.sep)))
+        return "buildsBytes";
+    return "otherBytes";
+}
+/** Read only this directory tree. Never follow symlinks or enter Git metadata. */
+function measure(roots, clean, protect = false) {
+    const usage = {
+        allocatedBytes: 0,
+        logicalBytes: 0,
+        estimatedBytes: 0,
+        dependenciesBytes: 0,
+        buildsBytes: 0,
+        otherBytes: 0,
+        files: 0,
+        symlinks: 0,
+        largestPaths: [],
+    };
+    const largest = new Map();
+    const links = new Map();
+    const pending = [...roots];
+    while (pending.length) {
+        const item = pending.pop();
+        const name = path.basename(item.path);
+        if (protect && protectedCleanupName(name))
+            throw new Error(`Cleanup contains protected metadata or credentials: ${item.relative}`);
+        if (!protect && name === ".git")
+            continue;
+        const stat = fs.lstatSync(item.path);
+        const bytes = stat.blocks * 512;
+        const kind = category(item.relative, clean);
+        let counted = true;
+        if (stat.isDirectory()) {
+            for (const child of fs.readdirSync(item.path).sort().reverse())
+                pending.push({
+                    path: path.join(item.path, child),
+                    relative: path.join(item.relative, child),
+                });
+            usage.estimatedBytes += bytes;
+        }
+        else if (stat.isFile() || stat.isSymbolicLink()) {
+            if (stat.isSymbolicLink())
+                usage.symlinks++;
+            else
+                usage.files++;
+            usage.logicalBytes += stat.size;
+            if (stat.nlink > 1) {
+                const key = `${stat.dev}:${stat.ino}`;
+                const previous = links.get(key);
+                if (previous) {
+                    previous.seen++;
+                    counted = false;
+                }
+                else
+                    links.set(key, { bytes, seen: 1, count: stat.nlink });
+            }
+            else
+                usage.estimatedBytes += bytes;
+        }
+        else if (protect)
+            throw new Error(`Cleanup contains a special file: ${item.relative}`);
+        if (counted) {
+            usage.allocatedBytes += bytes;
+            usage[kind] += bytes;
+            const top = item.relative.split(path.sep)[0];
+            if (top)
+                largest.set(top, (largest.get(top) ?? 0) + bytes);
+        }
+    }
+    for (const link of links.values())
+        if (link.seen >= link.count)
+            usage.estimatedBytes += link.bytes;
+    usage.largestPaths = [...largest]
+        .map(([path, allocatedBytes]) => ({ path, allocatedBytes }))
+        .sort((a, b) => b.allocatedBytes - a.allocatedBytes || a.path.localeCompare(b.path));
+    return usage;
+}
+function roots(clean) {
+    const sorted = [...new Set(clean)].sort((a, b) => a.length - b.length || a.localeCompare(b));
+    return sorted.filter((item, index) => !sorted.slice(0, index).some((parent) => item.startsWith(parent + "/")));
+}
+function validateIgnored(workspace, relative) {
+    if (git(workspace, "--literal-pathspecs", "ls-files", "--cached", "-z", "--", relative))
+        throw new Error(`Cleanup path contains tracked files: ${relative}`);
+    try {
+        git(workspace, "check-ignore", "--no-index", "--", relative + "/");
+    }
+    catch {
+        throw new Error(`Cleanup path must be ignored by Git: ${relative}`);
+    }
+    if (git(workspace, "--literal-pathspecs", "ls-files", "--others", "--exclude-standard", "-z", "--", relative))
+        throw new Error(`Cleanup path contains non-ignored files: ${relative}`);
+}
+function plan(workspace, clean) {
+    return roots(clean).flatMap((relative) => {
+        const target = containedPath(workspace, relative);
+        if (!fs.existsSync(target))
+            return [];
+        const stat = fs.lstatSync(target);
+        if (!stat.isDirectory())
+            throw new Error(`Cleanup target must be a directory: ${relative}`);
+        validateIgnored(workspace, relative);
+        const cwd = canonical(process.cwd());
+        if (cwd === target || inside(cwd, target))
+            throw new Error(`Cleanup would remove the current directory: ${relative}. Change to the workspace root first`);
+        return [
+            {
+                path: target,
+                relative,
+                dev: stat.dev,
+                ino: stat.ino,
+                usage: measure([{ path: target, relative }], clean, true),
+            },
+        ];
+    });
+}
+function verifyTarget(workspace, target) {
+    const current = containedPath(workspace, target.relative);
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.dev !== target.dev || stat.ino !== target.ino)
+        throw new Error(`Cleanup directory changed during inspection: ${target.relative}`);
+    validateIgnored(workspace, target.relative);
+}
+/** Stage within the current workspace before deletion; validation failures restore artifacts. */
+function remove(workspace, targets, recheck) {
+    const holding = fs.mkdtempSync(path.join(workspace, ".rl-clean-"));
+    const holdingIdentity = fs.lstatSync(holding);
+    const holdingValid = () => {
+        try {
+            const current = fs.lstatSync(holding);
+            return (current.isDirectory() &&
+                current.dev === holdingIdentity.dev &&
+                current.ino === holdingIdentity.ino &&
+                canonical(holding) === holding);
+        }
+        catch {
+            return false;
+        }
+    };
+    const staged = [];
+    const removed = [];
+    try {
+        for (const target of targets) {
+            recheck();
+            verifyTarget(workspace, target);
+            const destination = path.join(holding, String(staged.length));
+            fs.renameSync(target.path, destination);
+            staged.push({ target, path: destination });
+            const stat = fs.lstatSync(destination);
+            if (stat.dev !== target.dev ||
+                stat.ino !== target.ino ||
+                !stat.isDirectory())
+                throw new Error("Cleanup directory changed while staging");
+            // Recheck credentials/metadata added while the initial plan was being built.
+            measure([{ path: destination, relative: target.relative }], [], true);
+        }
+        recheck();
+        for (const item of staged)
+            validateIgnored(workspace, item.target.relative);
+        for (const item of staged) {
+            recheck();
+            if (!holdingValid())
+                throw new Error("Cleanup staging directory changed");
+            const stagedIdentity = fs.lstatSync(item.path);
+            if (!stagedIdentity.isDirectory() ||
+                stagedIdentity.dev !== item.target.dev ||
+                stagedIdentity.ino !== item.target.ino)
+                throw new Error("Cleanup artifact changed before removal");
+            fs.rmSync(item.path, { recursive: true });
+            removed.push(item.target.relative);
+        }
+        return removed;
+    }
+    catch (error) {
+        // A replaced staging path must never redirect rollback into another directory.
+        if (!holdingValid())
+            throw new Error(`${message(error)}. Staging path changed; inspect retained artifacts in the current workspace`);
+        for (const item of staged.reverse()) {
+            if (!fs.existsSync(item.path))
+                continue;
+            try {
+                containedPath(workspace, item.target.relative);
+                if (!fs.existsSync(item.target.path))
+                    fs.renameSync(item.path, item.target.path);
+            }
+            catch {
+                /* Preserve artifacts in the staging directory on restore failure. */
+            }
+        }
+        throw new Error(`${message(error)}${fs.readdirSync(holding).length ? `. Remaining artifacts retained at ${holding}` : ""}`);
+    }
+    finally {
+        if (holdingValid() && !fs.readdirSync(holding).length)
+            fs.rmdirSync(holding);
+    }
+}
+function suggestions(data, usage, estimatedBytes, days) {
+    const result = [];
+    if (estimatedBytes)
+        result.push(`Run rl clean --dry-run to preview ${size(estimatedBytes)} of configured generated files.`);
+    else if (usage.dependenciesBytes || usage.buildsBytes)
+        result.push("Add generated directory paths to the clean list in this workspace's .rl/workflows.json.");
+    const accessed = lastAccessed(data);
+    if (accessed && Date.now() - Date.parse(accessed) >= days * 86_400_000)
+        result.push(`This workspace has not been used for at least ${days} days.`);
+    if (String(data.pr?.state).toUpperCase() === "MERGED")
+        result.push("The cached PR is merged. Consider deleting this workspace when finished.");
+    return result;
+}
+export async function main(argv) {
+    const { values, positionals } = args(argv, [...contextOptions, "older-than"], ["json", "dry-run"]);
+    const [command, ...rest] = positionals;
+    arity(rest, 0);
+    if (!["storage", "clean"].includes(command) ||
+        (command === "storage" && values["dry-run"]) ||
+        (command === "clean" && values["older-than"] !== undefined))
+        throw new Error("Usage: rl storage [--json] [--older-than 14d] | rl clean [--dry-run] [--json] (current workspace only)");
+    const context = commandContext(values);
+    // Resolve from the caller's cwd before any scan, lock creation, or mutation.
+    const [file, data] = context.store.current();
+    const workspaceIdentity = fs.lstatSync(data.worktree);
+    const clean = readWorkflowConfig(data.worktree).clean;
+    const workspace = { id: data.id, branch: data.branch, path: data.worktree };
+    const days = Number(String(values["older-than"] ?? "14d").replace(/d$/, ""));
+    if (!Number.isInteger(days) || days < 1 || days > 36500)
+        throw new Error("--older-than must be a positive number of days, such as 14d");
+    if (command === "storage") {
+        const usage = measure(fs.readdirSync(data.worktree).map((name) => ({
+            path: path.join(data.worktree, name),
+            relative: name,
+        })), clean);
+        let targets = [], cleanupError = null;
+        try {
+            targets = plan(data.worktree, clean);
+        }
+        catch (error) {
+            cleanupError = message(error);
+        }
+        const estimatedBytes = targets.length
+            ? measure(targets.map((target) => ({
+                path: target.path,
+                relative: target.relative,
+            })), clean, true).estimatedBytes
+            : 0;
+        const report = {
+            workspace,
+            usage,
+            clean: {
+                configuredPaths: clean,
+                paths: targets.map((target) => target.relative),
+                estimatedBytes,
+                error: cleanupError,
+            },
+            lastAccessedAt: lastAccessed(data) ?? null,
+            suggestions: suggestions(data, usage, estimatedBytes, days),
+        };
+        if (values.json)
+            json(report);
+        else {
+            console.log(`Storage: ${visible(data.id)} (${visible(data.branch)})\n${visible(data.worktree)}\n\nTotal: ${size(usage.allocatedBytes)}\nDependencies: ${size(usage.dependenciesBytes)}\nBuilds / caches: ${size(usage.buildsBytes)}\nOther: ${size(usage.otherBytes)}\nConfigured cleanup: ${size(estimatedBytes)} estimated`);
+            console.log("\nLargest paths:");
+            for (const item of usage.largestPaths.slice(0, 8))
+                console.log(`  ${size(item.allocatedBytes).padStart(12)}  ${visible(item.path)}`);
+            if (cleanupError)
+                console.log(`\nCleanup unavailable: ${visible(cleanupError)}`);
+            for (const item of report.suggestions)
+                console.log(`\n${item}`);
+            console.log("\nApproximate sizes; filesystem sharing can reduce the space actually freed.");
+        }
+        return 0;
+    }
+    const recheck = () => {
+        const currentIdentity = fs.lstatSync(data.worktree);
+        if (!currentIdentity.isDirectory() ||
+            currentIdentity.dev !== workspaceIdentity.dev ||
+            currentIdentity.ino !== workspaceIdentity.ino ||
+            canonical(data.worktree) !== data.worktree)
+            throw new Error("Current workspace directory changed during cleanup");
+        const [currentFile, current] = context.store.current();
+        if (currentFile !== file || current.key !== data.key)
+            throw new Error("Current RL workspace changed during cleanup");
+        assertReady(data.worktree, false, data.branch);
+    };
+    const perform = () => {
+        recheck();
+        const currentClean = readWorkflowConfig(data.worktree).clean;
+        if (JSON.stringify(currentClean) !== JSON.stringify(clean))
+            throw new Error("Cleanup configuration changed; retry");
+        const targets = plan(data.worktree, clean);
+        const estimatedBytes = targets.length
+            ? measure(targets.map((target) => ({
+                path: target.path,
+                relative: target.relative,
+            })), clean, true).estimatedBytes
+            : 0;
+        const removedPaths = !values["dry-run"] && targets.length
+            ? remove(data.worktree, targets, recheck)
+            : [];
+        const report = {
+            workspace,
+            dryRun: !!values["dry-run"],
+            paths: targets.map((target) => target.relative),
+            estimatedBytes,
+            removedPaths,
+        };
+        if (values.json)
+            json(report);
+        else {
+            console.log(`${values["dry-run"] ? "Cleanup preview" : "Cleanup"}: ${visible(data.id)}\n${visible(data.worktree)}`);
+            for (const target of targets)
+                console.log(`  ${values["dry-run"] ? "Would remove" : "Removed"} ${visible(target.relative)} (${size(target.usage.allocatedBytes)})`);
+            console.log(`Estimated ${values["dry-run"] ? "space to free" : "cleanup size"}: ${size(estimatedBytes)}`);
+            if (!clean.length)
+                console.log('Configure "clean": ["node_modules", ".next", ".turbo"] in this workspace\'s .rl/workflows.json first.');
+            else if (!targets.length)
+                console.log("No configured generated directories exist.");
+        }
+        return 0;
+    };
+    // A preview does not create locks or write RL state.
+    return values["dry-run"] || !clean.length
+        ? perform()
+        : locked(path.join(context.store.root, GIT_WORKFLOW_DIRECTORY), GIT_WORKFLOW_LOCK, perform);
+}