@topogram/cli 0.3.34

package/src/generator/surfaces/services/hono.d.ts

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

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

@@ -0,0 +1,204 @@
+import { generateDbTarget } from "../databases/index.js";
+import { buildBackendRuntimeRealization } from "../../../realization/backend/index.js";
+import { getProjection } from "../shared.js";
+import { generatePersistenceScaffold } from "./persistence-wiring.js";
+import {
+  renderServerContextTs,
+  renderServerHelpers,
+  renderServerIndexTs,
+  renderServerPackageJson,
+  renderServerSeedScript,
+  renderServerTsconfig,
+  routeTypeNames,
+} from "./runtime-helpers.js";
+import { generateServerContract, renderServerContractModule } from "./server-contract.js";
+import { toPascalCase } from "../databases/shared.js";
+
+function renderServerAppTs(realization) {
+  const { contract, lookupRoutes } = realization;
+  const lines = [];
+  const typeImportNames = routeTypeNames(contract);
+  const serviceName = realization.backendReference.serviceName;
+  const defaultWebPort = realization.runtimeReference?.ports?.web || 5173;
+  const repositoryReference = realization.repositoryReference;
+  const dependencyName = repositoryReference.dependencyName;
+  const preconditionCapabilityIds = repositoryReference.preconditionCapabilityIds;
+  const preconditionResource = repositoryReference.preconditionResource;
+  const preconditionVariableName = preconditionResource.variableName || "currentResource";
+  const downloadCapabilityId = repositoryReference.downloadCapabilityId;
+
+  lines.push('import { Hono } from "hono";');
+  lines.push('import { cors } from "hono/cors";');
+  lines.push('import type { Context } from "hono";');
+  lines.push('import { serverContract } from "../topogram/server-contract";');
+  lines.push('import { HttpError, coerceValue, contentDisposition, jsonError, requireHeaders, requireRequestFields } from "./helpers";');
+  lines.push('import type { ServerDependencies } from "./context";');
+  lines.push(`import type { ${typeImportNames.join(", ")} } from "../persistence/types";`);
+  lines.push("");
+  lines.push("function buildInput(c: Context, route: any, body: Record<string, unknown>) {");
+  lines.push("  const input: Record<string, unknown> = {};");
+  lines.push("  for (const field of (route.requestContract?.transport.path || []) as any[]) {");
+  lines.push("    input[field.name] = coerceValue(c.req.param(field.transport.wireName), field.schema);");
+  lines.push("  }");
+  lines.push("  for (const field of (route.requestContract?.transport.query || []) as any[]) {");
+  lines.push("    input[field.name] = coerceValue(c.req.query(field.transport.wireName), field.schema);");
+  lines.push("  }");
+  lines.push("  for (const field of (route.requestContract?.transport.header || []) as any[]) {");
+  lines.push("    input[field.name] = coerceValue(c.req.header(field.transport.wireName), field.schema);");
+  lines.push("  }");
+  lines.push("  for (const field of (route.requestContract?.transport.body || []) as any[]) {");
+  lines.push('    const defaultValue = field.schema && typeof field.schema === "object" && "default" in field.schema ? field.schema.default : undefined;');
+  lines.push("    input[field.name] = body[field.transport.wireName] ?? defaultValue;");
+  lines.push("  }");
+  lines.push("  return input;");
+  lines.push("}");
+  lines.push("");
+  lines.push("function corsOrigin(origin: string) {");
+  lines.push(`  const configured = process.env.TOPOGRAM_CORS_ORIGINS || "http://localhost:${defaultWebPort},http://127.0.0.1:${defaultWebPort}";`);
+  lines.push("  const allowed = new Set(configured.split(\",\").map((entry) => entry.trim()).filter(Boolean));");
+  lines.push("  return allowed.has(origin) ? origin : \"\";");
+  lines.push("}");
+  lines.push("");
+  lines.push("export function createApp(deps: ServerDependencies) {");
+  lines.push("  const app = new Hono();");
+  lines.push('  app.use("*", cors({');
+  lines.push("    origin: corsOrigin,");
+  lines.push('    allowMethods: ["GET", "POST", "PATCH", "DELETE", "OPTIONS"],');
+  lines.push('    allowHeaders: ["Content-Type", "If-Match", "If-None-Match", "Idempotency-Key", "Authorization"],');
+  lines.push('    exposeHeaders: ["ETag", "Location", "Retry-After", "Content-Disposition"]');
+  lines.push("  }));");
+  lines.push("");
+  lines.push(`  app.get("/health", (c) => c.json({ ok: true, service: "${serviceName}" }, 200 as any));`);
+  lines.push("");
+  lines.push('  app.get("/ready", async (c) => {');
+  lines.push("    try {");
+  lines.push("      await deps.ready?.();");
+  lines.push(`      return c.json({ ok: true, ready: true, service: "${serviceName}" }, 200 as any);`);
+  lines.push("    } catch (error) {");
+  lines.push('      const message = error instanceof Error ? error.message : "Readiness check failed";');
+  lines.push(`      return c.json({ ok: false, ready: false, service: "${serviceName}", message }, 503 as any);`);
+  lines.push("    }");
+  lines.push("  });");
+  lines.push("");
+
+  for (const lookup of lookupRoutes) {
+    lines.push(`  app.get("${lookup.route}", async (c) => {`);
+    lines.push("    try {");
+    lines.push(`      const result = await deps.${dependencyName}.${lookup.repositoryMethod}();`);
+    lines.push("      return c.json(result, 200 as any);");
+    lines.push("    } catch (error) {");
+    lines.push("      const failure = jsonError(error);");
+    lines.push("      return c.json(failure.body, failure.status as any);");
+    lines.push("    }");
+    lines.push("  });");
+    lines.push("");
+  }
+
+  contract.routes.forEach((route, routeIndex) => {
+    const method = route.method.toLowerCase();
+    const routeVar = `route${routeIndex}`;
+    const responseMode = route.responseContract?.mode || "item";
+    const methodName = route.repositoryMethod;
+    const hasOwnershipAuthz = (route.endpoint.authz || []).some((rule) => rule.ownership && rule.ownership !== "none");
+    const authLoaderVar = `loadAuthorizationResource${routeIndex}`;
+    lines.push(`  const ${routeVar} = serverContract.routes[${routeIndex}]!;`);
+    lines.push(`  app.${method}(${routeVar}.path, async (c) => {`);
+    lines.push("    try {");
+    const needsBody = (route.requestContract?.transport.body || []).length > 0;
+    if (needsBody) {
+      lines.push("      const body = await c.req.json().catch(() => ({}));");
+    } else {
+      lines.push("      const body = {};");
+    }
+    lines.push(`      const input = buildInput(c, ${routeVar}, body);`);
+    if ((route.endpoint.authz || []).length > 0) {
+      if (hasOwnershipAuthz) {
+        if (preconditionCapabilityIds.includes(route.capabilityId)) {
+          lines.push(`      const ${authLoaderVar} = async () => await deps.${dependencyName}.${preconditionResource.repositoryMethod}({ ${preconditionResource.inputField}: String(input.${preconditionResource.inputField} || "") } as unknown as ${toPascalCase(preconditionResource.repositoryMethod)}Input) as unknown as Record<string, unknown>;`);
+        } else if (route.method === "GET" && responseMode === "item") {
+          lines.push(`      const ${authLoaderVar} = async () => await deps.${dependencyName}.${methodName}(input as unknown as ${toPascalCase(methodName)}Input) as unknown as Record<string, unknown>;`);
+        } else {
+          lines.push(`      const ${authLoaderVar} = undefined;`);
+        }
+      }
+      lines.push('      if (!deps.authorize) throw new HttpError(500, "authorization_handler_missing", "Missing authorization handler for protected route");');
+      lines.push(`      await deps.authorize(c, ${routeVar}.endpoint.authz, { capabilityId: ${routeVar}.capabilityId, input, ${hasOwnershipAuthz ? `loadResource: typeof ${authLoaderVar} === "function" ? ${authLoaderVar} : undefined` : "loadResource: undefined"} });`);
+    }
+    if ((route.endpoint.preconditions || []).length > 0 || (route.endpoint.idempotency || []).length > 0) {
+      lines.push(`      requireHeaders(c, [...${routeVar}.endpoint.preconditions, ...${routeVar}.endpoint.idempotency]);`);
+    }
+    lines.push(`      requireRequestFields(${routeVar}, input);`);
+    if (preconditionCapabilityIds.includes(route.capabilityId)) {
+      lines.push('      const ifMatch = c.req.header("If-Match");');
+      lines.push('      if (ifMatch) {');
+      lines.push(`        const ${preconditionVariableName} = await deps.${dependencyName}.${preconditionResource.repositoryMethod}({ ${preconditionResource.inputField}: String(input.${preconditionResource.inputField} || "") } as unknown as ${toPascalCase(preconditionResource.repositoryMethod)}Input);`);
+      lines.push(`        if (${preconditionVariableName}.${preconditionResource.versionField} !== ifMatch) {`);
+      lines.push('          throw new HttpError(412, "stale_precondition", "If-Match does not match the current resource version");');
+      lines.push("        }");
+      lines.push("      }");
+    }
+
+    if (route.capabilityId === downloadCapabilityId) {
+      lines.push(`      const artifact = await deps.${dependencyName}.${methodName}(input as unknown as ${toPascalCase(methodName)}Input);`);
+      lines.push("      const responseHeaders = new Headers();");
+      lines.push(`      responseHeaders.set("Content-Type", artifact.contentType || "${route.endpoint.download?.[0]?.media || "application/octet-stream"}");`);
+      lines.push(`      responseHeaders.set("Content-Disposition", contentDisposition("${route.endpoint.download?.[0]?.disposition || "attachment"}", artifact.filename || "${route.endpoint.download?.[0]?.filename || "download.bin"}"));`);
+      lines.push(`      return new Response(artifact.body as BodyInit | null, { status: ${route.successStatus}, headers: responseHeaders });`);
+    } else {
+      lines.push(`      const result = await deps.${dependencyName}.${methodName}(input as unknown as ${toPascalCase(methodName)}Input);`);
+      if ((route.endpoint.cache || []).length > 0) {
+        const cacheRule = route.endpoint.cache[0];
+        lines.push(`      const etag = (result as unknown as Record<string, unknown>)["${cacheRule.source}"];`);
+        lines.push(`      if (etag && c.req.header("${cacheRule.requestHeader}") === String(etag)) {`);
+        lines.push(`        return c.body(null, ${cacheRule.notModified} as any);`);
+        lines.push("      }");
+        lines.push(`      if (etag) c.header("${cacheRule.responseHeader}", String(etag));`);
+      }
+      if ((route.endpoint.async || []).length > 0) {
+        const asyncRule = route.endpoint.async[0];
+        lines.push(`      c.header("${asyncRule.locationHeader}", (result as unknown as Record<string, unknown>).status_url ? String((result as unknown as Record<string, unknown>).status_url) : "${asyncRule.statusPath}".replace(":job_id", String((result as unknown as Record<string, unknown>).job_id ?? "")));`);
+        lines.push(`      c.header("${asyncRule.retryAfterHeader}", "5");`);
+      }
+      if (responseMode === "item" || responseMode === "cursor" || responseMode === "paged" || responseMode === "collection") {
+        lines.push(`      return c.json(result as ${toPascalCase(methodName)}Result, ${route.successStatus} as any);`);
+      } else {
+        lines.push(`      return c.json(result, ${route.successStatus} as any);`);
+      }
+    }
+    lines.push("    } catch (error) {");
+    lines.push("      const failure = jsonError(error);");
+    lines.push("      return c.json(failure.body, failure.status as any);");
+    lines.push("    }");
+    lines.push("  });");
+    lines.push("");
+  });
+
+  lines.push("  return app;");
+  lines.push("}");
+  lines.push("");
+  lines.push("export type AppType = ReturnType<typeof createApp>;");
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export function generateHonoServer(graph, options = {}) {
+  const projection = getProjection(graph, options.projectionId);
+  const realization = buildBackendRuntimeRealization(graph, options);
+  const contract = realization.contract;
+  const persistenceScaffold = generatePersistenceScaffold(graph, { ...options, projectionId: realization.dbProjection.id });
+  const prismaSchema = generateDbTarget("prisma-schema", graph, { projectionId: realization.dbProjection.id });
+
+  return {
+    "package.json": renderServerPackageJson(),
+    "tsconfig.json": renderServerTsconfig(),
+    "scripts/seed-demo.mjs": renderServerSeedScript(graph, options),
+    "src/index.ts": renderServerIndexTs(graph, options),
+    "src/lib/topogram/server-contract.ts": renderServerContractModule(graph, projection.id),
+    "src/lib/server/helpers.ts": renderServerHelpers(),
+    "src/lib/server/context.ts": renderServerContextTs(contract, graph, options),
+    "src/lib/server/app.ts": renderServerAppTs(realization),
+    "src/lib/persistence/types.ts": persistenceScaffold["types.ts"],
+    "src/lib/persistence/repositories.ts": persistenceScaffold["repositories.ts"],
+    "src/lib/persistence/prisma/repositories.ts": persistenceScaffold["prisma/repositories.ts"],
+    "prisma/schema.prisma": prismaSchema
+  };
+}

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

@@ -0,0 +1,42 @@
+import { generateWithComponentGenerator } from "../../adapters.js";
+import { generateExpressServer } from "./express.js";
+import { generateHonoServer } from "./hono.js";
+import { generatePersistenceScaffold } from "./persistence-wiring.js";
+import { generateServerContract } from "./server-contract.js";
+
+export function generateBackendTarget(target, graph, options = {}) {
+  if (target === "server-contract") {
+    return generateServerContract(graph, options);
+  }
+  if (target === "persistence-scaffold") {
+    return generatePersistenceScaffold(graph, options);
+  }
+  if (target === "hono-server") {
+    if (options.component?.generator?.id) {
+      return generateWithComponentGenerator({
+        graph,
+        projection: options.component.projection,
+        component: options.component,
+        topology: options.topology || null,
+        implementation: options.implementation || null,
+        options
+      }).files;
+    }
+    return generateHonoServer(graph, options);
+  }
+  if (target === "express-server") {
+    if (options.component?.generator?.id) {
+      return generateWithComponentGenerator({
+        graph,
+        projection: options.component.projection,
+        component: options.component,
+        topology: options.topology || null,
+        implementation: options.implementation || null,
+        options
+      }).files;
+    }
+    return generateExpressServer(graph, options);
+  }
+
+  throw new Error(`Unsupported backend generator target '${target}'`);
+}

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

@@ -0,0 +1,240 @@
+import { generateApiContractGraph } from "../../api.js";
+import { findEnumStatement, toPascalCase } from "../databases/shared.js";
+import { getProjection } from "../shared.js";
+import { repositoryMethodName } from "./runtime-helpers.js";
+import { getExampleImplementation } from "../../../example-implementation.js";
+
+function indexStatements(graph) {
+  const byId = new Map();
+  for (const statement of graph.statements) {
+    byId.set(statement.id, statement);
+  }
+  return byId;
+}
+
+function repositoryOperations(graph, repositoryReference) {
+  const byId = indexStatements(graph);
+  const capabilityIds = repositoryReference.capabilityIds;
+
+  return capabilityIds
+    .map((id) => byId.get(id))
+    .filter(Boolean)
+    .map((capability) => ({
+      capability,
+      input: capability.input[0] ? byId.get(capability.input[0].id) : null,
+      output: capability.output[0] ? byId.get(capability.output[0].id) : null
+    }));
+}
+
+function tsTypeForField(field, byId) {
+  const enumStatement = findEnumStatement(byId, field.fieldType);
+  if (enumStatement) {
+    return enumStatement.values.map((value) => `"${value}"`).join(" | ");
+  }
+  switch (field.fieldType) {
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    default:
+      return "string";
+  }
+}
+
+function renderShapeType(name, shape, byId) {
+  if (!shape) {
+    return `export type ${name} = Record<string, unknown>;\n`;
+  }
+  const fields = shape.projectedFields || shape.fields || [];
+  const lines = [`export interface ${name} {`];
+  for (const field of fields) {
+    lines.push(`  ${field.name}${field.requiredness === "required" ? "" : "?"}: ${tsTypeForField(field, byId)};`);
+  }
+  lines.push("}");
+  return `${lines.join("\n")}\n`;
+}
+
+function renderResponseTypeDeclarations(baseName, contract, byId) {
+  if (!contract) {
+    return [`export type ${baseName} = Record<string, unknown>;\n`];
+  }
+
+  if (contract.mode === "item") {
+    const fields = contract.fields || [];
+    const lines = [`export interface ${baseName} {`];
+    for (const field of fields) {
+      const shapeField = {
+        fieldType:
+          field.schema?.["x-topogram-type"] || field.schema?.format === "uuid"
+            ? field.schema.format === "uuid"
+              ? "uuid"
+              : field.schema["x-topogram-type"]
+            : field.schema?.format === "date-time"
+              ? "datetime"
+              : field.schema?.type === "integer"
+                ? "integer"
+                : field.schema?.type === "number"
+                  ? "number"
+                  : field.schema?.type === "boolean"
+                    ? "boolean"
+                    : field.schema?.enum
+                      ? field.schema.enum.map((value) => `"${value}"`).join(" | ")
+                      : "text",
+        name: field.name,
+        requiredness: field.required ? "required" : "optional"
+      };
+      const type = field.schema?.enum
+        ? field.schema.enum.map((value) => `"${value}"`).join(" | ")
+        : tsTypeForField(shapeField, byId);
+      lines.push(`  ${field.name}${field.required ? "" : "?"}: ${type};`);
+    }
+    lines.push("}");
+    return [`${lines.join("\n")}\n`];
+  }
+
+  const itemName = `${baseName}Item`;
+  const itemFields = contract.fields || [];
+  const itemLines = [`export interface ${itemName} {`];
+  for (const field of itemFields) {
+    const shapeField = {
+      fieldType: field.schema?.format === "uuid"
+        ? "uuid"
+        : field.schema?.format === "date-time"
+          ? "datetime"
+          : field.schema?.type === "integer"
+            ? "integer"
+            : field.schema?.type === "number"
+              ? "number"
+              : field.schema?.type === "boolean"
+                ? "boolean"
+                : field.schema?.enum
+                  ? field.schema.enum.map((value) => `"${value}"`).join(" | ")
+                  : "text",
+      name: field.name,
+      requiredness: field.required ? "required" : "optional"
+    };
+    const type = field.schema?.enum
+      ? field.schema.enum.map((value) => `"${value}"`).join(" | ")
+      : tsTypeForField(shapeField, byId);
+    itemLines.push(`  ${field.name}${field.required ? "" : "?"}: ${type};`);
+  }
+  itemLines.push("}");
+
+  const envelopeLines = [`export interface ${baseName} {`];
+  if (contract.mode === "collection") {
+    envelopeLines.push(`  items: ${itemName}[];`);
+  }
+  if (contract.mode === "paged") {
+    envelopeLines.push(`  items: ${itemName}[];`);
+    envelopeLines.push("  page: number;");
+    envelopeLines.push("  page_size: number;");
+    envelopeLines.push("  total: number;");
+  }
+  if (contract.mode === "cursor") {
+    envelopeLines.push(`  items: ${itemName}[];`);
+    envelopeLines.push(`  ${contract.cursor?.responseNext || "next_cursor"}: string;`);
+    if (contract.cursor?.responsePrev) {
+      envelopeLines.push(`  ${contract.cursor.responsePrev}?: string;`);
+    }
+    if (contract.total?.included) {
+      envelopeLines.push("  total?: number;");
+    }
+  }
+  envelopeLines.push("}");
+
+  return [`${itemLines.join("\n")}\n`, `${envelopeLines.join("\n")}\n`];
+}
+
+export function generatePersistenceScaffold(graph, options = {}) {
+  const implementation = getExampleImplementation(graph, options);
+  const repositoryReference = implementation.backend.repositoryReference;
+  const repositoryRenderers = implementation.backend.repositoryRenderers;
+  const repositoryInterfaceName = repositoryReference.repositoryInterfaceName;
+  const prismaRepositoryClassName = repositoryReference.prismaRepositoryClassName;
+  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 byId = indexStatements(graph);
+  const operations = repositoryOperations(graph, repositoryReference);
+  const interfaceLines = [];
+  const prismaLines = [];
+  const drizzleLines = [];
+  const typeLines = [];
+
+  prismaLines.push('import { PrismaClient } from "@prisma/client";');
+  prismaLines.push(`import type { ${repositoryInterfaceName} } from "../repositories";`);
+  prismaLines.push('import type {');
+  drizzleLines.push('import type { NodePgDatabase } from "drizzle-orm/node-postgres";');
+  drizzleLines.push(`import type { ${repositoryInterfaceName} } from "../repositories";`);
+  drizzleLines.push(`import { ${repositoryReference.drizzleSchemaImports.join(", ")} } from "../schema";`);
+  drizzleLines.push('import type {');
+
+  const usedTypes = new Set();
+  for (const operation of operations) {
+    const apiContract = generateApiContractGraph(graph, { capabilityId: operation.capability.id });
+    const method = repositoryMethodName(operation.capability.id);
+    const inputType = `${toPascalCase(method)}Input`;
+    const outputType = `${toPascalCase(method)}Result`;
+    usedTypes.add(inputType);
+    usedTypes.add(outputType);
+    prismaLines.push(`  ${inputType},`);
+    prismaLines.push(`  ${outputType},`);
+    drizzleLines.push(`  ${inputType},`);
+    drizzleLines.push(`  ${outputType},`);
+    typeLines.push(renderShapeType(inputType, operation.input, byId));
+    typeLines.push(...renderResponseTypeDeclarations(outputType, apiContract.responseContract, byId));
+  }
+  for (const declaration of repositoryReference.additionalTypeDeclarations || []) {
+    typeLines.push(`${declaration.trimEnd()}\n`);
+  }
+  for (const typeName of repositoryReference.additionalTypeNames || []) {
+    usedTypes.add(typeName);
+    prismaLines.push(`  ${typeName},`);
+    drizzleLines.push(`  ${typeName},`);
+  }
+  interfaceLines.push('import type {');
+  for (const typeName of [...usedTypes].sort()) {
+    interfaceLines.push(`  ${typeName},`);
+  }
+  interfaceLines.push('} from "./types";');
+  interfaceLines.push("");
+  interfaceLines.push(`export interface ${repositoryInterfaceName} {`);
+  for (const operation of operations) {
+    const method = repositoryMethodName(operation.capability.id);
+    const inputType = `${toPascalCase(method)}Input`;
+    const outputType = `${toPascalCase(method)}Result`;
+    interfaceLines.push(`  ${method}(input: ${inputType}): Promise<${outputType}>;`);
+  }
+  for (const method of repositoryReference.additionalInterfaceMethods || []) {
+    interfaceLines.push(`  ${method}`);
+  }
+  interfaceLines.push("}");
+  prismaLines.push('} from "../types";');
+  drizzleLines.push('} from "../types";');
+  prismaLines.push("");
+  prismaLines.push('import { HttpError } from "../../server/helpers";');
+  drizzleLines.push("");
+  prismaLines.push(repositoryRenderers.renderPrismaRepositoryBody({
+    repositoryInterfaceName,
+    prismaRepositoryClassName,
+    repositoryReference
+  }).trimEnd());
+  drizzleLines.push(repositoryRenderers.renderDrizzleRepositoryBody({
+    repositoryInterfaceName,
+    drizzleRepositoryClassName,
+    repositoryReference,
+    drizzleHint
+  }).trimEnd());
+
+  return {
+    "types.ts": `${typeLines.join("\n").trimEnd()}\n`,
+    "repositories.ts": `${interfaceLines.join("\n").trimEnd()}\n`,
+    "prisma/repositories.ts": `${prismaLines.join("\n").trimEnd()}\n`,
+    "drizzle/repositories.ts": `${drizzleLines.join("\n").trimEnd()}\n`
+  };
+}