@synap-core/workspace-templates 0.9.2 → 0.9.4

package/dist/index.d.ts

@@ -5,22 +5,74 @@
  * YAML source files validate against these types.
  * Every consumer (browser, backend, CLI, marketplace) imports from here.
  */
-type TemplateAppKind = 'native' | 'stored' | 'url';
+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';
+    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>;
+    props?: Record<string, WorkspaceJsonValue>;
     /** For kind='url': external URL to open */
     url?: string;
     /** Human label */
     title?: string;
 }
+type WorkspaceJsonValue = string | number | boolean | null | WorkspaceJsonValue[] | {
+    [key: string]: WorkspaceJsonValue;
+};
+type WorkspacePrimarySurface = {
+    kind: "app";
+    appId: string;
+    rendererType: "native";
+    title?: string;
+    props?: Record<string, WorkspaceJsonValue>;
+} | {
+    kind: "app";
+    appId: string;
+    rendererType: "external";
+    url: string;
+    title?: string;
+    props?: Record<string, WorkspaceJsonValue>;
+} | {
+    kind: "cell";
+    cellKey: string;
+    title?: string;
+    props?: Record<string, WorkspaceJsonValue>;
+} | {
+    /**
+     * Ordinary website. Unlike an external `app`, this has no trusted app
+     * identity and is always opened through the Browser's unprivileged URL
+     * surface.
+     */
+    kind: "url";
+    url: string;
+    title?: string;
+} | {
+    kind: "view";
+    viewId: string;
+    title?: string;
+};
+/**
+ * Authoring-time view reference. View IDs do not exist until provisioning, so
+ * templates and packages address a view by its stable authored name and/or
+ * slug. The pod resolves this to `WorkspacePrimarySurface` before persistence.
+ */
+type WorkspacePrimarySurfaceViewReference = {
+    kind: "view";
+    viewName: string;
+    viewSlug?: string;
+    title?: string;
+} | {
+    kind: "view";
+    viewName?: string;
+    viewSlug: string;
+    title?: string;
+};
+type TemplatePrimarySurface = WorkspacePrimarySurface | WorkspacePrimarySurfaceViewReference;
 interface TemplateProperty {
     slug: string;
     label: string;
@@ -41,8 +93,7 @@ interface TemplateProfile {
      * Visibility of the profile DEFINITION — who can USE this vocabulary.
      * `system` = pod-wide; `shared` = ONE row reachable from other workspaces via
      * a `profile_workspace_access` grant; omit or `workspace` = this workspace
-     * only. Orthogonal to `entityScope` below — do not conflate the two axes.
-     */
+     * only. Orthogonal to `entityScope` below — do not conflate the two axes. */
     scope?: string;
     /**
      * Placement of the profile's ENTITY ROWS — where the data LANDS.
@@ -60,7 +111,7 @@ interface TemplateProfile {
      * `entity_scope` of an existing profile (a divergence is reported as an
      * advisory `scopeConflict` and the live row is left alone).
      */
-    entityScope?: 'pod' | 'workspace';
+    entityScope?: "pod" | "workspace";
     /** Semantic slug for system profiles. */
     semanticSlug?: string;
     /** Kind vs role profile. Omit for default ('kind'). */
@@ -117,21 +168,21 @@ interface TemplateDisplayTemplate {
     config: Record<string, unknown>;
 }
 interface TemplateSidebarSurface {
-    kind: 'cell' | 'view' | 'entity' | 'document' | 'channel' | 'app' | 'url';
+    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';
+    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';
+    kind: "app" | "view" | "profile" | "external" | "cell";
     appId?: string;
     viewName?: string;
     viewId?: string;
@@ -149,13 +200,20 @@ interface TemplateSidebarItem {
 interface TemplateLayoutConfig {
     pinnedApps?: string[];
     defaultView?: string;
-    /** The first-screen app — auto-opened on workspace switch */
+    /**
+     * Canonical first screen for this workspace.
+     *
+     * `undefined` means the template has no opinion during reconciliation,
+     * `null` explicitly returns the workspace to its home surface, and a
+     * descriptor replaces the current primary surface. */
+    primarySurface?: TemplatePrimarySurface | null;
+    /** Compatibility input only. New templates should use `app:` or `primarySurface`. */
     defaultApp?: string | null;
     theme?: string;
     sidebarItems?: TemplateSidebarItem[];
 }
 interface TemplateBentoBlock {
-    kind: 'view' | 'widget';
+    kind: "view" | "widget";
     viewName?: string;
     widgetType?: string;
     pos: {
@@ -173,7 +231,7 @@ interface TemplateProfileEntityBentoTemplates {
     };
 }
 /** Mirrors `WorkspaceSourceRole` in synap-backend `schema/workspaces.ts`. */
-type TemplateSourceRole = 'provider' | 'consumer' | 'provider-consumer';
+type TemplateSourceRole = "provider" | "consumer" | "provider-consumer";
 /** Mirrors `WorkspaceDefaultSource` in synap-backend `schema/workspaces.ts`. */
 interface TemplateDefaultSource {
     /** The workspace id that supplies this capability domain. */
@@ -191,7 +249,7 @@ interface TemplateOnboardingCollectTarget {
     /** Human description of what to capture for this target. */
     what: string;
     /** Roughly how many to expect — guides interview depth. */
-    cardinality?: 'one' | 'few' | 'several';
+    cardinality?: "one" | "few" | "several";
     /** Key fields the agent should make sure to fill. */
     keyFields?: string[];
 }
@@ -231,7 +289,7 @@ interface TemplateOnboarding {
 }
 interface TemplatePlaybookParam {
     name: string;
-    type: 'text' | 'number' | 'entity' | 'choice' | 'boolean';
+    type: "text" | "number" | "entity" | "choice" | "boolean";
     label?: string;
     required?: boolean;
     defaultValue?: unknown;
@@ -241,12 +299,12 @@ interface TemplatePlaybook {
     description?: string;
     goalTemplate: string;
     params?: TemplatePlaybookParam[];
-    executor?: 'is-agent' | 'external-agent' | 'hybrid';
-    inputStrategy?: 'none' | 'static' | 'rotating' | 'query';
+    executor?: "is-agent" | "external-agent" | "hybrid";
+    inputStrategy?: "none" | "static" | "rotating" | "query";
     channelSpec?: {
-        type: 'GROUP' | 'AGENT_COLLAB' | 'THREAD';
+        type: "GROUP" | "AGENT_COLLAB" | "THREAD";
         members?: string[];
-        aiReactionMode?: 'on_mention' | 'always' | 'never';
+        aiReactionMode?: "on_mention" | "always" | "never";
     };
     /**
      * A cron schedule that maintains ONE backing cron automation (a single
@@ -278,29 +336,29 @@ interface TemplatePlaybook {
         profileSlug: string;
         filter?: Record<string, unknown>;
     };
-    status?: 'draft' | 'active' | 'paused';
+    status?: "draft" | "active" | "paused";
 }
 interface TemplateAutomation {
     /** Stable local key (unused on the wire today — reserved for dedup/refs). */
     key?: string;
     name: string;
     description?: string;
-    triggerType: 'event' | 'cron' | 'webhook' | 'manual';
+    triggerType: "event" | "cron" | "webhook" | "manual";
     triggerConfig?: Record<string, unknown>;
     flow: {
         nodes: unknown[];
         edges: unknown[];
         precondition?: string;
     };
-    status?: 'draft' | 'active' | 'paused';
+    status?: "draft" | "active" | "paused";
 }
 interface TemplateActionPlacement {
     /** Entity kind whose detail surface this action appears on. */
     profileSlug: string;
     /** Where the action renders. Only "entity-detail" is consumed today. */
-    surface: 'entity-detail' | string;
+    surface: "entity-detail" | string;
     /** What the action does when clicked. */
-    kind: 'capability' | 'playbook' | 'automation';
+    kind: "capability" | "playbook" | "automation";
     /**
      * Reference to the thing to run: a capability verb key, or a playbook /
      * automation NAME (resolved to a row id at apply time).
@@ -332,7 +390,7 @@ interface TemplateIntegration {
     /** Override default params with {{var}} interpolation. */
     params?: Record<string, string>;
     /** "apply" (create+update) or "install" (create only). */
-    mode?: 'apply' | 'install';
+    mode?: "apply" | "install";
 }
 interface TemplateExtendsRef {
     source: string;
@@ -416,7 +474,7 @@ interface TemplateDependency {
      * - `'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';
+    relation?: "compose" | "require";
     /**
      * Short human reason shown in the install-time "this also installs…" prompt.
      */
@@ -453,7 +511,7 @@ interface WorkspaceYaml {
          * Workspace classifier — consumed by createFromDefinition (settings.workspaceType,
          * creator-role + agent-workspace behavior). Mirrors the backend union.
          */
-        workspaceType?: 'personal' | 'agent' | 'project' | 'operational';
+        workspaceType?: "personal" | "agent" | "project" | "operational";
         visibility?: string;
         /** Capabilities this workspace provides (e.g. "brand.library", "content.pipeline") */
         capabilities?: string[];
@@ -1036,8 +1094,8 @@ declare function groupByDomain<T>(items: readonly T[], domainOf: (item: T) => st
  *   • `scripts/check-converters.mjs` — injects the real converters, exits non-zero.
  *   • CP / pod / CLI (from dist) — import `validateTemplate` + `SYSTEM_PROFILES`.
  *
- * ZERO RUNTIME IMPORTS BY DESIGN. `build.mjs` loads this file directly under
- * Node's type-stripping BEFORE `tsup` builds `dist/`. A static
+ * NO RUNTIME IMPORT THAT FAILS AT STRIP-TIME. `build.mjs` loads this file
+ * directly under Node's type-stripping BEFORE `tsup` builds `dist/`. A static
  * `import { toWorkspaceDefinition } from "./define.js"` would fail to resolve at
  * that moment (define → templates.js does not exist pre-build, and Node's
  * type-stripper does not remap a `.js` specifier to its `.ts` source). So the
@@ -1045,6 +1103,14 @@ declare function groupByDomain<T>(items: readonly T[], domainOf: (item: T) => st
  * YAML/bento rules run everywhere; the converter-parity rules run wherever the
  * caller can supply the compiled converters (check-converters.mjs, from dist).
  * `import type` lines are fully erased by the type-stripper, so they are safe.
+ *
+ * THE ONE RUNTIME IMPORT: `./validate-flow.ts` (the pure automation-flow
+ * validator). It is imported with the `.ts` extension SPECIFICALLY so it resolves
+ * under Node's type-stripper at build.mjs time (a `.js` specifier would NOT — see
+ * above), and it has NO generated dependency (unlike `./define.js` → templates)
+ * so it is always present. It is DB-free (only `import type` internally), so it
+ * needs no injection: the flow-node contract check runs for every caller
+ * (build / check-converters / CLI / CP) automatically.
  */
 
 interface ValidationError {
@@ -1159,6 +1225,103 @@ declare function collectBaseProfileSlugs(data: WorkspaceYaml, resolveDep: (slug:
  */
 declare function validateTemplate(tpl: WorkspaceYaml, opts?: ValidateOptions): ValidateResult;
 
+/**
+ * Node-contract validation for automation flow definitions.
+ *
+ * The persist doors and the install/apply doors validate flow SHAPE only
+ * (`{ nodes: [], edges: [] }`). A semantically-broken flow — a `channel_message`
+ * output with a typo'd `channelType`, a `capability` node with no `verbId`, an
+ * edge to a nonexistent node, a cycle, an unknown `node.type` — passes the shape
+ * check and only fails at RUNTIME (automation-executor.ts throws mid-run). For a
+ * template automation this is worse: it validates green at author time and then
+ * SILENTLY never fires on a live pod.
+ *
+ * `validateFlowDefinition` closes that gap: a PURE, synchronous, DB-free function
+ * that rejects malformed flows with actionable per-node errors. It is called by
+ * `validateTemplate` (this package) so `synap market validate` / the build gate /
+ * the CP publish door all run the same contract check, and by the pod's persist
+ * doors.
+ *
+ * ── SSOT-IN-WAITING — temporary duplicate ────────────────────────────────────
+ * This is a PURE copy of synap-backend's
+ * `packages/api/src/services/automations/validate-flow.ts` (the current runtime
+ * SSOT, which carries the `@synap/database` COMPILE-TIME drift guard). This copy
+ * exists so `validateTemplate` — which runs in THIS published, backend-independent
+ * package (CLI `synap market validate` / build gate / CP publish) — can catch
+ * broken automation flows at AUTHOR time. It is intentionally free of any
+ * `@synap/database` import (this package depends only on zod + js-yaml), so the
+ * compile-time drift guard cannot live here; it stays in backend.
+ *
+ * The two copies are kept byte-identical (logic) by `validate-flow.drift.test.ts`
+ * in this package, which reads BOTH files and fails if they diverge.
+ *
+ * CUTOVER (collapse to ONE SSOT): publish `@synap-core/workspace-templates`, bump
+ * synap-backend (`^0.7.1`) and CP (`^0.9.2`) deps to that version, then replace
+ * backend's validate-flow.ts body with a re-export FROM HERE (keeping backend's
+ * `AssertExact` guard binding these arrays to the `@synap/database` unions).
+ * Until then: keep the constant arrays below identical to `@synap/database`
+ * `schema/automations.ts`.
+ */
+/** The 21 node types — `AutomationNodeBase.type` union (schema/automations.ts). */
+declare const FLOW_NODE_TYPES: readonly ["trigger", "command", "condition", "delay", "output", "loop", "transform", "fetch", "query", "entity_read", "related_entities", "guard", "compute", "select", "claim", "messages_query", "switch", "skill", "capability", "sub_automation", "playbook_run"];
+/** The 11 output types — `OutputNodeDef.data.outputType` (schema/automations.ts). */
+declare const FLOW_OUTPUT_TYPES: readonly ["notification", "entity_create", "entity_update", "facet_attach", "facet_update", "facet_detach", "relation_create", "webhook", "channel_message", "session_update", "set_state"];
+/**
+ * The known `config.channelType` values for a `channel_message` output. Mirrors
+ * the executor's channel_message resolution (automation-executor.ts). The output
+ * channel is CONTEXT-DERIVED — a channel_message is valid with `channelId`, OR
+ * `channelEntityRef` (an entity-id expression → that entity's internal channel),
+ * OR a `channelType` from this set, OR NOTHING (the executor defaults a targetless
+ * channel_message to the automation's own run channel). A `channelType` that is
+ * PRESENT but not one of these is still a typo → still an error.
+ */
+declare const CHANNEL_MESSAGE_CHANNEL_TYPES: readonly ["personal_thread", "proactive", "subjectEntity"];
+interface FlowValidationError {
+    /** Node the error is about (absent for graph-level / edge-level errors). */
+    nodeId?: string;
+    /** Edge the error is about (for dangling-reference / bad-handle errors). */
+    edgeId?: string;
+    /** Stable machine code — see the `code` literals below. */
+    code: string;
+    /** Human-actionable message naming what is wrong and how to fix it. */
+    message: string;
+}
+interface FlowValidationResult {
+    valid: boolean;
+    errors: FlowValidationError[];
+}
+/**
+ * Optional catalog resolvers. When provided, existence checks run; when omitted,
+ * those checks are SKIPPED (structural + contract checks always run). Kept
+ * synchronous so the whole function stays pure — the caller pre-loads whatever
+ * it needs and passes predicates.
+ */
+interface FlowValidationResolvers {
+    /** Does this capability verb (skill name) exist in the workspace catalog? */
+    verbExists?: (verbId: string) => boolean;
+    /** Does the referenced skill exist (by id OR by name)? */
+    skillExists?: (ref: {
+        skillId?: string;
+        skillName?: string;
+    }) => boolean;
+    /** Does the referenced playbook exist? */
+    playbookExists?: (ref: {
+        playbookId?: string;
+        playbookName?: string;
+    }) => boolean;
+}
+/**
+ * Validate an automation flow definition against the node contract.
+ * Pure and synchronous. `resolvers` gate the catalog-existence checks only.
+ */
+declare function validateFlowDefinition(flow: unknown, resolvers?: FlowValidationResolvers): FlowValidationResult;
+/**
+ * Convenience helper for the persist doors: run the validator and, if invalid,
+ * return a single joined actionable message (else null). Keeps the door code a
+ * one-liner and the message format consistent across create/update.
+ */
+declare function flowValidationErrorMessage(flow: unknown, resolvers?: FlowValidationResolvers): string | null;
+
 /**
  * @synap-core/workspace-templates — Definition adapter
  *
@@ -1207,6 +1370,14 @@ interface SplitBentoBlocks {
     bentoLayout: BentoWidgetBlockWire[];
     bentoViewBlocks: BentoViewBlockWire[];
 }
+/**
+ * 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.
+ */
+declare function normalizeTemplateLayout(layout: TemplateLayoutConfig | undefined, app: TemplateAppRef | undefined): TemplateLayoutConfig | undefined;
 declare function splitBentoBlocks(blocks: TemplateBentoBlock[] | undefined): SplitBentoBlocks;
 /** The flat definition object accepted by createFromDefinition. */
 interface WorkspaceDefinitionInput {
@@ -1362,4 +1533,4 @@ interface PackageDefinitionOutput {
  */
 declare function toPackageDefinition(slugOrYaml: string | WorkspaceYaml): PackageDefinitionOutput;
 
-export { type AssembleCatalogInput, type BentoViewBlockWire, type BentoWidgetBlockWire, type BundledCatalogEntry, type BundledEntry, type CatalogEntry, type CompositionEdge, type CompositionGraph, type CompositionInstalledEntry, type CompositionNode, type CompositionOverlay, type ConceptViolation, type CpPackageRow, DECLARED_DIVERGENCES, type DomainGroup, type InstalledTemplate, type LayerTemplateGraphInput, type MergeCatalogInput, type MergeCatalogResult, OTHER_DOMAIN_ID, OTHER_DOMAIN_LABEL, PACKAGE_DEPENDENCY_KINDS, type PackageDefinitionOutput, type PackageDependencyKind, REQUIRED_META_FIELDS, REQUIRED_WORKSPACE_FIELDS, type RemoteCatalogEntry, type RemoteEntry, type RemoteSourceStatus, SYSTEM_PROFILES, type SplitBentoBlocks, TEMPLATE_DOMAINS, type TemplateActionPlacement, type TemplateAppKind, type TemplateAppRef, type TemplateAutomation, type TemplateBentoBlock, type TemplateConverters, type TemplateDefaultSource, type TemplateDependency, type TemplateDisplayTemplate, type TemplateDomain, 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 TemplateUpdateCheck, type TemplateView, type ToDefinitionResult, type ValidateOptions, type ValidateResult, type ValidationError, WORKSPACE_TEMPLATES, type WorkspaceDefinitionInput, type WorkspaceTemplateSlug, type WorkspaceYaml, assembleCatalog, bundledEdgesOf, collectBaseProfileSlugs, computeTemplateUpdates, conceptTerm, domainLabel, findConceptViolations, formatConceptViolations, getWorkspaceTemplate, groupByDomain, isHashVersion, isKnownDomain, layerTemplateGraph, listPublicTemplates, listWorkspaceTemplates, mergeCatalog, rowToRemoteEntry, splitBentoBlocks, toPackageDefinition, toWorkspaceDefinition, validateTemplate };
+export { type AssembleCatalogInput, type BentoViewBlockWire, type BentoWidgetBlockWire, type BundledCatalogEntry, type BundledEntry, CHANNEL_MESSAGE_CHANNEL_TYPES, type CatalogEntry, type CompositionEdge, type CompositionGraph, type CompositionInstalledEntry, type CompositionNode, type CompositionOverlay, type ConceptViolation, type CpPackageRow, DECLARED_DIVERGENCES, type DomainGroup, FLOW_NODE_TYPES, FLOW_OUTPUT_TYPES, type FlowValidationError, type FlowValidationResolvers, type FlowValidationResult, type InstalledTemplate, type LayerTemplateGraphInput, type MergeCatalogInput, type MergeCatalogResult, OTHER_DOMAIN_ID, OTHER_DOMAIN_LABEL, PACKAGE_DEPENDENCY_KINDS, type PackageDefinitionOutput, type PackageDependencyKind, REQUIRED_META_FIELDS, REQUIRED_WORKSPACE_FIELDS, type RemoteCatalogEntry, type RemoteEntry, type RemoteSourceStatus, SYSTEM_PROFILES, type SplitBentoBlocks, TEMPLATE_DOMAINS, type TemplateActionPlacement, type TemplateAppKind, type TemplateAppRef, type TemplateAutomation, type TemplateBentoBlock, type TemplateConverters, type TemplateDefaultSource, type TemplateDependency, type TemplateDisplayTemplate, type TemplateDomain, type TemplateEntityLink, type TemplateExtendsRef, type TemplateIntegration, type TemplateLayoutConfig, type TemplateMeta, type TemplateOnboarding, type TemplateOnboardingCollectTarget, type TemplatePlaybook, type TemplatePlaybookParam, type TemplatePrimarySurface, type TemplateProfile, type TemplateProfileEntityBentoTemplates, type TemplateProperty, type TemplateSeedEntity, type TemplateSidebarItem, type TemplateSidebarSurface, type TemplateSourceRole, type TemplateSuggestedRelation, type TemplateUpdateCheck, type TemplateView, type ToDefinitionResult, type ValidateOptions, type ValidateResult, type ValidationError, WORKSPACE_TEMPLATES, type WorkspaceDefinitionInput, type WorkspaceJsonValue, type WorkspacePrimarySurface, type WorkspacePrimarySurfaceViewReference, type WorkspaceTemplateSlug, type WorkspaceYaml, assembleCatalog, bundledEdgesOf, collectBaseProfileSlugs, computeTemplateUpdates, conceptTerm, domainLabel, findConceptViolations, flowValidationErrorMessage, formatConceptViolations, getWorkspaceTemplate, groupByDomain, isHashVersion, isKnownDomain, layerTemplateGraph, listPublicTemplates, listWorkspaceTemplates, mergeCatalog, normalizeTemplateLayout, rowToRemoteEntry, splitBentoBlocks, toPackageDefinition, toWorkspaceDefinition, validateFlowDefinition, validateTemplate };