@topogram/cli 0.3.64 → 0.3.66

package/src/generator/runtime/runtime-check.js

@@ -1,554 +1,4 @@
-import {
-  generateRuntimeApiContracts,
-  buildVerificationSummary,
-  getDefaultEnvironmentProjections,
-  resolveRuntimeTopology,
-  runtimeDemoUserId,
-  selectChecksByVerification,
-  runtimePorts,
-  runtimeUrls
-} from "./shared.js";
-import { getExampleImplementation } from "../../example-implementation.js";
-import { renderNodeScriptRunner } from "./bundle-shared.js";
-
-function buildRuntimeCheckPlan(graph, options = {}) {
-  const implementation = getExampleImplementation(graph, options);
-  const runtimeReference = implementation.runtime.reference;
-  const runtimeChecks = implementation.runtime.checks;
-  const topology = resolveRuntimeTopology(graph, options);
-  const { apiProjection, uiProjection, dbProjection } = getDefaultEnvironmentProjections(graph, options);
-  const verification = buildVerificationSummary(graph, ["runtime", "contract", "journey"]);
-  const apiSelection = selectChecksByVerification(graph, runtimeChecks.apiStage.checks, ["runtime", "contract", "journey"], {
-    keepLookupChecks: true
-  });
-  const resolveLookupCheck = (check) => {
-    if (!check.lookupKey) {
-      return check;
-    }
-    const { lookupKey, ...rest } = check;
-    const path = runtimeReference.runtimeCheck.lookupPaths[check.lookupKey];
-    return path ? { ...rest, path } : rest;
-  };
-  return {
-    type: "runtime_check_plan",
-    name: runtimeReference.runtimeCheck.name,
-    projections: {
-      api: apiProjection.id,
-      ui: uiProjection.id,
-      db: dbProjection.id
-    },
-    topology: {
-      runtimes: topology.runtimes.map((runtime) => ({
-        id: runtime.id,
-        kind: runtime.kind,
-        projection: runtime.projection.id,
-        generator: runtime.generator
-      }))
-    },
-    ...(verification ? { verification } : {}),
-    ...(apiSelection.selection ? { selection: apiSelection.selection } : {}),
-    env: {
-      required: [
-        ...runtimeReference.runtimeCheck.requiredEnv
-      ],
-      apiBase: "TOPOGRAM_API_BASE_URL",
-      webBase: "TOPOGRAM_WEB_BASE_URL",
-      demoContainerId: runtimeReference.runtimeCheck.demoContainerEnvVar,
-      demoPrimaryId: runtimeReference.runtimeCheck.demoPrimaryEnvVar,
-      demoUserId: "TOPOGRAM_DEMO_USER_ID"
-    },
-    report: {
-      outputPath: "state/runtime-check-report.json"
-    },
-    stages: [
-      {
-        ...runtimeChecks.environmentStage,
-        checks: runtimeChecks.environmentStage.checks.map(resolveLookupCheck)
-      },
-      {
-        ...runtimeChecks.apiStage,
-        checks: apiSelection.checks.map(resolveLookupCheck)
-      }
-    ]
-  };
-}
-
-function renderRuntimeCheckEnvExample(graph, options = {}) {
-  const runtimeReference = getExampleImplementation(graph, options).runtime.reference;
-  const urls = runtimeUrls(runtimeReference, resolveRuntimeTopology(graph, options));
-  return `TOPOGRAM_API_BASE_URL=${urls.api}
-TOPOGRAM_WEB_BASE_URL=${urls.web}
-TOPOGRAM_DEMO_USER_ID=${runtimeDemoUserId(runtimeReference)}
-${runtimeReference.environment.envExample || ""}
-`;
-}
-
-function renderRuntimeCheckReadme(graph, options = {}) {
-  const runtimeReference = getExampleImplementation(graph, options).runtime.reference;
-  const verification = buildVerificationSummary(graph, ["runtime", "contract", "journey"]);
-  const stageNames = (runtimeReference.runtimeCheck.stageNotes && runtimeReference.runtimeCheck.stageNotes.length > 0)
-    ? runtimeReference.runtimeCheck.stageNotes
-    : [
-        {
-          id: "environment",
-          summary: "required env, web readiness, API health, API readiness, and seeded data checks"
-        },
-        {
-          id: "api",
-          summary: "core API happy paths, lookup endpoints, and important negative cases"
-        }
-      ];
-  const notes = (runtimeReference.runtimeCheck.notes && runtimeReference.runtimeCheck.notes.length > 0)
-    ? runtimeReference.runtimeCheck.notes
-    : [
-        "Mutating checks exercise the example's create/update/terminal flows.",
-        "Lookup checks verify the generated lookup endpoints configured for the example.",
-        "Later stages are skipped if environment readiness fails.",
-        "The generated server exposes both `/health` and `/ready`.",
-        "Use the smoke bundle for a faster minimal confidence check.",
-        "Use this runtime-check bundle for richer staged verification and JSON reporting."
-      ];
-  return `# ${runtimeReference.runtimeCheck.bundleTitle}
-
-This bundle gives you richer staged runtime verification for the generated stack.
-
-Use it when you want more than a quick smoke test. It goes beyond the lightweight smoke bundle by checking environment readiness, API health, DB-backed seeded data, and deeper API behavior.
-
-## Stages
-
-${stageNames.map((stage) => `- \`${stage.id}\`: ${stage.summary}`).join("\n")}
-
-## Usage
-
-1. Copy \`.env.example\` to \`.env\` if needed
-2. Run \`bash ./scripts/check.sh\`
-3. Inspect \`state/runtime-check-report.json\`
-
-## Notes
-
-${notes.map((note) => `- ${note}`).join("\n")}
-${verification ? `\n## Canonical Verification\n\n- Sources: ${verification.sources.map((entry) => `\`${entry.id}\``).join(", ")}\n- Scenarios: ${verification.scenarios.map((entry) => entry.label).join(", ")}` : ""}
-`;
-}
-
-function renderRuntimeCheckScript() {
-  return renderNodeScriptRunner("check.mjs", { searchParentEnv: true });
-}
-
-function renderRuntimeCheckModule(graph, options = {}) {
-  const implementation = getExampleImplementation(graph, options);
-  const runtimeReference = implementation.runtime.reference;
-  const runtimeCheckRenderers = implementation.runtime.checkRenderers;
-  const ports = runtimePorts(runtimeReference, resolveRuntimeTopology(graph, options));
-  return `import fs from "node:fs/promises";
-import { execFile } from "node:child_process";
-import path from "node:path";
-import { promisify } from "node:util";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const rootDir = path.resolve(__dirname, "..");
-const plan = JSON.parse(await fs.readFile(path.join(rootDir, "runtime-check-plan.json"), "utf8"));
-const apiContracts = JSON.parse(await fs.readFile(path.join(rootDir, "api-contracts.json"), "utf8"));
-const reportPath = path.join(rootDir, plan.report.outputPath);
-const execFileAsync = promisify(execFile);
-
-const envVars = Object.fromEntries(Object.entries(plan.env).filter(([, value]) => typeof value === "string"));
-${runtimeCheckRenderers.renderRuntimeCheckState()}
-
-function envValue(name) {
-  const direct = process.env[name];
-  if (direct) {
-    return direct;
-  }
-
-  const fallbackMap = {
-    TOPOGRAM_API_BASE_URL: process.env.PUBLIC_TOPOGRAM_API_BASE_URL || "http://localhost:${ports.server}",
-    TOPOGRAM_WEB_BASE_URL: process.env.PUBLIC_TOPOGRAM_WEB_BASE_URL || \`http://localhost:\${process.env.WEB_PORT || "${ports.web}"}\`,
-    ${runtimeReference.runtimeCheck.demoContainerEnvVar}: process.env.PUBLIC_TOPOGRAM_DEMO_CONTAINER_ID || "",
-    ${runtimeReference.runtimeCheck.demoPrimaryEnvVar}: process.env.PUBLIC_TOPOGRAM_DEMO_PRIMARY_ID || "",
-    TOPOGRAM_DEMO_USER_ID: process.env.PUBLIC_TOPOGRAM_AUTH_USER_ID || process.env.PUBLIC_TOPOGRAM_DEMO_USER_ID || "",
-    TOPOGRAM_AUTH_USER_ID: process.env.TOPOGRAM_DEMO_USER_ID || ""
-  };
-
-  return fallbackMap[name] || "";
-}
-
-function apiBase() {
-  return envValue(plan.env.apiBase);
-}
-
-function webBase() {
-  return envValue(plan.env.webBase);
-}
-
-function stackStartHint() {
-  return "Start the generated stack with 'npm run dev' from the app bundle, or 'npm run app:dev' from the project root, then rerun this command.";
-}
-
-function describeFetchError(error) {
-  if (error?.cause?.code) {
-    return error.cause.code;
-  }
-  if (Array.isArray(error?.cause?.errors) && error.cause.errors.length > 0) {
-    return [...new Set(error.cause.errors.map((entry) => entry.code).filter(Boolean))].join(", ");
-  }
-  return error instanceof Error ? error.message : String(error);
-}
-
-async function fetchWithStackHint(url, init, label) {
-  try {
-    return await fetch(url, init);
-  } catch (error) {
-    throw new Error(\`\${label} is not reachable at \${url.toString()}. \${stackStartHint()} Original error: \${describeFetchError(error)}\`);
-  }
-}
-
-function resolveCheckPath(pathTemplate) {
-  return String(pathTemplate || "")
-    .replace(/\\$env:([A-Z0-9_]+)/g, (_, name) => encodeURIComponent(envValue(name)))
-    .replace(/\\$state:primary_id/g, encodeURIComponent(String(state.latestPrimary?.id || state.createdPrimary?.id || "")));
-}
-
-function authToken() {
-  return envValue("TOPOGRAM_AUTH_TOKEN");
-}
-
-function pathParamValue(token) {
-  if (typeof token !== "string") {
-    return token;
-  }
-  if (token.startsWith("$env:")) {
-    return envValue(token.slice(5));
-  }
-  if (token === "$state:primary_id") {
-    return state.latestPrimary?.id || state.createdPrimary?.id || "";
-  }
-  return token;
-}
-
-function contractFor(capabilityId) {
-  const contract = apiContracts[capabilityId];
-  if (!contract) {
-    throw new Error(\`Missing API contract for \${capabilityId}\`);
-  }
-  return contract;
-}
-
-function buildUrl(base, endpointPath, pathParams = {}) {
-  let resolvedPath = endpointPath;
-  for (const [name, rawValue] of Object.entries(pathParams)) {
-    const value = pathParamValue(rawValue);
-    resolvedPath = resolvedPath.replace(\`:\${name}\`, encodeURIComponent(String(value)));
-  }
-  return new URL(resolvedPath, base);
-}
-
-function inferPathParams(contract, overrides = {}) {
-  const params = {};
-  for (const field of contract.requestContract?.transport?.path || []) {
-    if (Object.prototype.hasOwnProperty.call(overrides, field.name)) {
-      params[field.transport.wireName] = overrides[field.name];
-      continue;
-    }
-    if (
-      field.name.endsWith("_id") &&
-      field.transport?.wireName === "id" &&
-      field.name !== "job_id"
-    ) {
-      params[field.transport.wireName] = "$state:primary_id";
-      continue;
-    }
-    if (field.name === "job_id") {
-      throw new Error("Runtime checks do not support job_id paths in v1");
-    }
-  }
-  return params;
-}
-
-${runtimeCheckRenderers.renderRuntimeCheckCreatePayload()}
-
-function assertCondition(condition, message) {
-  if (!condition) {
-    throw new Error(message);
-  }
-}
-
-function assertErrorResponse(responseBody, expectedCode, label) {
-  assertCondition(responseBody && typeof responseBody === "object", \`\${label} did not return a JSON object body\`);
-  assertCondition(responseBody.error && typeof responseBody.error === "object", \`\${label} did not include an error object\`);
-  assertCondition(typeof responseBody.error.code === "string" && responseBody.error.code.length > 0, \`\${label} did not include an error code\`);
-  assertCondition(typeof responseBody.error.message === "string" && responseBody.error.message.length > 0, \`\${label} did not include an error message\`);
-  if (expectedCode) {
-    assertCondition(responseBody.error.code === expectedCode, \`\${label} expected error code \${expectedCode}, got \${responseBody.error.code}\`);
-  }
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function appleScriptString(value) {
-  return JSON.stringify(String(value ?? ""));
-}
-
-async function runSafariBrowserCheck(definition) {
-  if (process.platform !== "darwin") {
-    throw new Error("web_browser_contract is only supported on macOS local stacks");
-  }
-
-  const targetUrl = new URL(resolveCheckPath(definition.path), webBase()).toString();
-  const waitMs = Number(process.env.TOPOGRAM_BROWSER_WAIT_MS || "8000");
-  const pollMs = Number(process.env.TOPOGRAM_BROWSER_POLL_MS || "250");
-  const pollLimit = Math.max(1, Math.ceil(waitMs / pollMs));
-  const pollDelaySeconds = pollMs / 1000;
-  const browserApp = process.env.TOPOGRAM_BROWSER_APP || "Safari";
-  const script = [
-    \`set targetUrl to \${appleScriptString(targetUrl)}\`,
-    \`set expectedText to \${appleScriptString(definition.expectText || "")}\`,
-    \`set forbiddenText to \${appleScriptString(definition.expectNotText || "")}\`,
-    \`set pollLimit to \${appleScriptString(pollLimit)} as integer\`,
-    \`set pollDelay to \${appleScriptString(pollDelaySeconds)} as real\`,
-    \`tell application \${appleScriptString(browserApp)}\`,
-    "activate",
-    "set runtimeDoc to make new document with properties {URL:targetUrl}",
-    "repeat with attempt from 1 to pollLimit",
-    "delay pollDelay",
-    "try",
-    "set bodyText to do JavaScript \\"document.body ? document.body.innerText : ''\\" in runtimeDoc",
-    "if (expectedText is \\"\\" or bodyText contains expectedText) and (forbiddenText is \\"\\" or bodyText does not contain forbiddenText) then exit repeat",
-    "end try",
-    "end repeat",
-    "set finalText to do JavaScript \\"document.body ? document.body.innerText : ''\\" in runtimeDoc",
-    "close runtimeDoc",
-    "return finalText",
-    "end tell"
-  ];
-  const args = script.flatMap((line) => ["-e", line]);
-  const { stdout, stderr } = await execFileAsync("osascript", args);
-  if (stderr && stderr.trim()) {
-    throw new Error(\`browser check failed: \${stderr.trim()}\`);
-  }
-  return stdout.trim();
-}
-
-${runtimeCheckRenderers.renderRuntimeCheckHelpers()}
-
-async function parseResponseBody(response) {
-  const text = await response.text();
-  if (!text) {
-    return null;
-  }
-  const contentType = response.headers.get("content-type") || "";
-  if (contentType.includes("application/json")) {
-    return JSON.parse(text);
-  }
-  return text;
-}
-
-async function requestContract(capabilityId, { payload = null, pathParams = null, headers = {} } = {}) {
-  const contract = contractFor(capabilityId);
-  const resolvedPathParams = pathParams || inferPathParams(contract);
-  const url = buildUrl(apiBase(), contract.endpoint.path, resolvedPathParams);
-  const requestHeaders = new Headers(headers);
-  if ((contract.endpoint.authz || []).length > 0 && authToken() && !requestHeaders.has("Authorization")) {
-    requestHeaders.set("Authorization", \`Bearer \${authToken()}\`);
-  }
-  let body;
-  if (payload && (contract.requestContract?.transport?.body || []).length > 0) {
-    requestHeaders.set("content-type", "application/json");
-    body = JSON.stringify(payload);
-  }
-  const response = await fetchWithStackHint(url, {
-    method: contract.endpoint.method,
-    headers: requestHeaders,
-    body
-  }, "api service");
-  const responseBody = await parseResponseBody(response);
-  return { contract, response, responseBody, url: url.toString() };
-}
-
-function preconditionStatusFor(contract) {
-  return contract.endpoint.preconditions?.[0]?.error || 412;
-}
-
-function visibleTextFromHtml(html) {
-  return String(html || "")
-    .replace(/<script\\b[^>]*>[\\s\\S]*?<\\/script>/gi, " ")
-    .replace(/<style\\b[^>]*>[\\s\\S]*?<\\/style>/gi, " ")
-    .replace(/<[^>]+>/g, " ")
-    .replace(/&nbsp;/g, " ")
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/\\s+/g, " ")
-    .trim();
-}
-
-function checkResultTemplate(definition) {
-  return {
-    id: definition.id,
-    kind: definition.kind,
-    mandatory: definition.mandatory !== false,
-    mutating: Boolean(definition.mutating),
-    ok: null,
-    skipped: false,
-    durationMs: 0,
-    error: null,
-    resources: {}
-  };
-}
-
-async function runCheck(definition) {
-  const startedAt = Date.now();
-  const result = checkResultTemplate(definition);
-  try {
-    if (definition.id === "required_env") {
-      const missing = plan.env.required.filter((name) => !envValue(name));
-      assertCondition(missing.length === 0, \`Missing required environment variables: \${missing.join(", ")}\`);
-    } else if (definition.kind === "web_contract") {
-      const response = await fetchWithStackHint(new URL(resolveCheckPath(definition.path), webBase()), undefined, "web app");
-      const body = await response.text();
-      const bodyText = visibleTextFromHtml(body);
-      assertCondition(response.status === definition.expectStatus, \`web readiness expected \${definition.expectStatus}, got \${response.status}\`);
-      assertCondition(bodyText.includes(definition.expectText), \`web readiness did not include expected text: \${definition.expectText}\`);
-      if (definition.expectNotText) {
-        assertCondition(!bodyText.includes(definition.expectNotText), \`web readiness unexpectedly included text: \${definition.expectNotText}\`);
-      }
-    } else if (definition.kind === "web_browser_contract") {
-      const bodyText = await runSafariBrowserCheck(definition);
-      if (definition.expectText) {
-        assertCondition(bodyText.includes(definition.expectText), \`browser check did not include expected text: \${definition.expectText}\`);
-      }
-      if (definition.expectNotText) {
-        assertCondition(!bodyText.includes(definition.expectNotText), \`browser check unexpectedly included text: \${definition.expectNotText}\`);
-      }
-    } else if (definition.kind === "api_health") {
-      const response = await fetchWithStackHint(new URL(definition.path, apiBase()), undefined, "api service");
-      const responseBody = await parseResponseBody(response);
-      assertCondition(response.status === definition.expectStatus, \`api health expected \${definition.expectStatus}, got \${response.status}\`);
-      assertCondition(responseBody?.ok === definition.expectOk, "api health did not report ok");
-    } else if (definition.kind === "api_ready") {
-      const response = await fetchWithStackHint(new URL(definition.path, apiBase()), undefined, "api service");
-      const responseBody = await parseResponseBody(response);
-      assertCondition(response.status === definition.expectStatus, \`api readiness expected \${definition.expectStatus}, got \${response.status}\`);
-      assertCondition(responseBody?.ready === definition.expectReady, "api readiness did not report ready");
-${runtimeCheckRenderers.renderRuntimeCheckCases()}
-    } else {
-      throw new Error(\`Unsupported runtime check id: \${definition.id}\`);
-    }
-    result.ok = true;
-  } catch (error) {
-    result.ok = false;
-    result.error = error instanceof Error ? error.message : String(error);
-  } finally {
-    result.durationMs = Date.now() - startedAt;
-  }
-  return result;
-}
-
-function stageSummary(stageDefinition, checks) {
-  const failedMandatory = checks.some((check) => check.ok === false && check.mandatory);
-  const skipped = checks.every((check) => check.skipped);
-  return {
-    id: stageDefinition.id,
-    name: stageDefinition.name,
-    ok: skipped ? null : !failedMandatory,
-    skipped,
-    checks
-  };
-}
-
-function skippedChecksForStage(stageDefinition, reason) {
-  return stageDefinition.checks.map((definition) => ({
-    ...checkResultTemplate(definition),
-    skipped: true,
-    error: reason
-  }));
-}
-
-function logCheck(stageId, result) {
-  const icon = result.skipped ? "-" : result.ok ? "[ok]" : "[fail]";
-  const suffix = result.error ? \` - \${result.error}\` : "";
-  console.log(\`\${icon} \${stageId}:\${result.id} (\${result.durationMs}ms)\${suffix}\`);
-}
-
-async function writeReport(report) {
-  await fs.mkdir(path.dirname(reportPath), { recursive: true });
-  await fs.writeFile(reportPath, \`\${JSON.stringify(report, null, 2)}\\n\`, "utf8");
-}
-
-const report = {
-  ok: true,
-  name: plan.name,
-  reportPath: plan.report.outputPath,
-  stages: [],
-  generatedAt: new Date().toISOString()
-};
-
-let stopFurtherStages = false;
-
-for (const stageDefinition of plan.stages) {
-  if (stopFurtherStages) {
-    const skippedChecks = skippedChecksForStage(stageDefinition, "Skipped because a prior fail-fast stage failed");
-    for (const check of skippedChecks) {
-      logCheck(stageDefinition.id, check);
-    }
-    report.stages.push(stageSummary(stageDefinition, skippedChecks));
-    continue;
-  }
-
-  const checks = [];
-  for (const checkDefinition of stageDefinition.checks) {
-    const result = await runCheck(checkDefinition);
-    checks.push(result);
-    logCheck(stageDefinition.id, result);
-    if (stageDefinition.failFast && result.ok === false && result.mandatory) {
-      stopFurtherStages = true;
-      break;
-    }
-  }
-
-  if (stopFurtherStages && checks.length < stageDefinition.checks.length) {
-    const remaining = stageDefinition.checks.slice(checks.length).map((definition) => ({
-      ...checkResultTemplate(definition),
-      skipped: true,
-      error: "Skipped because this stage failed in fail-fast mode"
-    }));
-    for (const check of remaining) {
-      logCheck(stageDefinition.id, check);
-    }
-    checks.push(...remaining);
-  }
-
-  report.stages.push(stageSummary(stageDefinition, checks));
-}
-
-report.ok = report.stages.every((stage) => stage.ok !== false);
-await writeReport(report);
-console.log(JSON.stringify(report, null, 2));
-
-if (!report.ok) {
-  process.exitCode = 1;
-}
-`;
-}
-
-export function generateRuntimeCheckBundle(graph, options = {}) {
-  const plan = buildRuntimeCheckPlan(graph, options);
-  return {
-    ".env.example": renderRuntimeCheckEnvExample(graph, options),
-    "README.md": renderRuntimeCheckReadme(graph, options),
-    "runtime-check-plan.json": `${JSON.stringify(plan, null, 2)}\n`,
-    "api-contracts.json": `${JSON.stringify(generateRuntimeApiContracts(graph), null, 2)}\n`,
-    "scripts/check.sh": renderRuntimeCheckScript(),
-    "scripts/check.mjs": renderRuntimeCheckModule(graph, options)
-  };
-}
-
-export function generateRuntimeCheckPlan(graph, options = {}) {
-  return buildRuntimeCheckPlan(graph, options);
-}
+export {
+  generateRuntimeCheckBundle,
+  generateRuntimeCheckPlan
+} from "./runtime-check/index.js";