flownav 0.1.3 → 0.2.1

package/README.md

@@ -173,7 +173,7 @@ $ flownav check
 flownav install claude --mcp     # writes .claude/skills/flownav/SKILL.md and .mcp.json
 ```
 
-This installs a skill that tells the agent to query flownav before reading, renaming or deleting nodes, and registers an MCP server (`flownav serve`, stdio) exposing `flownav_scan`, `explain`, `neighbors`, `path`, `find`, `affected`, `callers`, `calls`, `uses`, `check` and `report`. The server reads `.flownav/graph.json` from the working directory (or `--graph <file>`) and reloads it when the file changes. The skill works without MCP too, as long as the agent can run shell commands.
+This installs a skill that tells the agent to query flownav before reading, renaming or deleting nodes, and registers an MCP server (`flownav serve`, stdio) exposing `flownav_scan`, `explain`, `neighbors`, `path`, `find`, `affected`, `callers`, `calls`, `uses`, `check`, `read` and `report`. The server reads `.flownav/graph.json` from the working directory (or `--graph <file>`) and reloads it when the file changes. The skill works without MCP too, as long as the agent can run shell commands.
 
 A typical rename: the agent runs `scan` to find the workflow id, then `affected "wf-orders:Normalize"`, edits the listed expressions together with the rename using whatever tool it has for editing n8n, syncs again, and runs `check` to confirm nothing dangles. flownav does not write to n8n; it tells the agent what is safe.
 
@@ -185,12 +185,47 @@ Tool replies are written for an agent to act on. If a name matches several nodes
 $ flownav explain order
 error: "order" matches 5 nodes. Do not guess: ask the user which one they mean. Then use the workflow:node form.
   1. Order intake › Order Webhook  [webhook]  use: wf-orders:Order Webhook
+       Webhook POST /orders (responseNode) · group "Intake" · starts the workflow
   2. Order intake › Is Large Order  [if]  use: wf-orders:Is Large Order
+       IF 1 condition(s) · group "Intake" · after: Normalize
   3. Order intake › Save Order  [googleSheets]  use: wf-orders:Save Order
+       googleSheets: append · group "Intake" · after: Is Large Order
   ...
 ```
 
-If a partial name matches exactly one node, it resolves but the reply starts with a `NOTE:` asking the agent to confirm with the user before changing anything. To search a family of workflows, use `flownav find --match "<part of workflow name>" --name "<part of node name>"` (`--name` searches node names only; `--text` also searches parameters and code). The installed skill tells the agent to stop and ask in these cases. How reliably an agent follows that depends on the agent.
+Each candidate carries one line of context (what the node does, its sticky-note group, and what feeds it or what it plugs into), so the agent can ask a specific question instead of "which one?". Workflow candidates show their trigger types and whether they are active. If a partial name matches exactly one node, it resolves but the reply starts with a `NOTE:` asking the agent to confirm with the user before changing anything. To search a family of workflows, use `flownav find --match "<part of workflow name>" --name "<part of node name>"` (`--name` searches node names only; `--text` also searches parameters and code). The installed skill tells the agent to stop and ask in these cases. How reliably an agent follows that depends on the agent.
+
+## Reading code in small pieces
+
+flownav normally returns structure (cards, paths, references), not code. When an agent (or you) needs to read a large Code node, `read` returns it in small, capped slices instead of the whole node:
+
+```text
+$ flownav read "Orphan Code"                 # default: an outline
+wf-orders:Orphan Code · jsCode · 3 line(s), 127 chars
+longest line: 46 chars
+functions: none found
+node references:
+  Normalize  line 1  {email}
+  Deleted Step  line 2  {x}
+next: grep for a name, or read a range with lines
+
+$ flownav read "Orphan Code" --grep normalize
+wf-orders:Orphan Code · jsCode · 3 line(s), 127 chars
+> 1: const row = $('Normalize').first().json.email;
+  2: const gone = $('Deleted Step').first().json.x;
+  3: return [{ json: { row, gone } }];
+1 of 1 matching line(s) shown
+
+$ flownav read "Orphan Code" --lines 2-3
+```
+
+- **Outline** (the default): size, the longest line, function names, and which nodes the code references, all with line numbers, so you can pick a slice without reading blindly.
+- **`--grep <pattern>`**: matching lines with context (`--context`, default 2, up to 10), overlapping windows merged, up to `--max` matches (default 20). Literal and case-insensitive by default; `--regex` and `--case` change that.
+- **`--lines 120-180`** (also `120` or `120-`): numbered lines, with a hint for the next slice. An open-ended range returns 60 lines.
+- **Long lines:** a line over 240 characters is shown windowed, and `--cols 241-480` reads inside it, which is what you need for minified or generated code.
+- **`--param`** reads another text parameter (for example an HTML field); without it, `read` uses `jsCode`, `pythonCode`, `functionCode` or `code`.
+
+Every reply is capped at about 6,000 characters whatever you ask for, and secrets in the code are redacted (key-like assignments such as `apiKey = "..."`, and token shapes such as `Bearer ...`; this is best-effort, not a guarantee). `read` takes the code from your exported files, or does one read-only `GET` of that workflow from your instance (it needs the API key in the environment variable named by your profile, `N8N_API_KEY` by default). `--from <folder>` reads from a folder of exports instead. If the workflow changed since the graph was built, the reply starts with a warning and shows the current source. The MCP tool `flownav_read` does the same and cannot be pointed at other folders.
 
 ## Seeing the graph
 
@@ -252,6 +287,9 @@ flownav path <A> <B> [--max N --kinds a,b]
 flownav find [--type --cred --text --name --resource --workflow --match --disabled --trigger]
 flownav affected <node> --rename|--delete|--schema|--behavior
 flownav callers <workflow> | calls <workflow> | uses --cred <c>
+flownav read <node> [--outline | --grep p [--regex --case --context n --max n] | --lines a-b]
+                    [--param p --cols a-b --from path]     read part of a Code node, capped and redacted
+flownav stats [--from path]           measure raw JSON tokens against flownav replies on your workflows
 flownav check [--only a,b] [--fail-on error|warn|info|none]
                                       checks: 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]
@@ -295,6 +333,7 @@ For a manual "before I touch this" step, run `flownav affected "Node" --rename`
 - `pinData` (sample execution data) is dropped on load and never stored.
 - String parameters are redacted before being kept for search: values under secret-looking keys (`apiKey`, `token`, `password`, `Authorization`, ...) and known token shapes (Bearer, `sk-...`, GitHub, Slack, AWS, JWT).
 - Credentials are recorded by id and type only.
+- `flownav read` is the one command that returns code. It redacts key-like assignments and token shapes (best-effort), caps every reply, and for live graphs makes a single read-only `GET` of the one workflow it needs.
 - Execution data is not fetched; `--executions` records only the last status per workflow.
 - `.flownav/` holds your graph and is git-ignored by this repo. Don't commit it or share the HTML views if your workflows are sensitive.
 
@@ -303,7 +342,7 @@ For a manual "before I touch this" step, run `flownav affected "Node" --rename`
 This is a back-of-the-envelope model, not a measurement of real agent sessions. Tokens are estimated as characters ÷ 4.
 
 - **n**: nodes the agent would otherwise read; **τ**: tokens per node in raw n8n JSON (assumed 300, it varies a lot: Code and HTML nodes are far heavier than a Set node); **W = n·τ**.
-- **S ≈ 1,300 tokens**: flownav's fixed overhead per session (the 11 MCP tool definitions, about 800 tokens, plus the skill, about 500).
+- **S ≈ 1,600 tokens**: flownav's fixed overhead per session (the 12 MCP tool definitions, about 1,000 tokens, plus the skill, about 550).
 - **r ≈ 100 tokens**: a typical reply. `explain` and `affected` replies are tens of tokens; a `scan` of a dozen workflows is a few hundred.
 - With prompt caching, text read once costs about 1.25× the first time and about 0.1× on each later turn. For Q questions:
   - raw: `C_raw ≈ W · (1.25 + 0.1·(Q − 1))`
@@ -316,25 +355,25 @@ Raw reading grows with the workflow; a flownav reply depends only on a node's lo
 
 | workflow size | raw tokens | 1 question | 10 questions |
 |---|---|---|---|
-| 5 nodes | 1,500 | 8% | −18% (costs more) |
-| 10 nodes | 3,000 | 54% | 41% |
-| 30 nodes | 9,000 | 85% | 80% |
-| 132 nodes | 40,000 | 97% | 96% |
-| whole instance (443 nodes) | 133,000 | 99% | 99% |
+| 5 nodes | 1,500 | −12% (costs more) | −38% (costs more) |
+| 10 nodes | 3,000 | 44% | 31% |
+| 30 nodes | 9,000 | 81% | 77% |
+| 132 nodes | 40,000 | 96% | 95% |
+| whole instance (443 nodes) | 133,000 | 99% | 98% |
 
 **Saving when the agent searches and reads only a fraction of a 132-node workflow:**
 
 | fraction read | 1 question | 10 questions |
 |---|---|---|
-| 30% | 89% | 85% |
-| 20% | 83% | 78% |
-| 10% | 66% | 56% |
+| 30% | 86% | 83% |
+| 20% | 79% | 74% |
+| 10% | 58% | 48% |
 
 What to take from it:
 
 - Below roughly 6 nodes, reading the JSON is cheaper than loading the tools. Around 10 to 30 nodes flownav saves about half to four fifths; on large workflows the saving approaches 100%.
 - Most agents search instead of reading everything, so for large workflows a realistic range is about 55 to 90%; the 96% rows are the best case.
-- τ is the main unknown. To get a real figure, measure the size of your own exports, or run the same task with and without flownav and compare the usage Claude reports, several times, since agent runs vary.
+- τ is the main unknown, and `flownav stats` measures it on your own workflows (the bundled examples come out at about 130 tokens per node, well below the 300 assumed here, because they are small and hand-written; real Code and HTML nodes are far heavier). You can also run the same task with and without flownav and compare the usage Claude reports, several times, or measure the size of your own exports, or run the same task with and without flownav and compare the usage Claude reports, several times, since agent runs vary.
 - Tokens are not the only benefit: `affected` finds `$('Name')` references in expressions and Code nodes that a skimming agent misses.
 
 ## Limitations

package/dist/cli.js

@@ -10,7 +10,9 @@ import { G } from './graph.js';
 import { installClaude } from './install.js';
 import { serve } from './mcp.js';
 import { affected, callers, calls, explain, find, neighbors, paths, uses } from './queries.js';
+import { readNode } from './read.js';
 import { report, scan } from './report.js';
+import { stats } from './stats.js';
 import { buildFromFiles, N8nApi, syncApi } from './source.js';
 import { DEFAULT_DIR, graphPath, loadGraph, loadProfiles, saveGraph, saveProfiles, writeText } from './store.js';
 import { FLOW_KINDS } from './types.js';
@@ -189,6 +191,33 @@ program
     if (failOn !== 'none' && f.some((x) => rank[x.severity] <= rank[failOn]))
         process.exitCode = 1;
 })());
+program
+    .command('read <node>')
+    .description("Read part of a node's code in small pieces: outline (default), --grep, or --lines")
+    .option('--param <name>', 'parameter to read (default: the code parameter)')
+    .option('--lines <range>', '"120-180", "120" or "120-"')
+    .option('--grep <pattern>', 'lines matching a pattern, with context')
+    .option('--regex', 'treat the grep pattern as a regular expression')
+    .option('--case', 'case-sensitive grep')
+    .option('--context <n>', 'lines around each grep match', '2')
+    .option('--max <n>', 'grep matches to show', '20')
+    .option('--outline', 'size, functions and node references with line numbers')
+    .option('--cols <range>', 'character window per line, e.g. 241-480')
+    .option('--from <path>', 'read the source from this folder of exported workflows')
+    .action((n, o) => run(async () => {
+    emit(await readNode(load(), {
+        node: n, param: o.param, lines: o.lines, grep: o.grep, regex: o.regex, caseSensitive: o.case,
+        context: Number(o.context), max: Number(o.max), outline: o.outline, cols: o.cols, from: o.from,
+        dir: dirname(opts().graph ?? graphPath()),
+    }));
+})());
+program
+    .command('stats')
+    .description('Measure raw workflow JSON size against flownav replies on your own workflows')
+    .option('--from <path>', 'read the workflows from this folder of exports')
+    .action((o) => run(async () => {
+    emit(await stats(load(), { from: o.from, dir: dirname(opts().graph ?? graphPath()) }));
+})());
 program
     .command('diagram [workflow]')
     .description('Mermaid flowchart of a workflow, everything, or --focus <node>')

package/dist/graph.js

@@ -66,7 +66,14 @@ export class G {
         const hits = exact.length ? exact : part;
         if (!hits.length)
             throw new Error(`No workflow matches "${q}". Run flownav_scan to list workflows.`);
-        const rows = hits.slice(0, 10).map((w, i) => `  ${i + 1}. ${w.name}  [id ${w.id}, ${w.nodeCount} nodes]`);
+        const rows = hits.slice(0, 10).flatMap((w, i) => {
+            const trig = [...new Set(this.nodesOf(w.id).filter((n) => n.trigger).map((n) => shortType(n.type)))];
+            const state = w.active === undefined ? '' : w.active ? ', active' : ', inactive';
+            return [
+                `  ${i + 1}. ${w.name}  [id ${w.id}, ${w.nodeCount} nodes${state}]`,
+                `       ${trig.length ? `started by: ${trig.slice(0, 4).join(', ')}` : 'no trigger of its own'}${w.errorWorkflow ? ' · has an error workflow' : ''}`,
+            ];
+        });
         if (hits.length > 10)
             rows.push(`  ... and ${hits.length - 10} more`);
         throw new Error([`"${q}" matches ${hits.length} workflows. ${ASK} Then use its id.`, ...rows,
@@ -76,8 +83,32 @@ export class G {
     resolveNode(q) {
         return this.resolveNodeEx(q).node;
     }
+    /** One line of context so the agent can tell candidates apart and ask a sharper question. */
+    contextLine(n) {
+        const bits = [n.summary];
+        if (n.group)
+            bits.push(`group "${n.group}"`);
+        if (n.disabled)
+            bits.push('disabled');
+        const names = (ids) => [...new Set(ids.map((id) => this.nodeById.get(id)?.name ?? id))];
+        const from = names(this.inE(n.id, ['main', 'capability']).map((e) => e.from));
+        const into = names(this.outE(n.id, ['capability']).map((e) => e.to));
+        if (n.trigger)
+            bits.push('starts the workflow');
+        else if (from.length)
+            bits.push(`after: ${from.slice(0, 2).join(', ')}${from.length > 2 ? ` (+${from.length - 2})` : ''}`);
+        else if (into.length)
+            bits.push(`plugs into: ${into.slice(0, 2).join(', ')}`);
+        else
+            bits.push('not connected to anything');
+        const line = bits.join(' · ');
+        return line.length > 150 ? `${line.slice(0, 149)}…` : line;
+    }
     ambiguousNodes(q, hits) {
-        const rows = hits.slice(0, 10).map((n, i) => `  ${i + 1}. ${this.g.workflows[n.wf]?.name ?? n.wf} › ${n.name}  [${shortType(n.type)}]  use: ${n.wf}:${n.name}`);
+        const rows = hits.slice(0, 10).flatMap((n, i) => [
+            `  ${i + 1}. ${this.g.workflows[n.wf]?.name ?? n.wf} › ${n.name}  [${shortType(n.type)}]  use: ${n.wf}:${n.name}`,
+            `       ${this.contextLine(n)}`,
+        ]);
         if (hits.length > 10)
             rows.push(`  ... and ${hits.length - 10} more`);
         return [`"${q}" matches ${hits.length} nodes. ${ASK} Then use the workflow:node form.`, ...rows].join('\n');

package/dist/install.js

@@ -19,6 +19,7 @@ Then query the graph; do not open workflow JSON unless the graph cannot answer.
 - \`flownav affected "<node>" --rename|--delete|--schema|--behavior\` **run before renaming or deleting a node**: references like \`$('Old Name')\` are not reliably rewritten (reportedly not inside Code nodes, and not for renames made through the API or by editing JSON), so list them first
 - \`flownav callers <workflow>\` / \`calls <workflow>\` cross-workflow links
 - \`flownav check\` fragile reads, dead refs, unreachable nodes, cycles, missing error handling
+- \`flownav read "<node>"\` read part of a Code node: start with the default outline (size, functions, node references with line numbers), then \`--grep "text"\` or \`--lines 120-180\`. Never read a whole large node at once; every reply is capped and secrets are redacted
 
 ## When the request is not specific
 

package/dist/mcp.js

@@ -1,8 +1,10 @@
 import { statSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { ALL_CHECKS, formatFindings, runChecks } from './checks.js';
 import { G } from './graph.js';
 import { affected, callers, calls, explain, find, neighbors, paths, uses } from './queries.js';
+import { readNode } from './read.js';
 import { report, scan } from './report.js';
 import { graphPath, loadGraph } from './store.js';
 import { VERSION } from './version.js';
@@ -18,6 +20,12 @@ const TOOLS = [
     { name: 'flownav_calls', description: 'What this workflow calls, plus unresolved dynamic calls.', schema: { workflow: str }, run: (g, a) => calls(g, a.workflow) },
     { name: 'flownav_uses', description: 'Nodes that use a credential (id, name or type).', schema: { credential: str }, run: (g, a) => uses(g, a.credential) },
     { name: 'flownav_check', description: `Health checks: ${ALL_CHECKS.join(', ')}. Pass only="a,b" to run some.`, schema: { only: str }, run: (g, a) => formatFindings(g, runChecks(g, a.only ? String(a.only).split(',').map((x) => x.trim()) : undefined)) },
+    {
+        name: 'flownav_read',
+        description: 'Read PART of one node\'s code (or other long text) instead of the whole node. Start with the default outline (size, functions, which nodes the code references, with line numbers), then grep for a name or read a line range. Replies are capped at about 6,000 characters and secrets are redacted. Use cols to read inside very long (minified) lines. If the reply says the workflow changed since the graph was built, ask the user to sync. If the name is ambiguous or only a partial match, ask the user which node before acting.',
+        schema: { node: str, param: str, lines: str, grep: str, regex: { type: 'boolean' }, caseSensitive: { type: 'boolean' }, context: { type: 'number' }, max: { type: 'number' }, outline: { type: 'boolean' }, cols: str },
+        run: (g, a, ctx) => readNode(g, { node: a.node, param: a.param, lines: a.lines, grep: a.grep, regex: a.regex, caseSensitive: a.caseSensitive, context: a.context, max: a.max, outline: a.outline, cols: a.cols, dir: ctx.dir }),
+    },
     { name: 'flownav_report', description: 'Full markdown workflow report.', schema: {}, run: (g) => report(g) },
 ];
 export function serve(graphFile) {
@@ -63,13 +71,9 @@ export function serve(graphFile) {
                 const tool = TOOLS.find((t) => t.name === params?.name);
                 if (!tool)
                     return void fail(-32602, `Unknown tool ${params?.name}`);
-                try {
-                    const r = tool.run(getG(), params.arguments ?? {});
-                    reply({ content: [{ type: 'text', text: typeof r === 'string' ? r : r.text }] });
-                }
-                catch (err) {
-                    reply({ isError: true, content: [{ type: 'text', text: err.message }] });
-                }
+                Promise.resolve()
+                    .then(() => tool.run(getG(), params.arguments ?? {}, { dir: dirname(file) }))
+                    .then((r) => reply({ content: [{ type: 'text', text: typeof r === 'string' ? r : r.text }] }), (err) => reply({ isError: true, content: [{ type: 'text', text: err.message }] }));
             }
             else if (id !== undefined) {
                 fail(-32601, `Method not found: ${method}`);

package/dist/read.js

@@ -0,0 +1,277 @@
+import { readFileSync } from 'node:fs';
+import { buildWorkflow } from './build.js';
+import { extractRefs } from './expressions.js';
+import { extractWorkflows, loadFiles, N8nApi } from './source.js';
+import { loadProfiles } from './store.js';
+import { redactString } from './util.js';
+/** Hard cap on what one call returns, whatever the request asks for. */
+export const MAX_CHARS = 6000;
+const DEFAULT_WIDTH = 240;
+const MAX_LINE_SCAN = 5000;
+const CODE_PARAMS = ['jsCode', 'pythonCode', 'functionCode', 'code'];
+/* ---------------- source ---------------- */
+export async function loadRaw(g, wfId, o) {
+    const info = g.g.workflows[wfId];
+    const pick = (wfs) => wfs.find((w) => w.id != null && String(w.id) === wfId) ??
+        wfs.find((w) => w.name === info.name) ??
+        (wfs.length === 1 ? wfs[0] : undefined);
+    if (o.from) {
+        const hit = pick(loadFiles(o.from).items.map((i) => i.raw));
+        if (!hit)
+            throw new Error(`Workflow "${info.name}" (${wfId}) was not found under ${o.from}.`);
+        return hit;
+    }
+    if (g.g.source.type === 'files') {
+        if (!info.file)
+            throw new Error(`The graph does not record a source file for ${wfId}. Rebuild it, or pass a folder of exports.`);
+        let wfs;
+        try {
+            wfs = extractWorkflows(JSON.parse(readFileSync(info.file, 'utf8')));
+        }
+        catch {
+            throw new Error(`Cannot read ${info.file}. Pass the folder of exports to read from.`);
+        }
+        const hit = pick(wfs);
+        if (!hit)
+            throw new Error(`Workflow "${info.name}" is not in ${info.file} any more.`);
+        delete hit.pinData;
+        return hit;
+    }
+    const profile = g.g.source.profile ? loadProfiles(o.dir)[g.g.source.profile] : undefined;
+    const keyEnv = profile?.keyEnv ?? 'N8N_API_KEY';
+    const key = process.env[keyEnv];
+    if (!key) {
+        throw new Error(`Reading code from the live instance needs the API key in the ${keyEnv} environment variable of this process (read-only GET). Set it, or read from exported files instead.`);
+    }
+    const wf = await new N8nApi(g.g.source.ref, key).get(`/workflows/${encodeURIComponent(wfId)}`);
+    delete wf.pinData;
+    return wf;
+}
+/* ---------------- parameter + redaction ---------------- */
+function getPath(obj, path) {
+    // accepts the paths this module prints, e.g. "assignments.assignments[0].value"
+    return path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean).reduce((a, k) => (a == null ? undefined : a[k]), obj);
+}
+function textParams(v, prefix = '', out = [], depth = 0) {
+    if (depth > 8 || v == null)
+        return out;
+    if (typeof v === 'string') {
+        if (v.length)
+            out.push({ path: prefix, len: v.length });
+    }
+    else if (Array.isArray(v)) {
+        v.forEach((x, i) => textParams(x, `${prefix}[${i}]`, out, depth + 1));
+    }
+    else if (typeof v === 'object') {
+        for (const [k, x] of Object.entries(v))
+            textParams(x, prefix ? `${prefix}.${k}` : k, out, depth + 1);
+    }
+    return out;
+}
+function listText(node) {
+    const rows = textParams(node.parameters).sort((a, b) => b.len - a.len).slice(0, 8);
+    return rows.length ? `Text parameters: ${rows.map((r) => `${r.path} (${r.len.toLocaleString('en-US')} chars)`).join(', ')}.` : 'It has no text parameters.';
+}
+function pickParam(node, wanted) {
+    const p = (node.parameters ?? {});
+    if (wanted) {
+        const v = getPath(p, wanted);
+        if (typeof v !== 'string')
+            throw new Error(`Parameter "${wanted}" of ${node.name} is not text. ${listText(node)}`);
+        return { name: wanted, text: v };
+    }
+    for (const k of CODE_PARAMS)
+        if (typeof p[k] === 'string')
+            return { name: k, text: p[k] };
+    throw new Error(`${node.name} has no code parameter; pass param. ${listText(node)}`);
+}
+const KEYED = /((?:api[-_]?key|token|secret|passw(?:or)?d|authorization|private[-_]?key|client[-_]?secret)["']?\s*[:=]\s*)(["'`])([^"'`\n]{6,})\2/gi;
+/** Best-effort redaction of a line of code: key-like assignments and known token shapes. */
+export function redactCode(line) {
+    return redactString(line.replace(KEYED, (_m, pre, q) => `${pre}${q}[REDACTED]${q}`));
+}
+/* ---------------- formatting ---------------- */
+function parseRange(s, what) {
+    const m = /^\s*(\d*)\s*(-?)\s*(\d*)\s*$/.exec(s ?? '');
+    if (!s || !m || (!m[1] && !m[3]))
+        throw new Error(`${what} must look like "120-180", "120" or "120-".`);
+    const a = m[1] ? Number(m[1]) : 1;
+    const b = m[2] ? (m[3] ? Number(m[3]) : undefined) : a;
+    if (a < 1 || (b !== undefined && b < a))
+        throw new Error(`${what} "${s}" is not a valid range.`);
+    return [a, b];
+}
+/** One line for display: windowed and marked when it is longer than the window. */
+function show(line, cols, focus) {
+    let start = 0;
+    let end = line.length;
+    if (cols) {
+        start = cols[0] - 1;
+        end = cols[1] ?? start + DEFAULT_WIDTH;
+    }
+    else if (line.length > DEFAULT_WIDTH) {
+        start = focus != null && focus > DEFAULT_WIDTH - 40 ? Math.max(0, focus - 80) : 0;
+        end = start + DEFAULT_WIDTH;
+    }
+    if (start >= line.length && line.length > 0)
+        return `[line has ${line.length} chars; the window starts at column ${start + 1}]`;
+    const body = line.slice(start, end);
+    return `${start > 0 ? '…' : ''}${body}${end < line.length ? `… [+${(line.length - end).toLocaleString('en-US')} chars, ${line.length.toLocaleString('en-US')} total]` : ''}`;
+}
+const lineIndexOf = (text, at) => text.slice(0, at).split('\n').length;
+function outlineOf(text, lines) {
+    const out = [];
+    const longest = lines.reduce((m, l) => Math.max(m, l.length), 0);
+    out.push(`longest line: ${longest.toLocaleString('en-US')} chars${longest > 1000 ? ' (minified or generated: use cols to read inside long lines)' : ''}`);
+    const fns = [];
+    lines.forEach((l, i) => {
+        const m = /^\s*(?:export\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/.exec(l) ??
+            /^\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/.exec(l) ??
+            /^\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?function/.exec(l) ??
+            /^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/.exec(l);
+        if (m)
+            fns.push(`L${i + 1} ${m[1]}`);
+    });
+    out.push(fns.length ? `functions (${fns.length}): ${fns.slice(0, 30).join(', ')}${fns.length > 30 ? ', …' : ''}` : 'functions: none found');
+    const ex = extractRefs(text);
+    if (ex.refs.length || ex.inferred.length) {
+        out.push('node references:');
+        for (const r of ex.refs) {
+            const ls = [...new Set(r.at.map((a) => lineIndexOf(text, a)))];
+            out.push(`  ${r.name}  line${ls.length > 1 ? 's' : ''} ${ls.slice(0, 12).join(', ')}${ls.length > 12 ? ', …' : ''}${r.fields.length ? `  {${r.fields.join(', ')}}` : ''}`);
+        }
+        if (ex.inferred.length)
+            out.push(`  via a literal name list (inferred): ${ex.inferred.join(', ')}`);
+    }
+    else {
+        out.push('node references: none');
+    }
+    if (ex.dynamic)
+        out.push(`computed-name references: ${ex.dynamic} (cannot be resolved statically)`);
+    if (ex.env.length)
+        out.push(`env vars: ${ex.env.join(', ')}`);
+    if (ex.vars.length)
+        out.push(`vars: ${ex.vars.join(', ')}`);
+    return out;
+}
+/* ---------------- main ---------------- */
+export async function readNode(g, o) {
+    const modes = [o.lines != null, o.grep != null, o.outline === true].filter(Boolean).length;
+    if (modes > 1)
+        throw new Error('Give only one of: lines, grep, outline.');
+    const { node: n, fuzzy } = g.resolveNodeEx(o.node);
+    const wf = await loadRaw(g, n.wf, o);
+    const notes = [];
+    if (fuzzy)
+        notes.push(`NOTE: "${fuzzy}" was only a partial name and matched just ${g.label(n.id)}. Confirm with the user that this is the node they mean before changing anything.`);
+    if (buildWorkflow(wf, n.wf).info.hash !== g.g.workflows[n.wf].hash) {
+        notes.push('WARNING: this workflow changed since the graph was built, so line numbers and references may not match the graph. Run flownav sync (or build) to refresh it. Showing the current source.');
+    }
+    const raw = wf.nodes?.find((x) => x.name === n.name);
+    if (!raw)
+        throw new Error(`Node "${n.name}" is no longer in the current source of ${g.wfName(n.wf)}. The graph is stale: run flownav sync (or build).`);
+    const { name: param, text } = pickParam(raw, o.param);
+    const lines = text.split(/\r?\n/);
+    const total = lines.length;
+    const safe = lines.map(redactCode);
+    const cols = o.cols ? parseRange(o.cols, 'cols') : undefined;
+    const head = `${g.label(n.id)} · ${param} · ${total.toLocaleString('en-US')} line(s), ${text.length.toLocaleString('en-US')} chars`;
+    const out = [...notes, head];
+    let used = out.join('\n').length;
+    const data = { node: n.id, param, totalLines: total, chars: text.length };
+    const push = (s) => {
+        if (used + s.length + 1 > MAX_CHARS)
+            return false;
+        out.push(s);
+        used += s.length + 1;
+        return true;
+    };
+    if (!text.length) {
+        out.push('(empty)');
+        return { text: out.join('\n'), data };
+    }
+    if (o.lines != null) {
+        const [a, b] = parseRange(o.lines, 'lines');
+        if (a > total)
+            throw new Error(`lines "${o.lines}" starts past the end: ${param} has ${total} line(s).`);
+        const end = Math.min(b ?? a + 59, total, a + 199);
+        const w = String(end).length;
+        let shown = a - 1;
+        for (let i = a; i <= end; i++) {
+            if (!push(`  ${String(i).padStart(w)}: ${show(safe[i - 1], cols)}`))
+                break;
+            shown = i;
+        }
+        const next = shown < total ? `; next: lines ${shown + 1}-${Math.min(total, shown + 60)}` : ' (end)';
+        out.push(`showing ${a}-${shown} of ${total}${shown < end ? ` (output capped at ${MAX_CHARS} chars)` : ''}${next}`);
+        Object.assign(data, { mode: 'lines', from: a, to: shown });
+        return { text: out.join('\n'), data };
+    }
+    if (o.grep != null) {
+        const pattern = o.grep;
+        if (!pattern)
+            throw new Error('grep needs a pattern.');
+        if (o.regex && pattern.length > 200)
+            throw new Error('A regex pattern may be at most 200 characters.');
+        let re;
+        try {
+            re = new RegExp(o.regex ? pattern : pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), o.caseSensitive ? '' : 'i');
+        }
+        catch (e) {
+            throw new Error(`Invalid regex: ${e.message}`);
+        }
+        const ctx = Math.min(Math.max(o.context ?? 2, 0), 10);
+        const max = Math.min(Math.max(o.max ?? 20, 1), 100);
+        const hits = [];
+        safe.forEach((l, i) => {
+            const m = re.exec(l.slice(0, MAX_LINE_SCAN));
+            if (m)
+                hits.push({ i, col: m.index });
+        });
+        if (!hits.length) {
+            out.push(`no match for ${o.regex ? 'regex ' : ''}"${pattern}"${o.caseSensitive ? '' : ' (case-insensitive)'}. Try a shorter pattern, regex=true, or outline.`);
+            Object.assign(data, { mode: 'grep', matches: 0 });
+            return { text: out.join('\n'), data };
+        }
+        const use = hits.slice(0, max);
+        const focus = new Map(use.map((h) => [h.i, h.col]));
+        const groups = [];
+        for (const h of use) {
+            const from = Math.max(0, h.i - ctx);
+            const to = Math.min(total - 1, h.i + ctx);
+            const last = groups[groups.length - 1];
+            if (last && from <= last[1] + 1)
+                last[1] = Math.max(last[1], to);
+            else
+                groups.push([from, to]);
+        }
+        const w = String(total).length;
+        let shownMatches = 0;
+        let capped = false;
+        outer: for (let gi = 0; gi < groups.length; gi++) {
+            if (gi > 0 && !push('  --')) {
+                capped = true;
+                break;
+            }
+            for (let i = groups[gi][0]; i <= groups[gi][1]; i++) {
+                const isHit = focus.has(i);
+                if (!push(`${isHit ? '>' : ' '} ${String(i + 1).padStart(w)}: ${show(safe[i], cols, focus.get(i))}`)) {
+                    capped = true;
+                    break outer;
+                }
+                if (isHit)
+                    shownMatches++;
+            }
+        }
+        out.push(`${shownMatches} of ${hits.length} matching line(s) shown${capped ? ` (output capped at ${MAX_CHARS} chars)` : ''}${hits.length > shownMatches ? '; narrow the pattern, raise max, or read a range with lines' : ''}`);
+        Object.assign(data, { mode: 'grep', matches: hits.length, shown: shownMatches });
+        return { text: out.join('\n'), data };
+    }
+    // default and explicit outline
+    for (const l of outlineOf(text, lines))
+        if (!push(l))
+            break;
+    out.push('next: grep for a name, or read a range with lines');
+    Object.assign(data, { mode: 'outline' });
+    return { text: out.join('\n'), data };
+}

package/dist/stats.js

@@ -0,0 +1,64 @@
+import { formatFindings, runChecks } from './checks.js';
+import { affected, explain } from './queries.js';
+import { loadRaw } from './read.js';
+import { scan } from './report.js';
+import { trunc } from './util.js';
+const tok = (s) => Math.round(s.length / 4);
+const fmt = (n) => n.toLocaleString('en-US');
+function median(xs) {
+    if (!xs.length)
+        return 0;
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+const pct = (small, big) => (big > 0 ? `${Math.max(0, Math.round((1 - small / big) * 100))}% fewer` : 'n/a');
+/**
+ * Measure, on your own workflows, how much an agent would read without flownav (the whole
+ * workflow JSON) against what flownav replies with. Tokens are estimated as characters / 4.
+ */
+export async function stats(g, o) {
+    const wfs = Object.values(g.g.workflows);
+    const rows = [];
+    for (const w of wfs) {
+        const raw = await loadRaw(g, w.id, o);
+        delete raw.pinData;
+        const rawTokens = tok(JSON.stringify(raw, null, 2));
+        rows.push({ id: w.id, name: w.name, nodes: w.nodeCount, rawTokens, perNode: w.nodeCount ? Math.round(rawTokens / w.nodeCount) : 0 });
+    }
+    rows.sort((a, b) => b.rawTokens - a.rawTokens);
+    const explainToks = g.g.nodes.map((n) => tok(explain(g, n.id).text));
+    const withReaders = g.g.nodes.filter((n) => g.outE(n.id, ['reads']).length);
+    const affectedToks = withReaders.map((n) => tok(affected(g, n.id, 'rename').text));
+    const scanTok = tok(scan(g).text);
+    const checkTok = tok(formatFindings(g, runChecks(g)).text);
+    const totalRaw = rows.reduce((a, r) => a + r.rawTokens, 0);
+    const totalNodes = rows.reduce((a, r) => a + r.nodes, 0);
+    const medRaw = median(rows.map((r) => r.rawTokens));
+    const medExplain = median(explainToks);
+    const medAffected = median(affectedToks);
+    const tau = totalNodes ? Math.round(totalRaw / totalNodes) : 0;
+    const w = Math.min(36, Math.max(...rows.map((r) => r.name.length), 8));
+    const L = [];
+    L.push(`${'workflow'.padEnd(w)}  ${'nodes'.padStart(5)}  ${'raw tokens'.padStart(10)}  ${'per node'.padStart(8)}`);
+    for (const r of rows)
+        L.push(`${trunc(r.name, w).padEnd(w)}  ${String(r.nodes).padStart(5)}  ${fmt(r.rawTokens).padStart(10)}  ${String(r.perNode).padStart(8)}`);
+    L.push(`${'total'.padEnd(w)}  ${String(totalNodes).padStart(5)}  ${fmt(totalRaw).padStart(10)}  ${String(tau).padStart(8)}`);
+    L.push('');
+    L.push('Cost of one question about one workflow (median):');
+    L.push(`  read the whole workflow JSON      ${fmt(medRaw).padStart(8)} tokens`);
+    L.push(`  flownav explain                   ${fmt(medExplain).padStart(8)} tokens   ${pct(medExplain, medRaw)}`);
+    L.push(`  flownav affected --rename         ${fmt(medAffected).padStart(8)} tokens   ${pct(medAffected, medRaw)}${withReaders.length ? '' : '  (no references found)'}`);
+    L.push('');
+    L.push('Whole instance:');
+    L.push(`  read every workflow               ${fmt(totalRaw).padStart(8)} tokens`);
+    L.push(`  flownav scan                      ${fmt(scanTok).padStart(8)} tokens   ${pct(scanTok, totalRaw)}`);
+    L.push(`  flownav check (all findings)      ${fmt(checkTok).padStart(8)} tokens   ${pct(checkTok, totalRaw)}`);
+    L.push('');
+    L.push(`Tokens are estimated as characters / 4 on each workflow's JSON re-printed with 2-space indentation (about ${tau} tokens per node here).`);
+    L.push('These compare against an agent that reads the whole workflow. An agent that searches first reads less, so treat the percentages as upper bounds.');
+    return {
+        text: L.join('\n'),
+        data: { workflows: rows, totalRawTokens: totalRaw, tokensPerNode: tau, median: { workflow: medRaw, explain: medExplain, affected: medAffected }, scan: scanTok, check: checkTok },
+    };
+}

package/dist/viewer.js

@@ -126,10 +126,11 @@ aside li button{width:100%;text-align:left;margin:2px 0;border-radius:6px;overfl
 <script>
 (function () {
   var D = JSON.parse(document.getElementById('data').textContent);
-  var NS = 'http://www.w3.org/2000/svg';
+  var svg = document.getElementById('svg'), vp = document.getElementById('vp'), panel = document.getElementById('panel');
+  // The page's own <svg> element already carries the SVG namespace; reuse it for new elements.
+  var NS = svg.namespaceURI;
   var NW = 176, NH = 38, COLW = 250, ROWH = 62, PAD = 36, HEAD = 34, GAP = 50;
   var LAYER = { main: 1, capability: 1, calls: 1, on_error: 1, webhook_calls: 1 };
-  var svg = document.getElementById('svg'), vp = document.getElementById('vp'), panel = document.getElementById('panel');
 
   function el(tag, attrs, parent, text) {
     var e = document.createElementNS(NS, tag);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flownav",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "See what references an n8n node before you rename it. A typed graph of your workflows with a CLI and an MCP server, so AI agents read a few lines instead of the whole workflow JSON.",
   "author": "Omer Turkenits",
   "license": "MIT",