@nurix/nustack 0.19.1 → 0.19.3

package/dist/commands/activity.js

@@ -0,0 +1,47 @@
+import { listActivity } from "../lib/hosting/logs.js";
+import { printJsonSuccess } from "../lib/json_output.js";
+import { emitError, emitFail, resolveTarget } from "./deploy.js";
+function renderEvent(event) {
+    const who = event.actorLabel ?? event.actorType ?? "—";
+    const what = event.entityLabel ? `${event.eventType} · ${event.entityLabel}` : event.eventType;
+    return `${event.createdAt}  ${event.channel.padEnd(7)} ${who}  ${what}`;
+}
+export async function runProjectActivity(options, globals) {
+    const command = "project activity";
+    const json = options.json === true;
+    const limit = options.limit === undefined ? undefined : Number(options.limit);
+    if (limit !== undefined && !(Number.isInteger(limit) && limit > 0)) {
+        emitFail(command, json, "INVALID_ARGUMENT", "--limit takes a positive whole number.");
+        return;
+    }
+    const target = await resolveTarget(command, options, globals);
+    if (!target)
+        return;
+    try {
+        const page = await listActivity(target, { cursor: options.cursor, limit, action: options.action });
+        if (json) {
+            printJsonSuccess(command, { projectId: target.projectId, items: page.items, nextCursor: page.nextCursor });
+            return;
+        }
+        if (page.items.length === 0)
+            console.error("No activity on this page.");
+        for (const event of page.items)
+            console.log(renderEvent(event));
+        if (page.nextCursor)
+            console.error(`more: nustack project activity --cursor ${page.nextCursor}`);
+    }
+    catch (error) {
+        emitError(command, json, error);
+    }
+}
+export function registerActivityCommand(projectCommand, getGlobalOptions) {
+    projectCommand
+        .command("activity")
+        .description("Who did what to the Project, on which channel — newest first, one page at a time")
+        .option("--project <id>", "the Project to read (defaults to the bound repository)")
+        .option("--limit <n>", "rows per page (default 50, at most 200)")
+        .option("--action <action>", "one action, or a prefix ending in * (hosting.*)")
+        .option("--cursor <cursor>", "the page after the one that printed this cursor")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runProjectActivity(options, getGlobalOptions()));
+}

package/dist/commands/api.js

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+import { ensureAuthWithRecovery, lastAuthFailure } from "../lib/auth_recovery.js";
+import { assertSafeApiPath } from "../lib/guards.js";
+import { authorizedFetch, resolveNuStackUrl } from "../lib/nustack_client.js";
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+function typedValue(raw) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (raw === "null")
+        return null;
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+function splitPair(raw, flag) {
+    const at = raw.indexOf("=");
+    if (at <= 0)
+        throw new Error(`${flag} takes key=value (got ${raw})`);
+    return [raw.slice(0, at), raw.slice(at + 1)];
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runApi(path, options, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    let url;
+    let body;
+    const headers = new Headers();
+    try {
+        url = assertSafeApiPath(baseUrl, path);
+        const fields = {};
+        for (const pair of options.field ?? []) {
+            const [key, value] = splitPair(pair, "-f");
+            fields[key] = value;
+        }
+        for (const pair of options.rawField ?? []) {
+            const [key, value] = splitPair(pair, "-F");
+            fields[key] = typedValue(value);
+        }
+        if (options.input !== undefined) {
+            if (Object.keys(fields).length > 0)
+                throw new Error("--input and -f/-F are two ways to send a body — use one.");
+            body = options.input === "-" ? await readStdin() : await readFile(options.input, "utf8");
+        }
+        else if (Object.keys(fields).length > 0) {
+            body = JSON.stringify(fields);
+        }
+        for (const raw of options.header ?? []) {
+            const at = raw.indexOf(":");
+            if (at <= 0)
+                throw new Error(`-H takes 'Name: value' (got ${raw})`);
+            headers.set(raw.slice(0, at).trim(), raw.slice(at + 1).trim());
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    if (body !== undefined && !headers.has("Content-Type"))
+        headers.set("Content-Type", "application/json");
+    const auth = await ensureAuthWithRecovery(baseUrl, true);
+    if (!auth) {
+        console.error(lastAuthFailure().message);
+        process.exitCode = 1;
+        return;
+    }
+    headers.set("Authorization", `Bearer ${auth.accessToken}`);
+    const method = (options.method ?? (body === undefined ? "GET" : "POST")).toUpperCase();
+    try {
+        const response = await authorizedFetch(url, { method, headers, body, signal: AbortSignal.timeout(30_000) });
+        if (options.include) {
+            console.error(`HTTP ${response.status} ${response.statusText}`);
+            response.headers.forEach((value, name) => console.error(`${name}: ${value}`));
+            console.error("");
+        }
+        const text = await response.text();
+        if (text)
+            process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+        if (!response.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export function registerApiCommand(program, getGlobalOptions) {
+    program
+        .command("api <path>")
+        .description("Call a NuStack route with this CLI's credential and print the body verbatim (like `gh api`)")
+        .option("-X, --method <method>", "the HTTP method (GET, or POST when a body is given)")
+        .option("-f, --field <key=value>", "a string field of the JSON body (repeatable)", collect)
+        .option("-F, --raw-field <key=value>", "a typed field — numbers, true, false, null (repeatable)", collect)
+        .option("--input <file>", "send a file as the body, or - for stdin")
+        .option("-H, --header <header>", "an extra request header, 'Name: value' (repeatable)", collect)
+        .option("-i, --include", "print the status line and response headers on stderr")
+        .action(async (path, options) => runApi(path, options, getGlobalOptions()));
+}

package/dist/commands/bootstrap.js

@@ -45,7 +45,7 @@ async function printBoundStatus(root) {
         p.log.success(`This repository is bound to Project ${binding.projectId} on branch ${binding.boundBranch}.`);
         p.log.info(`Binding ${binding.id} · ${binding.status} · applied Project sequence ${binding.lastAppliedProjectSequence}` +
             (pending.length > 0 ? ` · ${pending.length} pending inbound` : ""));
-        p.outro("Up to date locally — `nustack project status` for the cloud view, `nustack project sync now` to reconcile.");
+        p.outro("Up to date locally — `nustack status` for the cloud view, `nustack project sync now` to reconcile.");
         return true;
     }
     finally {

package/dist/commands/deploy.js

@@ -0,0 +1,372 @@
+import { ensureAccessToken } from "../lib/auth_grant.js";
+import { ensureAuthWithRecovery, lastAuthFailure } from "../lib/auth_recovery.js";
+import { getHostingStatus, HostingRequestError, listVersions, rollbackHosting, setKeepWarm, startDeploy, watchDeploy, } from "../lib/hosting/client.js";
+import { followRuntimeLogs, getBuildLog, getRuntimeLogs, renderBuildLog, renderRuntimeLine, stateNotice } from "../lib/hosting/logs.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+import { resolveNuStackUrl } from "../lib/nustack_client.js";
+import { resolveProjectId } from "../lib/project_context.js";
+import { projectOverviewJson, readProjectOverview } from "./project.js";
+const DEFAULT_TIMEOUT_MINUTES = 15;
+export function emitFail(command, json, code, message) {
+    if (json)
+        printJsonError(command, { code, message });
+    else {
+        console.error(message);
+        process.exitCode = 1;
+    }
+}
+export function emitError(command, json, error) {
+    if (error instanceof HostingRequestError)
+        emitFail(command, json, error.code, error.message);
+    else
+        emitFail(command, json, "REQUEST_FAILED", error instanceof Error ? error.message : String(error));
+}
+export async function resolveTarget(command, options, globals) {
+    const json = options.json === true;
+    const project = await resolveProjectId(process.cwd(), { project: options.project });
+    if (!project.ok) {
+        emitFail(command, json, "PROJECT_CONTEXT_MISSING", project.message);
+        return null;
+    }
+    const baseUrl = resolveNuStackUrl(globals);
+    const auth = await ensureAuthWithRecovery(baseUrl, json);
+    if (!auth) {
+        const failure = lastAuthFailure();
+        emitFail(command, json, failure.code, failure.message);
+        return null;
+    }
+    return { baseUrl, accessToken: auth.accessToken, projectId: project.projectId };
+}
+export function describeAge(iso, now = Date.now()) {
+    const seconds = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+    const steps = [
+        [86_400, "day"],
+        [3_600, "hour"],
+        [60, "minute"],
+    ];
+    for (const [size, unit] of steps) {
+        if (seconds >= size) {
+            const count = Math.floor(seconds / size);
+            return `${count} ${unit}${count === 1 ? "" : "s"} ago`;
+        }
+    }
+    return "just now";
+}
+function sourceLine(status) {
+    const age = status.settledAt ? `, settled ${describeAge(status.settledAt)}` : "";
+    return `deploying Studio's tree${age} — not this folder`;
+}
+const RED_TAIL_LINES = 40;
+function explainRed(outcome, failingTail) {
+    const lines = [outcome.failedClause ? `v${outcome.version} failed at \`${outcome.failedClause}\`` : `v${outcome.version} failed`];
+    if (failingTail) {
+        lines.push(failingTail.split("\n").slice(-RED_TAIL_LINES).join("\n"));
+        lines.push(`(the whole clause: nustack logs --build ${outcome.version})`);
+    }
+    else if (outcome.summary)
+        lines.push(outcome.summary);
+    if (outcome.redrive === "dispatched")
+        lines.push("Studio opened a coding round to fix this.");
+    return lines.join("\n");
+}
+async function failingTail(target, outcome) {
+    try {
+        const log = await getBuildLog(target, outcome.version);
+        const step = log.steps.find((candidate) => candidate.clause === outcome.failedClause) ?? log.steps.find((candidate) => candidate.state === "failed");
+        return step?.tail || null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseTimeoutMs(raw) {
+    if (raw === undefined)
+        return DEFAULT_TIMEOUT_MINUTES * 60_000;
+    const minutes = Number(raw);
+    return Number.isFinite(minutes) && minutes > 0 ? minutes * 60_000 : null;
+}
+export async function runDeploy(options, globals) {
+    const command = "deploy";
+    const json = options.json === true;
+    const timeoutMs = parseTimeoutMs(options.timeout);
+    if (timeoutMs === null) {
+        emitFail(command, json, "INVALID_ARGUMENT", `--timeout takes a positive number of minutes (got ${options.timeout}).`);
+        return;
+    }
+    const target = await resolveTarget(command, options, globals);
+    if (!target)
+        return;
+    try {
+        console.error(sourceLine(await getHostingStatus(target)));
+        const started = await startDeploy(target);
+        if (options.wait === false) {
+            if (json)
+                printJsonSuccess(command, { projectId: target.projectId, version: started.version, state: "building" });
+            else
+                console.log(String(started.version));
+            return;
+        }
+        const watched = await watchDeploy(target, started.version, {
+            timeoutMs,
+            onState: (state) => console.error(`${state} v${started.version}`),
+        });
+        if (watched.kind === "timeout") {
+            emitFail(command, json, "DEPLOY_TIMEOUT", `v${started.version} is still running on Studio — \`nustack status\` shows where it is.`);
+            return;
+        }
+        if (watched.kind === "superseded") {
+            emitFail(command, json, "DEPLOY_OUTCOME_UNKNOWN", `v${started.version} finished, but v${watched.laterVersion} settled after it and Studio keeps only the latest outcome — \`nustack versions\` shows which is live.`);
+            return;
+        }
+        const { outcome, status } = watched;
+        if (!outcome.ok) {
+            const explanation = explainRed(outcome, await failingTail(target, outcome));
+            if (json)
+                printJsonError(command, { code: "DEPLOY_FAILED", message: explanation });
+            else
+                emitFail(command, false, "DEPLOY_FAILED", explanation);
+            return;
+        }
+        if (json)
+            printJsonSuccess(command, { projectId: target.projectId, version: started.version, url: status.url, outcome });
+        else
+            console.log(status.url ?? `v${started.version} is live`);
+    }
+    catch (error) {
+        emitError(command, json, error);
+    }
+}
+function hostingLines(status) {
+    const lines = [];
+    if (status.live) {
+        lines.push(`live      v${status.live.version} · ${status.url ?? "—"} · promoted ${describeAge(status.live.promotedAt)} by ${status.live.promotedBy}`);
+    }
+    else if (status.url) {
+        lines.push(`live      nothing yet · ${status.url}`);
+    }
+    if (status.buildingVersion !== null)
+        lines.push(`building  v${status.buildingVersion} · ${status.deployState ?? "building"}`);
+    const last = status.lastOutcome;
+    if (last && !last.ok) {
+        const clause = last.failedClause ? `failed at \`${last.failedClause}\`` : "failed";
+        lines.push(`last      v${last.version} · ${clause}${last.redrive === "dispatched" ? " · Studio opened a coding round" : ""}`);
+    }
+    lines.push(`warm      ${status.isPinned ? "on" : "off"}`);
+    return lines;
+}
+function overviewLines(projectId, overview) {
+    const { cloudProject, binding, compatibility } = overview;
+    const name = cloudProject ? `${cloudProject.label} · ${cloudProject.status} / ${cloudProject.publicationState}` : `${projectId} · cloud unreachable — local-only view`;
+    const lines = [binding ? `${name} · bound to ${binding.repositoryRoot}` : `${name} · this folder is not bound on this device`];
+    if (binding)
+        lines.push(`binding   ${binding.id} on ${binding.boundBranch} (${binding.status}) · applied@${binding.lastAppliedProjectSequence}`);
+    lines.push(`toolkit   ${compatibility.blocksWrites ? `BLOCKED — ${compatibility.reason}` : "compatible"}`);
+    return lines;
+}
+export async function runStatus(options, globals) {
+    const command = "status";
+    const json = options.json === true;
+    const cwd = process.cwd();
+    const project = await resolveProjectId(cwd, { project: options.project });
+    if (!project.ok) {
+        emitFail(command, json, "PROJECT_CONTEXT_MISSING", project.message);
+        return;
+    }
+    const baseUrl = resolveNuStackUrl(globals);
+    const auth = await ensureAccessToken(baseUrl).catch(() => null);
+    const overview = await readProjectOverview(project.projectId, cwd, baseUrl, auth?.accessToken ?? null);
+    let hosting = null;
+    if (auth && overview.cloudProject) {
+        hosting = await getHostingStatus({ baseUrl, accessToken: auth.accessToken, projectId: project.projectId }).catch(() => null);
+    }
+    if (json) {
+        printJsonSuccess(command, { ...projectOverviewJson(project.projectId, overview), hosting });
+        return;
+    }
+    const lines = overviewLines(project.projectId, overview);
+    if (hosting)
+        lines.splice(1, 0, ...hostingLines(hosting));
+    console.log(lines.join("\n"));
+}
+export async function runVersions(options, globals) {
+    const command = "versions";
+    const json = options.json === true;
+    const target = await resolveTarget(command, options, globals);
+    if (!target)
+        return;
+    try {
+        const [list, status] = await Promise.all([listVersions(target), getHostingStatus(target)]);
+        const rollbackTarget = status.live && status.previous ? status.previousVersion : null;
+        const rows = list.versions.map((row) => ({
+            version: row.version,
+            createdAt: row.createdAt,
+            seam: row.seam,
+            isLive: row.isLive,
+            isStale: row.isStale,
+            isRollbackTarget: row.version === rollbackTarget,
+        }));
+        if (json) {
+            printJsonSuccess(command, { projectId: target.projectId, versions: rows });
+            return;
+        }
+        if (rows.length === 0) {
+            console.log("No versions yet — nothing has been published from Studio.");
+            return;
+        }
+        for (const row of rows) {
+            const marks = [row.isLive ? "live" : "", row.isRollbackTarget ? "rollback target" : "", row.isStale ? "stale" : ""].filter(Boolean).join(" · ");
+            console.log(`v${String(row.version).padEnd(5)} ${row.createdAt}  ${row.seam.padEnd(10)} ${marks}`.trimEnd());
+        }
+    }
+    catch (error) {
+        emitError(command, json, error);
+    }
+}
+export async function runRollback(options, globals) {
+    const command = "rollback";
+    const json = options.json === true;
+    const target = await resolveTarget(command, options, globals);
+    if (!target)
+        return;
+    try {
+        const moved = await rollbackHosting(target);
+        const status = await getHostingStatus(target);
+        if (json) {
+            printJsonSuccess(command, { projectId: target.projectId, liveVersion: moved.liveVersion, previousVersion: moved.previousVersion, url: status.url });
+            return;
+        }
+        console.error(`rolled back to v${moved.liveVersion}`);
+        console.log(status.url ?? `v${moved.liveVersion} is live`);
+    }
+    catch (error) {
+        emitError(command, json, error);
+    }
+}
+function readPositive(raw) {
+    if (raw === undefined)
+        return undefined;
+    return /^[1-9]\d*$/.test(raw) ? Number(raw) : null;
+}
+export async function runLogs(options, globals) {
+    const command = "logs";
+    const json = options.json === true;
+    const version = typeof options.build === "string" ? readPositive(options.build) : undefined;
+    const limit = readPositive(options.limit);
+    if (version === null || limit === null) {
+        emitFail(command, json, "INVALID_ARGUMENT", "--build's version and --limit take positive whole numbers.");
+        return;
+    }
+    if (options.follow && (options.build || json)) {
+        emitFail(command, json, "INVALID_ARGUMENT", "--follow streams runtime lines; it combines with neither --build nor --json.");
+        return;
+    }
+    const target = await resolveTarget(command, options, globals);
+    if (!target)
+        return;
+    try {
+        if (options.build) {
+            const status = version === undefined ? await getHostingStatus(target) : null;
+            const chosen = version ?? status?.buildingVersion ?? status?.lastOutcome?.version ?? status?.liveVersion ?? null;
+            if (chosen === null) {
+                emitFail(command, json, "INVALID_STATE", "No version has been graded yet — nothing has a build log.");
+                return;
+            }
+            const log = await getBuildLog(target, chosen);
+            if (json)
+                printJsonSuccess(command, { projectId: target.projectId, ...log });
+            else
+                console.log(renderBuildLog(log));
+            return;
+        }
+        const page = await getRuntimeLogs(target, { limit });
+        if (json) {
+            printJsonSuccess(command, { projectId: target.projectId, ...page });
+            return;
+        }
+        const notice = stateNotice(page);
+        if (notice)
+            console.error(notice);
+        for (const line of page.lines)
+            console.log(renderRuntimeLine(line));
+        if (options.follow) {
+            await followRuntimeLogs(target, page, { line: (text) => console.log(text), notice: (text) => console.error(text) }, limit);
+        }
+    }
+    catch (error) {
+        emitError(command, json, error);
+    }
+}
+const SETTING_KEYS = ["keep-warm"];
+export async function runProjectSet(key, value, options, globals) {
+    const command = "project set";
+    const json = options.json === true;
+    if (!SETTING_KEYS.includes(key)) {
+        emitFail(command, json, "INVALID_ARGUMENT", `Unknown setting "${key}" — the settings are: ${SETTING_KEYS.join(", ")}.`);
+        return;
+    }
+    if (value !== "on" && value !== "off") {
+        emitFail(command, json, "INVALID_ARGUMENT", `keep-warm takes on or off (got "${value}").`);
+        return;
+    }
+    const target = await resolveTarget(command, options, globals);
+    if (!target)
+        return;
+    try {
+        const outcome = await setKeepWarm(target, value === "on");
+        if (json) {
+            printJsonSuccess(command, { projectId: target.projectId, key, value, ...outcome });
+            return;
+        }
+        console.log(`keep-warm ${value} · ${outcome.slotsUsed} of ${outcome.slots} always-on slot(s) in use`);
+    }
+    catch (error) {
+        emitError(command, json, error);
+    }
+}
+export function registerDeployCommands(program, getGlobalOptions) {
+    program
+        .command("deploy")
+        .description("Grade and publish the tree Studio holds for this Project (never this folder), then print the live URL")
+        .option("--project <id>", "the Project to deploy (defaults to the bound repository)")
+        .option("--no-wait", "exit once the deploy starts, printing its version")
+        .option("--timeout <minutes>", `stop watching after this long; the deploy keeps running (default ${DEFAULT_TIMEOUT_MINUTES})`)
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runDeploy(options, getGlobalOptions()));
+    program
+        .command("status")
+        .description("The Project on one screen: what is live, what is building, the last outcome, keep-warm, the binding")
+        .option("--project <id>", "the Project to show (defaults to the bound repository)")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runStatus(options, getGlobalOptions()));
+    program
+        .command("versions")
+        .description("The Project's versions, marking the live one and the one a rollback restores")
+        .option("--project <id>", "the Project to list (defaults to the bound repository)")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runVersions(options, getGlobalOptions()));
+    program
+        .command("rollback")
+        .description("Make the previous version live again — one step back")
+        .option("--project <id>", "the Project to roll back (defaults to the bound repository)")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runRollback(options, getGlobalOptions()));
+}
+export function registerLogsCommand(program, getGlobalOptions) {
+    program
+        .command("logs")
+        .description("What the Project's backend printed recently (--follow keeps reading), or with --build a version's build log")
+        .option("--project <id>", "the Project to read (defaults to the bound repository)")
+        .option("--build [version]", "a graded version's build log instead of the runtime output (defaults to the one building, then the last graded, then the live one)")
+        .option("--follow", "keep reading new lines until interrupted")
+        .option("--limit <n>", "lines per read (app-hosting keeps the newest 1000)")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runLogs(options, getGlobalOptions()));
+}
+export function registerProjectSetCommand(projectCommand, getGlobalOptions) {
+    projectCommand
+        .command("set <key> <value>")
+        .description(`Change a Project setting (${SETTING_KEYS.join(", ")}); keep-warm takes on or off`)
+        .option("--project <id>", "the Project to change (defaults to the bound repository)")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (key, value, options) => runProjectSet(key, value, options, getGlobalOptions()));
+}

package/dist/commands/init.js

@@ -255,7 +255,7 @@ async function confirm(message) {
 function reportSuccess(result) {
     p.log.success(`Bound to Project ${result.projectId} on branch ${result.boundBranch} (binding ${result.bindingId}).`);
     p.log.info(`Toolkit ${result.toolkit.name}@${result.toolkit.version}. No Git push, pull, or remote was created.`);
-    p.outro("Ready — `nustack project status` · `nustack docs list` · `nustack project sync now`.");
+    p.outro("Ready — `nustack status` · `nustack docs list` · `nustack project sync now`.");
 }
 function reportFailure(failure) {
     p.log.error(failure.message);

package/dist/commands/mcp.js

@@ -0,0 +1,103 @@
+import { ensureAuthWithRecovery } from "../lib/auth_recovery.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+import { authorizedFetch, resolveNuStackUrl } from "../lib/nustack_client.js";
+import { resolveProjectId } from "../lib/project_context.js";
+import { doorUrlFor, runRelay } from "../lib/mcp/relay.js";
+import { applyEdit, ClientConfigError, detectClients, MCP_CLIENTS, planEdit, targetFor } from "../lib/mcp/clients.js";
+async function runServe(options, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    const flag = options.project?.trim();
+    const bound = flag ? null : await resolveProjectId(process.cwd(), {});
+    const defaultProjectId = flag ?? (bound?.ok ? bound.projectId : null);
+    const doorUrl = doorUrlFor(baseUrl, process.env.NUSTACK_MCP_URL);
+    process.stderr.write(`nustack mcp: relaying to ${doorUrl}${defaultProjectId ? `, default project ${defaultProjectId}` : ""}\n`);
+    await runRelay({
+        doorUrl,
+        bearer: async () => (await ensureAuthWithRecovery(baseUrl, true))?.accessToken ?? null,
+        defaultProjectId,
+        fetch: (url, init) => authorizedFetch(url, { ...init, signal: AbortSignal.timeout(60_000) }),
+        input: process.stdin,
+        output: process.stdout,
+        log: (line) => process.stderr.write(`${line}\n`),
+    });
+}
+function chosenClients(raw) {
+    if (!raw) {
+        const found = detectClients();
+        return found.length > 0 ? found : ["claude"];
+    }
+    const names = raw.split(",").map((name) => name.trim()).filter(Boolean);
+    const unknown = names.filter((name) => !MCP_CLIENTS.includes(name));
+    if (unknown.length > 0)
+        return `Unknown client ${unknown.join(", ")}; choose from ${MCP_CLIENTS.join(", ")}.`;
+    return names;
+}
+async function runEdit(command, options) {
+    const json = options.json === true;
+    const fail = (code, message) => {
+        if (json)
+            printJsonError(command, { code, message });
+        else {
+            console.error(message);
+            process.exitCode = 1;
+        }
+    };
+    const scope = (options.scope ?? "user");
+    if (scope !== "user" && scope !== "project")
+        return fail("INVALID_ARGUMENT", "--scope takes user or project.");
+    const clients = chosenClients(options.client);
+    if (typeof clients === "string")
+        return fail("INVALID_ARGUMENT", clients);
+    const install = command === "mcp install";
+    const rows = [];
+    for (const client of clients) {
+        const target = targetFor(client, scope, process.cwd());
+        if (!target) {
+            rows.push({ client, scope, path: null, action: "skipped", reason: `${client} has no ${scope}-scope MCP configuration` });
+            continue;
+        }
+        try {
+            const planned = await planEdit(target, install);
+            if (!options.dryRun)
+                await applyEdit(target, planned);
+            rows.push({ client, scope, path: target.file, action: planned.action });
+        }
+        catch (error) {
+            if (!(error instanceof ClientConfigError))
+                throw error;
+            rows.push({ client, scope, path: target.file, action: "skipped", reason: error.message });
+        }
+    }
+    if (json) {
+        printJsonSuccess(command, { dryRun: options.dryRun === true, changes: rows });
+        return;
+    }
+    for (const row of rows) {
+        const verb = options.dryRun && (row.action === "added" || row.action === "updated" || row.action === "removed") ? `would be ${row.action}` : row.action;
+        console.log(`${row.client.padEnd(7)} ${verb.padEnd(16)} ${row.path ?? ""}${row.reason ? `  (${row.reason})` : ""}`);
+    }
+    if (install && !options.dryRun && rows.some((row) => row.action === "added" || row.action === "updated")) {
+        console.error("Restart the agent to pick up the nustack MCP server.");
+    }
+}
+export function registerMcpCommands(program, getGlobalOptions) {
+    const mcp = program.command("mcp").description("NuStack as an MCP server for coding agents");
+    mcp.command("serve")
+        .description("Relay an agent's MCP stdio to NuStack with this CLI's credential (launched by the agent, not by you)")
+        .option("--project <id>", "the Project a Project tool acts on when the agent names none (default: this folder's)")
+        .action(async (options) => runServe(options, getGlobalOptions()));
+    mcp.command("install")
+        .description("Register `nustack mcp serve` with Claude Code, Cursor, Codex or VS Code")
+        .option("--client <names>", `comma-separated: ${MCP_CLIENTS.join(", ")} (default: the clients found on this machine)`)
+        .option("--scope <scope>", "user (your home folder) or project (this folder's files)", "user")
+        .option("--dry-run", "print each file and the change, write nothing")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runEdit("mcp install", options));
+    mcp.command("uninstall")
+        .description("Remove the entry `nustack mcp install` wrote, leaving everything else as it was")
+        .option("--client <names>", `comma-separated: ${MCP_CLIENTS.join(", ")} (default: the clients found on this machine)`)
+        .option("--scope <scope>", "user or project", "user")
+        .option("--dry-run", "print each file and the change, write nothing")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runEdit("mcp uninstall", options));
+}