toolroll 0.7.0 → 0.8.1

package/dist/agent-onboard.js

@@ -0,0 +1,356 @@
+/**
+ * `toolroll onboard`: the agent that installed Toolroll becomes its lead.
+ *
+ * Run inside a repository, it adds that repository as a project (the same
+ * registry and project row Projects → add writes), reports which agent
+ * CLIs are signed in (the checks Settings → AI providers makes), installs
+ * a thin operator skill for the person's own agent, prints the MCP line
+ * without running it, and ends with a handoff the agent can relay.
+ *
+ * Adding the project and writing the skill both need --yes or one yes
+ * typed at a terminal. The project is the main checkout (never a linked
+ * worktree, the home folder, or one of Toolroll's own worktrees). The skill
+ * is replaced by the next onboard and deleted by `onboard --remove` only
+ * while it is exactly a version Toolroll wrote; a file of the same name
+ * that is not ours, or ours with the person's edits, is never touched.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { CLAUDE_CODE_GUIDES, CLAUDE_CODE_MANAGED_MARK, MANAGED_MARK, OPERATOR_SKILL_MARK, claudeCodeSkillContent } from "./skills.js";
+import { connectionWords } from "./control-ui.js";
+import { envelopeJson } from "./envelope.js";
+export const ONBOARD_AGENTS = ["claude", "codex"];
+export const AGENT_NAMES = { claude: "Claude Code", codex: "Codex" };
+/** Each agent's user-level home: where its skills folder lives. A relative CODEX_HOME is under the home folder, never
+ * wherever onboard happens to run. */
+export function agentHome(agent, home, env) {
+    if (agent === "codex") {
+        const codexHome = env["CODEX_HOME"];
+        if (codexHome === undefined || codexHome === "")
+            return join(home, ".codex");
+        return isAbsolute(codexHome) ? codexHome : resolve(home, codexHome);
+    }
+    return join(home, ".claude");
+}
+export function operatorSkillPath(agent, home, env) {
+    return join(agentHome(agent, home, env), "skills", "toolroll", "SKILL.md");
+}
+/** The agents this person uses: those whose home folder exists, else Claude Code. */
+export function detectAgents(home, env) {
+    const found = ONBOARD_AGENTS.filter(agent => existsSync(agentHome(agent, home, env)));
+    return found.length > 0 ? found : ["claude"];
+}
+/** The line that adds Toolroll as tools, for every project. Printed, never run. */
+export function mcpLine(agent) {
+    return agent === "claude" ? "claude mcp add --scope user toolroll -- toolroll mcp" : `${agent} mcp add toolroll -- toolroll mcp`;
+}
+/** The thin skill: when to reach for Toolroll, and where the real guides are. */
+export function operatorSkillContent(version) {
+    return `---
+name: toolroll
+description: Hand coding work to this machine's Toolroll and see it through. Use when the person wants work done unattended ("queue these bugs overnight"), asks what needs them, wants to wait on or review a result, or wants finished work released.
+---
+
+${OPERATOR_SKILL_MARK} · written by toolroll ${version}. \`toolroll onboard --yes\` replaces this file; \`toolroll onboard --remove --yes\` deletes it. -->
+
+# Toolroll
+
+You lead this person's Toolroll. Its agents build; the person approves.
+
+- **Hand off** work that can run without anyone watching: a batch of bugs, a refactor, anything overnight.
+- **Wait** on handed-off work with Toolroll instead of checking by hand.
+- **Review**: say what needs the person, and open finished results.
+- **Release** a result the person accepted through Toolroll's own publishing, never by pushing it yourself.
+
+Read the guides from the installed binary. They match its version, so do not copy them:
+
+- \`toolroll skills get operating\`: the commands, their JSON answers, and what you must never do.
+- \`toolroll skills get console\`: which screen does what, for the person.
+- \`toolroll skills list\`: every other guide.
+
+Approving work and answering decisions belong to the person. Never read out or repeat their password.
+`;
+}
+const escapedMark = OPERATOR_SKILL_MARK.replace(/[.*+?^$()|[\]\\{}]/g, "\\$&");
+const WRITTEN_BY = new RegExp(`^(${escapedMark} · written by toolroll )(\\S+?)(\\. \`toolroll onboard)`, "m");
+/** A skill's fingerprint with the version it names set aside: every release writes the same words. */
+export function skillFingerprint(content) {
+    return createHash("sha256").update(content.replace(WRITTEN_BY, "$1*$3")).digest("hex");
+}
+/** Every SKILL.md Toolroll has generated at this path: the operator skill, and `skills install --claude-code`'s. */
+const KNOWN_SKILLS = new Set([operatorSkillContent("0.0.0"), claudeCodeSkillContent()].map(skillFingerprint));
+/** ours: exactly a version Toolroll wrote. edited: ours, with the person's changes. foreign: not ours at all. */
+function skillOwnership(path) {
+    const entry = lstatSync(path);
+    if (entry.isSymbolicLink() || !entry.isFile() || entry.size > 2_000_000)
+        return "foreign";
+    const content = readFileSync(path, "utf8");
+    const marked = content.startsWith("---\nname: toolroll\n") && [OPERATOR_SKILL_MARK, CLAUDE_CODE_MANAGED_MARK, MANAGED_MARK].some(mark => content.includes(mark));
+    if (!marked)
+        return "foreign";
+    return KNOWN_SKILLS.has(skillFingerprint(content)) ? "ours" : "edited";
+}
+/** Guide copies an older `skills install --claude-code` left beside SKILL.md. */
+function oldGuideCopies(folder) {
+    return CLAUDE_CODE_GUIDES.map(name => join(folder, `${name}.md`)).filter(path => {
+        try {
+            const entry = lstatSync(path);
+            return !entry.isSymbolicLink() && entry.isFile() && entry.size <= 2_000_000 && readFileSync(path, "utf8").startsWith(`${CLAUDE_CODE_MANAGED_MARK}\n\n`);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** What install (or --remove) would do, without writing anything. */
+export function planOperatorSkill(agents, options) {
+    return agents.map(agent => {
+        const path = operatorSkillPath(agent, options.home, options.env);
+        const folder = join(path, "..");
+        let folderIsReal = true;
+        try {
+            const entry = lstatSync(folder);
+            folderIsReal = entry.isDirectory() && !entry.isSymbolicLink();
+        }
+        catch {
+            return { agent, path, action: options.remove ? "absent" : "create", alsoRemove: [] };
+        }
+        if (!folderIsReal)
+            return { agent, path, action: "not-ours", alsoRemove: [] };
+        const alsoRemove = oldGuideCopies(folder);
+        if (!lstatExists(path)) {
+            return { agent, path, action: options.remove ? (alsoRemove.length > 0 ? "remove" : "absent") : "create", alsoRemove };
+        }
+        const ownership = skillOwnership(path);
+        if (ownership !== "ours")
+            return { agent, path, action: ownership === "edited" ? "edited" : "not-ours", alsoRemove: [] };
+        if (options.remove)
+            return { agent, path, action: "remove", alsoRemove };
+        const current = readFileSync(path, "utf8") === operatorSkillContent(options.version);
+        return { agent, path, action: current && alsoRemove.length === 0 ? "current" : "replace", alsoRemove };
+    });
+}
+function lstatExists(path) {
+    return lstatSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+/** Carry out a plan. Steps that are not ours, current, or absent change nothing. */
+export function applyOperatorSkill(steps, version) {
+    const wrote = [];
+    const removed = [];
+    for (const step of steps) {
+        const folder = join(step.path, "..");
+        if (step.action === "create" || step.action === "replace") {
+            mkdirSync(folder, { recursive: true });
+            writeFileSync(step.path, operatorSkillContent(version));
+            wrote.push(step.path);
+        }
+        if (step.action === "create" || step.action === "replace" || step.action === "remove") {
+            for (const path of step.alsoRemove) {
+                unlinkSync(path);
+                removed.push(path);
+            }
+        }
+        if (step.action === "remove") {
+            if (lstatExists(step.path)) {
+                unlinkSync(step.path);
+                removed.push(step.path);
+            }
+            if (readdirSync(folder).length === 0)
+                rmdirSync(folder);
+        }
+    }
+    return { wrote, removed };
+}
+export const NEXT_THINGS = ["queue these bugs overnight", "what needs me?", "open the result"];
+export function buildHandoff(input) {
+    return {
+        console: input.url,
+        start: "toolroll up",
+        login: input.login,
+        phone: "Open the console on your phone over your tailnet, or pair Telegram in Settings → Telegram with the /pair code it shows.",
+        next: NEXT_THINGS,
+    };
+}
+export function handoffLines(handoff) {
+    const login = handoff.login === null
+        ? "no account yet; `toolroll up` creates one"
+        : handoff.login.file === null
+            ? `${handoff.login.account ?? "your account"} — sign in with your password`
+            : `${handoff.login.account ?? "the account"} — the password is in ${handoff.login.file}`;
+    return [
+        "Toolroll is ready.",
+        `  console   ${handoff.console}`,
+        `  login     ${login}`,
+        `  phone     ${handoff.phone}`,
+        `  say next  ${handoff.next.map(one => `"${one}"`).join(" · ")}`,
+    ];
+}
+/** The account name from a saved login file, never its password. */
+export function loginAccount(file) {
+    try {
+        const raw = readFileSync(file, "utf8").trim();
+        const cut = raw.indexOf(" ");
+        return cut > 0 ? raw.slice(0, cut) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function agentReport(agent, connection) {
+    return { agent, name: AGENT_NAMES[agent], state: connection.state, words: connectionWords(connection), ...(connection.plan === undefined ? {} : { plan: connection.plan }) };
+}
+const real = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+};
+const within = (path, folder) => path === folder || path.startsWith(folder.endsWith(sep) ? folder : `${folder}${sep}`);
+/** Why a found repository cannot be the project, or null when it can. */
+export function projectRefusal(found, where) {
+    const worktrees = real(where.worktrees);
+    if ([where.cwd, found.top, found.main].some(path => within(real(path), worktrees))) {
+        return `${found.top} is one of Toolroll's own worktrees, not a project: run onboard inside your own checkout`;
+    }
+    const home = real(where.home);
+    if (real(found.main) === home || real(found.top) === home) {
+        return `${home} is your home folder, not a project: run onboard inside the repository you want to hand off`;
+    }
+    return null;
+}
+/** Returns the exit code: 0 done, 2 usage, 3 a refusal to answer. */
+export async function runOnboard(io) {
+    const command = "onboard";
+    const refuse = (reason, message, code, extra = {}) => {
+        io.write(io.json ? envelopeJson({ ok: false, command, reason, message, ...extra }) : message);
+        return code;
+    };
+    let agents;
+    if (io.agentFlag !== undefined) {
+        const asked = io.agentFlag.split(",").map(one => one.trim()).filter(one => one !== "");
+        const unknown = asked.filter(one => !ONBOARD_AGENTS.includes(one));
+        if (asked.length === 0 || unknown.length > 0)
+            return refuse("usage", "--agent takes claude, codex, or claude,codex", 2);
+        agents = [...new Set(asked)];
+    }
+    else {
+        agents = detectAgents(io.home, io.env);
+    }
+    // The skill: validate every file first.
+    const steps = planOperatorSkill(agents, { home: io.home, env: io.env, version: io.version, remove: io.remove });
+    const changes = steps.filter(step => step.action === "create" || step.action === "replace" || step.action === "remove");
+    const foreign = steps.filter(step => step.action === "not-ours" || step.action === "edited");
+    const skillChanges = foreign.length === 0 && changes.length > 0;
+    // The project: the main checkout of the repository onboard runs in, never --remove's business.
+    let project = { state: "none" };
+    if (!io.remove) {
+        const found = await io.findRepo(io.cwd);
+        if (found !== null) {
+            const refusal = projectRefusal(found, { cwd: io.cwd, home: io.home, worktrees: io.worktrees });
+            if (refusal !== null)
+                project = { state: "refused", path: found.main, message: refusal };
+            else
+                project = { state: (await io.enrolled(found.main)) ? "already" : "needs-yes", path: found.main };
+        }
+    }
+    const projectChange = project.state === "needs-yes";
+    // Then ask once for everything that writes, then write.
+    let consent = false;
+    if (skillChanges || projectChange) {
+        const parts = [
+            ...(projectChange ? [`add ${project.path} as a project`] : []),
+            ...(skillChanges ? [`${io.remove ? "remove" : "write"} ${changes.map(step => step.path).join(" and ")}`] : []),
+        ];
+        const question = `${parts.join(" and ").replace(/^./, first => first.toUpperCase())}? [y/N]`;
+        consent = io.yes || (io.interactive && !io.json && (await io.confirm(question)));
+    }
+    const unconfirmed = io.interactive && !io.json && !io.yes ? "declined" : "needs-yes";
+    let skill;
+    if (foreign.length > 0) {
+        skill = { state: foreign.some(step => step.action === "not-ours") ? "not-ours" : "edited", files: steps, wrote: [], removed: [] };
+    }
+    else if (!skillChanges) {
+        skill = { state: io.remove ? "absent" : "current", files: steps, wrote: [], removed: [] };
+    }
+    else if (!consent) {
+        skill = { state: unconfirmed, files: steps, wrote: [], removed: [] };
+    }
+    else {
+        const done = applyOperatorSkill(steps, io.version);
+        skill = { state: io.remove ? "removed" : "written", files: steps, ...done };
+    }
+    const skillLine = () => {
+        const where = (list) => list.map(step => step.path).join(", ");
+        const nothing = io.remove ? "removed" : "written";
+        switch (skill.state) {
+            case "written": return `skill     wrote ${skill.wrote.join(", ")}`;
+            case "removed": return `skill     removed ${skill.removed.join(", ")}`;
+            case "current": return `skill     up to date: ${where(steps)}`;
+            case "absent": return "skill     not installed; nothing to remove";
+            case "not-ours": return `skill     ${where(foreign)} ${foreign.length === 1 ? "is" : "are"} not Toolroll's, so nothing was ${nothing}`;
+            case "edited": return `skill     ${where(foreign)} ${foreign.length === 1 ? "has your edits, so it was" : "have your edits, so they were"} left as is`;
+            case "declined": return `skill     nothing ${nothing}`;
+            case "needs-yes": return `skill     not ${nothing} yet: run again with --yes to ${io.remove ? "remove" : "write"} ${where(changes)}`;
+        }
+    };
+    const skillData = { state: skill.state, files: skill.files.map(step => ({ agent: step.agent, path: step.path, action: step.action })), wrote: skill.wrote, removed: skill.removed };
+    if (io.remove) {
+        if (skill.state === "not-ours" || skill.state === "edited")
+            return refuse(skill.state, skillLine().replace(/^skill\s+/, ""), 3, { skill: skillData });
+        if (skill.state === "needs-yes" || skill.state === "declined") {
+            return refuse("unconfirmed", skillLine().replace(/^skill\s+/, ""), 3, { skill: skillData });
+        }
+        io.write(io.json ? envelopeJson({ ok: true, command, skill: skillData }) : skillLine());
+        return 0;
+    }
+    if (project.state === "needs-yes") {
+        if (!consent)
+            project = { state: unconfirmed, path: project.path };
+        else {
+            const enrolled = await io.enroll(project.path);
+            project = enrolled.ok ? { state: enrolled.added ? "added" : "already", path: project.path } : { state: "failed", path: project.path, message: enrolled.message };
+        }
+    }
+    const reports = await Promise.all(ONBOARD_AGENTS.map(async (agent) => agentReport(agent, await io.checkConnection(agent))));
+    const handoff = buildHandoff({ url: io.url, login: io.login });
+    const mcp = agents.map(agent => ({ agent, command: mcpLine(agent) }));
+    const projectData = project.state === "added" || project.state === "already" ? { path: project.path, added: project.state === "added" } : null;
+    const projectProblem = (() => {
+        switch (project.state) {
+            case "none": return "not inside a git repository";
+            case "refused": return project.message;
+            case "failed": return `${project.path} could not be added — ${project.message}`;
+            case "needs-yes": return `not added yet: run again with --yes to add ${project.path}`;
+            case "declined": return `${project.path} not added`;
+            default: return null;
+        }
+    })();
+    if (io.json) {
+        io.write(envelopeJson({
+            ok: true,
+            command,
+            project: projectData,
+            ...(projectProblem === null ? {} : { projectProblem }),
+            agents: reports,
+            skill: skillData,
+            mcp,
+            handoff,
+        }));
+        return 0;
+    }
+    const projectLine = projectData !== null
+        ? `project   ${projectData.path} — ${projectData.added ? "added" : "already added"}`
+        : project.state === "none" ? "project   none added: run onboard inside the repository you want to hand off" : `project   ${projectProblem}`;
+    io.write([
+        projectLine,
+        `agents    ${reports.map(one => `${one.name}: ${[one.words, one.plan].filter(Boolean).join(" · ")}`).join("; ")}`,
+        skillLine(),
+        ...mcp.map((one, index) => `${index === 0 ? "tools    " : "         "} ${one.command}   (add Toolroll as tools; not run)`),
+        "",
+        ...handoffLines(handoff),
+    ].join("\n"));
+    return 0;
+}