@synap-core/workspace-templates 0.2.1

package/src/types.ts

@@ -0,0 +1,426 @@
+/**
+ * @synap-core/workspace-templates — Types
+ *
+ * Canonical shape of a workspace template.
+ * YAML source files validate against these types.
+ * Every consumer (browser, backend, CLI, marketplace) imports from here.
+ */
+
+// ============================================================================
+// App Reference — what opens as first screen when entering this workspace
+// ============================================================================
+
+export type TemplateAppKind = 'native' | 'stored' | 'url';
+
+export 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;
+}
+
+// ============================================================================
+// Property / Profile / View (mirrors WorkspaceProposal from onboarding)
+// ============================================================================
+
+export interface TemplateProperty {
+  slug: string;
+  label: string;
+  valueType: string;
+  inputType?: string;
+  placeholder?: string;
+  enumValues?: string[];
+  constraints?: Record<string, unknown>;
+  targetProfileSlug?: string;
+}
+
+export 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;
+  properties: TemplateProperty[];
+}
+
+export 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;
+}
+
+export interface TemplateEntityLink {
+  sourceProfileSlug: string;
+  targetProfileSlug: string;
+  type: string;
+  label?: string;
+}
+
+export 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`.
+ */
+export 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`.
+ */
+export interface TemplateDisplayTemplate {
+  name: string;
+  description?: string;
+  entityType?: string;
+  targetType?: string;
+  isDefault?: boolean;
+  config: Record<string, unknown>;
+}
+
+// ============================================================================
+// Sidebar / Layout
+// ============================================================================
+
+export 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>;
+}
+
+export 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[];
+}
+
+export interface TemplateLayoutConfig {
+  pinnedApps?: string[];
+  defaultView?: string;
+  /** The first-screen app — auto-opened on workspace switch */
+  defaultApp?: string | null;
+  theme?: string;
+  sidebarItems?: TemplateSidebarItem[];
+}
+
+// ============================================================================
+// Bento dashboard
+// ============================================================================
+
+export 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>;
+}
+
+export interface TemplateProfileEntityBentoTemplates {
+  [profileSlug: string]: {
+    blocks: Array<Record<string, unknown>>;
+  };
+}
+
+// ============================================================================
+// Automations
+// ============================================================================
+
+export interface TemplateAutomation {
+  name: string;
+  description?: string;
+  trigger: string;
+  action: string;
+  config?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Cross-workspace source pinning
+// ============================================================================
+
+/** Mirrors `WorkspaceSourceRole` in synap-backend `schema/workspaces.ts`. */
+export type TemplateSourceRole = 'provider' | 'consumer' | 'provider-consumer';
+
+/** Mirrors `WorkspaceDefaultSource` in synap-backend `schema/workspaces.ts`. */
+export 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;
+}
+
+// ============================================================================
+// Onboarding spec — the per-workspace dynamic onboarding CONTEXT
+//
+// Written to workspace.settings.onboarding. The SHARED `onboard` skill (the
+// reusable adaptive interview PROCESS) reads this to know WHAT a given
+// workspace needs — without a per-domain skill file. The domain knowledge
+// lives here as data, declared by each template. Mirrors `OnboardingSpec` in
+// synap-backend `package-definition.ts` so the wire shape never drifts.
+// ============================================================================
+
+export 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[];
+}
+
+export 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;
+  /** 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;
+}
+
+// ============================================================================
+// Playbooks — session templates seeded with the workspace
+//
+// Mirrors `PackagePlaybook` in synap-backend `package-definition.ts`. Seeded
+// via the packages/apply provisioning path (not createFromDefinition), so they
+// are carried on the template but not part of WorkspaceDefinitionInput.
+// ============================================================================
+
+export interface TemplatePlaybookParam {
+  name: string;
+  type: 'text' | 'number' | 'entity' | 'choice' | 'boolean';
+  label?: string;
+  required?: boolean;
+  defaultValue?: unknown;
+}
+
+export 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';
+}
+
+// ============================================================================
+// Integrations — capability templates (tools/connectors) to install
+//
+// Distinct from `workspace.capabilities` (the capability slugs a workspace
+// ADVERTISES). This is the list of capability TEMPLATES to INSTALL on
+// provisioning (e.g. "nango-google", "agency-skills"). Mirrors
+// `PackageCapability` in synap-backend `package-definition.ts`. Seeded via the
+// packages/apply path (not createFromDefinition), so carried on the template.
+// ============================================================================
+
+export 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';
+}
+
+// ============================================================================
+// Extends — inherit profiles/views from another workspace
+// ============================================================================
+
+export interface TemplateExtendsRef {
+  source: string;
+  import?: {
+    profiles?: string[];
+    views?: string[];
+  };
+}
+
+// ============================================================================
+// Top-level template definition (YAML shape)
+// ============================================================================
+
+export interface TemplateMeta {
+  slug: string;
+  name: string;
+  description: string;
+  icon: string;
+  color: string;
+  tags?: string[];
+  isPublic?: boolean;
+}
+
+export 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[];
+}
+
+// ============================================================================
+// Resolved template — meta + fully typed definition ready for provisioning
+// ============================================================================
+
+export interface ResolvedWorkspaceTemplate {
+  meta: TemplateMeta;
+  definition: WorkspaceYaml['workspace'] & {
+    profiles: TemplateProfile[];
+    views: TemplateView[];
+    entityLinks: TemplateEntityLink[];
+    seedEntities: TemplateSeedEntity[];
+    app: TemplateAppRef | null;
+    layoutConfig: TemplateLayoutConfig | null;
+    bentoViewName?: string;
+    bentoViewBlocks?: TemplateBentoBlock[];
+    profileEntityBentoTemplates?: TemplateProfileEntityBentoTemplates;
+    automations: TemplateAutomation[];
+    extends?: TemplateExtendsRef[];
+  };
+}