@growthub/cli 0.14.8 → 0.14.9

package/assets/worker-kits/growthub-custom-workspace-starter-v1/SKILL.md

@@ -39,6 +39,27 @@ mcpTools: []
 
 The **Workspace** is the top-level Growthub Local product object. This kit is the official starter that bootstraps every governed Workspace; everything else (worker kits, templates, workflows, hosted agents, source imports) is an input to a Workspace.
 
+## Your operating role (read first)
+
+**If you are an agent reading this, you are the operating layer.** A human gave you an outcome; you operate this governed Workspace on their behalf. When the requester is a super admin or workspace admin, you can act as the super-admin orchestrator inside the governed boundary; when the requester is a regular user, you still do the orchestration work, but approval, review, rollback, and authority stay with the workspace/super-admin surfaces. You are not editing files and hoping tests catch mistakes — you are operating a live domain model where the platform rejects invalid reality before it lands and remembers everything that does. The chat you are in *is* the user's steering surface; the no-code Workspace is the control and audit plane.
+
+**The human is usually non-technical, and asks for a business outcome — not workspace mechanics.** They will not mention the Data Model, metadata graph, routes, validators, the PATCH boundary, or the run console — those are the control plane and proof layer that exist so you can operate safely and the super admin can inspect everything. They ask in plain language: *research a customer avatar, run market/competitor research, generate this week's content batch, script and brief the next campaign, pull the latest campaign performance, update the client report, build an MRR-by-plan dashboard, run the revenue workflow, iterate on a feature, find what broke.* Your job is to translate that outcome into governed operations over **what already exists** in this Workspace (prebuilt workflows, objects, and procedures), execute it, and deliver the result — outputs saved, synced, inspectable, and governed. This **private repository is the customer's durable operating environment**: their kit, objects, workflows, procedures, rules, source records, docs, receipts, run history, and governance boundaries all live here; your session is just the operator entering that universe.
+
+The completion bar is the user's real-world outcome, not a partial proposal or a hidden local artifact. Continue the governed loop until the workspace has objective proof: the relevant workflow ran or object changed, output rows/ledgers reflect the count and state, durable storage or source records hold the deliverables, receipts/run ids explain what happened, and any human-review state remains explicit. Do not hard-code one client's workflow as the pattern; swap the client, rows, registries, brand constraints, storage prefix, dashboard, and quality criteria while keeping the same governed causation loop.
+
+Your loop, every time:
+
+1. **Inherit state** — read the `workspace:agent-outcomes` receipt stream (`GET /api/workspace/agent-outcomes`) and `.growthub-fork/project.md` to see what the last agent did; continue from `nextActions` / `rollbackRef`, don't redo work.
+2. **Check what exists** — a scheduled job, external API, data view, or multi-agent workflow is almost always already a governed object. Prefer operating an existing object over writing code.
+3. **Act only through governed routes** — `PATCH /api/workspace` (config) and `POST /api/workspace/sandbox-run` (execution); drafts via `workflow/publish`; proposals via `helper/apply`. There is no third path.
+4. **Let the validator correct you** — preflight, read the rejection reason, repair, retry. Rejections are navigation, not failure.
+5. **Persist the outcome** — count only connected, durable outputs; save accepted artifacts to the governed ledger/storage surface; keep generated binaries and secrets out of git.
+6. **Leave proof** — every governed action emits a secret-redacted receipt. The human does not need the mechanics; the super admin inspects all of it after the fact (Workspace Map, Run Console, outcome cockpit).
+
+**Three roles:** the human states outcomes → you (the agent) operate → the workspace admin/super admin governs and audits. The mechanics of the boundary are in [`skills/governed-workspace-mutation/SKILL.md`](./skills/governed-workspace-mutation/SKILL.md) — read it before any mutation.
+
+> **For the human operator:** you do not have to operate this Workspace yourself. Tell an agent what you want; it operates the Workspace through governed routes; you (or your admin) inspect every change with full proof and rollback. The no-code Builder is the governed substrate and the audit surface — not a tool you must personally drive.
+
 Every Growthub governed Workspace is materialised from this kit. The kit ships the `.growthub-fork/` contract (identity, policy, trace, optional authority), the `apps/workspace` no-code Workspace Builder, the validated `growthub.config.json` V1 contract, plus the six primitive layers Claude/Cursor/Codex agents operate against:
 
 1. **`SKILL.md`** — this file. Discovery entry + routing menu. Always loaded first; the full operator runbook (`skills.md`) is disclosed progressively when work begins.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/README.md

@@ -18,7 +18,7 @@ It intentionally depends on adapter contracts:
 - `NANGO_ENVIRONMENT` (default `dev`)
 - `NANGO_MODE` (`cloud` | `self-hosted`, default `cloud`)
 
-The Growthub local-first operator shell remains at `../../studio`.
+This `apps/workspace` app is the only bundled app surface; the legacy `studio/` Vite shell has been removed. It is the governed control plane and audit surface — non-technical users do not operate it directly; an agent operates the Workspace on their behalf through the governed routes (see the workspace `SKILL.md` operating-role contract), while super admins use this app for inspection, proof, and governance.
 
 Settings exposes two universal integration lanes:
 

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/kit.json

@@ -107,6 +107,7 @@
     "apps/workspace/lib/workspace-metadata-store.js",
     "apps/workspace/lib/workspace-metadata-graph.js",
     "apps/workspace/lib/workspace-metadata-selectors.js",
+    "apps/workspace/lib/workspace-metadata-impact.js",
     "apps/workspace/app/api/workspace/metadata-graph/route.js",
     "apps/workspace/app/api/workspace/swarm-condition/route.js",
     "apps/workspace/app/data-model/components/WorkspaceGraphInspectorPanel.jsx",

package/assets/worker-kits/growthub-custom-workspace-starter-v1/skills/governed-workspace-mutation/SKILL.md

@@ -161,6 +161,17 @@ Every mutation lane emits the **same canonical receipt** (`@growthub/api-contrac
 
 **First-session continuation:** before acting, read the stream. Cite `receiptId`s, continue from `nextActions`, and inspect `rollbackRef` (previous version + delta index for publishes; sourceId for runs) before redoing anyone's work. Rejections come with `repairPlan[]` — follow it instead of retrying variations.
 
+**Outcome completion:** for regular user work, do not stop at "proposal created" or "run attempted" when the requested business outcome requires deliverables. The completion proof must live in governed state: successful run ids or source ids, connected output rows, durable storage/reference paths where applicable, review status, and a concise documentation/receipt trail. Failed or partial rows stay as evidence, but they do not count as delivered outputs. Human-review states remain explicit; an agent can execute and persist, but it does not silently approve or launch work that requires workspace-admin or super-admin judgment.
+
+## Intelligence layer — graph + blast radius (read-only)
+
+After a mutation lands, the platform **understands** it. Two read-only, secret-free surfaces:
+
+- **World model** — `GET /api/workspace/metadata-graph` projects the live config + source-record sidecar into a typed node/edge graph (`buildWorkspaceMetadataStore → buildWorkspaceMetadataGraph`, `lib/workspace-metadata-graph.js`); the Workspace Map (`/workspace-map`) renders the same graph. Every governed object becomes nodes; every dependency a deterministic edge (`bindsToObject`, `usesField`, `containsWidget`, `readsObject`/`writesObject`, `materializes`, …). A landed mutation expands this graph — the workspace knows more about itself than before.
+- **Causal impact** — the graph ships single-hop `findDependents(graph, nodeId)`; the transitive closure (the real blast radius) is `deriveBlastRadius(graph, nodeId)` in `lib/workspace-metadata-impact.js` — a deterministic, cycle-safe BFS of incoming edges returning every reachable dependent with hop distance and via-relation. This is the difference between *"what directly uses this field?"* (catalog) and *"if this field changes, which widgets, dashboards, and delivered workspace kits go stale?"* (intelligence). Verified live: editing `customers.mrr` → widget (`usesField`) → dashboard (`containsWidget`) → workerKit (`materializes`). Conceptual map: `docs/OPERATING_THE_GOVERNED_UNIVERSE_V1.md` in the source repo.
+
+Both are derived projections — they own no state and mutate nothing. Use them to size a change *before* you PATCH (pair with `patch/preflight`) and to explain what an accepted mutation affects.
+
 ## Applications as governed entities (Control Plane V1)
 
 Applications are first-class governed objects, not loose files. The source of truth is the `workspace-app-registry` Data Model object (objectType `"app-surface"`, preset ships in the Data Model) — one row per application, referencing its governed parts by id: `dashboardIds`, `workflowRefs` (`objectId:RowName`), `dataSourceIds`, `registryIds`. Rows mutate through the normal PATCH lane (policy + receipts apply).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthub/cli",
-  "version": "0.14.8",
+  "version": "0.14.9",
   "description": "CLI control plane for Growthub Local and Agent Workspace as Code: export, fork, inspect, operate, sync, and optionally activate governed AI workspaces.",
   "type": "module",
   "bin": {