@topogram/template-todo 0.1.30

package/implementation/runtime/check-renderers.js

@@ -0,0 +1,215 @@
+export function renderTodoRuntimeCheckState() {
+  return `const state = {
+  createdPrimary: null,
+  latestPrimary: null,
+  exportJob: null
+};`;
+}
+
+export function renderTodoRuntimeCheckCreatePayload() {
+  return `function createPayload(overrides = {}) {
+  return {
+    title: "Runtime Check Task",
+    description: "Generated by the richer runtime check bundle.",
+    priority: "high",
+    project_id: envValue(plan.env.demoContainerId),
+    ...(envValue(plan.env.demoUserId) ? { owner_id: envValue(plan.env.demoUserId) } : {}),
+    ...overrides
+  };
+}`;
+}
+
+export function renderTodoRuntimeCheckHelpers() {
+  return `async function waitForExportJob(jobId, { attempts = 10, delayMs = 25 } = {}) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const { response, responseBody } = await requestContract("cap_get_task_export_job", {
+      pathParams: {
+        job_id: jobId
+      }
+    });
+    assertCondition(response.status === 200, \`get export job expected 200 during polling, got \${response.status}\`);
+    if (responseBody?.status === "completed" && responseBody?.download_url) {
+      return responseBody;
+    }
+    await sleep(delayMs);
+  }
+  throw new Error("export job did not reach completed status in time");
+}`;
+}
+
+export function renderTodoRuntimeCheckCases() {
+  return `    } else if (definition.id === "api_seed_task_ready") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        pathParams: inferPathParams(contractFor(definition.capabilityId), definition.pathParams)
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`seed task readiness expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.id === envValue(plan.env.demoPrimaryId), "seed task readiness did not return the expected demo task");
+    } else if (definition.id === "create_task") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: createPayload(),
+        headers: {
+          "Idempotency-Key": crypto.randomUUID()
+        }
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`create task expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.id, "create task response did not include id");
+      assertCondition(responseBody?.project_id === envValue(plan.env.demoContainerId), "create task response used the wrong project");
+      assertCondition(responseBody?.priority === "high", "create task did not persist priority");
+      assertCondition(responseBody?.updated_at, "create task response did not include updated_at");
+      state.createdPrimary = responseBody;
+      state.latestPrimary = responseBody;
+      result.resources.primaryId = responseBody.id;
+    } else if (definition.id === "get_created_task") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId);
+      assertCondition(response.status === contract.endpoint.successStatus, \`get task expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.id === state.latestPrimary?.id, "get task did not return the created task");
+      assertCondition(responseBody?.title, "get task did not include title");
+      assertCondition(responseBody?.priority, "get task did not include priority");
+    } else if (definition.id === "list_tasks") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId);
+      assertCondition(response.status === contract.endpoint.successStatus, \`list tasks expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(Array.isArray(responseBody?.items), "list tasks did not return an items array");
+      assertCondition(responseBody.items.some((item) => item.id === state.latestPrimary?.id), "list tasks did not include the created task");
+    } else if (definition.id === "export_tasks") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          project_id: envValue(plan.env.demoContainerId)
+        }
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`export tasks expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.job_id, "export tasks did not return a job_id");
+      assertCondition(responseBody?.status_url, "export tasks did not return a status_url");
+      state.exportJob = responseBody;
+      result.resources.jobId = responseBody.job_id;
+    } else if (definition.id === "get_task_export_job") {
+      assertCondition(state.exportJob?.job_id, "get task export job requires a previously created export job");
+      const responseBody = await waitForExportJob(state.exportJob.job_id);
+      assertCondition(responseBody.job_id === state.exportJob.job_id, "get task export job returned the wrong job");
+      assertCondition(responseBody.status === "completed", "get task export job did not complete");
+      assertCondition(responseBody.download_url, "get task export job did not return a download_url");
+      state.exportJob = responseBody;
+      result.resources.jobId = responseBody.job_id;
+    } else if (definition.id === "download_task_export") {
+      assertCondition(state.exportJob?.job_id, "download task export requires a previously created export job");
+      const contract = contractFor(definition.capabilityId);
+      const requestHeaders = new Headers();
+      if ((contract.endpoint.authz || []).length > 0 && authToken()) {
+        requestHeaders.set("Authorization", \`Bearer \${authToken()}\`);
+      }
+      const response = await fetchWithStackHint(buildUrl(apiBase(), contract.endpoint.path, {
+        job_id: state.exportJob.job_id
+      }), { method: contract.endpoint.method, headers: requestHeaders }, "api service");
+      const responseBuffer = await response.arrayBuffer();
+      assertCondition(response.status === contract.endpoint.successStatus, \`download task export expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(response.headers.get("content-type")?.includes("application/zip"), "download task export did not return zip content");
+      assertCondition(response.headers.get("content-disposition")?.includes("task-export.zip"), "download task export did not include the expected filename");
+      assertCondition(responseBuffer.byteLength > 0, "download task export returned an empty body");
+      result.resources.jobId = state.exportJob.job_id;
+    } else if (definition.id === "project_lookup_ready" || definition.id === "user_lookup_ready") {
+      const response = await fetch(new URL(definition.path, apiBase()));
+      const responseBody = await parseResponseBody(response);
+      assertCondition(response.status === 200, \`\${definition.id} expected 200, got \${response.status}\`);
+      assertCondition(Array.isArray(responseBody), \`\${definition.id} did not return an array\`);
+      assertCondition(responseBody.length > 0, \`\${definition.id} returned no options\`);
+      assertCondition(responseBody.every((item) => item && typeof item.value === "string" && typeof item.label === "string"), \`\${definition.id} returned malformed lookup options\`);
+    } else if (definition.id === "update_without_precondition") {
+      const contract = contractFor(definition.capabilityId);
+      const { response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          title: "Runtime Check Task Updated"
+        }
+      });
+      const expected = preconditionStatusFor(contract);
+      assertCondition(response.status === expected, \`update without precondition expected \${expected}, got \${response.status}\`);
+      assertErrorResponse(responseBody, contract.endpoint.preconditions?.[0]?.code, "update without precondition");
+    } else if (definition.id === "update_with_stale_precondition") {
+      const { response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          title: "Runtime Check Task Stale Update"
+        },
+        headers: {
+          "If-Match": "1970-01-01T00:00:00.000Z"
+        }
+      });
+      assertCondition(response.status === definition.expectStatus, \`update with stale precondition expected \${definition.expectStatus}, got \${response.status}\`);
+      assertErrorResponse(responseBody, definition.expectErrorCode, "update with stale precondition");
+    } else if (definition.id === "update_task") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          title: "Runtime Check Task Updated",
+          priority: "low"
+        },
+        headers: {
+          "If-Match": state.latestPrimary?.updated_at || ""
+        }
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`update task expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.title === "Runtime Check Task Updated", "update task did not persist the updated title");
+      assertCondition(responseBody?.priority === "low", "update task did not persist the updated priority");
+      assertCondition(responseBody?.updated_at, "update task did not return updated_at");
+      state.latestPrimary = responseBody;
+      result.resources.primaryId = responseBody.id;
+    } else if (definition.id === "complete_without_precondition") {
+      const contract = contractFor(definition.capabilityId);
+      const { response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          completed_at: new Date().toISOString()
+        },
+        headers: {
+          "Idempotency-Key": crypto.randomUUID()
+        }
+      });
+      const expected = preconditionStatusFor(contract);
+      assertCondition(response.status === expected, \`complete without precondition expected \${expected}, got \${response.status}\`);
+      assertErrorResponse(responseBody, contract.endpoint.preconditions?.[0]?.code, "complete without precondition");
+    } else if (definition.id === "complete_task") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          completed_at: new Date().toISOString()
+        },
+        headers: {
+          "If-Match": state.latestPrimary?.updated_at || "",
+          "Idempotency-Key": crypto.randomUUID()
+        }
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`complete task expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.status === "completed", "complete task did not set status to completed");
+      assertCondition(responseBody?.updated_at, "complete task did not return updated_at");
+      state.latestPrimary = responseBody;
+      result.resources.primaryId = responseBody.id;
+    } else if (definition.id === "delete_without_precondition") {
+      const contract = contractFor(definition.capabilityId);
+      const { response, responseBody } = await requestContract(definition.capabilityId);
+      const expected = preconditionStatusFor(contract);
+      assertCondition(response.status === expected, \`delete without precondition expected \${expected}, got \${response.status}\`);
+      assertErrorResponse(responseBody, contract.endpoint.preconditions?.[0]?.code, "delete without precondition");
+    } else if (definition.id === "delete_task") {
+      const { contract, response, responseBody } = await requestContract(definition.capabilityId, {
+        headers: {
+          "If-Match": state.latestPrimary?.updated_at || ""
+        }
+      });
+      assertCondition(response.status === contract.endpoint.successStatus, \`delete task expected \${contract.endpoint.successStatus}, got \${response.status}\`);
+      assertCondition(responseBody?.status === "archived", "delete task did not archive the task");
+      state.latestPrimary = responseBody;
+      result.resources.primaryId = responseBody.id;
+    } else if (definition.id === "invalid_create_returns_4xx") {
+      const { response, responseBody } = await requestContract(definition.capabilityId, {
+        payload: {
+          description: "Missing required fields"
+        },
+        headers: {
+          "Idempotency-Key": crypto.randomUUID()
+        }
+      });
+      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_task_not_found") {
+      const { response, responseBody } = await requestContract(definition.capabilityId, {
+        pathParams: {
+          id: crypto.randomUUID()
+        }
+      });
+      assertCondition(response.status === definition.expectStatus, \`get unknown task expected \${definition.expectStatus}, got \${response.status}\`);
+      assertErrorResponse(responseBody, definition.expectErrorCode, "get unknown task");`;
+}

package/implementation/runtime/checks.js

@@ -0,0 +1,120 @@
+export const TODO_RUNTIME_CHECKS = {
+  environmentStage: {
+    id: "environment",
+    name: "Environment Readiness",
+    failFast: true,
+    checks: [
+      {
+        id: "required_env",
+        kind: "env_required",
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "web_tasks_page_ready",
+        kind: "web_contract",
+        path: "/tasks",
+        expectStatus: 200,
+        expectText: "Tasks",
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "web_projects_page_ready",
+        kind: "web_contract",
+        path: "/projects",
+        expectStatus: 200,
+        expectText: "Projects",
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "web_users_page_ready",
+        kind: "web_contract",
+        path: "/users",
+        expectStatus: 200,
+        expectText: "Users",
+        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_task_ready",
+        kind: "api_contract",
+        capabilityId: "cap_get_task",
+        pathParams: {
+          task_id: "$env:TOPOGRAM_DEMO_PRIMARY_ID"
+        },
+        expectShape: "task_detail",
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "web_task_detail_owner_edit_visible",
+        kind: "web_contract",
+        path: "/tasks/$env:TOPOGRAM_DEMO_PRIMARY_ID",
+        expectStatus: 200,
+        expectText: "Edit Task",
+        mandatory: true,
+        mutating: false
+      },
+      {
+        id: "web_task_detail_non_owner_edit_hidden",
+        kind: "web_contract",
+        path: "/tasks/$env:TOPOGRAM_DEMO_PRIMARY_ID?topogram_auth_user_id=99999999-9999-4999-8999-999999999999",
+        expectStatus: 200,
+        expectText: "Back to Tasks",
+        expectNotText: "Edit Task",
+        mandatory: true,
+        mutating: false
+      }
+    ]
+  },
+  apiStage: {
+    id: "api",
+    name: "API Runtime Flows",
+    failFast: false,
+    checks: [
+      { id: "create_task", kind: "api_contract", capabilityId: "cap_create_task", mutating: true, mandatory: true },
+      { id: "get_created_task", kind: "api_contract", capabilityId: "cap_get_task", mutating: false, mandatory: true },
+      { id: "list_tasks", kind: "api_contract", capabilityId: "cap_list_tasks", mutating: false, mandatory: true },
+      { id: "export_tasks", kind: "api_contract", capabilityId: "cap_export_tasks", mutating: true, mandatory: true },
+      { id: "get_task_export_job", kind: "api_contract", capabilityId: "cap_get_task_export_job", mutating: false, mandatory: true },
+      { id: "download_task_export", kind: "api_contract", capabilityId: "cap_download_task_export", mutating: false, mandatory: true },
+      { id: "project_lookup_ready", kind: "lookup_contract", lookupKey: "project", mandatory: true, mutating: false },
+      { id: "user_lookup_ready", kind: "lookup_contract", lookupKey: "user", mandatory: true, mutating: false },
+      { id: "update_without_precondition", kind: "api_negative", capabilityId: "cap_update_task", expectStatusFrom: "precondition", expectErrorCodeFrom: "precondition", mutating: false, mandatory: true },
+      { id: "update_with_stale_precondition", kind: "api_negative", capabilityId: "cap_update_task", expectStatus: 412, expectErrorCode: "stale_precondition", stalePrecondition: true, mutating: false, mandatory: true },
+      { id: "update_task", kind: "api_contract", capabilityId: "cap_update_task", mutating: true, mandatory: true },
+      { id: "complete_without_precondition", kind: "api_negative", capabilityId: "cap_complete_task", expectStatusFrom: "precondition", expectErrorCodeFrom: "precondition", mutating: false, mandatory: true },
+      { id: "complete_task", kind: "api_contract", capabilityId: "cap_complete_task", mutating: true, mandatory: true },
+      { id: "delete_without_precondition", kind: "api_negative", capabilityId: "cap_delete_task", expectStatusFrom: "precondition", expectErrorCodeFrom: "precondition", mutating: false, mandatory: true },
+      { id: "delete_task", kind: "api_contract", capabilityId: "cap_delete_task", mutating: true, mandatory: true },
+      { id: "invalid_create_returns_4xx", kind: "api_negative", capabilityId: "cap_create_task", expectStatusClass: 4, expectErrorCode: "cap_create_task_invalid_request", mutating: false, mandatory: true },
+      { id: "get_unknown_task_not_found", kind: "api_negative", capabilityId: "cap_get_task", expectStatus: 404, expectErrorCode: "cap_get_task_not_found", mutating: false, mandatory: true }
+    ]
+  },
+  smokeChecks: [
+    { id: "web_tasks_page", type: "web_get", path: "/tasks", expectStatus: 200, expectText: "Tasks" },
+    { id: "create_task", type: "api_post", path: "/tasks", expectStatus: 201, capabilityId: "cap_create_task" },
+    { id: "get_task", type: "api_get", path: "/tasks/:id", expectStatus: 200, capabilityId: "cap_get_task" },
+    { id: "list_tasks", type: "api_get", path: "/tasks", expectStatus: 200, capabilityId: "cap_list_tasks" }
+  ]
+};

package/implementation/runtime/reference.js

@@ -0,0 +1,92 @@
+import { TODO_BACKEND_REFERENCE } from "../backend/reference.js";
+
+export const TODO_RUNTIME_REFERENCE = {
+  localDbProjectionId: "proj_db_postgres",
+  serviceName: TODO_BACKEND_REFERENCE.serviceName,
+  ports: {
+    server: 3000,
+    web: 5173
+  },
+  environment: {
+    name: "Todo Local Runtime Stack",
+    databaseName: "topogram_todo",
+    envExample: `TOPOGRAM_AUTH_PROFILE=bearer_demo
+TOPOGRAM_AUTH_TOKEN=topogram-todo-demo-token
+TOPOGRAM_AUTH_USER_ID=${TODO_BACKEND_REFERENCE.demo.userId}
+TOPOGRAM_AUTH_PERMISSIONS=*
+TOPOGRAM_AUTH_ROLES=manager
+TOPOGRAM_AUTH_ADMIN=true
+PUBLIC_TOPOGRAM_AUTH_TOKEN=topogram-todo-demo-token
+PUBLIC_TOPOGRAM_AUTH_USER_ID=${TODO_BACKEND_REFERENCE.demo.userId}
+PUBLIC_TOPOGRAM_AUTH_PERMISSIONS=*
+PUBLIC_TOPOGRAM_DEMO_PRIMARY_ID=${TODO_BACKEND_REFERENCE.demo.taskId}
+PUBLIC_TOPOGRAM_DEMO_CONTAINER_ID=${TODO_BACKEND_REFERENCE.demo.projectId}
+TOPOGRAM_DEMO_PRIMARY_ID=${TODO_BACKEND_REFERENCE.demo.taskId}
+TOPOGRAM_DEMO_CONTAINER_ID=${TODO_BACKEND_REFERENCE.demo.projectId}`
+  },
+  compileCheck: {
+    name: "Todo Generated Compile Checks"
+  },
+  smoke: {
+    name: "Todo Runtime Smoke Plan",
+    bundleTitle: "Todo Runtime Smoke Bundle",
+    defaultContainerEnvVar: "TOPOGRAM_DEMO_CONTAINER_ID",
+    webPath: "/tasks",
+    expectText: "Tasks",
+    createPath: "/tasks",
+    getPathPrefix: "/tasks/",
+    listPath: "/tasks",
+    createPayload: {
+      title: "Smoke Test Task",
+      containerField: "project_id",
+      extraFields: {
+        owner_id: "__DEMO_USER_ID__"
+      }
+    }
+  },
+  runtimeCheck: {
+    name: "Todo Runtime Check Plan",
+    bundleTitle: "Todo Runtime Check Bundle",
+    requiredEnv: [
+      "TOPOGRAM_API_BASE_URL",
+      "TOPOGRAM_WEB_BASE_URL",
+      "TOPOGRAM_DEMO_CONTAINER_ID",
+      "TOPOGRAM_DEMO_PRIMARY_ID"
+    ],
+    demoContainerEnvVar: "TOPOGRAM_DEMO_CONTAINER_ID",
+    demoPrimaryEnvVar: "TOPOGRAM_DEMO_PRIMARY_ID",
+    lookupPaths: {
+      project: "/lookups/projects",
+      user: "/lookups/users"
+    },
+    stageNotes: [
+      {
+        id: "environment",
+        summary: "required env, web readiness, API health, API readiness, and DB-backed seeded task lookup"
+      },
+      {
+        id: "api",
+        summary: "core task happy paths, export/job flows, generated lookup endpoints, and important negative cases"
+      }
+    ],
+    notes: [
+      "Mutating checks create, update, complete, and archive a runtime-check task.",
+      "Export checks submit a task export job, verify job status, and verify the download endpoint.",
+      "Runtime checks also verify the generated project and user lookup endpoints.",
+      "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 richer staged verification and JSON reporting."
+    ]
+  },
+  appBundle: {
+    name: "Topogram Todo App Bundle",
+    demoContainerName: TODO_BACKEND_REFERENCE.demo.project.name,
+    demoPrimaryTitle: TODO_BACKEND_REFERENCE.demo.tasks[0].title
+  },
+  demoEnv: {
+    userId: TODO_BACKEND_REFERENCE.demo.userId,
+    containerId: TODO_BACKEND_REFERENCE.demo.projectId,
+    primaryId: TODO_BACKEND_REFERENCE.demo.taskId
+  }
+};

package/implementation/web/reference.js

@@ -0,0 +1,51 @@
+export const TODO_WEB_REFERENCE = {
+  brandName: "Topogram Todo",
+  client: {
+    primaryParam: "task_id",
+    functionNames: {
+      list: "listTasks",
+      get: "getTask",
+      create: "createTask",
+      update: "updateTask",
+      terminal: "completeTask"
+    },
+    capabilityIds: {
+      list: "cap_list_tasks",
+      get: "cap_get_task",
+      create: "cap_create_task",
+      update: "cap_update_task",
+      terminal: "cap_complete_task"
+    },
+    extraFunctions: [
+      { name: "deleteTask", capabilityId: "cap_delete_task", primaryParam: "task_id" },
+      { name: "exportTasks", capabilityId: "cap_export_tasks" },
+      { name: "getTaskExportJob", capabilityId: "cap_get_task_export_job", primaryParam: "job_id" }
+    ]
+  },
+  nav: {
+    browseLabel: "Tasks",
+    browseRoute: "/tasks",
+    createLabel: "Create Task",
+    createRoute: "/tasks/new",
+    links: [
+      { label: "Tasks", route: "/tasks" },
+      { label: "Projects", route: "/projects" },
+      { label: "Users", route: "/users" }
+    ]
+  },
+  home: {
+    demoPrimaryEnvVar: "PUBLIC_TOPOGRAM_DEMO_PRIMARY_ID",
+    demoTaskLabel: "Open Demo Task",
+    heroDescriptionTemplate: "Generated from Topogram via the PROFILE profile and wired to a multi-resource workspace for tasks, projects, and users.",
+    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_CONTAINER_ID",
+    helperText: "A project is required to create a task. Owner is optional.",
+    projectPlaceholder: "Select a project",
+    cancelLabel: "Cancel",
+    submitLabel: "Create Task"
+  }
+};