@synap-core/workspace-templates 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -455,43 +455,37 @@ interface TemplateExtendsRef {
  * 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:
+ * hand-copying it. `TemplateDependency` is mirrored by hand in several other
+ * places — a comment cannot fail a build, an import can, but these mirrors live
+ * in repos this package does not own, so they must match this list EXACTLY:
  *
- *   - 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)
+ *   - marketplace            `features/marketplace/src/types.ts`
+ *   - onboarding             `features/onboarding/src/{templates/workspace-templates,components/WorkspacePreview}.ts(x)`
+ *   - browser                `InstallPackageDialog.tsx`
+ *   - synap-backend          `package-definition.ts` (`PackageDependencyKind`)
+ *   - hub-protocol REST      `rest/packages.ts` (zod enum)
+ *   - control-plane-api      `db/schema/packages.ts` (`TemplateDependency` type)
+ *                            + `routes/packages.ts` (`DEPENDENCY_KINDS` 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`.
+ * These are the 7 literals the wire accepts, in lockstep with the CP publish
+ * enum (`DEPENDENCY_KINDS = [...PACKAGE_TYPES, "automation"]`, CP
+ * `routes/packages.ts`), the hub install enum (`rest/packages.ts`), and the
+ * backend resolver's `PackageDependencyKind` (`@synap/database`).
  *
- * 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.
+ * Resolver behaviour (backend `package-dependency-resolver.ts`):
+ *   - `workspace`         → resolve+install; the ONLY kind that may `compose`.
+ *   - `capability` / `cell` → resolve+install, always `require`d (presence).
+ *   - `skill` / `workflow` / `view` / `automation` → ACCEPTED and `require`d
+ *     present, surfaced as `required-absent` (non-fatal) — no standalone by-slug
+ *     applier on the pod yet; when one grows, give the kind its own branch.
  *
- * 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.
+ * `'automation'` is legacy vocabulary: CP migration `0049_package_vocabulary`
+ * renamed the `automation` package category → `workflow` (which absorbs
+ * automation + playbook, `PACKAGE_TYPES` in CP `db/schema/packages.ts`). It
+ * stays accepted on the wire — and therefore in this tuple — for back-compat
+ * with dependencies published before the rename.
  */
-declare const PACKAGE_DEPENDENCY_KINDS: readonly ["workspace", "capability", "automation"];
+declare const PACKAGE_DEPENDENCY_KINDS: readonly ["workspace", "capability", "skill", "workflow", "view", "cell", "automation"];
 /** What a `TemplateDependency` points at. Derived — never re-declare the list. */
 type PackageDependencyKind = (typeof PACKAGE_DEPENDENCY_KINDS)[number];
 interface TemplateDependency {
@@ -499,8 +493,8 @@ interface TemplateDependency {
     slug: string;
     /**
      * What the dependency is. Default `'workspace'`. Only `'workspace'`
-     * dependencies can be `compose`d; `'capability'`/`'automation'` are always
-     * `require`d present without merging.
+     * dependencies can be `compose`d; every other kind is always `require`d
+     * present without merging.
      */
     kind?: PackageDependencyKind;
     /**
@@ -681,6 +675,19 @@ declare function listPublicTemplates(): WorkspaceYaml[];
  *   in the consumers; this door only merges arrays they already fetched.
  */
 
+/**
+ * A lightweight, QUERY-TIME summary of one sub-object a package carries (a cell
+ * today; the shape generalizes to views/automations without change). Rides the
+ * catalog LIST projection so a surface can match/surface a sub-item WITHOUT the
+ * full `definition` — it carries `key + name` only, never the sub-object's code.
+ * `kind` is DERIVED (in the CP SELECT, from which sub-array the row came from),
+ * never a stored taxonomy.
+ */
+interface PackageItemSummary {
+    kind: string;
+    key: string;
+    name: string;
+}
 /**
  * A bundled template — the canonical `WorkspaceYaml` this package ships. Callers
  * pass `listPublicTemplates()` (18) or `listWorkspaceTemplates()` (21); the door
@@ -716,6 +723,13 @@ interface RemoteEntry {
      * never "unknown-so-hide".
      */
     isPrivate?: boolean;
+    /**
+     * Lightweight computed summary of the row's sub-objects (cells), carried on the
+     * LIST projection so a surface can surface a matching sub-item without the full
+     * `definition`. `undefined` on sources that don't compute it (bundled) — treated
+     * as "no known sub-items". See `PackageItemSummary`.
+     */
+    items?: PackageItemSummary[];
     /**
      * The CP `definition` jsonb — opaque install payload. The door reads only
      * `definition.sourcePackage.version` (the winner signal). Absent on browse rows
@@ -775,6 +789,11 @@ interface CpPackageRow {
     icon?: string | null;
     /** Present only on `/mine` rows. `false` ⇒ private. Browse rows omit it. */
     isPublic?: boolean;
+    /**
+     * Computed sub-object summary from `GET /api/packages` / `/mine` (query-time,
+     * not a stored column). Carries `key + name` per cell; never the cell code.
+     */
+    items?: PackageItemSummary[];
 }
 /**
  * Map a CP list row into the merge door's `RemoteEntry`. THE canonical mapping —
@@ -800,6 +819,12 @@ interface CatalogEntryBase {
     icon?: string | null;
     /** `true` ⇒ not publicly listed (internal bundled template, or private CP row). */
     isPrivate: boolean;
+    /**
+     * The entry's sub-object summary (cells). Always present (defaults to `[]`) so a
+     * consumer can match sub-items uniformly. Bundled workspace templates carry no
+     * cells → `[]` (honest); a remote row carries its CP-computed `items`.
+     */
+    items: PackageItemSummary[];
 }
 /** A catalog entry backed by a bundled template. Install via `toWorkspaceDefinition()` / `toPackageDefinition()` on `template`. */
 interface BundledCatalogEntry extends CatalogEntryBase {