@synap-core/workspace-templates 0.9.2 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/workspace-templates",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "description": "Canonical workspace definitions — YAML source + typed exports for browser, backend, CLI, and marketplace",

package/src/business-developer.yaml

@@ -86,14 +86,13 @@ profiles:
         inputType: select
         enumValues:
           [
-            manual,
-            referral,
+            cold-outreach,
             linkedin,
-            email,
+            twitter,
+            landing-page,
+            inbound-call,
+            referral,
             event,
-            inbound,
-            partner,
-            import,
             other,
           ]
       - slug: icpScore
@@ -352,6 +351,25 @@ profiles:
         label: Notes
         valueType: string
         inputType: textarea
+      # `campaign-type` is the campaign's NATURE/phase, orthogonal to
+      # `campaign-channel` (the delivery medium). scoping/outreach/live have no
+      # channel equivalent, so folding them into `campaign-channel` would lose
+      # them — they get their own def. Kept verbatim across the three campaign
+      # declarations (marketing / content-os / here) so there is no drift.
+      - slug: campaign-type
+        label: Type
+        valueType: string
+        inputType: select
+        enumValues:
+          [scoping, outreach, live, partnership, event, other]
+        constraints: { defaultValue: outreach }
+      # `campaign-color` backs the per-campaign colour the CRM surfaces render.
+      # Stored as a palette NAME (see apps/crm/lib/campaignColors.ts), not a hex.
+      - slug: campaign-color
+        label: Color
+        valueType: string
+        inputType: select
+        enumValues: [indigo, violet, amber, cyan, pink, teal]
 
 entityLinks:
   # The existing generic `linked_to_deal` relation remains the deal ↔

package/src/content-os.yaml

@@ -623,6 +623,25 @@ profiles:
         label: Notes
         valueType: string
         inputType: textarea
+      # `campaign-type` is the campaign's NATURE/phase, orthogonal to
+      # `campaign-channel` (the delivery medium). scoping/outreach/live have no
+      # channel equivalent, so folding them into `campaign-channel` would lose
+      # them — they get their own def. Kept verbatim across the three campaign
+      # declarations (business-developer / marketing / here) so there is no drift.
+      - slug: campaign-type
+        label: Type
+        valueType: string
+        inputType: select
+        enumValues:
+          [scoping, outreach, live, partnership, event, other]
+        constraints: { defaultValue: outreach }
+      # `campaign-color` backs the per-campaign colour the CRM surfaces render.
+      # Stored as a palette NAME (see apps/crm/lib/campaignColors.ts), not a hex.
+      - slug: campaign-color
+        label: Color
+        valueType: string
+        inputType: select
+        enumValues: [indigo, violet, amber, cyan, pink, teal]
 
   # ── Sponsor (shared ecosystem role — SSOT is foundation.yaml) ─────────────
   # `scope: shared` dedups to the ONE pod-wide `sponsor` role seeded by

package/src/crm.yaml

@@ -18,6 +18,14 @@ meta:
     - contacts
   isPublic: true
 
+# Canonical hosted surface. Browser resolves auth from appId and launches this
+# URL with non-secret workspace/Pod context; CRM establishes its own session.
+app:
+  kind: url
+  appId: crm
+  url: https://crm.synap.live
+  title: CRM
+
 # SSOT ordering guarantee — this template REFERENCES foundation's pod-wide
 # shared `client`/`partner`/`lead`/`churned` roles below. The apply engine seeds
 # a shared profile's pod-wide BASE property body from whichever template
@@ -79,7 +87,16 @@ profiles:
       - slug: source
         label: Source
         valueType: string
-        inputType: text
+        inputType: select
+        enumValues:
+          - cold-outreach
+          - linkedin
+          - twitter
+          - landing-page
+          - inbound-call
+          - referral
+          - event
+          - other
       - slug: icpScore
         label: ICP score
         valueType: number
@@ -141,7 +158,16 @@ profiles:
       - slug: source
         label: Source
         valueType: string
-        inputType: text
+        inputType: select
+        enumValues:
+          - cold-outreach
+          - linkedin
+          - twitter
+          - landing-page
+          - inbound-call
+          - referral
+          - event
+          - other
       - slug: icpScore
         label: ICP score
         valueType: number
@@ -438,6 +464,72 @@ entityLinks:
     targetProfileSlug: deal
     type: linked_to_deal
 
+onboarding:
+  goal: >
+    Turn the user's real commercial motion into a usable pipeline — the right
+    companies and people, their active opportunities, and an explicit next
+    step for every deal — so CRM becomes the place sales work moves forward.
+  framing: >
+    THE REVENUE OPERATOR: Act as a pragmatic sales lead setting up a CRM people
+    will actually maintain. Start from the user's existing motion, vocabulary,
+    and active conversations. Resolve before creating so imported or Pod-wide
+    people are reused rather than duplicated. Push for a concrete next step and
+    date; never invent revenue, probability, or contact details.
+  expertise:
+    starters:
+      - >
+        A useful first pipeline is deliberately small. Start with the few stages
+        that change how the team acts — contacted, qualifying, proposal,
+        negotiating, won, and lost — and keep the template's default stages
+        unless the user's real process needs a different view.
+      - >
+        Populate the workspace with live work, not a perfect historical archive:
+        propose the three to five opportunities the user is actively trying to
+        move, then add the companies and people needed to understand those deals.
+      - >
+        Every active deal needs one observable next step with a date. If the next
+        step is "follow up" or "keep warm", help turn it into a specific action
+        such as "send the revised proposal Thursday" before capturing it.
+    blindSpots:
+      - >
+        A deal without a real person is usually an account-shaped hope. If an
+        opportunity has no stakeholder, surface the gap instead of fabricating a
+        placeholder contact.
+      - >
+        Pipelines become fiction when stages describe confidence rather than an
+        event the buyer completed. Ask what evidence moves a deal into its current
+        stage, especially around proposal and negotiation.
+      - >
+        More fields do not create better sales hygiene. Prioritize stage, value
+        when known, expected close date, and next step; leave unverifiable fields
+        empty and offer enrichment separately.
+    bar: >
+      A sales lead can open the pipeline and immediately see the few live
+      opportunities, the real company and stakeholder behind each one, its
+      evidence-based stage, and the dated next action — with no duplicate people
+      and no invented commercial data.
+  collect:
+    - profileSlug: company
+      what: The real prospect organisations behind current conversations.
+      cardinality: few
+      keyFields: [website, industry, companySize, source, nextStep]
+    - profileSlug: person
+      what: The known stakeholders for those organisations and opportunities.
+      cardinality: few
+      keyFields: [email, jobTitle, company, source, nextFollowUpDate]
+    - profileSlug: deal
+      what: The live opportunities worth actively moving through the pipeline.
+      cardinality: few
+      keyFields: [dealStage, value, closeDate, nextStep]
+  openingQuestions:
+    - "Which three to five opportunities are you actively trying to move right now?"
+    - "For the most important one, which company and real stakeholder are involved?"
+    - "What has the buyer actually done so far, and what is the next dated action?"
+  doneWhen: >
+    At least one real opportunity is linked to its company or stakeholder and
+    has an evidence-based stage plus a concrete next step; the user can see how
+    to add or import the rest without duplicating existing people.
+
 # Playbook — enriches a lead/prospect from public sources (company site,
 # LinkedIn, firmographic signal) so ICP scoring and qualification start from
 # real data instead of a blank record. Bound to `lead` so a newly captured

package/src/define.primary-surface.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+import {
+  normalizeTemplateLayout,
+  toPackageDefinition,
+  toWorkspaceDefinition,
+} from './define.js';
+import type { WorkspaceYaml } from './types.js';
+import { validateTemplate } from './validate.js';
+
+function template(
+  overrides: Partial<Pick<WorkspaceYaml, 'app' | 'layout' | 'views' | 'bento'>>
+): WorkspaceYaml {
+  return {
+    meta: {
+      slug: 'surface-contract-test',
+      name: 'Surface contract test',
+      description: 'Surface contract fixture',
+      icon: 'panels-top-left',
+      color: 'blue',
+    },
+    workspace: {
+      name: 'Surface contract test',
+      description: 'Surface contract fixture',
+    },
+    profiles: [{ slug: 'thing', displayName: 'Thing', properties: [] }],
+    ...overrides,
+  };
+}
+
+describe('workspace primary-surface conversion', () => {
+  it('normalizes an external app into both provisioning doors', () => {
+    const source = template({
+      app: {
+        kind: 'url',
+        appId: 'crm',
+        url: 'https://crm.synap.live',
+        title: 'CRM',
+      },
+      layout: { pinnedApps: ['data'] },
+    });
+
+    const expected = {
+      kind: 'app',
+      appId: 'crm',
+      rendererType: 'external',
+      url: 'https://crm.synap.live',
+      title: 'CRM',
+    };
+
+    expect(toWorkspaceDefinition(source).definition.layoutConfig).toMatchObject(
+      {
+        pinnedApps: ['data'],
+        primarySurface: expected,
+      }
+    );
+    expect(toPackageDefinition(source).layoutConfig).toMatchObject({
+      pinnedApps: ['data'],
+      primarySurface: expected,
+    });
+  });
+
+  it('ships the generated CRM template as a hosted primary surface', () => {
+    expect(
+      toWorkspaceDefinition('crm').definition.layoutConfig?.primarySurface
+    ).toEqual({
+      kind: 'app',
+      appId: 'crm',
+      rendererType: 'external',
+      url: 'https://crm.synap.live',
+      title: 'CRM',
+    });
+  });
+
+  it('keeps legacy defaultApp as a native compatibility input', () => {
+    expect(
+      normalizeTemplateLayout({ defaultApp: 'dashboard' }, undefined)
+    ).toMatchObject({
+      defaultApp: 'dashboard',
+      primarySurface: {
+        kind: 'app',
+        appId: 'dashboard',
+        rendererType: 'native',
+      },
+    });
+  });
+
+  it('keeps an authored view name unresolved through both provisioning doors', () => {
+    const source = template({
+      views: [
+        {
+          name: 'Pipeline',
+          slug: 'pipeline',
+          type: 'kanban',
+          scopeProfileSlug: 'thing',
+        },
+      ],
+      layout: {
+        primarySurface: {
+          kind: 'view',
+          viewName: 'Pipeline',
+          viewSlug: 'pipeline',
+        },
+      },
+    });
+
+    expect(toWorkspaceDefinition(source).definition.layoutConfig).toMatchObject(
+      {
+        primarySurface: {
+          kind: 'view',
+          viewName: 'Pipeline',
+          viewSlug: 'pipeline',
+        },
+      }
+    );
+    expect(toPackageDefinition(source).layoutConfig).toMatchObject({
+      primarySurface: {
+        kind: 'view',
+        viewName: 'Pipeline',
+        viewSlug: 'pipeline',
+      },
+    });
+    expect(validateTemplate(source).ok).toBe(true);
+  });
+
+  it('rejects an unknown authored primary view before provisioning', () => {
+    const source = template({
+      views: [{ name: 'Pipeline', type: 'kanban' }],
+      layout: {
+        primarySurface: { kind: 'view', viewName: 'Missing' },
+      },
+    });
+
+    expect(validateTemplate(source).errors).toContainEqual(
+      expect.objectContaining({ rule: 'primary-view-reference-unknown' })
+    );
+  });
+
+  it('does not activate historical entity-detail placeholders without identity', () => {
+    expect(
+      normalizeTemplateLayout(
+        { defaultApp: null },
+        { kind: 'stored', cellKey: 'entity-detail' }
+      )
+    ).toMatchObject({
+      defaultApp: null,
+      primarySurface: null,
+    });
+  });
+
+  it('rejects two competing authoring sources', () => {
+    const source = template({
+      app: { kind: 'native', appId: 'dashboard' },
+      layout: {
+        primarySurface: {
+          kind: 'app',
+          appId: 'data',
+          rendererType: 'native',
+        },
+      },
+    });
+
+    expect(validateTemplate(source).errors).toContainEqual(
+      expect.objectContaining({ rule: 'primary-surface-authoring-conflict' })
+    );
+    expect(() => toWorkspaceDefinition(source)).toThrow(
+      /both top-level app and layout\.primarySurface/
+    );
+  });
+
+  it('rejects a hosted app that cannot be authorized by application id', () => {
+    const source = template({
+      app: { kind: 'url', url: 'https://crm.synap.live' },
+      layout: {},
+    });
+
+    expect(validateTemplate(source).errors).toContainEqual(
+      expect.objectContaining({ rule: 'app-url-identity-required' })
+    );
+    expect(() => toWorkspaceDefinition(source)).toThrow(
+      /requires both appId and url/
+    );
+  });
+});

package/src/define.ts

@@ -10,8 +10,12 @@
  * shape never drifts per call-site.
  */
 
-import type { TemplateAutomation, TemplateBentoBlock, WorkspaceYaml } from "./types.js";
-import { getWorkspaceTemplate } from "./templates.js";
+import type {
+  TemplateAppRef, TemplateAutomation, TemplateBentoBlock,
+  TemplateLayoutConfig,
+  WorkspacePrimarySurface,
+  WorkspaceYaml, } from './types.js';
+import { getWorkspaceTemplate } from './templates.js';
 
 /**
  * A `TemplateAutomation` as the apply door expects it: `flowDefinition`, not
@@ -25,12 +29,12 @@ export interface PackageAutomationWire {
   description?: string;
   triggerType: TemplateAutomation['triggerType'];
   triggerConfig?: Record<string, unknown>;
-  flowDefinition?: { nodes: unknown[]; edges: unknown[]; precondition?: string };
+  flowDefinition?: { nodes: unknown[]; edges: unknown[]; precondition?: string; };
   status?: TemplateAutomation['status'];
 }
 
 function toAutomationWire(
-  automations: TemplateAutomation[] | undefined,
+  automations: TemplateAutomation[] | undefined
 ): PackageAutomationWire[] | undefined {
   return automations?.map((a) => ({
     key: a.key,
@@ -63,6 +67,122 @@ export interface SplitBentoBlocks {
   bentoViewBlocks: BentoViewBlockWire[];
 }
 
+const hasOwn = <K extends PropertyKey>(
+  value: object,
+  key: K
+): value is Record<K, unknown> =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
+/**
+ * Convert the legacy top-level `app:` authoring shorthand into the persisted
+ * workspace surface contract. The conversion is deliberately conservative:
+ * an external app without an application id cannot pass the host's
+ * application/origin authorization, and the historical `entity-detail`
+ * placeholders have no entity identity to render.
+ */
+function appRefToPrimarySurface(
+  app: TemplateAppRef | undefined
+): WorkspacePrimarySurface | undefined {
+  if (!app) return undefined;
+
+  if (app.kind === 'native') {
+    if (!app.appId) {
+      throw new Error('Workspace template native app is missing appId');
+    }
+    return {
+      kind: 'app',
+      appId: app.appId,
+      rendererType: 'native',
+      ...(app.title ? { title: app.title } : {}),
+      ...(app.props ? { props: app.props } : {}),
+    };
+  }
+
+  if (app.kind === 'url') {
+    if (!app.appId || !app.url) {
+      throw new Error(
+        'Workspace template URL app requires both appId and url'
+      );
+    }
+    return {
+      kind: 'app',
+      appId: app.appId,
+      rendererType: 'external',
+      url: app.url,
+      ...(app.title ? { title: app.title } : {}),
+      ...(app.props ? { props: app.props } : {}),
+    };
+  }
+
+  if (app.kind === 'stored') {
+    if (!app.cellKey) {
+      throw new Error('Workspace template stored app is missing cellKey');
+    }
+    // Twenty-two historical templates carry this inert placeholder without an
+    // entity id. Activating it would open an unusable detail cell on entry.
+    if (app.cellKey === 'entity-detail' && !app.props?.entityId) {
+      return undefined;
+    }
+    return {
+      kind: 'cell',
+      cellKey: app.cellKey,
+      ...(app.title ? { title: app.title } : {}),
+      ...(app.props ? { props: app.props } : {}),
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Produce the canonical persisted layout. A template may author either the
+ * top-level `app:` shorthand or an explicit `layout.primarySurface`, never both.
+ * Legacy `defaultApp` is the final compatibility fallback. Keeping the property
+ * absent preserves a live workspace value during reconciliation; an authored
+ * null is retained as an explicit clear.
+ */
+export function normalizeTemplateLayout(
+  layout: TemplateLayoutConfig | undefined,
+  app: TemplateAppRef | undefined
+): TemplateLayoutConfig | undefined {
+  if (app && layout && hasOwn(layout, 'primarySurface')) {
+    throw new Error(
+      'Workspace template declares both top-level app and layout.primarySurface; choose one authoring source'
+    );
+  }
+
+  const primarySurface = (() => {
+    if (layout && hasOwn(layout, 'primarySurface')) {
+      return layout.primarySurface;
+    }
+
+    const fromApp = appRefToPrimarySurface(app);
+    if (fromApp) return fromApp;
+
+    if (layout && hasOwn(layout, 'defaultApp')) {
+      return layout.defaultApp
+        ? {
+            kind: 'app' as const,
+            appId: layout.defaultApp,
+            rendererType: 'native' as const,
+          }
+        : null;
+    }
+
+    return undefined;
+  })();
+
+  if (!layout && primarySurface === undefined) return undefined;
+
+  return {
+    ...layout,
+    ...(primarySurface !== undefined ||
+    (layout && hasOwn(layout, 'primarySurface'))
+      ? { primarySurface }
+      : {}),
+  };
+}
+
 /**
  * Split the authored `bento.blocks` DISCRIMINATED UNION into the TWO wire
  * fields the pod expects. This is the whole point: `TemplateBentoBlock` is one
@@ -229,12 +349,14 @@ export interface ToDefinitionResult {
  * or selected value string. Keep this conversion at the shared template seam
  * so browser creation and package application cannot silently disagree.
  */
-function toWorkspacePlaybooks(playbooks: WorkspaceYaml["playbooks"]): Array<Record<string, unknown>> | undefined {
+function toWorkspacePlaybooks(
+  playbooks: WorkspaceYaml['playbooks']
+): Array<Record<string, unknown>> | undefined {
   return playbooks?.map((playbook) => ({
     ...playbook,
     params: playbook.params?.map((param) => ({
       name: param.name,
-      type: param.type === "number" || param.type === "boolean" ? param.type : "string",
+      type: param.type === 'number' || param.type === 'boolean' ? param.type : 'string',
       ...(param.defaultValue !== undefined ? { default: param.defaultValue } : {}),
       ...(param.label
         ? { description: param.label }
@@ -249,7 +371,7 @@ function toWorkspacePlaybooks(playbooks: WorkspaceYaml["playbooks"]): Array<Reco
  */
 export function toWorkspaceDefinition(
   slugOrYaml: string | WorkspaceYaml,
-  nameOverride?: string,
+  nameOverride?: string
 ): ToDefinitionResult {
   const tpl: WorkspaceYaml | undefined =
     typeof slugOrYaml === 'string' ? getWorkspaceTemplate(slugOrYaml) : slugOrYaml;
@@ -276,7 +398,7 @@ export function toWorkspaceDefinition(
     seedEntities: tpl.seedEntities ?? [],
     suggestedRelations: tpl.suggestedRelations,
     displayTemplates: tpl.displayTemplates,
-    layoutConfig: tpl.layout,
+    layoutConfig: normalizeTemplateLayout(tpl.layout, tpl.app),
     bentoViewName: tpl.bento?.viewName,
     bentoLayout: bento.bentoLayout,
     bentoViewBlocks: bento.bentoViewBlocks,
@@ -315,7 +437,7 @@ export function toWorkspaceDefinition(
     dependencies: tpl.dependencies,
   };
 
-  return { definition, proposalId, workspaceName: name, templateId: tpl.meta.slug };
+  return { definition, proposalId, workspaceName: name, templateId: tpl.meta.slug, };
 }
 
 // ─── Exhaustiveness ledger: toWorkspaceDefinition ────────────────────────────
@@ -366,14 +488,11 @@ type WorkspaceDefinitionForwarded =
  * else is a real gap and should say so.
  */
 type WorkspaceDefinitionDropped =
-  // UI-only: `workspaces.createFromDefinition` has no `app` field. Consumers
-  // read `template.app` straight off the YAML to pick the first screen, so this
-  // never belonged on the wire.
+  // Normalized into `layoutConfig.primarySurface`.
   | 'app'
   // The door DOES accept `extends`, but no template declares it today (0/21).
   // Forwarding is a no-op until one does — wire it then.
-  | 'extends'
-  ;
+  | 'extends';
 
 type UnclassifiedWorkspaceDefinitionKey = Exclude<
   keyof WorkspaceYaml,
@@ -383,7 +502,9 @@ type UnclassifiedWorkspaceDefinitionKey = Exclude<
 // If this errors, a new `WorkspaceYaml` field is unclassified. Forward it in
 // `toWorkspaceDefinition` and add it to `WorkspaceDefinitionForwarded`, or add
 // it to `WorkspaceDefinitionDropped` with a one-line WHY.
-const _workspaceDefinitionLedger: [UnclassifiedWorkspaceDefinitionKey] extends [never]
+const _workspaceDefinitionLedger: [UnclassifiedWorkspaceDefinitionKey] extends [
+  never,
+]
   ? true
   : [
       'UNCLASSIFIED YAML FIELD — forward it or add it to WorkspaceDefinitionDropped:',
@@ -462,7 +583,7 @@ export interface PackageDefinitionOutput {
  * package instead of disk-stored JSON.
  */
 export function toPackageDefinition(
-  slugOrYaml: string | WorkspaceYaml,
+  slugOrYaml: string | WorkspaceYaml
 ): PackageDefinitionOutput {
   const tpl: WorkspaceYaml | undefined =
     typeof slugOrYaml === 'string' ? getWorkspaceTemplate(slugOrYaml) : slugOrYaml;
@@ -502,7 +623,7 @@ export function toPackageDefinition(
     bentoViewBlocks: bento.bentoViewBlocks,
     bentoViewName: tpl.bento?.viewName,
     profileEntityBentoTemplates: tpl.profileEntityBentoTemplates,
-    layoutConfig: tpl.layout,
+    layoutConfig: normalizeTemplateLayout(tpl.layout, tpl.app),
     capabilities: tpl.integrations,
     playbooks: tpl.playbooks,
     automations: toAutomationWire(tpl.automations),
@@ -541,7 +662,7 @@ type PackageDefinitionForwarded =
 
 /** Keys deliberately NOT forwarded by `toPackageDefinition`. */
 type PackageDefinitionDropped =
-  // UI-only, same as the definition door: `PackageDefinition` has no `app`.
+  // Normalized into `layoutConfig.primarySurface`.
   | 'app'
   // REAL GAP: backend `PackageDefinition` DOES declare `extends`
   // (package-definition.ts:262), but `PackageDefinitionOutput` omits it. No
@@ -557,7 +678,9 @@ type UnclassifiedPackageDefinitionKey = Exclude<
 // If this errors, a new `WorkspaceYaml` field is unclassified. Forward it in
 // `toPackageDefinition` and add it to `PackageDefinitionForwarded`, or add it
 // to `PackageDefinitionDropped` with a one-line WHY.
-const _packageDefinitionLedger: [UnclassifiedPackageDefinitionKey] extends [never]
+const _packageDefinitionLedger: [UnclassifiedPackageDefinitionKey] extends [
+  never,
+]
   ? true
   : [
       'UNCLASSIFIED YAML FIELD — forward it or add it to PackageDefinitionDropped:',