@suluk/cockpit 0.1.11 → 0.1.13

package/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <a href="https://github.com/MahmoodKhalil57/suluk">
+    <img src="https://raw.githubusercontent.com/MahmoodKhalil57/suluk/main/branding/export/wordmark.png" alt="Suluk" width="360" />
+  </a>
+</p>
+
+<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">
+  <em>Part of <a href="https://github.com/MahmoodKhalil57/suluk">Suluk</a> — one typed OpenAPI v4 contract projecting into every full-stack layer.</em>
+</p>
+
+---
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/cockpit
+```
+
+## The Suluk cycle
+
+`@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).
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,27 +1,39 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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 ."
-  }
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/cockpit"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+  ".": "./src/index.ts"
+},
+"dependencies": {
+  "@suluk/core": "0.1.6",
+  "@suluk/hono": "0.1.1",
+  "@suluk/scalar": "0.1.1",
+  "@suluk/swagger": "0.1.1",
+  "@suluk/shadcn": "0.1.1",
+  "@suluk/builder": "0.1.9",
+  "@suluk/deploy": "0.1.1",
+  "@suluk/cost": "0.1.1",
+  "@suluk/visual": "0.1.1"
+},
+"devDependencies": {
+  "@types/bun": "latest"
+},
+"scripts": {
+  "test": "bun test",
+  "typecheck": "tsc --noEmit -p ."
+}
 }

package/src/index.ts

@@ -18,6 +18,11 @@ export { crossCut, documentScopes, defaultViewers, type Viewer, type ViewerView,
 export { convergeContract, type ConvergeReport, type ConvergeFinding, type ConvergeCode } from "./converge";
 // diagrams: D2 source for views of the contract (ERD / the declarative cycle / the operation surface) — another projection.
 export { contractToD2, diagramViews, type DiagramView } from "./diagram";
+// component preview + pixel-confidence (surfaces @suluk/visual): decompose generated UI into primitives, check vs a baseline.
+export { componentReport, approveComponents, type ComponentReport } from "./visual";
+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";
 // cost formatting, re-exported so the extension shell can render a live /cost ledger without a direct @suluk/cost dep.
 export { formatMicroUsd, summarize, type CostSummary } from "@suluk/cost";
 // modules (C021): install a contract fragment into the hub doc — the cockpit then re-projects it for free.

package/src/lifecycle.ts

@@ -0,0 +1,82 @@
+/**
+ * Lifecycle / ship-readiness (L3) — the round-trip loop made legible. One contract walks: authored → coherent →
+ * pixel-confident → generated → deployed. contractGates computes the CONTRACT-level gates here (pure: valid /
+ * coherent / confident), each with a status + the cheapest next action; the extension adds the host gates
+ * (generated-in-sync, deployed-in-sync, health) it can only see with fs + network. The whole thing is one
+ * "are you ready to ship?" checklist that aggregates the cockpit's own audits. Pure (no host) → unit-tested.
+ */
+import { validateDocument, buildAda, type OpenAPIv4Document } from "@suluk/core";
+import { convergeContract } from "./converge";
+import { componentReport } from "./visual";
+import type { Baseline } from "@suluk/visual";
+
+// "info" is the non-blocking status: a gate that is honestly n/a (no env configured, no workspace open) — it
+// is shown for transparency but NEVER counts against readiness. Distinct from "warn"/"todo", which DO block.
+export type GateStatus = "ok" | "warn" | "error" | "todo" | "info";
+export interface Gate {
+  id: string;
+  title: string;
+  status: GateStatus;
+  detail: string;
+  /** the command to run to advance this gate (undefined ⇒ nothing to do) */
+  action?: string;
+}
+
+/** The CONTRACT-level ship gates — everything decidable from the document itself (no host needed). */
+export function contractGates(doc: OpenAPIv4Document, baseline: Baseline): Gate[] {
+  const gates: Gate[] = [];
+
+  // 0. non-empty — a contract with zero operations has nothing to ship, however valid/coherent it is in isolation.
+  const ops = buildAda(doc).operations.length;
+  gates.push({
+    id: "operations", title: "Has operations",
+    status: ops ? "ok" : "todo",
+    detail: ops ? `${ops} operation${ops === 1 ? "" : "s"}` : "no operations — nothing to ship",
+  });
+
+  // 1. valid v4
+  const v = validateDocument(doc);
+  gates.push({
+    id: "valid", title: "Valid v4 contract",
+    status: v.valid ? "ok" : "error",
+    detail: v.valid ? "passes the meta-schema" : `${v.errors.length} schema error${v.errors.length === 1 ? "" : "s"}`,
+    action: v.valid ? undefined : "suluk.validate",
+  });
+
+  // 2. coherent (converge)
+  const conv = convergeContract(doc);
+  const errs = conv.findings.filter((f) => f.severity === "error").length;
+  gates.push({
+    id: "coherent", title: "Coherent (no contradictions)",
+    status: errs ? "error" : "ok",
+    detail: errs ? `${errs} contradiction${errs === 1 ? "" : "s"} (dangling ref / orphan scope / …)` : "converges clean",
+    action: errs ? "suluk.convergeContract" : undefined,
+  });
+
+  // 3. pixel-confident components
+  const cr = componentReport(doc, baseline);
+  const pending = cr.confidence.missing.length + cr.confidence.drifted.length;
+  gates.push({
+    id: "confident", title: "Components pixel-confident",
+    status: cr.used.length === 0 ? "ok" : pending ? "todo" : "ok",
+    detail: cr.used.length === 0 ? "no generated components" : pending ? `${pending} primitive${pending === 1 ? "" : "s"} to verify once` : "every primitive approved + unchanged",
+    action: pending ? "suluk.previewComponents" : undefined,
+  });
+
+  return gates;
+}
+
+/** A one-line readiness summary over a set of gates (contract + host). "info" gates never count against ready. */
+export function shipSummary(gates: Gate[]): { ready: boolean; line: string } {
+  const errors = gates.filter((g) => g.status === "error").length;
+  const todos = gates.filter((g) => g.status === "todo" || g.status === "warn").length;
+  const ok = gates.filter((g) => g.status === "ok").length;
+  const info = gates.filter((g) => g.status === "info").length;
+  const ready = errors === 0 && todos === 0;
+  return {
+    ready,
+    line: ready
+      ? `ready to ship — ${ok} gate${ok === 1 ? "" : "s"} pass${info ? ` · ${info} n/a` : ""}`
+      : `${errors} blocker${errors === 1 ? "" : "s"} · ${todos} to do · ${ok}/${gates.length} pass`,
+  };
+}

package/src/visual.ts

@@ -0,0 +1,82 @@
+/**
+ * Component preview + pixel-confidence (surfaces @suluk/visual in the cockpit). A generated form/table is a
+ * COMPOSITION of widget primitives; its pixel-confidence reduces to "are all those primitives approved +
+ * unchanged?" — decided by content-hash, WITHOUT re-rendering. componentReport decomposes every entity's
+ * form/table into primitives, checks them against a baseline (confident / drifted / pending), and carries an
+ * inline control preview for each. approveComponents records the "verify once" — after that, the components are
+ * pixel-confident at that content hash forever, until a primitive's source drifts. Pure (no host) → unit-tested.
+ */
+import type { OpenAPIv4Document, SchemaOrRef } from "@suluk/core";
+import { formSpec, tableSpec, renderFormTsx, renderTableTsx, type FieldSpec, type FieldWidget } from "@suluk/shadcn";
+import {
+  formPrimitives, tablePrimitives, knownWidgets, primitiveControl,
+  checkConfidence, approve, confidenceCoverage, hash,
+  type Baseline, type UsedPrimitive, type ConfidenceReport, type Capture, type PrimitiveSources,
+} from "@suluk/visual";
+
+/** A one-field form for a widget — its REAL generated TSX is what we content-hash (so a renderer edit drifts it). */
+function canonicalField(widget: FieldWidget): FieldSpec {
+  return { name: "field", label: "Field", widget, required: true, options: widget === "select" ? ["a", "b", "c"] : undefined };
+}
+
+/**
+ * Primitive sources for the content-hash — the ACTUAL @suluk/shadcn generator output (the bytes that ship),
+ * NOT the isolated preview mock. A widget's source is renderFormTsx of a one-field form (control + layout, so a
+ * layout edit drifts every widget too); the table source is renderTableTsx. Editing render-form.ts /
+ * render-table.ts therefore drifts the affected primitives — the confidence is honest. (renderPrimitiveHtml /
+ * primitiveControl remain ONLY the human-viewable inline preview.)
+ */
+function sources(): PrimitiveSources {
+  const widgets: Record<string, string> = {};
+  for (const w of knownWidgets() as FieldWidget[]) widgets[w] = renderFormTsx({ fields: [canonicalField(w)], warnings: [] });
+  const tableLayout = renderTableTsx({ columns: [{ key: "id", header: "Id", type: "integer" }, { key: "name", header: "Name", type: "string" }], warnings: [] });
+  return { widgets, tableLayout }; // no separate formLayout marker — each widget render already carries the form layout
+}
+
+export interface ComponentReport {
+  /** the distinct primitives every generated form/table is composed of (deduped across entities) */
+  used: UsedPrimitive[];
+  confidence: ConfidenceReport;
+  /** 0..1 — fraction of used primitives that are approved + unchanged */
+  coverage: number;
+  /** primitive key → inline control HTML (widget primitives only — for the preview) */
+  preview: Record<string, string>;
+  /** which primitives each entity's form/table is built from */
+  entities: { name: string; form: string[]; table: string[] }[];
+}
+
+/** Decompose a contract's generated components into primitives and check their pixel-confidence vs a baseline. */
+export function componentReport(doc: OpenAPIv4Document, baseline: Baseline): ComponentReport {
+  const schemas = (doc.components?.schemas ?? {}) as Record<string, SchemaOrRef>;
+  const defs = schemas;
+  const src = sources();
+  const usedMap = new Map<string, UsedPrimitive>();
+  const entities: ComponentReport["entities"] = [];
+  for (const [name, schema] of Object.entries(schemas)) {
+    let fp: UsedPrimitive[] = [];
+    let tp: UsedPrimitive[] = [];
+    try { fp = formPrimitives(formSpec(schema, { defs }), src); } catch { /* schema not form-able */ }
+    try { tp = tablePrimitives(tableSpec(schema, { defs }), src); } catch { /* not table-able */ }
+    for (const p of [...fp, ...tp]) usedMap.set(p.key, p);
+    entities.push({ name, form: fp.map((p) => p.key), table: tp.map((p) => p.key) });
+  }
+  const used = [...usedMap.values()];
+  const preview: Record<string, string> = {};
+  for (const p of used) {
+    const m = p.key.match(/^widget:(.+)$/);
+    if (m) preview[p.key] = primitiveControl(m[1]);
+  }
+  return { used, confidence: checkConfidence(used, baseline), coverage: confidenceCoverage(used, baseline), preview, entities };
+}
+
+/** The "verify once": approve every used primitive at its current content hash, returning the new baseline. */
+export function approveComponents(report: ComponentReport, baseline: Baseline, at: number): Baseline {
+  const captures: Capture[] = report.used.map((p) => ({
+    key: p.key,
+    contentHash: p.contentHash,
+    // the snapshot proxy: the hash of what the operator just looked at (the control HTML, else the source hash)
+    snapshotHash: hash(report.preview[p.key] ?? p.contentHash),
+    label: p.label,
+  }));
+  return approve(captures, baseline, at);
+}

package/test/lifecycle.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe } from "bun:test";
+import { parseDocument } from "@suluk/core";
+import type { Baseline } from "@suluk/visual";
+import { componentReport, approveComponents } from "../src/visual";
+import { contractGates, shipSummary } from "../src/lifecycle";
+
+const good = () => parseDocument(`openapi: 4.0.0-candidate
+info: { title: Shop, version: 1.0.0 }
+paths:
+  "pet":
+    requests:
+      listPets: { method: get, responses: { ok: { status: 200, contentSchema: { $ref: "#/components/schemas/Pet" } } } }
+components: { schemas: { Pet: { type: object, properties: { name: { type: string } } } } }`);
+
+const gate = (gates: ReturnType<typeof contractGates>, id: string) => gates.find((g) => g.id === id)!;
+
+describe("contractGates — the contract-level ship gates", () => {
+  test("a valid, coherent contract passes valid + coherent; confidence is 'todo' against an empty baseline", () => {
+    const gates = contractGates(good(), {});
+    expect(gate(gates, "valid").status).toBe("ok");
+    expect(gate(gates, "coherent").status).toBe("ok");
+    expect(gate(gates, "confident").status).toBe("todo"); // never verified
+    expect(gate(gates, "confident").action).toBe("suluk.previewComponents");
+  });
+  test("a contradiction (a dangling $ref) makes the coherent gate an error with a fix action", () => {
+    const broken = parseDocument(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "p": { requests: { g: { method: get, responses: { ok: { status: 200, contentSchema: { $ref: "#/components/schemas/Ghost" } } } } } } }
+components: { schemas: {} }`);
+    const g = gate(contractGates(broken, {}), "coherent");
+    expect(g.status).toBe("error");
+    expect(g.action).toBe("suluk.convergeContract");
+  });
+  test("after approving the components, the confidence gate passes", () => {
+    const doc = good();
+    const baseline: Baseline = approveComponents(componentReport(doc, {}), {}, 1);
+    expect(gate(contractGates(doc, baseline), "confident").status).toBe("ok");
+  });
+  test("an empty contract (zero operations) is NOT ship-ready — the operations gate is 'todo'", () => {
+    const empty = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Empty, version: 1.0.0 }
+paths: {}`);
+    const gates = contractGates(empty, {});
+    expect(gate(gates, "operations").status).toBe("todo"); // nothing to ship
+    expect(shipSummary(gates).ready).toBe(false); // even though valid + coherent are clean
+  });
+});
+
+describe("shipSummary", () => {
+  test("all-ok gates ⇒ ready", () => {
+    const r = shipSummary([{ id: "a", title: "A", status: "ok", detail: "" }, { id: "b", title: "B", status: "ok", detail: "" }]);
+    expect(r.ready).toBe(true);
+    expect(r.line).toContain("ready to ship");
+  });
+  test("an error gate ⇒ NOT ready, counted as a blocker", () => {
+    const r = shipSummary([{ id: "a", title: "A", status: "ok", detail: "" }, { id: "b", title: "B", status: "error", detail: "" }, { id: "c", title: "C", status: "todo", detail: "" }]);
+    expect(r.ready).toBe(false);
+    expect(r.line).toContain("1 blocker");
+    expect(r.line).toContain("1 to do");
+  });
+  test("an 'info' gate is non-blocking — it never makes a clean contract read as not-ready", () => {
+    const r = shipSummary([{ id: "a", title: "A", status: "ok", detail: "" }, { id: "b", title: "B", status: "info", detail: "n/a — no environment configured" }]);
+    expect(r.ready).toBe(true);
+    expect(r.line).toContain("ready to ship");
+    expect(r.line).toContain("1 n/a"); // surfaced for transparency, but not counted against ready
+  });
+});

package/test/visual.test.ts

@@ -0,0 +1,69 @@
+import { test, expect, describe } from "bun:test";
+import { parseDocument } from "@suluk/core";
+import { contentHash, renderPrimitiveHtml, type Baseline } from "@suluk/visual";
+import { renderFormTsx } from "@suluk/shadcn";
+import { componentReport, approveComponents } from "../src/visual";
+
+const doc = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Shop, version: 1.0.0 }
+paths: {}
+components:
+  schemas:
+    Product: { type: object, required: [ name ], properties: { id: { type: integer }, name: { type: string }, sku: { type: string } } }
+    Order: { type: object, properties: { id: { type: integer }, status: { type: string, enum: [ open, closed ] } } }`);
+
+describe("componentReport — decompose generated UI into primitives", () => {
+  test("with an EMPTY baseline, every used primitive is pending (nothing confident yet)", () => {
+    const r = componentReport(doc, {});
+    expect(r.used.length).toBeGreaterThan(0);
+    expect(r.confidence.confident).toBe(false);
+    expect(r.confidence.missing.length).toBe(r.used.length);
+    expect(r.confidence.approved).toHaveLength(0);
+    expect(r.coverage).toBe(0);
+  });
+  test("decomposes each entity's form + table into shared primitives", () => {
+    const r = componentReport(doc, {});
+    const product = r.entities.find((e) => e.name === "Product")!;
+    expect(product.form.length).toBeGreaterThan(0); // form widgets
+    expect(product.table.length).toBeGreaterThan(0); // table layout/cell
+    // a text widget primitive is SHARED across entities — deduped in `used`
+    const widgetKeys = r.used.map((p) => p.key).filter((k) => k.startsWith("widget:"));
+    expect(new Set(widgetKeys).size).toBe(widgetKeys.length);
+  });
+  test("carries an inline control preview for each widget primitive", () => {
+    const r = componentReport(doc, {});
+    const widget = r.used.find((p) => p.key.startsWith("widget:"))!;
+    expect(r.preview[widget.key]).toBeTruthy();
+    expect(r.preview[widget.key]).toMatch(/<(input|select|textarea|label|div)/); // a real control fragment
+  });
+  test("a widget's content-hash tracks the REAL @suluk/shadcn renderer, not the isolated preview mock", () => {
+    const sel = componentReport(doc, {}).used.find((p) => p.key === "widget:select")!;
+    // it equals the hash of the ACTUAL generated control (renderFormTsx) — so editing render-form.ts drifts it
+    expect(sel.contentHash).toBe(contentHash(renderFormTsx({ fields: [{ name: "field", label: "Field", widget: "select", required: true, options: ["a", "b", "c"] }], warnings: [] })));
+    // and is NOT the @suluk/visual preview mock (the bug that made a real control edit never drift)
+    expect(sel.contentHash).not.toBe(contentHash(renderPrimitiveHtml({ widget: "select" })));
+  });
+});
+
+describe("approveComponents — verify once, confident forever (until drift)", () => {
+  test("after approval the SAME contract is fully confident — no re-verification", () => {
+    const before = componentReport(doc, {});
+    const baseline: Baseline = approveComponents(before, {}, 1_000);
+    const after = componentReport(doc, baseline);
+    expect(after.confidence.confident).toBe(true);
+    expect(after.confidence.missing).toHaveLength(0);
+    expect(after.confidence.drifted).toHaveLength(0);
+    expect(after.coverage).toBe(1);
+  });
+  test("adding a NEW widget (a new enum/select-backed field) leaves only the new primitive pending", () => {
+    const baseline = approveComponents(componentReport(doc, {}), {}, 1_000);
+    // a doc that introduces a date widget the baseline never approved
+    const withDate = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Shop, version: 1.0.0 }
+paths: {}
+components: { schemas: { Event: { type: object, properties: { when: { type: string, format: date } } } } }`);
+    const r = componentReport(withDate, baseline);
+    // the approved widgets stay confident; only genuinely-new primitives are pending
+    expect(r.confidence.missing.every((p) => !baseline[p.key])).toBe(true);
+  });
+});