@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/wire-core.ts

@@ -0,0 +1,231 @@
+/**
+ * The per-kind wire envelopes and the ONE unwrap — import-free on purpose.
+ *
+ * Re-exported (with the workspace types) by `./wire`, the public subpath
+ * `@synap-core/workspace-templates/wire`. It has no imports so a consumer that
+ * still resolves an older npm copy of this package (the CLI, the CP, the pod)
+ * can carry it as a BYTE-IDENTICAL mirror pinned by a tripwire until it can
+ * import the subpath. Edit it here; the mirror copies it.
+ *
+ * What `GET {CP}/api/packages/:slug` serves as `package.definition`, per kind:
+ * the outputs of this package's producers (`scripts/catalog-lib.mjs`
+ * `toPublishBody`; `toOfficialPublishBody` for workspaces) plus what the CP
+ * adds on store/serve (`_meta.slug` via `withTemplateSlug`,
+ * `capability.contentHash`).
+ *
+ * WHY: a skill package is served as `{ _meta, skill: {…} }`. Read flat, every
+ * field is `undefined`: install refused a "bodiless" skill and the update door
+ * reported "no drift" forever (founder pod 2026-10-13, creative-director). Each
+ * consumer had its own cast; this is the one place the envelope is known.
+ *
+ * Element fields are pinned to the catalog schema (`SKILL_FIELDS`,
+ * `CapabilitySpec`) and `AutomationElement` to `PackageAutomationWire` by
+ * `schema/wire.parity.test.ts` (compile time).
+ */
+
+// ─── Kinds ──────────────────────────────────────────────────────────────────
+
+/** The kinds whose served definition this module describes. */
+export const WIRE_KINDS = ["workspace", "capability", "skill", "automation", "view"] as const;
+export type WireKind = (typeof WIRE_KINDS)[number];
+
+/**
+ * Other names the same kinds go by: the pod's `market.install` says
+ * `template`, the CP category for an automation is `workflow`, and a pack is
+ * a workspace-shaped definition.
+ */
+export const WIRE_KIND_ALIASES = {
+  template: "workspace",
+  pack: "workspace",
+  workflow: "automation",
+} as const satisfies Record<string, WireKind>;
+export type WireKindName = WireKind | keyof typeof WIRE_KIND_ALIASES;
+
+/** `template` → `workspace`, `workflow` → `automation`; `null` for a kind with no wire contract here (e.g. `cell`). */
+export function toWireKind(kind: string): WireKind | null {
+  if ((WIRE_KINDS as readonly string[]).includes(kind)) return kind as WireKind;
+  return (WIRE_KIND_ALIASES as Record<string, WireKind>)[kind] ?? null;
+}
+
+// ─── Envelope pieces every kind shares ──────────────────────────────────────
+
+/**
+ * `definition._meta` as served: the CP stamps `slug` on every row (the pod
+ * keys "which space is this template's?" on it); the CLI adds the `version`
+ * label it installs.
+ */
+export interface WireMeta {
+  slug?: string;
+  version?: string;
+  [key: string]: unknown;
+}
+
+/** `meta.icon` / `color` / `domain`, mirrored onto the definition by every publish builder. */
+export interface WireIdentity {
+  icon?: string;
+  color?: string;
+  domain?: string;
+}
+
+/** A composition dependency. */
+export interface WireDependency {
+  slug: string;
+  kind?: "workspace" | "capability" | "skill" | "workflow" | "view" | "cell" | "automation";
+  relation?: "compose" | "require";
+  reason?: string;
+}
+
+export interface WireEnvelope extends WireIdentity {
+  _meta?: WireMeta;
+  dependencies?: WireDependency[];
+}
+
+// ─── Elements and envelopes, per kind ───────────────────────────────────────
+
+/** The capability itself (`CapabilityDefinition`). */
+export interface CapabilityElement {
+  key: string;
+  name: string;
+  description?: string;
+  params?: Array<Record<string, unknown>>;
+  vault?: Array<Record<string, unknown>>;
+  tools?: Array<Record<string, unknown>>;
+  skills?: Array<Record<string, unknown>>;
+  provides?: string[];
+  playbooks?: Array<Record<string, unknown>>;
+  /** Stamped by the CP on publish; the pod's drift marker. */
+  contentHash?: string;
+  automations?: Array<Record<string, unknown>>;
+  mcpServers?: unknown;
+  metadata?: Record<string, unknown>;
+  _generated?: unknown;
+}
+
+/** capability: `{ profiles: [], description, capability }`. */
+export interface CapabilityWire extends WireEnvelope {
+  profiles: unknown[];
+  description?: string;
+  capability: CapabilityElement;
+}
+
+/** ONE standalone skill. Not a workspace's `skills[]` link list. */
+export interface SkillElement {
+  /** The pod-side `load_skill` ref — its own identity, not the package slug. */
+  slug?: string;
+  name?: string;
+  displayName?: string;
+  description?: string;
+  kind?: "instruction" | "code" | "declarative" | "builtin";
+  scope?: "pod" | "user" | "workspace";
+  agentTypes?: string[];
+  body?: string;
+  code?: string;
+  providerSpec?: Record<string, unknown>;
+  parameters?: Record<string, unknown>;
+  category?: string;
+  executionMode?: "sync" | "async";
+  timeoutSeconds?: number;
+  intent?: string;
+  [key: string]: unknown;
+}
+
+/** skill: `{ skill, icon?, color?, domain?, dependencies? }`. */
+export interface SkillWire extends WireEnvelope {
+  skill: SkillElement;
+}
+
+/** One graph automation (= `PackageAutomationWire`): `flowDefinition`, not the authored `flow`. */
+export interface AutomationElement {
+  key?: string;
+  name: string;
+  description?: string;
+  triggerType: "event" | "cron" | "webhook" | "manual";
+  triggerConfig?: Record<string, unknown>;
+  flowDefinition?: { nodes: unknown[]; edges: unknown[]; precondition?: string };
+  status?: "draft" | "active" | "paused";
+}
+
+/** automation (CP category `workflow`): `{ profiles: [], automations: [one] }`. */
+export interface AutomationWire extends WireEnvelope {
+  profiles: unknown[];
+  automations: AutomationElement[];
+}
+
+/** One view, as the pod's view install and update doors read it. */
+export interface ViewElement {
+  slug?: string;
+  name?: string;
+  displayName?: string;
+  description?: string;
+  type?: string;
+  config?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  scopeProfileSlugs?: string[];
+  scopeProfileIds?: string[];
+  [key: string]: unknown;
+}
+
+/** view: `{ views: [...] }`, or a legacy single view with its fields on top (has its own `type`). No catalog producer today. */
+export type ViewWire = (WireEnvelope & { views: ViewElement[] }) | ViewElement;
+
+/**
+ * What {@link unwrapPackage} returns per kind. `workspace` is the definition
+ * itself; `./wire` narrows it to `WorkspaceWire`.
+ */
+export interface PackageElementByKind<W = Record<string, unknown>> {
+  workspace: W;
+  capability: CapabilityElement;
+  skill: SkillElement;
+  automation: AutomationElement[];
+  view: ViewElement[];
+}
+
+export type ElementOf<K extends WireKindName, W = Record<string, unknown>> = PackageElementByKind<W>[K extends WireKind
+  ? K
+  : K extends keyof typeof WIRE_KIND_ALIASES
+    ? (typeof WIRE_KIND_ALIASES)[K]
+    : never];
+
+// ─── The ONE unwrap ─────────────────────────────────────────────────────────
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * The installable element(s) inside a served definition:
+ *
+ *   skill      → the `skill` object (a legacy flat definition is the skill itself)
+ *   capability → the `capability` object (a flat `CapabilityDefinition` — the
+ *                pod cache / CP by-key shape — passes through)
+ *   automation → `automations[]` (`[]` when the definition declares none)
+ *   view       → `views[]`, or a legacy flat view (top-level `type`) as `[def]`, else `[]`
+ *   workspace  → the definition itself
+ *
+ * An empty array means the definition declares none; the install doors refuse
+ * that themselves. A definition that is not an object is a failed read, never
+ * an empty one: it throws.
+ */
+export function unwrapPackage<K extends WireKindName>(kind: K, definition: unknown): ElementOf<K>;
+export function unwrapPackage(kind: string, definition: unknown): unknown {
+  const wireKind = toWireKind(kind);
+  if (!wireKind) throw new Error(`unwrapPackage: "${kind}" has no wire contract`);
+  if (!isRecord(definition)) {
+    throw new TypeError(
+      `unwrapPackage(${kind}): the definition is not an object (${definition === null ? "null" : Array.isArray(definition) ? "array" : typeof definition})`,
+    );
+  }
+  switch (wireKind) {
+    case "skill":
+      return isRecord(definition.skill) ? definition.skill : definition;
+    case "capability":
+      return isRecord(definition.capability) ? definition.capability : definition;
+    case "automation":
+      return Array.isArray(definition.automations) ? definition.automations : [];
+    case "view":
+      if (Array.isArray(definition.views) && definition.views.length > 0) return definition.views;
+      return definition.type ? [definition] : [];
+    case "workspace":
+      return definition;
+  }
+}

package/src/wire.test.ts

@@ -0,0 +1,159 @@
+/**
+ * The wire contract, driven from the REAL producers: every capability, skill,
+ * automation and workspace in this catalog is compiled by `loadCatalog` (the
+ * same `toPublishBody` the official publish sends), given the `_meta.slug` the
+ * CP stamps on serve, and unwrapped. Nothing between the catalog file and the
+ * unwrap is hand-built, so a producer that moves an element out of its slot
+ * fails here.
+ */
+
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { loadCatalog } from "../scripts/catalog-lib.mjs";
+import { toAutomationWire, toPackageDefinition, toWorkspaceDefinition } from "./define";
+import { WORKSPACE_TEMPLATES } from "./templates";
+import { toWireKind, toWorkspaceInput, unwrapPackage, type WorkspaceWire } from "./wire";
+
+const loaded = await loadCatalog();
+// The shipped automations are STAGED (raw bridge files, no catalog header), so
+// no live automation compiles today; the fixture catalog's `demo-auto` goes
+// through the same `toPublishBody`.
+const fixture = await loadCatalog({
+  root: fileURLToPath(new URL("../scripts/__fixtures__/catalog", import.meta.url)),
+  dirs: { workspace: ["workspaces"] },
+});
+const ofKind = (kind: string) =>
+  [...loaded.corpus, ...(kind === "automation" ? fixture.corpus : [])].filter((e) => e.kind === kind && e.publishBody);
+/** What the CP serves: the stored definition with `_meta.slug` stamped (`withTemplateSlug`). */
+const served = (e: { slug: string; publishBody: { definition: Record<string, unknown> } }) => ({
+  ...e.publishBody.definition,
+  _meta: { ...((e.publishBody.definition._meta as object | undefined) ?? {}), slug: e.slug },
+});
+const one = (kind: string, slug: string) => {
+  const e = ofKind(kind).find((x) => x.slug === slug);
+  if (!e) throw new Error(`catalog has no ${kind} "${slug}"`);
+  return e;
+};
+
+describe("unwrapPackage — real producer output", () => {
+  it("non-vacuity: the catalog compiled entries of every kind", () => {
+    expect(ofKind("skill").length).toBeGreaterThanOrEqual(5);
+    expect(ofKind("capability").length).toBeGreaterThanOrEqual(20);
+    expect(ofKind("automation").length).toBeGreaterThanOrEqual(1);
+    expect(ofKind("workspace").length).toBeGreaterThanOrEqual(10);
+  });
+
+  it("skill: creative-director's body arrives (read flat it is undefined — the 10-13 bug)", () => {
+    const e = one("skill", "creative-director");
+    const def = served(e);
+    const skill = unwrapPackage("skill", def);
+    expect(typeof skill.body).toBe("string");
+    expect((skill.body as string).length).toBeGreaterThan(200);
+    expect(skill.name).toBeTruthy();
+    expect(skill).toEqual(e.manifest.spec);
+    expect((def as { body?: unknown }).body).toBeUndefined();
+  });
+
+  it("skill: every catalog skill unwraps to something the pod installs (body, code or providerSpec)", () => {
+    for (const e of ofKind("skill")) {
+      const s = unwrapPackage("skill", served(e));
+      expect(Boolean(s.body?.trim() || s.code?.trim() || s.providerSpec), e.slug).toBe(true);
+    }
+  });
+
+  it("capability: every catalog capability unwraps to the capability, its key and skills intact", () => {
+    for (const e of ofKind("capability")) {
+      const cap = unwrapPackage("capability", served(e));
+      expect(cap.key, e.slug).toBe(e.slug);
+      expect(cap).toEqual(e.manifest.spec);
+      expect(Array.isArray(cap.skills) || Array.isArray(cap.playbooks) || Array.isArray(cap.tools), e.slug).toBe(true);
+    }
+  });
+
+  it("automation: every catalog automation unwraps to its one flow, under either kind name", () => {
+    for (const e of ofKind("automation")) {
+      const autos = unwrapPackage("workflow", served(e));
+      expect(autos, e.slug).toHaveLength(1);
+      expect(autos).toEqual(toAutomationWire([e.manifest.spec as never]));
+      expect(autos[0]!.flowDefinition?.nodes.length, e.slug).toBeGreaterThan(0);
+      expect(unwrapPackage("automation", served(e))).toBe(autos);
+    }
+  });
+
+  it("workspace: the served definition is the element, under workspace / template / pack", () => {
+    const e = one("workspace", "content-os");
+    const def = served(e);
+    expect(unwrapPackage("template", def)).toBe(def);
+    expect(unwrapPackage("workspace", def).workspaceName).toBeTruthy();
+    expect(unwrapPackage("pack", def).profiles.length).toBeGreaterThan(0);
+  });
+
+  it("legacy flat definitions pass through", () => {
+    const skill = { name: "Flat", body: "# flat" };
+    expect(unwrapPackage("skill", skill)).toBe(skill);
+    const cap = one("capability", ofKind("capability")[0]!.slug).manifest.spec;
+    expect(unwrapPackage("capability", cap)).toBe(cap);
+  });
+
+  it("view: views[], a legacy single view as [def], none as []", () => {
+    const a = { name: "A", type: "table" };
+    const b = { name: "B", type: "kanban" };
+    expect(unwrapPackage("view", { views: [a, b] })).toEqual([a, b]);
+    const flat = { name: "Flat", type: "list", config: {} };
+    expect(unwrapPackage("view", flat)).toEqual([flat]);
+    expect(unwrapPackage("view", { views: [] })).toEqual([]);
+    expect(unwrapPackage("automation", { profiles: [] })).toEqual([]);
+  });
+
+  it("a definition that is not an object is a failed read, not an empty one; an unknown kind is refused", () => {
+    expect(() => unwrapPackage("skill", null)).toThrow(/not an object/);
+    expect(() => unwrapPackage("automation", [] as unknown)).toThrow(/not an object/);
+    expect(() => unwrapPackage("cell" as never, {})).toThrow(/no wire contract/);
+    expect(toWireKind("template")).toBe("workspace");
+    expect(toWireKind("workflow")).toBe("automation");
+    expect(toWireKind("cell")).toBeNull();
+  });
+});
+
+describe("toWorkspaceInput — the served workspace → create input", () => {
+  /**
+   * Keys where it differs from `toWorkspaceDefinition` (the bundle path), with
+   * why. Pinned as EXACT equality: a new difference — or one closing — fails.
+   *  - proposalId: the bundle uses `workspace.proposalId ?? <slug>-v1`; the
+   *    served definition only has the slug.
+   *  - taskIntents: NOT carried by the pod's cache path today (a real gap,
+   *    reported by lane W5a; mirrored 1:1 here so the pod can swap).
+   *  - capabilities / playbooks / actionPlacements: read off the PACKAGE
+   *    definition by the post-workspace layer, not the create input.
+   */
+  const EXPECTED_DIFFERENT = ["actionPlacements", "capabilities", "playbooks", "proposalId", "taskIntents"];
+
+  const slugs = Object.keys(WORKSPACE_TEMPLATES);
+  it("non-vacuity: the bundle has templates", () => expect(slugs.length).toBeGreaterThanOrEqual(10));
+
+  it("carries every other field exactly as the bundle path does, for every bundled template", () => {
+    const differing = new Set<string>();
+    const norm = (v: unknown) => JSON.parse(JSON.stringify(v ?? null));
+    for (const slug of slugs) {
+      const fromWire = toWorkspaceInput({ ...toPackageDefinition(slug), _meta: { slug } } as WorkspaceWire) as unknown as Record<string, unknown>;
+      const fromBundle = toWorkspaceDefinition(slug).definition as unknown as Record<string, unknown>;
+      for (const k of new Set([...Object.keys(fromWire), ...Object.keys(fromBundle)])) {
+        const a = norm(fromWire[k]);
+        const b = norm(fromBundle[k]);
+        const emptyEq = (x: unknown) => x === null || (Array.isArray(x) && x.length === 0);
+        if (JSON.stringify(a) !== JSON.stringify(b) && !(emptyEq(a) && emptyEq(b))) differing.add(k);
+      }
+    }
+    expect([...differing].sort()).toEqual(EXPECTED_DIFFERENT);
+  });
+
+  it("the two renames land: suggestedEntities → seedEntities, automations → flowAutomations", () => {
+    const slug = slugs.find((s) => (toPackageDefinition(s).automations?.length ?? 0) > 0)!;
+    const pd = toPackageDefinition(slug);
+    const input = toWorkspaceInput(pd);
+    expect(input.flowAutomations).toEqual(pd.automations);
+    expect(input.flowAutomations!.length).toBeGreaterThan(0);
+    expect(input.seedEntities).toBe(pd.suggestedEntities);
+    expect(input.proposalId).toBe(slug);
+  });
+});

package/src/wire.ts

@@ -0,0 +1,107 @@
+/**
+ * @synap-core/workspace-templates/wire — ONE wire contract per package kind.
+ *
+ * The per-kind envelopes and `unwrapPackage` live in `./wire-core` (import-free,
+ * so it can be mirrored byte-for-byte by consumers still pinned to an older npm
+ * copy). This adds what needs the rest of the package: the workspace envelope,
+ * derived from `PackageDefinitionOutput` instead of re-declared, and the one
+ * workspace wire → create-input translation.
+ */
+
+import type { PackageDefinitionOutput, WorkspaceDefinitionInput } from "./define";
+import { unwrapPackage as unwrapCore, type ElementOf, type WireIdentity, type WireKindName, type WireMeta } from "./wire-core";
+
+export {
+  WIRE_KINDS,
+  WIRE_KIND_ALIASES,
+  toWireKind,
+  type WireKind,
+  type WireKindName,
+  type WireMeta,
+  type WireIdentity,
+  type WireDependency,
+  type WireEnvelope,
+  type CapabilityElement,
+  type CapabilityWire,
+  type SkillElement,
+  type SkillWire,
+  type AutomationElement,
+  type AutomationWire,
+  type ViewElement,
+  type ViewWire,
+  type PackageElementByKind,
+} from "./wire-core";
+import type { AutomationWire, CapabilityWire, SkillWire, ViewWire, WireKind } from "./wire-core";
+
+/**
+ * workspace / pack: `toPackageDefinition()` output — re-used, not re-declared.
+ * As served it is `toOfficialPublishBody().definition` (identity mirrored on
+ * top, `sourcePackage`) with `_meta` cut down to what the CP stamps; a bundled
+ * `PackageDefinitionOutput` is assignable to it as is.
+ */
+export type WorkspaceWire = Omit<PackageDefinitionOutput, "_meta"> &
+  WireIdentity & {
+    _meta?: Partial<PackageDefinitionOutput["_meta"]> & WireMeta;
+    /** Which build of this package generated the row (official rows only). */
+    sourcePackage?: { name: string; version: string };
+  };
+
+/** The served definition, keyed by kind. */
+export interface PackageWireByKind {
+  workspace: WorkspaceWire;
+  capability: CapabilityWire;
+  skill: SkillWire;
+  automation: AutomationWire;
+  view: ViewWire;
+}
+export type PackageWire = PackageWireByKind[WireKind];
+
+/** `./wire-core`'s `unwrapPackage`, with the workspace element typed as {@link WorkspaceWire}. */
+export function unwrapPackage<K extends WireKindName>(kind: K, definition: unknown): ElementOf<K, WorkspaceWire> {
+  return unwrapCore(kind, definition) as ElementOf<K, WorkspaceWire>;
+}
+
+/**
+ * The served workspace definition → the input the pod's create/reconcile door
+ * takes (`WorkspaceDefinitionInput`). The two renames live here and only here:
+ * `suggestedEntities` → `seedEntities` and `automations` (graph flows) →
+ * `flowAutomations`.
+ *
+ * A 1:1 copy of the pod's `toWorkspaceDefinitionInput`
+ * (synap-backend `services/capabilities/resolve-workspace-template.ts`), so the
+ * pod can import this instead. Like it, it does NOT carry `taskIntents`,
+ * `capabilities`, `playbooks`, `actionPlacements`, `rules` or `skills`: the
+ * post-workspace layer reads the last five off the package definition itself;
+ * `taskIntents` is a gap on that path today. `wire.test.ts` pins every
+ * difference from `toWorkspaceDefinition`.
+ */
+export function toWorkspaceInput(pkg: WorkspaceWire): WorkspaceDefinitionInput {
+  return {
+    workspaceName: pkg.workspaceName,
+    description: pkg.description,
+    proposalId: pkg._meta?.slug,
+    profiles: pkg.profiles,
+    views: pkg.views ?? [],
+    entityLinks: pkg.entityLinks ?? [],
+    seedEntities: pkg.suggestedEntities ?? [],
+    suggestedRelations: pkg.suggestedRelations,
+    displayTemplates: pkg.displayTemplates,
+    layoutConfig: pkg.layoutConfig,
+    bentoViewName: pkg.bentoViewName,
+    bentoLayout: pkg.bentoLayout,
+    bentoViewBlocks: pkg.bentoViewBlocks,
+    profileEntityBentoTemplates: pkg.profileEntityBentoTemplates,
+    workspaceSubtype: pkg.workspaceSubtype,
+    workspaceType: pkg.workspaceType,
+    workspaceVisibility: pkg.workspaceVisibility,
+    workspaceCapabilities: pkg.workspaceCapabilities,
+    intent: pkg.intent,
+    sourceRoles: pkg.sourceRoles,
+    defaultSources: pkg.defaultSources,
+    onboarding: pkg.onboarding,
+    dependencies: pkg.dependencies,
+    flowAutomations: pkg.automations ?? [],
+    commands: pkg.commands ?? [],
+    relationDefs: pkg.relationDefs ?? [],
+  };
+}