@synap-core/workspace-templates 0.9.2 → 0.9.4

package/src/validate-onboarding.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+
+function templateWithOnboarding(onboarding: unknown): WorkspaceYaml {
+  return {
+    meta: {
+      slug: "onboarding-validation",
+      name: "Onboarding validation",
+      description: "Validation fixture",
+      icon: "circle",
+      color: "blue",
+    },
+    workspace: {
+      name: "Onboarding validation",
+      description: "Validation fixture",
+    },
+    profiles: [
+      {
+        slug: "record",
+        displayName: "Record",
+        properties: [],
+      },
+    ],
+    onboarding,
+  } as WorkspaceYaml;
+}
+
+describe("validateTemplate onboarding contract", () => {
+  it("accepts a complete domain recipe", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({
+        goal: "Create the first useful record.",
+        framing: "Act as a domain expert.",
+        expertise: {
+          starters: ["Begin with the live work."],
+          blindSpots: ["Do not collect records without an owner."],
+          bar: "Every record has a clear next step.",
+        },
+        collect: [
+          {
+            profileSlug: "record",
+            what: "The records currently in motion.",
+            cardinality: "few",
+            keyFields: ["title"],
+          },
+        ],
+        openingQuestions: ["What is currently in motion?"],
+        doneWhen: "At least one useful record exists.",
+      }),
+      {}
+    );
+
+    expect(result, JSON.stringify(result.errors)).toEqual({
+      ok: true,
+      errors: [],
+    });
+  });
+
+  it("rejects empty expertise prose and collection instructions", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({
+        goal: "Set up this workspace.",
+        framing: "Act as a domain expert.",
+        expertise: {
+          starters: [""],
+          blindSpots: ["  "],
+          bar: "",
+        },
+        collect: [{ profileSlug: "record", what: "", keyFields: [""] }],
+        openingQuestions: [""],
+        doneWhen: "",
+      }),
+      {}
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.errors.map((error) => error.rule)).toEqual(
+      expect.arrayContaining([
+        "onboarding-expertise-invalid",
+        "onboarding-collect-what-empty",
+        "onboarding-collect-key-fields-invalid",
+        "onboarding-opening-questions-invalid",
+        "onboarding-done-when-invalid",
+      ])
+    );
+  });
+});

package/src/validate.test.ts

@@ -79,3 +79,124 @@ describe("validateTemplate — clean template", () => {
     expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
   });
 });
+
+// Regression: before wiring `validateFlowDefinition` into validateTemplate, a
+// template automation with a broken FLOW (bogus node type / dangling edge / cycle
+// / typo'd channelType) passed the template gate green and then silently never
+// fired on a live pod — the flow contract only ran server-side at install.
+describe("validateTemplate — automation flow node contract", () => {
+  const withAutomation = (flow: unknown): WorkspaceYaml =>
+    ({
+      meta: {
+        slug: "flowy",
+        name: "Flowy",
+        description: "d",
+        icon: "x",
+        color: "#000000",
+      },
+      workspace: { name: "Flowy", description: "d" },
+      profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+      automations: [
+        { name: "on-create", triggerType: "event", triggerConfig: {}, flow },
+      ],
+    }) as unknown as WorkspaceYaml;
+
+  it("FAILS on an unknown node type (was green before)", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "t1", type: "trigger", data: {} },
+          { id: "x1", type: "not_a_real_node", data: {} },
+        ],
+        edges: [{ id: "e1", source: "t1", target: "x1" }],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    const err = result.errors.find(
+      (e) => e.rule === "automation-flow-unknown_node_type"
+    );
+    expect(err, JSON.stringify(result.errors)).toBeDefined();
+    expect(err!.message).toContain("not_a_real_node");
+  });
+
+  it("FAILS on a dangling edge (target references no node)", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [{ id: "t1", type: "trigger", data: {} }],
+        edges: [{ id: "e1", source: "t1", target: "ghost" }],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    const err = result.errors.find(
+      (e) => e.rule === "automation-flow-edge_bad_target"
+    );
+    expect(err, JSON.stringify(result.errors)).toBeDefined();
+  });
+
+  it("FAILS on a capability node with no verbId", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "t1", type: "trigger", data: {} },
+          { id: "c1", type: "capability", data: {} },
+        ],
+        edges: [{ id: "e1", source: "t1", target: "c1" }],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.find(
+        (e) => e.rule === "automation-flow-capability_missing_verbId"
+      ),
+      JSON.stringify(result.errors)
+    ).toBeDefined();
+  });
+
+  it("FAILS on a cycle", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "a", type: "transform", data: { expression: "{{x}}" } },
+          { id: "b", type: "transform", data: { expression: "{{y}}" } },
+        ],
+        edges: [
+          { id: "e1", source: "a", target: "b" },
+          { id: "e2", source: "b", target: "a" },
+        ],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.find((e) => e.rule === "automation-flow-flow_has_cycle"),
+      JSON.stringify(result.errors)
+    ).toBeDefined();
+  });
+
+  it("PASSES a well-formed flow (trigger → notification output)", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "t1", type: "trigger", data: { triggerType: "event" } },
+          {
+            id: "o1",
+            type: "output",
+            data: {
+              outputType: "notification",
+              config: { title: "Hi", body: "{{trigger.payload.data.title}}" },
+            },
+          },
+        ],
+        edges: [{ id: "e1", source: "t1", target: "o1" }],
+      }),
+      {}
+    );
+    expect(result, JSON.stringify(result.errors)).toEqual({
+      ok: true,
+      errors: [],
+    });
+  });
+});

package/src/validate.ts

@@ -14,8 +14,8 @@
  *   • `scripts/check-converters.mjs` — injects the real converters, exits non-zero.
  *   • CP / pod / CLI (from dist) — import `validateTemplate` + `SYSTEM_PROFILES`.
  *
- * ZERO RUNTIME IMPORTS BY DESIGN. `build.mjs` loads this file directly under
- * Node's type-stripping BEFORE `tsup` builds `dist/`. A static
+ * NO RUNTIME IMPORT THAT FAILS AT STRIP-TIME. `build.mjs` loads this file
+ * directly under Node's type-stripping BEFORE `tsup` builds `dist/`. A static
  * `import { toWorkspaceDefinition } from "./define.js"` would fail to resolve at
  * that moment (define → templates.js does not exist pre-build, and Node's
  * type-stripper does not remap a `.js` specifier to its `.ts` source). So the
@@ -23,6 +23,14 @@
  * YAML/bento rules run everywhere; the converter-parity rules run wherever the
  * caller can supply the compiled converters (check-converters.mjs, from dist).
  * `import type` lines are fully erased by the type-stripper, so they are safe.
+ *
+ * THE ONE RUNTIME IMPORT: `./validate-flow.ts` (the pure automation-flow
+ * validator). It is imported with the `.ts` extension SPECIFICALLY so it resolves
+ * under Node's type-stripper at build.mjs time (a `.js` specifier would NOT — see
+ * above), and it has NO generated dependency (unlike `./define.js` → templates)
+ * so it is always present. It is DB-free (only `import type` internally), so it
+ * needs no injection: the flow-node contract check runs for every caller
+ * (build / check-converters / CLI / CP) automatically.
  */
 
 import type {
@@ -31,6 +39,9 @@ import type {
   TemplateProfile,
 } from "./types.js";
 
+// eslint-disable-next-line import/extensions -- .ts extension is intentional; see header.
+import { validateFlowDefinition } from "./validate-flow.ts";
+
 // ── Result shape ─────────────────────────────────────────────────────────────
 
 export interface ValidationError {
@@ -263,7 +274,8 @@ export function validateTemplate(
   if (!tpl.meta) add("meta-required", "meta", "Missing required field: meta");
   else {
     for (const f of REQUIRED_META_FIELDS) {
-      if (!tpl.meta[f]) add("meta-field-required", `meta.${f}`, `meta.${f} is required`);
+      if (!tpl.meta[f])
+        add("meta-field-required", `meta.${f}`, `meta.${f} is required`);
     }
   }
   if (!tpl.workspace)
@@ -271,12 +283,88 @@ export function validateTemplate(
   else {
     for (const f of REQUIRED_WORKSPACE_FIELDS) {
       if (!tpl.workspace[f])
-        add("workspace-field-required", `workspace.${f}`, `workspace.${f} is required`);
+        add(
+          "workspace-field-required",
+          `workspace.${f}`,
+          `workspace.${f} is required`
+        );
     }
   }
   if (!tpl.profiles || tpl.profiles.length === 0) {
     add("profiles-required", "profiles", "At least one profile is required");
   }
+  if (
+    tpl.app &&
+    tpl.layout &&
+    Object.prototype.hasOwnProperty.call(tpl.layout, "primarySurface")
+  ) {
+    add(
+      "primary-surface-authoring-conflict",
+      "layout.primarySurface",
+      "Declare either top-level app or layout.primarySurface, not both"
+    );
+  }
+  if (tpl.app?.kind === "native" && !tpl.app.appId) {
+    add(
+      "app-native-id-required",
+      "app.appId",
+      "A native workspace app requires appId"
+    );
+  }
+  if (tpl.app?.kind === "url" && (!tpl.app.appId || !tpl.app.url)) {
+    add(
+      "app-url-identity-required",
+      "app",
+      "A hosted workspace app requires both appId and url"
+    );
+  }
+  if (tpl.app?.kind === "stored" && !tpl.app.cellKey) {
+    add(
+      "app-cell-key-required",
+      "app.cellKey",
+      "A stored workspace app requires cellKey"
+    );
+  }
+  const authoredPrimary = tpl.layout?.primarySurface;
+  if (authoredPrimary?.kind === "view" && !("viewId" in authoredPrimary)) {
+    const viewName = authoredPrimary.viewName;
+    const viewSlug = authoredPrimary.viewSlug;
+    if (!viewName && !viewSlug) {
+      add(
+        "primary-view-reference-required",
+        "layout.primarySurface",
+        "A view primary surface requires viewName or viewSlug"
+      );
+    } else {
+      const declaredViews = [
+        ...(tpl.views ?? []).map((view) => ({
+          name: view.name,
+          slug: view.slug,
+        })),
+        ...(tpl.bento?.viewName
+          ? [{ name: tpl.bento.viewName, slug: undefined }]
+          : []),
+      ];
+      const matches = declaredViews.filter(
+        (view) =>
+          (!viewName || view.name === viewName) &&
+          (!viewSlug || view.slug === viewSlug)
+      );
+      if (matches.length === 0) {
+        add(
+          "primary-view-reference-unknown",
+          "layout.primarySurface",
+          `Primary surface references an unknown view (${viewName ?? viewSlug})`
+        );
+      } else if (matches.length > 1) {
+        add(
+          "primary-view-reference-ambiguous",
+          "layout.primarySurface",
+          `Primary surface view reference matches ${matches.length} authored views; add a unique viewSlug`
+        );
+      }
+    }
+  }
 
   // ── Referential integrity: build the known-profile predicate ──────────────
   const baseProfileSlugs = collectBaseProfileSlugs(tpl, resolveDepFrom(opts));
@@ -349,7 +437,110 @@ export function validateTemplate(
     }
   }
 
-  for (const c of tpl.onboarding?.collect || []) {
+  const onboarding = tpl.onboarding;
+  if (onboarding) {
+    if (typeof onboarding.goal !== "string" || onboarding.goal.trim() === "") {
+      add(
+        "onboarding-goal-empty",
+        "onboarding.goal",
+        "onboarding.goal must be a non-empty string"
+      );
+    }
+    if (
+      typeof onboarding.framing !== "string" ||
+      onboarding.framing.trim() === ""
+    ) {
+      add(
+        "onboarding-framing-empty",
+        "onboarding.framing",
+        "onboarding.framing must be a non-empty string"
+      );
+    }
+    if (!Array.isArray(onboarding.collect) || onboarding.collect.length === 0) {
+      add(
+        "onboarding-collect-empty",
+        "onboarding.collect",
+        "onboarding.collect must contain at least one structured target"
+      );
+    }
+
+    const expertise = onboarding.expertise;
+    for (const [field, values] of [
+      ["starters", expertise?.starters],
+      ["blindSpots", expertise?.blindSpots],
+    ] as const) {
+      if (
+        values !== undefined &&
+        (!Array.isArray(values) ||
+          values.some(
+            (value) => typeof value !== "string" || value.trim() === ""
+          ))
+      ) {
+        add(
+          "onboarding-expertise-invalid",
+          `onboarding.expertise.${field}`,
+          `onboarding.expertise.${field} must contain only non-empty strings`
+        );
+      }
+    }
+    if (
+      expertise?.bar !== undefined &&
+      (typeof expertise.bar !== "string" || expertise.bar.trim() === "")
+    ) {
+      add(
+        "onboarding-expertise-invalid",
+        "onboarding.expertise.bar",
+        "onboarding.expertise.bar must be a non-empty string"
+      );
+    }
+
+    if (
+      onboarding.openingQuestions !== undefined &&
+      (!Array.isArray(onboarding.openingQuestions) ||
+        onboarding.openingQuestions.some(
+          (question) => typeof question !== "string" || question.trim() === ""
+        ))
+    ) {
+      add(
+        "onboarding-opening-questions-invalid",
+        "onboarding.openingQuestions",
+        "onboarding.openingQuestions must contain only non-empty strings"
+      );
+    }
+    if (
+      onboarding.doneWhen !== undefined &&
+      (typeof onboarding.doneWhen !== "string" ||
+        onboarding.doneWhen.trim() === "")
+    ) {
+      add(
+        "onboarding-done-when-invalid",
+        "onboarding.doneWhen",
+        "onboarding.doneWhen must be a non-empty string"
+      );
+    }
+  }
+
+  for (const c of onboarding?.collect || []) {
+    if (typeof c.what !== "string" || c.what.trim() === "") {
+      add(
+        "onboarding-collect-what-empty",
+        `onboarding.collect.${c.profileSlug}.what`,
+        `onboarding.collect target "${c.profileSlug}" must describe what to capture`
+      );
+    }
+    if (
+      c.keyFields !== undefined &&
+      (!Array.isArray(c.keyFields) ||
+        c.keyFields.some(
+          (field) => typeof field !== "string" || field.trim() === ""
+        ))
+    ) {
+      add(
+        "onboarding-collect-key-fields-invalid",
+        `onboarding.collect.${c.profileSlug}.keyFields`,
+        `onboarding.collect target "${c.profileSlug}" keyFields must contain only non-empty strings`
+      );
+    }
     if (!known(c.profileSlug))
       add(
         "onboarding-ref-unknown",
@@ -371,11 +562,39 @@ export function validateTemplate(
   // SILENTLY at runtime.
   for (const a of tpl.automations || []) {
     const refs: Array<{ where: string; slug: string }> = [];
-    collectProfileSlugRefs(a.triggerConfig, `automation "${a.name}".triggerConfig`, refs);
+    collectProfileSlugRefs(
+      a.triggerConfig,
+      `automation "${a.name}".triggerConfig`,
+      refs
+    );
     collectProfileSlugRefs(a.flow, `automation "${a.name}".flow`, refs);
     for (const r of refs)
       if (!known(r.slug))
-        add("automation-ref-unknown", r.where, `${r.where} references unknown profile "${r.slug}"`);
+        add(
+          "automation-ref-unknown",
+          r.where,
+          `${r.where} references unknown profile "${r.slug}"`
+        );
+
+    // Node-contract validation. Previously validate.ts checked automations for
+    // profileSlug refs ONLY, so a bogus node type / dangling edge / cycle / typo'd
+    // channelType / verb-less capability node passed the template gate green and
+    // then SILENTLY never fired at runtime (validateFlowDefinition only ran
+    // server-side at install). Run the SAME contract validator here, at author
+    // time. Catalog-existence checks are resolver-gated and skipped (no catalog at
+    // author time); the structural + per-node contract checks always run.
+    const flow = a.flow ?? (a as { flowDefinition?: unknown }).flowDefinition;
+    if (flow != null) {
+      const { errors: flowErrors } = validateFlowDefinition(flow);
+      for (const fe of flowErrors) {
+        const loc = fe.nodeId
+          ? `automation "${a.name}".flow.node "${fe.nodeId}"`
+          : fe.edgeId
+            ? `automation "${a.name}".flow.edge "${fe.edgeId}"`
+            : `automation "${a.name}".flow`;
+        add(`automation-flow-${fe.code}`, loc, `${loc}: ${fe.message}`);
+      }
+    }
   }
   for (const pb of tpl.playbooks || []) {
     const ps = pb.subjectProfile?.profileSlug;
@@ -426,7 +645,9 @@ export function validateTemplate(
   // its base's workspace. The additive reconcile OVERWRITES workspace-level
   // settings, so an overlay MUST set workspace.subtype to its compose-base's slug
   // and MUST OMIT workspace.visibility — else it clobbers the base's identity.
-  const composeDeps = (tpl.dependencies || []).filter((d) => d.relation === "compose");
+  const composeDeps = (tpl.dependencies || []).filter(
+    (d) => d.relation === "compose"
+  );
   for (const dep of composeDeps) {
     if (tpl.workspace?.visibility !== undefined) {
       add(
@@ -448,7 +669,9 @@ export function validateTemplate(
   const blocks: TemplateBentoBlock[] = tpl.bento?.blocks ?? [];
   const authoredWidgets = blocks.filter((b) => b.kind === "widget");
   const authoredViews = blocks.filter((b) => b.kind === "view");
-  const unknownKind = blocks.filter((b) => b.kind !== "widget" && b.kind !== "view");
+  const unknownKind = blocks.filter(
+    (b) => b.kind !== "widget" && b.kind !== "view"
+  );
   if (unknownKind.length) {
     add(
       "bento-unknown-kind",
@@ -485,8 +708,18 @@ export function validateTemplate(
       const expectW = authoredWidgets.length - badWidgets.length;
       const expectV = authoredViews.length - badViews.length;
 
-      const doors: Array<[string, Array<{ widgetType?: unknown }>, Array<{ viewName?: unknown; kind?: unknown }>]> = [
-        ["tRPC createFromDefinition", definition.bentoLayout ?? [], definition.bentoViewBlocks ?? []],
+      const doors: Array<
+        [
+          string,
+          Array<{ widgetType?: unknown }>,
+          Array<{ viewName?: unknown; kind?: unknown }>,
+        ]
+      > = [
+        [
+          "tRPC createFromDefinition",
+          definition.bentoLayout ?? [],
+          definition.bentoViewBlocks ?? [],
+        ],
         ["CP packages/apply", pkg.bentoLayout ?? [], pkg.bentoViewBlocks ?? []],
       ];
       for (const [door, layout, viewBlocks] of doors) {
@@ -497,7 +730,9 @@ export function validateTemplate(
             `[${door}]: authored ${expectW} widget/${expectV} view → got ${layout.length} bentoLayout/${viewBlocks.length} bentoViewBlocks`
           );
         }
-        const layoutBad = layout.filter((b) => typeof b.widgetType !== "string");
+        const layoutBad = layout.filter(
+          (b) => typeof b.widgetType !== "string"
+        );
         const viewsBad = viewBlocks.filter(
           (b) => typeof b.viewName !== "string" || b.kind !== "view"
         );