@topogram/cli 0.3.73 → 0.3.75

package/package.json

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

package/src/agent-brief.js

@@ -31,7 +31,8 @@ import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot, resolveWorkspaceContext } fr
  * @typedef {{ command: string, reason: string, phase: string }} AgentBriefCommand
  * @typedef {{ path: string, ownership: string, rule: string }} AgentBriefOutputBoundary
  * @typedef {{ id: string, title: string, commands: string[], rule: string }} AgentBriefWorkflow
- * @typedef {{ id: string, kind: string, projection: string|null, generator: string|null, uses_api: string|null, uses_database: string|null }} AgentBriefRuntime
+ * @typedef {{ ownership: string|null, tool: string|null, apply: string|null, statePath: string|null, snapshotPath: string|null, schemaPath: string|null, migrationsPath: string|null }} AgentBriefMigration
+ * @typedef {{ id: string, kind: string, projection: string|null, generator: string|null, uses_api: string|null, uses_database: string|null, migration: AgentBriefMigration|null }} AgentBriefRuntime
  * @typedef {{ path: string, workspaceRoot: string, source: string|null, tracks: string[], candidateCounts: Record<string, any>, ownership: string|null }} AgentBriefImport
  * @typedef {{ ok: true, payload: Record<string, any> } | { ok: false, kind: "topogram", validation: any } | { ok: false, kind: "project", validation: any, configPath: string }} AgentBriefResult
  */
@@ -103,7 +104,18 @@ function summarizeRuntimes(config) {
     projection: typeof runtime.projection === "string" ? runtime.projection : null,
     generator: typeof runtime.generator?.id === "string" ? runtime.generator.id : null,
     uses_api: typeof runtime.uses_api === "string" ? runtime.uses_api : null,
-    uses_database: typeof runtime.uses_database === "string" ? runtime.uses_database : null
+    uses_database: typeof runtime.uses_database === "string" ? runtime.uses_database : null,
+    migration: runtime.kind === "database" && runtime.migration
+      ? {
+          ownership: typeof runtime.migration.ownership === "string" ? runtime.migration.ownership : null,
+          tool: typeof runtime.migration.tool === "string" ? runtime.migration.tool : null,
+          apply: typeof runtime.migration.apply === "string" ? runtime.migration.apply : null,
+          statePath: typeof runtime.migration.statePath === "string" ? runtime.migration.statePath : null,
+          snapshotPath: typeof runtime.migration.snapshotPath === "string" ? runtime.migration.snapshotPath : null,
+          schemaPath: typeof runtime.migration.schemaPath === "string" ? runtime.migration.schemaPath : null,
+          migrationsPath: typeof runtime.migration.migrationsPath === "string" ? runtime.migration.migrationsPath : null
+        }
+      : null
   }));
 }
 
@@ -495,7 +507,10 @@ export function formatAgentBrief(brief) {
       runtime.uses_api ? `uses_api=${runtime.uses_api}` : null,
       runtime.uses_database ? `uses_database=${runtime.uses_database}` : null
     ].filter(Boolean).join(", ");
-    lines.push(`  - ${runtime.id}: ${runtime.kind}${runtime.projection ? ` -> ${runtime.projection}` : ""}${runtime.generator ? ` via ${runtime.generator}` : ""}${edges ? ` (${edges})` : ""}`);
+    const migration = runtime.migration
+      ? ` migration=${runtime.migration.ownership}/${runtime.migration.tool} apply=${runtime.migration.apply}`
+      : "";
+    lines.push(`  - ${runtime.id}: ${runtime.kind}${runtime.projection ? ` -> ${runtime.projection}` : ""}${runtime.generator ? ` via ${runtime.generator}` : ""}${edges ? ` (${edges})` : ""}${migration}`);
   }
   if ((brief.topology?.runtimes || []).length === 0) {
     lines.push("  - No topology runtimes configured.");

package/src/cli/commands/check.js

@@ -80,6 +80,17 @@ function summarizeProjectTopology(config) {
         version: component.generator?.version || null
       },
       port: topologyComponentPort(component),
+      migration: component.kind === "database" && component.migration
+        ? {
+            ownership: component.migration.ownership || null,
+            tool: component.migration.tool || null,
+            apply: component.migration.apply || null,
+            statePath: component.migration.statePath || null,
+            snapshotPath: component.migration.snapshotPath || null,
+            schemaPath: component.migration.schemaPath || null,
+            migrationsPath: component.migration.migrationsPath || null
+          }
+        : null,
       references: topologyComponentReferences(component)
     }))
     .sort((left, right) => left.id.localeCompare(right.id));
@@ -136,7 +147,10 @@ function formatTopologyComponent(component) {
     .filter(([, value]) => Boolean(value))
     .map(([key, value]) => `${key} ${value}`);
   const suffix = refs.length ? ` -> ${refs.join(", ")}` : "";
-  return `  - ${component.id}: ${component.kind} ${component.projection} via ${generator} (${port})${suffix}`;
+  const migration = component.migration
+    ? ` [migration ${component.migration.ownership}/${component.migration.tool}, apply=${component.migration.apply}]`
+    : "";
+  return `  - ${component.id}: ${component.kind} ${component.projection} via ${generator} (${port})${suffix}${migration}`;
 }
 
 /**

package/src/cli/commands/release-rollout.js

@@ -16,6 +16,7 @@ import {
   expectedConsumerWorkflowName,
   hasStagedGitChanges,
   inspectConsumerCi,
+  inspectGitUpstreamAhead,
   inspectGitWorktreeClean,
   messageFromError,
   runGit,
@@ -24,12 +25,101 @@ import {
 
 /**
  * @typedef {Record<string, any>} AnyRecord
+ * @typedef {{ consumer?: string, step: string, status: "start"|"ok"|"skip"|"waiting"|"error", message: string, elapsedMs?: number, [key: string]: any }} ReleaseRollProgress
  */
 
+/**
+ * @param {{ onProgress?: ((event: ReleaseRollProgress) => void)|null, captureProgress?: boolean }} options
+ * @param {ReleaseRollProgress} event
+ * @returns {void}
+ */
+function notifyProgress(options, event) {
+  if (typeof options.onProgress === "function") {
+    options.onProgress(event);
+  }
+}
+
+/**
+ * @param {AnyRecord} item
+ * @param {{ onProgress?: ((event: ReleaseRollProgress) => void)|null, captureProgress?: boolean }} options
+ * @param {ReleaseRollProgress["step"]} step
+ * @param {ReleaseRollProgress["status"]} status
+ * @param {string} message
+ * @param {AnyRecord} [detail]
+ * @returns {ReleaseRollProgress}
+ */
+function recordProgress(item, options, step, status, message, detail = {}) {
+  /** @type {ReleaseRollProgress} */
+  const event = {
+    consumer: item.name,
+    step,
+    status,
+    message
+  };
+  if (typeof detail.elapsedMs === "number") {
+    event.elapsedMs = detail.elapsedMs;
+  }
+  if (typeof detail.headSha === "string") {
+    event.headSha = detail.headSha;
+  }
+  if (typeof detail.expectedWorkflow === "string") {
+    event.expectedWorkflow = detail.expectedWorkflow;
+  }
+  if (detail.run && typeof detail.run === "object") {
+    event.run = {
+      workflowName: detail.run.workflowName || null,
+      status: detail.run.status || null,
+      conclusion: detail.run.conclusion || null,
+      headSha: detail.run.headSha || null,
+      url: detail.run.url || null
+    };
+  }
+  if (options.captureProgress !== true) {
+    notifyProgress(options, event);
+    return event;
+  }
+  if (!Array.isArray(item.progress)) {
+    item.progress = [];
+  }
+  item.progress.push(event);
+  notifyProgress(options, event);
+  return event;
+}
+
+/**
+ * @param {Array<AnyRecord>} consumers
+ * @param {{ version: string, push: boolean, watch: boolean, noWatch?: boolean }} options
+ * @returns {AnyRecord}
+ */
+function buildRecoverySummary(consumers, options) {
+  /**
+   * @param {(consumer: AnyRecord) => boolean} predicate
+   * @returns {string[]}
+   */
+  const namesFor = (predicate) => consumers.filter(predicate).map((consumer) => String(consumer.name));
+  return {
+    version: options.version,
+    alreadyCurrent: namesFor((consumer) => consumer.alreadyCurrent === true),
+    alreadyPushed: namesFor((consumer) => consumer.alreadyPushed === true),
+    updated: namesFor((consumer) => consumer.updated === true),
+    committed: namesFor((consumer) => consumer.committed === true),
+    pushed: namesFor((consumer) => consumer.pushed === true),
+    recoveredPushes: namesFor((consumer) => consumer.recoveredPush === true),
+    needsAttention: namesFor((consumer) => (
+      /** @type {Array<AnyRecord>} */ (consumer.diagnostics || [])
+    ).some((diagnostic) => diagnostic.severity === "error")),
+    resumeCommand: `topogram release roll-consumers ${options.version}${options.push ? "" : " --no-push"}${options.watch ? " --watch" : options.noWatch ? " --no-watch" : ""}`,
+    asyncVerificationCommand: "topogram release status --strict",
+    watchGuidance: options.watch
+      ? "If CI waiting is too slow or interrupted, rerun roll-consumers with --no-watch, then verify with release status --strict."
+      : "This rollout did not wait for CI. Verify consumers after workflows finish with release status --strict."
+  };
+}
+
 /**
  * @param {string} requested
- * @param {{ cwd?: string, push?: boolean, watch?: boolean }} [options]
- * @returns {{ ok: boolean, packageName: string, requestedVersion: string, requestedLatest: boolean, pushed: boolean, watched: boolean, consumers: Array<AnyRecord>, diagnostics: Array<AnyRecord>, errors: string[] }}
+ * @param {{ cwd?: string, push?: boolean, watch?: boolean, noWatch?: boolean, onProgress?: ((event: ReleaseRollProgress) => void)|null, captureProgress?: boolean }} [options]
+ * @returns {{ ok: boolean, packageName: string, requestedVersion: string, requestedLatest: boolean, pushed: boolean, watched: boolean, consumers: Array<AnyRecord>, diagnostics: Array<AnyRecord>, errors: string[], recovery: AnyRecord|null }}
  */
 export function buildReleaseRollConsumersPayload(requested, options = {}) {
   const cwd = options.cwd || process.cwd();
@@ -44,7 +134,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
       severity: "error",
       message: "`topogram release roll-consumers --watch` requires pushing consumer commits.",
       path: "release roll-consumers",
-      suggestedFix: "Remove --no-push or run without --watch and verify consumer CI separately."
+      suggestedFix: "Remove --no-push or use --no-watch and verify consumer CI separately."
     });
     return {
       ok: false,
@@ -55,7 +145,8 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
       watched: watch,
       consumers: [],
       diagnostics,
-      errors: diagnostics.map((diagnostic) => diagnostic.message)
+      errors: diagnostics.map((diagnostic) => diagnostic.message),
+      recovery: null
     };
   }
   const version = requestedLatest
@@ -79,9 +170,14 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
       commit: null,
       update: null,
       ci: null,
+      alreadyCurrent: false,
+      alreadyPushed: false,
+      recoveredPush: false,
+      upstreamAhead: null,
       diagnostics: []
     };
     consumers.push(item);
+    recordProgress(item, options, "inspect", "start", `${consumer.name}: inspecting repository and package metadata.`);
     if (!consumer.root || !fs.existsSync(consumer.root)) {
       item.diagnostics.push({
         code: "release_consumer_repo_missing",
@@ -91,6 +187,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: `Clone ${consumer.name} beside the topogram repo, then rerun roll-consumers.`
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "inspect", "error", `${consumer.name}: repository not found.`);
       continue;
     }
     const packagePath = path.join(consumer.root, "package.json");
@@ -103,6 +200,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: "Only package-backed first-party consumers can be rolled by this command."
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "inspect", "error", `${consumer.name}: package.json missing.`);
       continue;
     }
     const clean = inspectGitWorktreeClean(consumer.root);
@@ -115,11 +213,15 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: "Commit, stash, or discard unrelated consumer changes before rolling the CLI version."
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "inspect", "error", `${consumer.name}: worktree is dirty.`);
       continue;
     }
+    recordProgress(item, options, "inspect", "ok", `${consumer.name}: worktree is clean.`);
     try {
+      recordProgress(item, options, "update", "start", `${consumer.name}: updating ${CLI_PACKAGE_NAME} to ${version} and running package checks.`);
       item.update = buildPackageUpdateCliPayload(version, { cwd: consumer.root });
       item.updated = true;
+      recordProgress(item, options, "update", "ok", `${consumer.name}: package update/check completed.`);
     } catch (error) {
       item.diagnostics.push({
         code: "release_consumer_update_failed",
@@ -129,10 +231,12 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: "Fix the consumer update/check failure, then rerun roll-consumers."
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "update", "error", `${consumer.name}: package update/check failed.`);
       continue;
     }
     const filesToStage = ["package.json", "package-lock.json", "topogram-cli.version"]
       .filter((file) => fs.existsSync(path.join(consumer.root || "", file)));
+    recordProgress(item, options, "stage", "start", `${consumer.name}: staging package pin changes.`);
     const addResult = runGit(["add", ...filesToStage], consumer.root);
     if (addResult.status !== 0) {
       item.diagnostics.push(commandDiagnostic({
@@ -144,6 +248,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         result: addResult
       }));
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "stage", "error", `${consumer.name}: staging failed.`);
       continue;
     }
     const staged = hasStagedGitChanges(consumer.root);
@@ -157,16 +262,63 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         result: staged.result
       }));
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "stage", "error", `${consumer.name}: could not inspect staged changes.`);
       continue;
     }
     if (!staged.changed) {
+      item.alreadyCurrent = true;
+      item.commit = currentGitHead(consumer.root);
+      recordProgress(item, options, "stage", "skip", `${consumer.name}: already pinned to ${CLI_PACKAGE_NAME}@${version}; no commit needed.`);
+      if (push) {
+        const ahead = inspectGitUpstreamAhead(consumer.root);
+        item.upstreamAhead = ahead.ok ? ahead.ahead : null;
+        if (!ahead.ok) {
+          item.diagnostics.push(commandDiagnostic({
+            code: "release_consumer_git_upstream_unavailable",
+            severity: "warning",
+            message: `Could not inspect whether ${consumer.name} has unpushed commits.`,
+            path: consumer.root,
+            suggestedFix: "Inspect git status manually; if the consumer branch is ahead, push it before verifying CI.",
+            result: ahead.result
+          }));
+          diagnostics.push(...item.diagnostics.slice(-1));
+        } else if ((ahead.ahead || 0) > 0) {
+          recordProgress(item, options, "push", "start", `${consumer.name}: branch is ahead of upstream; pushing existing rollout commit.`);
+          const pushResult = runGit(["push", "origin", "main"], consumer.root);
+          if (pushResult.status !== 0) {
+            item.diagnostics.push(commandDiagnostic({
+              code: "release_consumer_git_push_failed",
+              severity: "error",
+              message: `Failed to push ${consumer.name} existing CLI update.`,
+              path: consumer.root,
+              suggestedFix: "Push the consumer update manually, then confirm its verification workflow passes.",
+              result: pushResult
+            }));
+            diagnostics.push(...item.diagnostics);
+            recordProgress(item, options, "push", "error", `${consumer.name}: push failed.`);
+            continue;
+          }
+          item.pushed = true;
+          item.recoveredPush = true;
+          recordProgress(item, options, "push", "ok", `${consumer.name}: pushed existing rollout commit.`);
+        } else {
+          item.alreadyPushed = true;
+          recordProgress(item, options, "push", "skip", `${consumer.name}: branch already matches upstream.`);
+        }
+      }
+      recordProgress(item, options, watch ? "watch-ci" : "check-ci", "start", `${consumer.name}: ${watch ? "watching" : "checking"} verification workflow.`);
       item.ci = watch
-        ? waitForConsumerCi(consumer)
+        ? waitForConsumerCi(consumer, {
+            onProgress: (event) => recordProgress(item, options, "watch-ci", event.status === "ok" ? "ok" : event.status === "error" ? "error" : "waiting", event.message, event)
+          })
         : inspectConsumerCi(consumer, { strict: false });
       item.diagnostics.push(...item.ci.diagnostics);
       diagnostics.push(...item.ci.diagnostics);
+      recordProgress(item, options, watch ? "watch-ci" : "check-ci", item.ci.ok === false ? "error" : "ok", `${consumer.name}: verification ${item.ci.ok === false ? "reported issues" : "checked"}.`);
       continue;
     }
+    recordProgress(item, options, "stage", "ok", `${consumer.name}: staged CLI pin changes.`);
+    recordProgress(item, options, "commit", "start", `${consumer.name}: committing CLI rollout.`);
     const commitResult = runGit(["commit", "-m", `Update Topogram CLI to ${version}`], consumer.root);
     if (commitResult.status !== 0) {
       item.diagnostics.push(commandDiagnostic({
@@ -178,11 +330,14 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         result: commitResult
       }));
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "commit", "error", `${consumer.name}: commit failed.`);
       continue;
     }
     item.committed = true;
     item.commit = currentGitHead(consumer.root);
+    recordProgress(item, options, "commit", "ok", `${consumer.name}: committed ${item.commit || "CLI rollout"}.`);
     if (push) {
+      recordProgress(item, options, "push", "start", `${consumer.name}: pushing rollout commit.`);
       const pushResult = runGit(["push", "origin", "main"], consumer.root);
       if (pushResult.status !== 0) {
         item.diagnostics.push(commandDiagnostic({
@@ -194,15 +349,21 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
           result: pushResult
         }));
         diagnostics.push(...item.diagnostics);
+        recordProgress(item, options, "push", "error", `${consumer.name}: push failed.`);
         continue;
       }
       item.pushed = true;
+      recordProgress(item, options, "push", "ok", `${consumer.name}: pushed rollout commit.`);
     }
+    recordProgress(item, options, watch ? "watch-ci" : "check-ci", "start", `${consumer.name}: ${watch ? "watching" : "checking"} verification workflow.`);
     item.ci = watch
-      ? waitForConsumerCi(consumer)
+      ? waitForConsumerCi(consumer, {
+          onProgress: (event) => recordProgress(item, options, "watch-ci", event.status === "ok" ? "ok" : event.status === "error" ? "error" : "waiting", event.message, event)
+        })
       : inspectConsumerCi(consumer, { strict: false });
     item.diagnostics.push(...item.ci.diagnostics);
     diagnostics.push(...item.ci.diagnostics);
+    recordProgress(item, options, watch ? "watch-ci" : "check-ci", item.ci.ok === false ? "error" : "ok", `${consumer.name}: verification ${item.ci.ok === false ? "reported issues" : "checked"}.`);
   }
   const errors = diagnostics
     .filter((diagnostic) => diagnostic.severity === "error")
@@ -216,10 +377,19 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
     watched: watch,
     consumers,
     diagnostics,
-    errors
+    errors,
+    recovery: buildRecoverySummary(consumers, { version, push, watch, noWatch: options.noWatch === true })
   };
 }
 
+/**
+ * @param {ReleaseRollProgress} event
+ * @returns {void}
+ */
+export function printReleaseRollProgress(event) {
+  console.error(`[roll-consumers] ${event.message}`);
+}
+
 /**
  * @param {ReturnType<typeof buildReleaseRollConsumersPayload>} payload
  * @returns {void}
@@ -233,9 +403,11 @@ export function printReleaseRollConsumers(payload) {
   console.log(`Push: ${payload.pushed ? "enabled" : "disabled"}`);
   console.log(`Watch: ${payload.watched ? "enabled" : "disabled"}`);
   for (const consumer of payload.consumers) {
-    const state = consumer.committed
-      ? consumer.pushed ? "pushed" : "committed"
-      : consumer.updated ? "updated" : "skipped";
+    const state = consumer.alreadyCurrent
+      ? consumer.pushed ? "pushed existing commit" : consumer.alreadyPushed ? "current" : "current"
+      : consumer.committed
+        ? consumer.pushed ? "pushed" : "committed"
+        : consumer.updated ? "updated" : "skipped";
     console.log(`- ${consumer.name}: ${state}`);
     if (consumer.update) {
       console.log(`  Checks run: ${consumer.update.scriptsRun.join(", ") || "none"}`);
@@ -254,4 +426,13 @@ export function printReleaseRollConsumers(payload) {
       console.log(`  ${label}: ${diagnostic.message}`);
     }
   }
+  if (payload.recovery) {
+    console.log("Recovery:");
+    console.log(`  Resume: ${payload.recovery.resumeCommand}`);
+    console.log(`  Verify: ${payload.recovery.asyncVerificationCommand}`);
+    if ((payload.recovery.needsAttention || []).length > 0) {
+      console.log(`  Needs attention: ${payload.recovery.needsAttention.join(", ")}`);
+    }
+    console.log(`  ${payload.recovery.watchGuidance}`);
+  }
 }

package/src/cli/commands/release-shared.js

@@ -19,6 +19,7 @@ const REPO_ROOT = decodeURIComponent(new URL("../../../../", import.meta.url).pa
 
 /**
  * @typedef {Record<string, any>} AnyRecord
+ * @typedef {{ consumer?: string, step?: string, status?: string, message: string, elapsedMs?: number, headSha?: string|null, expectedWorkflow?: string|null, run?: AnyRecord|null }} ReleaseProgressEvent
  */
 
 /**
@@ -157,6 +158,23 @@ export function currentGitHead(cwd) {
   return result.status === 0 ? String(result.stdout || "").trim() || null : null;
 }
 
+/**
+ * @param {string} cwd
+ * @returns {{ ok: boolean, ahead: number|null, result: ReturnType<typeof childProcess.spawnSync> }}
+ */
+export function inspectGitUpstreamAhead(cwd) {
+  const result = runGit(["rev-list", "--count", "@{u}..HEAD"], cwd);
+  if (result.status !== 0) {
+    return { ok: false, ahead: null, result };
+  }
+  const ahead = Number.parseInt(String(result.stdout || "").trim(), 10);
+  return {
+    ok: Number.isFinite(ahead),
+    ahead: Number.isFinite(ahead) ? ahead : null,
+    result
+  };
+}
+
 /**
  * @param {{ code: string, severity: "error"|"warning", message: string, path: string|null, suggestedFix: string, result: ReturnType<typeof childProcess.spawnSync> }} input
  * @returns {{ code: string, severity: "error"|"warning", message: string, path: string|null, suggestedFix: string }}
@@ -205,7 +223,7 @@ function positiveIntegerEnv(name, fallback) {
 
 /**
  * @param {{ name: string, root?: string|null, workflow?: string|null }} consumer
- * @param {{ timeoutMs?: number, intervalMs?: number }} [options]
+ * @param {{ timeoutMs?: number, intervalMs?: number, onProgress?: ((event: ReleaseProgressEvent) => void)|null }} [options]
  * @returns {ReturnType<typeof inspectConsumerCi>}
  */
 export function waitForConsumerCi(consumer, options = {}) {
@@ -213,12 +231,23 @@ export function waitForConsumerCi(consumer, options = {}) {
   const intervalMs = options.intervalMs || positiveIntegerEnv("TOPOGRAM_RELEASE_WATCH_INTERVAL_MS", 5000);
   const startedAt = Date.now();
   let latest = inspectConsumerCi(consumer, { strict: false });
+  const notify = typeof options.onProgress === "function" ? options.onProgress : null;
   while (true) {
     const currentRun = latest.run &&
       latest.headSha &&
       latest.run?.headSha &&
       latest.run.headSha === latest.headSha;
     if (currentRun && latest.run?.status === "completed") {
+      notify?.({
+        consumer: consumer.name,
+        step: "watch-ci",
+        status: "ok",
+        message: `${consumer.name}: verification workflow completed on current commit.`,
+        elapsedMs: Date.now() - startedAt,
+        headSha: latest.headSha,
+        expectedWorkflow: latest.expectedWorkflow,
+        run: latest.run
+      });
       return inspectConsumerCi(consumer, { strict: true });
     }
     if (Date.now() - startedAt >= timeoutMs) {
@@ -228,11 +257,31 @@ export function waitForConsumerCi(consumer, options = {}) {
         severity: "error",
         message: `${consumer.name} verification workflow did not complete on the current commit before the watch timeout.`,
         path: strictLatest.run?.url || consumerGithubRepoSlug(consumer),
-        suggestedFix: "Open the consumer workflow, fix failures if needed, then rerun release status."
+        suggestedFix: "Open the consumer workflow, fix failures if needed, then rerun release status. If you only need to push and verify later, rerun roll-consumers with --no-watch."
       });
       strictLatest.ok = false;
+      notify?.({
+        consumer: consumer.name,
+        step: "watch-ci",
+        status: "error",
+        message: `${consumer.name}: verification watch timed out; rerun with --no-watch to continue asynchronously.`,
+        elapsedMs: Date.now() - startedAt,
+        headSha: strictLatest.headSha,
+        expectedWorkflow: strictLatest.expectedWorkflow,
+        run: strictLatest.run
+      });
       return strictLatest;
     }
+    notify?.({
+      consumer: consumer.name,
+      step: "watch-ci",
+      status: "waiting",
+      message: `${consumer.name}: waiting for ${latest.expectedWorkflow || "verification workflow"} on ${latest.headSha || "HEAD"} (${Math.round((Date.now() - startedAt) / 1000)}s elapsed).`,
+      elapsedMs: Date.now() - startedAt,
+      headSha: latest.headSha,
+      expectedWorkflow: latest.expectedWorkflow,
+      run: latest.run
+    });
     sleepSync(intervalMs);
     latest = inspectConsumerCi(consumer, { strict: false });
   }

package/src/cli/commands/release.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { stableStringify } from "../../format.js";
 import {
   buildReleaseRollConsumersPayload,
+  printReleaseRollProgress,
   printReleaseRollConsumers
 } from "./release-rollout.js";
 import {
@@ -19,10 +20,11 @@ import {
  */
 export function printReleaseHelp() {
   console.log("Usage: topogram release status [--json] [--strict] [--markdown|--write-report <path>]");
-  console.log("   or: topogram release roll-consumers <version|--latest> [--json] [--no-push] [--watch]");
+  console.log("   or: topogram release roll-consumers <version|--latest> [--json] [--no-push] [--watch|--no-watch]");
   console.log("");
   console.log("Checks the local CLI version, latest published package version, release tag, first-party consumer pins, and strict consumer CI state.");
   console.log("Rolls first-party consumers to a published CLI version, runs their checks, commits, pushes, and can wait for current workflow runs.");
+  console.log("Rollout progress prints to stderr in human mode; JSON output stays final-only. Use --no-watch to push and verify later with release status --strict.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram release status");
@@ -88,13 +90,24 @@ export function runReleaseCommand(context) {
 
   if (command === "roll-consumers") {
     const push = !args.includes("--no-push");
+    const noWatch = args.includes("--no-watch");
     const watch = args.includes("--watch");
+    if (watch && noWatch) {
+      console.error("Use either --watch or --no-watch, not both.");
+      printReleaseHelp();
+      return 1;
+    }
     if (watch && !push) {
-      console.error("Use either --watch or --no-push, not both.");
+      console.error("Use either --watch or --no-push, not both. Use --no-watch with --no-push when CI will be verified separately.");
       printReleaseHelp();
       return 1;
     }
-    const payload = buildReleaseRollConsumersPayload(commandArgs.releaseRollVersion, { push, watch });
+    const payload = buildReleaseRollConsumersPayload(commandArgs.releaseRollVersion, {
+      push,
+      watch,
+      noWatch,
+      onProgress: json ? null : printReleaseRollProgress
+    });
     if (json) {
       console.log(stableStringify(payload));
     } else {

package/src/cli/help.js

@@ -11,7 +11,7 @@ export function printUsage(options = {}) {
   console.log("   or: topogram doctor --allow-local-npmrc");
   console.log("Usage: topogram setup package-auth|catalog-auth");
   console.log("Usage: topogram release status [--json] [--strict] [--markdown|--write-report <path>]");
-  console.log("   or: topogram release roll-consumers <version|--latest> [--json] [--no-push] [--watch]");
+  console.log("   or: topogram release roll-consumers <version|--latest> [--json] [--no-push] [--watch|--no-watch]");
   console.log("Usage: topogram check [path] [--json]");
   console.log("   or: topogram widget check [path] [--projection <id>] [--widget <id>] [--json]");
   console.log("   or: topogram widget behavior [path] [--projection <id>] [--widget <id>] [--json]");

package/src/generator/adapters.js

@@ -177,7 +177,7 @@ function buildContractsForContext(context) {
   if (surface === "database") {
     return {
       db: generateDbContractGraph(context.graph, { ...(context.options || {}), projectionId }),
-      lifecyclePlan: generateDbLifecyclePlan(context.graph, { ...(context.options || {}), projectionId })
+      lifecyclePlan: generateDbLifecyclePlan(context.graph, { ...(context.options || {}), projectionId, runtime, component: runtime, topology: context.topology })
     };
   }
   if (surface === "native" || surface === "ios_surface" || surface === "android_surface") {

package/src/generator/runtime/app-bundle.js

@@ -48,7 +48,7 @@ function buildAppBundlePlan(graph, options = {}) {
   const runtimeReference = runtimeReferenceFor(graph, options);
   const topology = resolveRuntimeTopology(graph, options);
   const { apiProjection, uiProjection, dbProjection } = getDefaultEnvironmentProjections(graph, options);
-  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id }) : null;
+  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id, runtime: topology.primaryDb || undefined }) : null;
   const environmentProfile = options.profileId || "local_process";
   const deployProfile = options.deployProfileId || "fly_io";
   const smokeVerification = buildVerificationSummary(graph, ["smoke", "journey"]);
@@ -77,7 +77,8 @@ function buildAppBundlePlan(graph, options = {}) {
         generator: runtime.generator,
         port: runtime.port ?? null,
         uses_api: runtime.api || null,
-        uses_database: runtime.database || null
+        uses_database: runtime.database || null,
+        ...(runtime.kind === "database" && runtime.migration ? { migration: runtime.migration } : {})
       }))
     },
     runtimeReference,