@suluk/cockpit - v0.2.0
    Preparing search index...

    @suluk/cockpit - v0.2.0

    Suluk

    @suluk/cockpit

    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 /superadmin web panel.

    Part of Suluk — one typed OpenAPI v4 contract projecting into every full-stack layer.

    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.

    bun add @suluk/cockpit

    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.
    • 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.

    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)

    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

    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

    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

    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)

    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

    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

    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.

    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.

    Apache-2.0

    Settings

    Member Visibility

    On This Page

    InstallWhat it doesWhen to reach for itUsageAPIBoundaryLicense