@topogram/cli 0.3.51 → 0.3.53

package/src/generator/registry.js

@@ -10,13 +10,13 @@ import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../ui/taxonomy.js";
  * @property {string} id
  * @property {string} version
  * @property {"api"|"web"|"database"|"native"} surface
- * @property {"api"|"web"|"database"|"native"} [targetKind]
- * @property {string[]} projectionPlatforms
+ * @property {string[]} runtimeKinds
+ * @property {string[]} projectionTypes
  * @property {string[]} inputs
  * @property {string[]} outputs
  * @property {Record<string, string>} stack
  * @property {Record<string, boolean>} capabilities
- * @property {{ patterns?: string[], behaviors?: string[], unsupported?: "error"|"warning"|"contract-only" }} [componentSupport]
+ * @property {{ patterns?: string[], behaviors?: string[], unsupported?: "error"|"warning"|"contract-only" }} [widgetSupport]
  * @property {"bundled"|"package"} source
  * @property {string} [profile]
  * @property {string} [package]
@@ -32,8 +32,8 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/hono",
     version: "1",
     surface: "api",
-    targetKind: "api",
-    projectionPlatforms: ["api"],
+    runtimeKinds: ["api_service"],
+    projectionTypes: ["api_contract"],
     inputs: ["server-contract", "api-contracts"],
     outputs: ["api-service"],
     stack: { runtime: "node", framework: "hono", language: "typescript" },
@@ -45,8 +45,8 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/express",
     version: "1",
     surface: "api",
-    targetKind: "api",
-    projectionPlatforms: ["api"],
+    runtimeKinds: ["api_service"],
+    projectionTypes: ["api_contract"],
     inputs: ["server-contract", "api-contracts"],
     outputs: ["api-service"],
     stack: { runtime: "node", framework: "express", language: "typescript" },
@@ -58,13 +58,13 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/vanilla-web",
     version: "1",
     surface: "web",
-    targetKind: "web",
-    projectionPlatforms: ["ui_web"],
-    inputs: ["ui-web-contract"],
+    runtimeKinds: ["web_surface"],
+    projectionTypes: ["web_surface"],
+    inputs: ["ui-surface-contract"],
     outputs: ["web-app", "generation-coverage"],
     stack: { runtime: "browser", framework: "vanilla", language: "javascript" },
     capabilities: { routes: true, components: false, coverage: true },
-    componentSupport: { patterns: [], behaviors: [], unsupported: "contract-only" },
+    widgetSupport: { patterns: [], behaviors: [], unsupported: "contract-only" },
     source: "bundled",
     profile: "vanilla"
   },
@@ -72,13 +72,13 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/sveltekit",
     version: "1",
     surface: "web",
-    targetKind: "web",
-    projectionPlatforms: ["ui_web"],
-    inputs: ["ui-web-contract", "api-contracts"],
+    runtimeKinds: ["web_surface"],
+    projectionTypes: ["web_surface"],
+    inputs: ["ui-surface-contract", "api-contracts"],
     outputs: ["web-app", "generation-coverage"],
     stack: { runtime: "node", framework: "sveltekit", language: "typescript" },
     capabilities: { routes: true, components: true, coverage: true },
-    componentSupport: {
+    widgetSupport: {
       patterns: RENDERED_COMPONENT_PATTERNS,
       behaviors: ["selection", "sorting", "filtering", "search", "pagination", "bulk_action", "optimistic_update"],
       unsupported: "warning"
@@ -90,13 +90,13 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/react",
     version: "1",
     surface: "web",
-    targetKind: "web",
-    projectionPlatforms: ["ui_web"],
-    inputs: ["ui-web-contract", "api-contracts"],
+    runtimeKinds: ["web_surface"],
+    projectionTypes: ["web_surface"],
+    inputs: ["ui-surface-contract", "api-contracts"],
     outputs: ["web-app", "generation-coverage"],
     stack: { runtime: "browser", framework: "react", language: "typescript" },
     capabilities: { routes: true, components: true, coverage: true },
-    componentSupport: {
+    widgetSupport: {
       patterns: RENDERED_COMPONENT_PATTERNS,
       behaviors: ["selection", "sorting", "filtering", "search", "pagination", "bulk_action", "optimistic_update"],
       unsupported: "warning"
@@ -108,13 +108,13 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/swiftui",
     version: "1",
     surface: "native",
-    targetKind: "native",
-    projectionPlatforms: ["ui_ios"],
-    inputs: ["ui-web-contract", "api-contracts"],
+    runtimeKinds: ["ios_surface"],
+    projectionTypes: ["ios_surface"],
+    inputs: ["ui-surface-contract", "api-contracts"],
     outputs: ["native-app"],
     stack: { platform: "ios", framework: "swiftui", language: "swift" },
     capabilities: { routes: true, components: false, coverage: false },
-    componentSupport: { patterns: [], behaviors: [], unsupported: "contract-only" },
+    widgetSupport: { patterns: [], behaviors: [], unsupported: "contract-only" },
     source: "bundled",
     profile: "swiftui"
   },
@@ -122,8 +122,8 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/postgres",
     version: "1",
     surface: "database",
-    targetKind: "database",
-    projectionPlatforms: ["db_postgres"],
+    runtimeKinds: ["database"],
+    projectionTypes: ["db_contract"],
     inputs: ["db-contract", "db-lifecycle-plan"],
     outputs: ["db-lifecycle-bundle", "sql-schema", "sql-migration", "prisma-schema", "drizzle-schema"],
     stack: { database: "postgres", language: "sql" },
@@ -135,8 +135,8 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/sqlite",
     version: "1",
     surface: "database",
-    targetKind: "database",
-    projectionPlatforms: ["db_sqlite"],
+    runtimeKinds: ["database"],
+    projectionTypes: ["db_contract"],
     inputs: ["db-contract", "db-lifecycle-plan"],
     outputs: ["db-lifecycle-bundle", "sql-schema", "sql-migration", "prisma-schema"],
     stack: { database: "sqlite", language: "sql" },
@@ -148,13 +148,13 @@ export const GENERATOR_MANIFESTS = [
     id: "topogram/android-compose",
     version: "1",
     surface: "native",
-    targetKind: "native",
-    projectionPlatforms: ["ui_android"],
-    inputs: ["ui-web-contract", "api-contracts"],
+    runtimeKinds: ["android_surface"],
+    projectionTypes: ["android_surface"],
+    inputs: ["ui-surface-contract", "api-contracts"],
     outputs: ["native-app"],
     stack: { platform: "android", framework: "compose", language: "kotlin" },
     capabilities: { routes: true, components: false, coverage: false },
-    componentSupport: { patterns: [], behaviors: [], unsupported: "contract-only" },
+    widgetSupport: { patterns: [], behaviors: [], unsupported: "contract-only" },
     source: "bundled",
     profile: "compose",
     planned: true
@@ -190,6 +190,16 @@ function isStringArray(value, nonEmpty = false) {
     value.every((entry) => typeof entry === "string" && entry.length > 0);
 }
 
+/**
+ * @param {string} oldName
+ * @param {string} newName
+ * @param {string} example
+ * @returns {string}
+ */
+function renameDiagnostic(oldName, newName, example) {
+  return `${oldName} was renamed to ${newName}. Example fix: ${example}`;
+}
+
 /**
  * @param {string} generatorId
  * @returns {GeneratorManifest|null}
@@ -392,8 +402,17 @@ export function validateGeneratorManifest(manifest) {
   if (!["api", "web", "database", "native"].includes(manifest.surface)) {
     errors.push(`${label} surface must be api, web, database, or native`);
   }
-  if (!isStringArray(manifest.projectionPlatforms, true)) {
-    errors.push(`${label} projectionPlatforms must be a non-empty string array`);
+  if (manifest.targetKind != null) {
+    errors.push(`${label} ${renameDiagnostic("'targetKind'", "'runtimeKinds'", `"runtimeKinds": ["web_surface"]`)}`);
+  }
+  if (!isStringArray(manifest.runtimeKinds, true)) {
+    errors.push(`${label} runtimeKinds must be a non-empty string array`);
+  }
+  if (manifest["projectionPlatforms"] != null) {
+    errors.push(`${label} ${renameDiagnostic("'projectionPlatforms'", "'projectionTypes'", `"projectionTypes": ["web_surface"]`)}`);
+  }
+  if (!isStringArray(manifest.projectionTypes, true)) {
+    errors.push(`${label} projectionTypes must be a non-empty string array`);
   }
   if (!isStringArray(manifest.inputs)) {
     errors.push(`${label} inputs must be a string array`);
@@ -407,21 +426,24 @@ export function validateGeneratorManifest(manifest) {
   if (!manifest.capabilities || typeof manifest.capabilities !== "object" || Array.isArray(manifest.capabilities)) {
     errors.push(`${label} capabilities must be an object`);
   }
-  if (manifest.componentSupport != null) {
-    if (typeof manifest.componentSupport !== "object" || Array.isArray(manifest.componentSupport)) {
-      errors.push(`${label} componentSupport must be an object when present`);
+  if (manifest["componentSupport"] != null) {
+    errors.push(`${label} ${renameDiagnostic("'componentSupport'", "'widgetSupport'", `"widgetSupport": { "patterns": ["resource_table"] }`)}`);
+  }
+  if (manifest.widgetSupport != null) {
+    if (typeof manifest.widgetSupport !== "object" || Array.isArray(manifest.widgetSupport)) {
+      errors.push(`${label} widgetSupport must be an object when present`);
     } else {
-      if (manifest.componentSupport.patterns != null && !isStringArray(manifest.componentSupport.patterns)) {
-        errors.push(`${label} componentSupport.patterns must be a string array`);
+      if (manifest.widgetSupport.patterns != null && !isStringArray(manifest.widgetSupport.patterns)) {
+        errors.push(`${label} widgetSupport.patterns must be a string array`);
       }
-      if (manifest.componentSupport.behaviors != null && !isStringArray(manifest.componentSupport.behaviors)) {
-        errors.push(`${label} componentSupport.behaviors must be a string array`);
+      if (manifest.widgetSupport.behaviors != null && !isStringArray(manifest.widgetSupport.behaviors)) {
+        errors.push(`${label} widgetSupport.behaviors must be a string array`);
       }
       if (
-        manifest.componentSupport.unsupported != null &&
-        !["error", "warning", "contract-only"].includes(manifest.componentSupport.unsupported)
+        manifest.widgetSupport.unsupported != null &&
+        !["error", "warning", "contract-only"].includes(manifest.widgetSupport.unsupported)
       ) {
-        errors.push(`${label} componentSupport.unsupported must be error, warning, or contract-only`);
+        errors.push(`${label} widgetSupport.unsupported must be error, warning, or contract-only`);
       }
     }
   }
@@ -466,20 +488,20 @@ export function isApiProjection(projection) {
  */
 export function projectionCompatibilityKey(projection) {
   if (isApiProjection(projection)) {
-    return "api";
+    return "api_contract";
   }
-  return projection?.platform || "";
+  return projection?.type || projection?.platform || "";
 }
 
 /**
  * @param {GeneratorManifest|null|undefined} manifest
- * @param {string} componentType
+ * @param {string} runtimeKind
  * @param {Record<string, any>|null|undefined} projection
  * @returns {boolean}
  */
-export function isGeneratorCompatible(manifest, componentType, projection) {
-  if (!manifest || manifest.planned || manifest.surface !== componentType) {
+export function isGeneratorCompatible(manifest, runtimeKind, projection) {
+  if (!manifest || manifest.planned || !manifest.runtimeKinds.includes(runtimeKind)) {
     return false;
   }
-  return manifest.projectionPlatforms.includes(projectionCompatibilityKey(projection));
+  return manifest.projectionTypes.includes(projectionCompatibilityKey(projection));
 }

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

@@ -66,14 +66,14 @@ function buildAppBundlePlan(graph, options = {}) {
       db: dbProjection?.id || null
     },
     topology: {
-      components: topology.components.map((component) => ({
-        id: component.id,
-        type: component.type,
-        projection: component.projection.id,
-        generator: component.generator,
-        port: component.port ?? null,
-        api: component.api || null,
-        database: component.database || null
+      runtimes: topology.runtimes.map((runtime) => ({
+        id: runtime.id,
+        kind: runtime.kind,
+        projection: runtime.projection.id,
+        generator: runtime.generator,
+        port: runtime.port ?? null,
+        uses_api: runtime.api || null,
+        uses_database: runtime.database || null
       }))
     },
     runtimeReference,
@@ -108,8 +108,8 @@ function renderAppBundleEnvExample(plan) {
   const demoUserId = runtimeDemoUserId(plan.runtimeReference);
   const databaseName = plan.runtimeReference.environment.databaseName || "topogram_app";
   const topology = {
-    primaryApi: { port: plan.topology.components.find((component) => component.type === "api")?.port },
-    primaryWeb: { port: plan.topology.components.find((component) => component.type === "web")?.port }
+    primaryApi: { port: plan.topology.runtimes.find((runtime) => runtime.kind === "api_service")?.port },
+    primaryWeb: { port: plan.topology.runtimes.find((runtime) => runtime.kind === "web_surface")?.port }
   };
   const ports = runtimePorts(plan.runtimeReference, topology);
   const urls = runtimeUrls(plan.runtimeReference, topology);
@@ -126,7 +126,7 @@ ${plan.runtimeReference.environment.envExample || ""}
 # Smoke-test defaults
 ${plan.projections.api ? `TOPOGRAM_API_BASE_URL=${urls.api}\n` : ""}${plan.projections.ui ? `TOPOGRAM_WEB_BASE_URL=${urls.web}\n` : ""}`;
   }
-  if (plan.projections.dbPlatform === "db_sqlite") {
+  if (plan.projections.dbPlatform === "db_contract") {
     return `# App bundle defaults
 TOPOGRAM_ENVIRONMENT_PROFILE=${plan.profiles.environment}
 TOPOGRAM_DEPLOY_PROFILE=${plan.profiles.deployment}
@@ -173,8 +173,8 @@ TOPOGRAM_WEB_BASE_URL=${urls.web}
 
 function renderAppBundleReadme(plan) {
   const urls = runtimeUrls(plan.runtimeReference, {
-    primaryApi: { port: plan.topology.components.find((component) => component.type === "api")?.port },
-    primaryWeb: { port: plan.topology.components.find((component) => component.type === "web")?.port }
+    primaryApi: { port: plan.topology.runtimes.find((runtime) => runtime.kind === "api_service")?.port },
+    primaryWeb: { port: plan.topology.runtimes.find((runtime) => runtime.kind === "web_surface")?.port }
   });
   return `# ${plan.name}
 
@@ -311,8 +311,8 @@ bash "$SCRIPT_DIR/runtime-check.sh"
 
 function renderAppBundleWaitForStackScript(plan) {
   const topology = {
-    primaryApi: { port: plan.topology.components.find((component) => component.type === "api")?.port },
-    primaryWeb: { port: plan.topology.components.find((component) => component.type === "web")?.port }
+    primaryApi: { port: plan.topology.runtimes.find((runtime) => runtime.kind === "api_service")?.port },
+    primaryWeb: { port: plan.topology.runtimes.find((runtime) => runtime.kind === "web_surface")?.port }
   };
   const ports = runtimePorts(plan.runtimeReference, topology);
   const urls = runtimeUrls(plan.runtimeReference, topology);

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

@@ -57,11 +57,11 @@ function buildCompileCheckPlan(graph, options = {}) {
       db: dbProjection?.id || null
     },
     topology: {
-      components: topology.components.map((component) => ({
-        id: component.id,
-        type: component.type,
-        projection: component.projection.id,
-        generator: component.generator
+      runtimes: topology.runtimes.map((runtime) => ({
+        id: runtime.id,
+        kind: runtime.kind,
+        projection: runtime.projection.id,
+        generator: runtime.generator
       }))
     },
     checks: [...apiChecks, ...webChecks]
@@ -73,7 +73,7 @@ function renderCompileCheckEnvExample(graph, options = {}) {
   const topology = resolveRuntimeTopology(graph, options);
   const { dbProjection } = getDefaultEnvironmentProjections(graph, options);
   const urls = runtimeUrls(runtimeReference, topology);
-  if (dbProjection?.platform === "db_sqlite") {
+  if (dbProjection?.platform === "db_contract") {
     return `DATABASE_URL=./var/${runtimeReference.environment.databaseName || "topogram_app"}.sqlite
 PUBLIC_TOPOGRAM_API_BASE_URL=${urls.api}
 PUBLIC_TOPOGRAM_DEMO_USER_ID=${runtimeDemoUserId(runtimeReference)}
@@ -122,7 +122,7 @@ function renderCompileCheckScript(plan) {
     ""
   ];
   if (plan.checks.length === 0) {
-    lines.push('echo "No API or web components are configured; compile check is a no-op."');
+    lines.push('echo "No API or web runtimes are configured; compile check is a no-op."');
   }
   for (const check of plan.checks) {
     const label = check.id.includes("web")

package/src/generator/runtime/deployment.js

@@ -33,7 +33,7 @@ function buildDeploymentPlan(graph, options = {}) {
   const profile = options.profileId || "fly_io";
   const supportedProfiles = ["fly_io", "railway"];
   const webProfile = manifestGeneratorProfile(topology.primaryWeb?.generator?.id, null) || projectionHintProfile(uiProjection, "sveltekit");
-  const databaseTarget = dbProjection.platform === "db_sqlite"
+  const databaseTarget = dbProjection.platform === "db_contract"
     ? "sqlite_file"
     : profile === "fly_io"
       ? "managed_postgres"
@@ -54,14 +54,14 @@ function buildDeploymentPlan(graph, options = {}) {
       db: dbProjection.id
     },
     topology: {
-      components: topology.components.map((component) => ({
-        id: component.id,
-        type: component.type,
-        projection: component.projection.id,
-        generator: component.generator,
-        port: component.port ?? null,
-        api: component.api || null,
-        database: component.database || null
+      runtimes: topology.runtimes.map((runtime) => ({
+        id: runtime.id,
+        kind: runtime.kind,
+        projection: runtime.projection.id,
+        generator: runtime.generator,
+        port: runtime.port ?? null,
+        uses_api: runtime.api || null,
+        uses_database: runtime.database || null
       }))
     },
     directories: {

package/src/generator/runtime/environment.js

@@ -43,10 +43,10 @@ function buildEnvironmentPlan(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 profile = options.profileId || (dbProjection?.platform === "db_sqlite" || !dbProjection ? "local_process" : "local_docker");
+  const profile = options.profileId || (dbProjection?.platform === "db_contract" || !dbProjection ? "local_process" : "local_docker");
   const usesDocker = profile === "local_docker";
   const webProfile = manifestGeneratorProfile(topology.primaryWeb?.generator?.id, null) || projectionHintProfile(uiProjection, "sveltekit");
-  const isSqlite = dbProjection?.platform === "db_sqlite";
+  const isSqlite = dbProjection?.platform === "db_contract";
   const ports = runtimePorts(runtimeReference, topology);
 
   return {
@@ -58,14 +58,14 @@ function buildEnvironmentPlan(graph, options = {}) {
       profile
     },
     topology: {
-      components: topology.components.map((component) => ({
-        id: component.id,
-        type: component.type,
-        projection: component.projection.id,
-        generator: component.generator,
-        port: component.port ?? null,
-        api: component.api || null,
-        database: component.database || null
+      runtimes: topology.runtimes.map((runtime) => ({
+        id: runtime.id,
+        kind: runtime.kind,
+        projection: runtime.projection.id,
+        generator: runtime.generator,
+        port: runtime.port ?? null,
+        uses_api: runtime.api || null,
+        uses_database: runtime.database || null
       }))
     },
     projections: {
@@ -110,7 +110,7 @@ function buildEnvironmentPlan(graph, options = {}) {
       db: topology.primaryDb ? topology.dbDir(topology.primaryDb) : null,
       scripts: "scripts"
     },
-    components: {
+    runtimes: {
       apis: topology.apiComponents.map((component) => ({
         id: component.id,
         projection: component.projection.id,
@@ -165,11 +165,11 @@ function renderEnvironmentEnvExample(plan) {
     primaryApi: { port: plan.ports.server },
     primaryWeb: { port: plan.ports.web }
   });
-  const extraDatabaseLines = plan.components.databases
-    .filter((component) => component.id !== plan.components.databases[0]?.id)
+  const extraDatabaseLines = plan.runtimes.databases
+    .filter((component) => component.id !== plan.runtimes.databases[0]?.id)
     .map((component) => {
       const fallbackName = `${databaseName}_${component.id}`;
-      if (component.platform === "db_sqlite") {
+      if (component.platform === "db_contract") {
         return `${component.env.databaseUrl}=file:./var/${component.id}.sqlite`;
       }
       return [
@@ -185,7 +185,7 @@ function renderEnvironmentEnvExample(plan) {
 TOPOGRAM_ENVIRONMENT_PROFILE=${plan.environment.profile}
 
 # Local stack ports
-${plan.components.apis.length ? `SERVER_PORT=${plan.ports.server}\n` : ""}${plan.components.webs.length ? `WEB_PORT=${plan.ports.web}\n` : ""}${plan.components.webs.length && plan.components.apis.length ? `PUBLIC_TOPOGRAM_API_BASE_URL=${urls.api}\n` : ""}${plan.components.webs.length ? `TOPOGRAM_CORS_ORIGINS=${urls.web},http://127.0.0.1:${plan.ports.web}\n` : ""}PUBLIC_TOPOGRAM_DEMO_USER_ID=${demoUserId}
+${plan.runtimes.apis.length ? `SERVER_PORT=${plan.ports.server}\n` : ""}${plan.runtimes.webs.length ? `WEB_PORT=${plan.ports.web}\n` : ""}${plan.runtimes.webs.length && plan.runtimes.apis.length ? `PUBLIC_TOPOGRAM_API_BASE_URL=${urls.api}\n` : ""}${plan.runtimes.webs.length ? `TOPOGRAM_CORS_ORIGINS=${urls.web},http://127.0.0.1:${plan.ports.web}\n` : ""}PUBLIC_TOPOGRAM_DEMO_USER_ID=${demoUserId}
 TOPOGRAM_DEMO_USER_ID=${demoUserId}
 ${plan.runtimeReference.environment.envExample || ""}
 TOPOGRAM_SEED_DEMO=true
@@ -193,7 +193,7 @@ TOPOGRAM_SEED_DEMO=true
   if (!plan.projections.db.platform) {
     return commonLines;
   }
-  if (plan.projections.db.platform === "db_sqlite") {
+  if (plan.projections.db.platform === "db_contract") {
     return `# Environment profile
 TOPOGRAM_ENVIRONMENT_PROFILE=${plan.environment.profile}
 
@@ -267,12 +267,12 @@ function apiDatabaseExportLines(component) {
 }
 
 function renderEnvironmentReadme(plan) {
-  const hasDb = plan.components.databases.length > 0;
-  const hasApi = plan.components.apis.length > 0;
-  const hasWeb = plan.components.webs.length > 0;
+  const hasDb = plan.runtimes.databases.length > 0;
+  const hasApi = plan.runtimes.apis.length > 0;
+  const hasWeb = plan.runtimes.webs.length > 0;
   const localProcessNotes = !hasDb
     ? "- This bundle has no generated database surface."
-    : plan.projections.db.platform === "db_sqlite"
+    : plan.projections.db.platform === "db_contract"
     ? "- SQLite is file-backed for this bundle; no separate DB server is required."
     : `- Make sure the Postgres server is already running before \`${plan.commands.bootstrapDb}\`.\n- \`DATABASE_URL\` and \`DATABASE_ADMIN_URL\` should point at your local or managed Postgres instance.`;
   const dockerSection = plan.orchestration.usesDocker
@@ -291,13 +291,13 @@ ${localProcessNotes}
 
 This bundle packages the generated runtime into one local environment:
 
-${hasApi ? "- `services/<api-id>/`: generated API service scaffolds\n" : ""}${hasWeb ? `- \`web/<web-id>/\`: generated ${plan.runtimeProfiles.web === "react" ? "Vite + React Router" : plan.runtimeProfiles.web === "vanilla" ? "vanilla HTML/CSS/JS" : "SvelteKit"} web scaffolds\n` : ""}${hasDb ? "- `db/<db-id>/`: generated DB lifecycle bundles\n" : ""}${plan.files.dockerCompose ? `- \`${plan.files.dockerCompose}\`: local Postgres container` : hasDb ? (plan.projections.db.platform === "db_sqlite" ? "- local SQLite file orchestration (no Docker files generated)" : "- local-process Postgres orchestration (no Docker files generated)") : "- no DB orchestration is generated"}
+${hasApi ? "- `services/<api-id>/`: generated API service scaffolds\n" : ""}${hasWeb ? `- \`web/<web-id>/\`: generated ${plan.runtimeProfiles.web === "react" ? "Vite + React Router" : plan.runtimeProfiles.web === "vanilla" ? "vanilla HTML/CSS/JS" : "SvelteKit"} web scaffolds\n` : ""}${hasDb ? "- `db/<db-id>/`: generated DB lifecycle bundles\n" : ""}${plan.files.dockerCompose ? `- \`${plan.files.dockerCompose}\`: local Postgres container` : hasDb ? (plan.projections.db.platform === "db_contract" ? "- local SQLite file orchestration (no Docker files generated)" : "- local-process Postgres orchestration (no Docker files generated)") : "- no DB orchestration is generated"}
 
 ## Quick Start
 
 1. Copy \`.env.example\` to \`.env\` if you want to customize defaults
 2. Start the database:
-   - ${!hasDb ? "not applicable" : plan.projections.db.platform === "db_sqlite" ? "no separate DB service is required" : plan.orchestration.usesDocker ? `\`${plan.commands.dockerDb}\`` : "use your local Postgres service"}
+   - ${!hasDb ? "not applicable" : plan.projections.db.platform === "db_contract" ? "no separate DB service is required" : plan.orchestration.usesDocker ? `\`${plan.commands.dockerDb}\`` : "use your local Postgres service"}
 3. Bootstrap or migrate the database:
    - \`${plan.commands.bootstrapDb}\`
 4. Start the stack:
@@ -313,7 +313,7 @@ ${dockerSection}
 
 ## Notes
 
-- ${hasApi && hasDb ? `The generated server expects ${plan.projections.db.platform === "db_sqlite" ? "SQLite plus Prisma." : "Postgres plus Prisma."}` : hasApi ? "The generated server is stateless." : "No server surface is generated."}
+- ${hasApi && hasDb ? `The generated server expects ${plan.projections.db.platform === "db_contract" ? "SQLite plus Prisma." : "Postgres plus Prisma."}` : hasApi ? "The generated server is stateless." : "No server surface is generated."}
 - ${hasWeb && hasApi ? "The generated web app talks to `PUBLIC_TOPOGRAM_API_BASE_URL`." : hasWeb ? "The generated web app is standalone." : "No web surface is generated."}
 - If \`.env\` is missing, generated scripts fall back to \`.env.example\`.
 - The DB lifecycle scripts remain the source of truth for greenfield bootstrap and brownfield migration.
@@ -325,9 +325,9 @@ function renderEnvironmentLoadEnvScript() {
 }
 
 function renderEnvironmentBootstrapDbScript(plan) {
-  const dbBootstrapLines = plan.components.databases.map((component) => {
+  const dbBootstrapLines = plan.runtimes.databases.map((component) => {
     const env = component.env;
-    const runtimeApi = plan.components.apis.find((apiComponent) => apiComponent.database === component.id);
+    const runtimeApi = plan.runtimes.apis.find((apiComponent) => apiComponent.database === component.id);
     const assignments = [
       `DATABASE_URL="\${${env.databaseUrl}:-}"`,
       `DATABASE_ADMIN_URL="\${${env.databaseAdminUrl}:-}"`,
@@ -335,10 +335,10 @@ function renderEnvironmentBootstrapDbScript(plan) {
     ].filter(Boolean).join(" ");
     return `(cd "$ROOT_DIR/${component.dir}" && TOPOGRAM_ENV_FILE=/dev/null ${assignments} bash ./scripts/db-bootstrap-or-migrate.sh)`;
   });
-  const primaryApi = plan.components.apis[0];
-  if (plan.components.databases.length === 0) {
+  const primaryApi = plan.runtimes.apis[0];
+  if (plan.runtimes.databases.length === 0) {
     return renderEnvAwareShellScript([
-      'echo "No database components are configured; skipping DB bootstrap."'
+      'echo "No database runtimes are configured; skipping DB bootstrap."'
     ]);
   }
   return renderEnvAwareShellScript([
@@ -367,9 +367,9 @@ function componentScriptOptions() {
   };
 }
 
-function renderEnvironmentServerDevScript(plan, component = plan.components.apis[0], options = {}) {
+function renderEnvironmentServerDevScript(plan, component = plan.runtimes.apis[0], options = {}) {
   if (!component) {
-    return renderEnvAwareShellScript(['echo "No API components are configured."']);
+    return renderEnvAwareShellScript(['echo "No API runtimes are configured."']);
   }
   const guardPortsScript = options.componentScript ? '"$ROOT_DIR/scripts/guard-ports.mjs"' : '"$SCRIPT_DIR/guard-ports.mjs"';
   return renderEnvAwareShellScript([
@@ -386,11 +386,11 @@ function renderEnvironmentServerDevScript(plan, component = plan.components.apis
   ], options.componentScript ? componentScriptOptions() : {});
 }
 
-function renderEnvironmentWebDevScript(plan, component = plan.components.webs[0], options = {}) {
+function renderEnvironmentWebDevScript(plan, component = plan.runtimes.webs[0], options = {}) {
   if (!component) {
-    return renderEnvAwareShellScript(['echo "No web components are configured."']);
+    return renderEnvAwareShellScript(['echo "No web runtimes are configured."']);
   }
-  const apiComponent = plan.components.apis.find((entry) => entry.id === component.api) || plan.components.apis[0];
+  const apiComponent = plan.runtimes.apis.find((entry) => entry.id === component.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`,
@@ -406,8 +406,8 @@ function renderEnvironmentWebDevScript(plan, component = plan.components.webs[0]
 
 function renderEnvironmentStackDevScript(plan) {
   const startLines = [
-    ...plan.components.apis.map((component) => `bash "$SCRIPT_DIR/services/${component.id}-dev.sh" &\nPIDS+=($!)`),
-    ...plan.components.webs.map((component) => `bash "$SCRIPT_DIR/web/${component.id}-dev.sh" &\nPIDS+=($!)`)
+    ...plan.runtimes.apis.map((component) => `bash "$SCRIPT_DIR/services/${component.id}-dev.sh" &\nPIDS+=($!)`),
+    ...plan.runtimes.webs.map((component) => `bash "$SCRIPT_DIR/web/${component.id}-dev.sh" &\nPIDS+=($!)`)
   ];
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -447,8 +447,8 @@ ${startLines.length ? "wait" : ""}
 
 function renderEnvironmentGuardPortsScript(plan) {
   const ports = [
-    ...plan.components.apis.map((component) => ({ id: component.id, type: "api", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: "SERVER_PORT", port: component.port })),
-    ...plan.components.webs.map((component) => ({ id: component.id, type: "web", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: "WEB_PORT", port: component.port }))
+    ...plan.runtimes.apis.map((component) => ({ id: component.id, type: "api", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: "SERVER_PORT", port: component.port })),
+    ...plan.runtimes.webs.map((component) => ({ id: component.id, type: "web", env: `${component.id.toUpperCase()}_PORT`, fallbackEnv: "WEB_PORT", port: component.port }))
   ];
   return `#!/usr/bin/env node
 import net from "node:net";
@@ -596,10 +596,10 @@ export function generateEnvironmentBundle(graph, options = {}) {
     "scripts/guard-ports.mjs": renderEnvironmentGuardPortsScript(plan)
   };
 
-  for (const component of plan.components.apis) {
+  for (const component of plan.runtimes.apis) {
     files[`scripts/services/${component.id}-dev.sh`] = renderEnvironmentServerDevScript(plan, component, { componentScript: true });
   }
-  for (const component of plan.components.webs) {
+  for (const component of plan.runtimes.webs) {
     files[`scripts/web/${component.id}-dev.sh`] = renderEnvironmentWebDevScript(plan, component, { componentScript: true });
   }
 

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

@@ -38,11 +38,11 @@ function buildRuntimeCheckPlan(graph, options = {}) {
       db: dbProjection.id
     },
     topology: {
-      components: topology.components.map((component) => ({
-        id: component.id,
-        type: component.type,
-        projection: component.projection.id,
-        generator: component.generator
+      runtimes: topology.runtimes.map((runtime) => ({
+        id: runtime.id,
+        kind: runtime.kind,
+        projection: runtime.projection.id,
+        generator: runtime.generator
       }))
     },
     ...(verification ? { verification } : {}),