@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/unipile-publish-post.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Unipile — what a pod app may ask it to publish (intent actions, decision
+ * ef0e917c, 2026-10-28; the Postiz precedent is postiz-contract.test.ts).
+ *
+ * A pod app asks the person's tools for `publish_post` with ONE input
+ * `{ text, media?, link?, when? }`. Unipile reaches several accounts through one
+ * key, so `unipile_publish_post` names an account source and the pod offers one
+ * action per account: the shared `unipile_list_accounts`, every provider, so
+ * LinkedIn and Instagram each get their own action (founder, 28 Oct, on
+ * decision 34103d1b). The post's images and videos come as `file[]:bytes`
+ * (phase 2c of plan e7c3c98e): the code holds one handle per pod file and the
+ * pod streams the bytes into a multipart part, so Instagram can post.
+ *
+ * SEAM: the verb's REAL `code` body, run the way the pod's executor wraps it
+ * (`async (args, context) => { <code> }` with `callProvider` in scope), against
+ * a recorded `callProvider`.
+ *
+ * NOT covered: the pod's own checks of the map and of `file[]:bytes`
+ * (backend `intent-input.ts`, `file-parameters.ts`), the handles turning into
+ * bytes (backend `pod-file-body.ts`), and whether Unipile accepts the request
+ * (not exercised against a live Unipile).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const capability = JSON.parse(
+  readFileSync(join(import.meta.dirname, "..", "capabilities", "unipile-linkedin.capability.json"), "utf8"),
+) as { spec: { skills: Array<Record<string, any>>; provides?: string[] } };
+
+const skill = (name: string) => capability.spec.skills.find((s) => s.name === name)!;
+const verb = skill("unipile_publish_post");
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (
+  ...args: string[]
+) => (...a: unknown[]) => Promise<unknown>;
+
+type Call = { tool: string; method: string; path: string; body: Record<string, unknown>; opts?: Record<string, unknown> };
+async function run(args: Record<string, unknown>, reply: Record<string, unknown> = { status: 201, body: { id: "p1", share_url: "https://x/p1" } }) {
+  const calls: Call[] = [];
+  const callProvider = async (tool: string, method: string, path: string, body: Record<string, unknown>, opts?: Record<string, unknown>) => {
+    calls.push({ tool, method, path, body, opts });
+    return reply;
+  };
+  const body = new AsyncFunction("args", "context", "callProvider", "propose", verb.code);
+  const result = await body(args, {}, callProvider, {});
+  return { result, calls };
+}
+
+describe("Unipile — what a pod app may ask it to publish", () => {
+  it("unipile_publish_post maps the text, the media and the account picked from unipile_list_accounts", () => {
+    expect(verb.intent).toBe("publish_post");
+    expect(verb.metadata).toEqual({ verbType: "write" });
+    expect(verb.inputMap).toEqual({
+      params: { text: "$.text", accountId: "$account.id", provider: "$account.provider", media: "$.media" },
+      accounts: { verb: "unipile_list_accounts", id: "id", label: "name", provider: "provider" },
+    });
+    expect(capability.spec.provides).toContain("publish_post");
+  });
+
+  it("Unipile has no scheduling and links stay out: the map never reads when or link", () => {
+    const read = Object.values(verb.inputMap.params).filter((s) => !String(s).startsWith("$account."));
+    expect(read.sort()).toEqual(["$.media", "$.text"]);
+  });
+
+  it("the media are pod files sent as bytes, so the verb is code run in the pod, toward its own tool", () => {
+    expect(verb.kind).toBe("code");
+    expect(verb.executionMode).not.toBe("box");
+    expect(verb.parameters).toEqual({
+      accountId: "string",
+      text: "string",
+      provider: "string?",
+      media: "file[]:bytes?",
+      postAs: "string?",
+      quotedPostId: "string?",
+    });
+    expect(verb.requires).toEqual(["unipile_linkedin"]);
+    // An install-time value in the code would stop the pod updating Unipile.
+    expect(verb.code).not.toMatch(/\{\{\w+\}\}/);
+  });
+
+  it("text alone is a JSON post of exactly { text } to /{accountId}/posts", async () => {
+    const { result, calls } = await run({ accountId: "acc_1", text: "Hello", provider: "linkedin" });
+    expect(calls).toEqual([{ tool: "unipile_linkedin", method: "POST", path: "/acc_1/posts", body: { text: "Hello" }, opts: undefined }]);
+    expect(result).toEqual({ postId: "p1", shareUrl: "https://x/p1", attachments: 0 });
+  });
+
+  it("with media, a multipart form: the text field and one attachments[i] part per pod file", async () => {
+    const { result, calls } = await run({ accountId: "acc_2", text: "Caption", provider: "instagram", media: ["podfile:a", "podfile:b"] });
+    expect(calls).toEqual([
+      {
+        tool: "unipile_linkedin",
+        method: "POST",
+        path: "/acc_2/posts",
+        body: { text: "Caption", "attachments[0]": "podfile:a", "attachments[1]": "podfile:b" },
+        opts: { multipart: true },
+      },
+    ]);
+    expect(result).toMatchObject({ postId: "p1", attachments: 2 });
+  });
+
+  it("refuses before any call: Instagram with no media, an account with no posts, no text", async () => {
+    await expect(run({ accountId: "acc_2", text: "Caption", provider: "instagram" })).rejects.toThrow(/Instagram needs at least one image or video/);
+    await expect(run({ accountId: "acc_3", text: "Hi", provider: "whatsapp" })).rejects.toThrow(/whatsapp account has no posts/);
+    await expect(run({ accountId: "acc_1", text: " ", provider: "linkedin" })).rejects.toThrow(/text is required/);
+  });
+
+  it("as a LinkedIn company page: post_as beside the text, as JSON and in the multipart form", async () => {
+    const { calls } = await run({ accountId: "acc_1", text: "Hello", provider: "linkedin", postAs: "12345" });
+    expect(calls[0]).toMatchObject({ path: "/acc_1/posts", body: { text: "Hello", post_as: "12345" }, opts: undefined });
+    const multi = await run({ accountId: "acc_1", text: "Hi", provider: "linkedin", postAs: "12345", media: ["podfile:a"] });
+    expect(multi.calls[0]).toMatchObject({ body: { text: "Hi", post_as: "12345", "attachments[0]": "podfile:a" }, opts: { multipart: true } });
+  });
+
+  it("a repost: quoted_post_id, with empty text a plain repost, with text a quote", async () => {
+    const plain = await run({ accountId: "acc_1", text: "", provider: "linkedin", quotedPostId: "WzEy" });
+    expect(plain.calls[0].body).toEqual({ text: "", quoted_post_id: "WzEy" });
+    const quote = await run({ accountId: "acc_1", text: "Worth a read", quotedPostId: "WzEy", postAs: "12345" });
+    expect(quote.calls[0].body).toEqual({ text: "Worth a read", post_as: "12345", quoted_post_id: "WzEy" });
+  });
+
+  it("an empty company page or original is left out, and Instagram refuses both before any call", async () => {
+    const { calls } = await run({ accountId: "acc_1", text: "Hello", provider: "linkedin", postAs: " ", quotedPostId: "" });
+    expect(calls[0].body).toEqual({ text: "Hello" });
+    await expect(run({ accountId: "acc_2", text: "C", provider: "instagram", media: ["podfile:a"], quotedPostId: "WzEy" })).rejects.toThrow(/Instagram has no company page post or repost/);
+    await expect(run({ accountId: "acc_2", text: "C", provider: "instagram", media: ["podfile:a"], postAs: "1" })).rejects.toThrow(/Instagram has no company page post or repost/);
+  });
+
+  it("linkedin_list_company_pages: a read of the same tool, listing each page's id and name", () => {
+    const pages = skill("linkedin_list_company_pages");
+    expect(pages).toMatchObject({ intent: "list_records", kind: "declarative", metadata: { readOnly: true }, parameters: { accountId: "string" } });
+    expect(pages.requires).toEqual(verb.requires);
+    expect(pages.providerSpec).toMatchObject({
+      tool: "unipile_linkedin",
+      method: "GET",
+      pathTemplate: "/{{accountId}}/linkedin/company/pages",
+      responseShape: { collectionPath: "data", item: { id: "id", name: "name" } },
+    });
+    // A read never maps into an app's intent: nothing publishes through it.
+    expect(pages.inputMap).toBeUndefined();
+  });
+
+  it("a refused post throws, and a proposed call is never reported as published", async () => {
+    await expect(run({ accountId: "acc_1", text: "Hello" }, { status: 422, body: {} })).rejects.toThrow(/status 422/);
+    const { result } = await run({ accountId: "acc_1", text: "Hello" }, { proposed: true, proposalId: "pr1" });
+    expect(result).toEqual({ success: false, proposed: true, proposalId: "pr1" });
+  });
+
+  it("the account source is a read of the same tool that lists every account with the fields it names", () => {
+    const list = skill("unipile_list_accounts");
+    expect(list.metadata).toEqual({ readOnly: true });
+    expect(list.requires).toEqual(verb.requires);
+    expect(list.providerSpec).toMatchObject({ method: "GET", pathTemplate: "/accounts/" });
+    expect(list.providerSpec.query).toBeUndefined();
+    expect(Object.keys(list.providerSpec.responseShape.item)).toEqual(expect.arrayContaining(["id", "name", "provider"]));
+  });
+
+  it("one Unipile verb publishes for apps", () => {
+    const mapped = capability.spec.skills.filter((s) => s.inputMap && s.intent === "publish_post").map((s) => s.name);
+    expect(mapped).toEqual(["unipile_publish_post"]);
+  });
+});

package/src/validate-flow.drift.test.ts

@@ -22,6 +22,7 @@ import { describe, expect, it } from "vitest";
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { stripComments } from "../../design-tokens/scripts/strip-comments.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const OWN_COPY = join(HERE, "validate-flow.ts");
@@ -40,11 +41,9 @@ const BACKEND_COPY = join(
  *     normalize whitespace.
  */
 function normalizeFlowValidatorSource(src: string): string {
-  return src
+  return stripComments(src, "ts")
     .replace(/import type \{[^}]*\} from ["']@synap\/database["'];/g, "")
     .replace(/type AssertExact<[\s\S]*?void _outputTypesInSync;/g, "")
-    .replace(/\/\*[\s\S]*?\*\//g, "") // block comments (incl. JSDoc)
-    .replace(/\/\/.*$/gm, "") // line + trailing comments
     .split("\n")
     .map((l) => l.replace(/\s+/g, " ").trim())
     .filter((l) => l.length > 0)

package/src/validate-flow.ts

@@ -35,6 +35,7 @@
  * Until then: keep the constant arrays below identical to `@synap/database`
  * `schema/automations.ts`.
  */
+import { PLAYBOOK_RUN_MODES } from "@synap-core/types/automations";
 
 // ── Contract constants (mirror schema/automations.ts — keep in sync) ──────────
 
@@ -65,9 +66,10 @@ export const FLOW_NODE_TYPES = [
   "playbook_run",
 ] as const;
 
-/** The 11 output types — `OutputNodeDef.data.outputType` (schema/automations.ts). */
+/** The 15 output types — `OutputNodeDef.data.outputType` (schema/automations.ts). */
 export const FLOW_OUTPUT_TYPES = [
   "notification",
+  "record_observation",
   "entity_create",
   "entity_update",
   "facet_attach",
@@ -77,6 +79,9 @@ export const FLOW_OUTPUT_TYPES = [
   "webhook",
   "channel_message",
   "session_update",
+  "complete_outcome",
+  "post_evidence",
+  "reevaluate_criterion",
   "set_state",
 ] as const;
 
@@ -380,6 +385,21 @@ export function validateFlowDefinition(
             }) that does not exist.`,
           });
         }
+        // An unknown `mode` would silently RUN (`readPlaybookRunMode` reads it
+        // as the default) — the opposite of what an author who typed
+        // "propose" wanted. Refused by name at the door instead.
+        if (
+          data.mode !== undefined &&
+          !(PLAYBOOK_RUN_MODES as readonly unknown[]).includes(data.mode)
+        ) {
+          errors.push({
+            nodeId,
+            code: "playbook_run_bad_mode",
+            message: `Playbook-run node "${nodeId}" has mode ${JSON.stringify(
+              data.mode
+            )}; expected one of ${PLAYBOOK_RUN_MODES.join(", ")}.`,
+          });
+        }
         break;
       }
 
@@ -667,7 +687,17 @@ function collectLoopBindingRefs(data: unknown): string[] {
       return;
     }
     if (isRecord(v)) {
-      for (const x of Object.values(v)) walk(x);
+      // Skip AUTHORING NOTES. An `_`-prefixed key is documentation the runtime
+      // never evaluates (`_filterNote` and friends explain what DOWNSTREAM
+      // nodes do, and so legitimately quote `{{loop.item...}}` in prose).
+      // Reading them as live references made a correct flow fail validation:
+      // a (since-removed) grant capability was reported as "references {{loop.item}} but is
+      // not inside a loop body" purely because its note DESCRIBED the nodes
+      // that do. Kept identical in all three copies of this walker.
+      for (const [k, x] of Object.entries(v)) {
+        if (k.startsWith("_")) continue;
+        walk(x);
+      }
     }
   };
   walk(data);

package/src/validate-onboarding.test.ts

@@ -85,4 +85,63 @@ describe("validateTemplate onboarding contract", () => {
       ])
     );
   });
+
+  it("a steady-state brief needs no interview: purpose + anchors + fetch is valid", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({
+        purpose: "Where records live.",
+        anchors: [{ profileSlug: "record", role: "root", limit: 1 }],
+        fetch: [{ profileSlug: "record", note: "the live ones" }],
+      }),
+      {}
+    );
+    expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("an interview still requires its persona and collect targets", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({ goal: "Set it up.", openingQuestions: ["Why?"] }),
+      {}
+    );
+    expect(result.errors.map((e) => e.rule)).toEqual(
+      expect.arrayContaining(["onboarding-framing-empty", "onboarding-collect-empty"])
+    );
+  });
+
+  it("rejects a brief that says nothing, bad anchors, bad fetch hints and bad minimums", () => {
+    const result = validateTemplate(
+      templateWithOnboarding({
+        anchors: [
+          { profileSlug: "record", role: "root", seedRef: "Nope" },
+          { profileSlug: "record", role: "root" },
+          { profileSlug: "ghost", role: "context" },
+        ],
+        fetch: [{ note: "no target" }],
+        collect: [{ profileSlug: "record", what: "x", min: 0 }],
+      }),
+      {}
+    );
+    expect(result.errors.map((e) => e.rule)).toEqual(
+      expect.arrayContaining([
+        "onboarding-brief-empty",
+        "onboarding-anchor-seedref-unknown",
+        "onboarding-anchor-invalid",
+        "onboarding-fetch-invalid",
+        "onboarding-collect-min-invalid",
+      ])
+    );
+  });
+
+  it("template rules need a unique kebab key and an intent", () => {
+    const tpl = templateWithOnboarding(undefined);
+    tpl.rules = [
+      { key: "use-approved", intent: "Use approved assets first." },
+      { key: "use-approved", intent: "Dup." },
+      { key: "Bad Key", intent: "" },
+    ];
+    const rules = validateTemplate(tpl, {}).errors.map((e) => e.rule);
+    expect(rules).toEqual(
+      expect.arrayContaining(["rule-key-duplicate", "rule-key-invalid", "rule-intent-empty"])
+    );
+  });
 });

package/src/validate.test.ts

@@ -15,7 +15,7 @@ import type { WorkspaceYaml } from "./types.js";
 describe("validateTemplate — fires on a bad template", () => {
   const bad = {
     // meta.slug MISSING — required field.
-    meta: { name: "Bad", description: "d", icon: "x", color: "#000000" },
+    meta: { name: "Bad", description: "d", icon: "x", color: "violet" },
     workspace: { name: "Bad", description: "d" },
     profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
     automations: [
@@ -65,7 +65,7 @@ describe("validateTemplate — clean template", () => {
         name: "Good",
         description: "d",
         icon: "x",
-        color: "#000000",
+        color: "violet",
       },
       workspace: { name: "Good", description: "d" },
       profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
@@ -80,6 +80,92 @@ describe("validateTemplate — clean template", () => {
   });
 });
 
+describe("validateTemplate — system Knowledge contract", () => {
+  const template = (overrides: Record<string, unknown> = {}): WorkspaceYaml =>
+    ({
+      meta: {
+        slug: "knowledge-consumer",
+        name: "Knowledge consumer",
+        description: "d",
+        icon: "brain",
+        color: "violet",
+      },
+      workspace: { name: "Knowledge consumer", description: "d" },
+      profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+      views: [
+        {
+          name: "Knowledge",
+          type: "table",
+          scopeProfileSlug: "knowledge",
+          config: { columns: ["title", "knowledgeForm"] },
+        },
+      ],
+      ...overrides,
+    }) as WorkspaceYaml;
+
+  it("allows templates to consume system Knowledge without redeclaring it", () => {
+    const result = validateTemplate(
+      template({
+        seedEntities: [
+          {
+            profileSlug: "knowledge",
+            title: "Write migrations that preserve meaning",
+            properties: { knowledgeForm: "insight" },
+          },
+        ],
+      })
+    );
+
+    expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("rejects a template-owned Knowledge profile", () => {
+    const result = validateTemplate(
+      template({
+        profiles: [
+          {
+            slug: "knowledge",
+            displayName: "Knowledge",
+            properties: [
+              {
+                slug: "ek_type",
+                label: "Type",
+                valueType: "string",
+                inputType: "select",
+                enumValues: ["gotcha", "lesson"],
+              },
+            ],
+          },
+        ],
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.some((error) => error.rule === "system-profile-redefined")
+    ).toBe(true);
+  });
+
+  it("rejects a legacy or missing Knowledge form on seeded Knowledge", () => {
+    const result = validateTemplate(
+      template({
+        seedEntities: [
+          {
+            profileSlug: "knowledge",
+            title: "Legacy knowledge",
+            properties: { ek_type: "gotcha" },
+          },
+        ],
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.map((error) => error.rule).sort()
+    ).toEqual(["knowledge-seed-form-invalid", "knowledge-seed-legacy-form"]);
+  });
+});
+
 // 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
@@ -92,7 +178,7 @@ describe("validateTemplate — automation flow node contract", () => {
         name: "Flowy",
         description: "d",
         icon: "x",
-        color: "#000000",
+        color: "violet",
       },
       workspace: { name: "Flowy", description: "d" },
       profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
@@ -200,3 +286,70 @@ describe("validateTemplate — automation flow node contract", () => {
     });
   });
 });
+
+describe("validateTemplate — a pack needs no profile shell (D8)", () => {
+  const pack = (tags: string[], deps: unknown[]) =>
+    ({
+      meta: {
+        slug: "acme-suite",
+        name: "Acme",
+        description: "d",
+        icon: "x",
+        color: "violet",
+        tags,
+      },
+      workspace: { name: "Acme", description: "d" },
+      profiles: [],
+      dependencies: deps,
+    }) as unknown as WorkspaceYaml;
+  const profileErrors = (t: WorkspaceYaml) =>
+    validateTemplate(t, {}).errors.filter((e) => e.rule === "profiles-required");
+
+  it("a suite that requires a workspace is valid without profiles", () => {
+    expect(
+      profileErrors(pack(["suite"], [{ slug: "crm", kind: "workspace", relation: "require" }]))
+    ).toEqual([]);
+  });
+
+  it("a suite requiring NO workspace still needs a profile", () => {
+    expect(profileErrors(pack(["suite"], []))).toHaveLength(1);
+  });
+
+  it("a non-suite template without profiles is still refused", () => {
+    expect(
+      profileErrors(pack([], [{ slug: "crm", kind: "workspace", relation: "require" }]))
+    ).toHaveLength(1);
+  });
+});
+
+describe("validateTemplate — entityLinks[].required", () => {
+  const withLinks = (entityLinks: unknown[]) =>
+    ({
+      meta: { slug: "links", name: "Links", description: "d", icon: "x", color: "violet" },
+      workspace: { name: "Links", description: "d" },
+      profiles: [
+        { slug: "gadget", displayName: "Gadget", properties: [] },
+        { slug: "widget", displayName: "Widget", properties: [] },
+      ],
+      entityLinks,
+    }) as unknown as WorkspaceYaml;
+  const link = { sourceProfileSlug: "gadget", targetProfileSlug: "widget", type: "relates_to" };
+  const requiredErrors = (t: WorkspaceYaml) =>
+    validateTemplate(t, {}).errors.filter((e) => e.rule === "entitylink-required-not-boolean");
+
+  it("accepts required: true, required: false and no required", () => {
+    const result = validateTemplate(
+      withLinks([{ ...link, required: true }, { ...link, type: "part_of", required: false }, { ...link, type: "mentions" }]),
+      {}
+    );
+    expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("refuses a required that is not a boolean, naming the link", () => {
+    for (const bad of ["yes", 1, "true", null]) {
+      const errors = requiredErrors(withLinks([{ ...link, required: bad }]));
+      expect(errors, String(bad)).toHaveLength(1);
+      expect(errors[0]!.message).toContain("gadget→widget (relates_to)");
+    }
+  });
+});