@topogram/cli 0.3.34

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

@@ -0,0 +1,97 @@
+// @ts-check
+
+import { getProjection } from "../shared.js";
+
+function renderPackageJson(profile) {
+  const dependencies = profile === "express"
+    ? { express: "^5.1.0" }
+    : { hono: "^4.6.14", "@hono/node-server": "^1.13.7" };
+  const devDependencies = profile === "express"
+    ? { "@types/express": "^5.0.0", "@types/node": "^22.10.2", tsx: "^4.19.2", typescript: "^5.6.3" }
+    : { "@types/node": "^22.10.2", tsx: "^4.19.2", typescript: "^5.6.3" };
+  return `${JSON.stringify({
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "tsx src/index.ts",
+      check: "tsc --noEmit",
+      start: "node dist/index.js"
+    },
+    dependencies,
+    devDependencies
+  }, null, 2)}\n`;
+}
+
+function renderTsconfig() {
+  return `${JSON.stringify({
+    compilerOptions: {
+      target: "ES2022",
+      module: "NodeNext",
+      moduleResolution: "NodeNext",
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      outDir: "dist"
+    },
+    include: ["src/**/*.ts"]
+  }, null, 2)}\n`;
+}
+
+function routePath(path) {
+  return String(path || "/").replace(/:([A-Za-z0-9_]+)/g, ":$1");
+}
+
+function renderHonoIndex(projection) {
+  const routes = (projection.http || []).map((route) => {
+    const method = String(route.method || "GET").toLowerCase();
+    return `app.${method}("${routePath(route.path)}", (c) => c.json({ ok: true, capability: "${route.capabilityId}", input: { params: c.req.param(), query: c.req.query() } }, ${route.success || 200} as any));`;
+  }).join("\n");
+  return `import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+
+const app = new Hono();
+
+app.get("/health", (c) => c.json({ ok: true, service: "${projection.id}" }));
+app.get("/ready", (c) => c.json({ ok: true, ready: true, service: "${projection.id}" }));
+${routes}
+
+const port = Number(process.env.PORT || 3000);
+serve({ fetch: app.fetch, port });
+console.log(\`${projection.id} listening on http://localhost:\${port}\`);
+`;
+}
+
+function expressPath(path) {
+  return routePath(path);
+}
+
+function renderExpressIndex(projection) {
+  const routes = (projection.http || []).map((route) => {
+    const method = String(route.method || "GET").toLowerCase();
+    return `app.${method}("${expressPath(route.path)}", (req, res) => res.status(${route.success || 200}).json({ ok: true, capability: "${route.capabilityId}", input: { params: req.params, query: req.query } }));`;
+  }).join("\n");
+  return `import express from "express";
+
+const app = express();
+app.use(express.json());
+
+app.get("/health", (_req, res) => res.json({ ok: true, service: "${projection.id}" }));
+app.get("/ready", (_req, res) => res.json({ ok: true, ready: true, service: "${projection.id}" }));
+${routes}
+
+const port = Number(process.env.PORT || 3000);
+app.listen(port, () => {
+  console.log(\`${projection.id} listening on http://localhost:\${port}\`);
+});
+`;
+}
+
+export function generateStatelessServer(graph, options = {}) {
+  const projection = getProjection(graph, options.projectionId);
+  const profile = options.profile === "express" ? "express" : "hono";
+  return {
+    "package.json": renderPackageJson(profile),
+    "tsconfig.json": renderTsconfig(),
+    "src/index.ts": profile === "express" ? renderExpressIndex(projection) : renderHonoIndex(projection)
+  };
+}

package/src/generator/surfaces/shared.js

@@ -0,0 +1,64 @@
+export const APP_TARGETS = new Set([
+  "ui-contract-graph",
+  "ui-contract-debug",
+  "ui-web-contract",
+  "ui-web-debug",
+  "sveltekit-app",
+  "server-contract",
+  "persistence-scaffold",
+  "hono-server",
+  "express-server"
+]);
+
+function indexStatements(graph) {
+  const byId = new Map();
+  for (const statement of graph.statements) {
+    byId.set(statement.id, statement);
+  }
+  return byId;
+}
+
+export function getProjection(graph, projectionId) {
+  const byId = indexStatements(graph);
+  const projection = byId.get(projectionId);
+  if (!projection || projection.kind !== "projection") {
+    throw new Error(`No projection found with id '${projectionId}'`);
+  }
+  return projection;
+}
+
+export function uiProjectionCandidates(graph) {
+  return (graph.byKind.projection || []).filter(
+    (projection) =>
+      (projection.uiScreens || []).length > 0 ||
+      (projection.uiCollections || []).length > 0 ||
+      (projection.uiActions || []).length > 0 ||
+      (projection.uiVisibility || []).length > 0 ||
+      (projection.uiLookups || []).length > 0 ||
+      (projection.uiAppShell || []).length > 0 ||
+      (projection.uiNavigation || []).length > 0 ||
+      (projection.uiScreenRegions || []).length > 0 ||
+      (projection.uiComponents || []).length > 0
+  );
+}
+
+export function generatorDefaultsMap(projection) {
+  const defaults = {};
+  for (const entry of projection.generatorDefaults || []) {
+    if (entry.key && entry.value != null) {
+      defaults[entry.key] = entry.value;
+    }
+  }
+  return defaults;
+}
+
+export function sharedUiProjectionForWeb(graph, projection) {
+  const byId = indexStatements(graph);
+  for (const ref of projection.realizes || []) {
+    const target = byId.get(ref.id);
+    if (target?.kind === "projection" && (target.uiScreens || []).length > 0) {
+      return target;
+    }
+  }
+  return null;
+}

package/src/generator/surfaces/web/api-client.js

@@ -0,0 +1 @@
+export { generateSvelteKitApp as generateWebApiClient } from "./sveltekit.js";

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

@@ -0,0 +1 @@
+export { generateSvelteKitApp as generateWebForms } from "./sveltekit.js";

package/src/generator/surfaces/web/index.d.ts

@@ -0,0 +1,2 @@
+export function generateWebApp(graph: any, options?: any): any;
+export function generateWebTarget(target: string, graph: any, options?: any): any;

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

@@ -0,0 +1,53 @@
+import {
+  generateUiContractDebug,
+  generateUiContractGraph
+} from "../contracts.js";
+import { generatorDefaultsMap, getProjection } from "../shared.js";
+import { generateWithComponentGenerator } from "../../adapters.js";
+import { generatorProfile } from "../../registry.js";
+import { generateReactApp } from "./react.js";
+import { generateSvelteKitApp } from "./sveltekit.js";
+import { generateVanillaWebApp } from "./vanilla.js";
+import {
+  generateUiWebContract,
+  generateUiWebDebug
+} from "./ui-web-contract.js";
+
+export function generateWebApp(graph, options = {}) {
+  const projection = getProjection(graph, options.projectionId);
+  if (options.component?.generator?.id) {
+    return generateWithComponentGenerator({
+      graph,
+      projection,
+      component: options.component,
+      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";
+  if (profile === "vanilla") {
+    return generateVanillaWebApp(graph, options);
+  }
+  return profile === "react" ? generateReactApp(graph, options) : generateSvelteKitApp(graph, options);
+}
+
+export function generateWebTarget(target, graph, options = {}) {
+  if (target === "ui-contract-graph") {
+    return generateUiContractGraph(graph, options);
+  }
+  if (target === "ui-contract-debug") {
+    return generateUiContractDebug(graph, options);
+  }
+  if (target === "ui-web-contract") {
+    return generateUiWebContract(graph, options);
+  }
+  if (target === "ui-web-debug") {
+    return generateUiWebDebug(graph, options);
+  }
+  if (target === "sveltekit-app") {
+    return generateWebApp(graph, options);
+  }
+
+  throw new Error(`Unsupported web generator target '${target}'`);
+}

package/src/generator/surfaces/web/react-components.js

@@ -0,0 +1,248 @@
+// @ts-check
+
+/**
+ * @typedef {{ id?: string, name?: string }} ComponentReference
+ * @typedef {{ component?: ComponentReference, region?: string }} ComponentUsage
+ * @typedef {{ patterns?: string[] }} ComponentContract
+ * @typedef {Record<string, ComponentContract>} ComponentContractMap
+ * @typedef {{ itemsExpression?: string, componentContracts?: ComponentContractMap, useTypescript?: boolean }} RenderOptions
+ * @typedef {{ components?: ComponentUsage[] }} ScreenContract
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function escapeAttribute(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function escapeText(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @returns {string}
+ */
+function componentName(usage) {
+  return usage?.component?.name || usage?.component?.id || "Component";
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @returns {string}
+ */
+function componentId(usage) {
+  return usage?.component?.id || "component";
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {ComponentContractMap | undefined} componentContracts
+ * @returns {string[]}
+ */
+function componentPatterns(usage, componentContracts) {
+  const id = usage?.component?.id;
+  const contract = id ? componentContracts?.[id] : null;
+  return Array.isArray(contract?.patterns) ? contract.patterns : [];
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {ComponentContractMap | undefined} componentContracts
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function hasPattern(usage, componentContracts, pattern) {
+  return componentPatterns(usage, componentContracts).includes(pattern);
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderSummaryStats(usage, options) {
+  const items = options.itemsExpression || "items";
+  return `<section className="component-card component-summary" data-topogram-component="${escapeAttribute(componentId(usage))}">
+          <div>
+            <p className="component-eyebrow">Component</p>
+            <h2>${escapeText(componentName(usage))}</h2>
+          </div>
+          <div className="summary-grid">
+            <div>
+              <strong>{${items}.length}</strong>
+              <span>Total</span>
+            </div>
+            <div>
+              <strong>{Object.keys(${items}[0] ?? {}).length}</strong>
+              <span>Fields</span>
+            </div>
+            <div>
+              <strong>{${items}.filter((item: any) => item && (item.id ?? item.uuid ?? item.key)).length}</strong>
+              <span>Identified</span>
+            </div>
+          </div>
+        </section>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderCollectionTable(usage, options) {
+  const items = options.itemsExpression || "items";
+  const itemParam = options.useTypescript ? "(item: any)" : "(item)";
+  return `<div className="component-card component-table" data-topogram-component="${escapeAttribute(componentId(usage))}">
+          <div className="component-header">
+            <div>
+              <p className="component-eyebrow">Component</p>
+              <h2>${escapeText(componentName(usage))}</h2>
+            </div>
+            <span className="badge">{${items}.length} items</span>
+          </div>
+          <div className="table-wrap component-table-wrap">
+            <table className="resource-table data-grid">
+              <thead>
+                <tr>
+                  {Object.keys(${items}[0] ?? {}).slice(0, 4).map((field) => (
+                    <th key={field}>{field}</th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {${items}.map(${itemParam} => (
+                  <tr key={String(item.id ?? item.title ?? item.name ?? item.message)}>
+                    {Object.keys(${items}[0] ?? {}).slice(0, 4).map((field) => (
+                      <td key={field}>{String(item?.[field] ?? "")}</td>
+                    ))}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderBoard(usage, options) {
+  const items = options.itemsExpression || "items";
+  const itemParam = options.useTypescript ? "(item: any)" : "(item)";
+  return `<div className="component-card component-board" data-topogram-component="${escapeAttribute(componentId(usage))}">
+          <div className="component-header">
+            <div>
+              <p className="component-eyebrow">Component</p>
+              <h2>${escapeText(componentName(usage))}</h2>
+            </div>
+          </div>
+          <div className="board-grid">
+            {Array.from(new Set(${items}.map((item: any) => item?.status ?? item?.state ?? item?.stage ?? item?.category ?? "items"))).map((group) => (
+              <section className="board-column" key={String(group)}>
+                <h3>{String(group)}</h3>
+                {${items}.filter(${itemParam} => (item?.status ?? item?.state ?? item?.stage ?? item?.category ?? "items") === group).map(${itemParam} => (
+                  <div className="board-card" key={String(item.id ?? item.title ?? item.name)}>
+                    {item.title ?? item.name ?? item.label ?? item.message ?? item.id ?? JSON.stringify(item)}
+                  </div>
+                ))}
+              </section>
+            ))}
+          </div>
+        </div>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderCalendar(usage, options) {
+  const items = options.itemsExpression || "items";
+  const itemParam = options.useTypescript ? "(item: any)" : "(item)";
+  return `<div className="component-card component-calendar" data-topogram-component="${escapeAttribute(componentId(usage))}">
+          <div className="component-header">
+            <div>
+              <p className="component-eyebrow">Component</p>
+              <h2>${escapeText(componentName(usage))}</h2>
+            </div>
+          </div>
+          <div className="calendar-list">
+            {${items}.filter(${itemParam} => item.date || item.due_at || item.dueAt || item.created_at || item.createdAt || item.updated_at || item.updatedAt).map(${itemParam} => (
+              <div className="calendar-card" key={String(item.id ?? item.title ?? item.name)}>
+                <span>{item.date ?? item.due_at ?? item.dueAt ?? item.created_at ?? item.createdAt ?? item.updated_at ?? item.updatedAt}</span>
+                <strong>{item.title ?? item.name ?? item.label ?? item.message ?? item.id ?? JSON.stringify(item)}</strong>
+              </div>
+            ))}
+          </div>
+        </div>`;
+}
+
+/**
+ * @param {ComponentUsage} usage
+ * @param {RenderOptions} options
+ * @returns {string}
+ */
+function renderUsage(usage, options) {
+  const componentContracts = options.componentContracts || {};
+  if (hasPattern(usage, componentContracts, "summary_stats")) {
+    return renderSummaryStats(usage, options);
+  }
+  if (hasPattern(usage, componentContracts, "board_view")) {
+    return renderBoard(usage, options);
+  }
+  if (hasPattern(usage, componentContracts, "calendar_view")) {
+    return renderCalendar(usage, options);
+  }
+  if (hasPattern(usage, componentContracts, "resource_table") || hasPattern(usage, componentContracts, "data_grid_view")) {
+    return renderCollectionTable(usage, options);
+  }
+  return "";
+}
+
+/**
+ * @param {ScreenContract} screen
+ * @param {string} region
+ * @returns {ComponentUsage[]}
+ */
+export function reactComponentUsagesForRegion(screen, region) {
+  return (screen?.components || []).filter((usage) => usage?.region === region);
+}
+
+/**
+ * @param {ScreenContract} screen
+ * @param {string} region
+ * @returns {boolean}
+ */
+export function hasReactComponentRegion(screen, region) {
+  return reactComponentUsagesForRegion(screen, region).length > 0;
+}
+
+/**
+ * @param {ScreenContract} screen
+ * @param {string} region
+ * @param {RenderOptions} [options]
+ * @returns {string}
+ */
+export function renderReactComponentRegion(screen, region, options = {}) {
+  const rendered = reactComponentUsagesForRegion(screen, region)
+    .map((usage) => renderUsage(usage, options))
+    .filter(Boolean);
+  if (rendered.length === 0) {
+    return "";
+  }
+  return rendered.join("\n");
+}