@atlassian/chippy 0.0.0-stage → 0.0.1-beta.1

package/lib/mcp-skill/scripts/format-probe-result.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/* eslint-disable */
+
+const mode = process.argv[2] || 'text';
+let input = '';
+
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+
+process.stdin.on('end', () => {
+  const payload = JSON.parse(input);
+  if (mode === 'json') {
+    process.stdout.write(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (!payload?.ok || !payload?.result?.ok) {
+    process.stdout.write(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const result = payload.result;
+  const text = String(result.text || '');
+  if (mode === 'complexity') {
+    const lines = text.split('\n');
+    const start = lines.indexOf('complexity:');
+    const end = lines.indexOf('structure:');
+    if (start >= 0) {
+      const until = end > start ? end : lines.length;
+      process.stdout.write(lines.slice(start, until).join('\n'));
+      return;
+    }
+  }
+  process.stdout.write(text || JSON.stringify(payload, null, 2));
+});

package/lib/mcp-skill/scripts/helper-access.js

@@ -0,0 +1,144 @@
+/* eslint-disable */
+// Access control for the Chippy helper.
+//
+// The helper can run scripts in connected pages, so its command API must not
+// be reachable from arbitrary websites or other hosts. Three checks apply:
+//   1. The helper binds to loopback by default. A wider bind (for example
+//      0.0.0.0 for a remote dev environment or container) is opt-in.
+//   2. When bound to loopback, the Host header must name a loopback host. This
+//      blocks DNS-rebinding pages that resolve their own name to 127.0.0.1.
+//   3. Protected routes require the X-Chippy-Token header. CORS does not allow
+//      that header, so a cross-origin page cannot send it.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const TOKEN_HEADER = 'x-chippy-token';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+
+// Routes that pages load without credentials: health, injected bundles, and
+// the page WebSocket.
+const PUBLIC_GET_PATHS = new Set([
+  '',
+  '/health',
+  '/inject.js',
+  '/inject.mjs',
+  '/avalanche.es.js',
+  '/avalanche.iife.js',
+  '/avalanche.es.js.map',
+  '/avalanche.iife.js.map',
+  '/devtools-hook-shim.js',
+  '/api/avalanche-arm',
+  '/proxy/go',
+  '/ws',
+]);
+
+// Routes the published browser extension calls from its service worker. The
+// extension sends no token, so these stay open to extension origins and
+// non-browser clients on every bind. They list pages and arm capture; they do
+// not run page code.
+const EXTENSION_ROUTES = new Set(['GET /api/pages', 'POST /api/avalanche-arm']);
+
+function stateDirectory(env = process.env) {
+  return env.CHIPPY_STATE_DIR || path.join(os.homedir(), '.chippy');
+}
+
+function resolveTokenFile(port, env = process.env) {
+  return path.join(stateDirectory(env), `helper-${port}.token`);
+}
+
+function readHelperToken(port, env = process.env) {
+  if (env.CHIPPY_HELPER_TOKEN) return env.CHIPPY_HELPER_TOKEN;
+  try {
+    return fs.readFileSync(resolveTokenFile(port, env), 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function createHelperToken(env = process.env) {
+  return env.CHIPPY_HELPER_TOKEN || crypto.randomBytes(32).toString('hex');
+}
+
+// Call only after the server is listening, so a helper that lost the port
+// race cannot replace the running helper's token.
+function writeHelperToken(port, token, env = process.env) {
+  if (env.CHIPPY_HELPER_TOKEN) return null;
+  const file = resolveTokenFile(port, env);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${token}\n`, { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+  return file;
+}
+
+function isLoopbackBind(host) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+
+function hostnameOf(hostHeader) {
+  if (!hostHeader) return '';
+  const value = String(hostHeader).toLowerCase();
+  if (value.startsWith('[')) return value.slice(0, value.indexOf(']') + 1);
+  return value.split(':')[0];
+}
+
+function allowedHosts(env = process.env) {
+  const extra = (env.CHIPPY_HELPER_ALLOWED_HOSTS || '')
+    .split(',')
+    .map((h) => h.trim().toLowerCase())
+    .filter(Boolean);
+  return new Set([...LOOPBACK_HOSTS, ...extra]);
+}
+
+function isAllowedHost(hostHeader, env = process.env) {
+  return allowedHosts(env).has(hostnameOf(hostHeader));
+}
+
+// Returns 'public', 'extension', or 'protected'. `route` is the path after the
+// Chippy prefix, or null for proxied application paths.
+function classifyRoute(method, route) {
+  if (route === null) return 'public';
+  if (method === 'OPTIONS') return 'public';
+  if (method === 'GET' && PUBLIC_GET_PATHS.has(route)) return 'public';
+  if (EXTENSION_ROUTES.has(`${method} ${route}`)) return 'extension';
+  return 'protected';
+}
+
+function isExtensionOrigin(origin) {
+  return typeof origin === 'string' && /^(chrome|moz)-extension:\/\//.test(origin);
+}
+
+function tokensMatch(expected, received) {
+  if (typeof received !== 'string' || !expected) return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(received);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+// Returns null when the request may proceed, otherwise { status, error }.
+function authorizeRequest({ method, route, headers, token, loopback, env = process.env }) {
+  if (loopback && !isAllowedHost(headers.host, env)) {
+    return { status: 403, error: 'Host header is not a loopback host; set CHIPPY_HELPER_ALLOWED_HOSTS to allow it' };
+  }
+  const kind = classifyRoute(method, route);
+  if (kind === 'public') return null;
+  if (tokensMatch(token, headers[TOKEN_HEADER])) return null;
+  if (kind === 'extension') {
+    const origin = headers.origin;
+    if (origin === undefined || isExtensionOrigin(origin)) return null;
+  }
+  return { status: 401, error: 'Missing or invalid X-Chippy-Token header' };
+}
+
+module.exports = {
+  TOKEN_HEADER,
+  authorizeRequest,
+  classifyRoute,
+  createHelperToken,
+  isAllowedHost,
+  isLoopbackBind,
+  readHelperToken,
+  resolveTokenFile,
+  writeHelperToken,
+};

package/lib/mcp-skill/scripts/probe-annotation-channel.js

@@ -0,0 +1,116 @@
+/* eslint-disable */
+
+const DIRECT_PROBE_IDS = new Set(['1', '2']);
+
+function normalizedAnnotation(marker) {
+  return {
+    intent: marker?.intent ?? null,
+    comment: typeof marker?.comment === 'string' ? marker.comment : '',
+  };
+}
+
+function annotationChanged(previousMarker, nextMarker) {
+  const previous = normalizedAnnotation(previousMarker);
+  const next = normalizedAnnotation(nextMarker);
+  return previous.intent !== next.intent || previous.comment !== next.comment;
+}
+
+function createProbeAnnotationChannel({ maxEvents = 50, serializeMarker = (marker) => marker } = {}) {
+  const queues = new Map();
+  const waiters = new Map();
+  let sequence = 0;
+
+  function getQueue(clientId) {
+    if (!queues.has(clientId)) queues.set(clientId, []);
+    return queues.get(clientId);
+  }
+
+  function getWaiters(clientId) {
+    if (!waiters.has(clientId)) waiters.set(clientId, []);
+    return waiters.get(clientId);
+  }
+
+  function deliver(clientId, event) {
+    const waiting = getWaiters(clientId);
+    while (waiting.length) {
+      const waiter = waiting.shift();
+      if (waiter.settled) continue;
+      waiter.finish(event);
+      return;
+    }
+    const queue = getQueue(clientId);
+    queue.push(event);
+    while (queue.length > maxEvents) queue.shift();
+  }
+
+  function publish({ clientId, at, page, integration, previousSnapshot, snapshot }) {
+    const previousMarkers = previousSnapshot?.markers || {};
+    const nextMarkers = snapshot?.markers || {};
+    const directIds = Object.keys(nextMarkers).filter((id) => DIRECT_PROBE_IDS.has(id));
+    const changedProbeIds = directIds.filter((id) => annotationChanged(previousMarkers[id], nextMarkers[id]));
+    const annotatedProbeIds = directIds.filter((id) => {
+      const annotation = normalizedAnnotation(nextMarkers[id]);
+      return annotation.intent !== null || annotation.comment.length > 0;
+    });
+    const selectedProbeIds = changedProbeIds.length
+      ? changedProbeIds
+      : (annotatedProbeIds.length ? annotatedProbeIds : directIds);
+
+    const event = {
+      eventId: `probe-annotation:${++sequence}`,
+      sequence,
+      at,
+      clientId,
+      reason: 'marker-annotation-change',
+      page: page || null,
+      integration: integration || null,
+      changedProbeIds,
+      annotations: selectedProbeIds.map((probeId) => ({
+        probeId,
+        ...normalizedAnnotation(nextMarkers[probeId]),
+        marker: serializeMarker(nextMarkers[probeId]),
+      })),
+    };
+    deliver(clientId, event);
+    return event;
+  }
+
+  function wait(clientId, timeoutMs) {
+    const queue = getQueue(clientId);
+    if (queue.length) {
+      return { promise: Promise.resolve(queue.shift()), cancel() {} };
+    }
+
+    let waiter;
+    const promise = new Promise((resolve) => {
+      waiter = {
+        settled: false,
+        timer: null,
+        finish(event) {
+          if (this.settled) return;
+          this.settled = true;
+          clearTimeout(this.timer);
+          const waiting = waiters.get(clientId);
+          const index = waiting?.indexOf(this) ?? -1;
+          if (index >= 0) waiting.splice(index, 1);
+          if (waiting?.length === 0) waiters.delete(clientId);
+          resolve(event);
+        },
+      };
+      waiter.timer = setTimeout(() => waiter.finish(null), timeoutMs);
+      getWaiters(clientId).push(waiter);
+    });
+
+    return {
+      promise,
+      cancel() {
+        if (!waiter || waiter.settled) return;
+        waiter.finish(null);
+      },
+    };
+  }
+
+  return { publish, wait };
+}
+
+module.exports = { createProbeAnnotationChannel };

package/lib/mcp-skill/scripts/search-recipes.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createReadStream } = require('node:fs');
+const { createInterface } = require('node:readline');
+
+const REQUIRED_FIELDS = ['id', 'q', 'tags', 'a', 'done', 'guard', 'refs'];
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'can', 'do', 'does', 'for', 'from', 'how', 'i', 'in',
+  'is', 'it', 'my', 'of', 'on', 'or', 'the', 'this', 'to', 'use', 'what', 'when',
+  'where', 'which', 'why', 'with',
+]);
+
+function usage() {
+  process.stderr.write('Usage: chippy.sh recipes <query...> [--limit N]\n');
+}
+
+function parseArgs(argv) {
+  let limit = 5;
+  const queryParts = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--limit') {
+      const next = argv[index + 1];
+      if (!next || !/^\d+$/.test(next)) {
+        throw new Error('--limit requires an integer from 1 to 20');
+      }
+      limit = Number(next);
+      index += 1;
+      continue;
+    }
+    queryParts.push(value);
+  }
+
+  if (limit < 1 || limit > 20) {
+    throw new Error('--limit must be between 1 and 20');
+  }
+
+  const query = queryParts.join(' ').trim();
+  if (!query) {
+    throw new Error('recipes requires a search query');
+  }
+
+  return { limit, query };
+}
+
+function normalizeToken(token) {
+  let value = token.toLowerCase();
+  if (value.length > 4 && value.endsWith('ies')) value = `${value.slice(0, -3)}y`;
+  else if (value.length > 4 && value.endsWith('ing')) value = value.slice(0, -3);
+  else if (value.length > 4 && value.endsWith('ed')) value = value.slice(0, -2);
+  else if (value.length > 3 && value.endsWith('s')) value = value.slice(0, -1);
+  return value;
+}
+
+function tokenize(value) {
+  return String(value)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .map(normalizeToken)
+    .filter((token) => token.length > 1 && !STOP_WORDS.has(token));
+}
+
+function parseRecord(line, lineNumber) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+
+  const fields = {};
+  for (const part of trimmed.split(' | ')) {
+    const equals = part.indexOf('=');
+    if (equals <= 0) throw new Error(`invalid recipe field at line ${lineNumber}`);
+    fields[part.slice(0, equals)] = part.slice(equals + 1);
+  }
+
+  const missing = REQUIRED_FIELDS.filter((field) => !fields[field]);
+  if (missing.length > 0) {
+    throw new Error(`recipe at line ${lineNumber} is missing: ${missing.join(', ')}`);
+  }
+  return fields;
+}
+
+async function forEachRecipe(file, visit) {
+  const lines = createInterface({
+    input: createReadStream(file, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+  let lineNumber = 0;
+  for await (const line of lines) {
+    lineNumber += 1;
+    const record = parseRecord(line, lineNumber);
+    if (record) await visit(record);
+  }
+}
+
+function isEditDistanceOne(left, right) {
+  if (left === right || Math.abs(left.length - right.length) > 1) return false;
+  let edits = 0;
+  let leftIndex = 0;
+  let rightIndex = 0;
+  while (leftIndex < left.length && rightIndex < right.length) {
+    if (left[leftIndex] === right[rightIndex]) {
+      leftIndex += 1;
+      rightIndex += 1;
+      continue;
+    }
+    edits += 1;
+    if (edits > 1) return false;
+    if (left.length > right.length) leftIndex += 1;
+    else if (right.length > left.length) rightIndex += 1;
+    else {
+      leftIndex += 1;
+      rightIndex += 1;
+    }
+  }
+  return edits + (leftIndex < left.length || rightIndex < right.length ? 1 : 0) === 1;
+}
+
+function matchWeight(queryToken, documentToken) {
+  if (queryToken === documentToken) return 1;
+  if (
+    Math.min(queryToken.length, documentToken.length) >= 4
+    && (queryToken.startsWith(documentToken) || documentToken.startsWith(queryToken))
+  ) return 0.72;
+  if (
+    Math.min(queryToken.length, documentToken.length) >= 5
+    && isEditDistanceOne(queryToken, documentToken)
+  ) return 0.58;
+  return 0;
+}
+
+function indexedTokens(record) {
+  const weightedFields = [
+    ['id', 3],
+    ['q', 2],
+    ['tags', 3],
+    ['a', 1],
+    ['done', 1],
+    ['guard', 1],
+    ['refs', 1],
+  ];
+  const result = [];
+  for (const [field, weight] of weightedFields) {
+    for (const token of tokenize(record[field])) result.push({ token, weight });
+  }
+  return result;
+}
+
+function termFrequency(queryToken, tokens) {
+  let frequency = 0;
+  for (const { token, weight } of tokens) {
+    frequency += matchWeight(queryToken, token) * weight;
+  }
+  return frequency;
+}
+
+function insertTop(results, candidate, limit) {
+  results.push(candidate);
+  results.sort((left, right) => right.score - left.score || left.record.id.localeCompare(right.record.id));
+  if (results.length > limit) results.length = limit;
+}
+
+async function search(file, query, limit) {
+  const queryTokens = [...new Set(tokenize(query))];
+  if (queryTokens.length === 0) throw new Error('search query contains no searchable words');
+
+  let documentCount = 0;
+  let totalLength = 0;
+  const documentFrequency = new Map(queryTokens.map((token) => [token, 0]));
+
+  await forEachRecipe(file, (record) => {
+    const tokens = indexedTokens(record);
+    documentCount += 1;
+    totalLength += tokens.length;
+    for (const queryToken of queryTokens) {
+      if (termFrequency(queryToken, tokens) > 0) {
+        documentFrequency.set(queryToken, documentFrequency.get(queryToken) + 1);
+      }
+    }
+  });
+
+  if (documentCount === 0) throw new Error('recipe corpus is empty');
+  const averageLength = totalLength / documentCount;
+  const results = [];
+  const k1 = 1.2;
+  const b = 0.75;
+  const normalizedPhrase = tokenize(query).join(' ');
+
+  await forEachRecipe(file, (record) => {
+    const tokens = indexedTokens(record);
+    let score = 0;
+    for (const queryToken of queryTokens) {
+      const frequency = termFrequency(queryToken, tokens);
+      if (frequency === 0) continue;
+      const df = documentFrequency.get(queryToken);
+      const inverseDocumentFrequency = Math.log(1 + ((documentCount - df + 0.5) / (df + 0.5)));
+      const denominator = frequency + k1 * (1 - b + b * (tokens.length / averageLength));
+      score += inverseDocumentFrequency * ((frequency * (k1 + 1)) / denominator);
+    }
+
+    const searchablePhrase = tokenize(`${record.id} ${record.q} ${record.tags}`).join(' ');
+    if (normalizedPhrase.length >= 5 && searchablePhrase.includes(normalizedPhrase)) score += 1.5;
+    if (score > 0) insertTop(results, { record, score }, limit);
+  });
+
+  return results;
+}
+
+function printResults(query, results) {
+  if (results.length === 0) {
+    process.stderr.write(`No Chippy recipe matched: ${query}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  results.forEach(({ record, score }, index) => {
+    if (index > 0) process.stdout.write('\n');
+    process.stdout.write(`recipe: ${record.id}\n`);
+    process.stdout.write(`score: ${score.toFixed(3)}\n`);
+    process.stdout.write(`question: ${record.q}\n`);
+    process.stdout.write(`answer: ${record.a}\n`);
+    process.stdout.write(`done: ${record.done}\n`);
+    process.stdout.write(`guard: ${record.guard}\n`);
+    process.stdout.write(`refs: ${record.refs}\n`);
+  });
+}
+
+async function main() {
+  const [file, ...argv] = process.argv.slice(2);
+  if (!file) {
+    usage();
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const { query, limit } = parseArgs(argv);
+    printResults(query, await search(file, query, limit));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    usage();
+    process.exitCode = 1;
+  }
+}
+
+main();

package/lib/mcp-skill/snippets/README.md

@@ -0,0 +1,89 @@
+# Chippy snippets
+
+Snippets are version-controlled page-realm programs executed through `chippy.sh eval-page`. Use them for a reusable inspection question or reproducible procedure that existing commands cannot answer and that does not justify another bridge round trip.
+
+Do not add a snippet to walk React fibers from a probe or remembered fiber until `probe-parents`, `explain-component`, `inspect-fiber-parents`, and `find-fibers` have proven the command surface cannot supply the path evidence. `probe-owners` reads debug-build `_debugOwner`, not the `fiber.return` parent chain; do not use it as a production-build route.
+
+Most snippets are read-only. Active or stateful snippets declare the target they touch, the state they own, and what becomes ambiguous after execution.
+
+## Run a snippet
+
+From the Chippy skill directory:
+
+```bash
+./scripts/chippy.sh eval-snippets
+./scripts/chippy.sh eval-page <clientId> <snippet-name> [--key value ...]
+```
+
+`snippet-name` resolves to `snippets/<name>.js`. An absolute path or a path relative to the current directory also works.
+
+The shell wrapper forwards every `--key value` pair into `ctx.args`, coercing numbers and `true`/`false`. Its page-script timeout is fixed at five seconds; the wrapper does not expose a timeout override.
+
+## Choose a packaged snippet
+
+| Snippet | Kind | Use it when |
+|---|---|---|
+| `find-context-providers` | Read-only | List modern `React.createContext` providers; filter with `--name <regex>`. |
+| `find-legacy-context` | Read-only | Find legacy `childContextTypes` / `contextTypes` producers and consumers. |
+| `count-context-consumers` | Read-only | Count consumers for a Context display-name regex with `--name`. |
+| `find-prop` | Read-only | Find fibers by prop name or value when a probe revealed a clue but the owner chain is broad. |
+| `hook-metrics` | Read-only (ATL plugin) | Read the host `__ATL_REACT_METRICS`, including NaN/undefined-safe `setStateCount`. |
+| `hook-metrics-sample` | Active, bounded (ATL plugin) | Measure a labeled before/after `setStateCount` delta, optionally clicking one test-id. |
+| `hook-tracker` | Stateful instrument (ATL plugin) | Install, query, reset, or remove the `onHookUpdate` recomputation tracker. |
+| `stability-nudge` | Active stimulus | Schedule one controlled component render for the stability-render procedure. |
+
+Read [hook metrics](../references/hook-metrics.md) before using the metrics snippets. Read [stability render](../references/stability-render.md) before using `stability-nudge`.
+
+## Authoring contract
+
+Each snippet is the body of an `async function (ctx) { ... }` executed in the connected page. Return a JSON-serializable value.
+
+`ctx` provides:
+
+| Field | Contract |
+|---|---|
+| `ctx.args` | Object built from `--key value` pairs. |
+| `ctx.log` | Array of human-readable trace strings returned with the result. |
+| `ctx.helpers.getRootFibers()` | Root fibers across all React renderers on the page. |
+| `ctx.helpers.walkAll(visit, opts?)` | Walk every fiber; `opts.limit` defaults to 200,000. |
+| `ctx.helpers.findFibers(predicate, opts?)` | Return matching fibers; `opts.max` defaults to 5,000. |
+| `ctx.helpers.getDisplayName(fiber)` | Best-effort display name. |
+| `ctx.helpers.fiberInfo(fiber)` | Circular-safe view of name, source, owner, and DOM context. |
+| `ctx.helpers.ancestorFibers(fiber, max?)` | Walk the fiber return chain. |
+| `ctx.helpers.devtoolsHook()` | Raw React DevTools global hook when a documented procedure requires it. |
+
+Prefer the smallest result that answers the question. Return summaries or bounded matches, not entire fiber trees.
+
+## Result envelope
+
+`eval-page` returns this shape:
+
+```json
+{
+  "ok": true,
+  "durationMs": 42,
+  "log": ["matched 3 fibers"],
+  "result": { "count": 3 }
+}
+```
+
+The helper removes circular references, trims depth, represents functions as strings, and caps arrays at 200 items per level.
+
+## Safety and ownership
+
+- Do not commit secrets or return sensitive page data.
+- Keep read-only snippets read-only.
+- For an active snippet, document the exact target, stimulus, owned state, pollution boundary, and required cleanup or recapture.
+- Use a current composite fiber for render stimuli. Re-resolve it after state changes or navigation.
+- Use one stimulus per bounded capture. Clear or recapture before repeating it.
+- Promote version-coupled React internals to a tested bridge capability; keep procedure and target resolution in the snippet.
+
+`hook-tracker` owns `window.__CHIPPY_HOOK_TRACKER` and the host `onHookUpdate` callback until `--action uninstall`. `stability-nudge` delegates the render to the bundled `fiber-schedule-update` capability and owns no hook or prop state.
+
+## Add or revise a snippet
+
+1. Name the reusable question or procedure and choose read-only, active, or stateful behavior.
+2. Add one JavaScript file under `snippets/` with a bounded input and result contract.
+3. Document its arguments, ownership, failure shape, and cleanup in this catalog or its owning reference.
+4. Exercise it through `eval-page`, not by calling its body directly.
+5. If the snippet becomes a documented multi-step procedure, link its canonical reference from [the reference guide](../references/README.md).

package/lib/mcp-skill/snippets/count-context-consumers.js

@@ -0,0 +1,40 @@
+// Count modern Context consumers for a given Context displayName regex.
+// A consumer is any fiber whose dependencies list contains the matching context.
+// Args:
+//   --name <regex>   REQUIRED. Context displayName regex (case-insensitive).
+//   --max  <N>       cap consumer samples returned (default 100)
+
+const { walkAll, fiberInfo } = ctx.helpers;
+if (!ctx.args.name) return { error: '--name <regex> is required' };
+const nameRe = new RegExp(String(ctx.args.name), 'i');
+const max = Number(ctx.args.max) || 100;
+
+const consumers = [];
+let scanned = 0;
+let totalConsumers = 0;
+walkAll((f) => {
+  scanned++;
+  // dependencies.firstContext is a singly-linked list of ContextDependency
+  const dep = f?.dependencies;
+  if (!dep) return;
+  let cur = dep.firstContext;
+  while (cur) {
+    const c = cur.context;
+    const name = c?.displayName || c?._context?.displayName || null;
+    if (name && nameRe.test(name)) {
+      totalConsumers++;
+      if (consumers.length < max) {
+        consumers.push({
+          contextName: name,
+          consumer: fiberInfo(f),
+          owner: f._debugOwner ? fiberInfo(f._debugOwner) : null,
+        });
+      }
+      break;
+    }
+    cur = cur.next;
+  }
+});
+
+ctx.log.push('scanned fibers: ' + scanned);
+return { matchedContexts: nameRe.source, totalConsumers, sampleCount: consumers.length, consumers };