@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/dist/src/cli/commands.js

@@ -0,0 +1,159 @@
+/**
+ * Command handlers for loop, MCP setup, status, doctor, and profile validate.
+ * Interactive prompting stays in ./prompt.ts and is invoked from here after
+ * argv parsing.
+ */
+import { spawn } from "node:child_process";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { doctor, doctorData, status, statusData } from "../installer.js";
+import { applyMcpSetup, planMcpSetup } from "../mcp-setup.js";
+import { loadProjectConfig, resolveProfiles } from "../profiles.js";
+import { assertKnownOptions, DOCTOR_FLAGS, flags, MCP_FLAGS, rootArg, STATUS_FLAGS, UI_FLAGS, value } from "./argv.js";
+import { loopDown, loopEnv, loopOverview, loopStop, loopUp, serveDashboard } from "./loop-launcher.js";
+import { confirmGeneral, mcpSetupSelections } from "./prompt.js";
+/** `loop leases [--task-id ID] [--root PATH] [--json] [--clear-stale]` and
+ * `loop migrate-data [--root PATH] [--json] [--dry-run]`: forwarded to
+ * loop-entry.mjs as `<action> [task-id] <root> [switches]`. */
+const loopDiagnosticArgs = (action, args) => {
+    const allowedSwitches = action === "leases" ? ["--json", "--clear-stale"] : ["--json", "--dry-run"];
+    const allowedValues = action === "leases" ? ["--task-id", "--root"] : ["--root"];
+    const parsed = new Map();
+    const switches = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index] ?? "";
+        if (allowedSwitches.includes(key)) {
+            if (switches.has(key))
+                throw new Error("Invalid or duplicate loop option");
+            switches.add(key);
+            continue;
+        }
+        const entry = args[index + 1];
+        if (!allowedValues.includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
+            throw new Error("Invalid or duplicate loop option");
+        parsed.set(key, entry);
+        index += 1;
+    }
+    const root = resolve(parsed.get("--root") ?? ".");
+    return { root, argv: action === "leases" ? ["leases", parsed.get("--task-id") ?? "", root, ...switches] : ["migrate-data", root, ...switches] };
+};
+export const runLoopCommand = async (args) => {
+    const action = args[0] ?? "";
+    if (!["up", "down", "stop", "env", "start", "status", "resume", "intake", "worker-image", "leases", "migrate-data"].includes(action))
+        throw new Error("Expected loop up, down, stop, env, start, status, intake, leases, migrate-data, or worker-image");
+    if (action === "up")
+        return loopUp(args.slice(1));
+    if (action === "down")
+        return loopDown(args.slice(1));
+    if (action === "stop")
+        return loopStop(args.slice(1));
+    if (action === "env")
+        return loopEnv(args.slice(1));
+    if (action === "status" && !args.includes("--task-id"))
+        return loopOverview(args.slice(1));
+    if (action === "leases" || action === "migrate-data") {
+        const { root, argv } = loopDiagnosticArgs(action, args.slice(1));
+        const child = spawn(process.execPath, [join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs"), ...argv], { stdio: "inherit" });
+        const code = await new Promise((resolveExit, rejectExit) => { child.once("error", rejectExit); child.once("exit", (exitCode) => resolveExit(exitCode)); });
+        if (code !== 0)
+            process.exitCode = code ?? 1;
+        return;
+    }
+    const parsed = new Map();
+    for (let index = 1; index < args.length; index += 2) {
+        const key = args[index];
+        const entry = args[index + 1];
+        if (key === undefined || !["--task-id", "--title", "--root", "--mode", "--provider", "--tag", "--loop-env"].includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
+            throw new Error("Invalid or duplicate loop option");
+        parsed.set(key, entry);
+    }
+    const root = resolve(parsed.get("--root") ?? ".");
+    const script = join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs");
+    const child = spawn(process.execPath, [script, action, parsed.get("--task-id") ?? "", root, parsed.get("--mode") ?? "", parsed.get("--provider") ?? "", parsed.get("--tag") ?? "", parsed.get("--title") ?? ""], { stdio: "inherit", env: { ...process.env, ...(parsed.has("--loop-env") ? { AIDLC_ENV_FILE: resolve(parsed.get("--loop-env") ?? "") } : {}) } });
+    // Stay alive while the child runs so its own staged shutdown (stop after the
+    // current turn → cancel the turn → exit) stays reachable. A terminal Ctrl-C
+    // already reaches the child through the process group, so SIGINT is only
+    // swallowed here (forwarding it would count twice); SIGTERM sent to this
+    // wrapper alone (e.g. `kill <pid>`) is forwarded instead of orphaning the child.
+    const onInterrupt = () => { };
+    const onTerminate = () => { if (child.exitCode === null && child.signalCode === null)
+        child.kill("SIGTERM"); };
+    process.on("SIGINT", onInterrupt);
+    process.on("SIGTERM", onTerminate);
+    try {
+        const { code, signal } = await new Promise((resolveExit, rejectExit) => {
+            child.once("error", rejectExit);
+            child.once("exit", (exitCode, exitSignal) => resolveExit({ code: exitCode, signal: exitSignal }));
+        });
+        if (code !== 0)
+            process.exitCode = code ?? (signal === "SIGINT" ? 130 : 1);
+    }
+    finally {
+        process.off("SIGINT", onInterrupt);
+        process.off("SIGTERM", onTerminate);
+    }
+};
+export const runUi = async (args) => {
+    assertKnownOptions(args, UI_FLAGS);
+    const reviewerTokenFile = value(args, "--reviewer-token-file");
+    const port = Number(value(args, "--port") ?? 4173);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("--port must be an integer between 1 and 65535");
+    await serveDashboard({
+        root: resolve(rootArg(args)), host: value(args, "--host") ?? "127.0.0.1", port, open: flags(args).has("--open"),
+        ...(reviewerTokenFile ? { reviewerTokenFile } : {}),
+    });
+};
+const mcpSetupOptions = async (args) => {
+    const selected = await mcpSetupSelections(args);
+    return { root: rootArg(args), template: join(fileURLToPath(new URL("../../services/aidlc-coordination", import.meta.url))), dryRun: flags(args).has("--dry-run"), deployment: selected.deployment, storage: selected.storage, bind: selected.bind, workspace: selected.workspace, pollMs: selected.pollMs, tokenEnv: selected.tokenEnv, providers: selected.providers, enable: flags(args).has("--enable") };
+};
+export const runMcpSetup = async (args) => {
+    assertKnownOptions(args.slice(1), MCP_FLAGS);
+    const options = await mcpSetupOptions(args.slice(1));
+    const plan = planMcpSetup(options);
+    console.log(`◆ MCP SETUP preview — ${options.dryRun ? "no files will be written" : "review before applying"}`);
+    console.log(JSON.stringify(plan, null, 2));
+    if (options.dryRun)
+        return;
+    if (!await confirmGeneral({ dryRun: options.dryRun, yes: flags(args.slice(1)).has("--yes") }, "Apply MCP setup"))
+        return;
+    applyMcpSetup(options);
+    console.log(`MCP setup written to ${plan.target}. MCP remains ${options.enable ? "enabled" : "disabled"}; start Docker explicitly with docker compose --env-file .env -f ${join(plan.target, "compose.yaml")} up -d.`);
+};
+export const runMcp = async (args) => { if (args[0] !== "setup")
+    throw new Error("Unknown command: mcp"); return runMcpSetup(args); };
+export const runStatus = (args) => {
+    assertKnownOptions(args, STATUS_FLAGS);
+    const root = rootArg(args);
+    if (flags(args).has("--json"))
+        console.log(JSON.stringify(statusData(root)));
+    else
+        console.log(status(root));
+};
+export const runDoctor = (args) => {
+    assertKnownOptions(args, DOCTOR_FLAGS);
+    const root = rootArg(args);
+    const strict = flags(args).has("--strict");
+    if (flags(args).has("--json")) {
+        const data = doctorData(root, strict);
+        console.log(JSON.stringify(data));
+        if (data.level === "error")
+            process.exitCode = 1;
+    }
+    else {
+        const result = doctor(root, strict);
+        console.log(result);
+        if (result.startsWith("ERROR:"))
+            process.exitCode = 1;
+    }
+};
+export const runProfileValidate = (args) => {
+    assertKnownOptions(args.slice(1), new Set());
+    const root = rootArg(args.slice(1));
+    const config = loadProjectConfig(root);
+    const profiles = resolveProfiles(root, config.extends);
+    console.log(`OK: ${profiles.map((item) => item.id).join(" → ")}`);
+};
+export const runProfile = (args) => { if (args[0] !== "validate")
+    throw new Error("Unknown command: profile"); return runProfileValidate(args); };

package/dist/src/cli/loop-launcher.d.ts

@@ -0,0 +1,47 @@
+export interface LauncherArgs {
+    root: string;
+    values: Map<string, string>;
+    switches: Set<string>;
+}
+/** Parses `--flag value` / `--switch` options against the per-action allowlist. */
+export declare const parseLauncherArgs: (args: string[], allowed: string[]) => LauncherArgs;
+export declare const installerCliPath: (root: string) => string;
+export declare const recordInstallerCli: (root: string) => void;
+export declare const uiStatePath: (root: string) => string;
+interface UiRecord {
+    pid: number;
+    url: string;
+    startedAt: string;
+    instance?: string;
+}
+/** The recorded dashboard, if any. `running` only means the pid exists; use
+ * `dashboardReachable` before trusting or signalling it (the pid may have been reused). */
+export declare const readUiRecord: (root: string) => (UiRecord & {
+    running: boolean;
+}) | undefined;
+/** True when the recorded dashboard itself still answers: the URL serves the same random
+ * instance id the record holds (another project's dashboard on that port does not match). */
+export declare const dashboardReachable: (record: {
+    url: string;
+    instance?: string;
+}) => Promise<boolean>;
+export interface ServeOptions {
+    root: string;
+    host: string;
+    port: number;
+    open: boolean;
+    reviewerTokenFile?: string;
+    record?: boolean;
+}
+export declare const isLoopbackHost: (host: string) => boolean;
+/** Printed when the dashboard listens on a non-loopback address: it has no authentication. */
+export declare const EXPOSED_WARNING = "Warning: the dashboard has no authentication; expose it only on a trusted network.";
+/** Serves the dashboard until SIGINT/SIGTERM. `record` writes ui.json so `loop down`/`up` can find it. */
+export declare const serveDashboard: (options: ServeOptions) => Promise<void>;
+export declare const loopUp: (args: string[]) => Promise<void>;
+export declare const loopStop: (args: string[]) => Promise<void>;
+export declare const loopDown: (args: string[]) => Promise<void>;
+export declare const loopEnv: (args: string[]) => void;
+/** `loop status` without a task id: daemon, dashboard, and environment at a glance. */
+export declare const loopOverview: (args: string[]) => Promise<void>;
+export {};

package/dist/src/cli/loop-launcher.js

@@ -0,0 +1,322 @@
+/**
+ * One-command local loop: `loop up | down | stop | env | status` (no task id).
+ *
+ * `up` checks the configuration and environment (`loop-entry.mjs env`), starts the
+ * daemon detached, then serves the dashboard in the foreground. Ctrl-C closes only
+ * the dashboard; the daemon keeps running until `loop down` / `loop stop`. The
+ * shipped `.agents/aidlc/scripts/loop.sh|loop.cmd` wrappers forward to these commands.
+ */
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { packageVersion } from "../workflow.js";
+import { daemonHealth, daemonStatus, ensureDaemon, pidAlive, stopDaemon } from "../ui/daemon.js";
+import { daemonLogPath, loopDataDir, loopEntryPath, openBrowser, readCredentialFile, scrubbedEnv } from "../ui/options.js";
+import { startUiServer } from "../ui/server.js";
+const SWITCHES = new Set(["--open", "--no-ui", "--now", "--json"]);
+const VALUES = new Set(["--root", "--loop-env", "--port", "--host", "--reviewer-token-file"]);
+/** Parses `--flag value` / `--switch` options against the per-action allowlist. */
+export const parseLauncherArgs = (args, allowed) => {
+    const values = new Map();
+    const switches = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index] ?? "";
+        if (!allowed.includes(key))
+            throw new Error(`Unknown loop option: ${key}`);
+        if (SWITCHES.has(key)) {
+            switches.add(key);
+            continue;
+        }
+        const entry = args[index + 1];
+        if (!VALUES.has(key) || entry === undefined || entry.startsWith("--") || values.has(key))
+            throw new Error(`${key} requires a value`);
+        values.set(key, entry);
+        index += 1;
+    }
+    return { root: resolve(values.get("--root") ?? "."), values, switches };
+};
+/** `AIDLC_ENV_FILE` for children when `--loop-env` is given (resolved against the caller's cwd). */
+const envOverlay = (parsed) => {
+    const file = parsed.values.get("--loop-env");
+    return file ? { AIDLC_ENV_FILE: resolve(file) } : {};
+};
+const readConfig = (root) => {
+    try {
+        return JSON.parse(readFileSync(join(root, ".agents", "config.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Fails with actionable guidance unless the project is installed with local loop mode. */
+const requireLocalLoop = (root) => {
+    if (!existsSync(loopEntryPath(root)))
+        throw new Error(`AI-DLC is not installed in ${root}; run: npx @felixdotgo/aidlc-kit init --loop-mode local`);
+    const mode = readConfig(root)?.loop?.mode ?? "off";
+    if (mode === "fleet")
+        throw new Error("loop up/down manage the local daemon; this project uses fleet mode (see docs/loop-runbook.md#fleet-multi-machine)");
+    if (mode !== "local")
+        throw new Error([
+            "Loop mode is off. Enable it in .agents/config.json:",
+            '  "loop": { "mode": "local", "agents": { "lead": "opencode", "workers": { "worker-a": "opencode" } } }',
+            "(providers: codex, claude, or opencode), or run: npx @felixdotgo/aidlc-kit init --loop-mode local",
+        ].join("\n"));
+};
+/** Runs `loop-entry.mjs env` for `root`; returns its exit status (output inherited or captured). */
+const envReport = (root, overlay, options = {}) => {
+    const result = spawnSync(process.execPath, [loopEntryPath(root), "env", root, ...(options.json ? ["--json"] : [])], {
+        cwd: root, encoding: "utf8", env: scrubbedEnv(overlay), stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+};
+/* ---- Installing CLI record (`.agents/data/loop/cli.json`) ----
+ * `init`/`upgrade` record the CLI that wrote `.agents/`, so `loop.sh`/`loop.cmd` run that
+ * exact build even when it came from the npx cache or a local `.tgz` (npx caches those by
+ * spec, so `npx --no-install @felixdotgo/aidlc-kit` cannot find them). Machine-local data,
+ * next to daemon.lock and daemon.log; never part of the managed manifest. */
+export const installerCliPath = (root) => join(loopDataDir(root), "cli.json");
+export const recordInstallerCli = (root) => {
+    try {
+        mkdirSync(loopDataDir(root), { recursive: true });
+        const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
+        writeFileSync(installerCliPath(root), `${JSON.stringify({ cli, version: packageVersion(), recordedAt: new Date().toISOString() }, null, 2)}\n`);
+    }
+    catch (error) {
+        console.warn(`warning: could not record the aidlc-kit CLI for the loop launcher (${error instanceof Error ? error.message : String(error)}); install the package in the project to use loop.sh`);
+    }
+};
+/* ---- Dashboard process record (`.agents/data/loop/ui.json`) ---- */
+export const uiStatePath = (root) => join(loopDataDir(root), "ui.json");
+/** The recorded dashboard, if any. `running` only means the pid exists; use
+ * `dashboardReachable` before trusting or signalling it (the pid may have been reused). */
+export const readUiRecord = (root) => {
+    try {
+        const record = JSON.parse(readFileSync(uiStatePath(root), "utf8"));
+        if (typeof record.pid !== "number" || typeof record.url !== "string")
+            return undefined;
+        return { pid: record.pid, url: record.url, startedAt: String(record.startedAt ?? ""), ...(typeof record.instance === "string" ? { instance: record.instance } : {}), running: pidAlive(record.pid) };
+    }
+    catch {
+        return undefined;
+    }
+};
+/** True when the recorded dashboard itself still answers: the URL serves the same random
+ * instance id the record holds (another project's dashboard on that port does not match). */
+export const dashboardReachable = async (record) => {
+    if (!record.instance)
+        return false;
+    try {
+        const response = await fetch(`${record.url}/api/instance`, { signal: AbortSignal.timeout(3000) });
+        const body = await response.json();
+        return response.ok && body.instance === record.instance;
+    }
+    catch {
+        return false;
+    }
+};
+/** A URL this machine can reach for a wildcard bind (0.0.0.0 / ::), else the bound host. */
+const recordHost = (host) => host === "0.0.0.0" ? "127.0.0.1" : host === "::" ? "::1" : host;
+const validPort = (raw) => {
+    const port = Number(raw ?? 4173);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("--port must be an integer between 1 and 65535");
+    return port;
+};
+/** Loopback binds are reachable only from this machine; anything else exposes the dashboard. */
+const LOOPBACK_BINDS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+export const isLoopbackHost = (host) => LOOPBACK_BINDS.has(host.toLowerCase());
+/** Printed when the dashboard listens on a non-loopback address: it has no authentication. */
+export const EXPOSED_WARNING = "Warning: the dashboard has no authentication; expose it only on a trusted network.";
+/** Serves the dashboard until SIGINT/SIGTERM. `record` writes ui.json so `loop down`/`up` can find it. */
+export const serveDashboard = async (options) => {
+    const { root, host } = options;
+    const port = validPort(String(options.port));
+    const reviewerToken = options.reviewerTokenFile ? readCredentialFile(root, options.reviewerTokenFile, { create: false }) : undefined;
+    const instance = randomUUID();
+    const { server, port: boundPort } = await startUiServer({ root, host, port, instance, ...(reviewerToken ? { reviewerToken } : {}) });
+    const base = `http://${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${boundPort}`;
+    console.log(`Loop (AI-DLC UI) listening on ${base} (Ctrl-C to stop)`);
+    console.log(`Open: ${base}`);
+    if (!isLoopbackHost(host))
+        console.log(EXPOSED_WARNING);
+    if (options.record) {
+        mkdirSync(loopDataDir(root), { recursive: true });
+        const local = recordHost(host);
+        const url = `http://${local.includes(":") ? `[${local}]` : local}:${boundPort}`;
+        writeFileSync(uiStatePath(root), `${JSON.stringify({ pid: process.pid, url, instance, startedAt: new Date().toISOString() })}\n`);
+    }
+    if (options.open)
+        openBrowser(base);
+    await new Promise((resolveClose) => {
+        const close = () => { server.close(() => resolveClose()); server.closeAllConnections?.(); };
+        process.once("SIGINT", close);
+        process.once("SIGTERM", close);
+    });
+    if (options.record && readUiRecord(root)?.pid === process.pid)
+        rmSync(uiStatePath(root), { force: true });
+};
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+const logTail = (root, lines = 15) => {
+    try {
+        return readFileSync(daemonLogPath(root), "utf8").trimEnd().split("\n").slice(-lines).join("\n");
+    }
+    catch {
+        return "";
+    }
+};
+/** Env file of this start: `--loop-env`, `AIDLC_ENV_FILE`, or the default. */
+const envFilePath = (root, overlay) => resolve(root, overlay.AIDLC_ENV_FILE ?? process.env.AIDLC_ENV_FILE ?? join(".agents", "loop.env"));
+/** Starts the daemon unless it runs; confirms it survived start-up. Returns false on failure. */
+const startDaemon = async (root, overlay) => {
+    const current = daemonStatus(root);
+    if (current.running) {
+        console.log(`Loop daemon already running (pid ${current.pid}${current.startedAt ? `, started ${current.startedAt}` : ""})`);
+        try {
+            if (current.startedAt && statSync(envFilePath(root, overlay)).mtimeMs > Date.parse(current.startedAt)) {
+                console.log("  note: the env file changed after the daemon started; restart it to apply: loop down, then loop up");
+            }
+        }
+        catch { /* no env file */ }
+        return true;
+    }
+    const started = ensureDaemon(root, overlay);
+    // The daemon writes its lock right after the environment check; an early exit means start-up failed.
+    for (let waited = 0; waited < 5000; waited += 250) {
+        await sleep(250);
+        if (daemonStatus(root).running) {
+            console.log(`Started the loop daemon (pid ${daemonStatus(root).pid}); log: ${daemonLogPath(root)}`);
+            return true;
+        }
+        if (started.pid !== null && !pidAlive(started.pid))
+            break;
+    }
+    if (daemonStatus(root).running)
+        return true;
+    if (started.pid !== null && pidAlive(started.pid)) {
+        console.log(`Loop daemon is starting (pid ${started.pid}); log: ${daemonLogPath(root)}`);
+        return true;
+    }
+    console.error(`The loop daemon exited during start-up. Last lines of ${daemonLogPath(root)}:`);
+    console.error(logTail(root) || "  (empty)");
+    return false;
+};
+export const loopUp = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--loop-env", "--port", "--host", "--open", "--no-ui", "--reviewer-token-file"]);
+    const { root } = parsed;
+    requireLocalLoop(root);
+    const port = validPort(parsed.values.get("--port"));
+    const overlay = envOverlay(parsed);
+    if (envReport(root, overlay).status !== 0) {
+        console.error("\nFix the errors above, then run loop up again.");
+        process.exitCode = 1;
+        return;
+    }
+    console.log("");
+    if (!await startDaemon(root, overlay)) {
+        process.exitCode = 1;
+        return;
+    }
+    if (parsed.switches.has("--no-ui")) {
+        console.log("Dashboard not started (--no-ui). Start it with: aidlc-kit ui");
+        return;
+    }
+    const ui = readUiRecord(root);
+    if (ui?.running && ui.pid !== process.pid && await dashboardReachable(ui)) {
+        console.log(`Dashboard already running at ${ui.url} (pid ${ui.pid}); open it there, or stop it with loop down.`);
+        return;
+    }
+    // A daemon the dashboard starts later (New task after loop stop) loads the same env file.
+    if (overlay.AIDLC_ENV_FILE)
+        process.env.AIDLC_ENV_FILE = overlay.AIDLC_ENV_FILE;
+    await serveDashboard({
+        root, host: parsed.values.get("--host") ?? "127.0.0.1", port, open: parsed.switches.has("--open"), record: true,
+        ...(parsed.values.has("--reviewer-token-file") ? { reviewerTokenFile: parsed.values.get("--reviewer-token-file") } : {}),
+    });
+    console.log("Dashboard stopped. The loop daemon keeps running; stop it with: loop down");
+};
+const reportStop = (result, now) => {
+    if (!result.wasRunning) {
+        console.log("Loop daemon is not running");
+        return;
+    }
+    if (result.stopped) {
+        console.log(`Stopped the loop daemon (pid ${result.pid})`);
+        return;
+    }
+    console.log(now
+        ? `Loop daemon (pid ${result.pid}) is still shutting down; check again with: loop status`
+        : `Loop daemon (pid ${result.pid}) will stop after its current agent turn. To cancel that turn now: loop stop --now`);
+};
+export const loopStop = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--now"]);
+    const now = parsed.switches.has("--now");
+    reportStop(await stopDaemon(parsed.root, { now }), now);
+};
+export const loopDown = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--now"]);
+    const { root } = parsed;
+    const ui = readUiRecord(root);
+    // Signal only a dashboard that still answers at its recorded URL: after a crash or reboot
+    // the recorded pid may belong to an unrelated process.
+    if (ui?.running && ui.pid !== process.pid && await dashboardReachable(ui)) {
+        try {
+            process.kill(ui.pid, "SIGTERM");
+        }
+        catch { /* already gone */ }
+        for (let waited = 0; waited < 5000 && pidAlive(ui.pid); waited += 200)
+            await sleep(200);
+        console.log(pidAlive(ui.pid) ? `Dashboard (pid ${ui.pid}) did not stop yet` : `Stopped the dashboard (pid ${ui.pid})`);
+        if (!pidAlive(ui.pid))
+            rmSync(uiStatePath(root), { force: true });
+    }
+    else if (ui?.running && ui.pid !== process.pid) {
+        // Not provably ours (busy, or the pid was reused): never signal it; keep the record.
+        console.log(`Dashboard record (pid ${ui.pid}, ${ui.url}) did not answer as this project's dashboard; not stopping it. Close it with Ctrl-C, or delete ${uiStatePath(root)} if it is gone.`);
+    }
+    else if (ui)
+        rmSync(uiStatePath(root), { force: true });
+    const now = parsed.switches.has("--now");
+    reportStop(await stopDaemon(root, { now }), now);
+};
+export const loopEnv = (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--loop-env", "--json"]);
+    if (!existsSync(loopEntryPath(parsed.root)))
+        throw new Error(`AI-DLC is not installed in ${parsed.root}`);
+    const { status } = envReport(parsed.root, envOverlay(parsed), { json: parsed.switches.has("--json") });
+    if (status !== 0)
+        process.exitCode = status;
+};
+/** `loop status` without a task id: daemon, dashboard, and environment at a glance. */
+export const loopOverview = async (args) => {
+    const parsed = parseLauncherArgs(args, ["--root", "--loop-env", "--json"]);
+    const { root } = parsed;
+    if (!existsSync(loopEntryPath(root)))
+        throw new Error(`AI-DLC is not installed in ${root}`);
+    const daemon = daemonStatus(root);
+    const errors = daemon.running ? daemonHealth(root) : [];
+    const record = readUiRecord(root);
+    const ui = record ? { ...record, running: record.running && await dashboardReachable(record) } : undefined;
+    if (parsed.switches.has("--json")) {
+        const env = envReport(root, envOverlay(parsed), { json: true, capture: true });
+        let parsedEnv = null;
+        try {
+            parsedEnv = JSON.parse(env.stdout);
+        }
+        catch {
+            parsedEnv = null;
+        }
+        console.log(JSON.stringify({ daemon: { ...daemon, errors }, ui: ui ?? null, env: parsedEnv }, null, 2));
+        return;
+    }
+    console.log(daemon.running ? `Daemon    : running · pid ${daemon.pid}${daemon.startedAt ? ` · started ${daemon.startedAt}` : ""}` : "Daemon    : stopped (start it with: loop up)");
+    for (const error of errors)
+        console.log(`  error   : ${error.taskId ? `${error.taskId}: ` : "poll: "}${error.message}`);
+    console.log(ui?.running ? `Dashboard : ${ui.url} · pid ${ui.pid}` : "Dashboard : not running (loop up starts it)");
+    console.log(`Log       : ${daemonLogPath(root)}`);
+    console.log("");
+    envReport(root, envOverlay(parsed));
+};

package/dist/src/cli/options.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure argv→options builders: init options, loop flag reads, worker mapping
+ * parsing, and the argv-provided part of MCP setup selections. Prompting for
+ * anything still missing happens in ./prompt.ts.
+ */
+import type { InitOptions } from "../model.js";
+import type { McpSetupOptions } from "../mcp-setup.js";
+export declare const initOptions: (args: string[]) => InitOptions;
+export declare const loopSelection: (args: string[]) => {
+    mode?: string;
+    lead?: string;
+    workers?: string;
+};
+export declare const parseWorkerMapping: (rawWorkers: string) => Record<string, string>;
+/** Argv-provided MCP selections: connection choices stay optional until prompted; the rest always carry defaults. */
+export type McpArgSelections = {
+    deployment?: McpSetupOptions["deployment"];
+    storage?: McpSetupOptions["storage"];
+    bind?: McpSetupOptions["bind"];
+    workspace?: string;
+    pollMs: number;
+    tokenEnv: string;
+    providers: string[];
+};
+export declare const mcpArgSelections: (args: string[]) => McpArgSelections;

package/dist/src/cli/options.js

@@ -0,0 +1,32 @@
+import { flags, rootArg, value } from "./argv.js";
+export const initOptions = (args) => ({
+    root: rootArg(args),
+    agents: (value(args, "--agent") ?? "").split(",").filter(Boolean),
+    all: flags(args).has("--all"),
+    dryRun: flags(args).has("--dry-run"),
+    yes: flags(args).has("--yes"),
+    force: flags(args).has("--force")
+});
+export const loopSelection = (args) => ({ mode: value(args, "--loop-mode"), lead: value(args, "--loop-lead"), workers: value(args, "--loop-workers") });
+export const parseWorkerMapping = (rawWorkers) => {
+    const workers = Object.create(null);
+    for (const entry of rawWorkers.split(",")) {
+        const parts = entry.split("=");
+        if (parts.length !== 2 || !parts[0] || !parts[1] || Object.hasOwn(workers, parts[0]))
+            throw new Error("Invalid or duplicate loop worker mapping");
+        workers[parts[0]] = parts[1];
+    }
+    return workers;
+};
+export const mcpArgSelections = (args) => {
+    const selected = {
+        deployment: value(args, "--deployment"),
+        storage: value(args, "--storage"),
+        bind: value(args, "--bind"),
+        workspace: value(args, "--workspace"),
+        pollMs: Number(value(args, "--poll-ms") ?? 30_000),
+        tokenEnv: value(args, "--token-env") ?? "AIDLC_MCP_TOKEN",
+        providers: (value(args, "--providers") ?? "").split(",").filter(Boolean)
+    };
+    return selected;
+};

package/dist/src/cli/prompt.d.ts

@@ -0,0 +1,9 @@
+import type { LoopConfig } from "../model.js";
+import type { McpSetupOptions } from "../mcp-setup.js";
+export declare const interactive: () => boolean;
+export declare const chooseLoop: (args: string[], upgrade: boolean) => Promise<LoopConfig | undefined>;
+export declare const mcpSetupSelections: (args: string[]) => Promise<Partial<Omit<McpSetupOptions, "root" | "template" | "dryRun" | "enable">>>;
+export declare const confirmGeneral: (options: {
+    dryRun: boolean;
+    yes: boolean;
+}, operation: string) => Promise<boolean>;