@synap-core/workspace-templates 0.6.0 → 0.6.1

package/dist/index.d.ts

@@ -269,6 +269,49 @@ interface TemplateExtendsRef {
  * `grants` → `operations`). Distinct from `extends` (which imports from a live
  * workspace, tRPC-only) — `dependencies` is template→template.
  */
+/**
+ * PACKAGE_DEPENDENCY_KINDS — the dependency-kind vocabulary, declared ONCE.
+ *
+ * This tuple exists so consumers can IMPORT the vocabulary instead of
+ * hand-copying it. `TemplateDependency` is currently mirrored by hand in six
+ * other places, four of which carry a comment promising they match "VERBATIM so
+ * the wire shape never drifts" — a comment doing a type's job. A comment cannot
+ * fail a build; an import can. Those mirrors live in repos this package does not
+ * own, so this tuple does not fix them by existing — it makes the fix possible:
+ *
+ *   - marketplace            `types.ts:102`
+ *   - onboarding             `workspace-templates.ts:27`
+ *   - synap-backend          `package-definition.ts:204` (exports its own
+ *                            `PackageDependencyKind` — the closest peer)
+ *   - hub-protocol REST      `rest/packages.ts:140` (zod enum)
+ *   - browser                `InstallPackageDialog.tsx:262`
+ *   - control-plane-api      `routes/packages.ts:436` (zod enum)
+ *
+ * ⚠️ `'automation'` IS RETIRED VOCABULARY, deliberately still listed here.
+ * CP migration `0049_package_vocabulary` retired the `automation` package
+ * category in favour of `workflow` ("workflow — a triggered/sequenced run
+ * (absorbs 'automation' + 'playbook')", `PACKAGE_TYPES` in CP
+ * `db/schema/packages.ts`). A dependency's `kind` names the TYPE of package it
+ * points at, so this vocabulary should track `PACKAGE_TYPES` — meaning the live
+ * spelling is `workflow`, not `automation`.
+ *
+ * It is NOT renamed here, on purpose. This is latent, not live: 0/21 templates
+ * declare any `kind` other than the default `'workspace'`. And all four wire
+ * enums (CP + hub zod, above) still accept `'automation'` and do NOT accept
+ * `'workflow'` — so emitting `'workflow'` today would be rejected with a 400 at
+ * both doors, and dropping `'automation'` from this tuple would make any
+ * consumer that derives a zod enum from it start rejecting a value the wire
+ * still legally accepts (a published third-party package may carry it; CP's own
+ * schema permits it). Narrowing must therefore follow the wire, not lead it.
+ *
+ * ORDERED FIX (each step deployable alone, no flag day):
+ *   1. Widen the CP + hub zod enums to accept BOTH `'automation'` and `'workflow'`.
+ *   2. Add `'workflow'` here; mark `'automation'` deprecated; migrate any authored use.
+ *   3. Once no payload carries `'automation'`, drop it from the wire enums and this tuple.
+ */
+declare const PACKAGE_DEPENDENCY_KINDS: readonly ["workspace", "capability", "automation"];
+/** What a `TemplateDependency` points at. Derived — never re-declare the list. */
+type PackageDependencyKind = (typeof PACKAGE_DEPENDENCY_KINDS)[number];
 interface TemplateDependency {
     /** Slug of the template/package this one depends on. */
     slug: string;
@@ -277,7 +320,7 @@ interface TemplateDependency {
      * dependencies can be `compose`d; `'capability'`/`'automation'` are always
      * `require`d present without merging.
      */
-    kind?: 'workspace' | 'capability' | 'automation';
+    kind?: PackageDependencyKind;
     /**
      * How this template relates to the dependency:
      * - `'compose'`: this template is an OVERLAY on the dependency's workspace.
@@ -385,8 +428,171 @@ declare const WORKSPACE_TEMPLATES: Record<string, WorkspaceYaml>;
 type WorkspaceTemplateSlug = keyof typeof WORKSPACE_TEMPLATES;
 declare function getWorkspaceTemplate(slug: string): WorkspaceYaml | undefined;
 declare function listWorkspaceTemplates(): WorkspaceYaml[];
+/**
+ * Public templates only (`meta.isPublic !== false`). This is a CONVENIENCE
+ * filter for the default picker — NOT a security boundary: the private YAML
+ * still ships in the published tarball, so anything that must not leak cannot
+ * rely on this. `listWorkspaceTemplates()` returns all of them (CLI, seeder,
+ * tripwire need the full set). Publicity is also expressed per-entry as
+ * `CatalogEntry.isPrivate` by `mergeCatalog()`, so a caller can pass ALL
+ * templates and filter at the presentation layer instead of choosing a list
+ * function up front — the merge door itself never filters (it stays pure).
+ */
 declare function listPublicTemplates(): WorkspaceYaml[];
 
+/**
+ * mergeCatalog — the ONE merge door for the workspace-template catalog.
+ * ====================================================================
+ *
+ * Both marketplace entry points (browser + CLI) and the pod need to show ONE
+ * list of installable workspace templates drawn from TWO sources:
+ *
+ *   1. BUNDLED — the canonical `@synap-core/workspace-templates` package that
+ *      ships inside every client (this package). Always present, zero network.
+ *   2. REMOTE  — rows in the control-plane package registry (`GET /api/packages`),
+ *      which includes both the official templates re-published by
+ *      `seed-templates.ts` AND private / third-party packages that never shipped
+ *      in the bundle.
+ *
+ * The two overlap: every official template exists in BOTH sources (once bundled,
+ * once seeded to the CP). Naively concatenating them shows 21 duplicate cards.
+ * `mergeCatalog` de-dupes them into ONE catalog with a deterministic winner.
+ *
+ * WHY THIS LIVES HERE (and is PURE):
+ *   This is the ONLY module the root `pnpm-workspace.yaml` lets `synap-cli`,
+ *   `browser`, `synap-control-plane-api`, AND `synap-backend/packages/api` all
+ *   resolve. `@synap-core/marketplace` pulls React and is `private: true`, so the
+ *   Node CLI cannot import it. Keep this file pure data — no fetch, no auth, no
+ *   React, no Node-only APIs. Each entry point has a DIFFERENT transport (browser
+ *   cookie/`cpFetch`, CLI Bearer, pod anonymous); a door that fetched would force
+ *   ONE auth model on all three and become the next lossy seam. Transport lives
+ *   in the consumers; this door only merges arrays they already fetched.
+ */
+
+/**
+ * A bundled template — the canonical `WorkspaceYaml` this package ships. Callers
+ * pass `listPublicTemplates()` (18) or `listWorkspaceTemplates()` (21); the door
+ * merges whatever it is given and does NOT filter (see the publicity note below).
+ */
+type BundledEntry = WorkspaceYaml;
+/**
+ * A control-plane registry row, mapped into the minimal shape the door needs.
+ * Consumers build this from a `MarketplacePackage` (browser) / the CP
+ * `GET /api/packages` JSON (CLI) — a thin, transport-specific projection.
+ *
+ * `definition` is carried OPAQUE: it is both (a) the install payload the consumer
+ * feeds back to the pod, and (b) the home of the ONE comparable version signal,
+ * `definition.sourcePackage.version` — the real npm semver of the published
+ * `@synap-core/workspace-templates` build that generated an official row
+ * (`seed-templates.ts` stamps it). The door only reads that one nested field; the
+ * rest of `definition` is passed through untouched.
+ */
+interface RemoteEntry {
+    slug: string;
+    name: string;
+    description?: string;
+    /** CP package category / type (e.g. `"workspace"`, `"view"`). */
+    category?: string;
+    tags?: string[];
+    icon?: string | null;
+    /**
+     * `true` when the CP row is not publicly listed (`isPublic === false`). Browse
+     * rows leave this `undefined` BY CONSTRUCTION — the browse route hard-filters
+     * `WHERE is_public = true`, so every browse row is public; `undefined` ⇒ public,
+     * never "unknown-so-hide".
+     */
+    isPrivate?: boolean;
+    /**
+     * The CP `definition` jsonb — opaque install payload. The door reads only
+     * `definition.sourcePackage.version` (the winner signal). Absent on browse rows
+     * (the list route strips `definition`), which is fine: absence ⇒ bundle wins.
+     */
+    definition?: {
+        sourcePackage?: {
+            name?: string;
+            version?: string;
+        };
+        [k: string]: unknown;
+    };
+}
+/** Whether the caller could reach / authenticate against the remote source. */
+type RemoteSourceStatus = "ok" | "unauthenticated" | "unreachable";
+interface MergeCatalogInput {
+    /** Bundled templates (this package). Always "ok" — it is in-process data. */
+    bundled: BundledEntry[];
+    /** Already-fetched CP rows. Empty/omitted when the fetch failed. */
+    remote?: RemoteEntry[];
+    /**
+     * This client's bundled-package version (`package.json` `version`, live `0.6.0`).
+     * Compared against each remote row's `sourcePackage.version` to decide whether
+     * THIS client's bundle is stale. Callers pass the compiled-in package version.
+     */
+    bundleVersion: string;
+    /**
+     * The transport's verdict on the remote fetch. `"ok"` (default) ⇒ merge the
+     * `remote` array. `"unauthenticated"` / `"unreachable"` ⇒ ignore `remote` and
+     * surface the degradation in `sources.remote`, so the consumer can render
+     * "18 available — private ones need login" instead of FAILING OPEN EMPTY.
+     */
+    remoteStatus?: RemoteSourceStatus;
+}
+interface CatalogEntryBase {
+    slug: string;
+    name: string;
+    description?: string;
+    /** Package category / type. Bundled templates are always `"workspace"`. */
+    category?: string;
+    tags: string[];
+    icon?: string | null;
+    /** `true` ⇒ not publicly listed (internal bundled template, or private CP row). */
+    isPrivate: boolean;
+}
+/** A catalog entry backed by a bundled template. Install via `toWorkspaceDefinition()` / `toPackageDefinition()` on `template`. */
+interface BundledCatalogEntry extends CatalogEntryBase {
+    source: "bundled";
+    template: WorkspaceYaml;
+}
+/** A catalog entry backed by a CP registry row. Install from `remote.definition`. */
+interface RemoteCatalogEntry extends CatalogEntryBase {
+    source: "remote";
+    remote: RemoteEntry;
+}
+/** One merged card. `source` discriminates the install path; common fields feed a picker. */
+type CatalogEntry = BundledCatalogEntry | RemoteCatalogEntry;
+interface MergeCatalogResult {
+    entries: CatalogEntry[];
+    /**
+     * Per-source health. LOAD-BEARING, not decoration: it is what lets a consumer
+     * distinguish "remote returned nothing" from "remote unreachable" and avoid the
+     * FAILS-OPEN-EMPTY trap (agent sees empty catalog → thinks pod is empty → dupes).
+     */
+    sources: {
+        bundled: "ok";
+        remote: RemoteSourceStatus;
+    };
+}
+/**
+ * Merge bundled + remote template catalogs into ONE de-duplicated list.
+ *
+ * DEDUPE KEY = `slug` — NOT `slug@version`. This is forced by the live data, not
+ * a preference: every CP flagship row is hardcoded `version: "1.0.0"`
+ * (`seed-templates.ts`) and `TemplateMeta` carries NO version field at all, so a
+ * `slug@version` key would collide on nothing → 21 duplicate cards. The real
+ * per-build version lives only in `definition.sourcePackage.version`, which is
+ * the WINNER signal, never the identity key.
+ *
+ * CONFLICT RESOLUTION (remote slug already claimed by a bundled template):
+ *   • remote `sourcePackage.version` strictly > `bundleVersion` → remote wins
+ *     (this client is stale — the CP has a fresher official build).
+ *   • otherwise (equal / older / no `sourcePackage`) → BUNDLE wins. The
+ *     no-`sourcePackage` case is a third-party package SQUATTING an official slug;
+ *     the bundle wins unconditionally (squatting defense).
+ *
+ * A remote slug that does NOT collide with any bundled template is a DISTINCT
+ * entry (a private or third-party package) and is always kept.
+ */
+declare function mergeCatalog(input: MergeCatalogInput): MergeCatalogResult;
+
 /**
  * @synap-core/workspace-templates — Definition adapter
  *
@@ -399,6 +605,24 @@ declare function listPublicTemplates(): WorkspaceYaml[];
  * shape never drifts per call-site.
  */
 
+/** A widget block as the wire expects it: `bentoLayout[]`, keyed by `widgetType`. */
+interface BentoWidgetBlockWire {
+    widgetType: string;
+    pos: TemplateBentoBlock['pos'];
+    config?: Record<string, unknown>;
+}
+/** A view block as the wire expects it: `bentoViewBlocks[]`, keyed by `viewName`. */
+interface BentoViewBlockWire {
+    kind: 'view';
+    viewName: string;
+    pos: TemplateBentoBlock['pos'];
+    overrides?: Record<string, unknown>;
+}
+interface SplitBentoBlocks {
+    bentoLayout: BentoWidgetBlockWire[];
+    bentoViewBlocks: BentoViewBlockWire[];
+}
+declare function splitBentoBlocks(blocks: TemplateBentoBlock[] | undefined): SplitBentoBlocks;
 /** The flat definition object accepted by createFromDefinition. */
 interface WorkspaceDefinitionInput {
     workspaceName: string;
@@ -412,7 +636,16 @@ interface WorkspaceDefinitionInput {
     displayTemplates?: WorkspaceYaml['displayTemplates'];
     layoutConfig: WorkspaceYaml['layout'] | undefined;
     bentoViewName?: string;
-    bentoViewBlocks?: NonNullable<WorkspaceYaml['bento']>['blocks'];
+    /**
+     * WIDGET half of the authored bento union. The door declares this field
+     * (`workspaces.createFromDefinition` zod) and the pod maps it as widgets via
+     * `widget.widgetType`. It was missing from this interface entirely, which is
+     * why `toWorkspaceDefinition` had nowhere to put widgets and dumped the whole
+     * union into `bentoViewBlocks` — where every widget was silently filtered out.
+     */
+    bentoLayout?: BentoWidgetBlockWire[];
+    /** VIEW half of the authored bento union — resolved against the viewMap. */
+    bentoViewBlocks?: BentoViewBlockWire[];
     profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
     workspaceSubtype?: string;
     workspaceType?: NonNullable<WorkspaceYaml['workspace']>['workspaceType'];
@@ -477,7 +710,17 @@ interface PackageDefinitionOutput {
     suggestedRelations?: WorkspaceYaml['suggestedRelations'];
     displayTemplates?: WorkspaceYaml['displayTemplates'];
     entityLinks?: WorkspaceYaml['entityLinks'];
-    bentoLayout?: NonNullable<WorkspaceYaml['bento']>['blocks'];
+    /** WIDGET half of the authored bento union — mapped by the pod via `widgetType`. */
+    bentoLayout?: BentoWidgetBlockWire[];
+    /**
+     * VIEW half of the authored bento union. Widgets go to `bentoLayout`, views
+     * here — the pod splits by field (create-workspace-from-definition.ts:1373
+     * reads `bentoViewBlocks`), so both wire fields must be carried. The apply
+     * door's `PackageApplySchema` now declares this field (it is a plain
+     * `z.object`, so an undeclared field would be silently stripped) — the inbound
+     * seam is closed to match this outbound emit.
+     */
+    bentoViewBlocks?: BentoViewBlockWire[];
     bentoViewName?: string;
     profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
     layoutConfig?: WorkspaceYaml['layout'];
@@ -495,4 +738,4 @@ interface PackageDefinitionOutput {
  */
 declare function toPackageDefinition(slugOrYaml: string | WorkspaceYaml): PackageDefinitionOutput;
 
-export { type PackageDefinitionOutput, type TemplateAppKind, type TemplateAppRef, type TemplateAutomation, type TemplateBentoBlock, type TemplateDefaultSource, type TemplateDependency, type TemplateDisplayTemplate, type TemplateEntityLink, type TemplateExtendsRef, type TemplateIntegration, type TemplateLayoutConfig, type TemplateMeta, type TemplateOnboarding, type TemplateOnboardingCollectTarget, type TemplatePlaybook, type TemplatePlaybookParam, type TemplateProfile, type TemplateProfileEntityBentoTemplates, type TemplateProperty, type TemplateSeedEntity, type TemplateSidebarItem, type TemplateSidebarSurface, type TemplateSourceRole, type TemplateSuggestedRelation, type TemplateView, type ToDefinitionResult, WORKSPACE_TEMPLATES, type WorkspaceDefinitionInput, type WorkspaceTemplateSlug, type WorkspaceYaml, getWorkspaceTemplate, listPublicTemplates, listWorkspaceTemplates, toPackageDefinition, toWorkspaceDefinition };
+export { type BentoViewBlockWire, type BentoWidgetBlockWire, type BundledCatalogEntry, type BundledEntry, type CatalogEntry, type MergeCatalogInput, type MergeCatalogResult, PACKAGE_DEPENDENCY_KINDS, type PackageDefinitionOutput, type PackageDependencyKind, type RemoteCatalogEntry, type RemoteEntry, type RemoteSourceStatus, type SplitBentoBlocks, type TemplateAppKind, type TemplateAppRef, type TemplateAutomation, type TemplateBentoBlock, type TemplateDefaultSource, type TemplateDependency, type TemplateDisplayTemplate, type TemplateEntityLink, type TemplateExtendsRef, type TemplateIntegration, type TemplateLayoutConfig, type TemplateMeta, type TemplateOnboarding, type TemplateOnboardingCollectTarget, type TemplatePlaybook, type TemplatePlaybookParam, type TemplateProfile, type TemplateProfileEntityBentoTemplates, type TemplateProperty, type TemplateSeedEntity, type TemplateSidebarItem, type TemplateSidebarSurface, type TemplateSourceRole, type TemplateSuggestedRelation, type TemplateView, type ToDefinitionResult, WORKSPACE_TEMPLATES, type WorkspaceDefinitionInput, type WorkspaceTemplateSlug, type WorkspaceYaml, getWorkspaceTemplate, listPublicTemplates, listWorkspaceTemplates, mergeCatalog, splitBentoBlocks, toPackageDefinition, toWorkspaceDefinition };