@suluk/cockpit 0.1.17 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 <h1 align="center">@suluk/cockpit</h1>
 
-<p align="center"><b>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.</b></p>
+<p align="center"><b>The pure cockpit core — one brain, two faces: the cycle model, the builder model, codegen, deploy planning, and the validate/audit/preview/converge helpers shared by the VS Code extension and the <code>/superadmin</code> web panel.</b></p>
 
 <p align="center">
   <em>Part of <a href="https://github.com/MahmoodKhalil57/suluk">Suluk</a> — one typed OpenAPI v4 contract projecting into every full-stack layer.</em>
@@ -24,11 +24,168 @@
 bun add @suluk/cockpit
 ```
 
-## The Suluk cycle
+## What it does
 
-`@suluk/cockpit` is one station on the Suluk walk — author one v4 source, then **validate · audit ·
-preview · generate · deploy** the whole stack from it. Explore the full toolchain in the
-[main repository](https://github.com/MahmoodKhalil57/suluk) or drive it from the [VS Code cockpit](https://marketplace.visualstudio.com/items?itemName=MahmoodKhalil.suluk-vscode).
+Given **one** v4 "Suluk" document, the cockpit computes every view a developer tool needs over it — as
+**pure functions, no host API**. The VS Code extension (`suluk-vscode`) and the web admin panel (`@suluk/admin`)
+both consume this exact core, so a projection is never reimplemented in a shell.
+
+- **The cycle model** — `buildCycle` projects the document into a layered view (data · contract · auth · cost ·
+  docs · state · UI · providers · tests). Each layer is a *projection* of the same source, so you can read the
+  lineage at a glance. The model is also a function of the requesting principal — pass scopes and gated
+  operations drop out.
+- **Validate / audit / preview** — `validateSource` (meta-schema), `auditSource` (doc-coverage findings), and
+  `previewHtml` (a self-contained Scalar or Swagger page) over raw source text.
+- **The builder model + codegen** — `buildBuilderModel` walks the tiered composition (pages → sections → blocks →
+  components); `generateForm` / `generateTable` / `generateAppFiles` land real TSX + a shadcn registry.
+- **Lifecycle & coherence** — `contractGates` + `shipSummary` (the "are you ready to ship?" checklist),
+  `convergeContract` (cross-cutting contradictions a clean merge leaves behind), `diffContracts` (local-vs-deployed
+  drift), `crossCut` (one contract refracted through every viewer), `contractToD2` (ERD / cycle / operation diagrams).
+- **Deploy planning** — `deployPlan` / `deployMarkdown` turn the contract into a Cloudflare plan + a `DEPLOY.md`.
+  The cockpit **plans**; it never runs `wrangler` and holds no credentials.
+
+## When to reach for it
+
+- You are building **another shell** over the Suluk contract (an editor integration, a CI gate, a dashboard) and
+  want the same brain the VS Code extension and `/superadmin` panel use — not a re-derivation.
+- You need a **single, principal-aware projection** of a v4 document: what entities, operations, costs, providers
+  and gated surfaces it implies, plus its ship-readiness and coherence.
+
+When **not** to: if you only need *one* projection in isolation, depend on it directly — `@suluk/scalar` /
+`@suluk/swagger` for docs HTML, `@suluk/shadcn` for forms/tables, `@suluk/builder` for the app graph, `@suluk/deploy`
+for the plan. The cockpit's value is **composing** them into the tool views above; reach past it when you don't need that.
+
+## Usage
+
+### The cycle model (the spine)
+
+```ts
+import { parseDocument } from "@suluk/core";
+import { buildCycle, cycleSummary } from "@suluk/cockpit";
+
+const doc = parseDocument(source); // a v4 "Suluk" document
+const model = buildCycle(doc);
+
+model.valid;     // passes the v4 meta-schema?
+model.coverage;  // documentation coverage 0..1
+cycleSummary(model);
+// → [{ layer: "Data (entities)", summary: "3 entities", status: "ok" }, … ]
+
+// Project for a principal — scope-gated operations they can't reach drop out of every layer:
+const asViewer = buildCycle(doc, { principal: { scopes: ["read:pets"] } });
+```
+
+### Validate · audit · preview (over raw source text)
+
+```ts
+import { validateSource, auditSource, previewHtml } from "@suluk/cockpit";
+
+const { ok, diagnostics } = validateSource(yamlOrJsonText);
+const { findings } = auditSource(yamlOrJsonText);     // under-documented routes
+const { html } = previewHtml(yamlOrJsonText, "scalar"); // or "swagger" — a self-contained page
+```
+
+### Ship-readiness + coherence
+
+```ts
+import { contractGates, shipSummary, convergeContract } from "@suluk/cockpit";
+import type { Baseline } from "@suluk/visual";
+
+const baseline: Baseline = {}; // the pixel-confidence baseline (empty ⇒ not yet verified)
+const gates = contractGates(doc, baseline);
+const { ready, line } = shipSummary(gates);
+// → { ready: false, line: "1 blocker · 1 to do · 3/5 pass" }
+
+const report = convergeContract(doc); // cross-cutting contradictions
+report.clean; // true ⇒ no dangling refs / undeclared schemes / orphan scopes / empty paths
+```
+
+### Drift, cross-cut, diagrams
+
+```ts
+import { diffContracts, crossCut, defaultViewers, contractToD2 } from "@suluk/cockpit";
+
+// "what's drifted in prod" — your LOCAL contract vs the DEPLOYED /openapi.json
+diffContracts(local, deployed).summary; // "1+ 0- 2~ ops · 1+ 0- 0~ schemas" | "in sync — local matches deployed"
+
+// one contract refracted through every viewer — the scope-gated surface
+crossCut(doc, defaultViewers(doc)).gated; // operations not visible to every viewer
+
+// another projection: D2 diagram source ("erd" | "cycle" | "operations")
+const d2 = contractToD2(doc, "erd"); // render with the d2 CLI / playground / kroki.io
+```
+
+### Codegen + deploy planning (the actions that land artifacts)
+
+```ts
+import { generateForm, generateAppFiles, deployPlan, deployMarkdown } from "@suluk/cockpit";
+
+const formTsx = generateForm(doc, "Pet");        // a shadcn form component (TSX) for an entity
+const files = generateAppFiles(doc);             // [{ path, content }] — openapi.json, components, pages, registry, diagrams
+
+const plan = deployPlan(doc);                    // a Cloudflare DeployPlan
+const md = deployMarkdown(plan);                 // a DEPLOY.md the user follows (Suluk never runs wrangler)
+```
+
+### Modules — install a contract fragment, re-project for free
+
+```ts
+import { installModule, ECOMMERCE, buildCycle } from "@suluk/cockpit";
+
+const { doc: merged } = installModule(host, ECOMMERCE); // ECOMMERCE | CRM | BILLING are first-party fragments
+buildCycle(merged); // every layer now includes the module's entities, operations, cost and provider slots
+```
+
+### Agents (OBSERVE-only)
+
+```ts
+import { agentsView, agentsSummary } from "@suluk/cockpit";
+
+const view = agentsView(doc); // the x-suluk-agents tier tree, effective scope, gate findings, reachable surface
+agentsSummary(view);          // a one-line digest — read-only; agent execution + secrets live OUTSIDE the cockpit
+```
+
+## API
+
+The package exposes a single entry point (`@suluk/cockpit`). The core groups:
+
+| Export | What it does |
+| --- | --- |
+| `buildCycle`, `cycleSummary`, `docChecks` | the layered cycle model (principal-aware) + doc-level contract checks |
+| `validateSource`, `auditSource`, `previewHtml`, `looksLikeV4` | validate / audit / preview over raw source text |
+| `buildBuilderModel`, `builderTree`, `entitiesFromDoc`, `generateAppFiles`, `generateRegistryJson` | the tiered builder model + the app/registry generators |
+| `entityNames`, `generateForm`, `generateTable`, `generateStoresModule`, `exportV4Json` | per-entity codegen + the canonical JSON export |
+| `contractGates`, `shipSummary` | the contract-level ship-readiness gates + a one-line summary |
+| `convergeContract` | a coherence audit (dangling refs / undeclared schemes / orphan scopes / preview backdoors) |
+| `diffContracts`, `canonical` | local-vs-deployed contract drift |
+| `crossCut`, `documentScopes`, `defaultViewers`, `previewRoles`, `previewAllowedRoles`, `previewLaunchUrl` | the per-viewer / role-preview security surface |
+| `contractToD2`, `diagramViews` | D2 diagram source (ERD / cycle / operations) |
+| `componentReport`, `approveComponents`, `primitiveCss` | UI-primitive decomposition + pixel-confidence (surfaces `@suluk/visual`) |
+| `deployPlan`, `deployMarkdown`, `previewDeployPlan`, `previewDeployMarkdown` | Cloudflare deploy planning + the rendered `DEPLOY.md` |
+| `agentsView`, `agentsSummary` | the `x-suluk-agents` OBSERVE view (tier tree · scope · context · model selection) |
+| `installModule`, `namespaceModule`, `previewInstall`, `gradeModule`, `composeModules`, `planComposition` | install / compose contract-fragment modules into the hub doc |
+| `ECOMMERCE`, `CRM`, `BILLING`, `FIRST_PARTY_REGISTRY`, `PROVIDER_CATALOG`, `STACK_TEMPLATES` | the first-party module + provider + stack-template catalogs |
+| `providerFacets`, `readProviders`, `swapProvider`, `parseRegistry`, `validateModule`, `resolveTemplate` | provider-slot + registry + template helpers (re-exported from `@suluk/builder`) |
+| `formatMicroUsd`, `summarize` | cost formatting (re-exported from `@suluk/cost`) for a live ledger |
+
+Every function is pure and typed against `OpenAPIv4Document` from `@suluk/core`; the type exports (`CycleModel`,
+`Gate`, `ConvergeReport`, `ContractDiff`, `CrossCut`, `AgentsView`, …) ride alongside each group.
+
+## Boundary
+
+The cockpit is **L3 — it renders and generates, never hosts** (the C023 line). It is pure logic with no host API:
+it returns models, strings and file lists; the *shell* writes files, fetches the deployed `/openapi.json`, opens
+terminals and renders webviews. Two consequences:
+
+- **No credentials seam.** Deploy planning emits a `DEPLOY.md` and the plan; it never runs `wrangler` or touches a
+  token — `wrangler login`'s OAuth happens in *your* terminal so credentials never reach Suluk (C020). Role-preview
+  links are computed (`previewLaunchUrl`) but the cockpit never mints or holds a session.
+- **Agents are OBSERVE-only.** `agentsView` derives the static tier tree, effective scope, gate findings and a
+  *projection preview* (file/tool **names**). It never executes an agent, fetches a preprompt, or reads a secret.
+
+Inject the host concerns (the bytes to fetch, the deployed document to diff against, the baseline to approve at);
+keep the projections here. To contribute a new view, add a pure function over `OpenAPIv4Document` and let both
+shells render it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.17",
+  "version": "0.2.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.",
   "publishConfig": {
   "access": "public"
@@ -19,16 +19,17 @@
   ".": "./src/index.ts"
 },
 "dependencies": {
-  "@suluk/core": "^0.1.9",
-  "@suluk/hono": "^0.1.2",
-  "@suluk/scalar": "^0.1.2",
+  "@suluk/core": "^0.1.13",
+  "@suluk/hono": "^0.1.5",
+  "@suluk/scalar": "^0.8.0",
   "@suluk/swagger": "^0.1.2",
   "@suluk/shadcn": "^0.1.2",
   "@suluk/builder": "^0.1.11",
-  "@suluk/deploy": "^0.1.3",
-  "@suluk/cost": "^0.1.2",
+  "@suluk/deploy": "^0.1.4",
+  "@suluk/cost": "^0.2.0",
+  "@suluk/harden": "^0.2.0",
   "@suluk/visual": "^0.1.3",
-  "@suluk/agents": "^0.1.1"
+  "@suluk/agents": "^0.1.6"
 },
 "devDependencies": {
   "@types/bun": "latest"

package/src/conformance.ts

@@ -0,0 +1,107 @@
+/**
+ * Conformance gates (C045) — the UNIFIED contract audit, the cockpit's "are you ready to ship?" checklist grown to fold
+ * the readiness DIMENSIONS into the same `Gate[]` model as `contractGates`. It COMPOSES shipped Suluk primitives — no
+ * new audit logic lives here:
+ *   • input hardening + schema readiness   ← @suluk/harden (auditDocument · auditReadiness, C043)
+ *   • cost completeness                     ← @suluk/cost   (costAudit)
+ *   • settlement "names a lever"            ← @suluk/cost   (settlementAudit, C044)
+ *   • implied error responses declared      ← @suluk/cost   (impliedErrorStatuses vs the op's declared statuses, C044)
+ *
+ * This is the generic form of toolfactory's `conformance-gate` (which hand-folds contract+errors+governance+stores+
+ * hardening): a consumer's CI collapses to `shipSummary([...contractGates(doc, baseline), ...conformanceGates(doc)])`
+ * (or `assertConformance(doc)`). Pure (no host) → unit-tested. cockpit never deps journeys (BDD coverage folds in via
+ * harden's combineGrades upstream, C043).
+ */
+import { type OpenAPIv4Document, type Request } from "@suluk/core";
+import { auditDocument, auditReadiness, type Grade } from "@suluk/harden";
+import { costAudit, settlementAudit, impliedErrorStatuses, eachOperation } from "@suluk/cost";
+import type { Gate, GateStatus } from "./lifecycle";
+
+const GRADE_STATUS: Record<Grade, GateStatus> = { A: "ok", B: "ok", C: "todo", D: "todo", F: "error" };
+
+/** The numeric statuses a request DECLARES (responses may be a map keyed by status or an array of {status}). */
+function declaredStatuses(req: Request): Set<number> {
+  const r = (req as { responses?: unknown }).responses;
+  const out = new Set<number>();
+  if (Array.isArray(r)) {
+    for (const x of r) {
+      const s = Number((x as { status?: unknown }).status);
+      if (Number.isFinite(s)) out.add(s);
+    }
+  } else if (r && typeof r === "object") {
+    for (const k of Object.keys(r)) {
+      const s = Number(k);
+      if (Number.isFinite(s)) out.add(s);
+    }
+  }
+  return out;
+}
+
+const findingStatus = (findings: { severity: string }[]): GateStatus =>
+  findings.length === 0 ? "ok" : findings.some((f) => f.severity === "high" || f.severity === "error") ? "error" : "todo";
+
+/** The CONFORMANCE gates — the readiness dimensions, each composed from a shipped Suluk audit. No host needed. */
+export function conformanceGates(doc: OpenAPIv4Document): Gate[] {
+  const gates: Gate[] = [];
+
+  // input hardening (security)
+  const sec = auditDocument(doc);
+  gates.push({
+    id: "hardened", title: "Input hardening",
+    status: GRADE_STATUS[sec.grade],
+    detail: `grade ${sec.grade} (${sec.score}/100) — ${sec.bySeverity.high} high · ${sec.bySeverity.medium} medium`,
+    action: GRADE_STATUS[sec.grade] === "ok" ? undefined : "harden the input schemas (maxLength/pattern/maximum/maxItems; close objects)",
+  });
+
+  // schema readiness (computed-required / missing-example)
+  const rd = auditReadiness(doc);
+  gates.push({
+    id: "readiness", title: "Schema readiness",
+    status: GRADE_STATUS[rd.grade],
+    detail: `grade ${rd.grade} (${rd.score}/100) — ${rd.findings.length} finding${rd.findings.length === 1 ? "" : "s"}`,
+    action: rd.findings.length ? "fix computed-required fields + add request examples" : undefined,
+  });
+
+  // cost completeness
+  const cf = costAudit(doc);
+  gates.push({
+    id: "costed", title: "Cost declared",
+    status: findingStatus(cf),
+    detail: cf.length ? `${cf.length} cost finding${cf.length === 1 ? "" : "s"}` : "every priced op declares its cost",
+    action: cf.length ? "complete x-suluk-cost" : undefined,
+  });
+
+  // settlement — every priced op names a lever (C044)
+  const sf = settlementAudit(doc);
+  gates.push({
+    id: "settled", title: "Cost settlement (the lever)",
+    status: findingStatus(sf),
+    detail: sf.length ? `${sf.length} settlement finding${sf.length === 1 ? "" : "s"} (${[...new Set(sf.map((f) => f.rule))].join(", ")})` : "every priced op names a lever (credit | rate-limited | free)",
+    action: sf.length ? "add x-suluk-cost.settlement (or the missing x-suluk-ratelimit cap)" : undefined,
+  });
+
+  // implied error responses declared (C044)
+  let missing = 0;
+  for (const { req } of eachOperation(doc)) {
+    const declared = declaredStatuses(req);
+    for (const s of impliedErrorStatuses(req)) if (!declared.has(s)) missing++;
+  }
+  gates.push({
+    id: "errors", title: "Implied error responses declared",
+    status: missing ? "todo" : "ok",
+    detail: missing ? `${missing} facet-implied error status${missing === 1 ? "" : "es"} not declared (credit→402, auth→401, scope→403, ratelimit→429, upstream→502)` : "every facet-implied error response is declared",
+    action: missing ? "declare the implied error responses on each operation" : undefined,
+  });
+
+  return gates;
+}
+
+/** CI gate (the hard incentive): throw if any conformance gate is an `error` (a blocker). Returns the gates otherwise. */
+export function assertConformance(doc: OpenAPIv4Document): Gate[] {
+  const gates = conformanceGates(doc);
+  const blockers = gates.filter((g) => g.status === "error");
+  if (blockers.length) {
+    throw new Error(`@suluk/cockpit: contract is not conformant — ${blockers.map((g) => `${g.title}: ${g.detail}`).join(" · ")}`);
+  }
+  return gates;
+}

package/src/index.ts

@@ -23,6 +23,10 @@ export { componentReport, approveComponents, type ComponentReport } from "./visu
 export { type Baseline, primitiveCss } from "@suluk/visual";
 // lifecycle / ship-readiness (L3): the round-trip loop as one checklist — authored → coherent → confident → generated → deployed.
 export { contractGates, shipSummary, type Gate, type GateStatus } from "./lifecycle";
+// conformance (C045): the UNIFIED contract audit — the readiness DIMENSIONS (harden security + readiness, cost,
+// settlement/lever, implied-errors) folded into the same Gate[] model. A consumer's CI collapses to
+// shipSummary([...contractGates, ...conformanceGates]) or assertConformance(doc).
+export { conformanceGates, assertConformance } from "./conformance";
 // agents (C027, OBSERVE): the x-suluk-agents tier tree, effective scope, gate findings, reachable surface + a
 // projection preview — read-only; agent execution + secrets live OUTSIDE the cockpit (C020 no-credentials seam).
 export {

package/test/conformance.test.ts

@@ -0,0 +1,73 @@
+import { test, expect, describe } from "bun:test";
+import { conformanceGates, assertConformance, shipSummary } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C045 — the unified contract audit: conformanceGates composes harden(security+readiness) + cost + settlement(lever) +
+ * implied-errors into the cockpit's Gate[] model. The generic form of toolfactory's conformance/governance/cost/errors
+ * gates. Composition only — no new audit logic here.
+ */
+const docOf = (requests: Record<string, unknown>): OpenAPIv4Document => ({ openapi: "4.0.0-candidate", info: { title: "T" }, paths: { "/x": { requests } } }) as unknown as OpenAPIv4Document;
+
+describe("conformanceGates — the five composed dimensions", () => {
+  const dirty = docOf({
+    charge: {
+      method: "post",
+      contentSchema: { type: "object", additionalProperties: false, required: ["amountCents", "balance"], properties: { amountCents: { type: "integer" }, balance: { type: "integer", "x-suluk-origin": "computed" } } },
+      "x-suluk-cost": { estimateMicroUsd: 1000, components: [] }, // priced, no settlement
+      "x-suluk-access": { requires: "authenticated" }, // implies 401
+      responses: { "200": { status: 200 } }, // 401 not declared
+    },
+  });
+  const gates = Object.fromEntries(conformanceGates(dirty).map((g) => [g.id, g]));
+
+  test("emits the five dimensions", () => {
+    expect(Object.keys(gates).sort()).toEqual(["costed", "errors", "hardened", "readiness", "settled"]);
+  });
+  test("hardening + readiness carry a grade", () => {
+    expect(gates.hardened.detail).toMatch(/grade [A-F]/);
+    expect(gates.readiness.detail).toMatch(/grade [A-F]/);
+  });
+  test("a priced op with no settlement is flagged on the settlement gate", () => {
+    expect(gates.settled.status).not.toBe("ok");
+    expect(gates.settled.detail).toContain("cost-without-settlement");
+  });
+  test("an undeclared facet-implied error is flagged on the errors gate", () => {
+    expect(gates.errors.status).toBe("todo"); // 401 implied by auth, not declared
+  });
+});
+
+describe("a clean contract passes every conformance gate", () => {
+  const clean = docOf({
+    clean: {
+      method: "post",
+      contentSchema: { type: "object", additionalProperties: false, required: ["name"], properties: { name: { type: "string", maxLength: 64, pattern: "^[a-z]+$" } }, examples: [{ name: "abc" }] },
+      "x-suluk-cost": { estimateMicroUsd: 100, components: [{ source: "compute", basis: "per-call", microUsd: 100 }], settlement: { method: "credit", credits: 1 } },
+      "x-suluk-access": { requires: "authenticated" },
+      responses: { "200": { status: 200 }, "401": { status: 401 }, "402": { status: 402 } },
+    },
+  });
+
+  test("all gates ok; assertConformance returns without throwing", () => {
+    const gates = conformanceGates(clean);
+    expect(gates.every((g) => g.status === "ok")).toBe(true);
+    expect(() => assertConformance(clean)).not.toThrow();
+    expect(shipSummary(gates).ready).toBe(true);
+  });
+});
+
+describe("assertConformance gates CI on error-status dimensions", () => {
+  const broken = docOf({
+    free: {
+      method: "post",
+      contentSchema: { type: "object", additionalProperties: false, required: ["n"], properties: { n: { type: "string", maxLength: 8, pattern: "^[a-z]+$" } }, examples: [{ n: "a" }] },
+      // settled by rate-limiting but NO x-suluk-ratelimit → a HIGH settlement finding → the settled gate is `error`
+      "x-suluk-cost": { estimateMicroUsd: 500, components: [], settlement: { method: "rate-limited" } },
+      responses: { "200": { status: 200 } },
+    },
+  });
+
+  test("throws when a conformance gate is an error blocker", () => {
+    expect(() => assertConformance(broken)).toThrow(/not conformant/i);
+  });
+});