@suluk/cockpit 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@suluk/cockpit",
+  "version": "0.1.0",
+  "description": "The pure cockpit core (cycle model · builder model · codegen · deploy planning · validate/audit/preview) shared by the vscode extension and the /superadmin web admin panel. CANDIDATE tooling.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@suluk/core": "0.1.0",
+    "@suluk/hono": "0.1.0",
+    "@suluk/scalar": "0.1.0",
+    "@suluk/swagger": "0.1.0",
+    "@suluk/shadcn": "0.1.0",
+    "@suluk/builder": "0.1.0",
+    "@suluk/deploy": "0.1.0",
+    "@suluk/cost": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
+}

package/src/builder.ts

@@ -0,0 +1,99 @@
+/**
+ * The cockpit's BUILDER surface (pure logic). Treats the hub document's components.schemas as entities, runs
+ * @suluk/builder over them, and exposes the tiered composition (pages → sections → blocks → components) with
+ * EACH tier's param contract attached — so the contract-narrowing is visible in the tree (a section node
+ * shows it exposes {tone, blocks}; you can read straight off it that a page can't reach the form's fields).
+ * Plus the two actions that land artifacts: generate the whole app, and export the shadcn registry.
+ */
+import type { OpenAPIv4Document, SchemaOrRef } from "@suluk/core";
+import { buildApp, toShadcnRegistry, type Entity, type BuiltApp, type DslDocument, type ParamSpec } from "@suluk/builder";
+import type { Registry } from "@suluk/builder";
+
+export interface BuilderNode {
+  tier: "page" | "section" | "block" | "component";
+  label: string;
+  /** The param-contract keys this tier exposes upward (empty for a leaf component). */
+  contract: string[];
+  children: BuilderNode[];
+}
+
+/** Each components.schemas entry becomes a builder entity. */
+export function entitiesFromDoc(doc: OpenAPIv4Document): Entity[] {
+  const schemas = (doc.components?.schemas ?? {}) as Record<string, SchemaOrRef>;
+  return Object.entries(schemas).map(([name, schema]) => ({ name, schema }));
+}
+
+function contractKeys(doc: DslDocument | undefined): string[] {
+  return Object.keys(doc?.params ?? {});
+}
+
+function listOptions(doc: DslDocument | undefined, key: string): string[] {
+  const spec = doc?.params?.[key] as ParamSpec | undefined;
+  return spec && spec.type === "list" ? spec.options : [];
+}
+
+function blockNode(reg: Registry, name: string): BuilderNode {
+  const block = reg.blocks[name];
+  const componentType = block?.root.type ?? "?";
+  return {
+    tier: "block", label: name, contract: contractKeys(block),
+    children: [{ tier: "component", label: componentType, contract: [], children: [] }],
+  };
+}
+
+function sectionNode(reg: Registry, name: string): BuilderNode {
+  const section = reg.sections[name];
+  return {
+    tier: "section", label: name, contract: contractKeys(section),
+    children: listOptions(section, "blocks").map((b) => blockNode(reg, b)),
+  };
+}
+
+function pageNode(reg: Registry, page: DslDocument): BuilderNode {
+  return {
+    tier: "page", label: page.name, contract: contractKeys(page),
+    children: listOptions(page, "sections").map((s) => sectionNode(reg, s)),
+  };
+}
+
+/** The full tier tree (pages → sections → blocks → components) with each tier's contract. */
+export function builderTree(app: BuiltApp): BuilderNode[] {
+  return Object.values(app.registry.pages).map((p) => pageNode(app.registry, p));
+}
+
+export interface BuilderModel {
+  app: BuiltApp;
+  tree: BuilderNode[];
+  /** DSL contract violations (empty ⇒ sound). */
+  errors: { doc: string; path: string; message: string }[];
+  entityCount: number;
+}
+
+/** Build the full builder model from a v4 document (its schemas → entities → buildApp). */
+export function buildBuilderModel(doc: OpenAPIv4Document): BuilderModel {
+  const entities = entitiesFromDoc(doc);
+  const app = buildApp({ entities, info: { title: doc.info?.title ?? "App", version: doc.info?.version ?? "0.0.0" } });
+  return { app, tree: builderTree(app), errors: app.errors, entityCount: entities.length };
+}
+
+export interface GeneratedFile { path: string; content: string }
+
+/** All files for the generated app: the v4 doc, the frontend components + pages, and the shadcn registry. */
+export function generateAppFiles(doc: OpenAPIv4Document): GeneratedFile[] {
+  const { app } = buildBuilderModel(doc);
+  const files: GeneratedFile[] = [];
+  files.push({ path: "openapi.json", content: JSON.stringify(app.backend.document, null, 2) });
+  for (const c of app.frontend.components) files.push({ path: `components/${c.name}.tsx`, content: c.tsx });
+  for (const p of app.frontend.pages) files.push({ path: `app/${p.name.toLowerCase()}/page.tsx`, content: p.tsx });
+  const reg = toShadcnRegistry(app, { name: (doc.info?.title ?? "app").toLowerCase().replace(/\s+/g, "-") });
+  files.push({ path: "registry.json", content: JSON.stringify(reg.index, null, 2) });
+  for (const item of reg.items) files.push({ path: `registry/${item.name}.json`, content: JSON.stringify(item, null, 2) });
+  return files;
+}
+
+/** The shadcn registry (index + items) as a pretty JSON string — the "Export shadcn registry" action. */
+export function generateRegistryJson(doc: OpenAPIv4Document): string {
+  const { app } = buildBuilderModel(doc);
+  const reg = toShadcnRegistry(app, { name: (doc.info?.title ?? "app").toLowerCase().replace(/\s+/g, "-") });
+  return JSON.stringify({ registry: reg.index, items: reg.items }, null, 2);
+}

package/src/codegen.ts

@@ -0,0 +1,67 @@
+/**
+ * The cockpit's action side — codegen that LANDS files. Every generator is a pure function over the v4 hub
+ * document, reusing the projection packages (so the editor never reimplements a projection). The vscode shell
+ * just writes the returned string to a file the user picks.
+ */
+import { parseDocument } from "@suluk/core";
+import type { OpenAPIv4Document, SchemaOrRef } from "@suluk/core";
+import { formSpec, tableSpec, renderFormTsx, renderTableTsx } from "@suluk/shadcn";
+import { buildCycle } from "./cycle";
+
+/** Entity names available for codegen (components.schemas). */
+export function entityNames(doc: OpenAPIv4Document): string[] {
+  return Object.keys(doc.components?.schemas ?? {});
+}
+
+function entitySchema(doc: OpenAPIv4Document, name: string): { schema: SchemaOrRef; defs: Record<string, SchemaOrRef> } {
+  const schemas = (doc.components?.schemas ?? {}) as Record<string, SchemaOrRef>;
+  const schema = schemas[name];
+  if (!schema) throw new Error(`no entity '${name}' in components.schemas`);
+  return { schema, defs: schemas };
+}
+
+/** Generate a shadcn form component (TSX) for an entity. */
+export function generateForm(doc: OpenAPIv4Document, name: string): string {
+  const { schema, defs } = entitySchema(doc, name);
+  return renderFormTsx(formSpec(schema, { defs }), { componentName: `${name}Form`, schemaName: `${name}Schema` });
+}
+
+/** Generate a shadcn table component (TSX) for an entity. */
+export function generateTable(doc: OpenAPIv4Document, name: string): string {
+  const { schema, defs } = entitySchema(doc, name);
+  return renderTableTsx(tableSpec(schema, { defs }), { componentName: `${name}Table` });
+}
+
+/**
+ * Generate the Nano Stores client wiring. @suluk/nano-stores is a runtime helper (createApiStores(routes)),
+ * so the "codegen" is a thin, honest scaffold: it wires the user's RouteContracts to a typed store client and
+ * lists, in comments, the exact stores the cockpit derived from the current document.
+ */
+export function generateStoresModule(doc: OpenAPIv4Document, opts: { baseUrl?: string } = {}): string {
+  const model = buildCycle(doc);
+  const state = model.layers.find((l) => l.id === "state");
+  const lines = (state?.items ?? []).map((i) => ` *   ${i.label.padEnd(24)} ${i.detail}`).join("\n");
+  const baseUrl = opts.baseUrl ?? "/api";
+  return `// CANDIDATE — generated by suluk-vscode. Not official OAS tooling.
+//
+// Nano Stores client for this API. @suluk/nano-stores projects your RouteContracts (the same ones your
+// Hono server is derived from) into typed fetcher/mutator stores. Wire your contracts here:
+//
+// Stores derived from the current v4 document:
+${lines || " *   (no operations)"}
+//
+import { createApiStores } from "@suluk/nano-stores";
+import { routes } from "./routes"; // your @suluk/hono RouteContract[] (the single source)
+
+export const api = createApiStores(routes, { baseUrl: ${JSON.stringify(baseUrl)} });
+
+// Usage:
+//   const $pet = api.fetchers.getPet({ petId: "123" });  // GET  → fetcher store
+//   await api.mutators.createPet.mutate({ data: { name: "Rex", tags: [] } }); // non-GET → mutator
+`;
+}
+
+/** Export the v4 document as pretty JSON (the canonical interchange artifact). */
+export function exportV4Json(source: string): string {
+  return JSON.stringify(parseDocument(source), null, 2);
+}

package/src/cycle.ts

@@ -0,0 +1,200 @@
+/**
+ * The cycle model — the cockpit's spine. From the ONE hub artifact (a v4 "Suluk" document) it computes a
+ * layered view of the whole declarative cycle: data entities, the API contract, auth, the document's health,
+ * the docs, the derived client stores, the derived UI, and the contract checks. Every layer is a *projection*
+ * of the same source, so the cockpit can show the lineage at a glance.
+ *
+ * It is also a FUNCTION of the requesting principal (the "who"): pass scopes and scope-gated operations the
+ * principal can't reach are filtered out — the same per-viewer projection emitV4 does, applied at the hub.
+ *
+ * Pure (no vscode) → unit-tested with bun. The extension shell renders this into a TreeView.
+ */
+import { buildAda, validateDocument, isReference } from "@suluk/core";
+import type { OpenAPIv4Document, Request, SchemaOrRef, SecurityRequirement } from "@suluk/core";
+import { audit, coverage } from "@suluk/hono";
+import { formSpec, tableSpec } from "@suluk/shadcn";
+import { costAudit, costTable, formatMicroUsd } from "@suluk/cost";
+
+export type LayerStatus = "ok" | "warn" | "error" | "info";
+
+export interface CycleItem {
+  label: string;
+  detail?: string;
+  status?: LayerStatus;
+  /** A stable handle (e.g. an entity or operation name) for command targeting. */
+  ref?: string;
+}
+
+export interface CycleLayer {
+  id: "data" | "contract" | "auth" | "document" | "cost" | "docs" | "state" | "ui" | "tests";
+  title: string;
+  status: LayerStatus;
+  summary: string;
+  items: CycleItem[];
+}
+
+export interface Principal {
+  scopes?: string[];
+}
+
+export interface CycleModel {
+  valid: boolean;
+  coverage: number;
+  /** The principal this view was projected for (undefined ⇒ the full/public view). */
+  principal?: Principal;
+  layers: CycleLayer[];
+}
+
+/** Scopes an operation requires (union across its security requirements; empty ⇒ public). */
+function requiredScopes(req: Request): string[][] {
+  const reqs = (req.security as SecurityRequirement[] | undefined) ?? [];
+  // each requirement is an AND of schemes; we collapse a requirement to the union of its scopes.
+  return reqs.map((r) => Object.values(r).flat());
+}
+
+/** Is `req` visible to a principal holding `scopes`? Public ops always; else ANY requirement must be satisfied. */
+function visibleTo(req: Request, scopes: Set<string> | undefined): boolean {
+  if (!scopes) return true; // no principal ⇒ full view
+  const reqs = requiredScopes(req);
+  if (reqs.length === 0) return true; // public op
+  return reqs.some((needed) => needed.every((s) => scopes.has(s)));
+}
+
+function schemaFieldCount(schema: SchemaOrRef, defs: Record<string, SchemaOrRef>): number {
+  try {
+    return formSpec(schema, { defs }).fields.length;
+  } catch {
+    return 0;
+  }
+}
+
+function pickStatus(...statuses: LayerStatus[]): LayerStatus {
+  if (statuses.includes("error")) return "error";
+  if (statuses.includes("warn")) return "warn";
+  if (statuses.includes("info")) return "info";
+  return "ok";
+}
+
+/** Build the full cycle model from a v4 document, optionally projected for a principal (the "who"). */
+export function buildCycle(doc: OpenAPIv4Document, opts: { principal?: Principal } = {}): CycleModel {
+  const schemas = (doc.components?.schemas ?? {}) as Record<string, SchemaOrRef>;
+  const defs = schemas;
+  const securitySchemes = doc.components?.securitySchemes ?? {};
+  const scopes = opts.principal ? new Set(opts.principal.scopes ?? []) : undefined;
+
+  const ada = buildAda(doc);
+  // operations, filtered by the principal (the per-viewer projection)
+  const ops = ada.operations.filter((o) => visibleTo(o.request, scopes));
+  const hiddenCount = ada.operations.length - ops.length;
+
+  // ── data: components.schemas (entities). x-suluk-db marks a DB-backed table (e.g. from @suluk/drizzle).
+  const dataItems: CycleItem[] = Object.entries(schemas).map(([name, s]) => {
+    const isTable = !isReference(s) && typeof s === "object" && s !== null && "x-suluk-db" in (s as object);
+    return { label: name, ref: name, detail: `${isTable ? "table" : "schema"} · ${schemaFieldCount(s, defs)} fields` };
+  });
+
+  // ── contract: the operations (API surface)
+  const scopeGated = ops.filter((o) => requiredScopes(o.request).some((r) => r.length > 0)).length;
+  const contractItems: CycleItem[] = ops.map((o) => ({
+    label: o.name,
+    ref: o.name,
+    detail: `${o.request.method.toUpperCase()} ${o.pathTemplate}`,
+    status: requiredScopes(o.request).some((r) => r.length > 0) ? "info" : undefined,
+  }));
+
+  // ── auth
+  const authItems: CycleItem[] = Object.entries(securitySchemes).map(([name, s]) => ({
+    label: name,
+    detail: (s as { type?: string }).type ?? "scheme",
+  }));
+
+  // ── document health
+  const v = validateDocument(doc);
+  const cov = coverage(doc);
+  const findings = audit(doc);
+  const warnFindings = findings.filter((f) => f.severity === "warn").length;
+
+  // ── docs (always derivable via the 3.1 downgrade)
+  const docsItems: CycleItem[] = [
+    { label: "Scalar", detail: "Preview in Scalar (3.1 downgrade)" },
+    { label: "Swagger UI", detail: "Preview in Swagger UI (3.1 downgrade)" },
+  ];
+
+  // ── state: one nano-store per operation (GET → fetcher, else mutator)
+  const stateItems: CycleItem[] = ops.map((o) => ({
+    label: o.name,
+    ref: o.name,
+    detail: o.request.method.toUpperCase() === "GET" ? "fetcher store" : "mutator store",
+  }));
+
+  // ── ui: a shadcn form + table per entity
+  const uiItems: CycleItem[] = Object.entries(schemas).map(([name, s]) => {
+    let cols = 0;
+    try { cols = tableSpec(s, { defs }).columns.length; } catch { cols = 0; }
+    return { label: name, ref: name, detail: `form (${schemaFieldCount(s, defs)} fields) · table (${cols} cols)` };
+  });
+
+  // ── cost: per-operation declared cost (x-suluk-cost) + coverage (which operations declared nothing)
+  const declaredCosts = costTable(doc);
+  const costFindings = costAudit(doc);
+  const undeclared = costFindings.filter((f) => f.code === "no-cost-model").length;
+  const costItems: CycleItem[] = declaredCosts.map((d) => ({ label: d.operation, ref: d.operation, detail: `${formatMicroUsd(d.estimateMicroUsd)} · ${d.sources.join(", ")}` }));
+
+  // ── tests: doc-level contract checks
+  const checks = docChecks(doc);
+  const testsItems: CycleItem[] = checks.map((c) => ({ label: c.name, status: c.pass ? "ok" : "error", detail: c.pass ? "pass" : c.message }));
+
+  const layers: CycleLayer[] = [
+    { id: "data", title: "Data (entities)", status: dataItems.length ? "ok" : "info", summary: `${dataItems.length} entities`, items: dataItems },
+    {
+      id: "contract", title: "Contract (API)",
+      status: "ok",
+      summary: `${ops.length} operations · ${scopeGated} scope-gated${hiddenCount ? ` · ${hiddenCount} hidden for this viewer` : ""}`,
+      items: contractItems,
+    },
+    { id: "auth", title: "Auth", status: authItems.length ? "ok" : "info", summary: authItems.length ? `${authItems.length} schemes` : "none", items: authItems },
+    {
+      id: "document", title: "Document (v4)",
+      status: pickStatus(v.valid ? "ok" : "error", warnFindings ? "warn" : "ok"),
+      summary: `${v.valid ? "meta-schema ✓" : `${v.errors.length} errors`} · coverage ${cov.toFixed(2)} · ${warnFindings} audit warns`,
+      items: v.valid ? [] : v.errors.slice(0, 20).map((e) => ({ label: e.message, detail: e.path, status: "error" as const })),
+    },
+    {
+      id: "cost", title: "Cost",
+      status: declaredCosts.length === 0 ? "info" : undeclared ? "warn" : "ok",
+      summary: declaredCosts.length === 0 ? "no costs declared" : `${declaredCosts.length} priced · ${undeclared} undeclared`,
+      items: costItems,
+    },
+    { id: "docs", title: "Docs", status: "ok", summary: "Scalar · Swagger", items: docsItems },
+    { id: "state", title: "State (Nano Stores)", status: "ok", summary: `${stateItems.length} stores`, items: stateItems },
+    { id: "ui", title: "UI (shadcn)", status: uiItems.length ? "ok" : "info", summary: `${uiItems.length} forms/tables`, items: uiItems },
+    {
+      id: "tests", title: "Tests (contract checks)",
+      status: checks.every((c) => c.pass) ? "ok" : "error",
+      summary: `${checks.filter((c) => c.pass).length}/${checks.length} ✓`,
+      items: testsItems,
+    },
+  ];
+
+  return { valid: v.valid, coverage: cov, principal: opts.principal, layers };
+}
+
+export interface DocCheck { name: string; pass: boolean; message: string }
+
+/** Doc-level "contract checks" — the mistakes a finished v4 document can still encode. */
+export function docChecks(doc: OpenAPIv4Document): DocCheck[] {
+  const out: DocCheck[] = [];
+  const v = validateDocument(doc);
+  out.push({ name: "validates against the v4 meta-schema", pass: v.valid, message: v.errors.slice(0, 3).map((e) => `${e.path} ${e.message}`).join("; ") });
+  const ada = buildAda(doc);
+  const provable = ada.collisions.filter((c) => c.verdict === "provable-collision");
+  out.push({ name: "no two operations provably collide", pass: provable.length === 0, message: provable.map((c) => `${c.a.name} vs ${c.b.name}`).join("; ") });
+  const ops = ada.operations.length;
+  out.push({ name: "every path has at least one operation", pass: ops > 0 || Object.keys(doc.paths ?? {}).length === 0, message: "a pathItem has no requests" });
+  return out;
+}
+
+/** A flat list for simple renderers / status lines. */
+export function cycleSummary(model: CycleModel): { layer: string; summary: string; status: LayerStatus }[] {
+  return model.layers.map((l) => ({ layer: l.title, summary: l.summary, status: l.status }));
+}

package/src/deploy.ts

@@ -0,0 +1,44 @@
+/**
+ * The cockpit's DEPLOY surface (pure logic). Turns the hub document into a Cloudflare deploy plan via
+ * @suluk/deploy (the swappable provider), and renders a DEPLOY.md the user follows. The extension writes the
+ * files + opens a terminal; it never runs wrangler for you — deploys are consequential, and auth (`wrangler
+ * login`, OAuth) happens in your terminal so credentials never touch Suluk.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { cloudflare, type DeployPlan } from "@suluk/deploy";
+import { entitiesFromDoc } from "./builder";
+
+/** Build the Cloudflare deploy plan from a v4 document (its schemas → entities). */
+export function deployPlan(doc: OpenAPIv4Document): DeployPlan {
+  return cloudflare.generate({
+    name: doc.info?.title ?? "suluk-app",
+    entities: entitiesFromDoc(doc),
+    appModule: "./src/app",
+    assetsDir: "./dist/client",
+  });
+}
+
+/** Render the deploy plan as a DEPLOY.md the user can follow step by step. */
+export function deployMarkdown(plan: DeployPlan): string {
+  const steps = plan.steps.map((s, i) => `${i + 1}. \`${s.cmd}\`\n   - ${s.note}`).join("\n");
+  const notes = plan.notes.map((n) => `- ${n}`).join("\n");
+  const files = plan.files.map((f) => `- \`${f.path}\``).join("\n");
+  return `# Deploy to Cloudflare — CANDIDATE (generated by Suluk)
+
+Your stack is Cloudflare-native: the Hono app is the Worker, the data floor (sqlite-core) is D1, and the
+built frontend is served as static assets. These files were generated for you:
+
+${files}
+
+## Steps (run them in the integrated terminal)
+
+${steps}
+
+## Notes
+
+${notes}
+
+> Suluk never runs these for you — \`wrangler login\` opens an OAuth flow in your browser, and deploys are
+> consequential. The deployment target is swappable: this is the \`cloudflare\` provider.
+`;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @suluk/cockpit — the PURE cockpit core: the cycle model, the builder model, codegen, deploy planning, and
+ * the validate/audit/preview helpers. No host API. Two shells consume this exact core: the vscode extension
+ * (suluk-vscode) and the web admin panel (@suluk/admin, served under /superadmin). One brain, two faces.
+ * CANDIDATE tooling — NOT official OAS.
+ */
+export { validateSource, auditSource, previewHtml, looksLikeV4, type Diagnostic } from "./logic";
+export { buildCycle, docChecks, cycleSummary, type CycleModel, type CycleLayer, type CycleItem, type LayerStatus, type Principal, type DocCheck } from "./cycle";
+export { buildBuilderModel, builderTree, entitiesFromDoc, generateAppFiles, generateRegistryJson, type BuilderModel, type BuilderNode, type GeneratedFile } from "./builder";
+export { entityNames, generateForm, generateTable, generateStoresModule, exportV4Json } from "./codegen";
+export { deployPlan, deployMarkdown } from "./deploy";
+export type { DeployPlan, DeployStep, DeployProvider } from "@suluk/deploy";

package/src/logic.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure extension logic — the part that does NOT touch the vscode API, so it is unit-testable with bun.
+ * The thin vscode shell (extension.ts) wires editor events + webviews to these functions. This separation
+ * is the same pattern as @suluk/better-auth (pure functions + a duck-typed adapter).
+ */
+import { parseDocument, validateDocument } from "@suluk/core";
+import type { OpenAPIv4Document } from "@suluk/core";
+import { audit, type Finding } from "@suluk/hono";
+import { scalarHtml } from "@suluk/scalar";
+import { swaggerHtml } from "@suluk/swagger";
+
+export interface Diagnostic {
+  severity: "error" | "warning" | "info";
+  path: string;
+  message: string;
+}
+
+/** True if a parsed document looks like a v4 "Suluk" document (so we only act on those). */
+export function looksLikeV4(doc: unknown): doc is OpenAPIv4Document {
+  return !!doc && typeof doc === "object" && typeof (doc as { openapi?: unknown }).openapi === "string" && (doc as { openapi: string }).openapi.startsWith("4");
+}
+
+/** Parse + meta-schema validate a document source. Parse failure → a single error diagnostic. */
+export function validateSource(text: string): { ok: boolean; diagnostics: Diagnostic[] } {
+  let doc: OpenAPIv4Document;
+  try {
+    doc = parseDocument(text);
+  } catch (e) {
+    return { ok: false, diagnostics: [{ severity: "error", path: "/", message: `parse error: ${(e as Error).message}` }] };
+  }
+  if (!looksLikeV4(doc)) {
+    return { ok: false, diagnostics: [{ severity: "info", path: "/openapi", message: "not an OpenAPI v4 'Suluk' document (openapi must start with \"4\")" }] };
+  }
+  const r = validateDocument(doc);
+  return {
+    ok: r.valid,
+    diagnostics: r.errors.map((e) => ({ severity: "error" as const, path: e.path, message: e.message })),
+  };
+}
+
+/** Documentation-coverage audit (under-documented routes) via the @suluk/hono engine. */
+export function auditSource(text: string): { findings: Finding[]; diagnostics: Diagnostic[] } {
+  let doc: OpenAPIv4Document;
+  try {
+    doc = parseDocument(text);
+  } catch {
+    return { findings: [], diagnostics: [] };
+  }
+  if (!looksLikeV4(doc)) return { findings: [], diagnostics: [] };
+  const findings = audit(doc);
+  return {
+    findings,
+    diagnostics: findings.map((f) => ({
+      severity: f.severity === "warn" ? "warning" : "info",
+      path: `${f.path}/${f.operation}`,
+      message: `${f.code}: ${f.message}`,
+    })),
+  };
+}
+
+/** Build a self-contained preview page (Scalar or Swagger) for a v4 source. Returns html + downgrade diagnostics. */
+export function previewHtml(text: string, ui: "scalar" | "swagger"): { html: string; diagnostics: { message: string }[] } {
+  const doc = parseDocument(text);
+  if (!looksLikeV4(doc)) throw new Error("not an OpenAPI v4 'Suluk' document");
+  const r = ui === "scalar" ? scalarHtml(doc) : swaggerHtml(doc);
+  return { html: r.html, diagnostics: r.diagnostics.map((d) => ({ message: `${d.kind}: ${d.message}` })) };
+}

package/test/builder.test.ts

@@ -0,0 +1,73 @@
+import { test, expect, describe } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseDocument } from "@suluk/core";
+import { buildBuilderModel, entitiesFromDoc, generateAppFiles, generateRegistryJson, type BuilderNode } from "../src/builder";
+
+const petstore = parseDocument(
+  readFileSync(join(import.meta.dir, "..", "..", "core", "test", "conformance", "valid", "01-petstore.yaml"), "utf8"),
+);
+
+function find(nodes: BuilderNode[], tier: string, label?: string): BuilderNode | undefined {
+  for (const n of nodes) {
+    if (n.tier === tier && (!label || n.label === label)) return n;
+    const inner = find(n.children, tier, label);
+    if (inner) return inner;
+  }
+  return undefined;
+}
+
+describe("buildBuilderModel — the cockpit Builder surface", () => {
+  const model = buildBuilderModel(petstore);
+
+  test("treats each schema as an entity (Pet, Category, Tag)", () => {
+    expect(entitiesFromDoc(petstore).map((e) => e.name).sort()).toEqual(["Category", "Pet", "Tag"]);
+    expect(model.entityCount).toBe(3);
+  });
+
+  test("the composition is sound", () => {
+    expect(model.errors).toEqual([]);
+  });
+
+  test("the tree is pages → sections → blocks → components", () => {
+    const page = model.tree[0];
+    expect(page.tier).toBe("page");
+    const section = find(model.tree, "section", "PetCrud")!;
+    expect(section.children.map((c) => c.label).sort()).toEqual(["PetForm", "PetTable"]);
+    const block = find(model.tree, "block", "PetForm")!;
+    expect(block.children[0].tier).toBe("component"); // ShadcnForm
+  });
+
+  test("each tier carries its param contract (the narrowing is visible)", () => {
+    const page = find(model.tree, "page")!;
+    const section = find(model.tree, "section", "PetCrud")!;
+    const block = find(model.tree, "block", "PetForm")!;
+    // a page may set { tone, sections }; a section { tone, blocks }; a form block { tone, fields }
+    expect(page.contract.sort()).toEqual(["sections", "tone"]);
+    expect(section.contract.sort()).toEqual(["blocks", "tone"]);
+    expect(block.contract).toContain("fields");
+    // the narrowing: `fields` is in the BLOCK contract but NOT the section/page contract
+    expect(section.contract).not.toContain("fields");
+    expect(page.contract).not.toContain("fields");
+  });
+});
+
+describe("generate actions land artifacts", () => {
+  test("generateAppFiles emits the v4 doc, frontend components/pages, and the shadcn registry", () => {
+    const files = generateAppFiles(petstore);
+    const paths = files.map((f) => f.path);
+    expect(paths).toContain("openapi.json");
+    expect(paths).toContain("components/PetForm.tsx");
+    expect(paths.some((p) => p.startsWith("app/") && p.endsWith("page.tsx"))).toBe(true);
+    expect(paths).toContain("registry.json");
+    expect(paths.some((p) => p === "registry/pet-crud.json")).toBe(true);
+  });
+
+  test("generateRegistryJson packages each slice (UI + backend) as installable items", () => {
+    const reg = JSON.parse(generateRegistryJson(petstore)) as { items: { name: string; files: { path: string }[] }[] };
+    const petCrud = reg.items.find((i) => i.name === "pet-crud")!;
+    const filePaths = petCrud.files.map((f) => f.path);
+    expect(filePaths).toContain("components/PetForm.tsx"); // UI
+    expect(filePaths).toContain("server/pet.routes.ts");   // backend, in the same install unit
+  });
+});

package/test/cycle.test.ts

@@ -0,0 +1,115 @@
+import { test, expect, describe } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseDocument } from "@suluk/core";
+import { buildCycle, cycleSummary, docChecks } from "../src/cycle";
+import { entityNames, generateForm, generateTable, generateStoresModule, exportV4Json } from "../src/codegen";
+
+const petstoreSrc = readFileSync(
+  join(import.meta.dir, "..", "..", "core", "test", "conformance", "valid", "01-petstore.yaml"),
+  "utf8",
+);
+const petstore = parseDocument(petstoreSrc);
+
+describe("buildCycle — the cockpit spine (every layer from one hub)", () => {
+  const model = buildCycle(petstore);
+
+  test("models all nine layers (incl. cost)", () => {
+    expect(model.layers.map((l) => l.id)).toEqual(["data", "contract", "auth", "document", "cost", "docs", "state", "ui", "tests"]);
+  });
+  test("the cost layer reflects declared costs (x-suluk-cost) — none on the bare petstore", () => {
+    expect(model.layers.find((l) => l.id === "cost")!.summary).toBe("no costs declared");
+  });
+  test("data layer lists the entities (Pet, Category, Tag)", () => {
+    const data = model.layers.find((l) => l.id === "data")!;
+    expect(data.items.map((i) => i.label).sort()).toEqual(["Category", "Pet", "Tag"]);
+  });
+  test("contract layer lists operations and flags scope-gated ones", () => {
+    const contract = model.layers.find((l) => l.id === "contract")!;
+    const names = contract.items.map((i) => i.label);
+    expect(names).toContain("createPet");
+    expect(names).toContain("listPets");
+    // createPet requires write:pets → flagged info; listPets is public
+    expect(contract.items.find((i) => i.label === "createPet")!.status).toBe("info");
+    expect(contract.items.find((i) => i.label === "listPets")!.status).toBeUndefined();
+  });
+  test("auth layer lists the security schemes", () => {
+    const auth = model.layers.find((l) => l.id === "auth")!;
+    expect(auth.items.map((i) => i.label).sort()).toEqual(["api_key", "petstore_auth"]);
+  });
+  test("document layer reports validity + coverage", () => {
+    expect(model.valid).toBe(true);
+    const docLayer = model.layers.find((l) => l.id === "document")!;
+    expect(docLayer.summary).toContain("meta-schema ✓");
+  });
+  test("state layer derives a store per operation (GET → fetcher, else mutator)", () => {
+    const state = model.layers.find((l) => l.id === "state")!;
+    expect(state.items.find((i) => i.label === "listPets")!.detail).toBe("fetcher store");
+    expect(state.items.find((i) => i.label === "createPet")!.detail).toBe("mutator store");
+  });
+  test("ui layer derives a form+table per entity", () => {
+    const ui = model.layers.find((l) => l.id === "ui")!;
+    expect(ui.items.find((i) => i.label === "Pet")!.detail).toMatch(/form \(\d+ fields\)/);
+  });
+  test("tests layer runs doc-level contract checks (all pass for petstore)", () => {
+    const tests = model.layers.find((l) => l.id === "tests")!;
+    expect(tests.status).toBe("ok");
+    expect(tests.items.every((i) => i.status === "ok")).toBe(true);
+  });
+});
+
+describe("the cockpit is a FUNCTION of the viewer (per-WHO projection)", () => {
+  test("anonymous hides scope-gated operations; a scoped principal reveals them", () => {
+    const anon = buildCycle(petstore, { principal: { scopes: [] } });
+    const writer = buildCycle(petstore, { principal: { scopes: ["write:pets"] } });
+    const anonOps = anon.layers.find((l) => l.id === "contract")!.items.map((i) => i.label);
+    const writerOps = writer.layers.find((l) => l.id === "contract")!.items.map((i) => i.label);
+    expect(anonOps).toContain("listPets");        // public
+    expect(anonOps).not.toContain("createPet");   // requires write:pets
+    expect(writerOps).toContain("createPet");
+    // the hidden count is surfaced honestly
+    expect(anon.layers.find((l) => l.id === "contract")!.summary).toContain("hidden for this viewer");
+  });
+  test("no principal ⇒ full view", () => {
+    const full = buildCycle(petstore);
+    expect(full.layers.find((l) => l.id === "contract")!.items.map((i) => i.label)).toContain("createPet");
+  });
+});
+
+describe("docChecks — the doc as an executable check", () => {
+  test("petstore passes all doc-level checks", () => {
+    expect(docChecks(petstore).every((c) => c.pass)).toBe(true);
+  });
+});
+
+describe("codegen actions land real artifacts", () => {
+  test("entityNames lists the schemas", () => {
+    expect(entityNames(petstore).sort()).toEqual(["Category", "Pet", "Tag"]);
+  });
+  test("generateForm emits a shadcn form TSX for Pet", () => {
+    const tsx = generateForm(petstore, "Pet");
+    expect(tsx).toContain("useForm");
+    expect(tsx).toContain("zodResolver");
+    expect(tsx).toContain("FormField");
+    expect(tsx).toContain("PetForm");
+  });
+  test("generateTable emits a shadcn table TSX for Pet", () => {
+    expect(generateTable(petstore, "Pet")).toContain("<Table");
+  });
+  test("generateStoresModule wires createApiStores and lists derived stores", () => {
+    const mod = generateStoresModule(petstore);
+    expect(mod).toContain("createApiStores");
+    expect(mod).toContain("@suluk/nano-stores");
+    expect(mod).toContain("createPet"); // a derived store listed in the comment
+  });
+  test("exportV4Json round-trips the document to JSON", () => {
+    const json = JSON.parse(exportV4Json(petstoreSrc));
+    expect(json.openapi).toContain("4.");
+  });
+});
+
+describe("cycleSummary — flat status line", () => {
+  test("returns one entry per layer", () => {
+    expect(cycleSummary(buildCycle(petstore)).length).toBe(9);
+  });
+});

package/test/deploy.test.ts

@@ -0,0 +1,32 @@
+import { test, expect, describe } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseDocument } from "@suluk/core";
+import { deployPlan, deployMarkdown } from "../src/deploy";
+
+const petstore = parseDocument(
+  readFileSync(join(import.meta.dir, "..", "..", "core", "test", "conformance", "valid", "01-petstore.yaml"), "utf8"),
+);
+
+describe("deployPlan — the cockpit's Cloudflare deploy surface", () => {
+  const plan = deployPlan(petstore);
+
+  test("produces the wrangler config, worker entry, and D1 schema from the doc's entities", () => {
+    const paths = plan.files.map((f) => f.path).sort();
+    expect(paths).toEqual(["schema.sql", "worker.ts", "wrangler.jsonc"]);
+    expect(plan.files.find((f) => f.path === "schema.sql")!.content).toContain("CREATE TABLE IF NOT EXISTS pet");
+  });
+
+  test("the ordered steps start with auth and end with deploy", () => {
+    expect(plan.steps[0].cmd).toBe("wrangler login");
+    expect(plan.steps.at(-1)!.cmd).toBe("wrangler deploy");
+  });
+
+  test("deployMarkdown renders a followable DEPLOY.md", () => {
+    const md = deployMarkdown(plan);
+    expect(md).toContain("# Deploy to Cloudflare");
+    expect(md).toContain("wrangler login");
+    expect(md).toContain("wrangler.jsonc");
+    expect(md).toContain("swappable");
+  });
+});

package/test/logic.test.ts

@@ -0,0 +1,68 @@
+import { test, expect, describe } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateSource, auditSource, previewHtml, looksLikeV4 } from "../src/logic";
+import { parseDocument } from "@suluk/core";
+
+const petstoreSrc = readFileSync(
+  join(import.meta.dir, "..", "..", "core", "test", "conformance", "valid", "01-petstore.yaml"),
+  "utf8",
+);
+
+describe("validateSource — the editor's diagnostics source", () => {
+  test("a valid v4 document yields no error diagnostics", () => {
+    const r = validateSource(petstoreSrc);
+    expect(r.ok).toBe(true);
+    expect(r.diagnostics).toEqual([]);
+  });
+  test("a malformed v4 document yields error diagnostics", () => {
+    const bad = `openapi: 4.0.0-candidate\ninfo: { title: t, version: "1" }\npaths:\n  "pet":\n    requests:\n      x: { responses: { ok: { status: 200 } } }\n`; // request missing `method`
+    const r = validateSource(bad);
+    expect(r.ok).toBe(false);
+    expect(r.diagnostics.length).toBeGreaterThan(0);
+  });
+  test("a YAML parse error becomes a single error diagnostic", () => {
+    const r = validateSource("openapi: 4.0\n  bad: : :\n:");
+    expect(r.ok).toBe(false);
+    expect(r.diagnostics[0].severity).toBe("error");
+  });
+  test("a non-v4 document is recognized and skipped (info, not error)", () => {
+    const r = validateSource(`openapi: 3.1.0\ninfo: { title: t, version: "1" }\npaths: {}`);
+    expect(r.ok).toBe(false);
+    expect(r.diagnostics[0].severity).toBe("info");
+  });
+});
+
+describe("looksLikeV4", () => {
+  test("accepts a 4.x document, rejects 3.x and junk", () => {
+    expect(looksLikeV4(parseDocument(petstoreSrc))).toBe(true);
+    expect(looksLikeV4({ openapi: "3.1.0" })).toBe(false);
+    expect(looksLikeV4({})).toBe(false);
+    expect(looksLikeV4(null)).toBe(false);
+  });
+});
+
+describe("auditSource — documentation coverage in the editor", () => {
+  test("returns findings as warning/info diagnostics for an under-documented doc", () => {
+    const sparse = `openapi: 4.0.0-candidate\ninfo: { title: t, version: "1" }\npaths:\n  "x":\n    requests:\n      doThing: { method: get, responses: { ok: { status: 200 } } }\n`;
+    const { findings, diagnostics } = auditSource(sparse);
+    expect(findings.length).toBeGreaterThan(0);
+    expect(diagnostics.some((d) => d.severity === "warning")).toBe(true); // missing-doc
+  });
+});
+
+describe("previewHtml — the webview content", () => {
+  test("scalar preview embeds the spec + loads Scalar", () => {
+    const { html } = previewHtml(petstoreSrc, "scalar");
+    expect(html).toContain("Scalar.createApiReference");
+    expect(html).toContain('"openapi":"3.1.0"');
+  });
+  test("swagger preview embeds the spec + loads Swagger UI", () => {
+    const { html } = previewHtml(petstoreSrc, "swagger");
+    expect(html).toContain("SwaggerUIBundle");
+    expect(html).toContain("swagger-ui-dist");
+  });
+  test("previewing a non-v4 doc throws a clear error", () => {
+    expect(() => previewHtml(`openapi: 3.1.0\ninfo: { title: t, version: "1" }\npaths: {}`, "scalar")).toThrow();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "types": ["bun"] },
+  "include": ["src", "test"]
+}