@suluk/cockpit 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",

package/src/crosscut.ts

@@ -0,0 +1,96 @@
+/**
+ * The cross-cut (M1) — the moat. The cockpit already projects all 9 layers for ONE viewer (buildCycle's
+ * principal filter). This compares ACROSS viewers: one contract, refracted through every principal, so you can
+ * see exactly which operations are gated and who can reach them. No other tool can do this, because none owns
+ * the derivation. Pure (no host) → unit-tested; the extension renders the matrix.
+ */
+import { buildAda } from "@suluk/core";
+import type { OpenAPIv4Document, Request, SecurityRequirement } from "@suluk/core";
+
+/** A viewer to project for. `scopes: undefined` ⇒ the full/operator view; `[]` ⇒ no scopes.
+ *  `authenticated` distinguishes a logged-in viewer from a truly anonymous one — an auth-only operation
+ *  (`security: [{ bearer: [] }]`, a requirement with zero scopes) is reachable by any AUTHENTICATED viewer but
+ *  NOT by anonymous. (This is more precise than the cockpit's single-principal "View as", which keys on scopes
+ *  alone; the cross-cut is the purpose-built security view.) */
+export interface Viewer {
+  label: string;
+  scopes: string[] | undefined;
+  /** does this viewer hold a credential? defaults to "holds at least one scope". */
+  authenticated?: boolean;
+}
+export interface ViewerView {
+  label: string;
+  scopes: string[] | null;
+  visible: string[];
+  hidden: string[];
+}
+export interface GatedOp {
+  operation: string;
+  detail: string;
+  /** the scope requirements (OR of AND-groups); empty ⇒ public */
+  requiredScopes: string[][];
+  /** the labels of the viewers who CAN see it */
+  visibleTo: string[];
+}
+export interface CrossCut {
+  operations: { name: string; detail: string }[];
+  viewers: ViewerView[];
+  /** operations not visible to every viewer — the scope-gated surface */
+  gated: GatedOp[];
+}
+
+function requiredScopes(req: Request): string[][] {
+  const reqs = (req.security as SecurityRequirement[] | undefined) ?? [];
+  return reqs.map((r) => Object.values(r).flat());
+}
+function visibleTo(req: Request, viewer: Viewer): boolean {
+  if (viewer.scopes === undefined) return true; // full operator view sees all
+  const reqs = requiredScopes(req);
+  if (reqs.length === 0) return true; // genuinely public op
+  const held = new Set(viewer.scopes);
+  const authed = viewer.authenticated ?? viewer.scopes.length > 0; // holding a scope implies a credential
+  // a requirement of [] (auth-only, no scope) is satisfied iff authenticated; a scoped requirement needs its scopes
+  return reqs.some((needed) => (needed.length === 0 ? authed : needed.every((s) => held.has(s))));
+}
+
+/** Every scope referenced by any operation's security requirements (sorted, deduped). */
+export function documentScopes(doc: OpenAPIv4Document): string[] {
+  return [...new Set(buildAda(doc).operations.flatMap((o) => requiredScopes(o.request).flat()))].sort();
+}
+
+/**
+ * Sensible default viewers for a document: anonymous, one per declared scope, and the full operator view —
+ * so a single command shows the whole gated surface without the user hand-entering scope sets.
+ */
+export function defaultViewers(doc: OpenAPIv4Document): Viewer[] {
+  const ops = buildAda(doc).operations;
+  const scopes = [...new Set(ops.flatMap((o) => requiredScopes(o.request).flat()))].sort();
+  // only show a distinct "authenticated" viewer when some operation requires auth WITHOUT a scope (else its
+  // column would duplicate "anonymous" — a logged-in user with no role sees the same public + scoped surface).
+  const hasAuthOnly = ops.some((o) => requiredScopes(o.request).some((r) => r.length === 0));
+  return [
+    { label: "anonymous", scopes: [], authenticated: false },
+    ...(hasAuthOnly ? [{ label: "authenticated", scopes: [] as string[], authenticated: true }] : []),
+    ...scopes.map((s) => ({ label: s, scopes: [s], authenticated: true })),
+    { label: "full", scopes: undefined },
+  ];
+}
+
+/** Project the contract through every viewer and surface the gated operations. */
+export function crossCut(doc: OpenAPIv4Document, viewers: Viewer[]): CrossCut {
+  const ops = buildAda(doc).operations.map((o) => ({ name: o.name, detail: `${o.request.method.toUpperCase()} ${o.pathTemplate}`, req: o.request }));
+  const views: ViewerView[] = viewers.map((v) => {
+    const visible: string[] = [];
+    const hidden: string[] = [];
+    for (const o of ops) (visibleTo(o.req, v) ? visible : hidden).push(o.name);
+    return { label: v.label, scopes: v.scopes ?? null, visible, hidden };
+  });
+  const gated: GatedOp[] = [];
+  for (const o of ops) {
+    const seers = views.filter((v) => v.visible.includes(o.name)).map((v) => v.label);
+    if (seers.length !== views.length) {
+      gated.push({ operation: o.name, detail: o.detail, requiredScopes: requiredScopes(o.req), visibleTo: seers });
+    }
+  }
+  return { operations: ops.map((o) => ({ name: o.name, detail: o.detail })), viewers: views, gated };
+}

package/src/cycle.ts

@@ -14,6 +14,7 @@ import type { OpenAPIv4Document, Request, SchemaOrRef, SecurityRequirement } fro
 import { audit, coverage } from "@suluk/hono";
 import { formSpec, tableSpec } from "@suluk/shadcn";
 import { costAudit, costTable, formatMicroUsd } from "@suluk/cost";
+import { readProviders } from "@suluk/builder";
 
 export type LayerStatus = "ok" | "warn" | "error" | "info";
 
@@ -26,7 +27,7 @@ export interface CycleItem {
 }
 
 export interface CycleLayer {
-  id: "data" | "contract" | "auth" | "document" | "cost" | "docs" | "state" | "ui" | "tests";
+  id: "data" | "contract" | "auth" | "document" | "cost" | "docs" | "state" | "ui" | "providers" | "tests";
   title: string;
   status: LayerStatus;
   summary: string;
@@ -140,6 +141,14 @@ export function buildCycle(doc: OpenAPIv4Document, opts: { principal?: Principal
   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(", ")}` }));
 
+  // ── providers: the swappable facet bindings recorded on the document (M3)
+  const providerBindings = readProviders(doc);
+  const providerItems: CycleItem[] = providerBindings.map((b) => ({
+    label: b.facet, ref: b.facet,
+    detail: `${b.title}${b.alternatives.length ? ` · ${b.alternatives.length} alternatives` : ""}`,
+    status: b.known ? undefined : "warn",
+  }));
+
   // ── 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 }));
@@ -168,6 +177,12 @@ export function buildCycle(doc: OpenAPIv4Document, opts: { principal?: Principal
     { 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: "providers", title: "Providers",
+      status: providerItems.length ? "ok" : "info",
+      summary: providerItems.length ? providerBindings.map((b) => `${b.facet}→${b.impl}`).join(" · ") : "none",
+      items: providerItems,
+    },
     {
       id: "tests", title: "Tests (contract checks)",
       status: checks.every((c) => c.pass) ? "ok" : "error",

package/src/index.ts

@@ -11,12 +11,16 @@ export { entityNames, generateForm, generateTable, generateStoresModule, exportV
 export { deployPlan, deployMarkdown } from "./deploy";
 export type { DeployPlan, DeployStep, DeployProvider } from "@suluk/deploy";
 // drift (OBSERVE): compare a LOCAL contract against a DEPLOYED one — the "what's drifted in prod" view (C020).
-export { diffContracts, canonical, type ContractDiff, type ChangedOp, type OpRef } from "./drift";
+export { diffContracts, canonical, type ContractDiff, type ChangedOp, type OpRef, type ProviderDelta, type ProviderChange } from "./drift";
+// cross-cut (M1): one contract refracted through every viewer — the scope-gated surface, the moat.
+export { crossCut, documentScopes, defaultViewers, type Viewer, type ViewerView, type GatedOp, type CrossCut } from "./crosscut";
 // 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.
 export {
   installModule, namespaceModule, previewInstall, gradeModule,
   ECOMMERCE, CRM, BILLING, FIRST_PARTY_REGISTRY,
+  PROVIDER_CATALOG, providerFacets, readProviders, swapProvider,
   type SulukModule, type InstallResult, type ModuleEntry, type ModuleRegistry, type ModuleGrade, type InstallPreview,
+  type ProviderImpl, type ProviderBinding,
 } from "@suluk/builder";

package/test/crosscut.test.ts

@@ -0,0 +1,81 @@
+import { test, expect, describe } from "bun:test";
+import { parseDocument } from "@suluk/core";
+import { crossCut, documentScopes, defaultViewers } from "../src/crosscut";
+
+// A petstore-ish contract: listPets/getPet are public; createPet/deletePet need write:pets; a read:secret op.
+const DOC = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Pets, version: 1.0.0 }
+paths:
+  "pet":
+    requests:
+      listPets: { method: get, responses: { ok: { status: 200 } } }
+      createPet: { method: post, security: [ { petstore_auth: [ "write:pets" ] } ], responses: { created: { status: 201 } } }
+  "pet/{id}":
+    requests:
+      getPet: { method: get, responses: { ok: { status: 200 } } }
+      deletePet: { method: delete, security: [ { petstore_auth: [ "write:pets" ] } ], responses: { deleted: { status: 204 } } }
+      auditPet: { method: get, security: [ { petstore_auth: [ "read:secret" ] } ], responses: { ok: { status: 200 } } }
+components:
+  securitySchemes:
+    petstore_auth: { type: oauth2, flows: { implicit: { authorizationUrl: "https://x/o", scopes: { "write:pets": "w", "read:secret": "r" } } } }
+`);
+
+describe("documentScopes / defaultViewers", () => {
+  test("collects every scope referenced by an operation", () => {
+    expect(documentScopes(DOC)).toEqual(["read:secret", "write:pets"]);
+  });
+  test("default viewers = anonymous + one per scope + full", () => {
+    expect(defaultViewers(DOC).map((v) => v.label)).toEqual(["anonymous", "read:secret", "write:pets", "full"]);
+  });
+});
+
+describe("crossCut — one contract through every viewer", () => {
+  const cc = crossCut(DOC, defaultViewers(DOC));
+  const view = (label: string) => cc.viewers.find((v) => v.label === label)!;
+
+  test("anonymous sees only the public operations", () => {
+    expect(view("anonymous").visible.sort()).toEqual(["getPet", "listPets"]);
+    expect(view("anonymous").hidden.sort()).toEqual(["auditPet", "createPet", "deletePet"]);
+  });
+  test("a write:pets viewer gains create/delete but NOT the read:secret op", () => {
+    expect(view("write:pets").visible.sort()).toEqual(["createPet", "deletePet", "getPet", "listPets"]);
+    expect(view("write:pets").visible).not.toContain("auditPet");
+  });
+  test("the full operator view sees everything", () => {
+    expect(view("full").hidden).toHaveLength(0);
+    expect(view("full").visible).toHaveLength(5);
+  });
+  test("the gated surface lists exactly the scope-gated operations + who can reach them", () => {
+    const gatedOps = cc.gated.map((g) => g.operation).sort();
+    expect(gatedOps).toEqual(["auditPet", "createPet", "deletePet"]);
+    const createPet = cc.gated.find((g) => g.operation === "createPet")!;
+    expect(createPet.visibleTo).toEqual(["write:pets", "full"]); // anonymous + read:secret cannot
+    expect(createPet.requiredScopes).toEqual([["write:pets"]]);
+  });
+  test("an auth-only operation (security with no scopes) is hidden from anonymous, visible to authenticated", () => {
+    const authed = parseDocument(`openapi: 4.0.0-candidate
+info: { title: A, version: 1.0.0 }
+paths:
+  "me":
+    requests:
+      getMe: { method: get, security: [ { bearerAuth: [] } ], responses: { ok: { status: 200 } } }
+      ping:  { method: get, responses: { ok: { status: 200 } } }
+components: { securitySchemes: { bearerAuth: { type: http, scheme: bearer } } }
+`);
+    const viewers = defaultViewers(authed);
+    expect(viewers.map((v) => v.label)).toContain("authenticated"); // surfaced because of the auth-only op
+    const cc = crossCut(authed, viewers);
+    const v = (l: string) => cc.viewers.find((x) => x.label === l)!;
+    expect(v("anonymous").visible).toEqual(["ping"]); // NOT getMe
+    expect(v("authenticated").visible.sort()).toEqual(["getMe", "ping"]);
+    expect(cc.gated.map((g) => g.operation)).toEqual(["getMe"]);
+    expect(cc.gated[0].visibleTo).toEqual(["authenticated", "full"]);
+  });
+  test("a fully-public contract has an empty gated surface", () => {
+    const open = parseDocument(`openapi: 4.0.0-candidate
+info: { title: Open, version: 1.0.0 }
+paths: { "a": { requests: { listA: { method: get, responses: { ok: { status: 200 } } } } } }
+`);
+    expect(crossCut(open, defaultViewers(open)).gated).toHaveLength(0);
+  });
+});

package/test/cycle.test.ts

@@ -14,8 +14,8 @@ 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("models all ten layers (incl. cost + providers)", () => {
+    expect(model.layers.map((l) => l.id)).toEqual(["data", "contract", "auth", "document", "cost", "docs", "state", "ui", "providers", "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");
@@ -110,6 +110,6 @@ describe("codegen actions land real artifacts", () => {
 
 describe("cycleSummary — flat status line", () => {
   test("returns one entry per layer", () => {
-    expect(cycleSummary(buildCycle(petstore)).length).toBe(9);
+    expect(cycleSummary(buildCycle(petstore)).length).toBe(10);
   });
 });

package/test/drift.test.ts

@@ -139,6 +139,15 @@ paths: { "p": { requests: { g: { method: get, responses: { ok: { status: 200 } }
     expect(c.changes.some((x) => x.includes("shape"))).toBe(true); // the residual is not suppressed
   });
 
+  test("provider-slot drift (x-suluk-providers) is reported", () => {
+    const local = { openapi: "4.0.0-candidate", info: { title: "T", version: "1.0.0" }, paths: {}, "x-suluk-providers": { payments: "paddle", email: "resend" } } as unknown as Parameters<typeof diffContracts>[0];
+    const deployed = { openapi: "4.0.0-candidate", info: { title: "T", version: "1.0.0" }, paths: {}, "x-suluk-providers": { payments: "stripe" } } as unknown as Parameters<typeof diffContracts>[0];
+    const d = diffContracts(local, deployed);
+    expect(d.identical).toBe(false);
+    expect(d.providers.changed).toEqual([{ facet: "payments", from: "stripe", to: "paddle" }]);
+    expect(d.providers.added).toEqual([{ facet: "email", impl: "resend" }]);
+    expect(d.summary).toContain("providers");
+  });
   test("canonical() is cycle-safe (does not overflow the stack)", () => {
     const a: Record<string, unknown> = { x: 1 };
     a.self = a;

package/test/module-cycle.test.ts

@@ -43,4 +43,10 @@ describe("installModule → the cockpit cycle lights up", () => {
   test("the document still validates against the v4 meta-schema after the merge", () => {
     expect(after.valid).toBe(true);
   });
+  test("the Providers layer lights up with the module's provider slot (payments→stripe)", () => {
+    const providers = layer(after, "providers");
+    expect(providers.summary).toContain("payments→stripe");
+    expect(providers.items.map((i) => i.label)).toContain("payments");
+    expect(layer(before, "providers").summary).toBe("none"); // the host had no provider slots
+  });
 });