flownav 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omer Turkenits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# flownav
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed node graph for n8n workflows, so an AI agent can navigate a workflow without reading raw JSON.
+Alias command: `fnav`. Read-only against n8n.
+
+```bash
+npm install && npm run build
+node dist/cli.js build ./examples       # -> .flownav/graph.json + WORKFLOW_REPORT.md
+node dist/cli.js explain "Reply"
+node dist/cli.js affected "Normalize" --rename
+node dist/cli.js check
+```
+
+## What it models
+
+Edges point in the direction of data or control flow and carry `kind`, optional `label`, optional `fields`, and a `confidence`.
+
+| kind | meaning | confidence |
+|---|---|---|
+| `main` | connection; labels `true`/`false`, `case N` or the rule's output name, `loop`/`done`, `error` | EXPLICIT |
+| `capability` | `ai_*` sub-node (model, tool, memory) into its agent; shown as an agent card | EXPLICIT |
+| `reads` | an expression or Code node reads another node, with field names (`$('X')`, `$node["X"]`, `$items("X")`) | EXTRACTED |
+| `calls` | Execute Workflow / tool workflow into the callee's trigger (`label: tool` for agent tools) | EXTRACTED by ID, INFERRED by name |
+| `on_error` | `settings.errorWorkflow` | EXTRACTED |
+| `webhook_calls` | HTTP Request to `/webhook/<path>` matched to a Webhook node | INFERRED |
+| `responds_via` | Webhook to a reachable Respond to Webhook | EXTRACTED |
+| `uses` | node to credential (by id; no secrets) | EXPLICIT |
+| `reads_resource` / `writes_resource` / `uses_resource` | same sheet, table, channel, `$env`/`$vars` across nodes | INFERRED / EXTRACTED |
+
+In Code nodes, `$(n)` where `n` iterates a literal list (`for (const n of ["A","B"])`, `.forEach`, `const n = "A"`) yields INFERRED `reads` edges to each name. Other dynamic references (computed node names, runtime workflow IDs, embedded or URL sub-workflows) are recorded as *unresolved* and shown in the report. They are never guessed.
+Sticky notes are not nodes; the nodes inside a sticky's rectangle get its title as their group.
+
+## Commands
+
+```
+flownav build <path>                  files -> graph + report         (--out dir, --no-report)
+flownav sync [--profile p | --url u]  live n8n, incremental           (--active --tags --name --project --executions)
+flownav status [--check]              what is loaded; --check compares with the instance
+flownav profile add|list|remove       base URL + the NAME of the env var holding the key
+flownav report | scan
+flownav explain <node>
+flownav neighbors <node> [--depth N --dir in|out|both --kinds a,b]
+flownav path <A> <B> [--max N --kinds a,b]
+flownav find [--type --cred --text --resource --workflow --disabled --trigger]
+flownav affected <node> --rename|--delete|--schema|--behavior
+flownav callers <workflow> | calls <workflow> | uses --cred <c>
+flownav check [--only fragile-reads|dead-refs|cycles|unreachable|dead-ends|no-error-handler|webhook-no-respond]
+flownav view [workflow] [--match text --collapse --focus <node> --depth N --out file.html --open]   interactive offline HTML graph
+flownav diagram [workflow] [--match text --collapse --focus <node> --depth N --no-reads --dir LR|TD --out file.md]   Mermaid flowchart
+flownav diff old.json new.json
+flownav install claude [--global] [--mcp]   writes the skill (and .mcp.json entry)
+flownav serve                         MCP server on stdio
+```
+
+Global: `--graph <file>`, `--format text|json`. Nodes are addressed as `Name` or `workflow:Name` (workflow id or name); ambiguous names list their candidates. `check` exits 1 when it finds an `error`.
+
+### The rename gap
+
+n8n rewrites connections when you rename a node but not `$('Old Name')` inside other nodes' expressions or Code. `affected --rename` lists exactly those nodes and parameters, and `check` reports references to nodes that no longer exist (`dead-refs`) and reads from nodes that may not have run (`fragile-reads`).
+
+## Live n8n
+
+```bash
+export N8N_API_KEY=...                       # never written to disk or logs
+flownav profile add prod --url https://n8n.example.com
+flownav sync --profile prod --executions
+flownav status --check
+```
+
+Only `GET /api/v1/...` is ever issued (`X-N8N-API-KEY` header, cursor pagination, 250 per page). If the list response lacks `nodes`, each changed workflow is fetched by id; unchanged ones (same `updatedAt` and `versionId`) are reused from the previous graph. `pinData` is dropped on load, string parameters are redacted (secret-looking keys and token shapes) before being stored for search, and execution data is not fetched (`--executions` records only the last status per workflow).
+
+## Agents
+
+```bash
+flownav install claude --mcp     # .claude/skills/flownav/SKILL.md + .mcp.json
+```
+
+The MCP server exposes `flownav_scan`, `explain`, `neighbors`, `path`, `find`, `affected`, `callers`, `calls`, `uses`, `check`, `report`, and reloads the graph file when it changes.
+
+## Not done / assumptions to verify against your exports
+
+- n8n field names are from the n8n export format as documented in `HANDOFF.md` and were exercised on the hand-written workflows in `examples/`, not on real exports. Check Execute Workflow `workflowId` shapes, `toolWorkflow`, `errorWorkflow` and sticky `width`/`height` on your own files.
+- `GET /workflows` is assumed to return either full nodes or slim items; both paths are handled and tested against a mock server, not a real instance.
+- OBSERVED confidence (edges seen in executions) is not implemented. Fragile reads use main-path ancestry, not dominators, so a read after a Merge of both branches is treated as safe.
+- Name check: search npm and trademarks before publishing; run `npm publish --dry-run` early. Scope the name if taken (`@you/flownav`).
+
+## Development
+
+```bash
+npm test      # builds, then node --test on test/
+```

package/dist/assemble.js

@@ -0,0 +1,127 @@
+import { CROSS_KINDS } from './types.js';
+import { shortType } from './util.js';
+/** Bump whenever extraction logic changes so cached per-workflow results are not reused. */
+export const BUILDER_VERSION = 4;
+export const wfOf = (g, id) => {
+    if (id.startsWith('wf:'))
+        return id.slice(3);
+    const i = id.indexOf('::');
+    return i > 0 && g.workflows[id.slice(0, i)] ? id.slice(0, i) : undefined;
+};
+/** Recompute all cross-workflow edges (calls, on_error, webhook_calls) from node data. */
+export function link(workflows, nodes) {
+    const edges = [];
+    const unresolved = [];
+    const byName = new Map();
+    for (const w of Object.values(workflows))
+        byName.set(w.name, [...(byName.get(w.name) ?? []), w.id]);
+    const entryOf = (wf, type) => nodes.find((n) => n.wf === wf && shortType(n.type) === type)?.id;
+    const resolve = (idOrName, name) => {
+        if (idOrName && workflows[idOrName])
+            return { id: idOrName, inferred: false };
+        for (const cand of [name, idOrName]) {
+            const hit = cand ? byName.get(cand) : undefined;
+            if (hit?.length === 1)
+                return { id: hit[0], inferred: true };
+        }
+        return { inferred: false };
+    };
+    for (const n of nodes) {
+        for (const c of n.calls ?? []) {
+            if (c.external) {
+                unresolved.push({ scope: 'cross', wf: n.wf, node: n.name, kind: 'external-subworkflow', detail: `${n.name} runs a sub-workflow from "${c.external}"` });
+            }
+            else if (c.dynamic) {
+                unresolved.push({ scope: 'cross', wf: n.wf, node: n.name, kind: 'dynamic-call', detail: `${n.name} calls a workflow chosen at runtime` });
+            }
+            else {
+                const r = resolve(c.targetId, c.targetName);
+                if (!r.id) {
+                    unresolved.push({ scope: 'cross', wf: n.wf, node: n.name, kind: 'missing-workflow', detail: `${n.name} calls workflow ${c.targetId ?? c.targetName}, which is not in the graph` });
+                }
+                else {
+                    edges.push({
+                        from: n.id,
+                        to: entryOf(r.id, 'executeWorkflowTrigger') ?? `wf:${r.id}`,
+                        kind: 'calls',
+                        label: c.via === 'toolWorkflow' ? 'tool' : undefined,
+                        confidence: r.inferred ? 'INFERRED' : 'EXTRACTED',
+                    });
+                }
+            }
+        }
+    }
+    for (const w of Object.values(workflows)) {
+        if (!w.errorWorkflow)
+            continue;
+        const r = resolve(w.errorWorkflow);
+        if (!r.id) {
+            unresolved.push({ scope: 'cross', wf: w.id, kind: 'missing-workflow', detail: `error workflow ${w.errorWorkflow} is not in the graph` });
+        }
+        else {
+            edges.push({ from: `wf:${w.id}`, to: entryOf(r.id, 'errorTrigger') ?? `wf:${r.id}`, kind: 'on_error', confidence: 'EXTRACTED' });
+        }
+    }
+    // HTTP Request to /webhook/<path> matched against Webhook node paths.
+    const hooks = nodes
+        .filter((n) => n.webhook?.path)
+        .map((n) => ({
+        n,
+        re: new RegExp(`^${n.webhook.path.split('/').map((s) => (s.startsWith(':') ? '[^/]+' : s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))).join('/')}$`),
+    }));
+    for (const n of nodes) {
+        for (const url of n.httpUrls ?? []) {
+            const m = /\/webhook(-test)?\/([^\s?#"'{}]+)/.exec(url);
+            if (!m)
+                continue;
+            const path = m[2].replace(/\/+$/, '');
+            for (const h of hooks) {
+                if (h.n.wf !== n.wf && h.re.test(path)) {
+                    edges.push({ from: n.id, to: h.n.id, kind: 'webhook_calls', label: m[1] ? 'test' : undefined, confidence: 'INFERRED' });
+                }
+                else if (h.n.wf === n.wf && h.re.test(path)) {
+                    edges.push({ from: n.id, to: h.n.id, kind: 'webhook_calls', label: 'self', confidence: 'INFERRED' });
+                }
+            }
+        }
+    }
+    return { edges, unresolved };
+}
+export function assemble(results, source) {
+    const workflows = {};
+    const nodes = [];
+    const edges = [];
+    const unresolved = [];
+    for (const r of results) {
+        workflows[r.info.id] = r.info;
+        nodes.push(...r.nodes);
+        edges.push(...r.edges.filter((e) => !CROSS_KINDS.includes(e.kind)));
+        unresolved.push(...r.unresolved.filter((u) => u.scope === 'local'));
+    }
+    const cross = link(workflows, nodes);
+    edges.push(...cross.edges);
+    unresolved.push(...cross.unresolved);
+    return { version: 1, builder: BUILDER_VERSION, builtAt: new Date().toISOString(), source, workflows, nodes, edges, unresolved };
+}
+/** Split a stored graph back into per-workflow results (cross edges dropped) for incremental sync. */
+export function splitGraph(g) {
+    const owner = new Map();
+    for (const n of g.nodes)
+        owner.set(n.id, n.wf);
+    const res = new Map();
+    for (const info of Object.values(g.workflows))
+        res.set(info.id, { info, nodes: [], edges: [], unresolved: [] });
+    for (const n of g.nodes)
+        res.get(n.wf)?.nodes.push(n);
+    for (const e of g.edges) {
+        if (CROSS_KINDS.includes(e.kind))
+            continue;
+        const wf = owner.get(e.from) ?? owner.get(e.to);
+        if (wf)
+            res.get(wf)?.edges.push(e);
+    }
+    for (const u of g.unresolved)
+        if (u.scope === 'local')
+            res.get(u.wf)?.unresolved.push(u);
+    return res;
+}

package/dist/build.js

@@ -0,0 +1,344 @@
+import { expressionBodies, extractRefs } from './expressions.js';
+import { redactString, rlValue, sha, shortType, stable, trunc, walkStrings } from './util.js';
+const CODE_KEYS = new Set(['jsCode', 'pythonCode', 'functionCode', 'code']);
+const CODE_TYPES = new Set(['code', 'function', 'functionItem']);
+const TRIGGER_NAMES = new Set(['webhook', 'manualTrigger', 'start', 'cron', 'interval']);
+export function isTrigger(type) {
+    const t = shortType(type);
+    return TRIGGER_NAMES.has(t) || /trigger$/i.test(t);
+}
+/** Output labels in output-index order. Single-output nodes yield ['main']. */
+export function outputLabels(n) {
+    const t = shortType(n.type);
+    const p = (n.parameters ?? {});
+    let out;
+    switch (t) {
+        case 'if':
+            out = ['true', 'false'];
+            break;
+        case 'splitInBatches':
+            out = ['done', 'loop'];
+            break;
+        case 'compareDatasets':
+            out = ['in A only', 'same', 'different', 'in B only'];
+            break;
+        case 'switch': {
+            const rules = p.rules?.values ?? p.rules?.rules ?? [];
+            if (p.mode === 'expression') {
+                const k = Number(p.numberOutputs ?? 4);
+                out = Array.from({ length: Number.isFinite(k) ? k : 4 }, (_, i) => `case ${i}`);
+            }
+            else {
+                out = rules.map((r, i) => (typeof r?.outputKey === 'string' && r.outputKey ? r.outputKey : `case ${i}`));
+                if (!out.length)
+                    out = ['case 0'];
+            }
+            if (p.options?.fallbackOutput === 'extra')
+                out.push('fallback');
+            break;
+        }
+        default:
+            out = ['main'];
+    }
+    if (n.onError === 'continueErrorOutput')
+        out.push('error');
+    return out;
+}
+function summarize(n) {
+    const t = shortType(n.type);
+    const p = (n.parameters ?? {});
+    const s = (v) => redactString(String(v ?? ''));
+    let out;
+    switch (t) {
+        case 'webhook':
+            out = `Webhook ${p.httpMethod ?? 'GET'} /${s(p.path)}${p.responseMode ? ` (${p.responseMode})` : ''}`;
+            break;
+        case 'httpRequest':
+            out = `HTTP ${p.method ?? 'GET'} ${s(p.url)}`;
+            break;
+        case 'set': {
+            const k = p.assignments?.assignments?.length ?? p.values?.string?.length ?? 0;
+            out = `Set ${k} field(s)`;
+            break;
+        }
+        case 'code': {
+            const src = String(p.jsCode ?? p.pythonCode ?? '');
+            out = `Code (${p.language ?? 'js'}, ${src ? src.split('\n').length : 0} lines)`;
+            break;
+        }
+        case 'if':
+            out = `IF ${p.conditions?.conditions?.length ?? ''} condition(s)`.replace('  ', ' ');
+            break;
+        case 'switch':
+            out = `Switch (${outputLabels(n).length} outputs)`;
+            break;
+        case 'executeWorkflow':
+        case 'toolWorkflow':
+            out = `${t === 'toolWorkflow' ? 'Tool: ' : ''}Execute workflow ${rlValue(p.workflowId).value ?? rlValue(p.workflowId).name ?? '?'}`;
+            break;
+        case 'agent':
+            out = 'AI Agent';
+            break;
+        case 'scheduleTrigger':
+            out = 'Schedule trigger';
+            break;
+        default: {
+            const bits = [p.resource, p.operation].filter((x) => typeof x === 'string');
+            out = bits.length ? `${t}: ${bits.join(' ')}` : t;
+        }
+    }
+    return trunc(out, 110);
+}
+function callRefs(n) {
+    const t = shortType(n.type);
+    if (t !== 'executeWorkflow' && t !== 'toolWorkflow')
+        return [];
+    const p = (n.parameters ?? {});
+    const source = String(p.source ?? 'database');
+    if (source === 'parameter')
+        return [{ via: t, external: 'embedded' }];
+    if (source === 'url' || source === 'localFile')
+        return [{ via: t, external: source }];
+    const { value, name } = rlValue(p.workflowId);
+    if (!value && !name)
+        return [{ via: t, dynamic: true }];
+    if (value?.startsWith('='))
+        return [{ via: t, dynamic: true }];
+    return [{ via: t, targetId: value, targetName: name }];
+}
+const READ_OPS = new Set(['get', 'getAll', 'getMany', 'read', 'search', 'select', 'list', 'lookup', 'find']);
+const WRITE_OPS = new Set([
+    'append', 'appendOrUpdate', 'update', 'upsert', 'insert', 'delete', 'create', 'send', 'post', 'remove', 'clear', 'upload', 'replace',
+]);
+const RES_KEYS = {
+    documentId: 'doc', spreadsheetId: 'doc', sheetName: 'sheet', table: 'table', tableId: 'table', schema: 'schema',
+    channelId: 'channel', channel: 'channel', baseId: 'base', base: 'base', fileId: 'file', folderId: 'folder', databaseId: 'database',
+};
+function resources(n) {
+    const p = (n.parameters ?? {});
+    const t = shortType(n.type).replace(/Trigger$/, '');
+    const out = [];
+    for (const [k, kind] of Object.entries(RES_KEYS)) {
+        const { value } = rlValue(p[k]);
+        if (value && !value.startsWith('='))
+            out.push(`res:${t}:${kind}=${value}`);
+    }
+    return out;
+}
+function stripStickyTitle(content, x, y) {
+    const line = content.split('\n').map((l) => l.replace(/^[#*\s_>-]+|[*_\s]+$/g, '')).find(Boolean);
+    return trunc(line || `group@${x},${y}`, 60);
+}
+export function buildWorkflow(raw, id, file) {
+    const all = (raw.nodes ?? []).filter((n) => n && typeof n.name === 'string' && typeof n.type === 'string');
+    const stickies = all.filter((n) => shortType(n.type) === 'stickyNote');
+    const stickyNames = new Set(stickies.map((n) => n.name));
+    const real = all.filter((n) => shortType(n.type) !== 'stickyNote');
+    const byName = new Map(real.map((n) => [n.name, n]));
+    const nid = (name) => `${id}::${name}`;
+    // Groups from sticky-note rectangles (smallest containing sticky wins).
+    const rects = stickies
+        .filter((s) => Array.isArray(s.position))
+        .map((s) => {
+        const p = (s.parameters ?? {});
+        const [x, y] = s.position;
+        const w = Number(p.width ?? 240);
+        const h = Number(p.height ?? 160);
+        return { x, y, w, h, name: stripStickyTitle(String(p.content ?? ''), x, y) };
+    });
+    const groups = new Map();
+    const groupOf = (n) => {
+        if (!Array.isArray(n.position))
+            return undefined;
+        const cx = n.position[0] + 50;
+        const cy = n.position[1] + 50;
+        const hit = rects
+            .filter((r) => cx >= r.x && cx <= r.x + r.w && cy >= r.y && cy <= r.y + r.h)
+            .sort((a, b) => a.w * a.h - b.w * b.h)[0];
+        return hit?.name;
+    };
+    const edges = [];
+    const unresolved = [];
+    const nodes = [];
+    for (const n of real) {
+        const outputs = outputLabels(n);
+        const credentials = Object.entries(n.credentials ?? {}).map(([type, c]) => ({
+            type, id: String(c?.id ?? c?.name ?? type), name: c?.name,
+        }));
+        const texts = [];
+        walkStrings(n.parameters, (s) => texts.push(s));
+        const p = (n.parameters ?? {});
+        const t = shortType(n.type);
+        const urls = t === 'httpRequest' && typeof p.url === 'string' ? [redactString(p.url)] : undefined;
+        const group = groupOf(n);
+        if (group)
+            groups.set(group, [...(groups.get(group) ?? []), n.name]);
+        const calls = callRefs(n);
+        const node = {
+            id: nid(n.name),
+            wf: id,
+            name: n.name,
+            type: n.type,
+            typeVersion: n.typeVersion,
+            summary: summarize(n),
+            disabled: n.disabled === true,
+            trigger: isTrigger(n.type),
+            outputs,
+            credentials,
+            group,
+            hash: sha(stable({ t: n.type, v: n.typeVersion, p: n.parameters, c: credentials.map((c) => c.id), d: n.disabled, e: n.onError })),
+            text: trunc(texts.join(' | '), 3000),
+            onError: n.onError,
+            httpUrls: urls,
+            calls: calls.length ? calls : undefined,
+        };
+        if (t === 'webhook') {
+            node.webhook = {
+                path: String(p.path ?? '').replace(/^\/+|\/+$/g, ''),
+                method: p.httpMethod ? String(p.httpMethod) : undefined,
+                responseMode: p.responseMode ? String(p.responseMode) : undefined,
+            };
+        }
+        nodes.push(node);
+        for (const c of credentials) {
+            edges.push({ from: node.id, to: `cred:${c.id}`, kind: 'uses', label: c.type, confidence: 'EXPLICIT' });
+        }
+        const op = typeof p.operation === 'string' ? p.operation : '';
+        for (const r of resources(n)) {
+            if (READ_OPS.has(op))
+                edges.push({ from: r, to: node.id, kind: 'reads_resource', label: op, confidence: 'INFERRED' });
+            else if (WRITE_OPS.has(op))
+                edges.push({ from: node.id, to: r, kind: 'writes_resource', label: op, confidence: 'INFERRED' });
+            else
+                edges.push({ from: node.id, to: r, kind: 'uses_resource', label: op || undefined, confidence: 'INFERRED' });
+        }
+    }
+    // Connections -> main / capability edges.
+    const labelFor = (src, oi) => {
+        const labels = outputLabels(src);
+        if (labels.length > 1)
+            return labels[oi] ?? `output ${oi}`;
+        return oi > 0 ? `output ${oi}` : undefined;
+    };
+    for (const [srcName, byType] of Object.entries(raw.connections ?? {})) {
+        if (stickyNames.has(srcName))
+            continue;
+        for (const [ctype, outs] of Object.entries(byType ?? {})) {
+            (outs ?? []).forEach((targets, oi) => {
+                for (const t of targets ?? []) {
+                    if (!t?.node || stickyNames.has(t.node))
+                        continue;
+                    const src = byName.get(srcName);
+                    if (!src || !byName.has(t.node)) {
+                        unresolved.push({ scope: 'local', wf: id, node: srcName, kind: 'dead-connection', detail: `${srcName} -> ${t.node}: node does not exist` });
+                        continue;
+                    }
+                    edges.push({
+                        from: nid(srcName),
+                        to: nid(t.node),
+                        kind: ctype === 'main' ? 'main' : 'capability',
+                        label: ctype === 'main' ? labelFor(src, oi) : ctype,
+                        confidence: 'EXPLICIT',
+                        outputIndex: oi,
+                        inputIndex: t.index ?? 0,
+                    });
+                }
+            });
+        }
+    }
+    // Expression / code references -> reads edges (source -> reader).
+    for (const n of real) {
+        const isCodeNode = CODE_TYPES.has(shortType(n.type));
+        const acc = new Map();
+        const inf = new Map();
+        const envs = new Set();
+        let dynamic = 0;
+        walkStrings(n.parameters, (s, path, key) => {
+            let body;
+            // Only {{ }} blocks are expressions; the rest of an "=" string is literal text
+            // (e.g. an HTML page whose browser JS contains $('form')).
+            if (s.startsWith('='))
+                body = expressionBodies(s);
+            else if (isCodeNode && CODE_KEYS.has(key))
+                body = s;
+            if (!body)
+                return;
+            const ex = extractRefs(body);
+            dynamic += ex.dynamic;
+            ex.env.forEach((e) => envs.add(`res:env:${e}`));
+            ex.vars.forEach((e) => envs.add(`res:var:${e}`));
+            for (const name of ex.inferred)
+                inf.set(name, new Set([...(inf.get(name) ?? []), path]));
+            for (const r of ex.refs) {
+                const a = acc.get(r.name) ?? { fields: new Set(), params: new Set() };
+                r.fields.forEach((f) => a.fields.add(f));
+                a.params.add(path);
+                acc.set(r.name, a);
+            }
+        });
+        for (const [name, a] of acc) {
+            if (name === n.name || stickyNames.has(name))
+                continue;
+            if (!byName.has(name)) {
+                unresolved.push({ scope: 'local', wf: id, node: n.name, kind: 'dead-ref', detail: `${n.name} reads "${name}", which does not exist` });
+                continue;
+            }
+            edges.push({
+                from: nid(name), to: nid(n.name), kind: 'reads', confidence: 'EXTRACTED',
+                fields: [...a.fields].sort(), params: [...a.params].sort(),
+            });
+        }
+        // Names reached via a loop variable over a literal list: real dependencies, but only INFERRED.
+        for (const [name, params] of inf) {
+            if (acc.has(name) || name === n.name || stickyNames.has(name))
+                continue;
+            if (!byName.has(name)) {
+                unresolved.push({ scope: 'local', wf: id, node: n.name, kind: 'maybe-dead-ref', detail: `${n.name} may read "${name}" (from a literal list), which does not exist` });
+                continue;
+            }
+            edges.push({ from: nid(name), to: nid(n.name), kind: 'reads', confidence: 'INFERRED', fields: [], params: [...params].sort() });
+        }
+        for (const e of envs)
+            edges.push({ from: e, to: nid(n.name), kind: 'reads_resource', label: 'env', confidence: 'EXTRACTED' });
+        if (dynamic) {
+            unresolved.push({ scope: 'local', wf: id, node: n.name, kind: 'dynamic-ref', detail: `${n.name} has ${dynamic} node reference(s) with a computed name` });
+        }
+    }
+    // Webhook -> Respond to Webhook (reachability over main).
+    const out = new Map();
+    for (const e of edges)
+        if (e.kind === 'main')
+            out.set(e.from, [...(out.get(e.from) ?? []), e.to]);
+    for (const w of nodes.filter((x) => x.webhook)) {
+        const seen = new Set([w.id]);
+        const queue = [w.id];
+        while (queue.length) {
+            const cur = queue.shift();
+            for (const nx of out.get(cur) ?? [])
+                if (!seen.has(nx)) {
+                    seen.add(nx);
+                    queue.push(nx);
+                }
+        }
+        for (const nd of nodes) {
+            if (seen.has(nd.id) && shortType(nd.type) === 'respondToWebhook') {
+                edges.push({ from: w.id, to: nd.id, kind: 'responds_via', confidence: 'EXTRACTED' });
+            }
+        }
+    }
+    const errWf = raw.settings?.errorWorkflow;
+    const info = {
+        id,
+        name: raw.name || id,
+        active: typeof raw.active === 'boolean' ? raw.active : undefined,
+        updatedAt: raw.updatedAt,
+        versionId: raw.versionId,
+        tags: (raw.tags ?? []).map((t) => (typeof t === 'string' ? t : String(t?.name ?? ''))).filter(Boolean),
+        file,
+        errorWorkflow: errWf != null && String(errWf) && String(errWf) !== 'DEFAULT' ? String(errWf) : undefined,
+        nodeCount: real.length,
+        hash: sha(stable({ n: nodes.map((x) => x.hash).sort(), c: raw.connections ?? {} })),
+        groups: [...groups].map(([name, ns]) => ({ name, nodes: ns })),
+    };
+    return { info, nodes, edges, unresolved };
+}