@seamward/cli 0.1.0-alpha.9

package/dist/setup-plan.js

@@ -0,0 +1,1240 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, link, mkdir, open, readFile, realpath, rename, stat, unlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { findExistingWebhookBinding } from "./existing-webhook-binding.js";
+export function setupCompletionStateFingerprint(state) {
+    return sha256(JSON.stringify(state));
+}
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function sha256(value) {
+    return `sha256:${hash(value)}`;
+}
+function actionId(value) {
+    return `setup_${hash(JSON.stringify(value)).slice(0, 16)}`;
+}
+function adapterForFinding(finding) {
+    if (finding.language !== "typescript" && finding.language !== "javascript") {
+        return "http_ingest";
+    }
+    switch (finding.kind) {
+        case "http_client":
+            return "observeFetch";
+        case "webhook_handler":
+            return "observeWebhook";
+        case "http_server":
+            return "record";
+        case "queue_publish":
+            return "observeQueuePublish";
+        case "queue_consume":
+            return "observeQueueConsumer";
+        case "scheduled_feed":
+            return "observeScheduledFeed";
+    }
+}
+export const supportedCollectorVersion = "0.1.0-alpha.2";
+function installCommand(packageManager) {
+    switch (packageManager) {
+        case "npm":
+            return `npm install @seamward/collector@${supportedCollectorVersion}`;
+        case "pnpm":
+            return `pnpm add @seamward/collector@${supportedCollectorVersion}`;
+        case "yarn":
+            return `yarn add @seamward/collector@${supportedCollectorVersion}`;
+        case "bun":
+            return `bun add @seamward/collector@${supportedCollectorVersion}`;
+    }
+}
+function integrationProtocol(finding) {
+    switch (finding.protocol) {
+        case "http":
+            return "http-api";
+        case "webhook":
+            return "http-webhook";
+        case "queue":
+            return "queue";
+        case "scheduled_feed":
+            return "scheduled-feed";
+    }
+}
+function scopeKey(scope) {
+    return `${scope.direction}:${scope.protocol}`;
+}
+export function discoverIntegrationScopes(discovery) {
+    const byKey = new Map();
+    for (const finding of discovery.findings) {
+        const scope = {
+            direction: finding.direction,
+            protocol: integrationProtocol(finding),
+        };
+        byKey.set(scopeKey(scope), scope);
+    }
+    return [...byKey.values()].sort((left, right) => scopeKey(left).localeCompare(scopeKey(right)));
+}
+const genericBoundaryNames = new Set([
+    "app",
+    "client",
+    "handler",
+    "index",
+    "integration",
+    "integrations",
+    "main",
+    "queue",
+    "routes",
+    "server",
+    "service",
+    "webhook",
+    "webhooks",
+]);
+function boundaryStem(file, scope) {
+    const parts = file.replaceAll("\\", "/").split("/");
+    const raw = (parts.at(-1) ?? "integration")
+        .replace(/\.[^.]+$/, "")
+        .toLowerCase()
+        .replace(/(?:^|[-_.])(api|client|consumer|handler|integration|producer|publisher|queue|routes?|service|webhooks?)(?:$|[-_.])/g, "-")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+    if (raw && !genericBoundaryNames.has(raw))
+        return raw;
+    const parent = parts
+        .at(-2)
+        ?.toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-");
+    if (parent && !genericBoundaryNames.has(parent) && parent !== "src") {
+        return parent;
+    }
+    return `${scope.direction}-${scope.protocol}`;
+}
+function readableBoundaryName(stem) {
+    return stem
+        .split("-")
+        .filter(Boolean)
+        .map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`)
+        .join(" ");
+}
+function contractStem(file) {
+    return path.posix
+        .basename(file.replaceAll("\\", "/"))
+        .replace(/\.(?:json|ya?ml)$/i, "")
+        .replace(/(?:^|[-_.])(openapi|schema|contract|v\d+)(?:$|[-_.])/gi, "-")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Groups discovered operations by business module as well as protocol scope.
+ * This deliberately avoids collapsing two providers that happen to use the
+ * same transport. Generic modules remain review-required instead of being
+ * silently merged.
+ */
+export function discoverIntegrationGroups(discovery) {
+    const groups = new Map();
+    for (const finding of discovery.findings) {
+        const scope = {
+            direction: finding.direction,
+            protocol: integrationProtocol(finding),
+        };
+        const stem = boundaryStem(finding.file, scope);
+        const key = `${scopeKey(scope)}:${stem}`;
+        const current = groups.get(key) ?? { scope, stem, findings: [] };
+        current.findings.push(finding);
+        groups.set(key, current);
+    }
+    return [...groups.values()]
+        .map(({ scope, stem, findings }) => {
+        const setupId = `${stem}-${hash(scopeKey(scope)).slice(0, 8)}`.slice(0, 63);
+        const matchingContracts = discovery.contracts
+            .filter((contract) => {
+            const candidate = contractStem(contract.file);
+            return (candidate.length > 0 &&
+                (candidate.includes(stem) || stem.includes(candidate)));
+        })
+            .map(({ file }) => file)
+            .sort();
+        const generic = stem === `${scope.direction}-${scope.protocol}`;
+        return {
+            id: setupId,
+            name: readableBoundaryName(stem),
+            scope,
+            findingIds: findings.map(({ id }) => id).sort(),
+            files: [...new Set(findings.map(({ file }) => file))].sort(),
+            contractFiles: matchingContracts,
+            confidence: generic ? "review_required" : "high",
+        };
+    })
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+/**
+ * Automatic setup is intentionally narrower than repository discovery.
+ * Ordinary first-party HTTP routes remain visible for an explicit setup
+ * choice, while the one-line flow selects only provider calls and webhook
+ * receivers that the shipped source transformer can instrument safely.
+ */
+export function isAutomaticIntegrationGroup(group) {
+    return (group.confidence === "high" &&
+        ((group.scope.direction === "outbound" &&
+            group.scope.protocol === "http-api") ||
+            (group.scope.direction === "inbound" &&
+                group.scope.protocol === "http-webhook")));
+}
+function findingMatchesScope(finding, scope) {
+    return (finding.direction === scope.direction &&
+        integrationProtocol(finding) === scope.protocol);
+}
+function normalizeContractFile(file) {
+    return path.posix.normalize(file.replaceAll("\\", "/")).replace(/^\.\//, "");
+}
+function validSetupId(value) {
+    return /^[a-z0-9][a-z0-9-]{0,62}$/.test(value);
+}
+export function setupPlanFile(plan) {
+    return plan.setupId
+        ? `.seamward/integrations/${plan.setupId}/setup-plan.json`
+        : ".seamward/setup-plan.json";
+}
+export function setupStateFile(plan) {
+    return plan.setupId
+        ? `.seamward/integrations/${plan.setupId}/setup-state.json`
+        : ".seamward/setup-state.json";
+}
+export function setupStateLockFile(plan) {
+    return plan.setupId
+        ? `.seamward/integrations/${plan.setupId}/setup-state.lock`
+        : ".seamward/setup-state.lock";
+}
+function unsignedPlan(plan) {
+    const { fingerprint: _fingerprint, ...unsigned } = plan;
+    return unsigned;
+}
+function fingerprintPlan(plan) {
+    return `sha256:${hash(JSON.stringify(plan))}`;
+}
+function nodeBootstrapPath(discovery, runtimeTarget, scope, setupId) {
+    const hasTypeScript = discovery.languages.includes("typescript");
+    const extension = hasTypeScript
+        ? "ts"
+        : runtimeTarget === "node-commonjs"
+            ? "mjs"
+            : "js";
+    const hasSourceDirectory = discovery.findings.some(({ file }) => file.startsWith("src/"));
+    const scopeSuffix = setupId
+        ? `.${setupId}`
+        : scope
+            ? `.${scope.direction}-${scope.protocol}`
+            : "";
+    return `${hasSourceDirectory ? "src/" : ""}seamward${scopeSuffix}.generated.${extension}`;
+}
+export function createSetupPlan(discovery, options) {
+    if (options.setupId && !validSetupId(options.setupId)) {
+        throw new Error("Setup ID must contain lowercase letters, numbers, and hyphens");
+    }
+    const availableScopes = discoverIntegrationScopes(discovery);
+    if (!options.integrationScope && availableScopes.length > 1) {
+        throw new Error("Discovery found multiple Integration scopes. Run setup with one explicit --direction and --protocol");
+    }
+    const selectedScope = options.integrationScope ??
+        (availableScopes.length === 1 ? (availableScopes[0] ?? null) : null);
+    if (selectedScope &&
+        availableScopes.length > 0 &&
+        !availableScopes.some((scope) => scopeKey(scope) === scopeKey(selectedScope))) {
+        throw new Error(`No discovered operations match ${scopeKey(selectedScope)}`);
+    }
+    const selectedFindingIds = options.findingIds
+        ? new Set(options.findingIds)
+        : null;
+    const selectedFindings = (selectedScope
+        ? discovery.findings.filter((finding) => findingMatchesScope(finding, selectedScope))
+        : discovery.findings).filter((finding) => selectedFindingIds ? selectedFindingIds.has(finding.id) : true);
+    if (selectedFindingIds &&
+        selectedFindings.length !== selectedFindingIds.size) {
+        throw new Error("One or more selected Integration operations are unavailable");
+    }
+    const requestedContractFiles = [
+        ...new Set((options.contractFiles ?? []).map(normalizeContractFile)),
+    ];
+    if (requestedContractFiles.length > 0 && !selectedScope) {
+        throw new Error("Contract assignment requires one explicit Integration direction and protocol");
+    }
+    const contractsByFile = new Map(discovery.contracts.map((contract) => [contract.file, contract]));
+    for (const file of requestedContractFiles) {
+        if (!contractsByFile.has(file)) {
+            throw new Error(`Contract was not discovered in this project: ${file}`);
+        }
+    }
+    const selectedContracts = requestedContractFiles.map((file) => contractsByFile.get(file));
+    if (selectedScope &&
+        selectedScope.protocol !== "http-api" &&
+        selectedScope.protocol !== "http-webhook" &&
+        selectedContracts.some(({ format }) => format === "openapi")) {
+        throw new Error("OpenAPI contracts require an HTTP API or webhook Integration scope. Use an operation-bound JSON Schema for queue or scheduled-feed contracts");
+    }
+    const selectedContractFiles = new Set(requestedContractFiles);
+    const unassignedContracts = discovery.contracts.filter(({ file }) => !selectedContractFiles.has(file));
+    const scopedDiscovery = {
+        ...discovery,
+        languages: [
+            ...new Set(selectedFindings.map(({ language }) => language)),
+        ].sort(),
+        findings: selectedFindings,
+    };
+    const excludedIntegrationScopes = availableScopes.filter((scope) => !selectedScope || scopeKey(scope) !== scopeKey(selectedScope));
+    const connectionKeyEnvironment = options.setupId
+        ? `SEAMWARD_CONNECTION_KEY_${options.setupId.replaceAll("-", "_")}`.toUpperCase()
+        : selectedScope
+            ? `SEAMWARD_CONNECTION_KEY_${selectedScope.direction}_${selectedScope.protocol}`
+                .replaceAll("-", "_")
+                .toUpperCase()
+            : "SEAMWARD_CONNECTION_KEY";
+    const ingestTokenEnvironment = options.setupId
+        ? `SEAMWARD_INGEST_TOKEN_${options.setupId.replaceAll("-", "_")}`.toUpperCase()
+        : "SEAMWARD_INGEST_TOKEN";
+    const hasNode = scopedDiscovery.languages.some((language) => language === "typescript" || language === "javascript");
+    const runtimeTarget = options.runtimeTarget ?? "unknown";
+    const hasNodeCollector = hasNode && runtimeTarget !== "unknown";
+    const packageManager = hasNodeCollector
+        ? (options.packageManager ?? "npm")
+        : null;
+    const generatedFiles = hasNodeCollector
+        ? [
+            {
+                path: nodeBootstrapPath(scopedDiscovery, runtimeTarget, selectedScope, options.setupId),
+                template: "node_collector_v2",
+            },
+        ]
+        : [];
+    const actions = [];
+    if (hasNodeCollector) {
+        const action = {
+            type: "create_bootstrap",
+            mode: "automatic",
+            adapter: "createSeamwardCollector",
+        };
+        actions.push({ id: actionId(action), ...action });
+    }
+    for (const finding of scopedDiscovery.findings) {
+        const action = {
+            type: "instrument_operation",
+            mode: hasNodeCollector &&
+                (finding.language === "typescript" || finding.language === "javascript")
+                ? "review_required"
+                : "manual",
+            adapter: hasNodeCollector ? adapterForFinding(finding) : "http_ingest",
+            language: finding.language,
+            findingId: finding.id,
+            file: finding.file,
+            line: finding.line,
+            direction: finding.direction,
+            protocol: finding.protocol,
+            operationKind: finding.kind,
+            targetHint: finding.targetHint,
+            confidence: finding.confidence,
+        };
+        actions.push({ id: actionId(action), ...action });
+    }
+    for (const contract of selectedContracts) {
+        const action = {
+            type: "register_contract",
+            mode: "review_required",
+            adapter: contract.format === "openapi" ? "openapi" : "json_schema",
+            file: contract.file,
+            contract,
+            integrationScope: selectedScope ?? undefined,
+        };
+        actions.push({ id: actionId(action), ...action });
+    }
+    const plan = {
+        schemaVersion: "0.2",
+        ...(options.setupId ? { setupId: options.setupId } : {}),
+        analysisFingerprint: discovery.repositoryFingerprint,
+        projectName: options.projectName,
+        integrationScope: selectedScope,
+        excludedIntegrationScopes,
+        unassignedContracts,
+        connectionKeyEnvironment,
+        runtimeTarget,
+        packageManager,
+        requiredEnvironment: [connectionKeyEnvironment, ingestTokenEnvironment],
+        install: hasNodeCollector && packageManager
+            ? {
+                package: "@seamward/collector",
+                command: installCommand(packageManager),
+            }
+            : null,
+        discovery: scopedDiscovery,
+        actions,
+        generatedFiles,
+    };
+    return { ...plan, fingerprint: fingerprintPlan(plan) };
+}
+function legacyBootstrapTemplate(language, connectionKeyEnvironment, ingestTokenEnvironment) {
+    const typeAnnotation = language === "typescript" ? ": string" : "";
+    return `// Generated by Seamward. This file contains no credentials.
+import { createSeamwardCollector } from "@seamward/collector";
+
+function required(name${typeAnnotation})${typeAnnotation} {
+  const value = process.env[name];
+  if (!value) throw new Error(\`\${name} is required\`);
+  return value;
+}
+
+export const seamward = createSeamwardCollector({
+  connectionKey: required("${connectionKeyEnvironment}"),
+  ingestToken: required("${ingestTokenEnvironment}"),
+});
+`;
+}
+function bootstrapTemplateV2(language, connectionKeyEnvironment, ingestTokenEnvironment) {
+    const isTypeScript = language === "typescript";
+    const collectorTypeImport = isTypeScript ? ", type ConnectedCollector" : "";
+    const collectorType = isTypeScript ? ": ConnectedCollector | null" : "";
+    const cachedCollectorType = isTypeScript
+        ? ": ConnectedCollector | undefined"
+        : "";
+    const observeFetchType = isTypeScript
+        ? ': ConnectedCollector["observeFetch"]'
+        : "";
+    const observeWebhookType = isTypeScript
+        ? ': ConnectedCollector["observeWebhook"]'
+        : "";
+    const seamwardType = isTypeScript
+        ? ': Pick<ConnectedCollector, "observeFetch" | "observeWebhook">'
+        : "";
+    return `// Generated by Seamward. This file contains no credentials.
+import { createSeamwardCollector${collectorTypeImport} } from "@seamward/collector";
+
+let activeCollector${cachedCollectorType};
+const setupVerification =
+  process.env.SEAMWARD_INTERNAL_SETUP_VERIFICATION === "1" ||
+  process.env.NODE_ENV === "test";
+
+function configuredCollector()${collectorType} {
+  if (activeCollector) return activeCollector;
+  const connectionKey = process.env["${connectionKeyEnvironment}"];
+  const ingestToken = process.env["${ingestTokenEnvironment}"];
+  if (!connectionKey || !ingestToken) {
+    if (setupVerification) return null;
+    throw new Error(
+      "Seamward runtime credentials are required. Configure the connection key and ingest token before starting observed traffic.",
+    );
+  }
+  try {
+    activeCollector = createSeamwardCollector({ connectionKey, ingestToken });
+    return activeCollector;
+  } catch (error) {
+    if (setupVerification) return null;
+    throw error;
+  }
+}
+
+const observeFetch${observeFetchType} = (meta, fetchFn) => {
+  const collector = configuredCollector();
+  return collector
+    ? collector.observeFetch(meta, fetchFn)
+    : (fetchFn ?? globalThis.fetch);
+};
+
+const observeWebhook${observeWebhookType} = (meta, handler) => {
+  const collector = configuredCollector();
+  return collector
+    ? collector.observeWebhook(meta, handler)
+    : async (payload) => handler(payload);
+};
+
+export const seamward${seamwardType} = { observeFetch, observeWebhook };
+`;
+}
+function resolveWithinProject(root, relativePath) {
+    const normalized = relativePath.split("/").join(path.sep);
+    const resolved = path.resolve(root, normalized);
+    const relative = path.relative(root, resolved);
+    if (relative === "" ||
+        relative.startsWith(`..${path.sep}`) ||
+        relative === ".." ||
+        path.isAbsolute(relative)) {
+        throw new Error(`Generated path escapes the project boundary: ${relativePath}`);
+    }
+    return resolved;
+}
+async function preflightGuarded(file, content, force) {
+    try {
+        const existing = await readFile(file, "utf8");
+        if (existing === content)
+            return { status: "unchanged", existing };
+        if (!force) {
+            throw new Error(`Refusing to overwrite existing generated file: ${file}`);
+        }
+        return { status: "write", existing };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT")
+            throw error;
+    }
+    return { status: "write", existing: null };
+}
+async function assertNoSymlinkPath(root, file) {
+    const relative = path.relative(root, file);
+    let current = root;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        try {
+            if ((await lstat(current)).isSymbolicLink()) {
+                throw new Error(`Refusing generated path through a symbolic link: ${file}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            return;
+        }
+    }
+}
+const staleLockFallbackMs = 15 * 60 * 1000;
+async function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function lockIsStale(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (typeof parsed.pid === "number" &&
+            Number.isInteger(parsed.pid) &&
+            parsed.pid > 0 &&
+            typeof parsed.createdAt === "string" &&
+            Number.isFinite(Date.parse(parsed.createdAt))) {
+            return !(await processIsAlive(parsed.pid));
+        }
+    }
+    catch {
+        // Fall back to age for malformed lock files.
+    }
+    try {
+        return Date.now() - (await stat(file)).mtimeMs > staleLockFallbackMs;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
+async function acquireProjectLock(root, relativeFile, conflictMessage) {
+    const file = resolveWithinProject(root, relativeFile);
+    await assertNoSymlinkPath(root, file);
+    await mkdir(path.dirname(file), { recursive: true });
+    const owner = randomUUID();
+    try {
+        const handle = await open(file, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify({ pid: process.pid, owner, createdAt: new Date().toISOString() })}\n`, "utf8");
+        return {
+            close: async () => {
+                await handle.close();
+                try {
+                    const current = JSON.parse(await readFile(file, "utf8"));
+                    if (current.owner === owner)
+                        await unlink(file);
+                }
+                catch {
+                    // Never delete a lock whose ownership cannot be verified.
+                }
+            },
+        };
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        if (await lockIsStale(file)) {
+            throw new Error(`Stale setup lock requires manual recovery: ${relativeFile}`);
+        }
+        throw new Error(conflictMessage);
+    }
+}
+async function withProjectLock(root, relativeFile, conflictMessage, operation) {
+    const lock = await acquireProjectLock(root, relativeFile, conflictMessage);
+    try {
+        return await operation();
+    }
+    finally {
+        await lock.close();
+    }
+}
+export async function withSetupProjectLock(root, relativeFile, conflictMessage, operation) {
+    return withProjectLock(root, relativeFile, conflictMessage, operation);
+}
+function completableActions(plan) {
+    return plan.actions.filter(({ mode }) => mode !== "automatic");
+}
+export function operatorReviewableSetupActions(plan) {
+    return completableActions(plan).filter(({ type }) => type === "instrument_operation");
+}
+async function readCompletionState(plan, root) {
+    const file = resolveWithinProject(root, setupStateFile(plan));
+    await assertNoSymlinkPath(root, file);
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (parsed.schemaVersion !== "0.2" ||
+            parsed.planFingerprint !== plan.fingerprint ||
+            !Array.isArray(parsed.completedActions) ||
+            parsed.completedActions.some((completion) => typeof completion !== "object" ||
+                completion === null ||
+                typeof completion.actionId !== "string" ||
+                typeof completion.completedAt !== "string" ||
+                !Number.isFinite(Date.parse(completion.completedAt)) ||
+                typeof completion.evidence !== "string" ||
+                completion.evidence.length < 1 ||
+                typeof completion.evidenceFingerprint !== "string" ||
+                !/^sha256:[a-f0-9]{64}$/.test(completion.evidenceFingerprint) ||
+                !Array.isArray(completion.implementationFiles) ||
+                completion.implementationFiles.some((file) => typeof file !== "object" ||
+                    file === null ||
+                    typeof file.path !== "string" ||
+                    typeof file.fingerprint !== "string" ||
+                    !/^sha256:[a-f0-9]{64}$/.test(file.fingerprint))) ||
+            (parsed.integrationBinding !== undefined &&
+                (typeof parsed.integrationBinding !== "object" ||
+                    parsed.integrationBinding === null ||
+                    typeof parsed.integrationBinding.integrationId !== "string" ||
+                    parsed.integrationBinding.integrationId.length < 1 ||
+                    !Number.isFinite(Date.parse(parsed.integrationBinding.recordedAt ?? "")))) ||
+            !validRemoteLifecycle(parsed.remoteLifecycle)) {
+            throw new Error("Setup completion state does not match the reviewed setup plan");
+        }
+        return {
+            schemaVersion: "0.2",
+            planFingerprint: plan.fingerprint,
+            completedActions: [...parsed.completedActions].sort((left, right) => left.actionId.localeCompare(right.actionId)),
+            ...(parsed.integrationBinding
+                ? { integrationBinding: parsed.integrationBinding }
+                : {}),
+            ...(parsed.remoteLifecycle
+                ? { remoteLifecycle: parsed.remoteLifecycle }
+                : {}),
+        };
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        return {
+            schemaVersion: "0.2",
+            planFingerprint: plan.fingerprint,
+            completedActions: [],
+        };
+    }
+}
+function validRemoteLifecycle(value) {
+    if (value === undefined)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const lifecycle = value;
+    if (lifecycle.activation !== undefined &&
+        (typeof lifecycle.activation !== "object" ||
+            lifecycle.activation === null ||
+            typeof lifecycle.activation.contractVersionId !== "string" ||
+            lifecycle.activation.contractVersionId.length < 1 ||
+            !Number.isFinite(Date.parse(lifecycle.activation.recordedAt)))) {
+        return false;
+    }
+    if (lifecycle.firstObservation !== undefined &&
+        (typeof lifecycle.firstObservation !== "object" ||
+            lifecycle.firstObservation === null ||
+            typeof lifecycle.firstObservation.integrationId !== "string" ||
+            typeof lifecycle.firstObservation.observationId !== "string" ||
+            !Number.isFinite(Date.parse(lifecycle.firstObservation.receivedAt)) ||
+            !Number.isFinite(Date.parse(lifecycle.firstObservation.recordedAt)))) {
+        return false;
+    }
+    return true;
+}
+async function writeCompletionState(plan, root, state) {
+    const file = resolveWithinProject(root, setupStateFile(plan));
+    await assertNoSymlinkPath(root, file);
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+    });
+    await assertNoSymlinkPath(root, file);
+    await rename(temporary, file);
+}
+async function withCompletionStateLock(plan, root, operation) {
+    return withProjectLock(root, setupStateLockFile(plan), "Setup state is being updated by another operation", operation);
+}
+export async function inspectSetupCompletionState(plan, rootDirectory) {
+    const root = await realpath(path.resolve(rootDirectory));
+    const state = await readCompletionState(plan, root);
+    return { state, fingerprint: setupCompletionStateFingerprint(state) };
+}
+export async function inspectSetupRemoteLifecycle(plan, rootDirectory) {
+    const root = await realpath(path.resolve(rootDirectory));
+    return (await readCompletionState(plan, root)).remoteLifecycle ?? {};
+}
+export async function inspectSetupIntegrationBinding(plan, rootDirectory) {
+    const root = await realpath(path.resolve(rootDirectory));
+    return ((await readCompletionState(plan, root)).integrationBinding?.integrationId ??
+        null);
+}
+export async function recordSetupIntegrationBinding(plan, rootDirectory, integrationId) {
+    if (!integrationId.trim())
+        throw new Error("Integration ID is required");
+    const root = await realpath(path.resolve(rootDirectory));
+    await withCompletionStateLock(plan, root, async () => {
+        const state = await readCompletionState(plan, root);
+        if (state.integrationBinding?.integrationId === integrationId)
+            return;
+        await writeCompletionState(plan, root, {
+            ...state,
+            integrationBinding: {
+                integrationId,
+                recordedAt: new Date().toISOString(),
+            },
+        });
+    });
+}
+export async function registeredContractVersionIdsForPlan(plan, rootDirectory) {
+    const root = await realpath(path.resolve(rootDirectory));
+    const state = await readCompletionState(plan, root);
+    const contractActionIds = new Set(plan.actions
+        .filter(({ type }) => type === "register_contract")
+        .map(({ id }) => id));
+    return state.completedActions.flatMap((completion) => {
+        if (!contractActionIds.has(completion.actionId))
+            return [];
+        const match = completion.evidence.match(/^registered_contract:(.+)$/);
+        return match?.[1] ? [match[1]] : [];
+    });
+}
+export async function registeredContractVersionIdForFile(plan, rootDirectory, contractFile) {
+    const contractAction = plan.actions.find((action) => action.type === "register_contract" && action.file === contractFile);
+    if (!contractAction)
+        return null;
+    const root = await realpath(path.resolve(rootDirectory));
+    const state = await readCompletionState(plan, root);
+    const completion = state.completedActions.find(({ actionId: completedActionId }) => completedActionId === contractAction.id);
+    const match = completion?.evidence.match(/^registered_contract:(.+)$/);
+    return match?.[1] ?? null;
+}
+export async function recordActivatedContractVersion(plan, rootDirectory, contractVersionId) {
+    const root = await realpath(path.resolve(rootDirectory));
+    await withCompletionStateLock(plan, root, async () => {
+        const state = await readCompletionState(plan, root);
+        await writeCompletionState(plan, root, {
+            ...state,
+            remoteLifecycle: {
+                activation: {
+                    contractVersionId,
+                    recordedAt: new Date().toISOString(),
+                },
+            },
+        });
+    });
+}
+export async function recordFirstSetupObservation(plan, rootDirectory, observation) {
+    const root = await realpath(path.resolve(rootDirectory));
+    await withCompletionStateLock(plan, root, async () => {
+        const state = await readCompletionState(plan, root);
+        if (state.remoteLifecycle?.firstObservation?.integrationId ===
+            observation.integrationId &&
+            state.remoteLifecycle.firstObservation.observationId ===
+                observation.observationId &&
+            state.remoteLifecycle.firstObservation.receivedAt ===
+                observation.receivedAt) {
+            return;
+        }
+        await writeCompletionState(plan, root, {
+            ...state,
+            remoteLifecycle: {
+                ...state.remoteLifecycle,
+                firstObservation: {
+                    ...observation,
+                    recordedAt: new Date().toISOString(),
+                },
+            },
+        });
+    });
+}
+export async function resetSetupCompletionState(plan, rootDirectory) {
+    const root = await realpath(path.resolve(rootDirectory));
+    await withCompletionStateLock(plan, root, () => writeCompletionState(plan, root, {
+        schemaVersion: "0.2",
+        planFingerprint: plan.fingerprint,
+        completedActions: [],
+    }));
+}
+async function completeSetupActions(plan, rootDirectory, actionIds, allowedActions, options, sourceBacked) {
+    const root = await realpath(path.resolve(rootDirectory));
+    return withCompletionStateLock(plan, root, () => completeSetupActionsUnlocked(plan, root, actionIds, allowedActions, options, sourceBacked));
+}
+async function completeSetupActionsUnlocked(plan, rootDirectory, actionIds, allowedActions, options, sourceBacked) {
+    await applySetupPlan(plan, rootDirectory);
+    const root = await realpath(path.resolve(rootDirectory));
+    const current = await readCompletionState(plan, root);
+    if (options.expectedStateFingerprint &&
+        setupCompletionStateFingerprint(current) !==
+            options.expectedStateFingerprint) {
+        throw new Error("Setup state fingerprint does not match current state");
+    }
+    return completeSetupActionsFromCurrent(plan, root, actionIds, allowedActions, options, sourceBacked, current);
+}
+async function completeSetupActionsFromCurrent(plan, root, actionIds, allowedActions, options, sourceBacked, current) {
+    const actions = completableActions(plan);
+    const valid = new Set(allowedActions.map(({ id }) => id));
+    const requested = [...new Set(actionIds)].sort();
+    if (requested.length === 0)
+        throw new Error("At least one action ID is required");
+    const unknown = requested.find((id) => !valid.has(id));
+    if (unknown)
+        throw new Error(`Setup action is not reviewable: ${unknown}`);
+    const evidence = options.evidence?.trim() || "operator_review";
+    if (evidence.length > 256 || /[\u0000-\u001f\u007f]/.test(evidence)) {
+        throw new Error("Setup review evidence is invalid");
+    }
+    const now = new Date().toISOString();
+    const actionById = new Map(actions.map((action) => [action.id, action]));
+    const evidenceByActionId = new Map();
+    for (const requestedActionId of requested) {
+        const action = actionById.get(requestedActionId);
+        if (!action)
+            throw new Error("Setup action no longer exists in the plan");
+        const implementationFiles = sourceBacked && action.type === "instrument_operation"
+            ? [await verifyInstrumentationSource(root, plan, action)]
+            : [];
+        const verification = sourceBacked && action.type === "instrument_operation"
+            ? options.verification
+            : undefined;
+        evidenceByActionId.set(requestedActionId, {
+            implementationFiles,
+            ...(verification ? { verification } : {}),
+            evidenceFingerprint: sha256(JSON.stringify({
+                planFingerprint: plan.fingerprint,
+                actionId: requestedActionId,
+                findingId: action.findingId ?? null,
+                adapter: action.adapter,
+                evidence,
+                implementationFiles,
+                verification: verification ?? null,
+            })),
+        });
+    }
+    const completionById = new Map(current.completedActions.map((completion) => [
+        completion.actionId,
+        completion,
+    ]));
+    let evidenceChanged = false;
+    for (const actionId of requested) {
+        const sourceEvidence = evidenceByActionId.get(actionId);
+        if (!sourceEvidence) {
+            throw new Error("Setup evidence could not be prepared");
+        }
+        const existing = completionById.get(actionId);
+        if (existing?.evidenceFingerprint !== sourceEvidence.evidenceFingerprint) {
+            evidenceChanged = true;
+            completionById.set(actionId, {
+                actionId,
+                completedAt: now,
+                evidence,
+                ...sourceEvidence,
+            });
+        }
+    }
+    const completedActions = [...completionById.values()].sort((left, right) => left.actionId.localeCompare(right.actionId));
+    const completedActionIds = completedActions.map(({ actionId }) => actionId);
+    const completed = new Set(completedActionIds);
+    const pendingActionIds = actions
+        .map(({ id }) => id)
+        .filter((id) => !completed.has(id));
+    if (options.write) {
+        const remoteLifecycle = sourceBacked && evidenceChanged
+            ? current.remoteLifecycle?.activation
+                ? { activation: current.remoteLifecycle.activation }
+                : undefined
+            : current.remoteLifecycle;
+        const { remoteLifecycle: _previousLifecycle, ...currentWithoutLifecycle } = current;
+        await writeCompletionState(plan, root, {
+            ...currentWithoutLifecycle,
+            completedActions,
+            ...(remoteLifecycle ? { remoteLifecycle } : {}),
+        });
+    }
+    return {
+        applied: options.write === true,
+        planFingerprint: plan.fingerprint,
+        completedActionIds,
+        pendingActionIds,
+    };
+}
+export async function completedSetupActionIds(plan, rootDirectory) {
+    if (fingerprintPlan(unsignedPlan(plan)) !== plan.fingerprint) {
+        throw new Error("Setup plan fingerprint does not match its contents");
+    }
+    const root = await realpath(path.resolve(rootDirectory));
+    const state = await readCompletionState(plan, root);
+    const valid = new Set(completableActions(plan).map(({ id }) => id));
+    if (state.completedActions.some(({ actionId }) => !valid.has(actionId))) {
+        throw new Error("Setup completion state contains an unknown action");
+    }
+    return new Set(state.completedActions.map(({ actionId }) => actionId));
+}
+export async function inspectSetupActionEvidence(plan, rootDirectory) {
+    if (fingerprintPlan(unsignedPlan(plan)) !== plan.fingerprint) {
+        throw new Error("Setup plan fingerprint does not match its contents");
+    }
+    const root = await realpath(path.resolve(rootDirectory));
+    const state = await readCompletionState(plan, root);
+    const completionById = new Map(state.completedActions.map((completion) => [
+        completion.actionId,
+        completion,
+    ]));
+    return Promise.all(completableActions(plan).map(async (action) => {
+        const completion = completionById.get(action.id);
+        if (!completion) {
+            return {
+                actionId: action.id,
+                actionType: action.type,
+                status: "pending",
+            };
+        }
+        if (action.type === "register_contract") {
+            return {
+                actionId: action.id,
+                actionType: action.type,
+                status: "registered",
+                evidenceFingerprint: completion.evidenceFingerprint,
+                recordedAt: completion.completedAt,
+            };
+        }
+        let status = completion.implementationFiles.length > 0 &&
+            (action.language === "typescript" || action.language === "javascript")
+            ? "source_verified"
+            : "attested_only";
+        for (const evidenceFile of completion.implementationFiles) {
+            const file = resolveWithinProject(root, evidenceFile.path);
+            await assertNoSymlinkPath(root, file);
+            try {
+                const currentFingerprint = sha256(await readFile(file, "utf8"));
+                if (currentFingerprint !== evidenceFile.fingerprint)
+                    status = "stale";
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    status = "missing";
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        if (status === "source_verified") {
+            try {
+                await verifyInstrumentationSource(root, plan, action);
+            }
+            catch {
+                status = "stale";
+            }
+        }
+        return {
+            actionId: action.id,
+            actionType: action.type,
+            status,
+            evidenceFingerprint: completion.evidenceFingerprint,
+            recordedAt: completion.completedAt,
+        };
+    }));
+}
+export async function reviewSetupActions(plan, rootDirectory, actionIds, options = {}) {
+    return completeSetupActions(plan, rootDirectory, actionIds, operatorReviewableSetupActions(plan), options, false);
+}
+export async function recordSourceBackedSetupEvidence(plan, rootDirectory, actionIds, options = {}) {
+    return completeSetupActions(plan, rootDirectory, actionIds, operatorReviewableSetupActions(plan), options, true);
+}
+export async function recordRegisteredContractAction(plan, rootDirectory, actionId, contractVersionId) {
+    const contractAction = plan.actions.find((action) => action.id === actionId && action.type === "register_contract");
+    if (!contractAction) {
+        throw new Error(`Setup action is not a contract registration: ${actionId}`);
+    }
+    const normalizedContractVersionId = contractVersionId.trim();
+    if (normalizedContractVersionId.length < 1 ||
+        normalizedContractVersionId.length > 200 ||
+        /[\u0000-\u001f\u007f]/.test(normalizedContractVersionId)) {
+        throw new Error("Registered contract version ID is invalid");
+    }
+    return completeSetupActions(plan, rootDirectory, [actionId], [contractAction], {
+        write: true,
+        evidence: `registered_contract:${normalizedContractVersionId}`,
+    }, false);
+}
+function escapedRegularExpression(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function setupInstrumentationMarker(plan, action) {
+    if (!action.file || action.type !== "instrument_operation") {
+        throw new Error("Instrumentation markers require a source operation");
+    }
+    const operations = plan.actions
+        .filter((candidate) => candidate.type === "instrument_operation" &&
+        candidate.file === action.file)
+        .sort((left, right) => (left.line ?? Number.MAX_SAFE_INTEGER) -
+        (right.line ?? Number.MAX_SAFE_INTEGER) ||
+        (left.operationKind ?? "").localeCompare(right.operationKind ?? "") ||
+        left.adapter.localeCompare(right.adapter) ||
+        left.id.localeCompare(right.id));
+    const operationNumber = operations.findIndex((candidate) => candidate.id === action.id);
+    if (operationNumber < 0) {
+        throw new Error("Instrumentation action does not belong to this setup plan");
+    }
+    const kind = (action.operationKind ?? "operation").replaceAll("_", " ");
+    return `seamward-setup: operation ${operationNumber + 1}, ${kind}, ${action.adapter}, original line ${action.line ?? "unknown"}`;
+}
+async function verifyInstrumentationSource(root, plan, action) {
+    if (!action.file) {
+        throw new Error("Source-backed verification failed: action has no file");
+    }
+    const file = resolveWithinProject(root, action.file);
+    await assertNoSymlinkPath(root, file);
+    let content;
+    try {
+        content = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Source-backed verification failed: implementation file is missing (${action.file})`);
+        }
+        throw error;
+    }
+    const marker = setupInstrumentationMarker(plan, action);
+    const markerIndex = content.indexOf(marker);
+    const actionsInFile = plan.actions.filter((candidate) => candidate.type === "instrument_operation" &&
+        candidate.file === action.file);
+    const supportsStaticVerification = action.language === "typescript" || action.language === "javascript";
+    const adapterCall = new RegExp(`(?:\\.|\\b)${escapedRegularExpression(action.adapter)}\\s*\\(`, "g");
+    const legacySingleOperationEvidence = markerIndex < 0 &&
+        actionsInFile.length === 1 &&
+        supportsStaticVerification &&
+        [...content.matchAll(adapterCall)].length === 1;
+    if (!legacySingleOperationEvidence &&
+        (markerIndex < 0 ||
+            content.indexOf(marker, markerIndex + marker.length) >= 0)) {
+        throw new Error(`Source-backed verification failed: ${action.file} is missing the unique marker for operation ${actionsInFile.findIndex((candidate) => candidate.id === action.id) + 1}`);
+    }
+    const nextMarkerIndex = legacySingleOperationEvidence
+        ? -1
+        : content.indexOf("seamward-setup:", markerIndex + marker.length);
+    const actionSegment = legacySingleOperationEvidence
+        ? content
+        : content.slice(markerIndex, nextMarkerIndex < 0 ? content.length : nextMarkerIndex);
+    const adapterCallCount = supportsStaticVerification
+        ? [...actionSegment.matchAll(adapterCall)].length
+        : 0;
+    const existingBinding = supportsStaticVerification &&
+        action.adapter === "observeWebhook" &&
+        action.file &&
+        action.line
+        ? findExistingWebhookBinding({
+            file: action.file,
+            content,
+            line: markerIndex < 0
+                ? action.line
+                : content.slice(0, markerIndex).split("\n").length,
+            ...(action.targetHint ? { targetHint: action.targetHint } : {}),
+        })
+        : null;
+    const existingCollectorBacked = Boolean(existingBinding && actionSegment.includes(existingBinding.marker));
+    if (supportsStaticVerification &&
+        adapterCallCount < 1 &&
+        !existingCollectorBacked) {
+        throw new Error(`Source-backed verification failed: ${action.file} requires a call to ${action.adapter}`);
+    }
+    return { path: action.file, fingerprint: sha256(content) };
+}
+function plannedWrites(plan, root) {
+    const nodeLanguage = plan.discovery.languages.includes("typescript")
+        ? "typescript"
+        : plan.discovery.languages.includes("javascript")
+            ? "javascript"
+            : undefined;
+    const generated = plan.generatedFiles.map((file) => {
+        const content = file.template === "node_collector"
+            ? legacyBootstrapTemplate(nodeLanguage, plan.connectionKeyEnvironment, plan.requiredEnvironment[1])
+            : file.template === "node_collector_v2"
+                ? bootstrapTemplateV2(nodeLanguage, plan.connectionKeyEnvironment, plan.requiredEnvironment[1])
+                : null;
+        if (!content)
+            throw new Error(`Unsupported generated template: ${String(file.template)}`);
+        return {
+            destination: resolveWithinProject(root, file.path),
+            relative: file.path,
+            content,
+        };
+    });
+    return [
+        {
+            destination: resolveWithinProject(root, setupPlanFile(plan)),
+            relative: setupPlanFile(plan),
+            content: `${JSON.stringify(plan, null, 2)}\n`,
+        },
+        ...generated,
+    ];
+}
+export async function inspectSetupPlanFiles(plan, rootDirectory) {
+    if (fingerprintPlan(unsignedPlan(plan)) !== plan.fingerprint) {
+        throw new Error("Setup plan fingerprint does not match its contents");
+    }
+    const root = await realpath(path.resolve(rootDirectory));
+    return Promise.all(plannedWrites(plan, root).map(async ({ destination, relative, content }) => {
+        await assertNoSymlinkPath(root, destination);
+        try {
+            return {
+                file: relative,
+                present: true,
+                matches: (await readFile(destination, "utf8")) === content,
+            };
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            return { file: relative, present: false, matches: false };
+        }
+    }));
+}
+export async function applySetupPlan(plan, rootDirectory, options = {}) {
+    if (plan.schemaVersion !== "0.2") {
+        throw new Error(`Unsupported setup plan version: ${String(plan.schemaVersion)}`);
+    }
+    const expectedFingerprint = fingerprintPlan(unsignedPlan(plan));
+    if (expectedFingerprint !== plan.fingerprint) {
+        throw new Error("Setup plan fingerprint does not match its contents");
+    }
+    const root = await realpath(path.resolve(rootDirectory));
+    const relativeFiles = [
+        setupPlanFile(plan),
+        ...plan.generatedFiles.map(({ path: file }) => file),
+    ];
+    if (!options.write) {
+        return {
+            applied: false,
+            fingerprint: plan.fingerprint,
+            files: relativeFiles,
+        };
+    }
+    await withProjectLock(root, ".seamward/setup-generated.lock", "Generated setup files are being updated by another operation", async () => {
+        const writes = plannedWrites(plan, root).sort((left, right) => {
+            if (left.relative === setupPlanFile(plan))
+                return 1;
+            if (right.relative === setupPlanFile(plan))
+                return -1;
+            return left.relative.localeCompare(right.relative);
+        });
+        const preflight = await Promise.all(writes.map(async ({ destination, content }) => {
+            await assertNoSymlinkPath(root, destination);
+            return preflightGuarded(destination, content, options.force === true);
+        }));
+        const staged = [];
+        const committed = [];
+        try {
+            for (const [index, write] of writes.entries()) {
+                const guard = preflight[index];
+                if (!guard || guard.status !== "write")
+                    continue;
+                await mkdir(path.dirname(write.destination), { recursive: true });
+                const temporary = `${write.destination}.${randomUUID()}.tmp`;
+                await writeFile(temporary, write.content, {
+                    encoding: "utf8",
+                    mode: 0o600,
+                    flag: "wx",
+                });
+                staged.push({
+                    destination: write.destination,
+                    content: write.content,
+                    existing: guard.existing,
+                    temporary,
+                });
+            }
+            for (const write of staged) {
+                await assertNoSymlinkPath(root, write.destination);
+                let current = null;
+                try {
+                    current = await readFile(write.destination, "utf8");
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+                if (current !== write.existing) {
+                    throw new Error(`Generated file changed after preflight: ${write.destination}`);
+                }
+            }
+            for (const write of staged) {
+                if (write.existing === null) {
+                    await link(write.temporary, write.destination);
+                    await unlink(write.temporary);
+                    committed.push({
+                        destination: write.destination,
+                        content: write.content,
+                    });
+                    continue;
+                }
+                const backup = `${write.destination}.${randomUUID()}.backup`;
+                await rename(write.destination, backup);
+                try {
+                    if ((await readFile(backup, "utf8")) !== write.existing) {
+                        throw new Error(`Generated file changed during replacement: ${write.destination}`);
+                    }
+                    await link(write.temporary, write.destination);
+                    await unlink(write.temporary);
+                    committed.push({
+                        destination: write.destination,
+                        content: write.content,
+                        backup,
+                    });
+                }
+                catch (error) {
+                    try {
+                        await rename(backup, write.destination);
+                    }
+                    catch {
+                        // Preserve the backup when an external writer claimed the path.
+                    }
+                    throw error;
+                }
+            }
+            for (const write of committed) {
+                if (write.backup)
+                    await unlink(write.backup).catch(() => undefined);
+            }
+        }
+        catch (error) {
+            for (const write of [...committed].reverse()) {
+                let current = null;
+                try {
+                    current = await readFile(write.destination, "utf8");
+                }
+                catch (readError) {
+                    if (readError.code !== "ENOENT") {
+                        continue;
+                    }
+                }
+                if (current !== write.content)
+                    continue;
+                await unlink(write.destination).catch(() => undefined);
+                if (write.backup) {
+                    await rename(write.backup, write.destination).catch(() => undefined);
+                }
+            }
+            throw error;
+        }
+        finally {
+            await Promise.all(staged.map(({ temporary }) => unlink(temporary).catch(() => undefined)));
+        }
+    });
+    return {
+        applied: true,
+        fingerprint: plan.fingerprint,
+        files: relativeFiles,
+    };
+}
+//# sourceMappingURL=setup-plan.js.map