@topogram/cli 0.3.55 → 0.3.56

package/CHANGELOG.md

@@ -5,6 +5,24 @@
 - Install package-backed generator dependencies during `topogram template check`
   before starter validation.
 
+## 0.3.55 - 2026-05-07
+
+- Complete the public DSL cleanup from `component` to `widget`: normalized
+  graph/context output now uses `widget`, `widgetBindings`, `widgetContract`,
+  and widget report target names without publishing component compatibility
+  aliases.
+- Reconcile/adoption import reports now emit `widgets` in candidate model
+  bundles, evidence, summaries, and promoted item plans. Existing imported
+  workspaces with `candidates.ui.components` are still accepted as a read-only
+  fallback, but new import output writes `candidates.ui.widgets`.
+- Old CLI names fail with explicit rename guidance instead of silently running:
+  `topogram component`, `--component`, `ui-component-contract`,
+  `component-conformance-report`, and `component-behavior-report`.
+- Generator policy diagnostics now describe topology entries as runtimes
+  (`runtimeId`) instead of components.
+- Tighten boundary tests so old public DSL vocabulary is allowed only in
+  migration guidance and explicit rename diagnostics.
+
 ## 0.3.16 - 2026-05-03
 
 - Install package-backed generator dependencies during `topogram template check`

package/package.json

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

package/src/generator/adapters.js

@@ -41,7 +41,7 @@ import { generateVanillaWebApp } from "./surfaces/web/vanilla.js";
  * @property {Record<string, any>} graph
  * @property {Record<string, any>} projection
  * @property {Record<string, any>} runtime
- * @property {Record<string, any>} component Internal runtime alias.
+ * @property {Record<string, any>} [component] Legacy runtime alias for existing generator packages.
  * @property {Record<string, any>|null} [topology]
  * @property {Record<string, any>} [contracts]
  * @property {Record<string, any>|null} [implementation]
@@ -88,7 +88,23 @@ function requiredManifest(generatorId) {
  * @returns {string}
  */
 function runtimeFor(context) {
-  return context.runtime || context.component || {};
+  return normalizeRuntimeForGenerator(context.runtime || context.component || {});
+}
+
+/**
+ * Keep package-backed generator context canonical while preserving aliases for already-published adapters.
+ *
+ * @param {Record<string, any>} runtime
+ * @returns {Record<string, any>}
+ */
+function normalizeRuntimeForGenerator(runtime) {
+  const apiRuntime = runtime.apiRuntime || runtime.apiComponent || null;
+  const databaseRuntime = runtime.databaseRuntime || runtime.databaseComponent || null;
+  return {
+    ...runtime,
+    ...(apiRuntime ? { apiRuntime, apiComponent: apiRuntime } : {}),
+    ...(databaseRuntime ? { databaseRuntime, databaseComponent: databaseRuntime } : {})
+  };
 }
 
 /**
@@ -108,7 +124,7 @@ function projectionIdFor(context) {
 function serverOptions(context, profile) {
   const projectionId = projectionIdFor(context);
   const runtime = runtimeFor(context);
-  const dbProjectionId = runtime.databaseComponent?.projection?.id || context.options?.dbProjectionId;
+  const dbProjectionId = runtime.databaseRuntime?.projection?.id || runtime.databaseComponent?.projection?.id || context.options?.dbProjectionId;
   return {
     ...(context.options || {}),
     projectionId,
@@ -178,7 +194,7 @@ export const BUNDLED_GENERATOR_ADAPTERS = [
     manifest: requiredManifest("topogram/hono"),
     generate(context) {
       const runtime = runtimeFor(context);
-      if (runtime && !runtime.databaseComponent) {
+      if (runtime && !runtime.databaseRuntime) {
         return fileResult(generateStatelessServer(context.graph, serverOptions(context, "hono")));
       }
       return fileResult(generateHonoServer(context.graph, serverOptions(context, "hono")));
@@ -188,7 +204,7 @@ export const BUNDLED_GENERATOR_ADAPTERS = [
     manifest: requiredManifest("topogram/express"),
     generate(context) {
       const runtime = runtimeFor(context);
-      if (runtime && !runtime.databaseComponent) {
+      if (runtime && !runtime.databaseRuntime) {
         return fileResult(generateStatelessServer(context.graph, serverOptions(context, "express")));
       }
       return fileResult(generateExpressServer(context.graph, serverOptions(context, "express")));

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

@@ -413,7 +413,7 @@ function noopBundle(name, message) {
 export function generateAppBundle(graph, options = {}) {
   const plan = buildAppBundlePlan(graph, options);
   const topology = resolveRuntimeTopology(graph, options);
-  const fullStack = topology.apiComponents.length > 0 && topology.webComponents.length > 0 && topology.dbComponents.length > 0;
+  const fullStack = topology.apiRuntimes.length > 0 && topology.webRuntimes.length > 0 && topology.dbRuntimes.length > 0;
   const envBundle = generateEnvironmentBundle(graph, { ...options, profileId: plan.profiles.environment });
   const deployBundle = fullStack
     ? generateDeploymentBundle(graph, { ...options, profileId: plan.profiles.deployment })

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

@@ -29,13 +29,13 @@ function runtimeReferenceFor(graph, options = {}) {
 function buildCompileCheckPlan(graph, options = {}) {
   const topology = resolveRuntimeTopology(graph, options);
   const { apiProjection, uiProjection, dbProjection } = getDefaultEnvironmentProjections(graph, options);
-  const apiChecks = topology.apiComponents.map((component, index) => ({
+  const apiChecks = topology.apiRuntimes.map((component, index) => ({
     id: index === 0 ? "server_typecheck" : `server_typecheck_${component.id}`,
     cwd: topology.serviceDir(component),
     install: "npm install --no-audit --no-fund",
     command: "npm run check"
   }));
-  const webChecks = topology.webComponents.flatMap((component, index) => [
+  const webChecks = topology.webRuntimes.flatMap((component, index) => [
     {
       id: index === 0 ? "web_typecheck" : `web_typecheck_${component.id}`,
       cwd: topology.webDir(component),
@@ -150,11 +150,11 @@ export function generateCompileCheckBundle(graph, options = {}) {
     "compile-check-plan.json": `${JSON.stringify(plan, null, 2)}\n`,
     "scripts/check.sh": renderCompileCheckScript(plan)
   };
-  for (const component of topology.apiComponents) {
+  for (const component of topology.apiRuntimes) {
     const serverBundle = generateServerBundle(graph, component.projection.id, { ...options, component });
     mergeBundleFiles(files, topology.serviceDir(component), serverBundle);
   }
-  for (const component of topology.webComponents) {
+  for (const component of topology.webRuntimes) {
     const webBundle = generateWebBundle(graph, component.projection.id, { ...options, component });
     mergeBundleFiles(files, topology.webDir(component), webBundle);
   }

package/src/generator/runtime/deployment.js

@@ -262,19 +262,19 @@ export function generateDeploymentBundle(graph, options = {}) {
     files["railway.json"] = renderRailwayJson(plan);
   }
 
-  for (const component of topology.apiComponents) {
+  for (const component of topology.apiRuntimes) {
     const serverBundle = generateServerBundle(graph, component.projection.id, { ...options, component });
     mergeNamedBundles(files, {
       [topology.serviceDir(component)]: serverBundle
     });
   }
-  for (const component of topology.webComponents) {
+  for (const component of topology.webRuntimes) {
     const webBundle = generateWebBundle(graph, component.projection.id, { ...options, component });
     mergeNamedBundles(files, {
       [topology.webDir(component)]: webBundle
     });
   }
-  for (const component of topology.dbComponents) {
+  for (const component of topology.dbRuntimes) {
     const dbBundle = generateDbBundle(graph, component.projection.id, { ...options, component });
     mergeNamedBundles(files, {
       [topology.dbDir(component)]: dbBundle

package/src/generator/runtime/environment.js

@@ -113,24 +113,24 @@ function buildEnvironmentPlan(graph, options = {}) {
       scripts: "scripts"
     },
     runtimes: {
-      apis: topology.apiComponents.map((component) => ({
+      apis: topology.apiRuntimes.map((component) => ({
         id: component.id,
         projection: component.projection.id,
         port: component.port || ports.server,
         dir: topology.serviceDir(component),
         uses_database: component.database,
-        databaseEnv: component.databaseComponent
-          ? dbEnvVarsForComponent(component.databaseComponent, { primary: component.databaseComponent?.id === topology.primaryDb?.id })
+        databaseEnv: component.databaseRuntime
+          ? dbEnvVarsForComponent(component.databaseRuntime, { primary: component.databaseRuntime?.id === topology.primaryDb?.id })
           : null
       })),
-      webs: topology.webComponents.map((component) => ({
+      webs: topology.webRuntimes.map((component) => ({
         id: component.id,
         projection: component.projection.id,
         port: component.port || ports.web,
         dir: topology.webDir(component),
         uses_api: component.api
       })),
-      databases: topology.dbComponents.map((component) => ({
+      databases: topology.dbRuntimes.map((component) => ({
         id: component.id,
         projection: component.projection.id,
         type: component.projection.type,
@@ -330,7 +330,7 @@ function renderEnvironmentLoadEnvScript() {
 function renderEnvironmentBootstrapDbScript(plan) {
   const dbBootstrapLines = plan.runtimes.databases.map((component) => {
     const env = component.env;
-    const runtimeApi = plan.runtimes.apis.find((apiComponent) => apiComponent.uses_database === component.id);
+    const runtimeApi = plan.runtimes.apis.find((apiRuntime) => apiRuntime.uses_database === component.id);
     const assignments = [
       `DATABASE_URL="\${${env.databaseUrl}:-}"`,
       `DATABASE_ADMIN_URL="\${${env.databaseAdminUrl}:-}"`,
@@ -393,12 +393,12 @@ function renderEnvironmentWebDevScript(plan, component = plan.runtimes.webs[0],
   if (!component) {
     return renderEnvAwareShellScript(['echo "No web runtimes are configured."']);
   }
-  const apiComponent = plan.runtimes.apis.find((entry) => entry.id === component.uses_api) || plan.runtimes.apis[0];
+  const apiRuntime = plan.runtimes.apis.find((entry) => entry.id === component.uses_api) || plan.runtimes.apis[0];
   const guardPortsScript = options.componentScript ? '"$ROOT_DIR/scripts/guard-ports.mjs"' : '"$SCRIPT_DIR/guard-ports.mjs"';
   return renderEnvAwareShellScript([
     `node ${guardPortsScript} web`,
     "",
-    ...(apiComponent ? [`export PUBLIC_TOPOGRAM_API_BASE_URL="\${PUBLIC_TOPOGRAM_API_BASE_URL:-http://localhost:\${${apiComponent.id.toUpperCase()}_PORT:-\${SERVER_PORT:-${apiComponent.port}}}}"`] : []),
+    ...(apiRuntime ? [`export PUBLIC_TOPOGRAM_API_BASE_URL="\${PUBLIC_TOPOGRAM_API_BASE_URL:-http://localhost:\${${apiRuntime.id.toUpperCase()}_PORT:-\${SERVER_PORT:-${apiRuntime.port}}}}"`] : []),
     `export TOPOGRAM_CORS_ORIGINS="\${TOPOGRAM_CORS_ORIGINS:-http://localhost:\${${component.id.toUpperCase()}_PORT:-\${WEB_PORT:-${component.port}}},http://127.0.0.1:\${${component.id.toUpperCase()}_PORT:-\${WEB_PORT:-${component.port}}}}"`,
     "",
     `cd "$ROOT_DIR/${component.dir}"`,
@@ -612,19 +612,19 @@ export function generateEnvironmentBundle(graph, options = {}) {
     files["scripts/docker-stack.sh"] = renderEnvironmentDockerStackScript();
   }
 
-  for (const component of topology.apiComponents) {
+  for (const component of topology.apiRuntimes) {
     const serverBundle = generateServerBundle(graph, component.projection.id, { ...options, component });
     mergeNamedBundles(files, {
       [topology.serviceDir(component)]: serverBundle
     });
   }
-  for (const component of topology.webComponents) {
+  for (const component of topology.webRuntimes) {
     const webBundle = generateWebBundle(graph, component.projection.id, { ...options, component });
     mergeNamedBundles(files, {
       [topology.webDir(component)]: webBundle
     });
   }
-  for (const component of topology.dbComponents) {
+  for (const component of topology.dbRuntimes) {
     const dbBundle = generateDbBundle(graph, component.projection.id, { ...options, component });
     mergeNamedBundles(files, {
       [topology.dbDir(component)]: dbBundle

package/src/generator/runtime/shared.js

@@ -27,8 +27,10 @@ import { defaultProjectConfigForGraph, validateProjectConfig } from "../../proje
  * @property {string|null} [api]
  * @property {string|null} [database]
  * @property {Record<string, string>} [env]
- * @property {RuntimeComponent|null} [apiComponent]
- * @property {RuntimeComponent|null} [databaseComponent]
+ * @property {RuntimeComponent|null} [apiRuntime]
+ * @property {RuntimeComponent|null} [databaseRuntime]
+ * @property {RuntimeComponent|null} [apiComponent] Legacy adapter alias for apiRuntime.
+ * @property {RuntimeComponent|null} [databaseComponent] Legacy adapter alias for databaseRuntime.
  */
 
 /**
@@ -39,10 +41,13 @@ import { defaultProjectConfigForGraph, validateProjectConfig } from "../../proje
  * @typedef {Object} RuntimeTopology
  * @property {import("../../project-config.js").ProjectConfig} config
  * @property {RuntimeComponent[]} runtimes
- * @property {RuntimeComponent[]} components
- * @property {RuntimeComponent[]} apiComponents
- * @property {RuntimeComponent[]} webComponents
- * @property {RuntimeComponent[]} dbComponents
+ * @property {RuntimeComponent[]} apiRuntimes
+ * @property {RuntimeComponent[]} webRuntimes
+ * @property {RuntimeComponent[]} dbRuntimes
+ * @property {RuntimeComponent[]} components Legacy alias for runtimes.
+ * @property {RuntimeComponent[]} apiComponents Legacy alias for apiRuntimes.
+ * @property {RuntimeComponent[]} webComponents Legacy alias for webRuntimes.
+ * @property {RuntimeComponent[]} dbComponents Legacy alias for dbRuntimes.
  * @property {RuntimeComponent|null} primaryApi
  * @property {RuntimeComponent|null} primaryWeb
  * @property {RuntimeComponent|null} primaryDb
@@ -65,7 +70,8 @@ import { defaultProjectConfigForGraph, validateProjectConfig } from "../../proje
  * @property {string} [dbProjectionId]
  * @property {string} [configDir]
  * @property {string} [projectRoot]
- * @property {RuntimeComponent} [component]
+ * @property {RuntimeComponent} [runtime]
+ * @property {RuntimeComponent} [component] Legacy alias for runtime.
  */
 
 /**
@@ -327,14 +333,15 @@ export function getDefaultEnvironmentProjections(graph, options = {}) {
  */
 export function generateServerBundle(graph, projectionId, options = {}) {
   const topology = resolveRuntimeTopology(graph, options);
-  const component = options.component || topology.apiComponents.find((entry) => entry.projection.id === projectionId);
-  if (!component) {
-    throw new Error(`No api topology component found for projection '${projectionId}'`);
+  const runtime = options.runtime || options.component || topology.apiRuntimes.find((entry) => entry.projection.id === projectionId);
+  if (!runtime) {
+    throw new Error(`No api runtime found for projection '${projectionId}'`);
   }
   return generateWithComponentGenerator({
     graph,
-    projection: component.projection,
-    component,
+    projection: runtime.projection,
+    runtime,
+    component: runtime,
     topology,
     implementation: options.implementation || null,
     options: { ...options, projectionId }
@@ -349,14 +356,15 @@ export function generateServerBundle(graph, projectionId, options = {}) {
  */
 export function generateWebBundle(graph, projectionId, options = {}) {
   const topology = resolveRuntimeTopology(graph, options);
-  const component = options.component || topology.webComponents.find((entry) => entry.projection.id === projectionId);
-  if (!component) {
-    throw new Error(`No web topology component found for projection '${projectionId}'`);
+  const runtime = options.runtime || options.component || topology.webRuntimes.find((entry) => entry.projection.id === projectionId);
+  if (!runtime) {
+    throw new Error(`No web runtime found for projection '${projectionId}'`);
   }
   return generateWithComponentGenerator({
     graph,
-    projection: component.projection,
-    component,
+    projection: runtime.projection,
+    runtime,
+    component: runtime,
     topology,
     implementation: options.implementation || null,
     options: { ...options, projectionId }
@@ -371,14 +379,15 @@ export function generateWebBundle(graph, projectionId, options = {}) {
  */
 export function generateDbBundle(graph, projectionId, options = {}) {
   const topology = resolveRuntimeTopology(graph, options);
-  const component = options.component || topology.dbComponents.find((entry) => entry.projection.id === projectionId);
-  if (!component) {
-    throw new Error(`No database topology component found for projection '${projectionId}'`);
+  const runtime = options.runtime || options.component || topology.dbRuntimes.find((entry) => entry.projection.id === projectionId);
+  if (!runtime) {
+    throw new Error(`No database runtime found for projection '${projectionId}'`);
   }
   return generateWithComponentGenerator({
     graph,
     projection: getProjection(graph, projectionId),
-    component,
+    runtime,
+    component: runtime,
     topology,
     implementation: options.implementation || null,
     options: { ...options, projectionId }
@@ -438,10 +447,12 @@ function decorateRuntimes(graph, config) {
   const byId = new Map(runtimes.map((runtime) => [runtime.id, runtime]));
   for (const runtime of runtimes) {
     if (runtime.kind === "api_service" && runtime.database) {
-      runtime.databaseComponent = byId.get(runtime.database) || null;
+      runtime.databaseRuntime = byId.get(runtime.database) || null;
+      runtime.databaseComponent = runtime.databaseRuntime;
     }
     if (runtime.kind === "web_surface" && runtime.api) {
-      runtime.apiComponent = byId.get(runtime.api) || null;
+      runtime.apiRuntime = byId.get(runtime.api) || null;
+      runtime.apiComponent = runtime.apiRuntime;
     }
   }
   return runtimes;
@@ -462,20 +473,23 @@ export function resolveRuntimeTopology(graph, options = {}) {
     throw new Error(validation.errors.map((error) => error.message).join("\n"));
   }
   const runtimes = decorateRuntimes(graph, config);
-  const apiComponents = runtimes.filter((runtime) => runtime.kind === "api_service");
-  const webComponents = runtimes.filter((runtime) => runtime.kind === "web_surface");
-  const dbComponents = runtimes.filter((runtime) => runtime.kind === "database");
-  const primaryApi = apiComponents[0] || null;
-  const primaryWeb = webComponents[0] || null;
-  const primaryDb = primaryApi?.databaseComponent || dbComponents[0] || null;
+  const apiRuntimes = runtimes.filter((runtime) => runtime.kind === "api_service");
+  const webRuntimes = runtimes.filter((runtime) => runtime.kind === "web_surface");
+  const dbRuntimes = runtimes.filter((runtime) => runtime.kind === "database");
+  const primaryApi = apiRuntimes[0] || null;
+  const primaryWeb = webRuntimes[0] || null;
+  const primaryDb = primaryApi?.databaseRuntime || dbRuntimes[0] || null;
 
   return {
     config,
     runtimes,
     components: runtimes,
-    apiComponents,
-    webComponents,
-    dbComponents,
+    apiRuntimes,
+    webRuntimes,
+    dbRuntimes,
+    apiComponents: apiRuntimes,
+    webComponents: webRuntimes,
+    dbComponents: dbRuntimes,
     primaryApi,
     primaryWeb,
     primaryDb,

package/src/generator/surfaces/databases/index.js

@@ -57,11 +57,13 @@ export function generateDbTarget(target, graph, options = {}) {
       : generatePostgresDbLifecyclePlan(graph, options);
   }
   if (target === "db-lifecycle-bundle") {
-    if (options.component?.generator?.id) {
+    const runtime = options.runtime || options.component;
+    if (runtime?.generator?.id) {
       return generateWithComponentGenerator({
         graph,
-        projection: options.component.projection,
-        component: options.component,
+        projection: runtime.projection,
+        runtime,
+        component: runtime,
         topology: options.topology || null,
         implementation: options.implementation || null,
         options

package/src/generator/surfaces/index.js

@@ -8,11 +8,13 @@ export function generateAppTarget(target, graph, options = {}) {
     return generateBackendTarget(target, graph, options);
   }
   if (target === "swiftui-app") {
-    if (options.component?.generator?.id) {
+    const runtime = options.runtime || options.component;
+    if (runtime?.generator?.id) {
       return generateWithComponentGenerator({
         graph,
-        projection: options.component.projection,
-        component: options.component,
+        projection: runtime.projection,
+        runtime,
+        component: runtime,
         topology: options.topology || null,
         implementation: options.implementation || null,
         options

package/src/generator/surfaces/services/index.js

@@ -12,11 +12,13 @@ export function generateBackendTarget(target, graph, options = {}) {
     return generatePersistenceScaffold(graph, options);
   }
   if (target === "hono-server") {
-    if (options.component?.generator?.id) {
+    const runtime = options.runtime || options.component;
+    if (runtime?.generator?.id) {
       return generateWithComponentGenerator({
         graph,
-        projection: options.component.projection,
-        component: options.component,
+        projection: runtime.projection,
+        runtime,
+        component: runtime,
         topology: options.topology || null,
         implementation: options.implementation || null,
         options
@@ -25,11 +27,13 @@ export function generateBackendTarget(target, graph, options = {}) {
     return generateHonoServer(graph, options);
   }
   if (target === "express-server") {
-    if (options.component?.generator?.id) {
+    const runtime = options.runtime || options.component;
+    if (runtime?.generator?.id) {
       return generateWithComponentGenerator({
         graph,
-        projection: options.component.projection,
-        component: options.component,
+        projection: runtime.projection,
+        runtime,
+        component: runtime,
         topology: options.topology || null,
         implementation: options.implementation || null,
         options

package/src/generator/surfaces/web/index.js

@@ -15,17 +15,19 @@ import {
 
 export function generateWebApp(graph, options = {}) {
   const projection = getProjection(graph, options.projectionId);
-  if (options.component?.generator?.id) {
+  const runtime = options.runtime || options.component;
+  if (runtime?.generator?.id) {
     return generateWithComponentGenerator({
       graph,
       projection,
-      component: options.component,
+      runtime,
+      component: runtime,
       topology: options.topology || null,
       implementation: options.implementation || null,
       options: { ...options, projectionId: projection.id }
     }).files;
   }
-  const profile = generatorProfile(options.component?.generator?.id, null) || generatorDefaultsMap(projection).profile || "sveltekit";
+  const profile = generatorProfile(runtime?.generator?.id, null) || generatorDefaultsMap(projection).profile || "sveltekit";
   if (profile === "vanilla") {
     return generateVanillaWebApp(graph, options);
   }