@synap-core/workspace-templates 0.7.0 → 0.7.1

package/dist/index.d.ts

@@ -751,6 +751,118 @@ declare function isHashVersion(version: string | undefined): boolean;
  */
 declare function computeTemplateUpdates(installed: InstalledTemplate[], catalog: CatalogEntry[], bundleVersion?: string): TemplateUpdateCheck[];
 
+/**
+ * layerTemplateGraph — the KEYSTONE composition-graph engine.
+ * ============================================================
+ *
+ * Today the CLI (`synap-cli/src/commands/market.ts` `buildCompositionTrees`)
+ * renders template composition as a nested TREE: `buildDependencyNode`
+ * rebuilds a fresh `TreeNode` for every OCCURRENCE of a slug on every path, so
+ * a widely-required base (e.g. `foundation`) prints once per branch that
+ * reaches it (6× under a suite like `enterprise-os`). Its "shared" tag is only
+ * top-level-package granularity — there is no true fan-in count.
+ *
+ * This module replaces that with a LAYERED DAG: every node appears EXACTLY
+ * ONCE, positioned at its longest-path depth, with edges converging on it —
+ * so `foundation` sinks to the bedrock row with N inbound edges instead of
+ * being redrawn N times. It is the single source of truth for template
+ * composition; the CLI, browser dialogs, backend boot-ordering, and (later)
+ * the Atlas all consume it.
+ *
+ * PURE + TRANSPORT-AGNOSTIC (same discipline as `catalog.ts`): this is the
+ * ONLY module `synap-cli`, `browser`, `synap-control-plane-api`, and
+ * `synap-backend` can all resolve. No React, no dagre/d3, no fetch, no
+ * Node-only APIs. Pixel layout lives elsewhere (browser-only) — this module
+ * only computes topology (layers + edges + memoized nodes), never coordinates.
+ *
+ * CONSUMES drift, never recomputes it: `installed` / `updates` are read
+ * straight off `catalog.ts`'s `InstalledTemplate`-shaped rows and
+ * `computeTemplateUpdates()` output — this module does no semver comparison
+ * of its own.
+ */
+
+/**
+ * An installed template row, keyed by slug — the shape this engine needs to
+ * mark a node `installed` and populate `workspaceIds`.
+ *
+ * NOTE ON NAMING: `catalog.ts`'s `InstalledTemplate` is `{ slug, version }`
+ * only — it was built for `computeTemplateUpdates`'s narrower need (a version
+ * to diff) and carries no `workspaceId`. `CompositionNode.workspaceIds` is
+ * part of the ratified API and cannot be populated from that shape, so this
+ * is a REAL conflict, not a preference: this module declares its own,
+ * slightly richer row instead of importing `catalog.ts`'s `InstalledTemplate`
+ * under that name. Every field of `catalog.ts`'s `InstalledTemplate` is a
+ * subset of this one, so a caller building `InstalledTemplate[]` for
+ * `computeTemplateUpdates` can build ONE array of `CompositionInstalledEntry`
+ * and pass it to both doors.
+ */
+interface CompositionInstalledEntry {
+    slug: string;
+    workspaceId: string;
+    workspaceName?: string;
+    /** `settings.packageVersion`, when the pod stamped one. Omit when unknown. */
+    version?: string;
+}
+/** One compose-relation dependency, attached to the BASE node it overlays onto. */
+interface CompositionOverlay {
+    slug: string;
+    name: string;
+    installed: boolean;
+}
+/** One edge in the raw dependency graph, exactly as declared (kept even when broken by a cycle). */
+interface CompositionEdge {
+    from: string;
+    to: string;
+    relation: "compose" | "require";
+    depKind?: string;
+}
+interface CompositionNode {
+    slug: string;
+    name: string;
+    /** Longest-path depth: `1 + max(layer of every node that depends on this one)`. Roots = 0, bedrock = max. */
+    layer: number;
+    /** TRUE fan-in — every slug (node or compose-only overlay source) that declares a dependency on this one. */
+    dependents: string[];
+    /** Which of the input `roots` transitively reach this node (self-inclusive for a root). */
+    roots: string[];
+    installed: boolean;
+    workspaceIds: string[];
+    installedVersion?: string;
+    latestVersion?: string | null;
+    updateAvailable: boolean;
+    noVersionInfo: boolean;
+    /** `compose`-relation deps that overlay onto THIS node (see rule 2 — the overlay source itself is never a layer node). */
+    overlays: CompositionOverlay[];
+}
+interface CompositionGraph {
+    nodes: Map<string, CompositionNode>;
+    edges: CompositionEdge[];
+    /** `layers[0]` = roots … `layers[n]` = bedrock. Compose-overlay SOURCES never appear here (rule 2). */
+    layers: CompositionNode[][];
+    /** Broken back-edges `[from, to]` — surfaced, never silently swallowed (rule 4). */
+    cycles: string[][];
+}
+interface LayerTemplateGraphInput {
+    /** Top-level slugs to walk from. Always land at `layer: 0`. */
+    roots: string[];
+    /** INJECTED edge source (rule 5) — never hardcoded to the bundled map. See `bundledEdgesOf`. */
+    edgesOf: (slug: string) => readonly TemplateDependency[];
+    nameOf?: (slug: string) => string | undefined;
+    installed?: CompositionInstalledEntry[];
+    updates?: TemplateUpdateCheck[];
+}
+/**
+ * Default `edgesOf` — reads `dependencies[]` off the BUNDLED template map
+ * only. This is what the current CLI walker is hardcoded to, which is
+ * precisely the live bug rule 5 fixes: a remote/private CP-only package's
+ * `definition.dependencies` are invisible to it, so its subtree silently
+ * renders empty. Callers with a remote catalog entry available should pass
+ * their OWN `edgesOf` that falls back to `entry.remote.definition.dependencies`
+ * (or similar) for slugs this default can't see.
+ */
+declare function bundledEdgesOf(slug: string): readonly TemplateDependency[];
+declare function layerTemplateGraph(input: LayerTemplateGraphInput): CompositionGraph;
+
 /**
  * @synap-core/workspace-templates — Definition adapter
  *
@@ -955,4 +1067,4 @@ interface PackageDefinitionOutput {
  */
 declare function toPackageDefinition(slugOrYaml: string | WorkspaceYaml): PackageDefinitionOutput;
 
-export { type AssembleCatalogInput, type BentoViewBlockWire, type BentoWidgetBlockWire, type BundledCatalogEntry, type BundledEntry, type CatalogEntry, type CpPackageRow, type InstalledTemplate, 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, computeTemplateUpdates, getWorkspaceTemplate, isHashVersion, 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 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 };

package/dist/index.js

@@ -26876,6 +26876,140 @@ function computeTemplateUpdates(installed, catalog, bundleVersion) {
   });
 }
 
+// src/composition-graph.ts
+function bundledEdgesOf(slug) {
+  return getWorkspaceTemplate(slug)?.dependencies ?? [];
+}
+function layerTemplateGraph(input) {
+  const { roots, edgesOf } = input;
+  const nameOf = input.nameOf ?? (() => void 0);
+  const rootSet = new Set(roots);
+  const installedBySlug = /* @__PURE__ */ new Map();
+  for (const entry of input.installed ?? []) {
+    const list = installedBySlug.get(entry.slug);
+    if (list) list.push(entry);
+    else installedBySlug.set(entry.slug, [entry]);
+  }
+  const updatesBySlug = new Map((input.updates ?? []).map((u) => [u.slug, u]));
+  const edges = [];
+  const cycles = [];
+  const touched = new Set(roots);
+  const adjacency = /* @__PURE__ */ new Map();
+  const dependentsMap = /* @__PURE__ */ new Map();
+  const composeEdges = [];
+  const discovered = /* @__PURE__ */ new Set();
+  function addAdjacency(from, to) {
+    const set = adjacency.get(from);
+    if (set) set.add(to);
+    else adjacency.set(from, /* @__PURE__ */ new Set([to]));
+  }
+  function addDependent(dependency, dependent) {
+    const set = dependentsMap.get(dependency);
+    if (set) set.add(dependent);
+    else dependentsMap.set(dependency, /* @__PURE__ */ new Set([dependent]));
+  }
+  function walk(slug, ancestors) {
+    const deps = edgesOf(slug) ?? [];
+    for (const dep of deps) {
+      const relation = dep.relation ?? "require";
+      touched.add(dep.slug);
+      if (ancestors.has(dep.slug)) {
+        cycles.push([slug, dep.slug]);
+        edges.push({ from: slug, to: dep.slug, relation, depKind: dep.kind });
+        continue;
+      }
+      edges.push({ from: slug, to: dep.slug, relation, depKind: dep.kind });
+      addAdjacency(slug, dep.slug);
+      addDependent(dep.slug, slug);
+      if (relation === "compose") {
+        composeEdges.push({ from: slug, to: dep.slug, depKind: dep.kind });
+      }
+      if (!discovered.has(dep.slug)) {
+        discovered.add(dep.slug);
+        const nextAncestors = new Set(ancestors);
+        nextAncestors.add(slug);
+        walk(dep.slug, nextAncestors);
+      }
+    }
+  }
+  for (const root of roots) {
+    if (discovered.has(root)) continue;
+    discovered.add(root);
+    walk(root, /* @__PURE__ */ new Set([root]));
+  }
+  const composeSources = new Set(composeEdges.map((e) => e.from));
+  const overlaysByBase = /* @__PURE__ */ new Map();
+  for (const e of composeEdges) {
+    const isInstalled = installedBySlug.has(e.from);
+    const overlay = { slug: e.from, name: nameOf(e.from) ?? e.from, installed: isInstalled };
+    const list = overlaysByBase.get(e.to);
+    if (list) list.push(overlay);
+    else overlaysByBase.set(e.to, [overlay]);
+  }
+  const nodeSlugs = [...touched].filter((s) => !composeSources.has(s)).sort();
+  const rootsReaching = /* @__PURE__ */ new Map();
+  for (const root of roots) {
+    const visited = /* @__PURE__ */ new Set([root]);
+    const queue = [root];
+    const addReach = (s) => {
+      const set = rootsReaching.get(s);
+      if (set) set.add(root);
+      else rootsReaching.set(s, /* @__PURE__ */ new Set([root]));
+    };
+    addReach(root);
+    while (queue.length) {
+      const cur = queue.shift();
+      for (const next of adjacency.get(cur) ?? []) {
+        if (visited.has(next)) continue;
+        visited.add(next);
+        addReach(next);
+        queue.push(next);
+      }
+    }
+  }
+  const layerMemo = /* @__PURE__ */ new Map();
+  function layerOf(slug, stack) {
+    if (rootSet.has(slug)) return 0;
+    const memoized = layerMemo.get(slug);
+    if (memoized !== void 0) return memoized;
+    if (stack.has(slug)) return 0;
+    stack.add(slug);
+    const dependents = dependentsMap.get(slug);
+    const layer = !dependents || dependents.size === 0 ? 0 : 1 + Math.max(...[...dependents].map((d) => layerOf(d, stack)));
+    stack.delete(slug);
+    layerMemo.set(slug, layer);
+    return layer;
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  for (const slug of nodeSlugs) {
+    const installedEntries = installedBySlug.get(slug) ?? [];
+    const workspaceIds = installedEntries.map((e) => e.workspaceId).filter(Boolean);
+    const installed = workspaceIds.length > 0;
+    const update = updatesBySlug.get(slug);
+    const installedVersion = update?.installedVersion || installedEntries[0]?.version;
+    const noVersionInfo = installed && (update === void 0 || update.latestVersion === void 0);
+    nodes.set(slug, {
+      slug,
+      name: nameOf(slug) ?? slug,
+      layer: layerOf(slug, /* @__PURE__ */ new Set()),
+      dependents: [...dependentsMap.get(slug) ?? []].sort(),
+      roots: [...rootsReaching.get(slug) ?? []].sort(),
+      installed,
+      workspaceIds,
+      installedVersion,
+      latestVersion: update?.latestVersion ?? null,
+      updateAvailable: update?.updateAvailable ?? false,
+      noVersionInfo,
+      overlays: overlaysByBase.get(slug) ?? []
+    });
+  }
+  const maxLayer = Math.max(0, ...[...nodes.values()].map((n) => n.layer));
+  const layers = Array.from({ length: maxLayer + 1 }, () => []);
+  for (const node of nodes.values()) layers[node.layer].push(node);
+  for (const bucket of layers) bucket.sort((a, b) => a.slug.localeCompare(b.slug));
+  return { nodes, edges, layers, cycles };
+}
+
 // src/define.ts
 function toAutomationWire(automations) {
   return automations?.map((a) => ({
@@ -27034,9 +27168,11 @@ export {
   PACKAGE_DEPENDENCY_KINDS,
   WORKSPACE_TEMPLATES,
   assembleCatalog,
+  bundledEdgesOf,
   computeTemplateUpdates,
   getWorkspaceTemplate,
   isHashVersion,
+  layerTemplateGraph,
   listPublicTemplates,
   listWorkspaceTemplates,
   mergeCatalog,