@synap-core/workspace-templates 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,24 +1,498 @@
 /**
- * @synap-core/workspace-templates
+ * @synap-core/workspace-templates — Types
  *
- * Canonical workspace template definitions.
- * ==========================================
- *
- * Usage (browser / backend / CLI):
+ * Canonical shape of a workspace template.
+ * YAML source files validate against these types.
+ * Every consumer (browser, backend, CLI, marketplace) imports from here.
+ */
+type TemplateAppKind = 'native' | 'stored' | 'url';
+interface TemplateAppRef {
+    kind: TemplateAppKind;
+    /** For kind='native': the appId registered in the browser manifest */
+    appId?: string;
+    /** For kind='native': how the platform renders the app */
+    rendererType?: 'native' | 'external' | 'iframe-srcdoc';
+    /** For kind='stored': the cell key registered in the cell registry */
+    cellKey?: string;
+    /** For kind='stored': default props passed to the cell */
+    props?: Record<string, unknown>;
+    /** For kind='url': external URL to open */
+    url?: string;
+    /** Human label */
+    title?: string;
+}
+interface TemplateProperty {
+    slug: string;
+    label: string;
+    valueType: string;
+    inputType?: string;
+    placeholder?: string;
+    enumValues?: string[];
+    constraints?: Record<string, unknown>;
+    targetProfileSlug?: string;
+}
+interface TemplateProfile {
+    slug: string;
+    displayName: string;
+    icon?: string;
+    color?: string;
+    description?: string;
+    /** Visibility scope. Omit or "WORKSPACE" for workspace-scoped. */
+    scope?: string;
+    /** Semantic slug for system profiles. */
+    semanticSlug?: string;
+    /** Kind vs role profile. Omit for default ('kind'). */
+    profileKind?: "kind" | "role";
+    /** For profileKind='role': which base-kind profile slugs this role can attach to. */
+    applicableKinds?: string[];
+    properties: TemplateProperty[];
+}
+interface TemplateView {
+    name: string;
+    slug?: string;
+    type: string;
+    scopeProfileSlug?: string;
+    scopeProfileSlugs?: string[];
+    config?: Record<string, unknown>;
+    /** If true, this view auto-selected as the default view for this workspace */
+    defaultView?: boolean;
+    description?: string;
+    groupBy?: string;
+}
+interface TemplateEntityLink {
+    sourceProfileSlug: string;
+    targetProfileSlug: string;
+    type: string;
+    label?: string;
+}
+interface TemplateSeedEntity {
+    profileSlug: string;
+    title: string;
+    properties?: Record<string, unknown>;
+    content?: string;
+}
+/**
+ * Relations between seed entities, created on provisioning. `sourceRef`/
+ * `targetRef` reference seed-entity titles (or refs) defined in `seedEntities`.
+ * Mirrors `suggestedRelations` in synap-backend `create-workspace-from-definition.ts`.
+ */
+interface TemplateSuggestedRelation {
+    sourceRef: string;
+    targetRef: string;
+    type: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Entity-card display templates. Mirrors `displayTemplates` in synap-backend
+ * `create-workspace-from-definition.ts`.
+ */
+interface TemplateDisplayTemplate {
+    name: string;
+    description?: string;
+    entityType?: string;
+    targetType?: string;
+    isDefault?: boolean;
+    config: Record<string, unknown>;
+}
+interface TemplateSidebarSurface {
+    kind: 'cell' | 'view' | 'entity' | 'document' | 'channel' | 'app' | 'url';
+    cellKey?: string;
+    viewId?: string;
+    viewName?: string;
+    appId?: string;
+    url?: string;
+    rendererType?: 'native' | 'external' | 'iframe-srcdoc';
+    placement?: 'main' | 'side' | 'floating' | 'modal' | 'popover' | 'embed';
+    displayMode?: 'compact' | 'medium' | 'full';
+    props?: Record<string, unknown>;
+    title?: string;
+    meta?: Record<string, unknown>;
+}
+interface TemplateSidebarItem {
+    kind: 'app' | 'view' | 'profile' | 'external' | 'cell';
+    appId?: string;
+    viewName?: string;
+    viewId?: string;
+    profileSlug?: string;
+    url?: string;
+    cellKey?: string;
+    cellProps?: Record<string, unknown>;
+    /** When present, bypasses kind-based dispatch — full surface control */
+    surface?: TemplateSidebarSurface;
+    label?: string;
+    icon?: string;
+    section?: string;
+    matchUrls?: string[];
+}
+interface TemplateLayoutConfig {
+    pinnedApps?: string[];
+    defaultView?: string;
+    /** The first-screen app — auto-opened on workspace switch */
+    defaultApp?: string | null;
+    theme?: string;
+    sidebarItems?: TemplateSidebarItem[];
+}
+interface TemplateBentoBlock {
+    kind: 'view' | 'widget';
+    viewName?: string;
+    widgetType?: string;
+    pos: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    config?: Record<string, unknown>;
+    overrides?: Record<string, unknown>;
+}
+interface TemplateProfileEntityBentoTemplates {
+    [profileSlug: string]: {
+        blocks: Array<Record<string, unknown>>;
+    };
+}
+interface TemplateAutomation {
+    name: string;
+    description?: string;
+    trigger: string;
+    action: string;
+    config?: Record<string, unknown>;
+}
+/** Mirrors `WorkspaceSourceRole` in synap-backend `schema/workspaces.ts`. */
+type TemplateSourceRole = 'provider' | 'consumer' | 'provider-consumer';
+/** Mirrors `WorkspaceDefaultSource` in synap-backend `schema/workspaces.ts`. */
+interface TemplateDefaultSource {
+    /** The workspace id that supplies this capability domain. */
+    workspaceId: string;
+    /** The capability domain this source satisfies (e.g. "brand", "strategy"). */
+    capability?: string;
+    /** Optional profile slug the source resolves to. */
+    profileSlug?: string;
+    /** Human label for the source. */
+    label?: string;
+}
+interface TemplateOnboardingCollectTarget {
+    /** Profile slug to populate (e.g. "audience", "competitor"). */
+    profileSlug: string;
+    /** Human description of what to capture for this target. */
+    what: string;
+    /** Roughly how many to expect — guides interview depth. */
+    cardinality?: 'one' | 'few' | 'several';
+    /** Key fields the agent should make sure to fill. */
+    keyFields?: string[];
+}
+interface TemplateOnboardingExpertise {
+    /**
+     * Concrete starting points the agent PROPOSES instead of asking blank —
+     * "most X do Y, want that as a starting point?". Grounds the agent's
+     * proposals in real domain knowledge (never fabricates strategy — for
+     * mission/positioning these FRAME, they don't invent the answer).
+     */
+    starters?: string[];
+    /**
+     * Blind spots founders in this domain commonly miss. The agent proactively
+     * surfaces these if the founder hasn't — catching what they don't say.
+     */
+    blindSpots?: string[];
+    /** What a GREAT result looks like here — the bar the agent pushes toward. */
+    bar?: string;
+}
+interface TemplateOnboarding {
+    /** The outcome this onboarding achieves, in one sentence. */
+    goal: string;
+    /** Domain framing/voice the agent adopts for THIS workspace (the persona). */
+    framing: string;
+    /**
+     * Authored domain expertise the agent leads with (optional). Turns the
+     * interview from "extract what the founder knows" into "resolve what they
+     * lack". See the `onboard` skill's "Lead with your expertise" step.
+     */
+    expertise?: TemplateOnboardingExpertise;
+    /** What structured data to collect (entities to create + their key fields). */
+    collect: TemplateOnboardingCollectTarget[];
+    /** A few opening questions — the agent adapts from here, never rigid. */
+    openingQuestions?: string[];
+    /** "Done" signal the agent self-evaluates against. */
+    doneWhen?: string;
+}
+interface TemplatePlaybookParam {
+    name: string;
+    type: 'text' | 'number' | 'entity' | 'choice' | 'boolean';
+    label?: string;
+    required?: boolean;
+    defaultValue?: unknown;
+}
+interface TemplatePlaybook {
+    name: string;
+    description?: string;
+    goalTemplate: string;
+    params?: TemplatePlaybookParam[];
+    executor?: 'is-agent' | 'external-agent' | 'hybrid';
+    inputStrategy?: 'none' | 'static' | 'rotating' | 'query';
+    channelSpec?: {
+        type: 'GROUP' | 'AGENT_COLLAB' | 'THREAD';
+        members?: string[];
+        aiReactionMode?: 'on_mention' | 'always' | 'never';
+    };
+    schedule?: {
+        cron: string;
+    } | null;
+    /** tool/skill keys this playbook grants. */
+    grants?: string[];
+    status?: 'draft' | 'active' | 'paused';
+}
+interface TemplateIntegration {
+    /** Capability template key to install (matches a capability template). */
+    templateKey: string;
+    /** Override default params with {{var}} interpolation. */
+    params?: Record<string, string>;
+    /** "apply" (create+update) or "install" (create only). */
+    mode?: 'apply' | 'install';
+}
+interface TemplateExtendsRef {
+    source: string;
+    import?: {
+        profiles?: string[];
+        views?: string[];
+    };
+}
+/**
+ * A dependency this template declares on ANOTHER template/package. The install
+ * resolver (backend `POST /api/hub/packages/apply`) reads these to build the
+ * pod's template graph: every dependency is ensured present before this
+ * template is applied — missing ones install first (topologically) — and a
+ * `compose` dependency LAYERS this template's schema additively onto the
+ * dependency's workspace instead of creating a second workspace.
  *
- *   import { getWorkspaceTemplate, listPublicTemplates } from '@synap-core/workspace-templates';
+ * This is the general composition primitive: a BASE template carries the
+ * agnostic data model; an OVERLAY template `compose`s onto it and adds the
+ * use-case-specific data (e.g. `blockchain-ecosystem` → `ecosystem`,
+ * `grants` → `operations`). Distinct from `extends` (which imports from a live
+ * workspace, tRPC-only) — `dependencies` is template→template.
+ */
+interface TemplateDependency {
+    /** Slug of the template/package this one depends on. */
+    slug: string;
+    /**
+     * What the dependency is. Default `'workspace'`. Only `'workspace'`
+     * dependencies can be `compose`d; `'capability'`/`'automation'` are always
+     * `require`d present without merging.
+     */
+    kind?: 'workspace' | 'capability' | 'automation';
+    /**
+     * How this template relates to the dependency:
+     * - `'compose'`: this template is an OVERLAY on the dependency's workspace.
+     *   The base is installed first if absent, then this template's profiles /
+     *   roles / relations / views are applied ADDITIVELY onto the base workspace
+     *   — no separate workspace is created for this template.
+     * - `'require'` (default): the dependency must be present on the pod as its
+     *   own artifact, but this template does not merge into it.
+     */
+    relation?: 'compose' | 'require';
+    /**
+     * Short human reason shown in the install-time "this also installs…" prompt.
+     */
+    reason?: string;
+}
+interface TemplateMeta {
+    slug: string;
+    name: string;
+    description: string;
+    icon: string;
+    color: string;
+    tags?: string[];
+    isPublic?: boolean;
+}
+interface WorkspaceYaml {
+    /** Template metadata — not sent to backend, used for listing/UI */
+    meta: TemplateMeta;
+    /** The workspace definition sent to createFromDefinition */
+    workspace: {
+        name: string;
+        description: string;
+        proposalId?: string;
+        subtype?: string;
+        /**
+         * Workspace classifier — consumed by createFromDefinition (settings.workspaceType,
+         * creator-role + agent-workspace behavior). Mirrors the backend union.
+         */
+        workspaceType?: 'personal' | 'agent' | 'project' | 'operational';
+        visibility?: string;
+        /** Capabilities this workspace provides (e.g. "brand.library", "content.pipeline") */
+        capabilities?: string[];
+        /**
+         * Cross-workspace dependency roles.
+         * E.g. { brand: "consumer", content: "provider" }
+         * "consumer" = this workspace reads from another workspace of that capability
+         * "provider" = this workspace provides that capability to others
+         */
+        sourceRoles?: Record<string, TemplateSourceRole>;
+        /**
+         * Pins which workspace supplies each capability domain for this workspace.
+         * E.g. { brand: { workspaceId: "..." } } — read by the IS source resolver
+         * (resolveBrandWorkspaceId / resolveFoundationWorkspaceId) before falling
+         * back to provider role. Usually set at runtime, not in a template, but
+         * carried here so it round-trips through the canonical seam.
+         */
+        defaultSources?: Record<string, TemplateDefaultSource>;
+    };
+    /** Entity profiles — the data schema */
+    profiles: TemplateProfile[];
+    /** Curated views — only the ones that add value */
+    views?: TemplateView[];
+    /** Schema-level links between entity types */
+    entityLinks?: TemplateEntityLink[];
+    /** Initial data to seed on workspace creation */
+    seedEntities?: TemplateSeedEntity[];
+    /** Relations between seed entities, created on provisioning */
+    suggestedRelations?: TemplateSuggestedRelation[];
+    /** Entity-card display templates */
+    displayTemplates?: TemplateDisplayTemplate[];
+    /** App reference — what opens as first screen */
+    app?: TemplateAppRef;
+    /** Browser sidebar + layout config */
+    layout?: TemplateLayoutConfig;
+    /** Bento dashboard */
+    bento?: {
+        viewName?: string;
+        blocks?: TemplateBentoBlock[];
+    };
+    /** Per-profile entity bento layouts */
+    profileEntityBentoTemplates?: TemplateProfileEntityBentoTemplates;
+    /** Automations to install on workspace creation */
+    automations?: TemplateAutomation[];
+    /** Playbooks (session templates) seeded with the workspace */
+    playbooks?: TemplatePlaybook[];
+    /** Capability templates (tools/connectors) to install on provisioning */
+    integrations?: TemplateIntegration[];
+    /**
+     * Per-workspace onboarding context. Written to workspace.settings.onboarding
+     * and read by the shared `onboard` skill to run a domain-specific adaptive
+     * interview — no per-domain skill file needed.
+     */
+    onboarding?: TemplateOnboarding;
+    /** Inherit profiles/views from other workspaces */
+    extends?: TemplateExtendsRef[];
+    /**
+     * Template-composition dependencies — other templates this one needs. The
+     * install resolver installs missing dependencies first and, for a `compose`
+     * dependency, layers this template additively onto the dependency's
+     * workspace. See {@link TemplateDependency}.
+     */
+    dependencies?: TemplateDependency[];
+}
+
+declare const WORKSPACE_TEMPLATES: Record<string, WorkspaceYaml>;
+type WorkspaceTemplateSlug = keyof typeof WORKSPACE_TEMPLATES;
+declare function getWorkspaceTemplate(slug: string): WorkspaceYaml | undefined;
+declare function listWorkspaceTemplates(): WorkspaceYaml[];
+declare function listPublicTemplates(): WorkspaceYaml[];
+
+/**
+ * @synap-core/workspace-templates — Definition adapter
  *
- *   const template = getWorkspaceTemplate('brand-library');
- *   // template.workspace.name === 'Brand Library'
- *   // template.app.kind === 'native'
- *   // template.layout.defaultApp === 'brandLibrary'
+ * Converts a YAML template (WorkspaceYaml) into the flat payload shape that
+ * the backend `workspaces.createFromDefinition` mutation + Hub REST
+ * `/workspaces/from-definition` endpoint expect.
  *
- * YAML source files live in src/*.yaml — AI-friendly, commentable, mergeable.
- * Run `pnpm build` to regenerate src/templates.ts from YAML.
- */
-export type { WorkspaceYaml, TemplateMeta, TemplateAppRef, TemplateAppKind, TemplateProfile, TemplateProperty, TemplateView, TemplateSidebarItem, TemplateSidebarSurface, TemplateLayoutConfig, TemplateBentoBlock, TemplateEntityLink, TemplateSeedEntity, TemplateSuggestedRelation, TemplateDisplayTemplate, TemplateIntegration, TemplateAutomation, TemplateExtendsRef, TemplateProfileEntityBentoTemplates, TemplateDefaultSource, TemplateSourceRole, TemplateOnboarding, TemplateOnboardingCollectTarget, TemplatePlaybook, TemplatePlaybookParam, } from './types.js';
-export { WORKSPACE_TEMPLATES, getWorkspaceTemplate, listWorkspaceTemplates, listPublicTemplates, } from './templates.js';
-export type { WorkspaceTemplateSlug } from './templates.js';
-export { toWorkspaceDefinition, toPackageDefinition } from './define.js';
-export type { WorkspaceDefinitionInput, ToDefinitionResult, PackageDefinitionOutput, } from './define.js';
-//# sourceMappingURL=index.d.ts.map
+ * This is the single canonical seam: every consumer (browser app, onboarding,
+ * CLI, marketplace) provisions a workspace through this function so the wire
+ * shape never drifts per call-site.
+ */
+
+/** The flat definition object accepted by createFromDefinition. */
+interface WorkspaceDefinitionInput {
+    workspaceName: string;
+    description: string;
+    proposalId?: string;
+    profiles: WorkspaceYaml['profiles'];
+    views: NonNullable<WorkspaceYaml['views']>;
+    entityLinks: NonNullable<WorkspaceYaml['entityLinks']>;
+    seedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+    suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+    displayTemplates?: WorkspaceYaml['displayTemplates'];
+    layoutConfig: WorkspaceYaml['layout'] | undefined;
+    bentoViewName?: string;
+    bentoViewBlocks?: NonNullable<WorkspaceYaml['bento']>['blocks'];
+    profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
+    workspaceSubtype?: string;
+    workspaceType?: NonNullable<WorkspaceYaml['workspace']>['workspaceType'];
+    workspaceVisibility?: string;
+    workspaceCapabilities?: string[];
+    sourceRoles?: NonNullable<WorkspaceYaml['workspace']>['sourceRoles'];
+    defaultSources?: NonNullable<WorkspaceYaml['workspace']>['defaultSources'];
+    /** Per-workspace onboarding context — written to settings.onboarding. */
+    onboarding?: WorkspaceYaml['onboarding'];
+    /**
+     * Template-composition dependencies. MUST be forwarded: the backend resolves
+     * these BEFORE materializing this workspace (`workspaces.createFromDefinition`
+     * → `materializeWorkspaceCore` Step 0 → `resolvePackageDependencies`), which
+     * is what installs a `require`d base FIRST and makes shared-profile base
+     * seeding deterministic. Dropping this field silently de-orders provisioning
+     * on the tRPC/UI door — see the note in `toWorkspaceDefinition`.
+     */
+    dependencies?: WorkspaceYaml['dependencies'];
+}
+interface ToDefinitionResult {
+    definition: WorkspaceDefinitionInput;
+    /** Stable idempotency key — the template's proposalId or slug. */
+    proposalId: string;
+    /** Display name for the new workspace. */
+    workspaceName: string;
+    /** Template id for telemetry / dedup. */
+    templateId: string;
+}
+/**
+ * Resolve a template (by slug or YAML object) into the createFromDefinition
+ * payload. Pass `nameOverride` to rename the workspace at creation time.
+ */
+declare function toWorkspaceDefinition(slugOrYaml: string | WorkspaceYaml, nameOverride?: string): ToDefinitionResult;
+/**
+ * The unified `PackageDefinition` shape consumed by `POST /api/hub/packages/apply`
+ * (CLI `synap launch`) and the CP package registry seeder. It composes the
+ * workspace definition with the capability/playbook/onboarding layers. Mirrors
+ * `PackageDefinition` in synap-backend `package-definition.ts`. Typed loosely on
+ * the layered fields to avoid a backend import; the wire validation lives in the
+ * apply endpoint.
+ */
+interface PackageDefinitionOutput {
+    _meta: {
+        slug: string;
+        icon?: string;
+        color?: string;
+        tags?: string[];
+        isPublic?: boolean;
+        requiredTier?: string | null;
+    };
+    workspaceName: string;
+    description: string;
+    workspaceType?: WorkspaceYaml['workspace']['workspaceType'];
+    workspaceSubtype?: string;
+    workspaceVisibility?: string;
+    workspaceCapabilities?: string[];
+    sourceRoles?: WorkspaceYaml['workspace']['sourceRoles'];
+    defaultSources?: WorkspaceYaml['workspace']['defaultSources'];
+    profiles: WorkspaceYaml['profiles'];
+    views: NonNullable<WorkspaceYaml['views']>;
+    suggestedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+    suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+    displayTemplates?: WorkspaceYaml['displayTemplates'];
+    entityLinks?: WorkspaceYaml['entityLinks'];
+    bentoLayout?: NonNullable<WorkspaceYaml['bento']>['blocks'];
+    bentoViewName?: string;
+    profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
+    layoutConfig?: WorkspaceYaml['layout'];
+    capabilities?: WorkspaceYaml['integrations'];
+    playbooks?: WorkspaceYaml['playbooks'];
+    onboarding?: WorkspaceYaml['onboarding'];
+    /** Template-composition dependencies — resolved by the apply endpoint. */
+    dependencies?: WorkspaceYaml['dependencies'];
+}
+/**
+ * Resolve a template (by slug or YAML object) into the full `PackageDefinition`
+ * accepted by `POST /api/hub/packages/apply` and the CP registry seeder. This is
+ * the single seam the CLI and control-plane use so they read from the canonical
+ * package instead of disk-stored JSON.
+ */
+declare function toPackageDefinition(slugOrYaml: string | WorkspaceYaml): PackageDefinitionOutput;
+
+export { type PackageDefinitionOutput, type TemplateAppKind, type TemplateAppRef, type TemplateAutomation, type TemplateBentoBlock, type TemplateDefaultSource, type TemplateDependency, type TemplateDisplayTemplate, type TemplateEntityLink, type TemplateExtendsRef, type TemplateIntegration, type TemplateLayoutConfig, type TemplateMeta, type TemplateOnboarding, type TemplateOnboardingCollectTarget, type TemplatePlaybook, type TemplatePlaybookParam, type TemplateProfile, type TemplateProfileEntityBentoTemplates, type TemplateProperty, type TemplateSeedEntity, type TemplateSidebarItem, type TemplateSidebarSurface, type TemplateSourceRole, type TemplateSuggestedRelation, type TemplateView, type ToDefinitionResult, WORKSPACE_TEMPLATES, type WorkspaceDefinitionInput, type WorkspaceTemplateSlug, type WorkspaceYaml, getWorkspaceTemplate, listPublicTemplates, listWorkspaceTemplates, toPackageDefinition, toWorkspaceDefinition };