toolroll 0.9.89 → 0.9.91

package/dist/easy-start.js

@@ -0,0 +1,321 @@
+/**
+ * EASY START (easy-start plan A, D, E): bare `toolroll` at a terminal, and `toolroll open`.
+ *
+ * At a person's terminal (stdin and stdout a TTY, no --json, not under a coding agent), bare `toolroll` makes sure this
+ * computer's Toolroll is running and opens the terminal UI on it:
+ *
+ * - The console is proved live first (console-instance.ts, both channels). When it isn't running: the background
+ *   service, if installed, is started through its supervisor; otherwise `up --laptop` starts as an ORDINARY child of
+ *   this process, so quitting the screen ends it through `up`'s own parent-death drain (today's foreground semantics).
+ * - With local mode on, the terminal UI opens in this process as the local owner (runAsLocalOwner): reads in-process,
+ *   writes through `runOperate`, refused wherever the local owner is. `--web` opens the browser instead, signed in
+ *   through the console's socket `link` verb (or, with nothing running, runs `up --laptop` in the foreground, which
+ *   opens it).
+ * - With local mode off (an install with passwords), nothing in the terminal writes: today's flow opens the browser,
+ *   where the person signs in with their password.
+ *
+ * Every outside effect is a seam; `defaultEasyStartSeams` gives the real ones. Under an agent, without a terminal or
+ * with --json, cli.ts never comes here: those keep exactly the behaviour they had (quick-start.ts and the scan).
+ */
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { requestLocalLink } from "./console-instance.js";
+import { backgroundInstalled, backgroundOn, startInstalledService } from "./laptop-background.js";
+import { proveConsoleReadOnly } from "./quick-start.js";
+import { backgroundAsked, localModeOf, openStore, openStoreReadOnly, recordBackgroundAsked } from "./store.js";
+export { easyStartApplies, easyStartArgs } from "./easy-start-args.js";
+const EXIT = { ok: 0, failed: 1, refused: 3 };
+/**
+ * Bare `toolroll` ("start") or `toolroll open` ("open") at a person's terminal. Resolves with the exit code once the
+ * screen (or the foreground `up`, or the browser hand-off) is done.
+ */
+export async function runEasyStart(mode, args, seams) {
+    const { write } = seams;
+    const rootArgs = args.projectRoot === null ? [] : ["--project-root", args.projectRoot];
+    const sleep = seams.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const first = await seams.prove();
+    if (!first.ok && first.state === "refused") {
+        write(`Toolroll can't open: ${first.message}.`);
+        return EXIT.refused;
+    }
+    // Attaching to a console already running: this folder's repository joins it, as bare `toolroll` always did.
+    const joinRepo = async () => {
+        if (mode !== "start")
+            return EXIT.ok;
+        const found = await seams.findRepo(seams.cwd);
+        if (found === null)
+            return EXIT.ok;
+        let repo = found;
+        try {
+            repo = realpathSync(found);
+        }
+        catch { /* as found */ }
+        return (await seams.enrolled(repo)) ? EXIT.ok : seams.admit(repo);
+    };
+    // An install with passwords: today's flow, in the browser, where the person signs in. Nothing here writes.
+    if (seams.localMode() === "off") {
+        if (!first.ok)
+            return seams.runUpForeground(rootArgs);
+        const joined = await joinRepo();
+        if (joined !== EXIT.ok)
+            return joined;
+        write(`Toolroll is on ${first.url}`);
+        await seams.openBrowser(first.url);
+        return EXIT.ok;
+    }
+    // --web with nothing running and no service: `up --laptop` in this terminal opens the browser itself, signed in.
+    if (args.web && !first.ok && !seams.serviceInstalled())
+        return seams.runUpForeground(["--laptop", ...rootArgs]);
+    let owned = null;
+    const upArgs = ["--laptop", "--no-open", ...rootArgs];
+    /** Start our own `up` and wait until its console proves live (or it ends, or the wait runs out). */
+    const startOwned = async () => {
+        const child = seams.spawnUp(upArgs);
+        owned = child;
+        const deadline = Date.now() + (seams.startTimeoutMs ?? 90_000);
+        for (;;) {
+            const proof = await seams.prove();
+            if (proof.ok)
+                return proof;
+            if (!child.running()) {
+                const last = child.tail().filter(line => line.trim() !== "").slice(-3).join(" — ");
+                return { ok: false, state: "refused", message: last === "" ? "it stopped while starting" : last };
+            }
+            if (Date.now() >= deadline) {
+                child.stop();
+                return { ok: false, state: "refused", message: "it didn't answer in time" };
+            }
+            await sleep(250);
+        }
+    };
+    let proof = first;
+    if (!proof.ok) {
+        write("Starting Toolroll…");
+        proof = seams.serviceInstalled() ? await seams.startService() : await startOwned();
+        if (!proof.ok) {
+            write(`Toolroll didn't start: ${proof.message}.`);
+            return EXIT.failed;
+        }
+    }
+    else {
+        const joined = await joinRepo();
+        if (joined !== EXIT.ok)
+            return joined;
+    }
+    const url = proof.url;
+    /** The `up` this process owns, while it runs. */
+    const ownedNow = () => (owned !== null && owned.running() ? owned : null);
+    const waitOwned = async () => {
+        const child = ownedNow();
+        if (child === null)
+            return EXIT.ok;
+        write("Ctrl-C stops it.");
+        await child.exited;
+        return EXIT.ok;
+    };
+    // No local mode here (a new install on a computer with no sandbox): the browser, with the password `up` saved.
+    if (seams.localMode() !== "on") {
+        write(`Toolroll is on ${url}. Sign in with your password.`);
+        await seams.openBrowser(url);
+        return waitOwned();
+    }
+    if (args.web) {
+        const link = await seams.requestLink();
+        if (!link.ok) {
+            write(`Toolroll is on ${url}, but it couldn't sign you in: ${link.message}.`);
+            ownedNow()?.stop();
+            return EXIT.refused;
+        }
+        write(`Toolroll is on ${url}`);
+        await seams.openBrowser(link.url);
+        return waitOwned();
+    }
+    /** Move to the background service, handing over from our own `up` (background on stops it and proves it gone). */
+    const handoff = async () => {
+        const child = ownedNow();
+        const result = await seams.backgroundOn(child === null ? null : {
+            controllerPid: child.pid,
+            // The service didn't take over: our own `up` starts again, as before.
+            restart: async () => { const again = await startOwned(); if (!again.ok)
+                throw Error(again.message); },
+        });
+        if (result.ok)
+            owned = null;
+        return result.message;
+    };
+    const session = {
+        owned: () => ownedNow() !== null,
+        openBrowser: async () => {
+            const link = await seams.requestLink();
+            if (!link.ok)
+                return `The browser couldn't be opened: ${link.message}.`;
+            await seams.openBrowser(link.url);
+            return "Opened in your browser.";
+        },
+        shouldAskBackground: () => ownedNow() !== null && !seams.serviceInstalled() && !seams.backgroundAsked(),
+        answerBackground: async (yes) => {
+            seams.recordBackgroundAnswer(yes);
+            return yes ? handoff() : "Okay. To change your mind later, run `toolroll background on`.";
+        },
+    };
+    const exit = await seams.openTui(session);
+    const child = ownedNow();
+    if (child !== null) {
+        if (exit === "keep") {
+            const said = await handoff();
+            write(said);
+            if (ownedNow() === null)
+                return EXIT.ok;
+        }
+        write("Stopping Toolroll… (running work is saved)");
+        child.stop();
+        await child.exited;
+        write("Toolroll stopped.");
+    }
+    return EXIT.ok;
+}
+/** `up` as an ordinary child of this process: its output kept (last lines, for a failed start), never on the screen. */
+export function spawnOwnedUp(args, options) {
+    const entry = options.entry ?? process.argv[1];
+    if (entry === undefined)
+        throw Error("can't find Toolroll's own command to start it");
+    const child = spawn(process.execPath, [...process.execArgv, entry, "up", ...args, "--db", options.databaseFile], {
+        cwd: options.cwd,
+        // An IPC channel: if this process ends without stopping it, `up` sees its parent go and drains (operate.ts).
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+    const lines = [];
+    const keep = (chunk) => {
+        for (const line of String(chunk).split("\n"))
+            if (line !== "")
+                lines.push(line);
+        if (lines.length > 40)
+            lines.splice(0, lines.length - 40);
+    };
+    child.stdout?.on("data", keep);
+    child.stderr?.on("data", keep);
+    let running = child.pid !== undefined;
+    const exited = new Promise(resolve => {
+        child.once("exit", code => { running = false; resolve(code); });
+        child.once("error", error => { running = false; lines.push(error.message); resolve(null); });
+    });
+    return { pid: child.pid ?? -1, exited, running: () => running, stop: () => { if (running)
+            child.kill("SIGTERM"); }, tail: () => [...lines] };
+}
+/** The real seams, for this installation's database. */
+export function defaultEasyStartSeams(options) {
+    const file = options.databaseFile;
+    const cwd = options.cwd ?? process.cwd();
+    return {
+        databaseFile: file,
+        cwd,
+        write: options.write,
+        prove: () => proveConsoleReadOnly(file, options.build),
+        localMode: () => localModeRead(file),
+        serviceInstalled: () => backgroundInstalled(),
+        startService: async () => {
+            const store = openStore(file);
+            try {
+                return await startInstalledService(store, file);
+            }
+            finally {
+                store.close();
+            }
+        },
+        spawnUp: args => spawnOwnedUp(args, { cwd, databaseFile: file }),
+        runUpForeground: async (args) => (await import("./operate.js")).runOperate("up", [...args, "--db", file], options.write, options.operate ?? {}),
+        openBrowser: async (url) => { (await import("./operate.js")).openBrowser(url); },
+        requestLink: async () => {
+            const store = openStoreReadOnly(file);
+            if (store === null)
+                return { ok: false, message: "Toolroll's database can't be read" };
+            try {
+                return await requestLocalLink(file, store, options.build);
+            }
+            finally {
+                store.close();
+            }
+        },
+        openTui: async (session) => {
+            const { createTuiSource } = await import("./tui-source.js");
+            const { runAsLocalOwner } = await import("./local-owner.js");
+            const source = createTuiSource({ databaseFile: file, ...(options.operate === undefined ? {} : { operate: options.operate }) });
+            try {
+                const tui = await loadTui();
+                return await runAsLocalOwner(() => tui.startTui(source, session));
+            }
+            finally {
+                source.close();
+            }
+        },
+        backgroundOn: async (foreground) => {
+            const store = openStore(file);
+            try {
+                // At this terminal, but the screen owns its input: another service on this database is refused, not asked.
+                const on = await backgroundOn(store, file, null, { terminal: false, ...(foreground === null ? {} : { foreground }) });
+                if (on.ok)
+                    return { ok: true, message: `Toolroll now runs in the background at ${on.url}. It starts when you log in.` };
+                return { ok: false, message: `Toolroll couldn't move to the background: ${on.message}.${(on.rolledBack ?? []).map(line => ` ${line}.`).join("")}` };
+            }
+            finally {
+                store.close();
+            }
+        },
+        backgroundAsked: () => {
+            const store = openStoreReadOnly(file);
+            // Unreadable: never ask on the strength of a database this build can't read.
+            if (store === null)
+                return true;
+            try {
+                return backgroundAsked(store) !== null;
+            }
+            finally {
+                store.close();
+            }
+        },
+        recordBackgroundAnswer: yes => {
+            const store = openStore(file);
+            try {
+                recordBackgroundAsked(store, yes ? "yes" : "no", new Date());
+            }
+            finally {
+                store.close();
+            }
+        },
+        findRepo: async (dir) => {
+            const { run } = await import("./exec.js");
+            const top = await run("git", ["rev-parse", "--show-toplevel"], { cwd: dir, timeoutMs: 10_000 });
+            return top.code === 0 ? top.stdout.trim() : null;
+        },
+        enrolled: async (repo) => {
+            const { loadRepos } = await import("./repos.js");
+            const { registryBeside } = await import("./project-admission.js");
+            const loaded = await loadRepos(registryBeside(file));
+            return !("error" in loaded) && loaded.repos.includes(repo);
+        },
+        admit: options.admit,
+    };
+}
+/** The terminal UI bundle (dist/tui.js, built from src/tui/entry.tsx), loaded only when the screen opens. */
+async function loadTui() {
+    const bundled = new URL("./tui.js", import.meta.url);
+    if (existsSync(bundled))
+        return await import(bundled.href);
+    // From source (`npm run dev`): the entry itself.
+    return await import(pathToFileURL(new URL("./tui/entry.tsx", import.meta.url).pathname).href);
+}
+/** Local mode as saved, read only: "absent" with no database yet; an older database has none ("off"). */
+export function localModeRead(file) {
+    if (file !== ":memory:" && !existsSync(file))
+        return "absent";
+    const store = openStoreReadOnly(file);
+    if (store === null)
+        return "off";
+    try {
+        return localModeOf(store)?.enabled === true ? "on" : "off";
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/first-run.d.ts

@@ -113,4 +113,81 @@ export declare function taskRoad(read: Parameters<typeof firstTaskJourney>[0], a
     report?: boolean;
     checks?: RoadChecks;
 }): JourneyStep[];
+/** The agents setup offers: the two whose sign-in check, readiness and chat are supported end to end. */
+export type WelcomeAgentId = "claude" | "codex";
+export declare const WELCOME_AGENTS: readonly {
+    id: WelcomeAgentId;
+    name: string;
+    signIn: string;
+    install: string;
+}[];
+/** The sample project's folder name under the project folder. */
+export declare const SAMPLE_PROJECT_NAME = "toolroll-sample";
+export type WelcomeAgentState = "signed-in" | "signed-out" | "not-installed" | "checking";
+export type WelcomeAgent = {
+    id: WelcomeAgentId;
+    name: string;
+    state: WelcomeAgentState;
+    /** The exact command that signs it in on this computer (installing it first when it isn't there); null once signed in or while checking. */
+    command: string | null;
+    inUse: boolean;
+    /** "Use this one" can choose it: signed in with an account, not already in use, and this person may choose. */
+    canUse: boolean;
+};
+export type WelcomeStarter = {
+    label: string;
+    draft: string;
+    href: string;
+};
+export type WelcomeModel = {
+    agent: {
+        done: boolean;
+        checking: boolean;
+        agents: WelcomeAgent[];
+        inUse: WelcomeAgentId | null;
+        /** Tasks are built with another agent than the one in use (Settings → Models decides): say so, with where to change it. */
+        buildsWith: string | null;
+    };
+    project: {
+        done: boolean;
+        projects: {
+            name: string;
+            path: string;
+        }[];
+        /** Where "Try a sample project" puts it; null when there is no project folder or it is already added. */
+        sample: string | null;
+        /** A project is added but nothing on this computer takes its tasks yet. */
+        notTakingWork: boolean;
+    };
+    task: {
+        done: boolean;
+        open: boolean;
+        starters: WelcomeStarter[];
+    };
+    /** The step the screen's one primary belongs to, or null when nothing is left that a page can do. */
+    next: "agent" | "project" | "task" | null;
+    left: number;
+};
+export type WelcomeFacts = {
+    /** Each agent's last sign-in check on this computer; null until one has answered. */
+    agents: Record<WelcomeAgentId, SignInState | null>;
+    inUse: WelcomeAgentId | null;
+    /** The provider routine builds run on now (claude by default). */
+    buildsOn: string | null;
+    canChoose: boolean;
+    projects: readonly {
+        name: string;
+        path: string;
+    }[];
+    /** The folder new projects go in; null when this console has none. */
+    projectRoot: string | null;
+    ready: boolean;
+    hasTask: boolean;
+    starters: readonly FirstTaskSuggestion[];
+    platform: NodeJS.Platform;
+};
+/** The welcome's three steps (Agent · Project · First task) from live facts, the same for every screen that shows them. */
+export declare function welcomeModel(facts: WelcomeFacts): WelcomeModel;
+/** First tasks for the sample project: the changes its README suggests. */
+export declare const SAMPLE_FIRST_TASKS: readonly FirstTaskSuggestion[];
 export {};

package/dist/first-run.js

@@ -225,3 +225,48 @@ export function taskRoad(read, approved, built, facts) {
     const waiting = read.stage === "needs-you";
     return steps.map(step => waiting && (step.state === "current" || step.state === "stuck") ? { ...step, needsYou: true } : step);
 }
+export const WELCOME_AGENTS = [
+    { id: "claude", name: "Claude Code", signIn: SIGN_IN_COMMAND, install: "npm install -g @anthropic-ai/claude-code" },
+    { id: "codex", name: "Codex", signIn: "codex login", install: "npm install -g @openai/codex" },
+];
+/** The sample project's folder name under the project folder. */
+export const SAMPLE_PROJECT_NAME = "toolroll-sample";
+const SIGNED_IN = new Set(["connected", "key-works", "key-present"]);
+/** The welcome's three steps (Agent · Project · First task) from live facts, the same for every screen that shows them. */
+export function welcomeModel(facts) {
+    const join = facts.platform === "win32" ? ";" : " &&";
+    const agents = WELCOME_AGENTS.map((one) => {
+        const seen = facts.agents[one.id];
+        const state = seen === null ? "checking" : SIGNED_IN.has(seen) ? "signed-in" : seen === "not-installed" ? "not-installed" : "signed-out";
+        const command = state === "signed-in" || state === "checking" ? null : state === "not-installed" ? `${one.install}${join} ${one.signIn}` : one.signIn;
+        const inUse = facts.inUse === one.id;
+        return { id: one.id, name: one.name, state, command, inUse, canUse: facts.canChoose && !inUse && seen === "connected" };
+    });
+    const signedIn = agents.some(one => one.state === "signed-in");
+    const checking = !signedIn && agents.some(one => one.state === "checking");
+    const builds = facts.buildsOn === null ? null : WELCOME_AGENTS.find(one => one.id === facts.buildsOn)?.name ?? facts.buildsOn;
+    const buildsWith = facts.inUse !== null && facts.buildsOn !== null && facts.buildsOn !== facts.inUse ? builds : null;
+    const hasProject = facts.projects.length > 0;
+    const samplePath = facts.projectRoot === null ? null : `${facts.projectRoot.replace(/\/+$/, "")}/${SAMPLE_PROJECT_NAME}`;
+    const sample = samplePath !== null && !facts.projects.some(one => one.path === samplePath) ? samplePath : null;
+    const projectDone = hasProject && facts.ready;
+    const taskOpen = hasProject;
+    const starters = facts.starters.slice(0, 3).map(one => ({ label: one.label, draft: one.draft, href: `/tasks/new?text=${encodeURIComponent(one.draft)}` }));
+    const model = {
+        agent: { done: signedIn, checking, agents, inUse: facts.inUse, buildsWith },
+        project: { done: projectDone, projects: [...facts.projects], sample, notTakingWork: hasProject && !facts.ready },
+        task: { done: facts.hasTask, open: taskOpen, starters: taskOpen ? starters : [] },
+    };
+    // The next step a page can move: the agent only when there is something to click (Use this one); its sign-in is a
+    // command on the computer, so a project or the first task leads meanwhile.
+    const agentAct = !signedIn ? false : facts.inUse === null && agents.some(one => one.canUse);
+    const next = agentAct ? "agent" : !projectDone ? "project" : !facts.hasTask ? "task" : null;
+    const left = [model.agent.done, model.project.done, model.task.done].filter(done => !done).length;
+    return { ...model, next, left };
+}
+/** First tasks for the sample project: the changes its README suggests. */
+export const SAMPLE_FIRST_TASKS = [
+    { source: "generic", label: "Round prices to whole cents", draft: "Round priceWithDiscount's result to whole cents and add a test for it." },
+    { source: "generic", label: "Refuse a negative discount", draft: "Make priceWithDiscount refuse a negative discount with a clear error, and test it." },
+    { source: "generic", label: "Add a usage example to the README", draft: "Add a short usage example for priceWithDiscount to the README." },
+];

package/dist/guides.js

@@ -288,7 +288,7 @@ ${AUTHORITY_LINE}
 - One command, inside the repository: \`npx toolroll up\` (or
   \`bunx toolroll up\`; Node 22.13+ must be installed — Bun's own
   runtime cannot host it). \`up\` mints the first login and saves it beside the
-  database as \`up-login.txt\` (every start prints that path and the
+  database in \`.toolroll-secrets/up-login.txt\` (every start prints that path and the
   \`cat\` command that shows the password, never the password itself),
   registers the machine as a worker, runs the console, opens the browser. Later starts ask for the
   password at most once and remember it on that machine.

package/dist/invoke.js

@@ -38,7 +38,8 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { poolRootOf } from "./worktree.js";
 import { checkLaunchRoot, signInGrants, signInIsItself } from "./agent-fence.js";
-import { CHECK_ACCESS_DEFAULT, checkAccessHere, narrowestAccess, narrowestNetwork, signInsAvailable } from "./check-access.js";
+import { localModeOn } from "./local-owner.js";
+import { CHECK_ACCESS_DEFAULT, checkAccessHere, localModeCap, narrowestAccess, narrowestNetwork, signInsAvailable } from "./check-access.js";
 import { readDenyPath } from "./project-sandbox.js";
 import { sandboxRuntimeWords } from "./sandbox-runtime.js";
 import { canonicalJson } from "./canonical-json.js";
@@ -999,8 +1000,9 @@ export function fencedCommands(store, runId, writes, inner, available = () => ma
         try {
             const temp = join(own, "tmp");
             mkdirSync(temp, { mode: 0o700 });
-            // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66.
-            if (access === "unsandboxed")
+            // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66. Never
+            // while local mode is on (easy-start C5): then they run in the fence, sandboxed.
+            if (access === "unsandboxed" && !localModeOn(store))
                 return await inner(file, args, { ...options, env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp } });
             const fenced = runFence(store, runId, "command", undefined, own, writes, sandbox);
             if (fenced.problem !== undefined)
@@ -1060,8 +1062,9 @@ export function fencedCheckoutCommands(store, repo, checkout, inner, available =
         try {
             const temp = join(own, "tmp");
             mkdirSync(temp, { mode: 0o700 });
-            // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66.
-            if (access === "unsandboxed")
+            // Not sandboxed (check-access.ts): the project's checks are trusted by the whole instance, as before 0.9.66. Never
+            // while local mode is on (easy-start C5): then they run in the fence, sandboxed.
+            if (access === "unsandboxed" && !localModeOn(store))
                 return await inner(file, args, { ...options, env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp } });
             let binding;
             try {
@@ -1259,7 +1262,9 @@ export function actualCheckAccess(store, access) {
  */
 export function checkoutLaunchOf(store, repo, runIds, platform = process.platform) {
     // As checks can get it: sign-ins (off for now; a stamp or setting from before, or another database) run sandboxed.
-    const access = checkAccessHere(narrowestAccess([store.projectCheckAccess(repo), ...runIds.map(id => store.runCheckAccess(id))]), platform);
+    const asked = checkAccessHere(narrowestAccess([store.projectCheckAccess(repo), ...runIds.map(id => store.runCheckAccess(id))]), platform);
+    // Easy-start C5: while local mode is on, never unsandboxed (re-read here, at launch).
+    const access = localModeOn(store) ? localModeCap(asked) : asked;
     if (access !== "sign-ins")
         return { access, network: undefined };
     const sealed = runIds.map(id => store.runCheckNetwork(id));