toolroll 0.7.0 → 0.8.0

package/dist/first-run.d.ts

@@ -0,0 +1,54 @@
+import type { Runner } from "./backend.js";
+export declare const SIGN_IN_COMMAND = "claude auth login";
+export declare const SANDBOX_COMMAND = "npx toolroll demo";
+export type FirstRunAction = {
+    kind: "link";
+    label: string;
+    href: string;
+} | {
+    kind: "command";
+    command: string;
+};
+export type FirstRunStep = {
+    key: "agent" | "project" | "task";
+    title: string;
+    done: boolean;
+    action: FirstRunAction | null;
+};
+export type FirstRunFacts = {
+    agentSignedIn: boolean;
+    projects: number;
+    hasTask: boolean;
+    firstResultAt: string | null;
+};
+/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+export declare function firstRunSteps(facts: FirstRunFacts): FirstRunStep[] | null;
+export type OpenIssue = {
+    number: number;
+    title: string;
+};
+export type TodoComment = {
+    file: string;
+    line: number;
+    text: string;
+};
+export type FirstTaskSuggestion = {
+    source: "issue" | "todo" | "generic";
+    label: string;
+    draft: string;
+};
+export declare const GENERIC_FIRST_TASKS: readonly FirstTaskSuggestion[];
+/** Issue titles and TODO text are written by anyone: keep only what a person can see, so the draft they send is the
+ * draft the lead reads (no control, format, zero-width, bidi, tag or variation-selector characters). */
+export declare const visibleText: (text: string) => string;
+/** Three first tasks: open GitHub issues first, then TODO or FIXME comments, then safe generic ones. */
+export declare function firstTaskSuggestions(found: {
+    issues: readonly OpenIssue[];
+    todos: readonly TodoComment[];
+}): FirstTaskSuggestion[];
+/** `git grep` lines ("file:line:text") to TODO or FIXME notes, one per file. */
+export declare function parseTodoLines(stdout: string, limit?: number): TodoComment[];
+/** Read the project's own sources for suggestions: its open issues through the `gh` login, then its TODO comments. Failures fall through quietly. */
+export declare function findFirstTasks(repo: string, runner?: Runner): Promise<FirstTaskSuggestion[]>;
+/** "First result in 7 min": how long after the installation began its first Ready result arrived. */
+export declare function firstResultWords(since: string, at: string): string | null;

package/dist/first-run.js

@@ -0,0 +1,101 @@
+/**
+ * The first run: three plain steps to a first result, and three first tasks
+ * to try. Everything here is derived from live facts on each render; the
+ * list retires permanently with the first Ready result (the
+ * 'first-success-at' installation fact). A suggestion only drafts words in
+ * the composer: nothing is filed until the person sends it and confirms.
+ */
+import { run } from "./exec.js";
+import { githubIssues } from "./issues.js";
+export const SIGN_IN_COMMAND = "claude auth login";
+export const SANDBOX_COMMAND = "npx toolroll demo";
+/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+export function firstRunSteps(facts) {
+    if (facts.firstResultAt !== null)
+        return null;
+    const project = facts.projects > 0;
+    return [
+        { key: "agent", title: "Agent signed in", done: facts.agentSignedIn, action: facts.agentSignedIn ? null : { kind: "command", command: SIGN_IN_COMMAND } },
+        { key: "project", title: "Project added", done: project, action: project ? null : { kind: "link", label: "Add a project", href: "/projects" } },
+        { key: "task", title: "Your first task", done: facts.hasTask, action: facts.hasTask ? null : { kind: "link", label: "New task", href: "/tasks/new" } },
+    ];
+}
+export const GENERIC_FIRST_TASKS = [
+    { source: "generic", label: "Add a test for an untested function", draft: "Find one function without a test and add a focused test for it." },
+    { source: "generic", label: "Fix a lint warning", draft: "Fix one lint warning without changing behaviour." },
+    { source: "generic", label: "Improve the README's setup section", draft: "Improve the setup section of the README so a newcomer can install and run the project." },
+];
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text);
+/** Issue titles and TODO text are written by anyone: keep only what a person can see, so the draft they send is the
+ * draft the lead reads (no control, format, zero-width, bidi, tag or variation-selector characters). */
+export const visibleText = (text) => text.replace(/[\p{Cf}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]/gu, "").replace(/[\p{Cc}\s]+/gu, " ").trim();
+/** Three first tasks: open GitHub issues first, then TODO or FIXME comments, then safe generic ones. */
+export function firstTaskSuggestions(found) {
+    const fromIssues = found.issues.map(({ number, title: raw }) => {
+        const title = visibleText(raw);
+        return { source: "issue", label: clip(`#${number} ${title}`, 80), draft: `Fix GitHub issue #${number}: ${title}` };
+    });
+    const fromTodos = found.todos.map(({ file: rawFile, line, text: rawText }) => ({ file: visibleText(rawFile), line, text: visibleText(rawText) })).map((todo) => ({
+        source: "todo", label: clip(todo.text === "" ? `The note in ${todo.file}` : todo.text.charAt(0).toUpperCase() + todo.text.slice(1), 80),
+        draft: `Resolve the note in ${todo.file} line ${todo.line}${todo.text === "" ? "" : `: ${todo.text}`}`,
+    }));
+    return [...fromIssues, ...fromTodos, ...GENERIC_FIRST_TASKS].slice(0, 3);
+}
+const SKIPPED = /(^|\/)(node_modules|dist|build|vendor|third_party|\.git)\//;
+/** `git grep` lines ("file:line:text") to TODO or FIXME notes, one per file. */
+export function parseTodoLines(stdout, limit = 3) {
+    const found = [];
+    const seen = new Set();
+    for (const line of stdout.split("\n")) {
+        const match = /^(.+?):(\d+):(.*)$/.exec(line);
+        if (match === null || SKIPPED.test(match[1]) || seen.has(match[1]))
+            continue;
+        const note = /\b(?:TODO|FIXME)\b(?:\([^)]*\))?[:\s-]*(.*)$/.exec(match[3]);
+        if (note === null)
+            continue;
+        seen.add(match[1]);
+        found.push({ file: match[1], line: Number(match[2]), text: clip(note[1].replace(/\s*(\*\/|-->)\s*$/, "").trim(), 120) });
+        if (found.length === limit)
+            break;
+    }
+    return found;
+}
+/** Read the project's own sources for suggestions: its open issues through the `gh` login, then its TODO comments. Failures fall through quietly. */
+export async function findFirstTasks(repo, runner = run) {
+    let issues = [];
+    try {
+        const listed = await githubIssues({ repo, runner, limit: 3, timeoutMs: 5_000 }).listReady();
+        if (listed.ok)
+            issues = listed.value.slice(0, 3).map(one => ({ number: Number(one.id), title: one.title })).filter(one => Number.isSafeInteger(one.number));
+    }
+    catch {
+        issues = [];
+    }
+    let todos = [];
+    if (issues.length < 3) {
+        try {
+            const result = await runner("git", ["grep", "-n", "-I", "-w", "--max-count=1", "-E", "TODO|FIXME"], { cwd: repo, timeoutMs: 5_000 });
+            if (result.code === 0 || result.stdout !== "")
+                todos = parseTodoLines(result.stdout);
+        }
+        catch {
+            todos = [];
+        }
+    }
+    return firstTaskSuggestions({ issues, todos });
+}
+/** "First result in 7 min": how long after the installation began its first Ready result arrived. */
+export function firstResultWords(since, at) {
+    const minutes = Math.round((Date.parse(at) - Date.parse(since)) / 60_000);
+    if (!Number.isFinite(minutes) || minutes < 0)
+        return null;
+    if (minutes < 1)
+        return "First result in under a minute";
+    if (minutes < 60)
+        return `First result in ${minutes} min`;
+    if (minutes < 48 * 60) {
+        const hours = Math.floor(minutes / 60), rest = minutes % 60;
+        return `First result in ${hours} h${rest === 0 ? "" : ` ${rest} min`}`;
+    }
+    return `First result in ${Math.round(minutes / (24 * 60))} days`;
+}

package/dist/install-method.d.ts

@@ -3,7 +3,7 @@
  * the one command that updates it that way. Only the path is read: nothing is
  * run and nothing leaves the computer.
  */
-export type InstallKind = "npm" | "pnpm" | "bun" | "yarn" | "homebrew" | "npx" | "source";
+export type InstallKind = "npm" | "pnpm" | "bun" | "yarn" | "homebrew" | "npx" | "source" | "managed";
 export type InstallMethod = {
     kind: InstallKind;
     updateCommand: string;

package/dist/install-method.js

@@ -13,6 +13,8 @@ export const UPDATE_COMMANDS = {
     homebrew: "brew upgrade ap9000/toolroll/toolroll",
     npx: "npx toolroll@latest",
     source: "git pull && npm install && npm run build",
+    // A runtime `toolroll update` installed (staged-upgrades/release-* or rollback-*): it updates itself.
+    managed: "toolroll update",
 };
 /** The install method of the bin at `bin` (the running one by default). Unknown shapes read as npm, the common case. */
 export function installMethod(bin = process.argv[1], probe = {}) {
@@ -34,6 +36,8 @@ function installKind(bin, probe) {
     // by deploying from source, never from npm.
     if (path.includes("/staged-upgrades/browser-"))
         return "source";
+    if (/\/staged-upgrades\/(release|rollback)-/.test(path))
+        return "managed";
     if (/\/Cellar\/toolroll\//i.test(path))
         return "homebrew";
     if (path.includes("/_npx/"))

package/dist/operate.d.ts

@@ -1,3 +1,4 @@
+import { type OnboardIo } from "./agent-onboard.js";
 import { type TriggerIo } from "./flow-triggers.js";
 import { type StepIo } from "./flow-steps.js";
 import { type Store } from "./store.js";
@@ -66,7 +67,15 @@ export type OperateOptions = {
     heldCoordinator?: import("./held.js").HeldSessionCoordinator;
     /** Test seam for the short indexed wait loop. */
     waitSleep?: (milliseconds: number) => Promise<void>;
+    /** Injected by tests: `onboard`'s home folder, terminal and probes. */
+    onboardSeams?: OnboardSeams;
+    /** Injected by tests: whether `up` has a person at a terminal, and how it opens a browser. */
+    upSeams?: {
+        terminal?: boolean;
+        openBrowser?: (url: string) => void;
+    };
 };
+export type OnboardSeams = Partial<Pick<OnboardIo, "home" | "env" | "cwd" | "interactive" | "confirm" | "findRepo" | "checkConnection">>;
 export declare const OPERATE_HELP: string;
 /** Parsed flags, with the positionals left over. */
 type Args = {

package/dist/operate.js

@@ -12,6 +12,7 @@ import { buildExport, exportSummary, exportZip, writeExportFolder } from "./expo
 import { startBudgetAlerts } from "./budget-alerts.js";
 import { liftAuthPause, openAuthPauses, signInGate, signInWords, startSignInProbes } from "./provider-auth.js";
 import { createConnectionChecker } from "./provider-connection.js";
+import { buildHandoff, handoffLines, loginAccount, runOnboard } from "./agent-onboard.js";
 import { backupFiles, backupFolderOf, backupOwner, backupNow, restoreDatabase, startBackups } from "./backup.js";
 import { pushLimitSink } from "./provider-limits.js";
 import { limitsView } from "./limits-ui.js";
@@ -565,13 +566,13 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "command", "timeout-seconds", "setup-digest", "stop-grace", "title", "name", "every", "lines",
     "label", "reviewers", "limit", "role", "key-file", "weekly-usd", "daily-turns", "per-hour", "token-file", "race", "compare", "race-per-usd", "race-total-usd", "race-count", "race-agents", "budget-usd", "build-usd", "sync-max-age", "merge-method",
     "phase", "risk", "tier", "clear-phase",
-    "run", "containment",
+    "run", "containment", "agent",
     "token-env", "after", "repair-max-attempts", "consumer", "batch", "feedback", "source", "view", "cursor", "why", "supersedes", "decision", "sessions", "timeout",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
     "json", "yes", "all", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
-    "no-open", "no-verify", "no-follow", "end", "report", "off", "tmux",
+    "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
     "self-heal", "plan-auto", "repair-auto", "review-retry-auto", "no-local",
     "html", "csv", "alerts-only",
     // v105: the full export.
@@ -725,6 +726,8 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(options.waitSleep === undefined ? {} : { waitSleep: options.waitSleep }),
             ...(options.releaseIo === undefined ? {} : { releaseIo: options.releaseIo }),
             ...(options.installBin === undefined ? {} : { installBin: options.installBin }),
+            ...(options.onboardSeams === undefined ? {} : { onboardSeams: options.onboardSeams }),
+            ...(options.upSeams === undefined ? {} : { upSeams: options.upSeams }),
         });
     }
     catch (error) {
@@ -939,6 +942,8 @@ async function dispatch(command, positional, flags, context) {
             return watchCommand(flags, context);
         case "up":
             return upCommand(flags, context);
+        case "onboard":
+            return onboardCommand(flags, context);
         case "daemon":
             return daemonCommand(positional, flags, context);
         case "bridge":
@@ -7660,6 +7665,54 @@ function openBrowser(url) {
         // A browser that will not open is a URL the greeting already printed.
     }
 }
+/**
+ * `onboard`: the agent that installed Toolroll becomes its lead. The work
+ * lives in agent-onboard.ts; this wires it to the installation: the same
+ * registry and project row Projects → add writes, and the same sign-in
+ * checks Settings → AI providers makes.
+ */
+async function onboardCommand(flags, context) {
+    const { store, write, json, clock } = context;
+    const seams = context.onboardSeams ?? {};
+    const portGiven = text(flags, "port");
+    const port = Number(portGiven ?? 4180);
+    if (portGiven !== undefined && (!Number.isInteger(port) || port < 1 || port >= 65536)) {
+        return fail(write, json, "onboard", "usage", "--port is a whole number under 65536", EXIT.usage);
+    }
+    const home = seams.home ?? homedir();
+    const env = seams.env ?? process.env;
+    const gitRun = context.gitRunner ?? ((file, args, opts) => run(file, [...args], { ...(opts?.cwd === undefined ? {} : { cwd: opts.cwd }), timeoutMs: 10_000 }));
+    const registryPath = registryPathOf(context);
+    const checker = createConnectionChecker({ home, env });
+    return runOnboard({
+        write,
+        json,
+        yes: flag(flags, "yes"),
+        remove: flag(flags, "remove"),
+        agentFlag: text(flags, "agent"),
+        url: `http://127.0.0.1:${port}`,
+        loginFile: join(dirname(context.databaseFile), UP_LOGIN_FILE),
+        home,
+        env,
+        version: PACKAGE_VERSION,
+        cwd: seams.cwd ?? process.cwd(),
+        interactive: seams.interactive ?? interactive(),
+        confirm: seams.confirm ?? (async (question) => /^y(es)?$/i.test(await ask(`${question} `))),
+        findRepo: seams.findRepo ?? (async (cwd) => {
+            const top = await gitRun("git", ["rev-parse", "--show-toplevel"], { cwd });
+            return top.code === 0 ? canonicalProject(top.stdout.trim()) : null;
+        }),
+        enroll: async (repo) => {
+            const before = await loadProjectRegistry(registryPath);
+            const enrolled = await updateRepos(registryPath, repos => addRepos(repos, [repo]));
+            if (!enrolled.ok)
+                return { ok: false, message: enrolled.message };
+            store.upsertProject(repo, projectName(repo), clock());
+            return { ok: true, added: "error" in before || !before.repos.includes(repo) };
+        },
+        checkConnection: seams.checkConnection ?? (agent => checker(agent)),
+    });
+}
 async function upCommand(flags, context) {
     const { store, write, json, clock } = context;
     const demoFence = refuseDemo(context, "up");
@@ -8099,6 +8152,8 @@ async function upCommand(flags, context) {
     // 9. Readiness, then the ONE startup envelope / greeting (finding 11/20).
     const approverPlan2 = approver;
     const url = console_.url;
+    const terminal = context.upSeams?.terminal ?? process.stdout.isTTY === true;
+    const upHandoff = buildHandoff({ url, loginFile: approverPlan2.passwordFile, account: approverPlan2.passwordFile === null ? approverPlan2.approver : loginAccount(approverPlan2.passwordFile) ?? approverPlan2.approver });
     if (fatal === null) {
         if (json) {
             write(envelopeJson({
@@ -8111,8 +8166,17 @@ async function upCommand(flags, context) {
                 approvers: approverPlan2.approvers,
                 approverVerified: approverPlan2.verified,
                 ...(approverPlan2.passwordFile === null ? {} : { passwordFile: approverPlan2.passwordFile }),
+                handoff: upHandoff,
             }));
         }
+        else if (!terminal) {
+            // No person at a terminal: an agent started this. It gets the
+            // handoff to relay, never the password, and no browser opens.
+            write("");
+            for (const line of handoffLines(upHandoff))
+                write(line);
+            write("Run `toolroll onboard` inside a repository to add it and install the Toolroll skill for your agent.");
+        }
         else {
             write("");
             write(`The console is on ${url}`);
@@ -8137,8 +8201,8 @@ async function upCommand(flags, context) {
             write("  The inbox checklist shows what remains before approved work builds unattended.");
             write("  Ctrl-C stops Toolroll on this machine.");
         }
-        if (!json && !flags.has("no-open") && process.stdout.isTTY === true)
-            openBrowser(url);
+        if (!json && !flags.has("no-open") && terminal)
+            (context.upSeams?.openBrowser ?? openBrowser)(url);
     }
     // 10. Supervise to the end.
     await stopped;

package/dist/releases.d.ts

@@ -16,6 +16,8 @@ export declare const UPDATE_SWITCH_FILE = "update-check";
 export declare const RUNNER_VERSIONS_FILE = "runner-versions.json";
 export declare const CHECK_EVERY_MS: number;
 export declare const CHECK_TIMEOUT_MS = 5000;
+/** The npm registry `toolroll update` downloads releases from. */
+export declare const REGISTRY = "https://registry.npmjs.org";
 export declare const REGISTRY_URL = "https://registry.npmjs.org/toolroll/latest";
 export declare const RELEASES_PAGE = "https://github.com/ap9000/toolroll/releases/tag/";
 export type Release = {
@@ -74,3 +76,10 @@ export declare function runnerVersions(dir: string): RunnerVersion[];
 export declare function startUpdateChecks(store: Store, dir: string, current: string, updateCommand: string, io?: ReleaseIo & {
     everyMs?: number;
 }): () => void;
+/** The latest version, asked of npm now: for an explicit update (the command, Check now), not the once-a-day
+ * notice, so neither its cache nor its switch applies. Throws with npm's own reason. */
+export declare function latestVersionNow(io?: {
+    fetch?: typeof fetch;
+}): Promise<{
+    version: string;
+}>;

package/dist/releases.js

@@ -18,7 +18,9 @@ export const UPDATE_SWITCH_FILE = "update-check";
 export const RUNNER_VERSIONS_FILE = "runner-versions.json";
 export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
 export const CHECK_TIMEOUT_MS = 5_000;
-export const REGISTRY_URL = "https://registry.npmjs.org/toolroll/latest";
+/** The npm registry `toolroll update` downloads releases from. */
+export const REGISTRY = "https://registry.npmjs.org";
+export const REGISTRY_URL = `${REGISTRY}/toolroll/latest`;
 export const RELEASES_PAGE = "https://github.com/ap9000/toolroll/releases/tag/";
 const NOTES_API = "https://api.github.com/repos/ap9000/toolroll/releases/tags/";
 const NOTES_MAX = 20_000;
@@ -223,3 +225,14 @@ function writeAtomic(file, content) {
     writeFileSync(temporary, content, { mode: 0o600 });
     renameSync(temporary, file);
 }
+/** The latest version, asked of npm now: for an explicit update (the command, Check now), not the once-a-day
+ * notice, so neither its cache nor its switch applies. Throws with npm's own reason. */
+export async function latestVersionNow(io = {}) {
+    const answer = await (io.fetch ?? fetch)(REGISTRY_URL, { signal: AbortSignal.timeout(10_000), headers: { accept: "application/json" } });
+    if (!answer.ok)
+        throw new Error(`npm answered ${answer.status}`);
+    const version = (await answer.json()).version;
+    if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version))
+        throw new Error("npm did not name a version");
+    return { version };
+}

package/dist/serve.d.ts

@@ -11,8 +11,10 @@ import { run as execRun } from "./exec.js";
 import { type AgentChoice } from "./agentconfig.js";
 import { type RouteProjection, type RouteOverride, type RouteStamp, type RiskLevel } from "./phase-routing.js";
 import { type Phase } from "./provider.js";
+import { launchRuntimeUpdate } from "./toolroll-update.js";
 import type { RevisionLineage } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
+import { type InstallMethod } from "./install-method.js";
 export type ServeOptions = {
     /** Tests: the bin whose real path says how Toolroll was installed (Settings → Updates' command). */
     installBin?: string;
@@ -53,6 +55,18 @@ export type ServeOptions = {
     configDir?: string;
     /** Test seam for the Slack setup handshake. */
     slackFetcher?: typeof fetch;
+    /** Settings → Updates seams: the latest release, how this Toolroll was
+     * installed, its version, and how the updater job starts. Tests and
+     * screenshots inject these; production reads the registry and launchd. */
+    updates?: {
+        latest?: () => Promise<{
+            version: string;
+        }>;
+        method?: InstallMethod;
+        current?: string;
+        dist?: string;
+        launch?: typeof launchRuntimeUpdate;
+    };
     discordFetcher?: typeof fetch;
     /** Injected by tests: Microsoft sign-in, key metadata and Teams conversation calls. */
     teamsFetcher?: typeof fetch;
@@ -107,6 +121,8 @@ export type ServeOptions = {
     additionalProjectRepos?: () => readonly string[];
     connectionProbe?: typeof execRun;
     connectionHome?: string;
+    /** Test seam for Chat's first tasks: the `gh` and `git grep` reads. */
+    firstTaskRunner?: typeof execRun;
     modelCatalogFetcher?: typeof fetch;
     /** Test seams for Settings → Models: CLI version probes and the PATH they search. */
     modelRunner?: VersionRunner;