@topogram/cli 0.3.34

package/src/component-behavior.js

@@ -0,0 +1,173 @@
+function asArray(value) {
+  if (Array.isArray(value)) {
+    return value.filter(Boolean);
+  }
+  return value == null ? [] : [value];
+}
+
+function propByName(contract) {
+  return new Map((contract?.props || []).map((prop) => [prop.name, prop]));
+}
+
+function bindingSourceForProp(usage, propName) {
+  return (usage?.dataBindings || []).find((binding) => binding.prop === propName)?.source || null;
+}
+
+function effectFromEventBinding(binding) {
+  if (binding.action === "navigate") {
+    return {
+      type: "navigation",
+      event: binding.event || null,
+      target: binding.target || null
+    };
+  }
+  if (binding.action === "action") {
+    return {
+      type: "command",
+      event: binding.event || null,
+      capability: binding.target || null
+    };
+  }
+  return {
+    type: "unknown",
+    event: binding.event || null,
+    action: binding.action || null,
+    target: binding.target || null
+  };
+}
+
+function uniqueEffects(effects) {
+  const seen = new Set();
+  const output = [];
+  for (const effect of effects) {
+    const key = JSON.stringify(effect);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    output.push(effect);
+  }
+  return output;
+}
+
+function eventRealizations(usage, eventNames) {
+  const bindings = usage?.eventBindings || [];
+  return eventNames.map((eventName) => {
+    const matchingBindings = bindings.filter((binding) => binding.event === eventName);
+    return {
+      event: eventName,
+      bound: matchingBindings.length > 0,
+      bindings: matchingBindings.map((binding) => ({
+        event: binding.event || null,
+        action: binding.action || null,
+        target: binding.target || null
+      })),
+      effects: matchingBindings.map(effectFromEventBinding)
+    };
+  });
+}
+
+function capabilityActionRealization(usage, capabilityId) {
+  const bindings = (usage?.eventBindings || [])
+    .filter((binding) =>
+      binding.action === "action" &&
+      binding.target?.kind === "capability" &&
+      binding.target?.id === capabilityId
+    );
+  const capability = {
+    id: capabilityId,
+    kind: "capability"
+  };
+  return {
+    event: null,
+    capability,
+    bound: bindings.length > 0,
+    bindings: bindings.map((binding) => ({
+      event: binding.event || null,
+      action: binding.action || null,
+      target: binding.target || null
+    })),
+    effects: bindings.length > 0
+      ? bindings.map(effectFromEventBinding)
+      : [{
+          type: "command",
+          event: null,
+          capability,
+          source: "behavior"
+        }]
+  };
+}
+
+function actionRealizations(usage, actionNames, eventNames) {
+  return actionNames.map((actionName) => {
+    if (eventNames.has(actionName)) {
+      return eventRealizations(usage, [actionName])[0];
+    }
+    return capabilityActionRealization(usage, actionName);
+  });
+}
+
+function behaviorStatus({ hasDirectives, state, emits }) {
+  const hasMissingEventBinding = emits.some((entry) => !entry.bound);
+  if (hasMissingEventBinding) {
+    return "partial";
+  }
+  if (state?.requiredness === "required" && !state.bound) {
+    return "partial";
+  }
+  return hasDirectives ? "realized" : "declared";
+}
+
+/**
+ * Build projection-specific realizations for component behavior contracts.
+ *
+ * Components declare reusable behavior capabilities; projection ui_components
+ * bindings provide concrete data/event outcomes. This derived contract is the
+ * normalized bridge agents and generators can use without inferring behavior
+ * from stack code.
+ *
+ * @param {Record<string, any>|null} contract
+ * @param {Record<string, any>} usage
+ * @returns {Array<Record<string, any>>}
+ */
+export function buildComponentBehaviorRealizations(contract, usage) {
+  const props = propByName(contract);
+  const eventNames = new Set((contract?.events || []).map((event) => event.id).filter(Boolean));
+  return (contract?.behaviors || []).map((behavior) => {
+    const directives = behavior.directives || {};
+    const statePropName = directives.state || null;
+    const stateProp = statePropName ? props.get(statePropName) || null : null;
+    const state = statePropName
+      ? {
+          prop: statePropName,
+          requiredness: stateProp?.requiredness || null,
+          bound: Boolean(bindingSourceForProp(usage, statePropName)),
+          source: bindingSourceForProp(usage, statePropName),
+          defaultValue: stateProp?.defaultValue ?? null
+        }
+      : null;
+    const emits = eventRealizations(usage, asArray(directives.emits));
+    const actions = actionRealizations(usage, [
+      ...asArray(directives.actions),
+      ...asArray(directives.submit)
+    ], eventNames);
+    const dataDependencies = (usage?.dataBindings || []).map((binding) => ({
+      prop: binding.prop || null,
+      source: binding.source || null
+    }));
+    const effects = uniqueEffects([...emits, ...actions].flatMap((entry) => entry.effects));
+    const hasDirectives = Object.keys(directives).length > 0;
+
+    return {
+      kind: behavior.kind || null,
+      source: behavior.source || null,
+      directives: { ...directives },
+      state,
+      emits,
+      actions,
+      dataDependencies,
+      effects,
+      status: behaviorStatus({ hasDirectives, state, emits: [...emits, ...actions] })
+    };
+  });
+}

package/src/example-implementation.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  findLegacyImplementationConfig,
+  findProjectConfig
+} from "./project-config.js";
+import { assertTrustedImplementation } from "./template-trust.js";
+
+function normalizeRoot(root) {
+  return String(root || "").replace(/\\/g, "/");
+}
+
+function normalizeSearchRoot(root) {
+  if (!root) {
+    return null;
+  }
+  const absolute = path.resolve(root);
+  try {
+    return fs.realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+function implementationProviderError(root) {
+  const suffix = root ? ` for ${normalizeRoot(root)}` : "";
+  return new Error(
+    `Topogram app/runtime generation requires an explicit implementation provider${suffix}. ` +
+      "Add topogram.project.json with implementation.module, or pass an implementation provider in generator options."
+  );
+}
+
+export function findImplementationConfig(root) {
+  const projectConfig = findProjectConfig(root);
+  if (projectConfig?.config?.implementation) {
+    return {
+      config: projectConfig.config.implementation,
+      configPath: projectConfig.configPath,
+      configDir: projectConfig.configDir
+    };
+  }
+  return findLegacyImplementationConfig(root);
+}
+
+export function getExampleImplementation(graph, options = {}) {
+  const implementation = options.implementation || options.implementationProvider || null;
+  if (implementation) {
+    return implementation;
+  }
+  throw implementationProviderError(graph?.root);
+}
+
+export async function loadImplementationProvider(root) {
+  const found = findImplementationConfig(root);
+  if (!found) {
+    throw implementationProviderError(root);
+  }
+
+  const { config, configPath, configDir } = found;
+  const projectConfig = findProjectConfig(root)?.config || null;
+  assertTrustedImplementation(found, projectConfig);
+  const implementationModule = config.implementation_module || config.module;
+  if (!implementationModule) {
+    throw new Error(
+      `Topogram implementation config ${normalizeRoot(configPath)} is missing implementation module.`
+    );
+  }
+
+  const modulePath = path.resolve(configDir, implementationModule);
+  const module = await import(pathToFileURL(modulePath).href);
+  const exportName = config.implementation_export || config.export || "default";
+  const implementation = module[exportName];
+  if (!implementation) {
+    throw new Error(
+      `Topogram implementation module ${normalizeRoot(modulePath)} does not export '${exportName}'.`
+    );
+  }
+  if (
+    (config.implementation_id || config.id) &&
+    implementation.exampleId &&
+    implementation.exampleId !== (config.implementation_id || config.id)
+  ) {
+    throw new Error(
+      `Topogram implementation config requested '${config.implementation_id || config.id}', ` +
+        `but provider exported '${implementation.exampleId}'.`
+    );
+  }
+  return implementation;
+}

package/src/format.js

@@ -0,0 +1,19 @@
+export function stableStringify(value) {
+  return JSON.stringify(sortValue(value), null, 2);
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortValue);
+  }
+
+  if (value && typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = sortValue(value[key]);
+    }
+    return sorted;
+  }
+
+  return value;
+}

package/src/generator/adapters.d.ts

@@ -0,0 +1,4 @@
+export const BUNDLED_GENERATOR_ADAPTERS: any[];
+export function getBundledGeneratorAdapter(generatorId: string): any;
+export function resolveGeneratorForComponent(component: any, options?: { rootDir?: string | null; configDir?: string | null }): { manifest: any; adapter: any };
+export function generateWithComponentGenerator(context: any): { files: Record<string, string>; artifacts?: any; diagnostics?: any[] };

package/src/generator/adapters.js

@@ -0,0 +1,325 @@
+// @ts-check
+
+import path from "node:path";
+import { createRequire } from "node:module";
+
+import { generateApiContractGraph } from "./api.js";
+import {
+  getGeneratorManifest,
+  packageGeneratorInstallHint,
+  resolveGeneratorManifestForBinding,
+  validateGeneratorManifest
+} from "./registry.js";
+import { generateDbContractGraph } from "./surfaces/databases/contract.js";
+import { generateDbLifecyclePlan } from "./surfaces/databases/lifecycle-shared.js";
+import {
+  generatePostgresDbLifecycleBundle
+} from "./surfaces/databases/postgres/index.js";
+import {
+  generateSqliteDbLifecycleBundle
+} from "./surfaces/databases/sqlite/index.js";
+import { generateSwiftUiApp } from "./surfaces/native/swiftui-app.js";
+import { generateExpressServer } from "./surfaces/services/express.js";
+import { generateHonoServer } from "./surfaces/services/hono.js";
+import { generateServerContract } from "./surfaces/services/server-contract.js";
+import { generateStatelessServer } from "./surfaces/services/stateless.js";
+import { generateReactApp } from "./surfaces/web/react.js";
+import { generateSvelteKitApp } from "./surfaces/web/sveltekit.js";
+import { generateUiWebContract } from "./surfaces/web/ui-web-contract.js";
+import { generateVanillaWebApp } from "./surfaces/web/vanilla.js";
+
+/**
+ * @typedef {import("./registry.js").GeneratorManifest} GeneratorManifest
+ */
+
+/**
+ * @typedef {Object} GeneratorContext
+ * @property {Record<string, any>} graph
+ * @property {Record<string, any>} projection
+ * @property {Record<string, any>} component
+ * @property {Record<string, any>|null} [topology]
+ * @property {Record<string, any>} [contracts]
+ * @property {Record<string, any>|null} [implementation]
+ * @property {Record<string, any>} [options]
+ * @property {GeneratorManifest} [manifest]
+ */
+
+/**
+ * @typedef {Object} GeneratorResult
+ * @property {Record<string, string>} files
+ * @property {Record<string, any>} [artifacts]
+ * @property {Array<Record<string, any>>} [diagnostics]
+ */
+
+/**
+ * @typedef {Object} GeneratorAdapter
+ * @property {GeneratorManifest} manifest
+ * @property {(context: GeneratorContext) => GeneratorResult} generate
+ */
+
+/**
+ * @param {Record<string, string>} files
+ * @param {Record<string, any>} [artifacts]
+ * @returns {GeneratorResult}
+ */
+function fileResult(files, artifacts = {}) {
+  return { files, artifacts, diagnostics: [] };
+}
+
+/**
+ * @param {string} generatorId
+ * @returns {GeneratorManifest}
+ */
+function requiredManifest(generatorId) {
+  const manifest = getGeneratorManifest(generatorId);
+  if (!manifest) {
+    throw new Error(`Bundled generator '${generatorId}' is missing its manifest.`);
+  }
+  return manifest;
+}
+
+/**
+ * @param {GeneratorContext} context
+ * @returns {string}
+ */
+function projectionIdFor(context) {
+  return context.projection?.id || context.component?.projection?.id || context.options?.projectionId;
+}
+
+/**
+ * @param {GeneratorContext} context
+ * @param {string} profile
+ * @returns {Record<string, any>}
+ */
+function serverOptions(context, profile) {
+  const projectionId = projectionIdFor(context);
+  const dbProjectionId = context.component?.databaseComponent?.projection?.id || context.options?.dbProjectionId;
+  return {
+    ...(context.options || {}),
+    projectionId,
+    dbProjectionId,
+    component: context.component,
+    topology: context.topology,
+    contracts: context.contracts,
+    implementation: context.implementation,
+    profile
+  };
+}
+
+/**
+ * @param {GeneratorContext} context
+ * @returns {Record<string, any>}
+ */
+function commonOptions(context) {
+  return {
+    ...(context.options || {}),
+    projectionId: projectionIdFor(context),
+    component: context.component,
+    topology: context.topology,
+    contracts: context.contracts,
+    implementation: context.implementation
+  };
+}
+
+/**
+ * @param {GeneratorContext} context
+ * @returns {Record<string, any>}
+ */
+function buildContractsForContext(context) {
+  const projectionId = projectionIdFor(context);
+  if (context.component.type === "web") {
+    return {
+      uiWeb: generateUiWebContract(context.graph, { ...(context.options || {}), projectionId })
+    };
+  }
+  if (context.component.type === "api") {
+    return {
+      server: generateServerContract(context.graph, { ...(context.options || {}), projectionId }),
+      api: generateApiContractGraph(context.graph, {})
+    };
+  }
+  if (context.component.type === "database") {
+    return {
+      db: generateDbContractGraph(context.graph, { ...(context.options || {}), projectionId }),
+      lifecyclePlan: generateDbLifecyclePlan(context.graph, { ...(context.options || {}), projectionId })
+    };
+  }
+  if (context.component.type === "native") {
+    return {
+      uiWeb: generateUiWebContract(context.graph, { ...(context.options || {}), projectionId })
+    };
+  }
+  return {};
+}
+
+/** @type {GeneratorAdapter[]} */
+export const BUNDLED_GENERATOR_ADAPTERS = [
+  {
+    manifest: requiredManifest("topogram/hono"),
+    generate(context) {
+      if (context.component && !context.component.databaseComponent) {
+        return fileResult(generateStatelessServer(context.graph, serverOptions(context, "hono")));
+      }
+      return fileResult(generateHonoServer(context.graph, serverOptions(context, "hono")));
+    }
+  },
+  {
+    manifest: requiredManifest("topogram/express"),
+    generate(context) {
+      if (context.component && !context.component.databaseComponent) {
+        return fileResult(generateStatelessServer(context.graph, serverOptions(context, "express")));
+      }
+      return fileResult(generateExpressServer(context.graph, serverOptions(context, "express")));
+    }
+  },
+  {
+    manifest: requiredManifest("topogram/vanilla-web"),
+    generate(context) {
+      return fileResult(generateVanillaWebApp(context.graph, commonOptions(context)));
+    }
+  },
+  {
+    manifest: requiredManifest("topogram/sveltekit"),
+    generate(context) {
+      return fileResult(generateSvelteKitApp(context.graph, commonOptions(context)));
+    }
+  },
+  {
+    manifest: requiredManifest("topogram/react"),
+    generate(context) {
+      return fileResult(generateReactApp(context.graph, commonOptions(context)));
+    }
+  },
+  {
+    manifest: requiredManifest("topogram/swiftui"),
+    generate(context) {
+      return fileResult(generateSwiftUiApp(context.graph, commonOptions(context)));
+    }
+  },
+  {
+    manifest: requiredManifest("topogram/postgres"),
+    generate(context) {
+      return fileResult(generatePostgresDbLifecycleBundle(context.graph, commonOptions(context)));
+    }
+  },
+  {
+    manifest: requiredManifest("topogram/sqlite"),
+    generate(context) {
+      return fileResult(generateSqliteDbLifecycleBundle(context.graph, commonOptions(context)));
+    }
+  }
+];
+
+const ADAPTER_BY_ID = new Map(BUNDLED_GENERATOR_ADAPTERS.map((adapter) => [adapter.manifest.id, adapter]));
+
+/**
+ * @param {string} generatorId
+ * @returns {GeneratorAdapter|null}
+ */
+export function getBundledGeneratorAdapter(generatorId) {
+  return ADAPTER_BY_ID.get(generatorId) || null;
+}
+
+/**
+ * @param {string|null|undefined} rootDir
+ * @returns {any}
+ */
+function requireFromProject(rootDir) {
+  return createRequire(path.join(rootDir || process.cwd(), "package.json"));
+}
+
+/**
+ * @param {any} moduleValue
+ * @param {string|null|undefined} exportName
+ * @returns {any}
+ */
+function selectPackageExport(moduleValue, exportName) {
+  if (exportName) {
+    return moduleValue?.[exportName] || moduleValue?.default?.[exportName] || null;
+  }
+  return moduleValue?.default || moduleValue;
+}
+
+/**
+ * @param {GeneratorManifest} manifest
+ * @param {Record<string, any>} component
+ * @param {{ rootDir?: string|null, configDir?: string|null }} [options]
+ * @returns {GeneratorAdapter}
+ */
+function loadPackageGeneratorAdapter(manifest, component, options = {}) {
+  const packageName = manifest.package || component?.generator?.package;
+  if (!packageName) {
+    throw new Error(`Component '${component?.id || "unknown"}' generator '${manifest.id}@${manifest.version}' is package-backed but does not declare a package.`);
+  }
+  const rootDir = options.configDir || options.rootDir || process.cwd();
+  let moduleValue;
+  try {
+    moduleValue = requireFromProject(rootDir)(packageName);
+  } catch (error) {
+    const installHint = packageGeneratorInstallHint(packageName);
+    throw new Error(`Component '${component?.id || "unknown"}' generator package '${packageName}' could not be loaded from '${rootDir}': ${error instanceof Error ? error.message : String(error)}${installHint ? `. ${installHint}` : ""}`);
+  }
+  const adapter = selectPackageExport(moduleValue, manifest.export);
+  if (!adapter || typeof adapter.generate !== "function") {
+    throw new Error(`Component '${component?.id || "unknown"}' generator package '${packageName}' must export an adapter with a generate(context) function.`);
+  }
+  const adapterManifest = adapter.manifest || manifest;
+  if (adapterManifest.id !== manifest.id || adapterManifest.version !== manifest.version) {
+    throw new Error(`Component '${component?.id || "unknown"}' generator package '${packageName}' adapter manifest '${adapterManifest.id}@${adapterManifest.version}' does not match '${manifest.id}@${manifest.version}'.`);
+  }
+  return {
+    manifest,
+    generate(context) {
+      return adapter.generate(context);
+    }
+  };
+}
+
+/**
+ * @param {Record<string, any>} component
+ * @param {{ rootDir?: string|null, configDir?: string|null }} [options]
+ * @returns {{ manifest: GeneratorManifest, adapter: GeneratorAdapter }}
+ */
+export function resolveGeneratorForComponent(component, options = {}) {
+  const generatorId = component?.generator?.id;
+  const resolved = resolveGeneratorManifestForBinding(component?.generator, options);
+  const manifest = resolved.manifest || getGeneratorManifest(generatorId);
+  if (!manifest) {
+    const detail = resolved.errors.length > 0 ? ` ${resolved.errors.join(" ")}` : "";
+    throw new Error(`Component '${component?.id || "unknown"}' uses unknown generator '${generatorId || "unknown"}'.${detail}`);
+  }
+  if (manifest.planned) {
+    throw new Error(`Component '${component?.id || "unknown"}' uses planned generator '${manifest.id}', which is not implemented yet.`);
+  }
+  if (component.generator?.version !== manifest.version) {
+    throw new Error(`Component '${component?.id || "unknown"}' generator '${manifest.id}' version '${component.generator?.version}' is unsupported; expected '${manifest.version}'.`);
+  }
+  const manifestValidation = validateGeneratorManifest(manifest);
+  if (!manifestValidation.ok) {
+    throw new Error(manifestValidation.errors.join("\n"));
+  }
+  if (manifest.source === "package") {
+    return { manifest, adapter: loadPackageGeneratorAdapter(manifest, component, options) };
+  }
+  const adapter = getBundledGeneratorAdapter(manifest.id);
+  if (!adapter) {
+    const installHint = packageGeneratorInstallHint(component?.generator?.package || manifest.package);
+    throw new Error(`Component '${component?.id || "unknown"}' generator '${manifest.id}@${manifest.version}' is not available. Package-backed generators must be installed before generation.${installHint ? ` ${installHint}` : ""}`);
+  }
+  return { manifest, adapter };
+}
+
+/**
+ * @param {Omit<GeneratorContext, "contracts"> & { contracts?: Record<string, any> }} context
+ * @returns {GeneratorResult}
+ */
+export function generateWithComponentGenerator(context) {
+  const { manifest, adapter } = resolveGeneratorForComponent(context.component, context.options || {});
+  const contracts = context.contracts || buildContractsForContext(context);
+  return adapter.generate({
+    ...context,
+    projection: context.projection,
+    manifest,
+    contracts
+  });
+}

package/src/generator/api.d.ts

@@ -0,0 +1 @@
+export function generateApiContractGraph(graph: any, options?: any): any;