@synap-core/workspace-templates 0.7.1 → 0.7.3

package/dist/index.d.ts

@@ -393,6 +393,15 @@ interface TemplateMeta {
     color: string;
     tags?: string[];
     isPublic?: boolean;
+    /**
+     * Human-facing subject area used to SECTION the marketplace (CLI `market
+     * list`, browser New Space + catalog). Authored here so grouping is a
+     * property of the template, read by every surface — never re-derived from a
+     * hardcoded slug→group map in a consumer. NOT `category` (that is the
+     * PACKAGE TYPE — `workspace`/`capability`/…). Optional and open: an unknown
+     * or missing value is grouped, never dropped — see `./domains.ts`.
+     */
+    domain?: string;
 }
 interface WorkspaceYaml {
     /** Template metadata — not sent to backend, used for listing/UI */
@@ -550,6 +559,8 @@ interface RemoteEntry {
     description?: string;
     /** CP package category / type (e.g. `"workspace"`, `"view"`). */
     category?: string;
+    /** Human-facing subject area for display grouping — authored on `meta.domain`. See `./domains.ts`. */
+    domain?: string;
     tags?: string[];
     icon?: string | null;
     /**
@@ -612,6 +623,8 @@ interface CpPackageRow {
     description?: string | null;
     /** CP package category / type (e.g. `"workspace"`, `"view"`). */
     category?: string;
+    /** Human-facing subject area for display grouping — from the package's `meta.domain`. */
+    domain?: string | null;
     tags?: string[] | null;
     icon?: string | null;
     /** Present only on `/mine` rows. `false` ⇒ private. Browse rows omit it. */
@@ -635,6 +648,8 @@ interface CatalogEntryBase {
     description?: string;
     /** Package category / type. Bundled templates are always `"workspace"`. */
     category?: string;
+    /** Human-facing subject area for display grouping — authored `meta.domain`. See ./domains. */
+    domain?: string;
     tags: string[];
     icon?: string | null;
     /** `true` ⇒ not publicly listed (internal bundled template, or private CP row). */
@@ -863,6 +878,250 @@ interface LayerTemplateGraphInput {
 declare function bundledEdgesOf(slug: string): readonly TemplateDependency[];
 declare function layerTemplateGraph(input: LayerTemplateGraphInput): CompositionGraph;
 
+/**
+ * Cross-template CONCEPT guard — catches vocabulary forks between templates.
+ *
+ * WHY THIS EXISTS (read before weakening or deleting it):
+ * `business-developer.yaml` introduced workspace-scoped `crm-lead`/`crm-client`
+ * for the same real-world concept that `foundation.yaml`/`crm.yaml` declare as
+ * pod-wide shared `lead`/`client`. Nothing failed. Three reasons:
+ *
+ *   1. `build.mjs`'s `validate()` runs PER FILE, inside the read loop, so it
+ *      structurally cannot see that another template already owns `lead`.
+ *   2. The only vocabulary rule that exists (`template-shared-role-ssot.test.ts`
+ *      in synap-backend) polices a HARDCODED five-slug set — and it FORBIDS
+ *      declaring one of those slugs workspace-scoped, which is exactly what the
+ *      two-tier design legitimately needed. So RENAMING was the path of least
+ *      resistance: `crm-lead` is outside the set and passes silently. That rule
+ *      polices SPELLING, not MEANING.
+ *   3. That test also cannot run in CI — it resolves this package across a
+ *      sibling-repo relative path that CI never checks out. It is green on a dev
+ *      machine and mute everywhere else.
+ *
+ * This guard lives HERE, in the repo that owns the template source, and runs in
+ * this repo's CI (`pnpm test`) and in `pnpm build` / `prepublishOnly` via
+ * `scripts/check-concepts.mjs`. It is deliberately NOT a hardcoded slug list —
+ * that is the pattern that failed.
+ *
+ * WHAT IT DOES NOT DO: it does not guess. There is no fuzzy name matching, no
+ * edit distance, no synonym table. A guesser nobody trusts is worse than no
+ * guard. It uses two exact, falsifiable signals only — see the rules below.
+ */
+
+interface ConceptViolation {
+    rule: "concept-collision" | "alias-shape-divergence" | "stale-allowlist";
+    /** The concept term or semantic slug the finding is about. */
+    concept: string;
+    message: string;
+}
+/**
+ * DECLARED, INTENTIONAL divergences — the escape hatch, and deliberately the
+ * SECONDARY mechanism. An entry here is an author saying "yes, two spellings of
+ * one concept, on purpose, and here is why". Keep it tiny; every entry must
+ * carry its WHY. A key that stops matching anything FAILS the guard, so this
+ * list cannot rot into a graveyard.
+ *
+ * Key = the two colliding profile slugs, sorted, joined by "|".
+ */
+declare const DECLARED_DIVERGENCES: Record<string, string>;
+/**
+ * The bare noun a concept identifier ends in: `crm.lead` → `lead`,
+ * `crm-lead` → `lead`, `lead` → `lead`.
+ *
+ * This is EXACT terminal-token equality on the author's own qualified name —
+ * not a similarity heuristic. `crm-lead` and `lead` collide because the author
+ * literally wrote the same noun; `prospect` and `lead` do not collide, and that
+ * is honest: no guard can know they mean the same thing.
+ */
+declare function conceptTerm(semanticSlug: string): string;
+declare function findConceptViolations(templates?: Record<string, WorkspaceYaml>): ConceptViolation[];
+declare function formatConceptViolations(violations: ConceptViolation[]): string;
+
+/**
+ * Template DOMAIN taxonomy — the authored, cross-surface grouping that sections
+ * the marketplace (CLI `market list`, browser New Space + catalog, marketplace).
+ *
+ * WHY A FIELD, NOT DERIVED FROM TAGS. Grouping is a property of the template, so
+ * it lives ON the template (`meta.domain`) — authored once, read by every
+ * surface. The alternative was a hardcoded slug→group map (or a tag heuristic)
+ * inside each consumer; that map drifts the instant a template is added, and no
+ * one authoring a template can see it. Same lesson as the vocabulary work: a
+ * declared relationship should live where it can be verified, not re-guessed.
+ *
+ * NOT `category`. The catalog already uses `category` for the PACKAGE TYPE
+ * (`workspace`/`capability`/`skill`/…). `domain` is the human subject area.
+ *
+ * WORKS FOR ANY TEMPLATE. A template may declare a domain absent from this
+ * registry, or none at all — `groupByDomain` never drops one. Known domains
+ * render first in registry order; an unknown-but-declared domain renders after
+ * them (its id title-cased); a missing domain falls into the `other` bucket,
+ * always last. So a NEW template appears correctly without touching this file —
+ * adding it here only controls a domain's ORDER and LABEL.
+ */
+interface TemplateDomain {
+    id: string;
+    label: string;
+}
+declare const OTHER_DOMAIN_ID = "other";
+declare const OTHER_DOMAIN_LABEL = "More";
+/** Known domains, in display order (the order sections appear in a listing). */
+declare const TEMPLATE_DOMAINS: readonly TemplateDomain[];
+/** Every valid domain id the registry knows about (excludes `other`). */
+declare function isKnownDomain(id: string | undefined | null): boolean;
+/** Display label for a domain id. Missing → "More"; unknown-declared → title-cased id. */
+declare function domainLabel(id: string | undefined | null): string;
+interface DomainGroup<T> {
+    id: string;
+    label: string;
+    items: T[];
+}
+/**
+ * Partition `items` into ordered domain sections: known domains first (registry
+ * order), then unknown-but-declared domains (alphabetical), then the missing
+ * "More" bucket, always last. Empty sections are omitted; nothing is dropped.
+ * Item order WITHIN a section is preserved from the input.
+ */
+declare function groupByDomain<T>(items: readonly T[], domainOf: (item: T) => string | undefined | null): DomainGroup<T>[];
+
+/**
+ * The ONE importable template validator.
+ * ======================================
+ *
+ * Historically the only real per-template guards lived in build-only scripts
+ * OUTSIDE `src/` — `build.mjs`'s `validate()` and `scripts/check-converters.mjs`
+ * — so no other repo could call them. The CP publish path, the pod install/apply
+ * path, and the CLI all re-implemented (or skipped) these checks. This module
+ * moves the per-template rule logic into `src/`, as a PURE function that
+ * RETURNS structured results (never `process.exit`), so all four callers share
+ * ONE validator:
+ *
+ *   • `build.mjs`                — loops the corpus, exits non-zero on errors.
+ *   • `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
+ * `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
+ * converters are INJECTED via `opts.converters` rather than imported: the pure
+ * 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.
+ */
+
+interface ValidationError {
+    /** Stable machine code for the rule that fired (e.g. "profile-ref-unknown"). */
+    rule: string;
+    /** Dotted location inside the template, for error messages. */
+    path: string;
+    /** Human-readable description of the violation. */
+    message: string;
+}
+interface ValidateResult {
+    ok: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Structural view of the two converters, INJECTED (not imported) — see the file
+ * header. `check-converters.mjs` passes the real `toWorkspaceDefinition` /
+ * `toPackageDefinition` from `dist/`; their concrete types are structurally
+ * compatible with these minimal shapes.
+ */
+interface TemplateConverters {
+    toWorkspaceDefinition: (tpl: WorkspaceYaml) => {
+        definition: {
+            bentoLayout?: Array<{
+                widgetType?: unknown;
+            }>;
+            bentoViewBlocks?: Array<{
+                viewName?: unknown;
+                kind?: unknown;
+            }>;
+            bentoViewName?: string;
+            capabilities?: unknown[];
+        };
+    };
+    toPackageDefinition: (tpl: WorkspaceYaml) => {
+        bentoLayout?: Array<{
+            widgetType?: unknown;
+        }>;
+        bentoViewBlocks?: Array<{
+            viewName?: unknown;
+            kind?: unknown;
+        }>;
+        bentoViewName?: string;
+        capabilities?: unknown[];
+    };
+}
+interface ValidateOptions {
+    /**
+     * The whole corpus (parsed template data objects). Used to resolve a
+     * `compose`/`require` base's profile vocabulary. Keyed by `meta.slug`. Ignored
+     * when `resolveDep` is given.
+     */
+    corpus?: WorkspaceYaml[];
+    /** Direct dependency resolver — supersedes `corpus` when provided. */
+    resolveDep?: (slug: string) => WorkspaceYaml | undefined;
+    /**
+     * Compiled converters. When present, the converter-parity rules run (bento
+     * union split, wire-field shape, bentoViewName + capabilities parity across
+     * both install doors). When absent, only the pure YAML/bento rules run.
+     */
+    converters?: TemplateConverters;
+}
+declare const REQUIRED_META_FIELDS: readonly ["slug", "name", "description", "icon", "color"];
+declare const REQUIRED_WORKSPACE_FIELDS: readonly ["name", "description"];
+/**
+ * System profiles a template may reference without defining. This MUST mirror
+ * the profiles seeded by synap-backend `ensure-system-profiles.ts` (the
+ * `profiles` array) — that seeder is the ground truth for what exists on every
+ * pod. A slug present here but NOT seeded lets a dangling ref validate green (the
+ * old bug: `project`/`document` were listed here after both were removed from the
+ * seeder — `project` became a first-class table in migration 0151, `document`
+ * never existed as a profile). A slug seeded but MISSING here forces every
+ * template to re-declare it, which is the exact pressure that spawns vocabulary
+ * forks. Keep the two lists in lockstep.
+ *
+ * SINGLE SOURCE OF TRUTH: this set lived in build.mjs; it now lives HERE and
+ * build.mjs imports it, so there is one list to keep in lockstep with the seeder.
+ */
+declare const SYSTEM_PROFILES: Set<string>;
+/**
+ * Profile slugs a template may reference by virtue of its dependencies.
+ *
+ * `compose` and `require` are NOT the same for what a consumer may reference:
+ *   • `compose` MERGES the overlay into the base's ONE workspace, so the consumer
+ *     legitimately references ALL of the base's profiles (workspace-scoped ones
+ *     included) — that is the point of composing.
+ *   • `require` creates a SEPARATE workspace (installed first). Only the base's
+ *     POD-WIDE profiles (`scope: shared`; system profiles are handled separately)
+ *     cross that boundary and are visible to the consumer. The base's
+ *     `scope: WORKSPACE` profiles live in the base's OWN workspace and resolve
+ *     against NOTHING when referenced across a `require` — that is the class of
+ *     bug the social→content-os fork hit (a view/link/prop pointing at the base's
+ *     workspace-scoped profile provisions dangling and throws at runtime).
+ *
+ * Resolved TRANSITIVELY (a base's own bases count too, each by its own relation).
+ * Without this the validator is per-file and a real overlay can only reference
+ * system profiles + its own (blocks e.g. communication composing on brand-library).
+ *
+ * Moved verbatim out of build.mjs (semantics unchanged); it now resolves bases
+ * through the injected `resolveDep` rather than a hand-built `dataBySlug` map, so
+ * the same closure serves every caller.
+ */
+declare function collectBaseProfileSlugs(data: WorkspaceYaml, resolveDep: (slug: string) => WorkspaceYaml | undefined, seen?: Set<string>): Set<string>;
+/**
+ * Validate ONE template. Pure: returns `{ ok, errors }`, never exits. Covers the
+ * per-template rules formerly split across build.mjs `validate()` (required
+ * fields, ≥1 profile, structured-view-needs-scope, profileSlug referential
+ * integrity against `own ∪ SYSTEM_PROFILES ∪ dependency-vocab`, overlay safety,
+ * entityLink `type`) and check-converters.mjs (bento union split, widgetType /
+ * viewName present, bentoViewName + capabilities parity — the last group only
+ * when `opts.converters` is supplied).
+ */
+declare function validateTemplate(tpl: WorkspaceYaml, opts?: ValidateOptions): ValidateResult;
+
 /**
  * @synap-core/workspace-templates — Definition adapter
  *
@@ -1008,6 +1267,7 @@ interface PackageDefinitionOutput {
         slug: string;
         icon?: string;
         color?: string;
+        domain?: string;
         tags?: string[];
         isPublic?: boolean;
         requiredTier?: string | null;
@@ -1046,13 +1306,11 @@ interface PackageDefinitionOutput {
     automations?: PackageAutomationWire[];
     /**
      * Entity-detail action placements — carried verbatim (authored form IS the
-     * wire form). NOTE: the Hub `PackageApplySchema` (synap-backend
-     * `hub-protocol/rest/packages.ts`) is a plain `z.object` and does not yet
-     * declare `actionPlacements`, so on the CLI/Hub install path this field is
-     * STRIPPED before `applyPackagePostWorkspace` sees it. The tRPC
-     * `createFromDefinition` door DOES carry it. Named follow-up: add an
-     * `ActionPlacementSchema` field to `PackageApplySchema` to close the Hub half
-     * (out of the T2 fence — flagged in the handoff).
+     * wire form). The Hub `PackageApplySchema` (synap-backend
+     * `hub-protocol/rest/packages.ts`) now declares `actionPlacements`
+     * (`z.array(ActionPlacementSchema).optional()`), so BOTH the tRPC
+     * `createFromDefinition` door and the CLI/Hub install path carry it through to
+     * `applyPackagePostWorkspace` — the parity is closed.
      */
     actionPlacements?: WorkspaceYaml['actionPlacements'];
     onboarding?: WorkspaceYaml['onboarding'];
@@ -1067,4 +1325,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 CpPackageRow, type InstalledTemplate, type LayerTemplateGraphInput, type MergeCatalogInput, type MergeCatalogResult, PACKAGE_DEPENDENCY_KINDS, type PackageDefinitionOutput, type PackageDependencyKind, type RemoteCatalogEntry, type RemoteEntry, type RemoteSourceStatus, type SplitBentoBlocks, type TemplateActionPlacement, 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 TemplateUpdateCheck, type TemplateView, type ToDefinitionResult, WORKSPACE_TEMPLATES, type WorkspaceDefinitionInput, type WorkspaceTemplateSlug, type WorkspaceYaml, assembleCatalog, bundledEdgesOf, computeTemplateUpdates, getWorkspaceTemplate, isHashVersion, layerTemplateGraph, listPublicTemplates, listWorkspaceTemplates, mergeCatalog, rowToRemoteEntry, splitBentoBlocks, toPackageDefinition, toWorkspaceDefinition };
+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 };