@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/start.test.ts

@@ -0,0 +1,188 @@
+/**
+ * `meta.start` — a template declares itself an onboarding start (A1).
+ *
+ * Pinned:
+ *  - a well-formed start validates with zero `start-*` errors;
+ *  - each `start-*` rule fires on a minimal broken fixture (and only it);
+ *  - the package door forwards a TOP-LEVEL `start`, never inside `_meta`;
+ *  - the catalog header accepts the shape and refuses it on a non-space kind.
+ */
+import { describe, expect, it } from "vitest";
+import { validateTemplate } from "./validate.js";
+import { toPackageDefinition } from "./define.js";
+import { INTENT_LABEL_MAX } from "./types.js";
+import type { TemplateProfile, TemplateStart, WorkspaceYaml } from "./types.js";
+import { manifestSchemaFor } from "../schema/index.ts";
+import { listWorkspaceTemplates } from "./templates.js";
+
+const deal: TemplateProfile = {
+  slug: "deal",
+  displayName: "Deal",
+  properties: [
+    { slug: "commercialStage", label: "Stage", valueType: "string", inputType: "select", enumValues: ["lead", "negotiating", "won"] },
+    { slug: "value", label: "Value", valueType: "number" },
+  ],
+} as TemplateProfile;
+
+const goodStart = (over: Partial<TemplateStart> = {}): TemplateStart => ({
+  order: 1,
+  label: "Sales",
+  promise: "Leads and deals, each with a dated next step.",
+  suggestFor: ["founder"],
+  profile: "deal",
+  views: ["deal-pipeline", "deals-table"],
+  example: [1, 2, 3, 4].map((n) => ({ title: `Deal ${n}`, values: { commercialStage: "negotiating", value: n * 1000 } })),
+  firstSession: { title: "Your live deals", goal: "Add the deals you are moving now." },
+  starters: ["a", "b", "c"],
+  ...over,
+});
+
+const make = (slug: string, start?: Partial<TemplateStart> | null, extra: Partial<WorkspaceYaml> = {}): WorkspaceYaml =>
+  ({
+    meta: { slug, name: slug, description: "d", icon: "box", color: "blue", ...(start === null ? {} : { start: goodStart(start) }) },
+    workspace: { name: slug, description: "d" },
+    profiles: [deal],
+    views: [
+      { name: "Pipeline", slug: "deal-pipeline", type: "kanban", scopeProfileSlug: "deal" },
+      { name: "Deals", slug: "deals-table", type: "table", scopeProfileSlugs: ["deal"] },
+      { name: "Other", slug: "other-table", type: "table", scopeProfileSlug: "task" },
+    ],
+    ...extra,
+  }) as unknown as WorkspaceYaml;
+
+const startErrors = (t: WorkspaceYaml, corpus?: WorkspaceYaml[]) =>
+  validateTemplate(t, { corpus }).errors.filter((e) => e.rule.startsWith("start-")).map((e) => e.rule);
+
+describe("meta.start — validator rules", () => {
+  it("a well-formed start passes", () => {
+    expect(startErrors(make("t"))).toEqual([]);
+  });
+
+  it("no start → no start-* error", () => {
+    expect(startErrors(make("t", null))).toEqual([]);
+  });
+
+  it("start-shape: a missing field", () => {
+    const t = make("t");
+    delete (t.meta.start as Partial<TemplateStart>).promise;
+    expect(startErrors(t)).toEqual(["start-shape"]);
+  });
+
+  it("start-no-workspace: an overlay owns no space", () => {
+    const t = make("t", {}, { dependencies: [{ slug: "base", relation: "compose" }] } as Partial<WorkspaceYaml>);
+    expect(startErrors(t)).toEqual(["start-no-workspace"]);
+  });
+
+  it("start-label: longer than INTENT_LABEL_MAX", () => {
+    expect(startErrors(make("t", { label: "x".repeat(INTENT_LABEL_MAX + 1) }))).toEqual(["start-label"]);
+  });
+
+  it("start-example-count and start-starters-count", () => {
+    expect(startErrors(make("t", { example: goodStart().example.slice(0, 3) }))).toEqual(["start-example-count"]);
+    expect(startErrors(make("t", { starters: ["a"] }))).toEqual(["start-starters-count"]);
+  });
+
+  it("start-views-count: none, or more than three", () => {
+    expect(startErrors(make("t", { views: [] }))).toEqual(["start-views-count"]);
+    expect(startErrors(make("t", { views: ["deal-pipeline", "deals-table", "deal-pipeline", "deals-table"] }))).toEqual(["start-views-count"]);
+  });
+
+  it("start-views-exist: a slug this template does not declare", () => {
+    expect(startErrors(make("t", { views: ["deal-pipeline", "nope"] }))).toEqual(["start-views-exist"]);
+  });
+
+  it("start-views-scope: a view scoped to another kind", () => {
+    expect(startErrors(make("t", { views: ["other-table"] }))).toEqual(["start-views-scope"]);
+  });
+
+  it("start-profile-unknown: a kind nobody declares", () => {
+    expect(startErrors(make("t", { profile: "ghost", views: [], example: goodStart().example.map((e) => ({ title: e.title })) }))).toContain("start-profile-unknown");
+  });
+
+  it("start-profile-unknown: the kind may come from the dependency closure", () => {
+    const dep = { meta: { slug: "dep", name: "dep", description: "d", icon: "b", color: "c" }, workspace: { name: "d", description: "d" }, profiles: [deal] } as unknown as WorkspaceYaml;
+    const t = make("t", { views: [] }, { profiles: [], views: [], dependencies: [{ slug: "dep", relation: "require" }] } as Partial<WorkspaceYaml>);
+    expect(startErrors(t, [t, dep])).toEqual(["start-views-count"]); // profile resolves; only the empty views fire
+  });
+
+  it("start-example-property: a key the kind does not have", () => {
+    const example = goodStart().example.map((e) => ({ ...e, values: { ...e.values, mood: "x" } }));
+    expect(startErrors(make("t", { example }))).toEqual(Array(4).fill("start-example-property"));
+  });
+
+  it("start-example-enum: a select value outside enumValues", () => {
+    const example = goodStart().example.map((e) => ({ ...e, values: { commercialStage: "dancing" } }));
+    expect(startErrors(make("t", { example }))).toEqual(Array(4).fill("start-example-enum"));
+  });
+
+  it("start-suggest-duplicate: an id twice in one start, and across starts", () => {
+    expect(startErrors(make("t", { suggestFor: ["founder", "founder"] }))).toEqual(["start-suggest-duplicate"]);
+    const a = make("a", { order: 1, suggestFor: ["founder"] });
+    const b = make("b", { order: 2, suggestFor: ["founder"] });
+    expect(startErrors(b, [a, b])).toEqual(["start-suggest-duplicate"]);
+  });
+
+  it("start-order-duplicate: two starts on one card slot", () => {
+    const a = make("a", { order: 1, suggestFor: ["x"] });
+    const b = make("b", { order: 1, suggestFor: ["y"] });
+    expect(startErrors(b, [a, b])).toEqual(["start-order-duplicate"]);
+    expect(startErrors(make("b", { order: 2, suggestFor: ["y"] }), [a, make("b", { order: 2, suggestFor: ["y"] })])).toEqual([]);
+  });
+});
+
+describe("meta.start — package door", () => {
+  it("carries a top-level start, never in _meta", () => {
+    const def = toPackageDefinition(make("t"));
+    expect(def.start).toEqual(goodStart());
+    expect("start" in def._meta).toBe(false);
+  });
+
+  it("no start → no field", () => {
+    expect("start" in toPackageDefinition(make("t", null))).toBe(false);
+  });
+});
+
+describe("meta.start — catalog header", () => {
+  const manifest = (kind: "workspace" | "skill", meta: Record<string, unknown>) => ({
+    apiVersion: "synap/v1",
+    kind,
+    meta: { slug: "t", name: "T", ...meta },
+    spec: kind === "workspace" ? { workspace: { name: "T", description: "d" }, profiles: [] } : { name: "t", content: "x" },
+  });
+
+  it("a workspace header accepts the shape and refuses an unknown key", () => {
+    expect(manifestSchemaFor("workspace").safeParse(manifest("workspace", { start: goodStart() })).success).toBe(true);
+    expect(manifestSchemaFor("workspace").safeParse(manifest("workspace", { start: { ...goodStart(), why: 1 } })).success).toBe(false);
+  });
+
+  it("is refused on a kind that is not a workspace", () => {
+    const r = manifestSchemaFor("skill").safeParse(manifest("skill", { start: goodStart() }));
+    expect(r.success).toBe(false);
+    expect(r.error?.issues.some((i) => i.path.join(".") === "meta.start")).toBe(true);
+  });
+});
+
+describe("meta.start — the shipped catalog (A2)", () => {
+  const all = listWorkspaceTemplates();
+  const starts = all.filter((t) => t.meta.start);
+
+  it("declares exactly the four starts, card orders 1-4", () => {
+    expect(starts.map((t) => [t.meta.start!.order, t.meta.slug]).sort()).toEqual([
+      [1, "builder-workspace"],
+      [2, "content-os"],
+      [3, "crm"],
+      [4, "operations"],
+    ]);
+  });
+
+  it("every start passes the start-* rules against the whole corpus", () => {
+    for (const t of starts) expect(startErrors(t, all), t.meta.slug).toEqual([]);
+  });
+
+  it("CRM has three deal views scoped to deal", () => {
+    const crm = all.find((t) => t.meta.slug === "crm")!;
+    const dealViews = (crm.views ?? []).filter((v) => v.scopeProfileSlug === "deal").map((v) => v.slug);
+    expect(dealViews).toEqual(["deal-pipeline", "deals-table", "deals-list"]);
+    expect(crm.meta.start!.views).toEqual(dealViews);
+  });
+});

package/src/task-intents.test.ts

@@ -0,0 +1,293 @@
+/**
+ * TRIPWIRE: `taskIntents` — the workspace's DECLARED task requirements.
+ *
+ * A template declares the intents (closed vocabulary) it needs to function, so
+ * an agent entering that space can be told what it is FOR without discovering
+ * it by failing. Three failure classes are guarded here, in increasing order of
+ * how quietly they would ship:
+ *
+ *   1. UNKNOWN SLUG — a `taskIntents` value outside the closed vocabulary. Caught
+ *      at authoring time by `validateTemplate`; asserted here over the whole
+ *      corpus so a seed added without ever running the validator still fails.
+ *   2. A TEMPLATE WITH NO DECLARATION — not an error by itself (a workspace
+ *      that needs no external capability declares nothing), but asserted
+ *      against a DERIVED set so a new template cannot silently ship undeclared.
+ *   3. CONTENT STUDIO SPECIFICALLY — the founder-specified reference list, and
+ *      the one template whose exact declaration is pinned as data in this file.
+ *
+ * WHAT IT PROVES: that the declared set is (a) inside the closed vocabulary,
+ * (b) free of duplicates, (c) agreed on by `validateTemplate` — the gate
+ * `build.mjs`, the CP publish path and the CLI actually call — and (d) exactly
+ * the founder-specified list for Content Studio. It REPORTS (never gates) how
+ * much of each declaration is currently backed by an installed pack; see the
+ * long note on that describe block for why a gap is a fact, not an error.
+ *
+ * WHAT IT DOES NOT PROVE: that any declared intent is the RIGHT requirement for
+ * a workspace — that is a judgement, not a derivable fact.
+ *
+ * ⚠️ THE SCAN IS DERIVED, NOT HAND-LISTED. The template set comes from
+ * `readYamlTemplates()` (the same reader `build.mjs` uses), so a template added
+ * tomorrow joins this scan BY EXISTING. A hand-written array of slugs is how a
+ * guard ends up holding only the entries that were already correct.
+ *
+ * ⚠️ NON-VACUITY IS ASSERTED EXPLICITLY, twice: the corpus must be non-empty,
+ * and the vocabulary must be a real closed set. A glob that matches zero files
+ * passes every "no unknown intent" assertion there is.
+ */
+
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CAPABILITY_INTENTS } from "@synap-core/types/capability-intents";
+import { validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// The reference list the founder specified for Content Studio, now carried by
+// Content OS (content-studio retired into it, 2026-11-03). Pinned HERE as
+// data so the test states what "correct" is rather than reading it from the
+// file it is meant to police.
+const CONTENT_OS_INTENTS = [
+  "generate_media",
+  "manage_file",
+  "capture_into_pod",
+  "search_external",
+];
+
+// The catalog's own capability manifests (the CP keeps a byte-checked mirror
+// until its pin bump; see the CP's catalog-mirror.tripwire.test.ts).
+const CAPABILITY_TEMPLATES_DIR = join(HERE, "../capabilities");
+
+/** The closed vocabulary as a set, plus a readable unknown-value report. */
+const VOCABULARY = new Set<string>(CAPABILITY_INTENTS);
+
+/**
+ * The intents a capability pack actually provides, from its declared verb
+ * intents. Reads the catalog manifest (its `spec` is the CP seed JSON, kept
+ * identical by the mirror tripwire) — so "declared" here means what the seeder
+ * will really install.
+ *
+ * Returns null for a pack this checkout cannot read, which callers treat as
+ * "cannot check" rather than "provides nothing" — an unresolvable pack must not
+ * silently pass a subset assertion.
+ */
+function providedIntents(templateKey: string): Set<string> | null {
+  const file = join(CAPABILITY_TEMPLATES_DIR, `${templateKey}.capability.json`);
+  if (!existsSync(file)) return null;
+  const json = JSON.parse(readFileSync(file, "utf-8")) as unknown;
+  const intents = new Set<string>();
+  const walk = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    if (node && typeof node === "object") {
+      for (const [key, value] of Object.entries(node)) {
+        if (key === "intent" && typeof value === "string") intents.add(value);
+        walk(value);
+      }
+    }
+  };
+  walk(json);
+  return intents;
+}
+
+/** Load the corpus through the ONE reader `build.mjs` uses. */
+function loadTemplates(): Array<{ file: string; slug: string; data: WorkspaceYaml }> {
+  // Imported lazily so this module's import cost is paid inside the tests, and
+  // so a YAML parse error surfaces as a test failure with context.
+  const { readYamlTemplates } = require("./generate.mjs") as {
+    readYamlTemplates: () => Array<{ file: string; slug: string; data: unknown }>;
+  };
+  return readYamlTemplates() as Array<{
+    file: string;
+    slug: string;
+    data: WorkspaceYaml;
+  }>;
+}
+
+const TEMPLATES = loadTemplates();
+const DECLARED = TEMPLATES.filter((t) => Array.isArray(t.data.taskIntents));
+
+describe("taskIntents — every declared slug is a known intent", () => {
+  it("non-vacuity: the scan actually found templates and a real vocabulary", () => {
+    // Without these, "no unknown intent" passes on an empty set.
+    expect(TEMPLATES.length).toBeGreaterThanOrEqual(10);
+    expect(CAPABILITY_INTENTS.length).toBeGreaterThanOrEqual(13);
+    expect(CAPABILITY_INTENTS.length).toBe(new Set(CAPABILITY_INTENTS).size);
+    expect(DECLARED.length).toBeGreaterThanOrEqual(5);
+    // The scan can still see a literal it hunts: prove the reader picks up a
+    // value rather than normalising it away.
+    expect(CONTENT_OS_INTENTS.filter((i) => VOCABULARY.has(i))).toHaveLength(
+      CONTENT_OS_INTENTS.length
+    );
+  });
+
+  it("no template declares an intent outside the closed vocabulary", () => {
+    const offenders: string[] = [];
+    for (const t of DECLARED) {
+      for (const intent of t.data.taskIntents as string[]) {
+        if (!VOCABULARY.has(intent)) {
+          offenders.push(`${t.file}: "${intent}"`);
+        }
+      }
+    }
+    expect(
+      offenders,
+      `Unknown taskIntents (closed vocabulary: ${CAPABILITY_INTENTS.join(", ")}):`
+    ).toEqual([]);
+  });
+
+  it("no template declares a duplicate intent", () => {
+    const offenders: string[] = [];
+    for (const t of DECLARED) {
+      const list = t.data.taskIntents as string[];
+      const dupes = list.filter((v, i) => list.indexOf(v) !== i);
+      if (dupes.length) offenders.push(`${t.file}: ${[...new Set(dupes)].join(", ")}`);
+    }
+    expect(offenders, "taskIntents must not repeat an intent").toEqual([]);
+  });
+
+  it("validateTemplate agrees with this scan (the authoring-time gate fires)", () => {
+    // The scanner above reads raw YAML; the validator is what build.mjs, the
+    // CP publish path and the CLI actually call. Assert the two cannot diverge
+    // on the case that matters — an unknown slug must be an ERROR there, not
+    // merely a warning this file swallowed.
+    const withUnknown: WorkspaceYaml = {
+      ...TEMPLATES[0].data,
+      taskIntents: ["generate_media", "definitely_not_an_intent"],
+    };
+    const result = validateTemplate(withUnknown);
+    const rule = result.errors.filter((e) => e.rule === "task-intent-unknown");
+    expect(rule).toHaveLength(1);
+    expect(rule[0].path).toContain("taskIntents");
+    // And a fully-valid list produces no taskIntents error at all.
+    const ok = validateTemplate({
+      ...TEMPLATES[0].data,
+      taskIntents: [...CONTENT_OS_INTENTS],
+    });
+    expect(ok.errors.filter((e) => e.rule.startsWith("task-intent"))).toEqual([]);
+  });
+});
+
+describe("taskIntents — declared requirements vs. what is installed today", () => {
+  /**
+   * ⚠️ THIS IS A REPORT, NOT A GATE — deliberately, and the reason is the point
+   * of the field.
+   *
+   * An earlier draft asserted `taskIntents ⊆ intents(provided by integrations)`
+   * as a hard failure. It went red immediately and was WRONG: the founder's
+   * reference declaration for Content Studio is
+   * `[generate_media, manage_file, capture_into_pod, search_external]`, while
+   * at the time its only installed pack (`remotion`, since retired) provided
+   * just `generate_media` — and today it ships NO pack at all (HyperFrames
+   * runs on the user's own agent, plan D9). A subset rule would have forbidden
+   * the specification itself.
+   *
+   * `taskIntents` is what a workspace NEEDS TO FUNCTION, not a snapshot of what
+   * it currently has. Declaring an intent ahead of the pack that serves it is
+   * the requirement doing its job — it is what a later install, or a Phase-3
+   * match, is checked against. So a gap is a FACT to surface, not an error to
+   * reject.
+   *
+   * What this therefore does NOT prove: that every requirement is satisfiable.
+   * A template could declare an intent nothing can ever provide, and this stays
+   * green. Only a human (or the Phase-3 resolver) can say a requirement is
+   * met; a structural check can only say whether it is currently backed.
+   *
+   * It DOES prove the reporting machinery works: the corpus is walked, packs are
+   * resolved for real, and an unresolvable pack is reported rather than counted
+   * as providing nothing — the "silently passing" failure this file exists to
+   * prevent.
+   */
+  it("reports each declaration's backing and its gaps", () => {
+    interface Coverage {
+      file: string;
+      declared: number;
+      backed: number;
+      gaps: string[];
+      unreadable: string[];
+    }
+    const coverage: Coverage[] = [];
+    for (const t of DECLARED) {
+      const installed = t.data.integrations ?? [];
+      const provided = new Set<string>();
+      const unreadable: string[] = [];
+      for (const integration of installed) {
+        const intents = providedIntents(integration.templateKey);
+        if (intents === null) {
+          unreadable.push(integration.templateKey);
+          continue;
+        }
+        intents.forEach((i) => provided.add(i));
+      }
+      const declared = t.data.taskIntents as string[];
+      coverage.push({
+        file: t.file,
+        declared: declared.length,
+        backed: declared.filter((i) => provided.has(i)).length,
+        gaps: declared.filter((i) => !provided.has(i)),
+        unreadable,
+      });
+    }
+
+    // Non-vacuity: the report is real — every declared template was walked and
+    // at least one pack resolved, so the gap list is measured, not empty-by-
+    // construction.
+    expect(coverage.length).toBeGreaterThanOrEqual(5);
+    const resolvable = coverage.filter((c) => c.unreadable.length < (c.declared ? 1 : 0));
+    expect(
+      coverage.some((c) => c.backed > 0),
+      "no declared intent matched any installed pack — the derivation is broken"
+    ).toBe(true);
+
+    // The only hard assertion: a template cannot claim MORE intents than it
+    // declared. (Trivially true by construction — kept as the shape check that
+    // fails if the coverage walk ever stops being total.)
+    for (const c of coverage) {
+      expect(c.backed).toBeLessThanOrEqual(c.declared);
+    }
+
+    if (process.env.SYNAP_REPORT_TASK_INTENTS === "1") {
+      for (const c of coverage) {
+        console.warn(
+          `[taskIntents] ${c.file}: ${c.backed}/${c.declared} backed` +
+            (c.gaps.length ? ` · gaps: ${c.gaps.join(", ")}` : "") +
+            (c.unreadable.length
+              ? ` · unreadable packs: ${c.unreadable.join(", ")}`
+              : "")
+        );
+      }
+    }
+  });
+});
+
+// Content OS carries the founder-specified intents over from the retired
+// content-studio (retired.yaml, 2026-11-03), with the video pipeline they describe.
+describe("taskIntents — Content OS is the reference declaration", () => {
+  it("declares exactly the founder-specified intents", () => {
+    const contentOs = TEMPLATES.find((t) => t.slug === "content-os");
+    expect(contentOs, "content-os template not found in src/*.yaml").toBeTruthy();
+    expect(contentOs?.data.taskIntents, "content-os must declare taskIntents")
+      .toEqual(CONTENT_OS_INTENTS);
+  });
+
+  it("every one of them is a real intent", () => {
+    for (const intent of CONTENT_OS_INTENTS) {
+      expect(VOCABULARY.has(intent), `"${intent}" is not a known intent`).toBe(
+        true
+      );
+    }
+  });
+
+  it("and the template itself validates", () => {
+    const contentOs = TEMPLATES.find((t) => t.slug === "content-os");
+    const result = validateTemplate(contentOs!.data);
+    expect(
+      result.errors.filter((e) => e.rule.startsWith("task-intent")),
+      "content-os failed taskIntents validation"
+    ).toEqual([]);
+  });
+});