@growthub/cli 0.14.8 → 0.14.10

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-metadata-impact.js

@@ -0,0 +1,198 @@
+/**
+ * Growthub Workspace Blast-Radius V1 — transitive impact deriver.
+ *
+ * Answers the one question the single-hop primitives cannot: *if I change (or
+ * remove) this node, what is the FULL downstream set that goes stale?*
+ *
+ * The metadata graph (`workspace-metadata-graph.js`) already ships:
+ *   - `findDependents(graph, nodeId)`  — the nodes ONE hop upstream (incoming edges)
+ *   - `selectImpactedNodes(graph, nodeId)` (selectors) — a thin wrapper over it
+ *
+ * Both stop at the first hop. Editing a field surfaces the widgets that use it,
+ * but NOT the dashboards that contain those widgets, nor the runs that executed
+ * a workflow whose node reads the object. This module generalises
+ * `findDependents` into its transitive closure: a deterministic breadth-first
+ * walk of incoming edges, returning every reachable dependent with its hop
+ * distance and the relation it was reached through.
+ *
+ * It is a PURE module — no React, no fetch, no fs, no writes, no localStorage,
+ * no CSS. It introduces NO new graph, NO new mutation path: it reads the
+ * read-only graph the Workspace Map already builds, and emits a low-entropy
+ * view-model that the Map inspector, `patch/preflight`, the CLI `plan` command,
+ * and an MCP `simulate_causal_impact` tool can all consume from one source of
+ * truth. It contains no secrets — it carries only the same compact node
+ * summaries the graph already exposes.
+ *
+ * Determinism: results are ordered (distance → type → id) and the BFS visits
+ * each node once, so a cycle in the graph terminates and the output diffs
+ * cleanly between calls.
+ */
+
+const BLAST_RADIUS_KIND = "growthub-workspace-blast-radius-v1";
+const BLAST_RADIUS_VERSION = 1;
+
+// Bound the walk so a pathological graph can never produce an unbounded
+// payload. Honest truncation (`truncated: true`) beats a silent cap.
+const DEFAULT_MAX_NODES = 500;
+
+function safeString(value) {
+  if (value == null) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+function summarizeOrigin(node) {
+  if (!node || typeof node !== "object") return null;
+  return {
+    id: node.id,
+    type: node.type,
+    label: node.label,
+    metadataId: node.metadataId
+  };
+}
+
+/**
+ * Build a `Map<toId, Array<{ from, relation }>>` of incoming edges once, so the
+ * transitive walk is linear in (nodes + edges) instead of calling the O(N)
+ * `findDependents` per visited node. This is the transitive form of
+ * `findDependents`; the per-hop semantics are identical.
+ */
+function buildIncomingIndex(graph) {
+  const incoming = new Map();
+  const edges = Array.isArray(graph?.edges) ? graph.edges : [];
+  for (const edge of edges) {
+    if (!edge || edge.from == null || edge.to == null) continue;
+    const key = String(edge.to);
+    if (!incoming.has(key)) incoming.set(key, []);
+    incoming.get(key).push({ from: String(edge.from), relation: edge.relation });
+  }
+  return incoming;
+}
+
+/**
+ * Compute the blast radius of a node — every node that transitively depends on
+ * it (reverse edge closure).
+ *
+ * @param {object} graph    a `buildWorkspaceMetadataGraph` envelope
+ * @param {string} originId the metadataId of the node being changed/removed
+ * @param {object} [options]
+ * @param {number} [options.maxNodes=500] hard cap on impacted nodes
+ * @param {number} [options.maxDistance] optional hop limit (omit = unbounded)
+ * @returns {object} `{ kind, version, origin, impacted[], byType, total, maxDistanceReached, truncated, summary, warnings }`
+ */
+function deriveBlastRadius(graph, originId, options = {}) {
+  const maxNodes = Number.isFinite(options.maxNodes) && options.maxNodes > 0
+    ? Math.floor(options.maxNodes)
+    : DEFAULT_MAX_NODES;
+  const maxDistance = Number.isFinite(options.maxDistance) && options.maxDistance > 0
+    ? Math.floor(options.maxDistance)
+    : Infinity;
+
+  const empty = (warning) => ({
+    kind: BLAST_RADIUS_KIND,
+    version: BLAST_RADIUS_VERSION,
+    origin: null,
+    impacted: [],
+    byType: {},
+    total: 0,
+    maxDistanceReached: 0,
+    truncated: false,
+    summary: "No impact computed.",
+    warnings: warning ? [warning] : []
+  });
+
+  const id = safeString(originId).trim();
+  if (!graph || typeof graph !== "object" || !Array.isArray(graph.nodes)) {
+    return empty("graph missing or malformed");
+  }
+  if (!id) return empty("originId missing");
+
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const originNode = nodesById.get(id);
+  if (!originNode) return empty(`origin "${id}" not found in graph`);
+
+  const incoming = buildIncomingIndex(graph);
+
+  const visited = new Set([id]);
+  const impacted = [];
+  let truncated = false;
+  let maxDistanceReached = 0;
+
+  // FIFO queue → breadth-first, so the first time a node is reached is via its
+  // shortest dependency path (the most direct reason it goes stale).
+  const queue = [{ id, distance: 0 }];
+  while (queue.length) {
+    const current = queue.shift();
+    if (current.distance >= maxDistance) continue;
+    const dependents = incoming.get(current.id) || [];
+    for (const { from, relation } of dependents) {
+      if (visited.has(from)) continue;
+      const node = nodesById.get(from);
+      if (!node) continue;
+      if (impacted.length >= maxNodes) {
+        truncated = true;
+        continue;
+      }
+      visited.add(from);
+      const distance = current.distance + 1;
+      maxDistanceReached = Math.max(maxDistanceReached, distance);
+      impacted.push({
+        id: node.id,
+        type: node.type,
+        label: node.label,
+        metadataId: node.metadataId,
+        distance,
+        viaRelation: relation
+      });
+      queue.push({ id: from, distance });
+    }
+  }
+
+  // Deterministic order: nearest first, then by type, then by id.
+  impacted.sort((a, b) =>
+    a.distance - b.distance ||
+    a.type.localeCompare(b.type) ||
+    a.id.localeCompare(b.id)
+  );
+
+  const byType = {};
+  for (const entry of impacted) {
+    byType[entry.type] = (byType[entry.type] || 0) + 1;
+  }
+
+  return {
+    kind: BLAST_RADIUS_KIND,
+    version: BLAST_RADIUS_VERSION,
+    origin: summarizeOrigin(originNode),
+    impacted,
+    byType,
+    total: impacted.length,
+    maxDistanceReached,
+    truncated,
+    summary: summarizeBlastRadius(originNode, impacted, byType, truncated),
+    warnings: []
+  };
+}
+
+/**
+ * One human sentence for the inspector chip / PR comment / CLI line.
+ * Pure string assembly — never throws.
+ */
+function summarizeBlastRadius(originNode, impacted, byType, truncated) {
+  const label = originNode?.label || originNode?.id || "node";
+  if (!impacted.length) {
+    return `Changing "${label}" has no downstream impact — nothing depends on it.`;
+  }
+  const parts = Object.keys(byType)
+    .sort()
+    .map((type) => `${byType[type]} ${type}`);
+  const tail = truncated ? " (truncated)" : "";
+  return `Changing "${label}" affects ${impacted.length} downstream node(s): ${parts.join(", ")}${tail}.`;
+}
+
+export {
+  BLAST_RADIUS_KIND,
+  BLAST_RADIUS_VERSION,
+  DEFAULT_MAX_NODES,
+  deriveBlastRadius,
+  summarizeBlastRadius
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-patch-impact.js

@@ -0,0 +1,133 @@
+/**
+ * Growthub Workspace Patch-Impact V1 — the single, authoritative "what does this
+ * patch actually change?" deriver, shared by the preflight route and the CLI.
+ *
+ * A dataModel/dashboards PATCH REPLACES the whole array, so the patch body alone
+ * is never "what changed". This diffs the CURRENT config against the MERGED
+ * (post-patch) config and reports THREE classes of change, each with downstream
+ * impact:
+ *
+ *   - added / modified objects + dashboards → seeded on the MERGED graph
+ *     (their new dependents).
+ *   - REMOVED objects + dashboards → seeded on the CURRENT graph, because the
+ *     deleted node no longer exists in the merged graph; the surfaces that
+ *     depended on it are the blast radius of deleting it. Without this, deleting
+ *     a business surface would silently report no impact — the highest-risk
+ *     false confidence.
+ *
+ * Pure: composes `deriveStaleSurfaces` (which composes the blast-radius spine),
+ * no new traversal, no writes, no secrets.
+ */
+
+import { deriveStaleSurfaces } from "./workspace-stale-surfaces.js";
+
+const PATCH_IMPACT_KIND = "growthub-workspace-patch-impact-v1";
+const PATCH_IMPACT_VERSION = 1;
+
+function objectIndex(config) {
+  return new Map((config?.dataModel?.objects || []).map((o) => [o && o.id, JSON.stringify(o)]));
+}
+function dashboardIndex(config) {
+  return new Map((config?.dashboards || []).map((d) => [d && (d.id || d.name), JSON.stringify(d)]));
+}
+
+/**
+ * @param {object} currentGraph graph built from the CURRENT config (pre-patch)
+ * @param {object} mergedGraph  graph built from the MERGED config (post-patch)
+ * @param {object} currentConfig
+ * @param {object} mergedConfig
+ * @returns {object} `{ kind, version, scope, seeds[], total, byType, staleSurfaces[], removed[], summary, warnings }`
+ */
+function derivePatchImpact(currentGraph, mergedGraph, currentConfig, mergedConfig) {
+  const empty = (warning) => ({
+    kind: PATCH_IMPACT_KIND,
+    version: PATCH_IMPACT_VERSION,
+    scope: "changed-only",
+    seeds: [],
+    total: 0,
+    byType: {},
+    staleSurfaces: [],
+    removed: [],
+    summary: "No object or dashboard added, modified, or removed.",
+    warnings: warning ? [warning] : []
+  });
+
+  if (!mergedGraph || !Array.isArray(mergedGraph.nodes)) return empty("merged graph missing");
+
+  const curObjects = objectIndex(currentConfig);
+  const mergedObjects = objectIndex(mergedConfig);
+  const curDashboards = dashboardIndex(currentConfig);
+  const mergedDashboards = dashboardIndex(mergedConfig);
+
+  const changedObjectIds = new Set();
+  const removedObjectIds = new Set();
+  for (const [id, json] of mergedObjects) if (id && curObjects.get(id) !== json) changedObjectIds.add(id);
+  for (const [id] of curObjects) if (id && !mergedObjects.has(id)) removedObjectIds.add(id);
+
+  const changedDashboardIds = new Set();
+  const removedDashboardIds = new Set();
+  for (const [id, json] of mergedDashboards) if (id && curDashboards.get(id) !== json) changedDashboardIds.add(id);
+  for (const [id] of curDashboards) if (id && !mergedDashboards.has(id)) removedDashboardIds.add(id);
+
+  // ── added / modified: seed on the MERGED graph ──────────────────────────
+  const changedSeeds = [];
+  for (const node of mergedGraph.nodes) {
+    if (node.type === "dataModelObject" && (changedObjectIds.has(node.summary?.objectId) || changedObjectIds.has(node.metadataId))) {
+      changedSeeds.push(node.id);
+    } else if (node.type === "dashboard" && (changedDashboardIds.has(node.metadataId) || changedDashboardIds.has(node.label))) {
+      changedSeeds.push(node.id);
+    }
+  }
+  const changedStale = changedSeeds.length ? deriveStaleSurfaces(mergedGraph, { seedIds: changedSeeds }) : null;
+
+  // ── removed: seed on the CURRENT graph (the deleted node lived there) ────
+  const removed = [];
+  const currentNodes = (currentGraph && Array.isArray(currentGraph.nodes)) ? currentGraph.nodes : [];
+  for (const node of currentNodes) {
+    const isRemovedObject = node.type === "dataModelObject" && (removedObjectIds.has(node.summary?.objectId) || removedObjectIds.has(node.metadataId));
+    const isRemovedDashboard = node.type === "dashboard" && (removedDashboardIds.has(node.metadataId) || removedDashboardIds.has(node.label));
+    if (!isRemovedObject && !isRemovedDashboard) continue;
+    const downstream = deriveStaleSurfaces(currentGraph, { seedIds: [node.id] });
+    removed.push({
+      id: node.id,
+      type: node.type,
+      label: node.label,
+      metadataId: node.metadataId,
+      affectedTotal: downstream.total,
+      affected: downstream.staleSurfaces,
+      summary: `Removing "${node.label}" affects ${downstream.total} downstream surface(s) that depend on it.`
+    });
+  }
+
+  if (!changedStale && !removed.length) return empty();
+
+  return {
+    kind: PATCH_IMPACT_KIND,
+    version: PATCH_IMPACT_VERSION,
+    scope: "changed-only",
+    seeds: changedStale ? changedStale.seeds : [],
+    total: changedStale ? changedStale.total : 0,
+    byType: changedStale ? changedStale.byType : {},
+    staleSurfaces: changedStale ? changedStale.staleSurfaces : [],
+    removed,
+    summary: summarizePatchImpact(changedStale, removed),
+    warnings: removed.length ? [`${removed.length} object/dashboard removal(s) — review affected downstream before applying.`] : []
+  };
+}
+
+function summarizePatchImpact(changedStale, removed) {
+  const parts = [];
+  if (changedStale && changedStale.total) parts.push(`${changedStale.total} surface(s) stale from add/modify`);
+  if (removed.length) {
+    const affected = removed.reduce((sum, r) => sum + (r.affectedTotal || 0), 0);
+    parts.push(`${removed.length} removal(s) affecting ${affected} downstream surface(s)`);
+  }
+  return parts.length ? `Patch impact: ${parts.join("; ")}.` : "No downstream impact.";
+}
+
+export {
+  PATCH_IMPACT_KIND,
+  PATCH_IMPACT_VERSION,
+  derivePatchImpact,
+  summarizePatchImpact
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-provenance-lineage.js

@@ -0,0 +1,214 @@
+/**
+ * Growthub Workspace Provenance-Lineage V1 — bidirectional lineage deriver.
+ *
+ * The mirror twin of `deriveBlastRadius`. It exposes BOTH transitive directions
+ * over the SAME edge taxonomy, named to MATCH the graph's own helper contract
+ * (`findDependents` = incoming, `findDependencies` = outgoing) so an agent never
+ * mis-reads a consumer as a producer:
+ *
+ *   - dependents    — transitive INCOMING closure (generalises `findDependents`):
+ *                     the nodes that DEPEND ON this node — its consumers and the
+ *                     things impacted if it changes (e.g. a widget that binds an
+ *                     object is the object's dependent). "What depends on this?"
+ *   - dependencies  — transitive OUTGOING closure (generalises `findDependencies`):
+ *                     the nodes this one DEPENDS ON — what it is built from /
+ *                     reads (e.g. an object's source record). "What does this
+ *                     depend on?"
+ *
+ * `ancestors` / `descendants` are kept ONLY as backward-compatible aliases of
+ * `dependents` / `dependencies` respectively — they read intuitively for the
+ * run→artifact case but mislead for objects/widgets/dashboards, so prefer the
+ * canonical names. The `direction` option accepts `dependents` | `dependencies`
+ * | `both` (and the legacy `ancestors` | `descendants`).
+ *
+ * One bounded, cycle-safe, deterministic BFS — the same skeleton the spine uses.
+ * No new graph, no new edges, no mutation, no secrets. `selectRunLineage` is the
+ * flat single-run ancestor of this module.
+ */
+
+import { summarizeGraphNode } from "./workspace-metadata-graph.js";
+import { deriveBlastRadius } from "./workspace-metadata-impact.js";
+
+const PROVENANCE_KIND = "growthub-workspace-provenance-lineage-v1";
+const PROVENANCE_VERSION = 1;
+
+const DEFAULT_MAX_NODES = 500;
+
+function safeString(value) {
+  if (value == null) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+/**
+ * Build the OUTGOING adjacency index once: `Map<fromId, Array<{ to, relation }>>`.
+ * (The INCOMING/dependents direction is NOT re-implemented here — it reuses the
+ * shipped `deriveBlastRadius` reverse closure, the single source of truth for
+ * incoming-edge traversal.)
+ */
+function buildOutgoingIndex(graph) {
+  const adjacency = new Map();
+  const edges = Array.isArray(graph?.edges) ? graph.edges : [];
+  for (const edge of edges) {
+    if (!edge || edge.from == null || edge.to == null) continue;
+    const key = String(edge.from);
+    if (!adjacency.has(key)) adjacency.set(key, []);
+    adjacency.get(key).push({ to: String(edge.to), relation: edge.relation });
+  }
+  return adjacency;
+}
+
+/**
+ * Bounded, cycle-safe BFS from `originId` over a pre-built adjacency index.
+ * Mirrors the blast-radius walk: FIFO queue → shortest path first, each node
+ * visited once, honest truncation past `maxNodes`.
+ */
+function walk(adjacency, nodesById, originId, maxNodes) {
+  const visited = new Set([originId]);
+  const reached = [];
+  let truncated = false;
+  let maxDistanceReached = 0;
+  const queue = [{ id: originId, distance: 0 }];
+  while (queue.length) {
+    const current = queue.shift();
+    const neighbours = adjacency.get(current.id) || [];
+    for (const { to, relation } of neighbours) {
+      if (visited.has(to)) continue;
+      const node = nodesById.get(to);
+      if (!node) continue;
+      if (reached.length >= maxNodes) {
+        truncated = true;
+        continue;
+      }
+      visited.add(to);
+      const distance = current.distance + 1;
+      maxDistanceReached = Math.max(maxDistanceReached, distance);
+      reached.push({
+        id: node.id,
+        type: node.type,
+        label: node.label,
+        metadataId: node.metadataId,
+        distance,
+        viaRelation: relation
+      });
+      queue.push({ id: to, distance });
+    }
+  }
+  reached.sort((a, b) =>
+    a.distance - b.distance ||
+    a.type.localeCompare(b.type) ||
+    a.id.localeCompare(b.id)
+  );
+  return { reached, truncated, maxDistanceReached };
+}
+
+/**
+ * @param {object} graph a `buildWorkspaceMetadataGraph` envelope
+ * @param {string} originId the metadataId to trace lineage for
+ * @param {object} [options]
+ * @param {"dependents"|"dependencies"|"both"|"ancestors"|"descendants"} [options.direction="both"]
+ * @param {number} [options.maxNodes=500] hard cap PER direction
+ * @returns {object} `{ kind, version, origin, direction, dependents[], dependencies[],
+ *   ancestors[] (alias of dependents), descendants[] (alias of dependencies),
+ *   byType, truncated, summary, warnings }`
+ */
+function deriveProvenanceLineage(graph, originId, options = {}) {
+  const maxNodes = Number.isFinite(options.maxNodes) && options.maxNodes > 0
+    ? Math.floor(options.maxNodes)
+    : DEFAULT_MAX_NODES;
+  // Normalise the requested direction to the canonical names (legacy aliases
+  // ancestors→dependents, descendants→dependencies).
+  const requested = safeString(options.direction) || "both";
+  const direction = requested === "ancestors" ? "dependents"
+    : requested === "descendants" ? "dependencies"
+      : ["dependents", "dependencies", "both"].includes(requested) ? requested
+        : "both";
+
+  const empty = (warning) => ({
+    kind: PROVENANCE_KIND,
+    version: PROVENANCE_VERSION,
+    origin: null,
+    direction,
+    dependents: [],
+    dependencies: [],
+    ancestors: [],
+    descendants: [],
+    byType: { dependents: {}, dependencies: {} },
+    truncated: false,
+    summary: "No lineage computed.",
+    warnings: warning ? [warning] : []
+  });
+
+  if (!graph || typeof graph !== "object" || !Array.isArray(graph.nodes)) {
+    return empty("graph missing or malformed");
+  }
+  const id = safeString(originId).trim();
+  if (!id) return empty("originId missing");
+
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const originNode = nodesById.get(id);
+  if (!originNode) return empty(`origin "${id}" not found in graph`);
+
+  let dependents = [];
+  let dependencies = [];
+  let truncated = false;
+
+  if (direction === "dependents" || direction === "both") {
+    // Reuse the spine — `dependents` IS the transitive incoming (reverse) closure
+    // that deriveBlastRadius already computes. No second incoming BFS.
+    const blast = deriveBlastRadius(graph, id, { maxNodes });
+    dependents = blast.impacted;
+    truncated = truncated || blast.truncated;
+  }
+  if (direction === "dependencies" || direction === "both") {
+    const res = walk(buildOutgoingIndex(graph), nodesById, id, maxNodes);
+    dependencies = res.reached;
+    truncated = truncated || res.truncated;
+  }
+
+  const countByType = (entries) => {
+    const out = {};
+    for (const entry of entries) out[entry.type] = (out[entry.type] || 0) + 1;
+    return out;
+  };
+
+  return {
+    kind: PROVENANCE_KIND,
+    version: PROVENANCE_VERSION,
+    origin: summarizeGraphNode(originNode),
+    direction,
+    // Canonical names — match findDependents (incoming) / findDependencies (outgoing).
+    dependents,
+    dependencies,
+    // Backward-compatible aliases (deprecated; can mislead for non-run nodes).
+    ancestors: dependents,
+    descendants: dependencies,
+    byType: { dependents: countByType(dependents), dependencies: countByType(dependencies) },
+    truncated,
+    summary: summarizeLineage(originNode, dependents, dependencies, direction, truncated),
+    warnings: []
+  };
+}
+
+function summarizeLineage(originNode, dependents, dependencies, direction, truncated) {
+  const label = originNode?.label || originNode?.id || "node";
+  const tail = truncated ? " (truncated)" : "";
+  if (direction === "dependents") {
+    return dependents.length
+      ? `${dependents.length} node(s) depend on "${label}"${tail}.`
+      : `Nothing depends on "${label}".`;
+  }
+  if (direction === "dependencies") {
+    return dependencies.length
+      ? `"${label}" depends on ${dependencies.length} node(s)${tail}.`
+      : `"${label}" depends on nothing.`;
+  }
+  return `"${label}": ${dependents.length} dependent(s), ${dependencies.length} dependenc(ies)${tail}.`;
+}
+
+export {
+  PROVENANCE_KIND,
+  PROVENANCE_VERSION,
+  DEFAULT_MAX_NODES,
+  deriveProvenanceLineage,
+  summarizeLineage
+};