@synap-core/workspace-templates 0.11.0 → 0.23.0

package/src/foundation.yaml

@@ -7,15 +7,18 @@
 meta:
   slug: foundation
   domain: strategy
-  name: Foundation
+  name: Strategy
   description: The strategic DNA — mission, audience, positioning, and principles — that every workspace inherits.
   icon: compass
   color: "#4F46E5"
   tags: [strategy, mission, positioning, audience]
   isPublic: true
+  # A LIBRARY: it produces nothing a home counts (homes).
+  intent:
+    label: Strategy
 
 workspace:
-  name: Foundation
+  name: Strategy
   description: The company's strategic DNA — mission, vision, audiences, pains, positioning, and operating principles that downstream workspaces inherit.
   proposalId: foundation-v1
   subtype: foundation
@@ -246,8 +249,9 @@ profiles:
   # every consumer must treat absence as "no commercial axis" rather than an
   # empty required field. Deliberately thin: what it is, whether it is live, how
   # it is priced, and the two identity rows it hangs off. Money AMOUNTS live on
-  # the deal/contract that references the offer, not here — an offer's price is a
-  # model, not a number.
+  # the deal/contract that references the offer, not here. The offer carries only
+  # a "starting at" list price (offer-list-price + currency + billing) so it can
+  # be advertised; the deal stays authoritative for what is actually paid.
   # ═══════════════════════════════════════════════════════════════════════════
   - slug: offer
     displayName: Offer
@@ -283,6 +287,30 @@ profiles:
           - usage-based
           - free
           - other
+      # "Starting at" list price. The deal/contract stays authoritative for what
+      # a buyer actually pays; these three only answer "what do we advertise".
+      - slug: offer-list-price
+        label: Starting at
+        valueType: number
+        inputType: number
+        placeholder: "List price, before any negotiation"
+      - slug: offer-currency
+        label: Currency
+        valueType: string
+        inputType: select
+        enumValues:
+          - EUR
+          - USD
+          - GBP
+          - CHF
+        constraints: { defaultValue: EUR }
+      - slug: offer-billing
+        label: Billing
+        valueType: string
+        inputType: select
+        enumValues:
+          - one-off
+          - monthly
       - slug: offer-audience
         label: Audience
         valueType: entity_id
@@ -324,17 +352,17 @@ profiles:
     applicableKinds:
       - company
       - person
+    # The ONE lifecycle (work model L1): the relationship base as it stands
+    # (prospect · active · paused · former · churned; lifecycle-presets.ts).
+    # The compiler writes the options and the select's enumValues.
+    lifecycle:
+      property: clientStatus
+      adopts: relationship
     properties:
       - slug: clientStatus
         label: Status
         valueType: string
         inputType: select
-        enumValues:
-          - prospect
-          - active
-          - paused
-          - former
-          - churned
       - slug: accountManager
         label: Account Manager
         valueType: string
@@ -379,6 +407,17 @@ profiles:
         label: Drive folder ID
         valueType: string
         inputType: text
+      # A state is never a role: an ended relationship is `clientStatus:
+      # churned` on THIS facet, not a separate `churned` role (retired
+      # 2026-10-11, work model W12/W13). Its two fields moved here with it.
+      - slug: churnedDate
+        label: Churned Date
+        valueType: date
+        inputType: date
+      - slug: churnReason
+        label: Churn reason
+        valueType: string
+        inputType: textarea
 
   # ── Partner (referral source + co-delivery collaborator) ──────────────────
   - slug: partner
@@ -486,47 +525,107 @@ profiles:
     applicableKinds:
       - company
       - person
+    # The ONE lifecycle (work model L1): every option's category. `converted`
+    # is a person's move (CRM build plan A4, 2026-10-22): it happens when a
+    # person records a booked meeting, which opens the deal; no agent sets it.
+    lifecycle:
+      property: leadStage
+      options:
+        - { key: new, category: open }
+        - { key: researching, category: open }
+        - { key: outreach, category: open }
+        - { key: engaged, category: active }
+        - { key: qualified, category: active }
+        - { key: nurturing, category: active }
+        - { key: converted, category: done, humanOnly: true }
+        - { key: disqualified, category: lost, humanOnly: true }
     properties:
+      # The lead role's ONE lifecycle (work model W15, 2026-10-11):
+      # qualification only. `converted` = a person recorded a booked meeting
+      # and a deal was opened (the sale then lives on the deal's commercialStage);
+      # `disqualified` = dropped. Business Developer's `lifecycleStage` overlay
+      # folded into this; old `prospect` → new, `lost` → disqualified
+      # (conversions `w12.lead.*`).
       - slug: leadStage
         label: Stage
         valueType: string
         inputType: select
         enumValues:
-          - prospect
+          - new
+          - researching
+          - outreach
+          - engaged
           - qualified
           - nurturing
           - converted
-          - lost
-        constraints: { defaultValue: prospect }
+          - disqualified
+        constraints: { defaultValue: new }
       - slug: notes
         label: Notes
         valueType: string
         inputType: textarea
 
-  # ── Churned (formerly-active relationship that ended) ──────────────────────
-  - slug: churned
-    displayName: Churned
-    icon: user-x
-    color: gray
-    description: A relationship (client, partner, or otherwise) that was active and has since ended.
+  # ── Roles the BUSINESS MODEL needs, and why they live here ─────────────────
+  # `porteur` and `funder` are hats, not kinds: the same person entity is a
+  # porteur of one venture and a funder of another, and the hat is revocable
+  # while the person is not. They are declared HERE because foundation.yaml is
+  # the shared-role SSOT (`shared-role-ssot.test.ts` derives the guarded
+  # vocabulary from this file) — declaring them in business-model.yaml instead
+  # would fork a second identity for a hat the whole pod refers to.
+  - slug: porteur
+    displayName: Porteur
+    icon: user-check
+    color: amber
+    description: The person carrying a venture — the one whose commitment, skills, and constraints the model actually rests on. Distinct from `client` (who pays) and `partner` (who collaborates).
     scope: shared
     profileKind: role
     applicableKinds:
-      - company
       - person
     properties:
-      - slug: churnedDate
-        label: Churned Date
-        valueType: date
-        inputType: date
-      - slug: churnReason
-        label: Reason
+      - slug: brings
+        label: What They Bring
         valueType: string
         inputType: textarea
-      - slug: notes
-        label: Notes
+        description: The specific competence, network, capital, or legitimacy this person contributes that the model depends on.
+      - slug: commitmentLevel
+        label: Commitment
+        valueType: string
+        inputType: select
+        enumValues: [full-time, part-time, advisory, intermittent]
+      - slug: constraints
+        label: Constraints
+        valueType: string
+        inputType: textarea
+        description: What limits this porteur — time, cash runway, geography, non-compete, family. A model that ignores these is fiction.
+  - slug: funder
+    displayName: Funder
+    icon: banknote
+    color: green
+    description: A source of non-revenue money or subsidy — a bank, a public scheme, an investor, a grantor. A hat worn by a company or a person, never a kind of its own.
+    scope: shared
+    profileKind: role
+    applicableKinds:
+      - company
+      - person
+    properties:
+      - slug: fundingType
+        label: Funding Type
+        valueType: string
+        inputType: select
+        enumValues: [grant, subsidy, loan, equity, guarantee, prize, other]
+      - slug: amountCommitted
+        label: Amount Committed
+        valueType: number
+        inputType: number
+      - slug: eligibilityConditions
+        label: Eligibility Conditions
         valueType: string
         inputType: textarea
+        description: The conditions the venture must satisfy to keep this money. These are the constraints most often discovered too late.
+      - slug: decisionDate
+        label: Decision Date
+        valueType: date
+        inputType: date
 
 views:
   - name: Mission & Vision
@@ -629,10 +728,12 @@ onboarding:
       alternatives — in one breath, with no fluff.
   collect:
     - profileSlug: mission
+      min: 1
       what: The one mission that anchors the company — what we serve, what we change, why now.
       cardinality: one
       keyFields: [statement, time-horizon]
     - profileSlug: audience
+      min: 1
       what: The ideal customer profiles the company is built for.
       cardinality: few
       keyFields: [segment, jobs-to-be-done]
@@ -641,6 +742,7 @@ onboarding:
       cardinality: several
       keyFields: [description, severity]
     - profileSlug: positioning
+      min: 1
       what: The market category, who we stand against, and why we win.
       cardinality: one
       keyFields: [category, against, because]

package/src/frame-host-modules.d.mts

@@ -0,0 +1,6 @@
+/** Types for `frame-host-modules.mjs` — the modules a space package's frame gets from its host. */
+export declare const FRAME_HOST_MODULES: readonly string[];
+export declare const FRAME_HOST_MODULE_RE: RegExp;
+export declare function hostRequiresIn(code: string): string[];
+export declare const FRAME_KIT_MODULE: string;
+export declare function kitImportsIn(code: string): string[];

package/src/frame-host-modules.mjs

@@ -0,0 +1,58 @@
+/**
+ * The modules a space package's frame gets from its HOST, never from its
+ * bundle (`@synap-core/web/cell-runtime` frame-import-map.ts): one React, its
+ * JSX runtimes, one react-dom, the view SDK, and the shared kit
+ * (`@synap/kit`, built from `packages/web/src/space-packages/kit.ts`). Shared
+ * by the build (`scripts/build-space-packages.mjs`, which keeps them external
+ * and builds the React modules and the kit as the host's frame modules) and
+ * the freshness test (which re-checks the committed bundle).
+ */
+export const FRAME_HOST_MODULES = [
+  'react',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@synap/view-sdk',
+  '@synap/kit',
+];
+
+/** The kit module's specifier (a package reaches the shared layers only through it). */
+export const FRAME_KIT_MODULE = '@synap/kit';
+
+/**
+ * Every name a bundle imports from the kit: `import{A as b,C}from"@synap/kit"`
+ * → `['A', 'C']`. A namespace or default import of the kit is returned as
+ * `*` / `default` so the build can refuse it (its names cannot be checked).
+ */
+export function kitImportsIn(code) {
+  const names = new Set();
+  for (const m of code.matchAll(/import\s*([^;'"]*?)\s*from\s*["']@synap\/kit["']/g)) {
+    const clause = m[1];
+    const braces = /\{([^}]*)\}/.exec(clause);
+    for (const part of braces ? braces[1].split(',') : []) {
+      const name = part.trim().split(/\s+as\s+/)[0];
+      if (name) names.add(name);
+    }
+    const head = clause.replace(/\{[^}]*\}/, '').replace(/,/g, ' ').trim();
+    if (/^\*\s*as\s+[\w$]+$/.test(head)) names.add('*');
+    else if (/^[\w$]+$/.test(head)) names.add('default');
+  }
+  return [...names].sort();
+}
+
+const NAMES = FRAME_HOST_MODULES.map((m) => m.replace(/[/.]/g, '\\$&')).join('|');
+
+/** Matches a host module name exactly (an esbuild `onResolve` filter). */
+export const FRAME_HOST_MODULE_RE = new RegExp(`^(${NAMES})$`);
+
+/**
+ * Every `require()` of a frame host module left in a bundle: a call to
+ * esbuild's `__require` shim, e.g. `jI("react")`. Each one throws in the frame
+ * ("Dynamic require of "react" is not supported"), so the module never links.
+ * `import("react")` and method calls (`x.f("react")`) are not requires.
+ */
+export function hostRequiresIn(code) {
+  const call = new RegExp(`(?<![\\w$.])(?!import\\()[A-Za-z_$][\\w$]*\\(\\s*["'](${NAMES})["']\\s*\\)`, 'g');
+  return [...code.matchAll(call)].map((m) => m[0]);
+}

package/src/generate.mjs

@@ -23,20 +23,26 @@ import { readFileSync, readdirSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import yaml from 'js-yaml';
+// `.ts` on purpose: this file runs under Node's type stripping (build.mjs) and
+// vitest; lifecycle-presets.ts has only `import type`.
+import { resolveLifecyclePresets } from './lifecycle-presets.ts';
 
 export const SRC_DIR = dirname(fileURLToPath(import.meta.url));
 export const TEMPLATES_FILE = join(SRC_DIR, 'templates.ts');
 
 /**
- * Read + parse every `src/*.yaml`, in the same (readdir) order build.mjs used.
- * No validation here — validation stays in build.mjs, which is the writer.
+ * Read + parse every `src/*.yaml`, in the same (readdir) order build.mjs used,
+ * and compile its lifecycle presets (`adopts:` → flat options, generated
+ * `enumValues`; see lifecycle-presets.ts). No validation here — validation
+ * stays in build.mjs, which is the writer; an overlay that cannot be resolved
+ * is left as authored and `validateTemplate` reports it.
  */
 export function readYamlTemplates() {
   return readdirSync(SRC_DIR)
     .filter((f) => f.endsWith('.yaml'))
     .map((file) => {
       const parsed = yaml.load(readFileSync(join(SRC_DIR, file), 'utf-8'));
-      return { file, slug: parsed?.meta?.slug, data: parsed };
+      return { file, slug: parsed?.meta?.slug, data: resolveLifecyclePresets(parsed).template };
     });
 }
 

package/src/github-merge.test.ts

@@ -0,0 +1,210 @@
+/**
+ * github-merge: a ship step as a governed tool verb (decision 4d6d7922: the pod
+ * holds the ship credential, an approval is a typed action pinned to a head,
+ * GitHub's own checks gate it).
+ *
+ * SEAM: the verb's REAL `code` body, run the way the pod's executor wraps it
+ * (`async (args, context) => { <code> }` with `callProvider` in scope), after
+ * the install-time values are put in its `{{repos}}` / `{{requiredChecks}}`
+ * the way the install templating does, against a recorded `callProvider`.
+ *
+ * NOT covered: the pod's own path (the approval, the vault, the sandbox) and
+ * GitHub itself (not exercised against a live repository: the proof merge in
+ * session 2d2a3473 does that).
+ */
+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", "github-merge.capability.json"), "utf8"),
+) as { spec: Record<string, any> };
+const verb = capability.spec.skills.find((s: { name: string }) => s.name === "github_merge_pr");
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (
+  ...args: string[]
+) => (...a: unknown[]) => Promise<unknown>;
+
+const SHA = "a524c103d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6";
+const ARGS = { repo: "Synap-core/app-bases", pr: 12, expectedHeadSha: SHA, base: "main", method: "squash" };
+const PR_PATH = "/repos/Synap-core/app-bases/pulls/12";
+
+type Reply = { status: number; body?: unknown };
+type Call = { tool: string; method: string; path: string; body?: unknown };
+
+function github(over: Partial<Record<string, Reply>> = {}): Record<string, Reply> {
+  return {
+    [`GET ${PR_PATH}`]: {
+      status: 200,
+      body: { state: "open", merged: false, draft: false, head: { sha: SHA }, base: { ref: "main" }, html_url: "https://github.com/Synap-core/app-bases/pull/12" },
+    },
+    [`GET /repos/Synap-core/app-bases/commits/${SHA}/check-runs?per_page=100`]: { status: 200, body: { check_runs: [] } },
+    [`GET /repos/Synap-core/app-bases/commits/${SHA}/status`]: {
+      status: 200,
+      body: { statuses: [{ context: "synap/devbox", state: "success" }] },
+    },
+    [`PUT ${PR_PATH}/merge`]: { status: 200, body: { merged: true, sha: "f00dfeed00000000000000000000000000000000" } },
+    ...over,
+  } as Record<string, Reply>;
+}
+
+async function run(
+  args: Record<string, unknown>,
+  replies: Record<string, Reply> = github(),
+  install: { repos?: string; requiredChecks?: string } = {},
+) {
+  const calls: Call[] = [];
+  const callProvider = async (tool: string, method: string, path: string, body?: unknown) => {
+    calls.push({ tool, method, path, ...(body === undefined ? {} : { body }) });
+    const r = replies[`${method} ${path}`];
+    if (!r) throw new Error(`unexpected call ${method} ${path}`);
+    return r;
+  };
+  const code = String(verb.code)
+    .replaceAll("{{repos}}", install.repos ?? "Synap-core/app-bases, https://github.com/Synap-core/browser")
+    .replaceAll("{{requiredChecks}}", install.requiredChecks ?? "synap/devbox");
+  const body = new AsyncFunction("args", "context", "callProvider", "propose", code);
+  try {
+    return { result: await body(args, {}, callProvider, {}), calls, error: null as Error | null };
+  } catch (error) {
+    return { result: null, calls, error: error as Error };
+  }
+}
+const merged = (calls: Call[]) => calls.some((c) => c.method === "PUT");
+
+describe("github-merge — the manifest", () => {
+  it("one write verb on its own tool, its own token, never pod-wide, separate from github-read", () => {
+    expect(capability.spec.key).toBe("github-merge");
+    expect(capability.spec.skills.map((s: { name: string }) => s.name)).toEqual(["github_merge_pr"]);
+    expect(verb.kind).toBe("code");
+    expect(verb.requires).toEqual(["github_merge_api"]);
+    expect(verb.metadata).toEqual({ verbType: "write" });
+    expect(verb.parameters).toEqual({ repo: "string", pr: "number", expectedHeadSha: "string", base: "string", method: "string?" });
+    expect(capability.spec.tools.map((t: { name: string; credentialRef: string }) => [t.name, t.credentialRef])).toEqual([
+      ["github_merge_api", "githubMergeTokenSecret"],
+    ]);
+    expect(capability.spec.vault.filter((v: { podWide?: boolean }) => v.podWide)).toEqual([]);
+    // github-read keeps its promise: it holds no write verb and no write tool.
+    const read = JSON.parse(readFileSync(join(import.meta.dirname, "..", "capabilities", "github-read.capability.json"), "utf8")).spec;
+    expect(read.skills.map((s: { name: string }) => s.name)).not.toContain("github_merge_pr");
+    // Every call goes to its own tool.
+    const tools = [...String(verb.code).matchAll(/callProvider\(\s*'([^']+)'/g)].map((m) => m[1]);
+    expect(tools.length).toBeGreaterThanOrEqual(2);
+    expect(new Set(tools)).toEqual(new Set(["github_merge_api"]));
+  });
+});
+
+describe("github_merge_pr — merges only the approved head, with its checks green", () => {
+  it("reads the PR and its checks, then merges pinned to the approved sha", async () => {
+    const { result, calls, error } = await run(ARGS);
+    expect(error).toBeNull();
+    expect(calls.map((c) => `${c.method} ${c.path}`)).toEqual([
+      `GET ${PR_PATH}`,
+      `GET /repos/Synap-core/app-bases/commits/${SHA}/check-runs?per_page=100`,
+      `GET /repos/Synap-core/app-bases/commits/${SHA}/status`,
+      `PUT ${PR_PATH}/merge`,
+    ]);
+    expect(calls.at(-1)!.body).toEqual({ sha: SHA, merge_method: "squash" });
+    expect(result).toEqual({
+      merged: true,
+      mergeCommitSha: "f00dfeed00000000000000000000000000000000",
+      url: "https://github.com/Synap-core/app-bases/pull/12",
+      detail: "Merged Synap-core/app-bases#12 at a524c103 into main as f00dfeed.",
+    });
+  });
+
+  it("a repository not in the install's list is refused before anything is read", async () => {
+    const { calls, error } = await run({ ...ARGS, repo: "Synap-core/backend" });
+    expect(error?.message).toMatch(/Synap-core\/backend is not in this pod's merge list/);
+    expect(calls).toEqual([]);
+  });
+
+  it("a head that moved since the approval is refused, never merged", async () => {
+    const replies = github({
+      [`GET ${PR_PATH}`]: { status: 200, body: { state: "open", head: { sha: "b".repeat(40) }, base: { ref: "main" } } },
+    });
+    const { calls, error } = await run(ARGS, replies);
+    expect(error?.message).toMatch(/moved since it was approved: approved a524c103, head is now bbbbbbbb/);
+    expect(merged(calls)).toBe(false);
+  });
+
+  it("a required check missing, pending or failed refuses; so does any failed check", async () => {
+    const statusPath = `GET /repos/Synap-core/app-bases/commits/${SHA}/status`;
+    const runsPath = `GET /repos/Synap-core/app-bases/commits/${SHA}/check-runs?per_page=100`;
+    const cases: Array<[Record<string, Reply>, RegExp]> = [
+      [{ [statusPath]: { status: 200, body: { statuses: [] } } }, /missing: synap\/devbox/],
+      [{ [statusPath]: { status: 200, body: { statuses: [{ context: "synap/devbox", state: "pending" }] } } }, /not green: synap\/devbox \(pending\)/],
+      [{ [statusPath]: { status: 200, body: { statuses: [{ context: "synap/devbox", state: "failure" }] } } }, /not green: synap\/devbox \(failed\)/],
+      [
+        { [runsPath]: { status: 200, body: { check_runs: [{ id: 1, name: "lint", status: "completed", conclusion: "failure" }] } } },
+        /failed: lint/,
+      ],
+    ];
+    for (const [over, reason] of cases) {
+      const { calls, error } = await run(ARGS, github(over));
+      expect(error?.message).toMatch(reason);
+      expect(merged(calls)).toBe(false);
+    }
+  });
+
+  it("a check that failed then passed on a re-run reads by its latest run", async () => {
+    const runsPath = `GET /repos/Synap-core/app-bases/commits/${SHA}/check-runs?per_page=100`;
+    const replies = github({
+      [runsPath]: {
+        status: 200,
+        body: {
+          check_runs: [
+            { id: 9, name: "lint", status: "completed", conclusion: "success" },
+            { id: 3, name: "lint", status: "completed", conclusion: "failure" },
+          ],
+        },
+      },
+    });
+    const { error, calls } = await run(ARGS, replies);
+    expect(error).toBeNull();
+    expect(merged(calls)).toBe(true);
+  });
+
+  it("no required check configured refuses: nothing would vouch for the head", async () => {
+    const { calls, error } = await run(ARGS, github(), { requiredChecks: " , " });
+    expect(error?.message).toMatch(/no required checks are configured/);
+    expect(calls).toEqual([]);
+  });
+
+  it("a PR that is merged, closed, a draft or targets another base is refused", async () => {
+    const pr = (body: Record<string, unknown>) =>
+      github({ [`GET ${PR_PATH}`]: { status: 200, body: { state: "open", head: { sha: SHA }, base: { ref: "main" }, ...body } } });
+    for (const [body, reason] of [
+      [{ merged: true }, /already merged/],
+      [{ state: "closed" }, /is closed/],
+      [{ draft: true }, /is a draft/],
+      [{ base: { ref: "release" } }, /targets release, not main/],
+    ] as Array<[Record<string, unknown>, RegExp]>) {
+      const { calls, error } = await run(ARGS, pr(body));
+      expect(error?.message).toMatch(reason);
+      expect(merged(calls)).toBe(false);
+    }
+  });
+
+  it("arguments that cannot pin the act are refused before any call", async () => {
+    for (const bad of [
+      { ...ARGS, expectedHeadSha: "a524c103" },
+      { ...ARGS, pr: 0 },
+      { ...ARGS, base: "" },
+      { ...ARGS, method: "force" },
+      { ...ARGS, repo: "app-bases" },
+    ]) {
+      const { calls, error } = await run(bad);
+      expect(error, JSON.stringify(bad)).not.toBeNull();
+      expect(calls).toEqual([]);
+    }
+  });
+
+  it("a failed read or a merge GitHub refuses throws: nothing reads as merged", async () => {
+    const unread = await run(ARGS, github({ [`GET ${PR_PATH}`]: { status: 404, body: {} } }));
+    expect(unread.error?.message).toMatch(/HTTP 404/);
+    expect(merged(unread.calls)).toBe(false);
+    const refused = await run(ARGS, github({ [`PUT ${PR_PATH}/merge`]: { status: 409, body: { message: "Head branch was modified" } } }));
+    expect(refused.error?.message).toMatch(/refused to merge .*HTTP 409: Head branch was modified/);
+  });
+});