@apexops/cli 0.10.0-next.5 → 0.11.0-next.1

package/dist/bootstrap-wizard.js

@@ -0,0 +1,259 @@
+import { createInterface } from "node:readline/promises";
+import { join } from "node:path";
+import { stdin, stdout } from "node:process";
+import { isDeepStrictEqual } from "node:util";
+import { ApexService } from "./service.js";
+import { ApexError, EXIT_CODES } from "./errors.js";
+/** An APEX error raised while waiting for an answer, such as a stale workspace after the wait; it ends the wizard. */
+class InterruptedWait extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+    }
+}
+export async function runBootstrapWizard(root, interaction, serviceAt = (directory) => new ApexService(directory), scope = (_directory, body) => body()) {
+    const progress = [];
+    const ask = async (question) => {
+        const value = (await interaction.ask(question).catch((error) => {
+            throw error instanceof ApexError ? new InterruptedWait(error) : error;
+        })).trim();
+        if (value.toLowerCase() === "cancel")
+            throw new Error("BOOTSTRAP_CANCELLED");
+        if (value.length > 4096)
+            throw new ApexError("APEX_VALIDATION", "Bootstrap answer exceeds the input budget", EXIT_CODES.validation);
+        return value;
+    };
+    const choose = async (question, values, fallback) => {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const value = (await ask(question)) || fallback;
+            if (value !== undefined && values.includes(value))
+                return value;
+            interaction.show(`Choose one of: ${values.join(", ")}. Enter cancel to stop.`);
+        }
+        throw new ApexError("APEX_VALIDATION", "Bootstrap choice remains invalid", EXIT_CODES.validation);
+    };
+    const confirm = async (question) => (await choose(`${question} [yes/no, default no]: `, ["yes", "no"], "no")) === "yes";
+    try {
+        interaction.show("APEX repository bootstrap. Enter cancel at any question to stop. Never enter tokens, passwords or client secrets.");
+        let directories = [root];
+        if (await confirm("Copy one or more independent workloads from a remote COE?")) {
+            const repository = await ask("Remote COE HTTPS URL (https://github.com/OWNER/REPO): ");
+            const revision = await ask("Exact 40-character source commit: ");
+            const catalogPath = (await ask("Catalog directory [archetypes]: ")) || "archetypes";
+            const service = serviceAt(root);
+            const catalog = await service.listArchetypes(repository, revision, catalogPath);
+            interaction.show(catalog.candidates.map(({ selectedPath }, index) => ({ selection: index + 1, path: selectedPath })));
+            const selection = await ask("Select workload numbers separated by commas: ");
+            if (!/^[1-9][0-9]*(?:\s*,\s*[1-9][0-9]*)*$/.test(selection))
+                throw new ApexError("APEX_VALIDATION", "Workload selection must contain exact listed numbers", EXIT_CODES.validation);
+            const indexes = selection.split(",").map((value) => Number(value.trim()) - 1);
+            if (new Set(indexes).size !== indexes.length ||
+                indexes.length > 16 ||
+                indexes.some((index) => !catalog.candidates[index]))
+                throw new ApexError("APEX_VALIDATION", "Workload selection is duplicated or outside the catalog", EXIT_CODES.validation);
+            const selections = [];
+            for (const index of indexes) {
+                const selectedPath = catalog.candidates[index].selectedPath;
+                selections.push({
+                    selectedPath,
+                    destination: await ask(`Independent destination folder for ${selectedPath}: `),
+                });
+            }
+            const config = { schemaVersion: "1.0.0", repository, revision, selections };
+            const plan = await service.planArchetypeBatch(config);
+            interaction.show(plan);
+            if (!(await confirm("Copy exactly these reviewed files and exclusions?")))
+                return { status: "pending", progress, nextAction: "COE copy was not confirmed." };
+            const copied = await service.importArchetypeBatch(config, plan.planHash, true);
+            progress.push({ directory: root, step: "coe-copy", outcome: copied });
+            if (copied.status === "blocked")
+                return { status: "blocked", progress, nextAction: copied.nextAction };
+            directories = selections.map(({ destination }) => join(root, destination));
+        }
+        for (const directory of directories) {
+            const stopped = await scope(directory, async () => {
+                interaction.show({ workspace: directory });
+                const createRepository = await confirm("Initialize a local Git repository if none exists here?");
+                const config = {
+                    schemaVersion: "1.0.0",
+                    client: "github-copilot-cli",
+                    createRepository,
+                };
+                const service = serviceAt(directory);
+                const plan = await service.planBootstrap(config);
+                interaction.show(plan);
+                if (plan.status === "blocked")
+                    return {
+                        status: "blocked",
+                        progress,
+                        nextAction: "Resolve the local bootstrap blockers; existing files were preserved.",
+                    };
+                if (!(await confirm("Install the exact workspace runtime and configure or resume APEX here without creating a project?")))
+                    return { status: "pending", progress, nextAction: "Workspace setup was not confirmed." };
+                if (!isDeepStrictEqual(await service.planBootstrap(config), plan))
+                    throw new ApexError("APEX_STALE", "The local bootstrap plan changed after it was shown; run the wizard again to review a fresh plan.", EXIT_CODES.stale);
+                const initialized = await service.bootstrap({ createRepository, clientId: "github-copilot-cli" });
+                progress.push({ directory, step: "local-bootstrap", outcome: initialized });
+                if (await confirm("Create a GitHub repository and push this reviewed branch?")) {
+                    const owner = await ask("Repository owner (user or organization login): ");
+                    const name = await ask("Repository name: ");
+                    const visibility = (await choose("Visibility [private/internal/public, default private]: ", ["private", "internal", "public"], "private"));
+                    const branch = (await ask("Branch to publish [main]: ")) || "main";
+                    const publishConfig = {
+                        schemaVersion: "1.0.0",
+                        owner,
+                        name,
+                        visibility,
+                        branch,
+                        remote: "origin",
+                    };
+                    const publishPlan = await service.planRepositoryPublish(publishConfig);
+                    interaction.show(publishPlan);
+                    progress.push({ directory, step: "github-repository-plan", outcome: publishPlan });
+                    if (publishPlan.status === "pending") {
+                        if (await confirm(`Create ${publishPlan.repository.fullName} as ${publishPlan.repository.visibility} and push exactly commit ${publishPlan.push.commit} on ${publishPlan.push.branch} without force?`)) {
+                            const published = await service.publishRepository(publishConfig, publishPlan.planHash, true);
+                            interaction.show(published);
+                            progress.push({ directory, step: "github-repository", outcome: published });
+                        }
+                    }
+                }
+                const governance = await choose("Governance source [consumer/central/later, default later]: ", ["consumer", "central", "later"], "later");
+                if (governance === "consumer") {
+                    const repository = await ask("Consumer GitHub repository (OWNER/REPOSITORY): ");
+                    const tenantId = await ask("Azure tenant ID: ");
+                    const subscriptionId = await ask("Login and standalone collection subscription ID: ");
+                    const managementGroupId = await ask("Management-group collection ID, or blank for subscription: ");
+                    const mode = await choose("Identity [reuse/create]: ", ["reuse", "create"]);
+                    const identity = mode === "reuse"
+                        ? {
+                            mode,
+                            clientId: await ask("Approved application client ID: "),
+                            principalId: await ask("Approved service-principal object ID: "),
+                        }
+                        : { mode: "create", displayName: await ask("Proposed dedicated application display name: ") };
+                    const governanceConfig = {
+                        schemaVersion: "1.0.0",
+                        repository,
+                        tenantId,
+                        subscriptionId,
+                        identity,
+                        ...(managementGroupId ? { managementGroupId } : {}),
+                    };
+                    const setup = await service.planGovernanceSetup(governanceConfig);
+                    interaction.show(setup);
+                    progress.push({ directory, step: "governance-plan", outcome: setup });
+                    if (identity.mode === "reuse" && setup.status !== "blocked") {
+                        const provisioning = await service.planGovernanceProvision(governanceConfig);
+                        interaction.show(provisioning);
+                        progress.push({ directory, step: "governance-provision-plan", outcome: provisioning });
+                        if (provisioning.status === "ready" &&
+                            (await confirm("Create only the listed Azure federation and Reader assignment for this existing identity? GitHub configuration and collection stay unchanged."))) {
+                            const outcome = await service.provisionGovernance(governanceConfig, provisioning.planHash, true);
+                            interaction.show(outcome);
+                            progress.push({ directory, step: "governance-provision", outcome });
+                        }
+                    }
+                }
+                else if (governance === "central") {
+                    progress.push({
+                        directory,
+                        step: "central-baseline-check",
+                        outcome: {
+                            status: "pending",
+                            imported: false,
+                            nextAction: "APEX will check the reviewed central baseline once the first project and its target are known.",
+                        },
+                    });
+                }
+                else {
+                    progress.push({
+                        directory,
+                        step: "governance",
+                        outcome: {
+                            status: "pending",
+                            source: governance,
+                            nextAction: governance === "central"
+                                ? "Select and import the current reviewed central baseline using the governance workflow."
+                                : "Configure governance before planning infrastructure.",
+                        },
+                    });
+                }
+                return undefined;
+            });
+            if (stopped !== undefined)
+                return stopped;
+        }
+        const blocked = progress.some(({ outcome }) => outcome !== null && typeof outcome === "object" && "status" in outcome && outcome.status === "blocked");
+        return {
+            status: blocked ? "blocked" : "pending",
+            progress,
+            nextAction: "Workspace setup is complete; no project was created. Open APEX to gather details and create the first project. Complete pending governance and client checks. No deployment is authorized.",
+        };
+    }
+    catch (error) {
+        if (error instanceof InterruptedWait)
+            throw error.error;
+        return {
+            status: error instanceof Error && error.message === "BOOTSTRAP_CANCELLED" ? "cancelled" : "blocked",
+            progress,
+            nextAction: error instanceof ApexError
+                ? error.message
+                : "Setup stopped; completed steps were preserved. Inspect prerequisites before retrying.",
+        };
+    }
+}
+/**
+ * Runs the wizard on the terminal, or on `options.interaction` when given, while the command holds the workspace lock
+ * of `root` through `service`. Each copied workspace's steps also hold that workspace's own lock. Every question is
+ * asked without any of these locks, so MCP calls are not blocked while the wizard waits; if a workspace changed during
+ * the wait, the wizard fails with `APEX_STALE` instead of applying the answer.
+ */
+export async function interactiveBootstrap(root, service, options = {}) {
+    const services = new Map();
+    const serviceAt = (directory) => {
+        let current = services.get(directory);
+        if (current === undefined) {
+            current = options.serviceAt?.(directory) ?? new ApexService(directory);
+            services.set(directory, current);
+        }
+        return current;
+    };
+    // Workspaces whose locks the wizard holds, outermost first; a question waits without all of them.
+    const holders = [service];
+    const scope = (directory, body) => {
+        if (directory === root)
+            return body();
+        const workspace = serviceAt(directory);
+        return workspace.withWorkspaceWriteLock(async () => {
+            holders.push(workspace);
+            try {
+                return await body();
+            }
+            finally {
+                holders.pop();
+            }
+        }, undefined, { suspendable: true });
+    };
+    const outsideLocks = (wait) => holders.reduce((inner, holder) => () => holder.waitOutsideWorkspaceLock(inner), wait)();
+    const run = (terminal) => runBootstrapWizard(root, {
+        ask: (question) => outsideLocks(() => terminal.ask(question)),
+        show: (value) => terminal.show(value),
+    }, serviceAt, scope);
+    if (options.interaction !== undefined)
+        return run(options.interaction);
+    if (!stdin.isTTY || !stdout.isTTY)
+        throw new ApexError("APEX_USAGE", "bootstrap wizard requires an interactive terminal; use typed plan commands for automation", EXIT_CODES.usage);
+    const terminal = createInterface({ input: stdin, output: stdout });
+    try {
+        return await run({
+            ask: (question) => terminal.question(question),
+            show: (value) => stdout.write(`${typeof value === "string" ? value : JSON.stringify(value, null, 2)}\n`),
+        });
+    }
+    finally {
+        terminal.close();
+    }
+}
+//# sourceMappingURL=bootstrap-wizard.js.map

package/dist/cli.d.ts

@@ -1,5 +1,20 @@
 #!/usr/bin/env node
-import { type ServiceOptions } from "./service.js";
-export declare function execute(argv: string[], root?: string, options?: ServiceOptions): Promise<unknown>;
+import { type McpServiceResolver } from "./mcp.js";
+import { ApexService, type ServiceOptions } from "./service.js";
+import { type BootstrapInteraction } from "./bootstrap-wizard.js";
+export { mcpWorkspaceRoot, resolveMcpWorkspace } from "./workspace-root.js";
+type FlagValue = string | string[] | boolean;
+type Flags = Record<string, FlagValue>;
+export declare function createApexService(root: string, flags?: Flags, command?: string, options?: ServiceOptions): Promise<ApexService>;
+/**
+ * One service per resolved workspace root. Every service sees the others as pending-review guard peers, so a guarded
+ * call aimed at another workspace still fails while any served workspace has a review waiting for its capture.
+ */
+export declare function mcpServiceResolver(defaultService: ApexService, create: (workspaceRoot: string, workspacePath: string) => Promise<ApexService>): McpServiceResolver;
+/** Terminal seams for interactive commands; tests substitute them for a real terminal. */
+export interface CliInteraction {
+    bootstrap?: BootstrapInteraction;
+}
+export declare function execute(argv: string[], root?: string, options?: ServiceOptions, interaction?: CliInteraction): Promise<unknown>;
 export declare function formatHumanResult(args: string[], result: unknown): string;
 //# sourceMappingURL=cli.d.ts.map