@topogram/cli 0.3.50 → 0.3.52

package/src/generator/runtime/shared.js

@@ -19,24 +19,26 @@ import { defaultProjectConfigForGraph, validateProjectConfig } from "../../proje
 /**
  * @typedef {Object} RuntimeComponent
  * @property {string} id
- * @property {"api"|"web"|"database"|"native"} type
+ * @property {"api_service"|"web_surface"|"ios_surface"|"android_surface"|"database"} kind
+ * @property {string} [type]
  * @property {RuntimeStatement} projection
  * @property {import("../../project-config.js").GeneratorBinding} generator
  * @property {number|null} [port]
- * @property {string} [api]
- * @property {string} [database]
+ * @property {string|null} [api]
+ * @property {string|null} [database]
  * @property {Record<string, string>} [env]
  * @property {RuntimeComponent|null} [apiComponent]
  * @property {RuntimeComponent|null} [databaseComponent]
  */
 
 /**
- * @typedef {import("../../project-config.js").RuntimeTopologyComponent} RuntimeTopologyComponent
+ * @typedef {import("../../project-config.js").RuntimeTopologyRuntime} RuntimeTopologyComponent
  */
 
 /**
  * @typedef {Object} RuntimeTopology
  * @property {import("../../project-config.js").ProjectConfig} config
+ * @property {RuntimeComponent[]} runtimes
  * @property {RuntimeComponent[]} components
  * @property {RuntimeComponent[]} apiComponents
  * @property {RuntimeComponent[]} webComponents
@@ -227,17 +229,17 @@ function apiProjectionCandidates(graph) {
  */
 function uiWebProjectionCandidates(graph) {
   return (graph.byKind.projection || []).filter(
-    (projection) => projection.platform === "ui_web" && (projection.uiRoutes || []).length > 0
+    (projection) => projection.platform === "web_surface" && (projection.uiRoutes || []).length > 0
   );
 }
 
-const WEB_UI_FAMILY_PREFIX = "proj_ui_web__";
-const NATIVE_UI_FAMILY_PREFIX = "proj_ui_native__";
+const WEB_UI_FAMILY_PREFIX = "proj_web_surface__";
+const NATIVE_UI_FAMILY_PREFIX = "proj_ios_surface__";
 
 /** Prefer canonical ids when multiple shipped web stacks exist (deterministic, not lexicographic). */
-const DEFAULT_WEB_UI_STACK_ORDER = ["proj_ui_web__sveltekit", "proj_ui_web__react"];
+const DEFAULT_WEB_UI_STACK_ORDER = ["proj_web_surface__sveltekit", "proj_web_surface__react"];
 
-const DEFAULT_NATIVE_UI_PLATFORM_ORDER = ["proj_ui_native__ios"];
+const DEFAULT_NATIVE_UI_PLATFORM_ORDER = ["proj_ios_surface__swiftui"];
 
 /**
  * @param {ResolvedGraph} graph
@@ -245,12 +247,12 @@ const DEFAULT_NATIVE_UI_PLATFORM_ORDER = ["proj_ui_native__ios"];
  */
 function uiIosProjectionCandidates(graph) {
   return (graph.byKind.projection || []).filter(
-    (projection) => projection.platform === "ui_ios" && (projection.uiRoutes || []).length > 0
+    (projection) => projection.platform === "ios_surface" && (projection.uiRoutes || []).length > 0
   );
 }
 
 /**
- * Prefer canonical native projections (`proj_ui_native__{platform}`); otherwise first routed ui_ios projection.
+ * Prefer canonical native projections (`proj_ios_surface__{stack}`); otherwise first routed iOS surface projection.
  *
  * @param {ResolvedGraph} graph
  * @returns {RuntimeStatement|undefined}
@@ -271,7 +273,7 @@ export function pickDefaultIosUiProjection(graph) {
 }
 
 /**
- * Prefer canonical shipped web projections (`proj_ui_web__{stack}`); otherwise first routed ui_web projection.
+ * Prefer canonical shipped web projections (`proj_web_surface__{stack}`); otherwise first routed web surface projection.
  *
  * @param {ResolvedGraph} graph
  * @returns {RuntimeStatement|undefined}
@@ -288,10 +290,6 @@ export function pickDefaultUiWebProjection(graph) {
     }
     return hierarchical.sort((a, b) => a.id.localeCompare(b.id))[0];
   }
-  const legacySvelteKitProjection = candidates.find((projection) => projection.id === "proj_ui_web");
-  if (legacySvelteKitProjection) {
-    return legacySvelteKitProjection;
-  }
   return candidates[0];
 }
 
@@ -302,7 +300,7 @@ export function pickDefaultUiWebProjection(graph) {
  */
 export function getDefaultEnvironmentProjections(graph, options = {}) {
   const topology = resolveRuntimeTopology(graph, options);
-  const dbCandidates = graph.byKind.projection?.filter((projection) => ["db_postgres", "db_sqlite"].includes(projection.platform)) || [];
+  const dbCandidates = graph.byKind.projection?.filter((projection) => ["db_contract", "db_contract"].includes(projection.platform)) || [];
   const apiProjection = /** @type {RuntimeStatement|null} */ (topology.primaryApi?.projection ||
     (options.projectionId ? getProjection(graph, options.projectionId) : null) ||
     apiProjectionCandidates(graph).find((projection) => projection.id === "proj_api") ||
@@ -396,14 +394,14 @@ export function generateRuntimeApiContracts(graph) {
 }
 
 /**
- * @param {string} componentId
+ * @param {string} runtimeId
  * @param {EnvVarOptions} [options]
  * @returns {string}
  */
-function envVarPrefix(componentId, options = {}) {
-  return options.primary || componentId === "db"
+function envVarPrefix(runtimeId, options = {}) {
+  return options.primary || runtimeId === "db"
     ? ""
-    : `${componentId.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_`;
+    : `${runtimeId.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_`;
 }
 
 /**
@@ -426,24 +424,27 @@ export function dbEnvVarsForComponent(component, options = {}) {
  * @param {import("../../project-config.js").ProjectConfig} config
  * @returns {RuntimeComponent[]}
  */
-function decorateComponents(graph, config) {
+function decorateRuntimes(graph, config) {
   const byProjectionId = new Map((graph.byKind.projection || []).map((projection) => [projection.id, projection]));
-  const rawComponents = config.topology?.components || [];
+  const rawRuntimes = config.topology?.runtimes || config.topology?.components || [];
   /** @type {RuntimeComponent[]} */
-  const components = rawComponents.map((component) => ({
-    ...component,
-    projection: byProjectionId.get(component.projection) || {}
+  const runtimes = rawRuntimes.map((runtime) => ({
+    ...runtime,
+    kind: runtime.kind || runtime.type || null,
+    api: runtime.uses_api ?? runtime.api ?? null,
+    database: runtime.uses_database ?? runtime.database ?? null,
+    projection: byProjectionId.get(runtime.projection) || {}
   }));
-  const byId = new Map(components.map((component) => [component.id, component]));
-  for (const component of components) {
-    if (component.type === "api" && component.database) {
-      component.databaseComponent = byId.get(component.database) || null;
+  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;
     }
-    if (component.type === "web" && component.api) {
-      component.apiComponent = byId.get(component.api) || null;
+    if (runtime.kind === "web_surface" && runtime.api) {
+      runtime.apiComponent = byId.get(runtime.api) || null;
     }
   }
-  return components;
+  return runtimes;
 }
 
 /**
@@ -460,17 +461,18 @@ export function resolveRuntimeTopology(graph, options = {}) {
   if (!validation.ok) {
     throw new Error(validation.errors.map((error) => error.message).join("\n"));
   }
-  const components = decorateComponents(graph, config);
-  const apiComponents = components.filter((component) => component.type === "api");
-  const webComponents = components.filter((component) => component.type === "web");
-  const dbComponents = components.filter((component) => component.type === "database");
+  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;
 
   return {
     config,
-    components,
+    runtimes,
+    components: runtimes,
     apiComponents,
     webComponents,
     dbComponents,

package/src/generator/runtime/smoke.js

@@ -26,11 +26,11 @@ function buildRuntimeSmokePlan(graph, options = {}) {
       ui: uiProjection.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 } : {}),

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

@@ -16,7 +16,7 @@ export function generateDbContractDebug(graph, options = {}) {
   for (const contract of contracts) {
     lines.push(`## \`${contract.projection.id}\` - ${contract.projection.name}`);
     lines.push("");
-    lines.push(`Platform: \`${contract.projection.platform}\``);
+    lines.push(`Type: \`${contract.projection.type}\``);
     lines.push(`Profile: \`${contract.profile}\``);
     lines.push("");
 

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

@@ -80,15 +80,16 @@ function dbLifecyclePlan(graph, projection, options = {}) {
 }
 
 function renderEmptySnapshotForProjection(projection) {
-  const engine = projection.platform === "db_sqlite" ? "sqlite" : "postgres";
+  const profile = dbProfileForProjection(projection);
+  const engine = profile.startsWith("sqlite") ? "sqlite" : "postgres";
   return {
     type: "db_schema_snapshot",
     projection: {
       id: projection.id,
       name: projection.name || projection.id,
-      platform: projection.platform
+      type: projection.type || projection.platform
     },
-    profile: dbProfileForProjection(projection),
+    profile,
     generatorDefaults: generatorDefaultsMap(projection),
     engine,
     enums: [],
@@ -97,7 +98,7 @@ function renderEmptySnapshotForProjection(projection) {
 }
 
 function renderDbLifecycleEnvExample(projection, plan) {
-  const engine = projection.platform === "db_sqlite" ? "sqlite" : "postgres";
+  const engine = plan.engine || (dbProfileForProjection(projection).startsWith("sqlite") ? "sqlite" : "postgres");
   const inputPath = "../../../../topogram";
   if (engine === "sqlite") {
     return `DATABASE_URL=file:./var/${projection.id}.sqlite\nTOPOGRAM_INPUT_PATH=${inputPath}\n`;
@@ -580,7 +581,7 @@ function generateDbLifecycleBundle(graph, projection, options = {}) {
 
   if (plan.bundle.prismaSchema) {
     files[plan.bundle.prismaSchema] =
-      projection.platform === "db_sqlite"
+      plan.engine === "sqlite"
         ? generateSqlitePrismaSchema(graph, { projectionId: projection.id })
         : generatePostgresPrismaSchema(graph, { projectionId: projection.id });
   }

package/src/generator/surfaces/databases/postgres/drizzle.js

@@ -50,8 +50,9 @@ function drizzleColumnBuilder(column, relation, targetTableVar) {
 export function generatePostgresDrizzleSchema(graph, options = {}) {
   resolvePostgresCapabilities(options.profileId);
   const projection = getProjection(graph, options.projectionId);
-  if (projection.platform !== "db_postgres") {
-    throw new Error(`Drizzle schema generation currently supports db_postgres projections only, found '${projection.platform}'`);
+  const projectionType = projection.type || projection.platform;
+  if (projectionType !== "db_contract") {
+    throw new Error(`Drizzle schema generation currently supports db_contract projections only, found '${projectionType}'`);
   }
 
   const contract = buildDbProjectionContract(graph, projection);

package/src/generator/surfaces/databases/postgres/prisma.js

@@ -40,8 +40,9 @@ function prismaDefaultForColumn(column, byId) {
 export function generatePostgresPrismaSchema(graph, options = {}) {
   resolvePostgresCapabilities(options.profileId);
   const projection = getProjection(graph, options.projectionId);
-  if (projection.platform !== "db_postgres") {
-    throw new Error(`Prisma schema generation currently supports db_postgres projections only, found '${projection.platform}'`);
+  const projectionType = projection.type || projection.platform;
+  if (projectionType !== "db_contract") {
+    throw new Error(`Prisma schema generation currently supports db_contract projections only, found '${projectionType}'`);
   }
 
   const byId = indexGraphStatements(graph);

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

@@ -42,6 +42,7 @@ export function indexGraphStatements(graph) {
 export function dbProjectionCandidates(graph) {
   return (graph.byKind.projection || []).filter(
     (projection) =>
+      (projection.type || projection.platform) === "db_contract" ||
       projection.platform?.startsWith("db_") ||
       (projection.dbTables || []).length > 0 ||
       (projection.dbColumns || []).length > 0 ||
@@ -66,7 +67,7 @@ export function generatorDefaultsMap(projection) {
 
 export function dbProfileForProjection(projection) {
   const defaults = generatorDefaultsMap(projection);
-  return defaults.profile || (projection.platform === "db_sqlite" ? "sqlite_sql" : "postgres_sql");
+  return defaults.profile || "postgres_sql";
 }
 
 function mergeDbKeys(entity, projection) {
@@ -277,7 +278,7 @@ export function buildDbProjectionContract(graph, projection) {
     projection: {
       id: projection.id,
       name: projection.name || projection.id,
-      platform: projection.platform
+      type: projection.type || projection.platform
     },
     profile: dbProfileForProjection(projection),
     generatorDefaults: generatorDefaultsMap(projection),

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

@@ -11,7 +11,7 @@ import {
 } from "./shared.js";
 
 export function normalizeDbSchemaSnapshot(contract, byId = null) {
-  const engine = contract.projection.platform === "db_sqlite" ? "sqlite" : "postgres";
+  const engine = contract.profile?.startsWith("sqlite") ? "sqlite" : "postgres";
   const tables = [...contract.tables]
     .map((table) => ({
       table: table.table,

package/src/generator/surfaces/databases/sqlite/prisma.js

@@ -45,8 +45,9 @@ function prismaDefaultForColumn(column) {
 export function generateSqlitePrismaSchema(graph, options = {}) {
   resolveSqliteCapabilities(options.profileId);
   const projection = getProjection(graph, options.projectionId);
-  if (projection.platform !== "db_sqlite") {
-    throw new Error(`Prisma schema generation currently supports db_sqlite projections only, found '${projection.platform}'`);
+  const projectionType = projection.type || projection.platform;
+  if (projectionType !== "db_contract") {
+    throw new Error(`Prisma schema generation currently supports db_contract projections only, found '${projectionType}'`);
   }
 
   const byId = indexGraphStatements(graph);

package/src/generator/surfaces/native/swiftui-app.js

@@ -8,13 +8,13 @@ import { pickDefaultIosUiProjection, pickDefaultUiWebProjection } from "../../ru
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /**
- * Emits a SwiftPM iOS SwiftUI app driven by the routed UI contract (default: `proj_ui_native__ios` when present, else first `proj_ui_web__*` projection).
+ * Emits a SwiftPM iOS SwiftUI app driven by the routed UI contract (default: `proj_ios_surface__swiftui` when present, else first `proj_web_surface__*` projection).
  */
 export function generateSwiftUiApp(graph, options = {}) {
   const fallbackId =
     pickDefaultIosUiProjection(graph)?.id ||
     pickDefaultUiWebProjection(graph)?.id ||
-    "proj_ui_web__sveltekit";
+    "proj_web_surface__sveltekit";
   const projectionId = options.projectionId || fallbackId;
   const realization = buildWebRealization(graph, { projectionId });
   const apiContracts = realization.apiContracts;
@@ -31,7 +31,7 @@ export function generateSwiftUiApp(graph, options = {}) {
 
   files["Package.swift"] = fs.readFileSync(path.join(__dirname, "swiftui-templates", "Package.swift.txt"), "utf8");
   files["README.md"] = fs.readFileSync(path.join(__dirname, "swiftui-templates", "README.generated.md"), "utf8");
-  files["Sources/TodoSwiftUIApp/Resources/ui-web-contract.json"] = contractJson;
+  files["Sources/TodoSwiftUIApp/Resources/ui-surface-contract.json"] = contractJson;
   files["Sources/TodoSwiftUIApp/Resources/api-contracts.json"] = apiJson;
 
   return files;

package/src/generator/surfaces/native/swiftui-templates/Package.swift.txt

@@ -13,7 +13,7 @@ let package = Package(
             path: "Sources/TodoSwiftUIApp",
             resources: [
                 .copy("Resources/api-contracts.json"),
-                .copy("Resources/ui-web-contract.json")
+                .copy("Resources/ui-surface-contract.json")
             ]
         )
     ]

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

@@ -1,10 +1,10 @@
 # Todo SwiftUI (generated)
 
-Apple SwiftUI client generated from the same **`buildWebRealization`** routed UI contract as the web stacks. Prefer the **`proj_ui_native__ios`** projection when present; otherwise the generator falls back to a **`proj_ui_web__*`** projection (often **`proj_ui_web__sveltekit`**).
+Apple SwiftUI client generated from the same **`buildWebRealization`** routed UI contract as the web stacks. Prefer the **`proj_ios_surface__swiftui`** projection when present; otherwise the generator falls back to a **`proj_web_surface__*`** projection (often **`proj_web_surface__sveltekit`**).
 
 ## Bundle inputs
 
-- **`Resources/ui-web-contract.json`** — same shape as `apps/web/src/lib/topogram/ui-web-contract.json`
+- **`Resources/ui-surface-contract.json`** — same shape as `apps/web/src/lib/topogram/ui-surface-contract.json`
 - **`Resources/api-contracts.json`** — same shape as `apps/web/src/lib/topogram/api-contracts.json`
 
 ## Run
@@ -22,5 +22,5 @@ Configure the API base URL and demo auth token via scheme environment variables
 From `engine/`:
 
 ```bash
-topogram ./topogram --generate swiftui-app --projection proj_ui_native__ios --write --out-dir ./app/ios-swiftui
+topogram ./topogram --generate swiftui-app --projection proj_ios_surface__swiftui --write --out-dir ./app/ios-swiftui
 ```

package/src/generator/surfaces/native/swiftui-templates/runtime/DynamicScreens.swift

@@ -1,6 +1,6 @@
 import SwiftUI
 
-/// Holds decoded ui-web-contract.json for runtime-driven navigation (parity with web bundle).
+/// Holds decoded ui-surface-contract.json for runtime-driven navigation (parity with web bundle).
 public final class TodoUiContract: ObservableObject {
     public let raw: [String: Any]
 
@@ -12,9 +12,9 @@ public final class TodoUiContract: ObservableObject {
     }
 
     public static func loadBundled() throws -> Data {
-        guard let url = Bundle.module.url(forResource: "ui-web-contract", withExtension: "json"),
+        guard let url = Bundle.module.url(forResource: "ui-surface-contract", withExtension: "json"),
               let data = try? Data(contentsOf: url) else {
-            throw NSError(domain: "TodoUiContract", code: 2, userInfo: [NSLocalizedDescriptionKey: "Missing ui-web-contract.json"])
+            throw NSError(domain: "TodoUiContract", code: 2, userInfo: [NSLocalizedDescriptionKey: "Missing ui-surface-contract.json"])
         }
         return data
     }

package/src/generator/surfaces/services/persistence-wiring.js

@@ -155,8 +155,9 @@ export function generatePersistenceScaffold(graph, options = {}) {
   const drizzleRepositoryClassName = repositoryReference.drizzleRepositoryClassName;
   const drizzleHint = repositoryReference.drizzleHint;
   const projection = getProjection(graph, options.projectionId);
-  if (!["db_postgres", "db_sqlite"].includes(projection.platform)) {
-    throw new Error(`Persistence scaffold generation currently supports db_postgres and db_sqlite projections only, found '${projection.platform}'`);
+  const projectionType = projection.type || projection.platform;
+  if (projectionType !== "db_contract") {
+    throw new Error(`Persistence scaffold generation currently supports db_contract projections only, found '${projectionType}'`);
   }
 
   const byId = indexStatements(graph);

package/src/generator/surfaces/services/server-contract.js

@@ -11,7 +11,7 @@ function indexStatements(graph) {
 }
 
 function apiProjectionCandidates(graph) {
-  return (graph.byKind.projection || []).filter((projection) => (projection.http || []).length > 0);
+  return (graph.byKind.projection || []).filter((projection) => (projection.http || projection.endpoints || []).length > 0);
 }
 
 function repositoryMethodName(capabilityId) {
@@ -30,7 +30,7 @@ function buildServerContract(graph, projection) {
     projection: {
       id: projection.id,
       name: projection.name || projection.id,
-      platform: projection.platform
+      type: projection.type || projection.platform
     },
     routes: realizedCapabilities.map((capability) => {
       const apiContract = generateApiContractGraph(graph, { capabilityId: capability.id });
@@ -50,8 +50,8 @@ function buildServerContract(graph, projection) {
           preconditions: apiContract.endpoint.preconditions || [],
           idempotency: apiContract.endpoint.idempotency || [],
           cache: apiContract.endpoint.cache || [],
-          async: apiContract.endpoint.async || [],
-          status: apiContract.endpoint.status || [],
+          asyncJobs: apiContract.endpoint.async || [],
+          asyncStatus: apiContract.endpoint.status || [],
           download: apiContract.endpoint.download || []
         }
       };

package/src/generator/surfaces/shared.js

@@ -1,8 +1,8 @@
 export const APP_TARGETS = new Set([
   "ui-contract-graph",
   "ui-contract-debug",
-  "ui-web-contract",
-  "ui-web-debug",
+  "ui-surface-contract",
+  "ui-surface-debug",
   "sveltekit-app",
   "server-contract",
   "persistence-scaffold",

package/src/generator/surfaces/web/design-intent.js

@@ -262,7 +262,7 @@ function requiredDesignMarkers(design) {
  * @returns {{ coverage: any, diagnostics: any[] }}
  */
 export function buildDesignIntentCoverage(contract, files, cssPath) {
-  const design = normalizeDesignIntent(contract?.design);
+  const design = normalizeDesignIntent(contract?.designTokens);
   const css = files[cssPath] || "";
   const markers = requiredDesignMarkers(design);
   const mapped = markers.filter((item) => css.includes(item.marker));

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

@@ -9,9 +9,9 @@ import { generateReactApp } from "./react.js";
 import { generateSvelteKitApp } from "./sveltekit.js";
 import { generateVanillaWebApp } from "./vanilla.js";
 import {
-  generateUiWebContract,
-  generateUiWebDebug
-} from "./ui-web-contract.js";
+  generateUiSurfaceContract,
+  generateUiSurfaceDebug
+} from "./ui-surface-contract.js";
 
 export function generateWebApp(graph, options = {}) {
   const projection = getProjection(graph, options.projectionId);
@@ -39,11 +39,11 @@ export function generateWebTarget(target, graph, options = {}) {
   if (target === "ui-contract-debug") {
     return generateUiContractDebug(graph, options);
   }
-  if (target === "ui-web-contract") {
-    return generateUiWebContract(graph, options);
+  if (target === "ui-surface-contract") {
+    return generateUiSurfaceContract(graph, options);
   }
-  if (target === "ui-web-debug") {
-    return generateUiWebDebug(graph, options);
+  if (target === "ui-surface-debug") {
+    return generateUiSurfaceDebug(graph, options);
   }
   if (target === "sveltekit-app") {
     return generateWebApp(graph, options);