@suluk/cockpit 0.1.12 → 0.1.13

package/package.json

@@ -1,36 +1,39 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.12",
+  "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.",
-  "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 ."
-  }
+  "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

@@ -21,6 +21,8 @@ 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/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
+  });
+});