@growthub/cli 0.14.9 → 0.14.10

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
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-stale-surfaces.js

@@ -0,0 +1,217 @@
+/**
+ * Growthub Workspace Stale-Surfaces V1 — freshness-aware impact deriver.
+ *
+ * Answers the question the spine (`deriveBlastRadius`) cannot answer on its
+ * own: *given the changes the graph already records, which downstream surfaces
+ * are stale RIGHT NOW?* — with no change-event argument required.
+ *
+ * The metadata graph already timestamps the only nodes whose freshness is
+ * observable: `run.ranAt`, `sourceRecord.fetchedAt`, and
+ * `pipelineHealth.latestRanAt`. When one of those upstream nodes changes, the
+ * surfaces that DEPEND on it (its reverse-edge closure) are the surfaces now
+ * showing old data. This module seeds the EXISTING `deriveBlastRadius` closure
+ * from those freshly-changed nodes and labels the reachable dependents stale.
+ *
+ * It builds NO new graph and NO second traversal engine — it composes the
+ * shipped blast-radius deriver and the timestamps the graph already carries.
+ * Pure: no React, no fetch, no fs, no writes, no secrets. Deterministic:
+ * results are ordered (distance → type → id) and the union de-duplicates, so
+ * the output diffs cleanly between calls.
+ *
+ * Relationship to `selectStaleMetadataGroups` (single-hop, group-level): that
+ * selector answers "given THIS change event, which metadata GROUPS reload?".
+ * This deriver answers "given the timestamps already in the graph, which
+ * specific NODES are stale, transitively?". They are complementary; this one
+ * is node-level and needs no caller-supplied event.
+ */
+
+import { deriveBlastRadius } from "./workspace-metadata-impact.js";
+
+const STALE_SURFACES_KIND = "growthub-workspace-stale-surfaces-v1";
+const STALE_SURFACES_VERSION = 1;
+
+const DEFAULT_MAX_NODES = 500;
+
+// Summary fields that observably timestamp a node's last refresh. Ordered by
+// the precision of "this node changed at T". The newest of these wins.
+const FRESHNESS_FIELDS = ["ranAt", "fetchedAt", "latestRanAt"];
+
+function safeString(value) {
+  if (value == null) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+/**
+ * Parse a node's last-known-fresh timestamp (ms epoch) from its summary, or
+ * null when the node carries no observable freshness. Never throws.
+ */
+function nodeFreshAt(node) {
+  const summary = node && typeof node === "object" ? node.summary : null;
+  if (!summary || typeof summary !== "object") return null;
+  let newest = null;
+  for (const field of FRESHNESS_FIELDS) {
+    const raw = summary[field];
+    if (!raw) continue;
+    const ms = Date.parse(safeString(raw));
+    if (Number.isNaN(ms)) continue;
+    if (newest == null || ms > newest) newest = ms;
+  }
+  return newest;
+}
+
+/**
+ * Compute the surfaces that are stale given the freshness already recorded in
+ * the graph.
+ *
+ * @param {object} graph a `buildWorkspaceMetadataGraph` envelope
+ * @param {object} [options]
+ * @param {string|number} [options.since] only treat nodes changed at/after
+ *        this instant (ISO string or ms epoch) as seeds. Omit to seed from
+ *        every node that carries a freshness timestamp.
+ * @param {string[]} [options.seedIds] explicit seed node ids (e.g. the nodes a
+ *        just-applied PATCH touched). When given, `since` is ignored and these
+ *        ids are the change set — this is the preflight/`plan` entry point.
+ * @param {number} [options.maxNodes=500] hard cap on stale surfaces.
+ * @returns {object} `{ kind, version, since, seeds[], staleSurfaces[], byType, total, truncated, summary, warnings }`
+ */
+function deriveStaleSurfaces(graph, options = {}) {
+  const maxNodes = Number.isFinite(options.maxNodes) && options.maxNodes > 0
+    ? Math.floor(options.maxNodes)
+    : DEFAULT_MAX_NODES;
+
+  const empty = (warning) => ({
+    kind: STALE_SURFACES_KIND,
+    version: STALE_SURFACES_VERSION,
+    since: null,
+    seeds: [],
+    staleSurfaces: [],
+    byType: {},
+    total: 0,
+    truncated: false,
+    summary: "No stale surfaces computed.",
+    warnings: warning ? [warning] : []
+  });
+
+  if (!graph || typeof graph !== "object" || !Array.isArray(graph.nodes)) {
+    return empty("graph missing or malformed");
+  }
+
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+
+  // ── Resolve the change set (the seeds) ──────────────────────────────────
+  let sinceMs = null;
+  let seeds = [];
+  const explicit = Array.isArray(options.seedIds) ? options.seedIds.map(safeString).filter(Boolean) : null;
+
+  if (explicit && explicit.length) {
+    for (const id of explicit) {
+      const node = nodesById.get(id);
+      if (node) seeds.push({ node, changedAtMs: nodeFreshAt(node) });
+    }
+  } else {
+    if (options.since != null) {
+      const raw = options.since;
+      sinceMs = typeof raw === "number" ? raw : Date.parse(safeString(raw));
+      if (Number.isNaN(sinceMs)) sinceMs = null;
+    }
+    for (const node of graph.nodes) {
+      const changedAtMs = nodeFreshAt(node);
+      if (changedAtMs == null) continue;
+      if (sinceMs != null && changedAtMs < sinceMs) continue;
+      seeds.push({ node, changedAtMs });
+    }
+  }
+
+  if (!seeds.length) {
+    const out = empty();
+    out.since = sinceMs;
+    out.summary = "No recently-changed nodes — nothing is stale.";
+    return out;
+  }
+
+  // ── Union the reverse closures of every seed (reuse the spine) ──────────
+  // A downstream node is stale relative to a seed when its own last-fresh
+  // timestamp predates the seed's change (or it carries none — it cannot prove
+  // freshness, so it is reported stale honestly rather than silently fresh).
+  const staleById = new Map();
+  for (const { node: seedNode, changedAtMs } of seeds) {
+    const blast = deriveBlastRadius(graph, seedNode.id, { maxNodes });
+    for (const impacted of blast.impacted) {
+      const target = nodesById.get(impacted.id);
+      const targetFreshAt = nodeFreshAt(target);
+      const isStale = changedAtMs == null
+        ? true
+        : targetFreshAt == null || targetFreshAt < changedAtMs;
+      if (!isStale) continue;
+      const existing = staleById.get(impacted.id);
+      // Keep the nearest / most-recent reason for each stale surface.
+      if (!existing || impacted.distance < existing.distance) {
+        staleById.set(impacted.id, {
+          id: impacted.id,
+          type: impacted.type,
+          label: impacted.label,
+          metadataId: impacted.metadataId,
+          distance: impacted.distance,
+          viaRelation: impacted.viaRelation,
+          staleSinceSeed: seedNode.id,
+          lastFreshAt: targetFreshAt != null ? new Date(targetFreshAt).toISOString() : null
+        });
+      }
+    }
+  }
+
+  let staleSurfaces = Array.from(staleById.values());
+  let truncated = false;
+  if (staleSurfaces.length > maxNodes) {
+    staleSurfaces = staleSurfaces.slice(0, maxNodes);
+    truncated = true;
+  }
+
+  staleSurfaces.sort((a, b) =>
+    a.distance - b.distance ||
+    a.type.localeCompare(b.type) ||
+    a.id.localeCompare(b.id)
+  );
+
+  const byType = {};
+  for (const entry of staleSurfaces) {
+    byType[entry.type] = (byType[entry.type] || 0) + 1;
+  }
+
+  return {
+    kind: STALE_SURFACES_KIND,
+    version: STALE_SURFACES_VERSION,
+    since: sinceMs,
+    seeds: seeds.map(({ node }) => ({ id: node.id, type: node.type, label: node.label, metadataId: node.metadataId })),
+    staleSurfaces,
+    byType,
+    total: staleSurfaces.length,
+    truncated,
+    summary: summarizeStaleSurfaces(seeds, staleSurfaces, byType, truncated),
+    warnings: []
+  };
+}
+
+/**
+ * One human sentence for the inspector chip / preflight line / CLI output.
+ * Pure string assembly — never throws.
+ */
+function summarizeStaleSurfaces(seeds, staleSurfaces, byType, truncated) {
+  if (!staleSurfaces.length) {
+    return `${seeds.length} recent change(s) — no downstream surface is stale.`;
+  }
+  const parts = Object.keys(byType)
+    .sort()
+    .map((type) => `${byType[type]} ${type}`);
+  const tail = truncated ? " (truncated)" : "";
+  return `${seeds.length} recent change(s) leave ${staleSurfaces.length} surface(s) stale: ${parts.join(", ")}${tail}.`;
+}
+
+export {
+  STALE_SURFACES_KIND,
+  STALE_SURFACES_VERSION,
+  DEFAULT_MAX_NODES,
+  deriveStaleSurfaces,
+  summarizeStaleSurfaces,
+  nodeFreshAt
+};