@synap-core/workspace-templates 0.5.0 → 0.6.1

package/src/define.ts

@@ -10,8 +10,106 @@
  * shape never drifts per call-site.
  */
 
-import type { WorkspaceYaml } from './types.js';
-import { getWorkspaceTemplate } from './templates.js';
+import type { TemplateBentoBlock, WorkspaceYaml } from "./types.js";
+import { getWorkspaceTemplate } from "./templates.js";
+
+/** A widget block as the wire expects it: `bentoLayout[]`, keyed by `widgetType`. */
+export interface BentoWidgetBlockWire {
+  widgetType: string;
+  pos: TemplateBentoBlock['pos'];
+  config?: Record<string, unknown>;
+}
+
+/** A view block as the wire expects it: `bentoViewBlocks[]`, keyed by `viewName`. */
+export interface BentoViewBlockWire {
+  kind: 'view';
+  viewName: string;
+  pos: TemplateBentoBlock['pos'];
+  overrides?: Record<string, unknown>;
+}
+
+export interface SplitBentoBlocks {
+  bentoLayout: BentoWidgetBlockWire[];
+  bentoViewBlocks: BentoViewBlockWire[];
+}
+
+/**
+ * Split the authored `bento.blocks` DISCRIMINATED UNION into the TWO wire
+ * fields the pod expects. This is the whole point: `TemplateBentoBlock` is one
+ * array discriminated by `kind`, but the pod does NOT read `kind` — it splits by
+ * FIELD (`create-workspace-from-definition.ts`):
+ *
+ *   - `bentoLayout`     → mapped as widgets, reads `widget.widgetType`
+ *   - `bentoViewBlocks` → filtered against `viewMap[vb.viewSlug ?? vb.viewName]`,
+ *                         unknown entries DROPPED with a logger.warn
+ *
+ * Dumping the whole union into either single field silently mis-routes the other
+ * half — which is exactly what both converters used to do:
+ *   - `toWorkspaceDefinition` sent all blocks as `bentoViewBlocks`, so widgets
+ *     (no `viewName`) hit `viewMap[undefined]` and were filtered out.
+ *   - `toPackageDefinition` sent all blocks as `bentoLayout`, so view blocks
+ *     (no `widgetType`) became widgets with `widgetType: undefined`.
+ * Net: nobody had ever seen an authored bento render as authored.
+ *
+ * Blocks are emitted in the EXACT shape each sink declares (the tRPC
+ * `createFromDefinition` zod is strict: `bentoLayout` requires `widgetType`,
+ * `bentoViewBlocks` requires `kind: 'view'` + `viewName`), so a widget's
+ * `overrides` and a view's `config` are not smuggled into the wrong sink.
+ * Authored order is preserved WITHIN each kind; the pod concatenates
+ * `[...widgetBlocks, ...viewBlocks]`, so cross-kind order is the pod's to define.
+ *
+ * `kind` is INFERRED from field presence when absent. `TemplateBentoBlock.kind`
+ * is a required field in TypeScript, but the generated `templates.ts` casts the
+ * parsed YAML `as unknown as Record<string, WorkspaceYaml>` — so the compiler
+ * never checks the authored data against the type, and `agent-fleet.yaml`
+ * authored 8 widget blocks with no `kind:` at all (bare `widgetType`). Routing
+ * strictly on `kind` would silently DROP those — the exact failure mode this
+ * function exists to end. Inferring by field mirrors what the pod itself does
+ * (it splits by field and never reads `kind`), so the seam is total: a block
+ * that CAN be materialized always is. `scripts/check-converters.mjs` is the
+ * strict half — it fails the build if an authored block omits `kind` — so this
+ * leniency is a safety net, not a place for drift to hide.
+ */
+function resolveBlockKind(block: TemplateBentoBlock): 'widget' | 'view' | null {
+  if (block.kind === 'widget' || block.kind === 'view') return block.kind;
+  if (block.widgetType) return 'widget';
+  if (block.viewName) return 'view';
+  return null;
+}
+
+export function splitBentoBlocks(
+  blocks: TemplateBentoBlock[] | undefined
+): SplitBentoBlocks {
+  const bentoLayout: BentoWidgetBlockWire[] = [];
+  const bentoViewBlocks: BentoViewBlockWire[] = [];
+
+  for (const block of blocks ?? []) {
+    const kind = resolveBlockKind(block);
+    if (kind === 'widget') {
+      // A widget block without `widgetType` cannot be rendered — the pod would
+      // create a `widgetType: undefined` block. Drop it loudly rather than ship
+      // a broken block; the build-time guard asserts this never happens in the
+      // authored templates.
+      if (!block.widgetType) continue;
+      bentoLayout.push({
+        widgetType: block.widgetType,
+        pos: block.pos,
+        ...(block.config ? { config: block.config } : {}),
+      });
+    } else if (kind === 'view') {
+      // Same reasoning: the pod filters unknown/absent view names anyway.
+      if (!block.viewName) continue;
+      bentoViewBlocks.push({
+        kind: 'view',
+        viewName: block.viewName,
+        pos: block.pos,
+        ...(block.overrides ? { overrides: block.overrides } : {}),
+      });
+    }
+  }
+
+  return { bentoLayout, bentoViewBlocks };
+}
 
 /** The flat definition object accepted by createFromDefinition. */
 export interface WorkspaceDefinitionInput {
@@ -26,7 +124,16 @@ export 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'];
   // Workspace-level metadata (flattened from the `workspace` block)
   workspaceSubtype?: string;
@@ -37,6 +144,15 @@ export interface WorkspaceDefinitionInput {
   defaultSources?: NonNullable<WorkspaceYaml['workspace']>['defaultSources'];
   /** Per-workspace onboarding context — written to settings.onboarding. */
   onboarding?: WorkspaceYaml['onboarding'];
+  /**
+   * Template-composition dependencies. MUST be forwarded: the backend resolves
+   * these BEFORE materializing this workspace (`workspaces.createFromDefinition`
+   * → `materializeWorkspaceCore` Step 0 → `resolvePackageDependencies`), which
+   * is what installs a `require`d base FIRST and makes shared-profile base
+   * seeding deterministic. Dropping this field silently de-orders provisioning
+   * on the tRPC/UI door — see the note in `toWorkspaceDefinition`.
+   */
+  dependencies?: WorkspaceYaml['dependencies'];
 }
 
 export interface ToDefinitionResult {
@@ -68,6 +184,10 @@ export function toWorkspaceDefinition(
   const name = nameOverride ?? ws.name;
   const proposalId = ws.proposalId ?? `${tpl.meta.slug}-v1`;
 
+  // The authored `bento.blocks` union must be ROUTED, not forwarded: the pod
+  // splits by field, not by `kind`. See `splitBentoBlocks`.
+  const bento = splitBentoBlocks(tpl.bento?.blocks);
+
   const definition: WorkspaceDefinitionInput = {
     workspaceName: name,
     description: ws.description,
@@ -80,7 +200,8 @@ export function toWorkspaceDefinition(
     displayTemplates: tpl.displayTemplates,
     layoutConfig: tpl.layout,
     bentoViewName: tpl.bento?.viewName,
-    bentoViewBlocks: tpl.bento?.blocks,
+    bentoLayout: bento.bentoLayout,
+    bentoViewBlocks: bento.bentoViewBlocks,
     profileEntityBentoTemplates: tpl.profileEntityBentoTemplates,
     workspaceSubtype: ws.subtype,
     workspaceType: ws.workspaceType,
@@ -89,11 +210,106 @@ export function toWorkspaceDefinition(
     sourceRoles: ws.sourceRoles,
     defaultSources: ws.defaultSources,
     onboarding: tpl.onboarding,
+    // Template-composition dependencies — forwarded so the tRPC/UI door gets the
+    // SAME deps-first ordering the CLI/Hub door gets via `toPackageDefinition`.
+    // `workspaces.createFromDefinition` declares `dependencies` in its zod input
+    // and branches on `input.definition.dependencies?.length` to run
+    // `materializeWorkspaceCore` (Step 0 = `resolvePackageDependencies`) BEFORE
+    // creating this workspace. Omitting it here made that branch dead on every
+    // frontend call-site, so a `require: foundation` dep was silently dropped and
+    // shared-profile bases were seeded by whichever template happened to apply
+    // first. This function is documented as "the single canonical seam" — it only
+    // is one if it forwards the fields the wire shape declares.
+    dependencies: tpl.dependencies,
   };
 
   return { definition, proposalId, workspaceName: name, templateId: tpl.meta.slug };
 }
 
+// ─── Exhaustiveness ledger: toWorkspaceDefinition ────────────────────────────
+// `WorkspaceYaml` is read by two converters and nothing forced either to be
+// total — which is how `dependencies` was silently dropped here for months.
+// Every key of `WorkspaceYaml` must be classified below as either FORWARDED
+// onto the wire or explicitly DROPPED with a reason. Adding a field to
+// `WorkspaceYaml` FAILS THE BUILD until it is classified, forcing the author
+// to make the forward-or-drop decision instead of defaulting to silent loss.
+//
+// ⚠️ KNOW WHAT THIS LEDGER DOES NOT CATCH. It is FIELD-PRESENCE-exhaustive, not
+// SEMANTICS-exhaustive. It asks "is every key classified?" — not "does the value
+// reach the right sink?". `bento` was classified as forwarded, and it WAS
+// forwarded: the whole discriminated union was dumped into ONE field on each
+// door (`bentoViewBlocks` here, `bentoLayout` in `toPackageDefinition`). The
+// ledger passed while widgets were filtered out on one door and views became
+// `widgetType: undefined` widgets on the other. A ledger entry is a CLAIM about
+// routing; only a runtime assertion can check the claim.
+// → The counterpart guard for that class is `scripts/check-converters.mjs`,
+//   which RUNS both converters over all templates and asserts the per-kind
+//   block counts survive the split. Any future union-shaped field (one authored
+//   array fanning out to N wire fields) needs an assertion there too — do not
+//   let a ledger comment stand in for one.
+
+/** Keys `toWorkspaceDefinition` reads and carries onto the wire. */
+type WorkspaceDefinitionForwarded =
+  | 'meta'          // → proposalId (meta.slug) + templateId; not a wire field itself
+  | 'workspace'     // flattened into workspaceName/description/workspaceType/…
+  | 'profiles'
+  | 'views'
+  | 'entityLinks'
+  | 'seedEntities'
+  | 'suggestedRelations'
+  | 'displayTemplates'
+  | 'layout'        // → layoutConfig
+  | 'bento'         // → bentoViewName + bentoLayout (widgets) + bentoViewBlocks (views)
+  | 'profileEntityBentoTemplates'
+  | 'onboarding'
+  | 'dependencies';
+
+/**
+ * Keys deliberately NOT forwarded by `toWorkspaceDefinition`. Each needs a
+ * one-line WHY. "The door has no such field" = forwarding is a no-op; anything
+ * else is a real gap and should say so.
+ */
+type WorkspaceDefinitionDropped =
+  // UI-only: `workspaces.createFromDefinition` has no `app` field. Consumers
+  // read `template.app` straight off the YAML to pick the first screen, so this
+  // never belonged on the wire.
+  | 'app'
+  // The door DOES accept `extends`, but no template declares it today (0/21).
+  // Forwarding is a no-op until one does — wire it then.
+  | 'extends'
+  // The door DOES accept `automations`, but no template declares it today
+  // (0/21), and its zod shape ({trigger,action:{playbook_run}}) is not
+  // `TemplateAutomation`. Needs a mapper if a template ever uses it.
+  // The browser install path installs automations via its own createAutomation door.
+  | 'automations'
+  // The door has no `integrations` field. Its `tools` field is a DIFFERENT
+  // shape ({name,kind,inputSchema} vs {templateKey,params,mode}). Capability
+  // templates are seeded via the packages/apply path, not createFromDefinition
+  // — see the note on `TemplateIntegration` in types.ts. Forwarding = no-op.
+  | 'integrations'
+  // REAL GAP (agent-fleet, project-management declare playbooks). The door
+  // accepts `playbooks`, but the shapes disagree: template param `type` allows
+  // 'text'|'entity'|'choice', the tRPC enum accepts only string|number|boolean
+  // (and defaultValue↔default, grants: string[]↔{kind,ref}[]). Raw forwarding =
+  // zod BAD_REQUEST. Needs a param mapper — separate wave, not a silent drop.
+  | 'playbooks';
+
+type UnclassifiedWorkspaceDefinitionKey = Exclude<
+  keyof WorkspaceYaml,
+  WorkspaceDefinitionForwarded | WorkspaceDefinitionDropped
+>;
+
+// If this errors, a new `WorkspaceYaml` field is unclassified. Forward it in
+// `toWorkspaceDefinition` and add it to `WorkspaceDefinitionForwarded`, or add
+// it to `WorkspaceDefinitionDropped` with a one-line WHY.
+const _workspaceDefinitionLedger: [UnclassifiedWorkspaceDefinitionKey] extends [never]
+  ? true
+  : [
+      'UNCLASSIFIED YAML FIELD — forward it or add it to WorkspaceDefinitionDropped:',
+      UnclassifiedWorkspaceDefinitionKey,
+    ] = true;
+void _workspaceDefinitionLedger;
+
 /**
  * The unified `PackageDefinition` shape consumed by `POST /api/hub/packages/apply`
  * (CLI `synap launch`) and the CP package registry seeder. It composes the
@@ -125,13 +341,25 @@ export 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'];
   capabilities?: WorkspaceYaml['integrations'];
   playbooks?: WorkspaceYaml['playbooks'];
   onboarding?: WorkspaceYaml['onboarding'];
+  /** Template-composition dependencies — resolved by the apply endpoint. */
+  dependencies?: WorkspaceYaml['dependencies'];
 }
 
 /**
@@ -151,6 +379,9 @@ export function toPackageDefinition(
   }
 
   const ws = tpl.workspace;
+  // Same routing as the tRPC door — the union is split by `kind`, never dumped
+  // whole into one field. See `splitBentoBlocks`.
+  const bento = splitBentoBlocks(tpl.bento?.blocks);
   return {
     _meta: {
       slug: tpl.meta.slug,
@@ -173,12 +404,67 @@ export function toPackageDefinition(
     suggestedRelations: tpl.suggestedRelations,
     displayTemplates: tpl.displayTemplates,
     entityLinks: tpl.entityLinks,
-    bentoLayout: tpl.bento?.blocks,
+    bentoLayout: bento.bentoLayout,
+    bentoViewBlocks: bento.bentoViewBlocks,
     bentoViewName: tpl.bento?.viewName,
     profileEntityBentoTemplates: tpl.profileEntityBentoTemplates,
     layoutConfig: tpl.layout,
     capabilities: tpl.integrations,
     playbooks: tpl.playbooks,
     onboarding: tpl.onboarding,
+    dependencies: tpl.dependencies,
   };
 }
+
+// ─── Exhaustiveness ledger: toPackageDefinition ──────────────────────────────
+// Same forcing function as above, for the OTHER converter. These two are NOT
+// merged on purpose: they target different endpoints with different contracts
+// (`PackageDefinition` is a superset with renames — seedEntities→suggestedEntities,
+// bento.blocks→bentoLayout, integrations→capabilities, plus `_meta`). Keeping
+// two converters is fine; keeping either one lossy-by-accident is not.
+
+/** Keys `toPackageDefinition` reads and carries onto the wire. */
+type PackageDefinitionForwarded =
+  | 'meta'          // → _meta
+  | 'workspace'     // flattened into workspaceName/description/workspaceType/…
+  | 'profiles'
+  | 'views'
+  | 'seedEntities'  // → suggestedEntities
+  | 'suggestedRelations'
+  | 'displayTemplates'
+  | 'entityLinks'
+  | 'bento'         // → bentoViewName + bentoLayout (widgets) + bentoViewBlocks (views)
+  | 'profileEntityBentoTemplates'
+  | 'layout'        // → layoutConfig
+  | 'integrations'  // → capabilities
+  | 'playbooks'
+  | 'onboarding'
+  | 'dependencies';
+
+/** Keys deliberately NOT forwarded by `toPackageDefinition`. */
+type PackageDefinitionDropped =
+  // UI-only, same as the definition door: `PackageDefinition` has no `app`.
+  | 'app'
+  // REAL GAP: backend `PackageDefinition` DOES declare `extends`
+  // (package-definition.ts:262) and `automations` (:268), but
+  // `PackageDefinitionOutput` omits both. No template declares either today
+  // (0/21), so this is latent, not live — wire them when a template first uses
+  // one.
+  | 'extends'
+  | 'automations';
+
+type UnclassifiedPackageDefinitionKey = Exclude<
+  keyof WorkspaceYaml,
+  PackageDefinitionForwarded | PackageDefinitionDropped
+>;
+
+// If this errors, a new `WorkspaceYaml` field is unclassified. Forward it in
+// `toPackageDefinition` and add it to `PackageDefinitionForwarded`, or add it
+// to `PackageDefinitionDropped` with a one-line WHY.
+const _packageDefinitionLedger: [UnclassifiedPackageDefinitionKey] extends [never]
+  ? true
+  : [
+      'UNCLASSIFIED YAML FIELD — forward it or add it to PackageDefinitionDropped:',
+      UnclassifiedPackageDefinitionKey,
+    ] = true;
+void _packageDefinitionLedger;

package/src/dev-dashboard.yaml

@@ -115,6 +115,9 @@ profiles:
     color: "#8B5CF6"
     description: "External services, tools, and providers used by the Synap platform."
     scope: WORKSPACE
+    profileKind: role
+    applicableKinds:
+      - company
     properties:
       - slug: vendor-type
         label: Vendor Type