@topogram/cli 0.3.60 → 0.3.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.60",
+  "version": "0.3.62",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/cli.js

@@ -153,6 +153,17 @@ const KNOWN_CLI_CONSUMER_WORKFLOWS = {
   "topogram-hello": "Topogram Package Verification",
   "topograms": "Catalog Verification"
 };
+const KNOWN_CLI_CONSUMER_WORKFLOW_JOBS = {
+  "topograms": [
+    "Validate catalog",
+    "Smoke native starter",
+    "Smoke starter alias (hello-web)",
+    "Smoke starter alias (hello-api)",
+    "Smoke starter alias (hello-db)",
+    "Smoke starter alias (web-api)",
+    "Smoke starter alias (web-api-db)"
+  ]
+};
 const PACKAGE_UPDATE_CLI_CHECK_SCRIPTS = [
   "cli:surface",
   "doctor",
@@ -199,7 +210,7 @@ function printUsage(options = {}) {
   console.log("   or: topogram widget check [path] [--projection <id>] [--widget <id>] [--json]");
   console.log("   or: topogram widget behavior [path] [--projection <id>] [--widget <id>] [--json]");
   console.log("   or: topogram generate [path] [--out <path>]");
-  console.log("   or: topogram generate [path] --generate <target> [--json|--write --out-dir <path>]");
+  console.log("   or: topogram emit <target> [path] [--json|--write --out-dir <path>]");
   console.log("   or: topogram query list [--json]");
   console.log("   or: topogram query show <name> [--json]");
   console.log("   or: topogram trust template [path]");
@@ -259,6 +270,8 @@ function printUsage(options = {}) {
   console.log("  topogram query list");
   console.log("  topogram query show widget-behavior");
   console.log("  topogram query widget-behavior ./topogram --projection proj_web_surface --json");
+  console.log("  topogram emit ui-widget-contract --widget widget_data_grid --json");
+  console.log("  topogram emit widget-conformance-report ./topogram --projection proj_web_surface --json");
   console.log("  topogram generator list");
   console.log("  topogram generator show @topogram/generator-react-web");
   console.log("  topogram generator check ./generator-package");
@@ -327,7 +340,8 @@ function printUsage(options = {}) {
   console.log("   or: topogram template show <id> [--json] [--catalog <path-or-source>]");
   console.log("   or: topogram import app <path> [--from <track[,track]>] [--write]");
   console.log("   or: topogram validate <path>");
-  console.log("   or: node ./src/cli.js <path> [--json] [--validate] [--resolve] [--generate <target>] [--workflow <name>] [--mode <id>] [--from <track[,track]>] [--adopt <selector>] [--refresh-adopted] [--shape <id>] [--capability <id>] [--widget <id>] [--projection <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--task <id>] [--profile <id>] [--from-snapshot <path>] [--from-topogram <path>] [--write] [--out-dir <path>]");
+  console.log("   or: node ./src/cli.js <path> [--json] [--validate] [--resolve] [--workflow <name>] [--mode <id>] [--from <track[,track]>] [--adopt <selector>] [--refresh-adopted] [--shape <id>] [--capability <id>] [--widget <id>] [--projection <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--task <id>] [--profile <id>] [--from-snapshot <path>] [--from-topogram <path>] [--write] [--out-dir <path>]");
+  console.log("   or: node ./src/cli.js emit <target> [path] [--json] [--write] [--out-dir <path>]");
   console.log("   or: node ./src/cli.js import app <path> [--from <track[,track]>] [--write]");
   console.log("   or: node ./src/cli.js import docs <path> [--write]");
   console.log("   or: node ./src/cli.js generate journeys <path> [--write]");
@@ -400,11 +414,23 @@ function printNewHelp() {
 function printGenerateHelp() {
   console.log("Usage: topogram generate [path] [--out <path>]");
   console.log("   or: topogram generate app [path] [--out <path>]");
-  console.log("   or: topogram generate [path] --generate <target> [--json]");
-  console.log("   or: topogram generate [path] --generate <target> --write [--out-dir <path>]");
   console.log("");
   console.log("Defaults: path is ./topogram and app generation writes ./app.");
-  console.log("Explicit --generate targets print JSON by default and write files only with --write.");
+  console.log("Use `topogram emit <target>` for contracts, reports, snapshots, migration plans, and other artifacts.");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram generate");
+  console.log("  topogram generate ./topogram --out ./app");
+  console.log("  topogram generate app ./topogram --out ./app");
+}
+
+function printEmitHelp() {
+  console.log("Usage: topogram emit <target> [path] [--json]");
+  console.log("   or: topogram emit <target> [path] --write [--out-dir <path>]");
+  console.log("");
+  console.log("Emits named contracts, reports, snapshots, migration plans, and other artifacts.");
+  console.log("");
+  console.log("Defaults: path is ./topogram. Emit prints to stdout unless --write is passed. --write writes ./artifacts unless --out-dir is supplied.");
   console.log("");
   console.log("Common artifact targets:");
   console.log("  ui-widget-contract");
@@ -422,13 +448,12 @@ function printGenerateHelp() {
   console.log("  --journey <id>");
   console.log("");
   console.log("Examples:");
-  console.log("  topogram generate");
-  console.log("  topogram generate ./topogram --out ./app");
-  console.log("  topogram generate app ./topogram --out ./app");
-  console.log("  topogram generate ./topogram --generate ui-widget-contract --widget widget_data_grid --json");
-  console.log("  topogram generate ./topogram --generate widget-conformance-report --projection proj_web_surface --json");
-  console.log("  topogram generate ./topogram --generate widget-behavior-report --projection proj_web_surface --json");
-  console.log("  topogram generate ./topogram --generate ui-widget-contract --write --out-dir ./contracts");
+  console.log("  topogram emit ui-widget-contract --widget widget_data_grid --json");
+  console.log("  topogram emit widget-conformance-report ./topogram --projection proj_web_surface --json");
+  console.log("  topogram emit widget-behavior-report ./topogram --projection proj_web_surface --json");
+  console.log("  topogram emit db-schema-snapshot ./topogram --projection proj_db_postgres --json");
+  console.log("  topogram emit sql-migration ./topogram --projection proj_db_postgres --from-snapshot ./state/current.json");
+  console.log("  topogram emit ui-widget-contract --write --out-dir ./contracts");
 }
 
 function printWidgetHelp() {
@@ -858,6 +883,10 @@ function printCommandHelp(command) {
     printGenerateHelp();
     return true;
   }
+  if (command === "emit") {
+    printEmitHelp();
+    return true;
+  }
   if (command === "widget") {
     printWidgetHelp();
     return true;
@@ -3211,6 +3240,14 @@ function expectedConsumerWorkflowName(name) {
   return KNOWN_CLI_CONSUMER_WORKFLOWS[name] || null;
 }
 
+/**
+ * @param {string} name
+ * @returns {string[]}
+ */
+function expectedConsumerWorkflowJobs(name) {
+  return KNOWN_CLI_CONSUMER_WORKFLOW_JOBS[name] || [];
+}
+
 /**
  * @param {string[]} args
  * @param {string} cwd
@@ -3351,16 +3388,18 @@ function waitForConsumerCi(consumer, options = {}) {
 /**
  * @param {{ name: string, root?: string|null, workflow?: string|null }} consumer
  * @param {{ strict?: boolean }} [options]
- * @returns {{ checked: boolean, ok: boolean|null, expectedWorkflow: string|null, headSha: string|null, run: { databaseId?: number, workflowName?: string, status?: string, conclusion?: string, headSha?: string, url?: string }|null, diagnostics: Array<Record<string, any>> }}
+ * @returns {{ checked: boolean, ok: boolean|null, expectedWorkflow: string|null, expectedJobs: string[], headSha: string|null, run: { databaseId?: number, workflowName?: string, status?: string, conclusion?: string, headSha?: string, url?: string, jobs?: Array<Record<string, any>> }|null, diagnostics: Array<Record<string, any>> }}
  */
 function inspectConsumerCi(consumer, options = {}) {
   const diagnostics = [];
   const expectedWorkflow = consumer.workflow || expectedConsumerWorkflowName(consumer.name);
+  const expectedJobs = expectedConsumerWorkflowJobs(consumer.name);
   if (!consumer.root || !fs.existsSync(consumer.root)) {
     return {
       checked: false,
       ok: null,
       expectedWorkflow,
+      expectedJobs,
       headSha: null,
       run: null,
       diagnostics: []
@@ -3388,6 +3427,7 @@ function inspectConsumerCi(consumer, options = {}) {
       checked: true,
       ok: false,
       expectedWorkflow,
+      expectedJobs,
       headSha,
       run: null,
       diagnostics
@@ -3424,6 +3464,7 @@ function inspectConsumerCi(consumer, options = {}) {
       checked: true,
       ok: false,
       expectedWorkflow,
+      expectedJobs,
       headSha,
       run: null,
       diagnostics
@@ -3454,6 +3495,7 @@ function inspectConsumerCi(consumer, options = {}) {
       checked: true,
       ok: false,
       expectedWorkflow,
+      expectedJobs,
       headSha,
       run: null,
       diagnostics
@@ -3477,17 +3519,105 @@ function inspectConsumerCi(consumer, options = {}) {
       suggestedFix: "Wait for or fix the consumer verification workflow, then rerun release status."
     });
   }
+  if (expectedJobs.length > 0 && run.databaseId) {
+    const jobResult = inspectConsumerWorkflowJobs(consumer, run.databaseId, expectedJobs, options);
+    if (jobResult.jobs) {
+      run.jobs = jobResult.jobs;
+    }
+    diagnostics.push(...jobResult.diagnostics);
+  } else if (expectedJobs.length > 0) {
+    diagnostics.push({
+      code: "release_consumer_ci_jobs_unavailable",
+      severity: options.strict ? "error" : "warning",
+      message: `${consumer.name} ${expectedWorkflow} run did not include a database id, so expected jobs could not be inspected.`,
+      path: run.url || `attebury/${consumer.name}`,
+      suggestedFix: "Rerun release status after GitHub exposes the workflow run id."
+    });
+  }
+  const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
   return {
     checked: true,
-    ok: diagnostics.filter((diagnostic) => diagnostic.severity === "error").length === 0 &&
+    ok: errorCount === 0 &&
       (!options.strict || (run.status === "completed" && run.conclusion === "success" && (!headSha || !run.headSha || run.headSha === headSha))),
     expectedWorkflow,
+    expectedJobs,
     headSha,
     run,
     diagnostics
   };
 }
 
+/**
+ * @param {{ name: string, root?: string|null }} consumer
+ * @param {number|string} runId
+ * @param {string[]} expectedJobs
+ * @param {{ strict?: boolean }} [options]
+ * @returns {{ jobs: Array<Record<string, any>>|null, diagnostics: Array<Record<string, any>> }}
+ */
+function inspectConsumerWorkflowJobs(consumer, runId, expectedJobs, options = {}) {
+  const diagnostics = [];
+  const result = childProcess.spawnSync("gh", [
+    "run",
+    "view",
+    String(runId),
+    "--repo",
+    `attebury/${consumer.name}`,
+    "--json",
+    "jobs"
+  ], {
+    cwd: consumer.root || process.cwd(),
+    encoding: "utf8",
+    env: { ...process.env, PATH: process.env.PATH || "" }
+  });
+  if (result.status !== 0) {
+    diagnostics.push(commandDiagnostic({
+      code: "release_consumer_ci_jobs_unavailable",
+      severity: options.strict ? "error" : "warning",
+      message: `Could not inspect expected jobs for ${consumer.name}.`,
+      path: `attebury/${consumer.name}`,
+      suggestedFix: "Check GitHub CLI auth/network access, then rerun release status.",
+      result
+    }));
+    return { jobs: null, diagnostics };
+  }
+  let payload = {};
+  try {
+    payload = JSON.parse(String(result.stdout || "{}"));
+  } catch (error) {
+    diagnostics.push({
+      code: "release_consumer_ci_jobs_unreadable",
+      severity: options.strict ? "error" : "warning",
+      message: `Could not parse ${consumer.name} workflow job status: ${messageFromError(error)}`,
+      path: `attebury/${consumer.name}`,
+      suggestedFix: "Rerun release status after GitHub CLI output is valid JSON."
+    });
+  }
+  const jobs = Array.isArray(payload.jobs) ? payload.jobs : [];
+  for (const expectedJob of expectedJobs) {
+    const job = jobs.find((candidate) => candidate?.name === expectedJob);
+    if (!job) {
+      diagnostics.push({
+        code: "release_consumer_ci_job_missing",
+        severity: options.strict ? "error" : "warning",
+        message: `${consumer.name} workflow is missing expected job '${expectedJob}'.`,
+        path: `attebury/${consumer.name}`,
+        suggestedFix: "Update the consumer workflow or the release-status expected job list, then rerun release status."
+      });
+      continue;
+    }
+    if (job.status !== "completed" || job.conclusion !== "success") {
+      diagnostics.push({
+        code: "release_consumer_ci_job_not_successful",
+        severity: options.strict ? "error" : "warning",
+        message: `${consumer.name} job '${expectedJob}' is ${job.status || "unknown"}/${job.conclusion || "unknown"}.`,
+        path: job.url || `attebury/${consumer.name}`,
+        suggestedFix: "Wait for or fix the expected workflow job, then rerun release status."
+      });
+    }
+  }
+  return { jobs, diagnostics };
+}
+
 /**
  * @param {string} cwd
  * @returns {Array<{ name: string, root: string|null, path: string, version: string|null, found: boolean }>}
@@ -8482,12 +8612,18 @@ if (args[0] === "version" || args[0] === "--version") {
 } else if (args[0] === "generator") {
   printGeneratorHelp();
   process.exit(args[1] ? 1 : 0);
+} else if (args[0] === "emit") {
+  if (!args[1] || args[1].startsWith("-")) {
+    printEmitHelp();
+    process.exit(1);
+  }
+  commandArgs = { generateTarget: args[1], inputPath: commandPath(2), emitArtifact: true };
 } else if (args[0] === "validate") {
   commandArgs = { validate: true, inputPath: args[1] };
 } else if (args[0] === "generate" && args[1] === "app") {
   commandArgs = { generateTarget: "app-bundle", write: true, inputPath: commandPath(2), defaultOutDir: "./app" };
 } else if (args[0] === "generate" && args.indexOf("--generate") >= 0) {
-  commandArgs = { inputPath: commandPath(1) };
+  commandArgs = { inputPath: commandPath(1), deprecatedGenerateArtifact: true };
 } else if (args[0] === "generate" && args[1] !== "journeys") {
   commandArgs = { generateTarget: "app-bundle", write: true, inputPath: commandPath(1), defaultOutDir: "./app" };
 } else if (args[0] === "trust" && args[1] === "template") {
@@ -8727,8 +8863,13 @@ const shouldValidate = Boolean(commandArgs?.validate) || args.includes("--valida
 const shouldResolve = args.includes("--resolve");
 const generateIndex = args.indexOf("--generate");
 const generateTarget = commandArgs?.generateTarget || (generateIndex >= 0 ? args[generateIndex + 1] : null);
+if (commandArgs?.deprecatedGenerateArtifact && (!generateTarget || generateTarget.startsWith("-"))) {
+  console.error("Missing required --generate <target>.");
+  printUsage();
+  process.exit(1);
+}
 if (RENAMED_GENERATE_TARGETS.has(generateTarget)) {
-  console.error(`Generator target '${generateTarget}' was renamed to '${RENAMED_GENERATE_TARGETS.get(generateTarget)}'.`);
+  console.error(`Artifact target '${generateTarget}' was renamed to '${RENAMED_GENERATE_TARGETS.get(generateTarget)}'.`);
   process.exit(1);
 }
 const workflowIndex = args.indexOf("--workflow");
@@ -11461,6 +11602,9 @@ try {
   const ast = parsePath(inputPath);
 
   if (generateTarget) {
+    if (commandArgs?.deprecatedGenerateArtifact) {
+      console.error(`Deprecated: use \`topogram emit ${generateTarget} ${inputPath || "./topogram"}\` instead of \`topogram generate ${inputPath || "./topogram"} --generate ${generateTarget}\`.`);
+    }
     const projectRoot = normalizeProjectRoot(inputPath);
     const explicitProjectConfig = loadProjectConfig(projectRoot) || loadProjectConfig(inputPath);
     const implementationOptionalTargets = new Set(["app-bundle-plan", "app-bundle", "environment-plan", "environment-bundle", "compile-check-plan", "compile-check-bundle"]);

package/src/generator/surfaces/databases/lifecycle-shared.js

@@ -352,17 +352,17 @@ infer_current_snapshot_from_live_tables() {
 }
 
 generate_desired_snapshot() {
-  "$TOPOGRAM_BIN" "$INPUT_PATH" --generate db-schema-snapshot --projection "$PROJECTION_ID" > "$DESIRED_SNAPSHOT"
+  "$TOPOGRAM_BIN" emit db-schema-snapshot "$INPUT_PATH" --projection "$PROJECTION_ID" > "$DESIRED_SNAPSHOT"
 }
 
 generate_migration_plan() {
   local from_snapshot="$1"
-  "$TOPOGRAM_BIN" "$INPUT_PATH" --generate db-migration-plan --projection "$PROJECTION_ID" --from-snapshot "$from_snapshot" > "$PLAN_JSON"
+  "$TOPOGRAM_BIN" emit db-migration-plan "$INPUT_PATH" --projection "$PROJECTION_ID" --from-snapshot "$from_snapshot" > "$PLAN_JSON"
 }
 
 generate_sql_migration() {
   local from_snapshot="$1"
-  "$TOPOGRAM_BIN" "$INPUT_PATH" --generate sql-migration --projection "$PROJECTION_ID" --from-snapshot "$from_snapshot" > "$MIGRATION_SQL"
+  "$TOPOGRAM_BIN" emit sql-migration "$INPUT_PATH" --projection "$PROJECTION_ID" --from-snapshot "$from_snapshot" > "$MIGRATION_SQL"
 }
 
 ensure_supported_plan() {

package/src/generator/surfaces/native/swiftui-templates/README.generated.md

@@ -22,5 +22,5 @@ Configure the API base URL and optional auth token via scheme environment variab
 From `engine/`:
 
 ```bash
-topogram ./topogram --generate swiftui-app --projection proj_ios_surface__swiftui --write --out-dir ./app/ios-swiftui
+topogram emit swiftui-app ./topogram --projection proj_ios_surface__swiftui --write --out-dir ./app/ios-swiftui
 ```

package/src/new-project.js

@@ -2046,6 +2046,8 @@ Or run self-contained local runtime verification:
 
 Useful inspection:
    npm run check:json
+   topogram emit ui-widget-contract ./topogram --json
+   topogram emit widget-conformance-report ./topogram --json
    npm run doctor
    npm run source:status
    npm run source:status:remote
@@ -2123,6 +2125,7 @@ ${workflowCommands.join("\n")}
 
 Edit \`topogram/\` and \`topogram.project.json\`, then regenerate with \`npm run generate\`.
 Generated app code is written to \`app/\`.
+Use \`topogram emit <target>\` to inspect contracts, reports, snapshots, and other artifacts without regenerating the app.
 ${template.includesExecutableImplementation ? "\nThis template copied `implementation/` code. `topogram new` did not execute it; review `implementation/`, `topogram.template-policy.json`, and `.topogram-template-trust.json` before regenerating after edits.\n" : ""}
 `;
   fs.writeFileSync(path.join(projectRoot, "README.md"), readme, "utf8");