@seamward/cli 0.1.0-alpha.10

package/dist/cli.js

@@ -0,0 +1,659 @@
+#!/usr/bin/env node
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import { applySetupPlan, completedSetupActionIds, createSetupPlan, inspectSetupActionEvidence, operatorReviewableSetupActions, recordSourceBackedSetupEvidence, reviewSetupActions, } from "./setup-plan.js";
+import { scanProject } from "./discovery.js";
+import { activatePlanContractVersion, previewPlanContract, previewPlanContractActivation, readContractStatus, registerPlanContracts, } from "./contract-sync.js";
+import { checkFirstSetupObservation } from "./observation-sync.js";
+import { cliVersion } from "./version.js";
+import { readProjectMetadata } from "./project-metadata.js";
+import { readSetupPlan, verifySetup } from "./setup-engine.js";
+async function processPrompt(question) {
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        return await readline.question(question);
+    }
+    finally {
+        readline.close();
+    }
+}
+const processIo = {
+    cwd: () => process.cwd(),
+    stdout: (value) => process.stdout.write(value),
+    stderr: (value) => process.stderr.write(value),
+    env: (name) => process.env[name],
+    fetchFn: fetch,
+    isInteractive: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    prompt: processPrompt,
+};
+const usage = `Seamward setup CLI
+
+Usage:
+  seamward discover [directory]
+  seamward setup [directory] [--direction <inbound|outbound>] [--protocol <http-api|http-webhook|queue|scheduled-feed>] [--contract <path>] [--write] [--force]
+  seamward review [directory] [--all | --action <id> [--action <id>]] [--source-backed] [--evidence <note>] [--write]
+  seamward verify [directory]
+  seamward observations check [directory] [--endpoint <url>] [--write]
+  seamward contracts register [directory] --version <version> [--file <path>] [--binding <path>] [--include-examples] [--write]
+  seamward contracts status [directory] [--endpoint <url>]
+  seamward contracts activate [directory] --contract <id> --expected <id|none> [--reason <promote|rollback>] [--write]
+  seamward --version
+
+Commands are read-only unless --write is supplied. Interactive review records
+selected actions only after confirmation. Source code and secret values are
+never included in the generated setup plan.
+`;
+function parseArguments(arguments_) {
+    const [rawCommand = "help", ...remaining] = arguments_;
+    if (rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
+        return {
+            command: "help",
+            directory: ".",
+            write: false,
+            force: false,
+            files: [],
+            setupContracts: [],
+            actions: [],
+            all: false,
+            sourceBacked: false,
+            expectedProvided: false,
+            includeExamples: false,
+        };
+    }
+    if (rawCommand === "--version" ||
+        rawCommand === "-v" ||
+        rawCommand === "version") {
+        return {
+            command: "version",
+            directory: ".",
+            write: false,
+            force: false,
+            files: [],
+            setupContracts: [],
+            actions: [],
+            all: false,
+            sourceBacked: false,
+            expectedProvided: false,
+            includeExamples: false,
+        };
+    }
+    let command = rawCommand;
+    if (rawCommand === "contracts" && remaining[0] === "register") {
+        command = "contracts-register";
+        remaining.shift();
+    }
+    else if (rawCommand === "contracts" && remaining[0] === "status") {
+        command = "contracts-status";
+        remaining.shift();
+    }
+    else if (rawCommand === "contracts" && remaining[0] === "activate") {
+        command = "contracts-activate";
+        remaining.shift();
+    }
+    else if (rawCommand === "observations" && remaining[0] === "check") {
+        command = "observations-check";
+        remaining.shift();
+    }
+    if (command !== "discover" &&
+        command !== "setup" &&
+        command !== "review" &&
+        command !== "verify" &&
+        command !== "observations-check" &&
+        command !== "contracts-register" &&
+        command !== "contracts-status" &&
+        command !== "contracts-activate") {
+        throw new Error(`unknown command: ${rawCommand}`);
+    }
+    let directory = ".";
+    let directorySeen = false;
+    let write = false;
+    let force = false;
+    let version;
+    let endpoint;
+    let contractVersionId;
+    let expectedActiveContractVersionId;
+    let expectedProvided = false;
+    let reason;
+    let binding;
+    let includeExamples = false;
+    let evidence;
+    let direction;
+    let protocol;
+    const files = [];
+    const setupContracts = [];
+    const actions = [];
+    let all = false;
+    let sourceBacked = false;
+    for (let index = 0; index < remaining.length; index += 1) {
+        const argument = remaining[index] ?? "";
+        if (argument === "--write" &&
+            (command === "setup" ||
+                command === "review" ||
+                command === "observations-check" ||
+                command === "contracts-register" ||
+                command === "contracts-activate")) {
+            write = true;
+            continue;
+        }
+        if (argument === "--action" && command === "review") {
+            const action = remaining[index + 1];
+            if (!action || action.startsWith("-")) {
+                throw new Error("--action requires a value");
+            }
+            actions.push(action);
+            index += 1;
+            continue;
+        }
+        if (argument === "--all" && command === "review") {
+            all = true;
+            continue;
+        }
+        if (argument === "--source-backed" && command === "review") {
+            sourceBacked = true;
+            continue;
+        }
+        if (argument === "--evidence" && command === "review") {
+            evidence = remaining[index + 1];
+            if (!evidence || evidence.startsWith("-")) {
+                throw new Error("--evidence requires a value");
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--force" && command === "setup") {
+            force = true;
+            continue;
+        }
+        if (argument === "--direction" && command === "setup") {
+            const value = remaining[index + 1];
+            if (value !== "inbound" && value !== "outbound") {
+                throw new Error("--direction must be inbound or outbound");
+            }
+            direction = value;
+            index += 1;
+            continue;
+        }
+        if (argument === "--protocol" && command === "setup") {
+            const value = remaining[index + 1];
+            if (value !== "http-api" &&
+                value !== "http-webhook" &&
+                value !== "queue" &&
+                value !== "scheduled-feed") {
+                throw new Error("--protocol must be http-api, http-webhook, queue, or scheduled-feed");
+            }
+            protocol = value;
+            index += 1;
+            continue;
+        }
+        if (argument === "--contract" && command === "setup") {
+            const file = remaining[index + 1];
+            if (!file || file.startsWith("-")) {
+                throw new Error("--contract requires a value");
+            }
+            setupContracts.push(file);
+            index += 1;
+            continue;
+        }
+        if (argument === "--version" && command === "contracts-register") {
+            version = remaining[index + 1];
+            if (!version || version.startsWith("-")) {
+                throw new Error("--version requires a value");
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--file" && command === "contracts-register") {
+            const file = remaining[index + 1];
+            if (!file || file.startsWith("-")) {
+                throw new Error("--file requires a value");
+            }
+            files.push(file);
+            index += 1;
+            continue;
+        }
+        if (argument === "--binding" && command === "contracts-register") {
+            binding = remaining[index + 1];
+            if (!binding || binding.startsWith("-")) {
+                throw new Error("--binding requires a value");
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--include-examples" && command === "contracts-register") {
+            includeExamples = true;
+            continue;
+        }
+        if (argument === "--endpoint" &&
+            (command === "contracts-register" ||
+                command === "contracts-status" ||
+                command === "contracts-activate" ||
+                command === "observations-check")) {
+            endpoint = remaining[index + 1];
+            if (!endpoint || endpoint.startsWith("-")) {
+                throw new Error("--endpoint requires a value");
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--contract" && command === "contracts-activate") {
+            contractVersionId = remaining[index + 1];
+            if (!contractVersionId || contractVersionId.startsWith("-")) {
+                throw new Error("--contract requires a value");
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--expected" && command === "contracts-activate") {
+            const expected = remaining[index + 1];
+            if (!expected || expected.startsWith("-")) {
+                throw new Error("--expected requires a contract ID or none");
+            }
+            expectedProvided = true;
+            expectedActiveContractVersionId = expected === "none" ? null : expected;
+            index += 1;
+            continue;
+        }
+        if (argument === "--reason" && command === "contracts-activate") {
+            const value = remaining[index + 1];
+            if (value !== "promote" && value !== "rollback") {
+                throw new Error("--reason must be promote or rollback");
+            }
+            reason = value;
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith("-")) {
+            throw new Error(`unknown option for ${command}: ${argument}`);
+        }
+        if (directorySeen)
+            throw new Error(`unexpected argument: ${argument}`);
+        directory = argument;
+        directorySeen = true;
+    }
+    if (force && !write)
+        throw new Error("--force requires --write");
+    if (command === "setup" && Boolean(direction) !== Boolean(protocol)) {
+        throw new Error("setup requires --direction and --protocol together");
+    }
+    if (command === "review" && all && actions.length > 0) {
+        throw new Error("review accepts either --all or --action, not both");
+    }
+    if (command === "contracts-register" && !version) {
+        throw new Error("contracts register requires --version");
+    }
+    if (command === "contracts-register" && files.length > 1) {
+        throw new Error("contracts register accepts exactly one --file");
+    }
+    if (command === "contracts-activate" && !contractVersionId) {
+        throw new Error("contracts activate requires --contract");
+    }
+    if (command === "contracts-activate" && !expectedProvided) {
+        throw new Error("contracts activate requires --expected");
+    }
+    return {
+        command,
+        directory,
+        write,
+        force,
+        version,
+        files,
+        setupContracts,
+        actions,
+        all,
+        sourceBacked,
+        ...(evidence ? { evidence } : {}),
+        endpoint,
+        contractVersionId,
+        expectedActiveContractVersionId,
+        expectedProvided,
+        reason,
+        direction,
+        protocol,
+        binding,
+        includeExamples,
+    };
+}
+function safeTerminalText(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+}
+function reviewActionLabel(action) {
+    const direction = action.direction ?? "unknown";
+    const operation = (() => {
+        switch (action.operationKind) {
+            case "http_client":
+                return "HTTP client";
+            case "http_server":
+                return "HTTP handler";
+            case "webhook_handler":
+                return "webhook handler";
+            case "queue_publish":
+                return "queue publisher";
+            case "queue_consume":
+                return "queue consumer";
+            case "scheduled_feed":
+                return "scheduled feed";
+            default:
+                return "integration operation";
+        }
+    })();
+    const location = action.file
+        ? `${action.file}${action.line ? `:${action.line}` : ""}`
+        : "the discovered integration boundary";
+    return safeTerminalText(`Instrument ${direction} ${operation} in ${location}`);
+}
+function parseInteractiveSelection(value, actionCount) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized || normalized === "cancel" || normalized === "q") {
+        return "cancel";
+    }
+    if (normalized === "all" || normalized === "a") {
+        return Array.from({ length: actionCount }, (_, index) => index);
+    }
+    const entries = normalized.split(/[\s,]+/).filter(Boolean);
+    if (entries.length === 0)
+        return null;
+    const indexes = entries.map((entry) => Number(entry) - 1);
+    if (indexes.some((index) => !Number.isInteger(index) || index < 0 || index >= actionCount)) {
+        return null;
+    }
+    return [...new Set(indexes)];
+}
+async function runInteractiveReview(plan, root, io, evidence, sourceBacked) {
+    if (!io.isInteractive?.() || !io.prompt) {
+        throw new Error("Interactive review requires a terminal. Use --all or --action for automation");
+    }
+    const completed = sourceBacked
+        ? new Set((await inspectSetupActionEvidence(plan, root))
+            .filter(({ status }) => status === "source_verified")
+            .map(({ actionId }) => actionId))
+        : await completedSetupActionIds(plan, root);
+    const pending = operatorReviewableSetupActions(plan).filter(({ id }) => !completed.has(id));
+    if (pending.length === 0) {
+        io.stdout("No pending instrumentation actions require review.\n");
+        return 0;
+    }
+    io.stdout(`Seamward found ${pending.length} pending instrumentation ${pending.length === 1 ? "change" : "changes"}:\n\n`);
+    for (const [index, action] of pending.entries()) {
+        io.stdout(`  ${index + 1}. ${reviewActionLabel(action)}\n`);
+    }
+    io.stdout("\nReview records that an engineer implemented and reviewed the selected changes. It does not modify application source.\n\n");
+    let selectedIndexes = null;
+    while (selectedIndexes === null) {
+        selectedIndexes = parseInteractiveSelection(await io.prompt("Select actions (all, comma-separated numbers, or cancel): "), pending.length);
+        if (selectedIndexes === null) {
+            io.stderr("Select all, one or more listed numbers, or cancel.\n");
+        }
+    }
+    if (selectedIndexes === "cancel") {
+        io.stdout("Review cancelled. No review was recorded.\n");
+        return 0;
+    }
+    const selected = selectedIndexes.map((index) => pending[index]);
+    const reviewEvidence = evidence ?? (await io.prompt("Review note (optional): "));
+    const confirmation = (await io.prompt(`Mark ${selected.length} ${selected.length === 1 ? "action" : "actions"} as implemented and reviewed? (y/N): `))
+        .trim()
+        .toLowerCase();
+    if (confirmation !== "y" && confirmation !== "yes") {
+        io.stdout("Review cancelled. No review was recorded.\n");
+        return 0;
+    }
+    const recordReview = sourceBacked
+        ? recordSourceBackedSetupEvidence
+        : reviewSetupActions;
+    await recordReview(plan, root, selected.map(({ id }) => id), {
+        write: true,
+        ...(reviewEvidence.trim() ? { evidence: reviewEvidence } : {}),
+    });
+    io.stdout(`Review recorded for ${selected.length} ${selected.length === 1 ? "action" : "actions"}.\n`);
+    return 0;
+}
+async function readJsonSchemaBinding(root, relativeFile) {
+    if (!relativeFile)
+        return undefined;
+    const realRoot = await realpath(root);
+    const resolved = await realpath(path.resolve(realRoot, relativeFile));
+    const relative = path.relative(realRoot, resolved);
+    if (relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        throw new Error("JSON Schema binding path escapes the project boundary");
+    }
+    try {
+        return JSON.parse(await readFile(resolved, "utf8"));
+    }
+    catch {
+        throw new Error("JSON Schema binding must be a valid JSON file");
+    }
+}
+export async function runCli(arguments_, io = processIo) {
+    let parsed;
+    try {
+        parsed = parseArguments(arguments_);
+    }
+    catch (error) {
+        io.stderr(`${error.message}\n\n${usage}`);
+        return 2;
+    }
+    if (parsed.command === "help") {
+        io.stdout(usage);
+        return 0;
+    }
+    if (parsed.command === "version") {
+        io.stdout(`${cliVersion}\n`);
+        return 0;
+    }
+    try {
+        const root = path.resolve(io.cwd(), parsed.directory);
+        if (parsed.command === "verify") {
+            const plan = await readSetupPlan(root);
+            const result = await verifySetup(root, plan);
+            const reviewActions = [
+                ...result.instrumentationActions,
+                ...result.contractActions,
+            ];
+            const pendingReviewActions = reviewActions.filter(({ status }) => status === "pending" || status === "stale" || status === "missing").length;
+            io.stdout(`${JSON.stringify({
+                ...result,
+                fingerprint: result.planFingerprint,
+                collectorDependency: result.collectorDependency.present,
+                collectorDependencyVersion: result.collectorDependency.version,
+                pendingReviewActions,
+                completedReviewActions: reviewActions.length - pendingReviewActions,
+            }, null, 2)}\n`);
+            return result.setupComplete ? 0 : 1;
+        }
+        if (parsed.command === "review") {
+            const plan = await readSetupPlan(root);
+            if (!parsed.all && parsed.actions.length === 0) {
+                return await runInteractiveReview(plan, root, io, parsed.evidence, parsed.sourceBacked);
+            }
+            const selectedActions = parsed.all
+                ? operatorReviewableSetupActions(plan).map(({ id }) => id)
+                : parsed.actions;
+            if (selectedActions.length === 0) {
+                throw new Error("No instrumentation actions are available for review");
+            }
+            const recordReview = parsed.sourceBacked
+                ? recordSourceBackedSetupEvidence
+                : reviewSetupActions;
+            const result = await recordReview(plan, root, selectedActions, {
+                write: parsed.write,
+                ...(parsed.evidence ? { evidence: parsed.evidence } : {}),
+            });
+            io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+            return 0;
+        }
+        if (parsed.command === "observations-check") {
+            const plan = await readSetupPlan(root);
+            const connectionKey = io.env?.(plan.connectionKeyEnvironment) ?? "";
+            const apiKey = io.env?.("SEAMWARD_API_KEY") ?? "";
+            if (!connectionKey || !apiKey) {
+                throw new Error(`${plan.connectionKeyEnvironment} and SEAMWARD_API_KEY are required for the first-observation check`);
+            }
+            const endpoint = parsed.endpoint ?? io.env?.("SEAMWARD_MANAGEMENT_API_URL");
+            const result = await checkFirstSetupObservation(plan, root, {
+                apiKey,
+                connectionKey,
+                ...(endpoint ? { endpoint } : {}),
+                ...(io.fetchFn ? { fetchFn: io.fetchFn } : {}),
+                write: parsed.write,
+            });
+            io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+            return result.status === "observed" ? 0 : 1;
+        }
+        if (parsed.command === "contracts-register") {
+            const plan = await readSetupPlan(root);
+            const connectionKey = io.env?.(plan.connectionKeyEnvironment) ?? "";
+            if (!connectionKey) {
+                throw new Error(`${plan.connectionKeyEnvironment} is required for contract registration`);
+            }
+            await applySetupPlan(plan, root);
+            const jsonSchemaBinding = await readJsonSchemaBinding(root, parsed.binding);
+            const selected = await previewPlanContract(plan, root, connectionKey, {
+                ...(parsed.files[0] ? { file: parsed.files[0] } : {}),
+                ...(jsonSchemaBinding ? { jsonSchemaBinding } : {}),
+                includeExamples: parsed.includeExamples,
+            });
+            if (!parsed.write) {
+                io.stdout(`${JSON.stringify({
+                    applied: false,
+                    operation: "contract_registration",
+                    integrationId: selected.integrationId,
+                    declaredVersion: parsed.version,
+                    files: [selected.file],
+                    format: selected.format,
+                    fingerprint: selected.fingerprint,
+                    byteSize: selected.byteSize,
+                    removedExampleFields: selected.removedExampleFields,
+                    ...(selected.operationBinding
+                        ? { operationBinding: selected.operationBinding }
+                        : {}),
+                    examples: parsed.includeExamples ? "included" : "removed",
+                }, null, 2)}\n`);
+                return 0;
+            }
+            const apiKey = io.env?.("SEAMWARD_API_KEY") ?? "";
+            if (!apiKey)
+                throw new Error("SEAMWARD_API_KEY is required with --write");
+            const endpoint = parsed.endpoint ?? io.env?.("SEAMWARD_MANAGEMENT_API_URL");
+            const result = await registerPlanContracts(plan, root, {
+                apiKey,
+                connectionKey,
+                declaredVersion: parsed.version ?? "",
+                ...(endpoint ? { endpoint } : {}),
+                ...(parsed.files[0] ? { file: parsed.files[0] } : {}),
+                ...(jsonSchemaBinding ? { jsonSchemaBinding } : {}),
+                includeExamples: parsed.includeExamples,
+                writeCompletion: true,
+                ...(io.fetchFn ? { fetchFn: io.fetchFn } : {}),
+            });
+            io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+            return 0;
+        }
+        if (parsed.command === "contracts-status") {
+            const plan = await readSetupPlan(root);
+            const connectionKey = io.env?.(plan.connectionKeyEnvironment) ?? "";
+            const apiKey = io.env?.("SEAMWARD_API_KEY") ?? "";
+            if (!connectionKey || !apiKey) {
+                throw new Error(`${plan.connectionKeyEnvironment} and SEAMWARD_API_KEY are required for contract status`);
+            }
+            const endpoint = parsed.endpoint ?? io.env?.("SEAMWARD_MANAGEMENT_API_URL");
+            const status = await readContractStatus({
+                apiKey,
+                connectionKey,
+                ...(endpoint ? { endpoint } : {}),
+                ...(io.fetchFn ? { fetchFn: io.fetchFn } : {}),
+            });
+            io.stdout(`${JSON.stringify(status, null, 2)}\n`);
+            return 0;
+        }
+        if (parsed.command === "contracts-activate") {
+            const plan = await readSetupPlan(root);
+            const connectionKey = io.env?.(plan.connectionKeyEnvironment) ?? "";
+            const apiKey = io.env?.("SEAMWARD_API_KEY") ?? "";
+            if (!connectionKey || !apiKey) {
+                throw new Error(`${plan.connectionKeyEnvironment} and SEAMWARD_API_KEY are required for contract activation`);
+            }
+            const endpoint = parsed.endpoint ?? io.env?.("SEAMWARD_MANAGEMENT_API_URL");
+            const status = await readContractStatus({
+                apiKey,
+                connectionKey,
+                ...(endpoint ? { endpoint } : {}),
+                ...(io.fetchFn ? { fetchFn: io.fetchFn } : {}),
+            });
+            const preview = await previewPlanContractActivation(plan, root, status, {
+                contractVersionId: parsed.contractVersionId ?? "",
+                reason: parsed.reason ?? "promote",
+            });
+            if (preview.expectedActiveContractVersionId !==
+                (parsed.expectedActiveContractVersionId ?? null)) {
+                throw new Error("The reviewed --expected contract does not match current contract status");
+            }
+            if (!parsed.write) {
+                io.stdout(`${JSON.stringify({
+                    applied: false,
+                    operation: "contract_activation",
+                    ...preview,
+                }, null, 2)}\n`);
+                return 0;
+            }
+            const result = await activatePlanContractVersion(plan, root, preview, {
+                apiKey,
+                connectionKey,
+                ...(endpoint ? { endpoint } : {}),
+                ...(io.fetchFn ? { fetchFn: io.fetchFn } : {}),
+            });
+            io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+            return 0;
+        }
+        const discovery = await scanProject(root);
+        if (parsed.command === "discover") {
+            io.stdout(`${JSON.stringify(discovery, null, 2)}\n`);
+            return 0;
+        }
+        const metadata = await readProjectMetadata(root);
+        const plan = createSetupPlan(discovery, {
+            ...metadata,
+            contractFiles: parsed.setupContracts,
+            ...(parsed.direction && parsed.protocol
+                ? {
+                    integrationScope: {
+                        direction: parsed.direction,
+                        protocol: parsed.protocol,
+                    },
+                }
+                : {}),
+        });
+        const result = await applySetupPlan(plan, root, {
+            write: parsed.write,
+            force: parsed.force,
+        });
+        io.stdout(`${JSON.stringify({ ...result, plan }, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr(`${error.message}\n`);
+        return 1;
+    }
+}
+const entrypoint = process.argv[1];
+let isEntrypoint = false;
+if (entrypoint) {
+    try {
+        isEntrypoint =
+            import.meta.url === pathToFileURL(await realpath(entrypoint)).href;
+    }
+    catch {
+        isEntrypoint = import.meta.url === pathToFileURL(entrypoint).href;
+    }
+}
+if (isEntrypoint) {
+    const exitCode = await runCli(process.argv.slice(2));
+    process.exitCode = exitCode;
+}
+//# sourceMappingURL=cli.js.map