@topogram/starter-web-api-db 0.1.7

package/README.md

@@ -0,0 +1,32 @@
+# Topogram Starter: Web API DB
+
+Package-backed SvelteKit + Hono + Postgres starter for `topogram new`.
+
+This starter includes executable `implementation/` provider code. Review local
+template trust before generation.
+
+```bash
+topogram new ./web-api-db --template @topogram/starter-web-api-db
+```
+
+## Contract
+
+- Catalog id: `web-api-db`
+- Surfaces: `web`, `api`, `database`
+- Generators: `@topogram/generator-sveltekit-web`, `@topogram/generator-hono-api`, `@topogram/generator-postgres-db`
+- Runtime stack: SvelteKit + Hono + Postgres
+- Executable implementation: yes
+- Purpose: full-stack starter with explicit web-to-API and API-to-database wiring.
+
+## First Run
+
+```bash
+topogram new ./web-api-db --template web-api-db
+cd ./web-api-db
+npm install
+npm run doctor
+npm run check
+npm run generate
+```
+
+Review copied `implementation/` code before refreshing trust after local edits.

package/implementation/README.md

@@ -0,0 +1,5 @@
+# Starter Implementation
+
+This folder holds the small implementation provider copied by the package-backed
+`web-api-db` starter. It intentionally avoids Todo-specific domain logic; richer
+product examples belong in external template packs.

package/implementation/backend/reference.js

@@ -0,0 +1,49 @@
+export const HELLO_BACKEND_REFERENCE = {
+  serviceName: "topogram-starter-server",
+  renderSeedScript() {
+    const reference = HELLO_BACKEND_REFERENCE;
+    return `import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+const demoGreetingId = process.env.TOPOGRAM_DEMO_PRIMARY_ID || "${reference.demo.greetingId}";
+const demoMessage = process.env.TOPOGRAM_DEMO_MESSAGE || "${reference.demo.message}";
+
+async function main() {
+  const now = new Date();
+
+  await prisma.greeting.upsert({
+    where: { id: demoGreetingId },
+    update: {
+      message: demoMessage,
+      created_at: now
+    },
+    create: {
+      id: demoGreetingId,
+      message: demoMessage,
+      created_at: now
+    }
+  });
+
+  console.log(JSON.stringify({
+    ok: true,
+    demoGreetingId,
+    seededGreetingCount: 1
+  }, null, 2));
+}
+
+main()
+  .catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });
+`;
+  },
+  demo: {
+    greetingId: "33333333-3333-4333-8333-333333333333",
+    message: "hello-from-topogram"
+  }
+};

package/implementation/backend/repository-reference.js

@@ -0,0 +1,30 @@
+export const HELLO_BACKEND_REPOSITORY_REFERENCE = {
+  capabilityIds: [
+    "cap_get_greeting",
+    "cap_list_greetings",
+    "cap_create_greeting",
+    "cap_update_greeting"
+  ],
+  preconditionCapabilityIds: [],
+  preconditionResource: {
+    variableName: "currentGreeting",
+    repositoryMethod: "getGreeting",
+    inputField: "greeting_id",
+    versionField: "created_at"
+  },
+  downloadCapabilityId: "",
+  repositoryInterfaceName: "StarterRepository",
+  prismaRepositoryClassName: "PrismaStarterRepository",
+  drizzleRepositoryClassName: "DrizzleStarterRepository",
+  dependencyName: "starterRepository",
+  lookupBindings: [],
+  export: {
+    filename: "starter-export.json",
+    contentType: "application/json"
+  },
+  drizzleHint: "Fill in Drizzle query logic if you switch this starter to a Drizzle runtime.",
+  drizzleSchemaImports: ["greetingsTable"],
+  additionalTypeNames: [],
+  additionalTypeDeclarations: [],
+  additionalInterfaceMethods: []
+};

package/implementation/backend/repository-renderers.js

@@ -0,0 +1,108 @@
+export function renderHelloPrismaRepositoryBody({
+  repositoryInterfaceName,
+  prismaRepositoryClassName
+}) {
+  return `
+function iso(value: Date | string | null | undefined): string | undefined {
+  if (!value) return undefined;
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+function nextCursor<T extends { created_at: Date | string }>(items: T[]): string {
+  return items.length > 0 ? iso(items[items.length - 1]!.created_at) || "" : "";
+}
+
+function mapGreetingRecord(greeting: {
+  id: string;
+  message: string;
+  created_at: Date | string;
+}): GetGreetingResult {
+  return {
+    id: greeting.id,
+    message: greeting.message,
+    created_at: iso(greeting.created_at)!
+  };
+}
+
+export class ${prismaRepositoryClassName} implements ${repositoryInterfaceName} {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async getGreeting(input: GetGreetingInput): Promise<GetGreetingResult> {
+    const greeting = await this.prisma.greeting.findUnique({ where: { id: input.greeting_id } });
+    if (!greeting) throw new HttpError(404, "cap_get_greeting_not_found", "Greeting not found");
+    return mapGreetingRecord(greeting);
+  }
+
+  async listGreetings(input: ListGreetingsInput): Promise<ListGreetingsResult> {
+    const take = Math.min(input.limit ?? 25, 100);
+    const greetings = await this.prisma.greeting.findMany({
+      where: { ...(input.after ? { created_at: { lt: new Date(input.after) } } : {}) },
+      orderBy: [{ created_at: "desc" }],
+      take: take + 1
+    });
+    const page = greetings.slice(0, take).map(mapGreetingRecord);
+    return {
+      items: page,
+      next_cursor: nextCursor(greetings.slice(0, take))
+    };
+  }
+
+  async createGreeting(input: CreateGreetingInput): Promise<CreateGreetingResult> {
+    const greeting = await this.prisma.greeting.create({
+      data: {
+        id: crypto.randomUUID(),
+        message: input.message,
+        created_at: new Date()
+      }
+    });
+    return mapGreetingRecord(greeting);
+  }
+
+  async updateGreeting(input: UpdateGreetingInput): Promise<UpdateGreetingResult> {
+    const greeting = await this.prisma.greeting.update({
+      where: { id: input.greeting_id },
+      data: {
+        ...(input.message !== undefined ? { message: input.message } : {})
+      }
+    }).catch((error) => {
+      throw new HttpError(404, "cap_get_greeting_not_found", error instanceof Error ? error.message : "Greeting not found");
+    });
+    return mapGreetingRecord(greeting);
+  }
+}
+`;
+}
+
+export function renderHelloDrizzleRepositoryBody({
+  repositoryInterfaceName,
+  drizzleRepositoryClassName,
+  drizzleHint
+}) {
+  return `
+export class ${drizzleRepositoryClassName} implements ${repositoryInterfaceName} {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  private unsupported(): never {
+    void this.db;
+    void greetingsTable;
+    throw new Error(${JSON.stringify(drizzleHint)});
+  }
+
+  async getGreeting(): Promise<GetGreetingResult> {
+    this.unsupported();
+  }
+
+  async listGreetings(): Promise<ListGreetingsResult> {
+    this.unsupported();
+  }
+
+  async createGreeting(): Promise<CreateGreetingResult> {
+    this.unsupported();
+  }
+
+  async updateGreeting(): Promise<UpdateGreetingResult> {
+    this.unsupported();
+  }
+}
+`;
+}

package/implementation/index.js

@@ -0,0 +1,53 @@
+import { HELLO_BACKEND_REFERENCE } from "./backend/reference.js";
+import { HELLO_BACKEND_REPOSITORY_REFERENCE } from "./backend/repository-reference.js";
+import {
+  renderHelloDrizzleRepositoryBody,
+  renderHelloPrismaRepositoryBody
+} from "./backend/repository-renderers.js";
+import { HELLO_RUNTIME_REFERENCE } from "./runtime/reference.js";
+import { HELLO_RUNTIME_CHECKS } from "./runtime/checks.js";
+import {
+  renderHelloRuntimeCheckCases,
+  renderHelloRuntimeCheckCreatePayload,
+  renderHelloRuntimeCheckHelpers,
+  renderHelloRuntimeCheckState
+} from "./runtime/check-renderers.js";
+import { HELLO_WEB_REFERENCE } from "./web/reference.js";
+import { HELLO_WEB_SCREEN_REFERENCE } from "./web/screens-reference.js";
+import {
+  renderHelloHomePage,
+  renderHelloRoutes
+} from "./web/renderers.js";
+
+export const WEB_API_DB_IMPLEMENTATION = {
+  exampleId: "web-api-db-template",
+  exampleRoot: "/topogram",
+  backend: {
+    reference: HELLO_BACKEND_REFERENCE,
+    repositoryReference: HELLO_BACKEND_REPOSITORY_REFERENCE,
+    repositoryRenderers: {
+      renderPrismaRepositoryBody: renderHelloPrismaRepositoryBody,
+      renderDrizzleRepositoryBody: renderHelloDrizzleRepositoryBody
+    }
+  },
+  runtime: {
+    reference: HELLO_RUNTIME_REFERENCE,
+    checks: HELLO_RUNTIME_CHECKS,
+    checkRenderers: {
+      renderRuntimeCheckState: renderHelloRuntimeCheckState,
+      renderRuntimeCheckCreatePayload: renderHelloRuntimeCheckCreatePayload,
+      renderRuntimeCheckHelpers: renderHelloRuntimeCheckHelpers,
+      renderRuntimeCheckCases: renderHelloRuntimeCheckCases
+    }
+  },
+  web: {
+    reference: HELLO_WEB_REFERENCE,
+    screenReference: HELLO_WEB_SCREEN_REFERENCE,
+    renderers: {
+      renderHomePage: renderHelloHomePage,
+      renderRoutes: renderHelloRoutes
+    }
+  }
+};
+
+export default WEB_API_DB_IMPLEMENTATION;

package/implementation/runtime/check-renderers.js

@@ -0,0 +1,72 @@
+export function renderHelloRuntimeCheckState() {
+  return `const state = {
+  createdPrimary: null,
+  latestPrimary: null
+};`;
+}
+
+export function renderHelloRuntimeCheckCreatePayload() {
+  return `function createPayload(overrides = {}) {
+  return {
+    message: "Hello from the runtime check",
+    ...overrides
+  };
+}`;
+}
+
+export function renderHelloRuntimeCheckHelpers() {
+  return "";
+}
+
+export function renderHelloRuntimeCheckCases() {
+  return `    } else if (definition.id === "api_seed_greeting_ready") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        pathParams: inferPathParams(contractFor(definition.capabilityId), definition.pathParams)
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`seed greeting readiness expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.id === envValue(plan.env.demoPrimaryId), "seed greeting readiness did not return the expected demo greeting");
+    } else if (definition.id === "create_greeting") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: createPayload()
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`create greeting expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.id, "create greeting response did not include id");
+      assertCondition(responseBody?.message === "Hello from the runtime check", "create greeting did not persist message");
+      state.createdPrimary = responseBody;
+      state.latestPrimary = responseBody;
+      result.resources.primaryId = responseBody.id;
+    } else if (definition.id === "get_created_greeting") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId);
+      assertCondition(response.status === contract.endpoint.successStatus, \`get greeting expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.id === state.latestPrimary?.id, "get greeting did not return the created greeting");
+      assertCondition(responseBody?.message, "get greeting did not include message");
+    } else if (definition.id === "list_greetings") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId);
+      assertCondition(response.status === contract.endpoint.successStatus, \`list greetings expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(Array.isArray(responseBody?.items), "list greetings did not return an items array");
+      assertCondition(responseBody.items.some((item) => item.id === state.latestPrimary?.id), "list greetings did not include the created greeting");
+    } else if (definition.id === "update_greeting") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          message: "Hello from the updated runtime check"
+        }
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`update greeting expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.message === "Hello from the updated runtime check", "update greeting did not persist message");
+      state.latestPrimary = responseBody;
+      result.resources.primaryId = responseBody.id;
+    } else if (definition.id === "invalid_create_returns_4xx") {
+      const { response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {}
+      });
+      assertCondition(Math.floor(response.status / 100) === definition.expectStatusClass, \`invalid create expected \${definition.expectStatusClass}xx, got \${response.status}\`);
+      assertErrorResponse(responseBody, definition.expectErrorCode, "invalid create");
+    } else if (definition.id === "get_unknown_greeting_not_found") {
+      const { response, responseBody } = await requestContract(definition.capabilityId, {
+        pathParams: {
+          id: crypto.randomUUID()
+        }
+      });
+      assertCondition(response.status === definition.expectStatus, \`get unknown greeting expected \${definition.expectStatus}, got \${response.status}\`);
+      assertErrorResponse(responseBody, definition.expectErrorCode, "get unknown greeting");`;
+}

package/implementation/runtime/checks.js

@@ -0,0 +1,70 @@
+export const HELLO_RUNTIME_CHECKS = {
+  environmentStage: {
+    id: "environment",
+    name: "Environment Readiness",
+    failFast: true,
+    checks: [
+      {
+        id: "required_env",
+        kind: "env_required",
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "web_home_ready",
+        kind: "web_contract",
+        path: "/",
+        expectStatus: 200,
+        expectText: "Topogram Starter",
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "api_health_ready",
+        kind: "api_health",
+        path: "/health",
+        expectStatus: 200,
+        expectOk: true,
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "api_ready",
+        kind: "api_ready",
+        path: "/ready",
+        expectStatus: 200,
+        expectReady: true,
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "api_seed_greeting_ready",
+        kind: "api_contract",
+        capabilityId: "cap_get_greeting",
+        pathParams: {
+          greeting_id: "$env:TOPOGRAM_DEMO_PRIMARY_ID"
+        },
+        mandatory: true,
+        mutating: false
+      }
+    ]
+  },
+  apiStage: {
+    id: "api",
+    name: "API Contract Checks",
+    checks: [
+      { id: "create_greeting", kind: "api_contract", capabilityId: "cap_create_greeting", mutating: true, mandatory: true },
+      { id: "get_created_greeting", kind: "api_contract", capabilityId: "cap_get_greeting", mutating: false, mandatory: true },
+      { id: "list_greetings", kind: "api_contract", capabilityId: "cap_list_greetings", mutating: false, mandatory: true },
+      { id: "update_greeting", kind: "api_contract", capabilityId: "cap_update_greeting", mutating: true, mandatory: true },
+      { id: "invalid_create_returns_4xx", kind: "api_negative", capabilityId: "cap_create_greeting", expectStatusClass: 4, expectErrorCode: "cap_create_greeting_invalid_request", mutating: false, mandatory: true },
+      { id: "get_unknown_greeting_not_found", kind: "api_negative", capabilityId: "cap_get_greeting", expectStatus: 404, expectErrorCode: "cap_get_greeting_not_found", mutating: false, mandatory: true }
+    ]
+  },
+  smokeChecks: [
+    { id: "web_home_page", type: "web_get", path: "/", expectStatus: 200, expectText: "Topogram Starter" },
+    { id: "create_greeting", type: "api_post", path: "/greetings", expectStatus: 201, capabilityId: "cap_create_greeting" },
+    { id: "get_greeting", type: "api_get", path: "/greetings/:id", expectStatus: 200, capabilityId: "cap_get_greeting" },
+    { id: "list_greetings", type: "api_get", path: "/greetings", expectStatus: 200, capabilityId: "cap_list_greetings" }
+  ]
+};

package/implementation/runtime/reference.js

@@ -0,0 +1,73 @@
+import { HELLO_BACKEND_REFERENCE } from "../backend/reference.js";
+
+export const HELLO_RUNTIME_REFERENCE = {
+  localDbProjectionId: "proj_db_postgres",
+  serviceName: HELLO_BACKEND_REFERENCE.serviceName,
+  ports: {
+    server: 3000,
+    web: 5173
+  },
+  environment: {
+    name: "Starter Local Runtime Stack",
+    databaseName: "topogram_starter",
+    envExample: `PUBLIC_TOPOGRAM_DEMO_PRIMARY_ID=${HELLO_BACKEND_REFERENCE.demo.greetingId}
+TOPOGRAM_DEMO_PRIMARY_ID=${HELLO_BACKEND_REFERENCE.demo.greetingId}
+TOPOGRAM_DEMO_MESSAGE=${HELLO_BACKEND_REFERENCE.demo.message}`
+  },
+  compileCheck: {
+    name: "Starter Generated Compile Checks"
+  },
+  smoke: {
+    name: "Starter Runtime Smoke Plan",
+    bundleTitle: "Starter Runtime Smoke Bundle",
+    defaultContainerEnvVar: "TOPOGRAM_DEMO_MESSAGE",
+    webPath: "/",
+    expectText: "Topogram Starter",
+    createPath: "/greetings",
+    getPathPrefix: "/greetings/",
+    listPath: "/greetings",
+    createPayload: {
+      title: "Smoke Test Greeting",
+      containerField: "message"
+    }
+  },
+  runtimeCheck: {
+    name: "Starter Runtime Check Plan",
+    bundleTitle: "Starter Runtime Check Bundle",
+    requiredEnv: [
+      "TOPOGRAM_API_BASE_URL",
+      "TOPOGRAM_WEB_BASE_URL",
+      "TOPOGRAM_DEMO_PRIMARY_ID"
+    ],
+    demoContainerEnvVar: "TOPOGRAM_DEMO_MESSAGE",
+    demoPrimaryEnvVar: "TOPOGRAM_DEMO_PRIMARY_ID",
+    lookupPaths: {},
+    stageNotes: [
+      {
+        id: "environment",
+        summary: "required env, web readiness, API health, API readiness, and seeded greeting lookup"
+      },
+      {
+        id: "api",
+        summary: "core greeting create, get, list, and update paths"
+      }
+    ],
+    notes: [
+      "Mutating checks create and update a runtime-check greeting.",
+      "Later stages are skipped if environment readiness fails.",
+      "The generated server exposes both `/health` and `/ready`.",
+      "Use the smoke bundle for a faster minimal confidence check.",
+      "Use this runtime-check bundle for staged verification and JSON reporting."
+    ]
+  },
+  appBundle: {
+    name: "Topogram Starter App Bundle",
+    demoContainerName: HELLO_BACKEND_REFERENCE.demo.message,
+    demoPrimaryTitle: HELLO_BACKEND_REFERENCE.demo.message
+  },
+  demoEnv: {
+    userId: "",
+    containerId: HELLO_BACKEND_REFERENCE.demo.message,
+    primaryId: HELLO_BACKEND_REFERENCE.demo.greetingId
+  }
+};

package/implementation/web/reference.js

@@ -0,0 +1,45 @@
+export const HELLO_WEB_REFERENCE = {
+  brandName: "Topogram Starter",
+  client: {
+    primaryParam: "greeting_id",
+    functionNames: {
+      list: "listGreetings",
+      get: "getGreeting",
+      create: "createGreeting",
+      update: "updateGreeting",
+      terminal: "reloadGreeting"
+    },
+    capabilityIds: {
+      list: "cap_list_greetings",
+      get: "cap_get_greeting",
+      create: "cap_create_greeting",
+      update: "cap_update_greeting",
+      terminal: "cap_get_greeting"
+    },
+    extraFunctions: []
+  },
+  nav: {
+    browseLabel: "Starter",
+    browseRoute: "/",
+    createLabel: "API Contract",
+    createRoute: "/",
+    links: [
+      { label: "Home", route: "/" }
+    ]
+  },
+  home: {
+    demoPrimaryEnvVar: "PUBLIC_TOPOGRAM_DEMO_PRIMARY_ID",
+    demoTaskLabel: "Seeded Greeting ID",
+    heroDescriptionTemplate: "Generated from Topogram via the PROFILE profile and wired to a neutral API, web surface, and database.",
+    dynamicRouteText: "This screen uses a dynamic route.",
+    noRouteText: "No direct route is exposed for this screen."
+  },
+  createPrimary: {
+    defaultAssigneeEnvVar: "PUBLIC_TOPOGRAM_DEMO_USER_ID",
+    defaultContainerEnvVar: "PUBLIC_TOPOGRAM_DEMO_MESSAGE",
+    helperText: "Create a greeting through the generated API.",
+    projectPlaceholder: "Greeting message",
+    cancelLabel: "Cancel",
+    submitLabel: "Create Greeting"
+  }
+};

package/implementation/web/renderers.js

@@ -0,0 +1,45 @@
+export function renderHelloHomePage({
+  useTypescript,
+  demoPrimaryEnvVar,
+  screens,
+  projectionName,
+  homeDescription
+}) {
+  return `<script${useTypescript ? ' lang="ts"' : ""}>
+  import { ${demoPrimaryEnvVar} as DEMO_GREETING_ID } from "$env/static/public";
+
+  const screens = ${JSON.stringify(screens, null, 2)};
+</script>
+
+<main>
+  <div class="stack">
+    <section class="card hero">
+      <div>
+        <p class="muted">Generated starter</p>
+        <h1>Topogram Starter</h1>
+        <p>${homeDescription}</p>
+      </div>
+      <div class="button-row">
+        <a class="button-link" href="/greetings">View API route</a>
+        {#if DEMO_GREETING_ID}
+          <span class="badge">Seed: {DEMO_GREETING_ID}</span>
+        {/if}
+      </div>
+    </section>
+
+    <section class="grid two">
+      {#each screens as screen}
+        <article class="card">
+          <h2>{screen.title}</h2>
+          <p class="muted">{screen.route || "Contract-only screen"}</p>
+        </article>
+      {/each}
+    </section>
+  </div>
+</main>
+`;
+}
+
+export function renderHelloRoutes() {
+  return {};
+}

package/implementation/web/screens-reference.js

@@ -0,0 +1,7 @@
+export const HELLO_WEB_SCREEN_REFERENCE = {
+  listScreenId: "greeting_list",
+  detailScreenId: "greeting_detail",
+  createScreenId: "greeting_create",
+  editScreenId: null,
+  exportsScreenId: null
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@topogram/starter-web-api-db",
+  "version": "0.1.7",
+  "description": "SvelteKit, Hono, and Postgres Topogram starter.",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "files": [
+    "topogram-template.json",
+    "topogram",
+    "topogram.project.json",
+    "implementation",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@topogram/generator-hono-api": "0.2.6",
+    "@topogram/generator-postgres-db": "0.1.6",
+    "@topogram/generator-sveltekit-web": "0.1.14"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/topogram/actors/actor-operator.tg

@@ -0,0 +1,6 @@
+actor actor_operator {
+  name "Operator"
+  description "Person using the starter application"
+
+  status active
+}

package/topogram/capabilities/cap-create-greeting.tg

@@ -0,0 +1,11 @@
+capability cap_create_greeting {
+  name "Create Greeting"
+  description "Creates a greeting"
+
+  actors [actor_operator]
+  creates [entity_greeting]
+  input [shape_input_create_greeting]
+  output [shape_output_greeting_detail]
+
+  status active
+}

package/topogram/capabilities/cap-get-greeting.tg

@@ -0,0 +1,11 @@
+capability cap_get_greeting {
+  name "Get Greeting"
+  description "Fetches one greeting"
+
+  actors [actor_operator]
+  reads [entity_greeting]
+  input [shape_input_get_greeting]
+  output [shape_output_greeting_detail]
+
+  status active
+}

package/topogram/capabilities/cap-list-greetings.tg

@@ -0,0 +1,11 @@
+capability cap_list_greetings {
+  name "List Greetings"
+  description "Lists greetings"
+
+  actors [actor_operator]
+  reads [entity_greeting]
+  input [shape_input_list_greetings]
+  output [shape_output_greeting_detail]
+
+  status active
+}

package/topogram/capabilities/cap-update-greeting.tg

@@ -0,0 +1,12 @@
+capability cap_update_greeting {
+  name "Update Greeting"
+  description "Updates one greeting"
+
+  actors [actor_operator]
+  reads [entity_greeting]
+  updates [entity_greeting]
+  input [shape_input_update_greeting]
+  output [shape_output_greeting_detail]
+
+  status active
+}

package/topogram/entities/entity-greeting.tg

@@ -0,0 +1,21 @@
+entity entity_greeting {
+  name "Greeting"
+  description "A minimal resource used by the neutral starter"
+
+  fields {
+    id uuid required
+    message text required
+    created_at datetime required
+  }
+
+  keys {
+    primary [id]
+    index [created_at]
+  }
+
+  invariants {
+    message length <= 240
+  }
+
+  status active
+}

package/topogram/projections/proj-api.tg

@@ -0,0 +1,29 @@
+projection proj_api {
+  name "Starter API"
+  description "HTTP API realization for the neutral starter"
+  platform dotnet
+
+  realizes [cap_create_greeting, cap_get_greeting, cap_list_greetings, cap_update_greeting]
+  outputs [database_schema, entity_models, request_contracts, response_contracts, endpoints]
+
+  http {
+    cap_create_greeting method POST path /greetings success 201 auth none request body
+    cap_get_greeting method GET path /greetings/:id success 200 auth none request path
+    cap_list_greetings method GET path /greetings success 200 auth none request query
+    cap_update_greeting method PATCH path /greetings/:id success 200 auth none request body
+  }
+
+  http_fields {
+    cap_get_greeting input greeting_id in path as id
+    cap_update_greeting input greeting_id in path as id
+    cap_update_greeting input message in body
+    cap_list_greetings input after in query
+    cap_list_greetings input limit in query
+  }
+
+  http_responses {
+    cap_list_greetings mode cursor item shape_output_greeting_detail cursor request_after after response_next next_cursor limit field limit default 25 max 100 sort by created_at direction desc total included false
+  }
+
+  status active
+}

package/topogram/projections/proj-db-postgres.tg

@@ -0,0 +1,31 @@
+projection proj_db_postgres {
+  name "Starter Postgres DB"
+  description "Postgres persistence realization for the neutral starter"
+  platform db_postgres
+
+  realizes [entity_greeting]
+  outputs [db_contract, sql_schema]
+
+  db_tables {
+    entity_greeting table greetings
+  }
+
+  db_keys {
+    entity_greeting primary [id]
+  }
+
+  db_indexes {
+    entity_greeting index [created_at]
+  }
+
+  db_lifecycle {
+    entity_greeting timestamps created_at created_at updated_at created_at
+  }
+
+  generator_defaults {
+    profile postgres_sql
+    language sql
+  }
+
+  status active
+}

package/topogram/projections/proj-ui-shared.tg

@@ -0,0 +1,38 @@
+projection proj_ui_shared {
+  name "Starter Shared UI"
+  description "Platform-neutral UI semantics for the neutral starter"
+  platform ui_shared
+
+  realizes [cap_list_greetings, cap_get_greeting, cap_create_greeting, cap_update_greeting]
+  outputs [ui_contract]
+
+  ui_app_shell {
+    brand "Topogram Starter"
+    shell topbar
+    global_search false
+    notifications false
+    account_menu false
+    footer none
+  }
+
+  ui_screens {
+    screen greeting_list kind list title "Greetings" load cap_list_greetings item_shape shape_output_greeting_card detail_capability cap_get_greeting primary_action cap_create_greeting empty_title "No greetings yet" empty_body "Create a greeting to verify the generated stack" loading_state skeleton error_state inline
+    screen greeting_detail kind detail title "Greeting Details" load cap_get_greeting view_shape shape_output_greeting_detail primary_action cap_update_greeting loading_state skeleton
+    screen greeting_create kind form title "Create Greeting" input_shape shape_input_create_greeting submit cap_create_greeting success_navigate greeting_detail success_state banner
+  }
+
+  ui_navigation {
+    group starter label "Starter" placement primary pattern primary
+    screen greeting_list group starter label "Greetings" order 10 visible true default true sitemap include pattern primary
+    screen greeting_create group starter label "Create" order 20 visible true sitemap include pattern primary
+    screen greeting_detail group starter label "Greeting Details" visible false breadcrumb greeting_list sitemap exclude pattern stack_navigation
+  }
+
+  ui_screen_regions {
+    screen greeting_list region hero pattern summary_stats placement primary
+    screen greeting_list region results pattern resource_table placement primary
+    screen greeting_detail region summary pattern detail_panel placement primary
+  }
+
+  status active
+}

package/topogram/projections/proj-ui-web.tg

@@ -0,0 +1,34 @@
+projection proj_ui_web {
+  name "Starter Web UI"
+  description "Web realization for the neutral starter using a SvelteKit profile"
+  platform ui_web
+
+  realizes [proj_ui_shared, cap_list_greetings, cap_get_greeting, cap_create_greeting, cap_update_greeting]
+  outputs [ui_contract, web_app]
+
+  ui_routes {
+    screen greeting_list path /greetings
+    screen greeting_detail path /greetings/:id
+    screen greeting_create path /greetings/new
+  }
+
+  ui_web {
+    screen greeting_list shell topbar
+    screen greeting_list layout responsive_collection
+    screen greeting_list desktop_variant table
+    screen greeting_list mobile_variant cards
+    screen greeting_list collection table
+    screen greeting_detail layout detail_page
+    screen greeting_create present page
+    action cap_create_greeting present button
+    action cap_create_greeting placement toolbar
+  }
+
+  generator_defaults {
+    profile sveltekit
+    language typescript
+    styling css
+  }
+
+  status active
+}

package/topogram/shapes/shape-input-create-greeting.tg

@@ -0,0 +1,7 @@
+shape shape_input_create_greeting from entity_greeting {
+  name "Create Greeting Input"
+  description "Fields accepted when creating a greeting"
+  include [message]
+
+  status active
+}

package/topogram/shapes/shape-input-get-greeting.tg

@@ -0,0 +1,10 @@
+shape shape_input_get_greeting {
+  name "Get Greeting Input"
+  description "Input for fetching one greeting"
+
+  fields {
+    greeting_id uuid required
+  }
+
+  status active
+}

package/topogram/shapes/shape-input-list-greetings.tg

@@ -0,0 +1,11 @@
+shape shape_input_list_greetings {
+  name "List Greetings Input"
+  description "Input for listing greetings"
+
+  fields {
+    after text optional
+    limit integer optional default 25
+  }
+
+  status active
+}

package/topogram/shapes/shape-input-update-greeting.tg

@@ -0,0 +1,11 @@
+shape shape_input_update_greeting {
+  name "Update Greeting Input"
+  description "Input for updating a greeting"
+
+  fields {
+    greeting_id uuid required
+    message text optional
+  }
+
+  status active
+}

package/topogram/shapes/shape-output-greeting-card.tg

@@ -0,0 +1,7 @@
+shape shape_output_greeting_card from entity_greeting {
+  name "Greeting Card Output"
+  description "Compact greeting payload"
+  include [id, message, created_at]
+
+  status active
+}

package/topogram/shapes/shape-output-greeting-detail.tg

@@ -0,0 +1,7 @@
+shape shape_output_greeting_detail from entity_greeting {
+  name "Greeting Detail Output"
+  description "Detailed greeting payload"
+  include [id, message, created_at]
+
+  status active
+}

package/topogram/verifications/verification-runtime-flow.tg

@@ -0,0 +1,16 @@
+verification ver_runtime_flow {
+  name "Starter runtime flow"
+  description "Verifies the core greeting runtime behavior."
+
+  validates [cap_create_greeting, cap_get_greeting, cap_list_greetings, cap_update_greeting]
+  method runtime
+
+  scenarios [
+    create_greeting_runtime,
+    get_created_greeting_runtime,
+    list_greetings_runtime,
+    update_greeting_runtime
+  ]
+
+  status active
+}

package/topogram/verifications/verification-runtime-smoke.tg

@@ -0,0 +1,16 @@
+verification ver_runtime_smoke {
+  name "Starter runtime smoke"
+  description "Covers the minimum web and API checks for the neutral starter."
+
+  validates [cap_create_greeting, cap_get_greeting, cap_list_greetings]
+  method smoke
+
+  scenarios [
+    home_page_responds,
+    create_greeting_smoke,
+    get_created_greeting_smoke,
+    list_greetings_smoke
+  ]
+
+  status active
+}

package/topogram-template.json

@@ -0,0 +1,8 @@
+{
+  "id": "@topogram/starter-web-api-db",
+  "version": "0.1.7",
+  "kind": "starter",
+  "description": "Neutral Hello-resource web/API/database starter.",
+  "topogramVersion": "0.1",
+  "includesExecutableImplementation": true
+}

package/topogram.project.json

@@ -0,0 +1,53 @@
+{
+  "version": "0.1",
+  "implementation": {
+    "id": "web-api-db-template",
+    "module": "./implementation/index.js",
+    "export": "WEB_API_DB_IMPLEMENTATION"
+  },
+  "outputs": {
+    "app": {
+      "path": "./app",
+      "ownership": "generated"
+    }
+  },
+  "topology": {
+    "components": [
+      {
+        "id": "app_api",
+        "type": "api",
+        "projection": "proj_api",
+        "generator": {
+          "id": "@topogram/generator-hono-api",
+          "version": "1",
+          "package": "@topogram/generator-hono-api"
+        },
+        "port": 3000,
+        "database": "app_postgres"
+      },
+      {
+        "id": "app_sveltekit",
+        "type": "web",
+        "projection": "proj_ui_web",
+        "generator": {
+          "id": "@topogram/generator-sveltekit-web",
+          "version": "1",
+          "package": "@topogram/generator-sveltekit-web"
+        },
+        "port": 5173,
+        "api": "app_api"
+      },
+      {
+        "id": "app_postgres",
+        "type": "database",
+        "projection": "proj_db_postgres",
+        "generator": {
+          "id": "@topogram/generator-postgres-db",
+          "version": "1",
+          "package": "@topogram/generator-postgres-db"
+        },
+        "port": 5432
+      }
+    ]
+  }
+}