@numa-tech/numa 1.12.7 → 1.12.10

package/dist/application-onboarding/commands.js

@@ -0,0 +1,694 @@
+import { readFile, stat } from "node:fs/promises";
+import process from "node:process";
+import { loadAppConfig } from "../app-config.js";
+import { loadConfig } from "../config.js";
+import { registerApplicationCandidateCommands } from "../application-candidates/commands.js";
+import { OnboardingClient } from "./client.js";
+import { OnboardingError, sanitizeOnboardingOutput } from "./errors.js";
+import { OnboardingModeSchema, OnboardingEventOutputSchema, OnboardingSessionStateSchema, OnboardingSpecSchema, ScmProviderSchema } from "./schemas.js";
+import { readScmAdminConnectionInput, readScmCredentialBundle } from "./scm-credentials.js";
+import { runOnboardingTui } from "./tui.js";
+const TERMINAL_STATES = new Set(["COMPLETED", "FAILED", "CANCELLED"]);
+const ACTIVE_STATES = new Set(["RUNNING", "WAITING_EXTERNAL", "VERIFYING"]);
+const MAX_SPEC_BYTES = 262_144;
+const STATE_SUMMARIES = {
+    DRAFT: "服务端草稿尚未完成",
+    READY: "草稿完整，等待服务端预检",
+    PLANNED: "服务端计划已锁定，等待 apply",
+    RUNNING: "服务端正在执行入驻步骤",
+    WAITING_EXTERNAL: "服务端正在等待外部系统或人工条件",
+    VERIFYING: "副作用步骤已完成，服务端正在验收",
+    COMPLETED: "服务端验收已完成",
+    FAILED: "服务端执行失败；请依据事件中的 errorCode 和 recoveryAction 恢复",
+    CANCELLED: "服务端已取消尚未开始的步骤；既有外部资源未回滚"
+};
+function addExamples(command, examples, notes = []) {
+    const noteSection = notes.length
+        ? `\n说明:\n${notes.map((item) => `  - ${item}`).join("\n")}\n`
+        : "";
+    return command.addHelpText("after", `${noteSection}\nExamples:\n${examples.map((item) => `  ${item}`).join("\n")}\n`);
+}
+function snakeCase(key) {
+    return key.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toLowerCase();
+}
+function stableOutput(value) {
+    const safe = sanitizeOnboardingOutput(value);
+    if (Array.isArray(safe))
+        return safe.map(stableOutput);
+    if (safe && typeof safe === "object") {
+        return Object.fromEntries(Object.entries(safe).map(([key, item]) => [snakeCase(key), stableOutput(item)]));
+    }
+    return safe;
+}
+export function publicOnboardingEvent(event) {
+    if (event.output == null)
+        return { ...event, output: event.output };
+    const parsed = OnboardingEventOutputSchema.safeParse(event.output);
+    return { ...event, output: parsed.success ? parsed.data : undefined };
+}
+export function onboardingExecutionView(session, events = []) {
+    const safeEvents = events
+        .map(publicOnboardingEvent)
+        .sort((left, right) => left.sequenceNo - right.sequenceNo);
+    const eventOutput = Object.assign({}, ...safeEvents.map((event) => event.output ?? {}));
+    const failed = [...safeEvents].reverse().find((event) => event.stepState === "FAILED" || event.errorCode != null);
+    return {
+        state: session.state,
+        currentStep: session.currentStep ?? null,
+        summary: STATE_SUMMARIES[session.state],
+        active: ACTIVE_STATES.has(session.state),
+        terminal: TERMINAL_STATES.has(session.state),
+        lastSequence: safeEvents.reduce((maximum, event) => Math.max(maximum, event.sequenceNo), 0),
+        retryable: failed?.retryable ?? false,
+        errorCode: failed?.errorCode ?? null,
+        eventOutput
+    };
+}
+function executionText(session, events = []) {
+    const view = onboardingExecutionView(session, events);
+    const lines = [sessionLine(session), `状态说明: ${view.summary}`];
+    if (view.errorCode)
+        lines.push(`error-code: ${view.errorCode}${view.retryable ? " (retryable)" : ""}`);
+    if (view.eventOutput.recoveryAction)
+        lines.push(`recovery-action: ${view.eventOutput.recoveryAction}`);
+    if (view.eventOutput.retryAfterSeconds != null)
+        lines.push(`retry-after: ${view.eventOutput.retryAfterSeconds}s`);
+    if (view.state === "COMPLETED") {
+        const resources = [
+            view.eventOutput.applicationId == null ? undefined : `application:${view.eventOutput.applicationId}`,
+            view.eventOutput.repositoryId == null ? undefined : `repository:${view.eventOutput.repositoryId}`,
+            view.eventOutput.repositoryFullName,
+            view.eventOutput.changeRequestUrl
+        ].filter((value) => value != null && value !== "");
+        if (resources.length)
+            lines.push(`结果: ${resources.join(" · ")}`);
+    }
+    return lines.join("\n");
+}
+async function jsonEnabled(command) {
+    const configured = await loadAppConfig();
+    return Boolean(command.optsWithGlobals().json || configured.output === "json");
+}
+async function output(command, payload, textValue) {
+    if (await jsonEnabled(command)) {
+        process.stdout.write(`${JSON.stringify(stableOutput(payload), null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${String(sanitizeOnboardingOutput(textValue))}\n`);
+    }
+}
+export function parseOnboardingMode(value) {
+    const parsed = OnboardingModeSchema.safeParse(value.trim().toUpperCase());
+    if (!parsed.success) {
+        throw new OnboardingError("mode must be new or existing.", "onboarding_input_invalid");
+    }
+    return parsed.data;
+}
+export function parseApplicationCatalogOptionType(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!["team", "system", "business-domain", "environment"].includes(normalized)) {
+        throw new OnboardingError("type must be team, system, business-domain, or environment.", "onboarding_input_invalid");
+    }
+    return normalized;
+}
+function catalogOptionLine(item) {
+    const id = item.id ?? "-";
+    const code = item.code ?? item.key ?? item.slug ?? "-";
+    const name = item.name ?? item.displayName ?? item.label ?? "-";
+    return `${String(id)}\t${String(code)}\t${String(name)}`;
+}
+function parseSessionState(value) {
+    if (value == null)
+        return undefined;
+    const parsed = OnboardingSessionStateSchema.safeParse(value.trim().toUpperCase());
+    if (!parsed.success) {
+        throw new OnboardingError("state is not a supported onboarding session state.", "onboarding_input_invalid");
+    }
+    return parsed.data;
+}
+function nonNegativeInteger(value, label, fallback) {
+    if (value == null)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new OnboardingError(`${label} must be a non-negative integer.`, "onboarding_input_invalid");
+    }
+    return parsed;
+}
+function positiveInteger(value, label, fallback, maximum = Number.MAX_SAFE_INTEGER) {
+    if (value == null && fallback != null)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > maximum) {
+        throw new OnboardingError(`${label} must be an integer between 1 and ${maximum}.`, "onboarding_input_invalid");
+    }
+    return parsed;
+}
+function revision(value) {
+    if (value == null) {
+        throw new OnboardingError("version is required.", "onboarding_scm_input_invalid");
+    }
+    return nonNegativeInteger(value, "version", 0);
+}
+function parseScmProvider(value) {
+    if (!value)
+        return undefined;
+    const parsed = ScmProviderSchema.safeParse(value.trim().toUpperCase());
+    if (!parsed.success)
+        throw new OnboardingError("provider must be github or codeup.", "onboarding_scm_input_invalid");
+    return parsed.data;
+}
+function safeCursor(value) {
+    const cursor = value?.trim();
+    if (!cursor)
+        return undefined;
+    if (cursor.length > 4096 || /[\u0000-\u001f\u007f]/u.test(cursor)) {
+        throw new OnboardingError("cursor must be at most 4096 printable characters.", "onboarding_scm_input_invalid");
+    }
+    return cursor;
+}
+export async function resolveScmConnection(client, code) {
+    const normalized = code.trim();
+    if (!normalized)
+        throw new OnboardingError("SCM connection code is required.", "onboarding_scm_input_invalid");
+    const result = await client.listScmConnections({ search: normalized });
+    const matches = result.items.filter((connection) => connection.code === normalized);
+    if (matches.length !== 1) {
+        throw new OnboardingError(`SCM connection not found or ambiguous: ${normalized}`, "onboarding_scm_connection_not_found");
+    }
+    return matches[0];
+}
+export function scmCredentialUpdate(version, authType, credential) {
+    if (authType === "GITHUB_APP")
+        return { version, githubApp: credential };
+    if (authType === "GITHUB_PAT")
+        return { version, githubPat: credential };
+    return { version, codeup: credential };
+}
+function scmConnectionLine(connection) {
+    const enabled = Object.entries(connection.capabilities).filter(([, value]) => value).map(([key]) => key);
+    return `${connection.code}\t${connection.provider}\t${connection.health}\t${connection.organizationKey}\t${enabled.join(",") || "no-capabilities"}`;
+}
+function repositoryLine(repository) {
+    return `${repository.externalId}\t${repository.fullName ?? repository.name}\t${repository.defaultBranch}\t${repository.headRevision}${repository.archived ? "\tARCHIVED" : ""}`;
+}
+function requireConfirmation(value, operation) {
+    if (!value) {
+        throw new OnboardingError(`${operation} requires --yes.`, "onboarding_confirmation_required");
+    }
+}
+function idempotencyKey(value) {
+    const candidate = value?.trim();
+    if (!candidate) {
+        throw new OnboardingError("--apply requires --idempotency-key so retries can reuse the same submission identity.", "onboarding_idempotency_key_required");
+    }
+    if (candidate.length > 160 || /[\u0000-\u001f\u007f]/u.test(candidate)) {
+        throw new OnboardingError("idempotency-key must be at most 160 printable characters.", "onboarding_input_invalid");
+    }
+    return candidate;
+}
+export async function readOnboardingSpec(path) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile() || info.size < 2 || info.size > MAX_SPEC_BYTES) {
+            throw new Error("spec must be a JSON file between 2 bytes and 256 KiB");
+        }
+        const raw = JSON.parse(await readFile(path, "utf8"));
+        const parsed = OnboardingSpecSchema.safeParse(raw);
+        if (!parsed.success)
+            throw new Error(parsed.error.message);
+        return parsed.data;
+    }
+    catch (error) {
+        if (error instanceof OnboardingError)
+            throw error;
+        throw new OnboardingError(`Cannot read onboarding specification ${path}: ${error instanceof Error ? error.message : String(error)}`, "onboarding_input_invalid");
+    }
+}
+export async function executeOnboardingSpec(client, spec, options = {}) {
+    if (options.plan && options.apply) {
+        throw new OnboardingError("Choose --plan or --apply, not both.", "onboarding_input_invalid");
+    }
+    if (options.mode && options.mode !== spec.mode) {
+        throw new OnboardingError("--mode must match the mode in --spec.", "onboarding_input_invalid");
+    }
+    if (!options.apply && options.idempotencyKey) {
+        throw new OnboardingError("--idempotency-key is only valid with --apply.", "onboarding_input_invalid");
+    }
+    const key = options.apply ? idempotencyKey(options.idempotencyKey) : undefined;
+    const draftSession = options.sessionNo
+        ? await client.getSession(options.sessionNo)
+        : await client.createSession(spec.mode);
+    if (draftSession.mode !== spec.mode) {
+        throw new OnboardingError("Existing session mode must match the mode in --spec.", "onboarding_input_invalid");
+    }
+    let session = await client.updateSession(draftSession.sessionNo, {
+        revision: draftSession.revision,
+        currentStep: "REVIEW",
+        draft: spec
+    });
+    if (!options.plan && !options.apply)
+        return { session };
+    const preflight = await client.preflight(session.sessionNo);
+    session = await client.getSession(session.sessionNo);
+    if (!options.apply)
+        return { session, preflight };
+    if (preflight.blockingErrors.length > 0) {
+        throw new OnboardingError(`Preflight has ${preflight.blockingErrors.length} blocking error(s); apply was not submitted.`, "onboarding_preflight_blocked", undefined, undefined, false, { sessionNo: session.sessionNo, blockingErrors: preflight.blockingErrors });
+    }
+    const planHash = preflight.planHash ?? session.planHash;
+    if (!planHash) {
+        throw new OnboardingError("The server did not return a plan hash; apply was not submitted.", "onboarding_plan_missing");
+    }
+    const task = await client.apply(session.sessionNo, { planHash, idempotencyKey: key });
+    session = await client.getSession(session.sessionNo);
+    return { session, preflight, task, idempotencyKey: key };
+}
+function defaultSleep(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new OnboardingError("Onboarding watch was cancelled.", "onboarding_watch_cancelled"));
+            return;
+        }
+        const timeout = setTimeout(resolve, milliseconds);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            reject(new OnboardingError("Onboarding watch was cancelled.", "onboarding_watch_cancelled"));
+        }, { once: true });
+    });
+}
+export async function watchOnboardingEvents(client, sessionNo, options = {}) {
+    const sleep = options.sleep ?? defaultSleep;
+    let lastSequence = options.afterSequence ?? 0;
+    while (true) {
+        try {
+            const events = await client.getEvents(sessionNo, lastSequence);
+            for (const event of [...events.items].sort((left, right) => left.sequenceNo - right.sequenceNo)) {
+                if (event.sequenceNo <= lastSequence)
+                    continue;
+                lastSequence = event.sequenceNo;
+                options.onEvent?.(event);
+            }
+            const session = await client.getSession(sessionNo);
+            options.onSession?.(session);
+            if (TERMINAL_STATES.has(session.state))
+                return { session, lastSequence };
+        }
+        catch (error) {
+            if (!(error instanceof OnboardingError) || (!error.retryable && (error.status == null || error.status < 500))) {
+                throw error;
+            }
+            options.onReconnect?.(error);
+        }
+        await sleep(2_000, options.signal);
+    }
+}
+export async function inspectOnboardingSession(client, sessionNo, afterSequence = 0) {
+    const [session, eventPage] = await Promise.all([
+        client.getSession(sessionNo),
+        client.getEvents(sessionNo, afterSequence)
+    ]);
+    const events = eventPage.items
+        .filter((event) => event.sequenceNo > afterSequence)
+        .map(publicOnboardingEvent)
+        .sort((left, right) => left.sequenceNo - right.sequenceNo);
+    const lastSequence = events.reduce((maximum, event) => Math.max(maximum, event.sequenceNo), afterSequence);
+    return {
+        session,
+        events,
+        lastSequence,
+        execution: { ...onboardingExecutionView(session, events), lastSequence }
+    };
+}
+export async function executeOnboardingAction(client, sessionNo, action) {
+    await client[action](sessionNo);
+    return inspectOnboardingSession(client, sessionNo);
+}
+async function withInterrupt(run) {
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGINT", stop);
+    try {
+        return await run(controller.signal);
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+    }
+}
+function sessionLine(session) {
+    return `${session.sessionNo}\t${session.mode}\t${session.state}\t${session.currentStep ?? "-"}\trev:${session.revision}`;
+}
+function eventLine(event) {
+    const safe = publicOnboardingEvent(event);
+    const details = safe.output && Object.keys(safe.output).length
+        ? `\t${JSON.stringify(safe.output)}`
+        : "";
+    return `#${safe.sequenceNo}\t${safe.stepCode ?? safe.eventType}\t${safe.stepState ?? "-"}\t${safe.message}${details}`;
+}
+export function registerApplicationOnboardingCommands(program, dependencies = {}) {
+    const client = () => dependencies.clientFactory?.() ?? new OnboardingClient(loadConfig("platform"));
+    const isInteractive = dependencies.interactive ?? (() => Boolean(process.stdin.isTTY && process.stdout.isTTY));
+    const tui = dependencies.runTui ?? runOnboardingTui;
+    const sleep = dependencies.sleep ?? defaultSleep;
+    const app = program.command("app")
+        .description("创建新应用或把存量代码库接入 DevOps 平台")
+        .addHelpText("after", `
+核心约束:
+  所有客户端共享服务端 sessionNo、revision、planHash 和事件 sequence。
+  --plan 只预检；--apply 才提交副作用，且服务端决定真实状态。
+  结果不明时用相同 idempotency-key 重试或 inspect/resume，禁止新建重复会话。
+`);
+    registerApplicationCandidateCommands(app);
+    addExamples(app.command("options <type>")
+        .description("按名称查询应用所需的团队、系统、业务域或环境 ID")
+        .option("--search <text>", "按 code 或名称搜索")
+        .option("--limit <number>", "返回条数 1-100", "50")
+        .action(async (type, options, command) => {
+        const result = await client().listCatalogOptions(parseApplicationCatalogOptionType(type), {
+            search: options.search?.trim() || undefined,
+            limit: positiveInteger(options.limit, "limit", 50, 100)
+        });
+        await output(command, { ok: true, options: result }, result.items.map(catalogOptionLine).join("\n") || "没有找到目录选项");
+    }), [
+        "numa app options team --search platform --json",
+        "numa app options system --json",
+        "numa app options environment --json"
+    ], [
+        "当前用户身份和 Owner 信息使用 numa profile 查询；应用归属以服务端 teamId 权限校验为准。"
+    ]);
+    const scm = app.command("scm")
+        .description("查询 SCM 连接和真实仓库；平台管理员可维护连接与轮换凭据")
+        .addHelpText("after", `
+安全边界:
+  普通诊断只显示 code、provider、organization、health 和 capability。
+  live probe 与连接变更由服务端校验平台管理员权限和乐观锁 version。
+  provider credential 只能来自权限受限文件或重定向 stdin；禁止通过 argv、环境变量或普通 JSON 输出传递。
+  Codeup 云 AK/Role 只能引用已有 aliyunAccountId/aliyunAssumeRoleId，Numa 不读取或保存云 AK。
+  未提供 Codeup accessToken 时使用服务端 Aliyun identity，不提交空 credential bundle。
+`);
+    addExamples(scm.command("list")
+        .description("列出当前用户可见的安全 SCM 连接摘要")
+        .option("--provider <provider>", "github|codeup")
+        .option("--search <text>", "按 code、name 或 organization 搜索")
+        .action(async (options, command) => {
+        const connections = await client().listScmConnections({
+            provider: parseScmProvider(options.provider),
+            search: options.search?.trim() || undefined
+        });
+        await output(command, { ok: true, connections }, connections.items.map(scmConnectionLine).join("\n") || "没有找到可见的 SCM 连接");
+    }), ["numa app scm list --provider github --json"]);
+    addExamples(scm.command("inspect <code>")
+        .description("查看安全连接信息，可选查询一页真实仓库")
+        .option("--repositories", "同时查询仓库页；结果固定 externalId/defaultBranch/headRevision")
+        .option("--search <text>", "仓库搜索词；必须与 --repositories 一起使用")
+        .option("--cursor <cursor>", "仓库分页游标；必须与 --repositories 一起使用")
+        .option("--limit <number>", "每页仓库数量 1-100", "50")
+        .action(async (code, options, command) => {
+        if (!options.repositories && (options.search || options.cursor)) {
+            throw new OnboardingError("--search and --cursor require --repositories.", "onboarding_scm_input_invalid");
+        }
+        const onboarding = client();
+        const connection = await resolveScmConnection(onboarding, code);
+        const repositories = options.repositories
+            ? await onboarding.listRepositories(connection.code, {
+                search: options.search?.trim() || undefined,
+                cursor: safeCursor(options.cursor),
+                limit: positiveInteger(options.limit, "limit", 50, 100)
+            })
+            : undefined;
+        const text = repositories
+            ? `${scmConnectionLine(connection)}\n${repositories.items.map(repositoryLine).join("\n") || "没有匹配仓库"}${repositories.hasMore ? `\nnext-cursor: ${repositories.nextCursor}` : ""}`
+            : scmConnectionLine(connection);
+        await output(command, { ok: true, connection, ...(repositories ? { repositories } : {}) }, text);
+    }), [
+        "numa app scm inspect codeup-main --json",
+        "numa app scm inspect github-main --repositories --search order --limit 50 --json"
+    ], [
+        "仓库选择必须保存 externalId、defaultBranch 和 headRevision；向导会把 headRevision 写入 expectedHead。",
+        "HTTP 429 会保留 Retry-After 诊断，不会由客户端无限重试。"
+    ]);
+    addExamples(scm.command("probe <code>")
+        .description("显示缓存健康诊断；管理员可用 --live 发起真实 provider probe")
+        .option("--live", "调用管理员 live probe；服务端会重新探测 capability/health")
+        .option("--revision <number>", "live probe 的乐观锁 version")
+        .action(async (code, options, command) => {
+        const onboarding = client();
+        if (!options.live) {
+            if (options.revision != null)
+                throw new OnboardingError("--revision is only valid with --live.", "onboarding_scm_input_invalid");
+            const connection = await resolveScmConnection(onboarding, code);
+            await output(command, {
+                ok: true,
+                probe: {
+                    mode: "CACHED",
+                    code: connection.code,
+                    provider: connection.provider,
+                    health: connection.health,
+                    capabilities: connection.capabilities,
+                    lastCheckedAt: connection.lastCheckedAt ?? null
+                }
+            }, `${scmConnectionLine(connection)}\tchecked:${connection.lastCheckedAt ?? "never"}`);
+            return;
+        }
+        const version = revision(options.revision);
+        const before = await onboarding.getAdminScmConnection(code);
+        if (before.version !== version) {
+            throw new OnboardingError("SCM connection version changed; inspect and retry with the latest version.", "onboarding_scm_revision_conflict", 409);
+        }
+        const connection = await onboarding.probeAdminScmConnection(before.code, { version });
+        await output(command, { ok: true, probe: { mode: "LIVE", connection } }, `${connection.code}\t${connection.status}\tversion:${connection.version}`);
+    }), [
+        "numa app scm probe github-main --json",
+        "numa app scm probe github-main --live --revision 4 --json"
+    ]);
+    addExamples(scm.command("create")
+        .description("平台管理员创建 SCM 连接；GitHub 或可选 Codeup token 可在创建后安全写入")
+        .requiredOption("--input <file>", "无 secret 的连接 metadata JSON")
+        .option("--credential-file <file>", "仅 owner 可读（chmod 600）的 provider credential JSON")
+        .option("--credential-stdin", "从重定向 stdin 读取 provider credential JSON")
+        .action(async (options, command) => {
+        const onboarding = client();
+        const input = await readScmAdminConnectionInput(options.input);
+        const existing = await onboarding.listAdminScmConnections();
+        if (existing.items.some((item) => item.code === input.code)) {
+            throw new OnboardingError(`SCM connection already exists: ${input.code}`, "onboarding_scm_connection_exists", 409);
+        }
+        const credential = await readScmCredentialBundle(input.authType, options);
+        let connection = await onboarding.createAdminScmConnection(input);
+        if (credential) {
+            connection = await onboarding.rotateAdminScmCredential(connection.code, scmCredentialUpdate(connection.version, connection.authType, credential));
+        }
+        await output(command, { ok: true, connection }, `${connection.code}\t${connection.status}\tversion:${connection.version}\tcredential:${connection.credentialConfigured ? "configured" : "missing"}`);
+    }), [
+        "numa app scm create --input github.json --credential-file github-app.private.json --json",
+        "numa app scm create --input codeup.json --json"
+    ]);
+    addExamples(scm.command("update <code>")
+        .description("平台管理员按 version 更新连接 metadata；身份字段变更可能使已有 plan 失效")
+        .requiredOption("--input <file>", "无 secret 的完整连接 metadata JSON")
+        .requiredOption("--revision <number>", "当前乐观锁 version")
+        .option("--yes", "确认连接更新")
+        .action(async (code, options, command) => {
+        requireConfirmation(options.yes, "SCM connection update");
+        const onboarding = client();
+        const input = await readScmAdminConnectionInput(options.input);
+        if (input.code !== code)
+            throw new OnboardingError("Input code must match the target connection code.", "onboarding_scm_input_invalid");
+        const version = revision(options.revision);
+        const before = await onboarding.getAdminScmConnection(code);
+        if (before.version !== version)
+            throw new OnboardingError("SCM connection version changed; inspect and retry.", "onboarding_scm_revision_conflict", 409);
+        const connection = await onboarding.updateAdminScmConnection(code, { ...input, version });
+        await output(command, { ok: true, connection }, `${connection.code}\t${connection.status}\tversion:${connection.version}`);
+    }), ["numa app scm update github-main --input github.json --revision 4 --yes --json"]);
+    addExamples(scm.command("rotate <code>")
+        .description("平台管理员写入新 GitHub 或 Codeup access token；不会回显 credential")
+        .requiredOption("--revision <number>", "当前乐观锁 version")
+        .option("--credential-file <file>", "仅 owner 可读（chmod 600）的 provider credential JSON")
+        .option("--credential-stdin", "从重定向 stdin 读取 provider credential JSON")
+        .option("--yes", "确认凭据轮换并使旧 plan 失效")
+        .action(async (code, options, command) => {
+        requireConfirmation(options.yes, "SCM credential rotation");
+        if (!options.credentialFile && !options.credentialStdin) {
+            throw new OnboardingError("SCM credential rotation requires --credential-file or --credential-stdin.", "onboarding_scm_credential_source_invalid");
+        }
+        const onboarding = client();
+        const version = revision(options.revision);
+        const before = await onboarding.getAdminScmConnection(code);
+        if (before.version !== version)
+            throw new OnboardingError("SCM connection version changed; inspect and retry.", "onboarding_scm_revision_conflict", 409);
+        const credential = await readScmCredentialBundle(before.authType, options);
+        if (!credential)
+            throw new OnboardingError("SCM credential input is required.", "onboarding_scm_credential_source_invalid");
+        const connection = await onboarding.rotateAdminScmCredential(code, scmCredentialUpdate(version, before.authType, credential));
+        await output(command, { ok: true, connection }, `${connection.code}\tcredential:configured\tversion:${connection.version}`);
+    }), [
+        "numa app scm rotate github-main --revision 4 --credential-file github-app.private.json --yes --json",
+        "numa app scm rotate codeup-main --revision 2 --credential-stdin --yes --json < codeup-token.private.json"
+    ]);
+    addExamples(scm.command("disable <code>")
+        .description("平台管理员软禁用连接；服务端会阻止仍被非终态会话使用的连接")
+        .requiredOption("--revision <number>", "当前乐观锁 version")
+        .option("--yes", "确认软禁用")
+        .action(async (code, options, command) => {
+        requireConfirmation(options.yes, "SCM connection disable");
+        const onboarding = client();
+        const version = revision(options.revision);
+        const before = await onboarding.getAdminScmConnection(code);
+        if (before.version !== version)
+            throw new OnboardingError("SCM connection version changed; inspect and retry.", "onboarding_scm_revision_conflict", 409);
+        await onboarding.disableAdminScmConnection(code, version);
+        await output(command, { ok: true, code, disabled: true, previousVersion: version }, `${code}\tDISABLED`);
+    }), ["numa app scm disable github-main --revision 5 --yes --json"]);
+    addExamples(app.command("onboard")
+        .description("启动入驻向导，或按 JSON spec 创建、预检和执行")
+        .option("--mode <mode>", "new|existing；如有 --spec 必须与文件一致")
+        .option("--session <session-no>", "更新已有草稿并跨 Web/CLI 恢复；不创建新会话")
+        .option("--spec <file>", "schemaVersion=1 的 onboarding JSON 文件")
+        .option("--plan", "保存草稿并执行服务端预检，不产生外部副作用")
+        .option("--apply", "保存草稿、预检并提交服务端异步执行")
+        .option("--idempotency-key <key>", "apply 幂等键；结果不明时必须复用")
+        .action(async (options, command) => {
+        const mode = options.mode ? parseOnboardingMode(options.mode) : undefined;
+        if (!options.spec) {
+            if (!isInteractive()) {
+                throw new OnboardingError("Non-interactive onboarding requires --spec <file>.", "onboarding_input_required");
+            }
+            if (options.plan || options.apply || options.idempotencyKey) {
+                throw new OnboardingError("--plan, --apply, and --idempotency-key require --spec.", "onboarding_input_invalid");
+            }
+            await tui(client(), { mode, sessionNo: options.session });
+            return;
+        }
+        const onboarding = client();
+        const result = await executeOnboardingSpec(onboarding, await readOnboardingSpec(options.spec), {
+            mode,
+            sessionNo: options.session,
+            plan: options.plan,
+            apply: options.apply,
+            idempotencyKey: options.idempotencyKey
+        });
+        const execution = onboardingExecutionView(result.session);
+        const text = result.task
+            ? `入驻执行已提交:\n${executionText(result.session)}\nidempotency-key: ${result.idempotencyKey}`
+            : result.preflight
+                ? `预检完成: ${sessionLine(result.session)}\nplan: ${result.preflight.planHash ?? "-"}\nblocking: ${result.preflight.blockingErrors.length}`
+                : `草稿已保存: ${sessionLine(result.session)}`;
+        await output(command, { ok: true, ...result, execution }, text);
+    }), [
+        "numa app onboard",
+        "numa app onboard --session <session-no> --spec onboarding.json --plan --json",
+        "numa app onboard --spec onboarding.json --plan --json",
+        "numa app onboard --spec onboarding.json --apply --idempotency-key app-order-20260819 --json"
+    ], [
+        "非 TTY 必须提供 --spec；缺失时稳定返回 onboarding_input_required。",
+        "未指定 --plan/--apply 时只保存服务端草稿。",
+        "完整 spec 保存的 currentStep 为稳定字符串 REVIEW。"
+    ]);
+    addExamples(app.command("resume <session-no>")
+        .description("让服务端重新检查外部等待条件，不在客户端推进状态")
+        .action(async (sessionNo, _options, command) => {
+        const inspection = await executeOnboardingAction(client(), sessionNo, "resume");
+        await output(command, { ok: true, ...inspection }, executionText(inspection.session, inspection.events));
+    }), ["numa app resume 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --json"]);
+    addExamples(app.command("apply <session-no>")
+        .description("按服务端已锁定 planHash 幂等提交已有 PLANNED 会话")
+        .requiredOption("--idempotency-key <key>", "结果不明时复用相同幂等键")
+        .action(async (sessionNo, options, command) => {
+        const onboarding = client();
+        const before = await onboarding.getSession(sessionNo);
+        if (!before.planHash) {
+            throw new OnboardingError("Session has no server plan hash; run onboarding preflight first.", "onboarding_plan_missing");
+        }
+        const key = idempotencyKey(options.idempotencyKey);
+        const task = await onboarding.apply(sessionNo, { planHash: before.planHash, idempotencyKey: key });
+        const session = await onboarding.getSession(sessionNo);
+        await output(command, { ok: true, session, task, idempotencyKey: key, execution: onboardingExecutionView(session) }, `入驻执行已提交:\n${executionText(session)}\nidempotency-key: ${key}`);
+    }), ["numa app apply 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --idempotency-key app-order-20260819 --json"], [
+        "用于先 --plan 后 apply 的安全自动化，也用于响应不明时以同一 key 重放。"
+    ]);
+    addExamples(app.command("inspect <session-no>")
+        .description("查询会话；watch 从最后 event sequence 持续恢复")
+        .option("--watch", "持续补拉事件直到服务端终态；Ctrl+C 只停止本地观察")
+        .option("--after-sequence <number>", "从已持久化的最后 sequence 之后恢复", "0")
+        .action(async (sessionNo, options, command) => {
+        const onboarding = client();
+        const useJson = await jsonEnabled(command);
+        const afterSequence = nonNegativeInteger(options.afterSequence, "after-sequence", 0);
+        let session;
+        const observedEvents = [];
+        let lastSequence = afterSequence;
+        if (options.watch) {
+            const watched = await withInterrupt((signal) => watchOnboardingEvents(onboarding, sessionNo, {
+                afterSequence,
+                sleep,
+                signal,
+                onEvent: (event) => {
+                    const safeEvent = publicOnboardingEvent(event);
+                    lastSequence = Math.max(lastSequence, event.sequenceNo);
+                    observedEvents.push(safeEvent);
+                    if (!useJson)
+                        process.stderr.write(`${String(sanitizeOnboardingOutput(eventLine(safeEvent)))}\n`);
+                },
+                onReconnect: (error) => { if (!useJson)
+                    process.stderr.write(`连接中断，将从 #${lastSequence} 恢复: ${error.message}\n`); },
+                onSession: () => undefined
+            }));
+            session = watched.session;
+            lastSequence = watched.lastSequence;
+        }
+        else {
+            const inspection = await inspectOnboardingSession(onboarding, sessionNo, afterSequence);
+            session = inspection.session;
+            observedEvents.push(...inspection.events);
+            lastSequence = inspection.lastSequence;
+        }
+        const execution = { ...onboardingExecutionView(session, observedEvents), lastSequence };
+        await output(command, { ok: true, session, events: observedEvents, lastSequence, execution }, executionText(session, observedEvents));
+    }), [
+        "numa app inspect 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --json",
+        "numa app inspect 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --watch --after-sequence 42"
+    ]);
+    addExamples(app.command("list")
+        .description("列出当前用户可见的入驻会话")
+        .option("--state <state>", "按服务端会话状态过滤")
+        .option("--cursor <cursor>", "分页游标")
+        .option("--all", "请求当前用户有权查看的全部会话；默认仅本人")
+        .action(async (options, command) => {
+        const sessions = await client().listSessions({
+            state: parseSessionState(options.state),
+            cursor: options.cursor,
+            mine: !options.all
+        });
+        await output(command, { ok: true, sessions }, sessions.items.map(sessionLine).join("\n") || "没有找到入驻会话");
+    }), ["numa app list --state failed --json"]);
+    addExamples(app.command("tui")
+        .description("打开可恢复的 Application Onboarding TUI")
+        .option("--session <session-no>", "打开已有服务端会话")
+        .action(async (options) => tui(client(), { sessionNo: options.session })), [
+        "numa app tui",
+        "numa app tui --session 8d15ee89-43f0-4378-a7aa-51f09c5b42fc"
+    ]);
+    addExamples(app.command("retry <session-no>")
+        .description("让服务端重试可重入的失败步骤")
+        .action(async (sessionNo, _options, command) => {
+        const inspection = await executeOnboardingAction(client(), sessionNo, "retry");
+        await output(command, { ok: true, ...inspection }, executionText(inspection.session, inspection.events));
+    }), ["numa app retry 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --json"]);
+    addExamples(app.command("reassess <session-no>")
+        .description("对存量仓库的新 head 请求服务端重新评估")
+        .action(async (sessionNo, _options, command) => {
+        const inspection = await executeOnboardingAction(client(), sessionNo, "reassess");
+        await output(command, { ok: true, ...inspection }, executionText(inspection.session, inspection.events));
+    }), ["numa app reassess 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --json"]);
+    addExamples(app.command("cancel <session-no>")
+        .description("取消尚未开始的步骤；不会回滚已完成的外部副作用")
+        .option("--yes", "确认取消")
+        .action(async (sessionNo, options, command) => {
+        if (!options.yes)
+            throw new OnboardingError("Cancelling an onboarding session requires --yes.", "onboarding_confirmation_required");
+        const inspection = await executeOnboardingAction(client(), sessionNo, "cancel");
+        await output(command, { ok: true, ...inspection }, executionText(inspection.session, inspection.events));
+    }), ["numa app cancel 8d15ee89-43f0-4378-a7aa-51f09c5b42fc --yes --json"]);
+}
+//# sourceMappingURL=commands.js.map