@pipefy/pipefy-process-coder 0.1.0

package/src/workspace/docs.ts

@@ -0,0 +1,407 @@
+import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import { writeFile, exists } from '../util/fsx.ts';
+import type { Tree } from '../model/tree.ts';
+import type { Capabilities } from '../pipefy/capability.ts';
+import { registryRows } from '../apply/registry.ts';
+import type { Lock } from './lock.ts';
+import { paths } from './layout.ts';
+import { renderReferenceMd, type Reference } from '../pipefy/reference.ts';
+
+/**
+ * The generated docs that are the whole interface for whoever edits this
+ * workspace — PLAN.md §6. No agent baked into the app: the FDE pulls, edits
+ * with an agent in a terminal, and publishes. These files are what make that
+ * work unattended, regardless of which agent is reading them.
+ */
+
+const AGENTS_MD = (lock: Lock, trees: Tree[]) => {
+  const reconstructed = lock.repos.filter((r) => r.source === 'reconstructed');
+  const unknownGroups = new Set<string>();
+  for (const r of lock.repos) {
+    for (const [name, cov] of Object.entries(r.coverage)) if (cov === 'unknown') unknownGroups.add(name);
+  }
+
+  return `# Editing this Pipefy workspace
+
+This directory is a Pipefy pipe (and everything it connects to) pulled to disk as
+JSON. Edit the JSON, then let \`pipe\` validate, plan and apply it. The rules below
+are not style preferences — breaking one either corrupts a live pipe or makes the
+apply refuse.
+
+## The loop
+
+\`\`\`bash
+pipe validate          # JSON shape + referential integrity. Instant, offline.
+pipe diff              # what you changed, against the last pull
+pipe plan --dry-run    # is every change actually applicable? refuses if not
+pipe apply             # snapshot, apply, verify
+\`\`\`
+
+**\`pipe validate && pipe plan --dry-run\` must both be clean before you propose an
+apply.** Iterate against them yourself; they need no network for validate and no
+writes for plan.
+
+## Identity rules
+
+- \`id\` is **server-owned**. Never invent one, never edit one, never reuse one.
+- A **new** entity is \`"id": null\` plus \`"_new": true\`. For \`phases\`, \`fields\`,
+  \`automations\` and \`labels\` — the only four arrays that have one — also add a
+  fresh v4 \`uuid\`. Everything else is identified by its owner.
+- To **delete**, remove the object (or the whole file). Do not set a tombstone.
+- \`_\`-prefixed keys are tool metadata. Leave them alone; they are ignored by
+  every comparator and never sent to the API.
+
+## What cannot be changed at all
+
+| Edit | Why it is refused |
+| --- | --- |
+| a field's \`type_id\` | \`updatePhaseField\` has no \`type_id\`. Doing it as delete+create destroys every existing value. |
+| a field's \`phase_id\` | \`updatePhaseField\` has no \`phase_id\`. Same data loss. |
+| a phase's \`index\` (reordering) | \`createPhase\` takes an index, \`updatePhase\` does not. |
+| anything under \`_readonly/\` | no public write path exists. Read it, reason with it, don't edit it. |
+| anything under \`_non-snapshot/\` | not part of the structure payload; never written back. |
+| the start-form phase's existence, \`index\`, or \`name\` | it is a real phase at index 0; deleting or reindexing it is catastrophic, and its name is referenced by other things (the public form, automations, a client's own docs) this tool cannot check for breakage. |
+
+If a request needs one of these, say so plainly and stop — do not work around it
+with a delete and a create.
+
+## Field references
+
+Automations and conditions refer to fields by numeric id inside opaque JSON:
+\`"recipients": "%{<fieldId>}"\`, \`"field_address": "433255493"\`,
+\`"trigger_field_ids": ["433255544"]\`. \`MAPPING.md\` translates every one of those
+numbers into a label and a phase.
+
+- **Deleting a field obliges you to fix every reference to it.** \`pipe validate\`
+  fails on a dangling reference, by design.
+- Referencing a field you are creating in the same edit is fine: leave the
+  placeholder \`%{_new:<uuid>}\` and the applier substitutes the real id after the
+  field exists.
+
+## Flows reference fields too, and \`pipe validate\` does not check them
+
+If this workspace has any \`flows/\` directories, they are iPaaS flows (Advanced
+Automations) — the same entities as the pipe, pulled, diffed, planned and
+applied by the same \`pipe pull/diff/plan/apply\` commands (\`--no-flows\` opts
+out). A flow's datapills address a field by **slug**, inside opaque strings:
+\`{{step_1['output'].data.card.fields.<slug>.value}}\`.
+
+- **\`pipe validate\` never looks inside a flow.** Renaming, retyping or deleting
+  a field is checked against automations and conditions, never against flow
+  datapills — a broken reference there is silent until the flow runs. Before
+  editing a field a flow might use, grep \`flows/\` for its slug yourself.
+- A field's slug does **not** change when its label is renamed (measured;
+  \`VALIDATION.md\` §3g), so a label-only rename is safe for existing datapills.
+  Anything that changes or removes the slug is not.
+- **Adding a node to an existing flow works if the node is reachable from the
+  trigger** — some other node's \`_nextAction\`, \`_firstLoopAction\` or a
+  branch's \`_children\` must point at it, which is how the diff finds the
+  parent to send \`ADD_ACTION\` after. An orphan node nothing points to is
+  still refused, by name, rather than guessed at.
+- Enabling a flow arms it against live traffic and is refused unless you pass
+  \`--allow-flow-enable\`, the same shape as \`--allow-card-moves\`.
+- Load the \`ppc-pipefy-flow-authoring\` skill before writing or debugging a flow by
+  hand — it covers node shapes, datapill syntax and the traps that validate
+  clean and resolve nothing at runtime.
+
+## Values that come from a closed set
+
+\`REFERENCE.md\` in this workspace lists what the API accepts in every position
+where a value must come from a fixed list: each automation event's
+\`event_params\`, each action's \`action_params\`, which events and actions cannot be
+paired, and the field \`type_id\`, \`color\` and \`filter\` sets. It was read from the
+API on the last pull.
+
+**Read it before writing an automation.** The schema publishes these lists and
+then types the inputs that consume them as \`ID\` and \`String\`, so a wrong value is
+not caught by GraphQL. It reaches a runtime check and comes back as \`is invalid\`
+or \`All fields must be filled properly.\` — naming no parameter, no event, and no
+accepted value, partway through an apply.
+
+The traps are near-misses, not nonsense. \`in_phase_id\` is a real parameter that
+belongs to \`card_inbox_received_email\`; \`card_moved\` takes only \`to_phase_id\`.
+\`card_id\` is real on \`update_card_field\` and refused on \`move_single_card\`.
+
+\`pipe validate\` checks all of this offline and names the parameter, so a wrong
+value costs a second rather than a half-applied change. It is a backstop, not a
+substitute for reading the file.
+
+## Where things live
+
+\`\`\`
+pipes/<id>--<name>/
+  pipe.json                    the repo row
+  phases/NN--name.json         phase + its fields[] + jump_target_ids[] + team_member_ids[]
+  automations/<name>.json      automation + condition + field_maps + response_schemas
+  field-conditions/<name>.json condition + actions
+  labels.json  webhooks.json  public-form.json  preferences.json  relations.json
+  _readonly/   _non-snapshot/  _meta.json
+databases/<id>--<apiId>--<name>/
+  table.json                   the database row
+  phases/00--start-form.json   the database's COLUMNS live here, as fields[]
+  phases/NN--*.json            record statuses — readable, no write path
+  README.md                    what each of those files actually is
+\`\`\`
+
+Fields live **inside their phase file** — that is where they make sense and where
+you will edit them most. Ordering comes from the \`index\` value inside the file,
+never from the filename, so renumbering works without renaming anything.
+
+${
+  reconstructed.length
+    ? `## This workspace was read without snapshots
+
+${reconstructed.length} of ${lock.repos.length} repo(s) were reconstructed from the
+GraphQL and internal APIs rather than from a snapshot payload. Consequences you
+must respect:
+
+${[...unknownGroups].sort().map((g) => `- \`${g}\` is **unknown**, not empty. Do not add to it and do not conclude the pipe has none.`).join('\n')}
+
+An \`unknown\` entity group is never diffed and never applied. \`_meta.json\` in each
+repo directory records exactly what was and was not read.
+`
+    : `## This workspace was read from snapshots
+
+Every entity group came from the snapshot payload, so absence means absence.
+`
+}
+## Secrets
+
+Webhook URLs are bearer-equivalent — possession is authorization — and
+HTTP-request automations can carry live credentials in \`action_params\`. This
+workspace has a \`.gitignore\`, but do not paste these files into anything, and do
+not commit the workspace.
+
+## Runs
+
+Pass \`--report\` to any of pull, apply, dry run or verify and it writes a folder
+under \`runs/\` recording what happened:
+
+\`\`\`
+runs/index.md                         one line per run, oldest first
+runs/<when>--<kind>/report.md         what happened, readable, no credentials
+runs/<when>--<kind>/run.json          the same thing structured
+runs/<when>--<kind>/pipe.json         the payload as of the end of that run
+runs/<when>--<kind>/integrations.json webhooks, relations, cross-repo automations
+\`\`\`
+
+An apply also writes \`pipe.before.json\`, so both sides of the change sit in one
+folder. Read \`report.md\` first — it is the only file in there written for a
+human.
+
+It is off by default: a run folder holds a full copy of the pipe, credentials
+included, and one per command would grow without bound. The record an apply
+needs in order to resume is the plan file under \`.ppc/plans/\`, which is always
+written.
+
+${trees.length ? `## This workspace\n\n${trees.map((t) => `- ${t.repo['name']} (${t.meta.repoKind} ${t.repo['id']}) — ${t.phases.length} phases, ${t.phases.reduce((n, p) => n + p.fields.length, 0)} fields, ${t.automations.length} automations, read from ${t.meta.source}`).join('\n')}` : ''}
+`;
+};
+
+const MAPPING_MD = (trees: Tree[], lock: Lock) => {
+  const sections = trees.map((t) => {
+    const fields = t.phases.flatMap((p) => p.fields.map((f) => ({ f, phase: String(p['name'] ?? '') })));
+    const fieldRows = fields
+      .map(({ f, phase }) => `| \`${f['id']}\` | ${f['label']} | \`${f['slug'] ?? ''}\` | ${f['type_id']} | ${phase} |`)
+      .join('\n');
+
+    const phaseRows = t.phases
+      .map(
+        (p) =>
+          `| ${p['index']} | \`${p['id']}\` | ${p['name']}${Number(p['index']) === 0 ? ' **(start form)**' : ''} | ${
+            p.fields.length
+          } | ${p.jump_target_ids.length ? p.jump_target_ids.map((j) => `\`${j}\``).join(', ') : '—'} |`,
+      )
+      .join('\n');
+
+    const autoRows = t.automations
+      .map(
+        (a) =>
+          `| \`${a['id']}\` | ${a['name']} | ${a['event_id']} → ${a['action_id']} | ${
+            a['action_repo_id'] !== a['event_repo_id'] ? `cross-repo → \`${a['action_repo_id']}\`` : 'same repo'
+          } | ${a.condition ? 'yes' : '—'} |`,
+      )
+      .join('\n');
+
+    const connectors = fields
+      .filter(({ f }) => f['type_id'] === 'connector')
+      .map(({ f, phase }) => `| \`${f['id']}\` | ${f['label']} | ${phase} | \`${f['connected_pipe_id']}\` |`)
+      .join('\n');
+
+    return `## ${t.repo['name']} — ${t.meta.repoKind} \`${t.repo['id']}\`
+
+### Phases
+
+| index | id | name | fields | jumps to |
+| --- | --- | --- | --- | --- |
+${phaseRows}
+
+### Fields
+
+| id | label | slug | type | phase |
+| --- | --- | --- | --- | --- |
+${fieldRows}
+
+### Automations
+
+| id | name | event → action | scope | condition |
+| --- | --- | --- | --- | --- |
+${autoRows || '| — | none | | | |'}
+
+${connectors ? `### Connector fields\n\n| field id | label | phase | connected repo |\n| --- | --- | --- | --- |\n${connectors}\n` : ''}`;
+  });
+
+  /**
+   * Edges name what they point at, not just its id.
+   *
+   * `301908697` on its own tells a reader nothing — and a connector field aimed
+   * at a database means something different from one aimed at a pipe: the target
+   * has columns and records rather than phases and cards. The repo is looked up
+   * in the lock, so a target outside the workspace still shows as unknown rather
+   * than being guessed at.
+   */
+  const byId = new Map(lock.repos.map((r) => [String(r.id), r]));
+  const edgeRows = lock.edges
+    .map((e) => {
+      const to = byId.get(String(e.to));
+      const target = to ? `${to.kind} · ${to.name}` : 'not in this workspace';
+      return `| \`${e.from}\` | \`${e.to}\` | ${target} | ${e.kind} | ${e.label ?? ''} |`;
+    })
+    .join('\n');
+
+  return `# Mapping
+
+Generated on pull. This is what makes \`%{<fieldId>}\` mean "Requester email".
+
+${sections.join('\n\n')}
+
+## Connections
+
+Discovered as the union of \`pipe_relations\`, connector fields, and cross-repo
+automations — connector fields alone find edges that neither \`pipe_relations\` nor
+\`pipeMapGraph\` reports (PLAN.md §2.2).
+
+| from | to | what it is | via | label |
+| --- | --- | --- | --- | --- |
+${edgeRows || '| — | — | — | — | — |'}
+`;
+};
+
+const CAPABILITIES_MD = (caps: Capabilities | null) => {
+  const rows = registryRows()
+    .sort((a, b) => a.key.localeCompare(b.key))
+    .map(
+      (r) =>
+        `| \`${r.entity}\` | ${r.op} | ${
+          r.status === 'SUPPORTED' ? 'yes' : r.status === 'PARTIAL' ? 'partly' : '**no**'
+        } | ${r.via ? `\`${r.via}\`` : '—'} | ${r.reason ?? ''}${r.ask ? ` _(ask ${r.ask})_` : ''} |`,
+    )
+    .join('\n');
+
+  const detected = caps
+    ? `## Detected on this endpoint
+
+| Capability | Present | Consequence if absent |
+| --- | --- | --- |
+| snapshots (\`createRepoSnapshot\`) | ${caps.snapshots ? 'yes' : '**no**'} | pulls reconstruct the structure over GraphQL instead |
+| \`restoreRepoSnapshot\` | ${caps.restoreRepoSnapshot ? 'yes' : '**no**'} | no atomic rollback; a failed apply is repaired forward |
+| \`createRepoDraft\` | ${caps.createRepoDraft ? 'yes' : '**no**'} | no free rehearsal environment; plans are checked, not proven |
+| \`importRepoSnapshot\` | ${caps.importRepoSnapshot ? 'yes' : 'no'} | Route B is unavailable; writes go through the mutation compiler |
+| internal API | ${caps.internalApi} | automation detail and phase-jump editing depend on it |
+
+${caps.internalApi === 'unavailable' ? '> The internal endpoint did not answer. Automations and phase jumps are reported as **unknown** rather than empty, and any change to them is refused rather than silently skipped.\n' : ''}`
+    : '';
+
+  return `# Capabilities
+
+Generated from the live registry in \`src/apply/registry.ts\`, so what you read
+here is what the applier will actually attempt. If something says **no**, propose
+a different change rather than a workaround.
+
+${detected}
+## Write coverage
+
+| Entity | Operation | Writable | Via | Notes |
+| --- | --- | --- | --- | --- |
+${rows}
+
+## Flows (iPaaS), separately from the table above
+
+Flows compile through \`src/apply/flowops.ts\`, not the registry above — they are
+still applied by the same \`pipe apply\` (skip with \`--no-flows\`), just tracked
+here rather than in the write-coverage table.
+
+| Change | Writable | Via | Notes |
+| --- | --- | --- | --- |
+| create a flow | yes | \`createFlow\` (whole tree) | built trigger-first, then each node in execution order |
+| delete a flow | yes | \`deleteFlow\` | destructive |
+| rename a flow | yes | \`CHANGE_NAME\` | |
+| update the trigger | yes | \`UPDATE_TRIGGER\` | whole node, not a sparse patch |
+| update an action | yes | \`UPDATE_ACTION\` | whole node; a router's branches live in \`settings.branches\`, so editing them is an \`UPDATE_ACTION\` on the router — there is no \`UPDATE_BRANCH\` |
+| delete an action | yes | \`DELETE_ACTION\` | destructive |
+| add a node **to an existing flow** | yes, if reachable from the trigger | \`ADD_ACTION\` | the parent is found by scanning the authored tree for whoever's \`_nextAction\` / \`_firstLoopAction\` / \`_children\` points at the new node. An orphan node nothing points to is refused by name |
+| enable a flow | partly | \`CHANGE_STATUS\` | arms it against live traffic — refused unless \`--allow-flow-enable\`, and refused outright while any connection it uses is still a placeholder |
+| disable a flow | yes | \`CHANGE_STATUS\` | |
+| a connection the flow needs but the project lacks | yes, as a placeholder | \`createConnection\` | created disabled with a placeholder credential so the structure can still be built; reconnect it for real before enabling |
+| whole-tree replace | **refused on purpose** | — | \`IMPORT_FLOW\` exists and is never used — it re-runs an old schema migration on an already-live tree and doubles every datapill (\`{{step_1['output'].x}}\` → \`{{step_1['output']['output'].x}}\`), resolving nothing at runtime while every validator still calls it valid |
+
+After any flow write, the applier reads the flow back and diffs its datapills
+against what was sent — the only check that catches the \`IMPORT_FLOW\`-shaped
+migration bug, and the reason a flow apply is not reported successful on the
+mutation's response alone.
+
+## The three that hurt most
+
+1. **Field type changes** — routine to ask for, impossible to do without
+   destroying data. Refused.
+2. **Moving a field between phases** — same.
+3. **Reordering phases** — \`createPhase\` takes an index, \`updatePhase\` does not.
+
+These are asks 2, 3 and 4 in \`ROUTE-B-V2.md\`. Every refusal pipe emits is a data
+point for them.
+`;
+};
+
+const GITIGNORE = `# A pulled workspace contains webhook URLs (bearer-equivalent: possession is
+# authorization) and HTTP-request automation credentials. Never commit it.
+.ppc/
+*.gz
+
+# Run folders hold a full copy of the pipe (runs/*/pipe.json) and its integration
+# surface, credentials included. The report beside them is redacted and can be
+# shared by hand; the payloads cannot.
+runs/*/pipe*.json
+runs/*/integrations*.json
+
+# Uncomment to keep the structure out of git entirely.
+# pipes/
+# databases/
+# runs/
+`;
+
+export const writeDocs = async (
+  root: string,
+  lock: Lock,
+  trees: Tree[],
+  caps: Capabilities | null,
+  ref: Reference | null = null,
+) => {
+  const p = paths(root);
+  await writeFile(p.agentsMd, AGENTS_MD(lock, trees));
+  await writeFile(p.mappingMd, MAPPING_MD(trees, lock));
+  await writeFile(p.capabilitiesMd, CAPABILITIES_MD(caps));
+  await writeFile(p.referenceMd, renderReferenceMd(ref));
+  await writeFile(p.gitignore, GITIGNORE);
+
+  /**
+   * Migration cleanup: a workspace pulled before this rename has a stale
+   * `CLAUDE.md` sitting beside the new `AGENTS.md`, still telling whoever
+   * reads it to look here — remove it rather than leave a duplicate that
+   * silently goes out of date the next time this file is regenerated.
+   */
+  const staleClaudeMd = join(root, 'CLAUDE.md');
+  if (await exists(staleClaudeMd)) await rm(staleClaudeMd, { force: true });
+
+  return [p.agentsMd, p.mappingMd, p.capabilitiesMd, p.referenceMd, p.gitignore];
+};

package/src/workspace/flows.ts

@@ -0,0 +1,191 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { mkdirp, exists, writeJson, readJson } from '../util/fsx.ts';
+import { flowBaselineFile } from './layout.ts';
+import { slug } from '../util/slug.ts';
+import { canonicalString } from '../util/json.ts';
+import { unlinkFlow, linkFlow, type FlowTree } from '../codec/flow.ts';
+import type { Row } from '../model/payload.ts';
+import type { ConnectionRow, RunRow } from '../pipefy/ipaas.ts';
+
+/**
+ * The `flows/` half of a workspace.
+ *
+ * A pipe's iPaaS flows are entities of that pipe — the pipe's own webhook URLs
+ * carry their ids — so they live beside `pipes/`, read by the same pull and
+ * written by the same apply.
+ *
+ *   pipes/<id>--<name>/flows/
+ *     _meta.json                    coverage, projectId, counts, read time
+ *     connections.json              externalId, pieceName, displayName, status
+ *     pieces.json                   pieceName -> version the instance offers
+ *     _readonly/flow-runs.json      recent outcomes; never written back
+ *     <flowId>--<slug>/
+ *       flow.json                   the flow row
+ *       version.json                the version row, without the trigger
+ *       nodes/NN--<name>.json       one node per file, in execution order
+ *
+ * Coverage matters here as much as anywhere: a pipe whose iPaaS could not be
+ * reached gets `unknown`, which is never read as "this pipe has no flows".
+ */
+
+export const FLOWS_DIR = 'flows';
+
+export type FlowsMeta = {
+  coverage: 'complete' | 'unknown';
+  projectId?: string;
+  readAt: string;
+  flows?: number;
+  connections?: number;
+  pieces?: number;
+  reason?: string;
+  notes: string[];
+};
+
+export type FlowsSection = {
+  meta: FlowsMeta;
+  /** flowId → the flow, in the ordered form. A new flow has `_new` and no id. */
+  flows: FlowTree[];
+  connections: ConnectionRow[];
+  pieces: Record<string, string>;
+  runs: RunRow[];
+};
+
+/**
+ * The flows directory of ONE repo. Under the repo, not at the workspace root:
+ * a workspace can hold several pipes, each with its own iPaaS workspace, and a
+ * shared directory meant the second pipe's pull deleted the first pipe's flows.
+ */
+export const flowsRoot = (repoDir: string) => join(repoDir, FLOWS_DIR);
+
+export const flowDirName = (tree: FlowTree) => {
+  const id = tree.flow['id'] ? String(tree.flow['id']) : '_new';
+  return `${id}--${slug(String(tree.version['displayName'] ?? 'flow'))}`;
+};
+
+/** The empty section, for a pipe with no iPaaS or one that could not be read. */
+export const unknownFlows = (reason: string): FlowsSection => ({
+  meta: { coverage: 'unknown', readAt: new Date().toISOString(), reason, notes: [reason] },
+  flows: [],
+  connections: [],
+  pieces: {},
+  runs: [],
+});
+
+// ── write ───────────────────────────────────────────────────────────────────
+
+export const writeFlows = async (workspace: string, section: FlowsSection): Promise<string[]> => {
+  const root = flowsRoot(workspace);
+  /**
+   * Rewritten wholesale rather than merged: a flow deleted upstream has to
+   * disappear from the workspace too, and a leftover directory would be read as a
+   * flow the author wants created.
+   */
+  if (await exists(root)) await fs.rm(root, { recursive: true, force: true });
+  await mkdirp(join(root, '_readonly'));
+
+  const written: string[] = [];
+  const put = async (path: string, value: unknown) => {
+    await writeJson(path, value);
+    written.push(path);
+  };
+
+  await put(join(root, '_meta.json'), section.meta);
+  await put(join(root, 'connections.json'), section.connections);
+  await put(join(root, 'pieces.json'), section.pieces);
+  await put(join(root, '_readonly', 'flow-runs.json'), section.runs);
+
+  for (const tree of section.flows) {
+    const dir = join(root, flowDirName(tree));
+    await mkdirp(join(dir, 'nodes'));
+    await put(join(dir, 'flow.json'), tree.flow);
+    await put(join(dir, 'version.json'), tree.version);
+    for (const [i, node] of tree.nodes.entries()) {
+      await put(join(dir, 'nodes', `${String(i).padStart(2, '0')}--${node.name}.json`), node);
+    }
+  }
+  return written;
+};
+
+// ── read ────────────────────────────────────────────────────────────────────
+
+export const readFlows = async (workspace: string): Promise<FlowsSection | null> => {
+  const root = flowsRoot(workspace);
+  if (!(await exists(root))) return null;
+
+  const meta = (await readJson<FlowsMeta>(join(root, '_meta.json')).catch(() => null)) ?? {
+    coverage: 'unknown' as const,
+    readAt: new Date().toISOString(),
+    notes: ['flows/_meta.json is missing, so coverage is unknown'],
+  };
+  const connections = (await readJson<ConnectionRow[]>(join(root, 'connections.json')).catch(() => [])) ?? [];
+  const pieces = (await readJson<Record<string, string>>(join(root, 'pieces.json')).catch(() => ({}))) ?? {};
+  const runs =
+    (await readJson<RunRow[]>(join(root, '_readonly', 'flow-runs.json')).catch(() => [])) ?? [];
+
+  const flows: FlowTree[] = [];
+  for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    /**
+     * Only the tool's own metadata directories are skipped, not everything with a
+     * leading underscore.
+     *
+     * `flowDirName` names a flow that does not exist yet `_new--<slug>`, so a
+     * blanket `startsWith('_')` filter made an authored flow invisible to the
+     * reader that produced it — the diff reported "no changes" over a whole flow
+     * waiting to be created.
+     */
+    if (entry.name === '_readonly') continue;
+    const dir = join(root, entry.name);
+    const flow = await readJson<Row>(join(dir, 'flow.json'));
+    const version = await readJson<Row>(join(dir, 'version.json'));
+
+    const nodeDir = join(dir, 'nodes');
+    const files = (await fs.readdir(nodeDir)).filter((f) => f.endsWith('.json')).sort();
+    const nodes = [];
+    for (const f of files) {
+      const node = await readJson<Row>(join(nodeDir, f));
+      nodes.push({ ...node, name: String(node['name'] ?? ''), type: String(node['type'] ?? '') });
+    }
+    /**
+     * Order comes from the filename prefix, which is how the codec wrote it — but
+     * the trigger must be first for `linkFlow` to find the head of the chain, and
+     * a rename could put something else there.
+     */
+    const triggerAt = nodes.findIndex((n) => n.name === 'trigger');
+    if (triggerAt > 0) nodes.unshift(...nodes.splice(triggerAt, 1));
+    flows.push({ flow, version, nodes });
+  }
+
+  return { meta, flows, connections, pieces, runs };
+};
+
+/**
+ * Record what was just read as the baseline, so the next diff has a past to
+ * compare against without touching the network.
+ */
+export const writeFlowBaseline = (workspaceRoot: string, repoId: number, section: FlowsSection) =>
+  writeJson(flowBaselineFile(workspaceRoot, repoId), section);
+
+/** The recorded flow baseline, or null when this repo has never been pulled. */
+export const readFlowBaseline = async (workspaceRoot: string, repoId: number): Promise<FlowsSection | null> => {
+  try {
+    return await readJson<FlowsSection>(flowBaselineFile(workspaceRoot, repoId));
+  } catch {
+    return null;
+  }
+};
+
+/** The flow row as the API would return it, for comparison and for operations. */
+export const asApiFlow = (tree: FlowTree): Row => linkFlow(tree);
+
+/** Whether two flow trees are the same, ignoring `_` metadata differences in order. */
+export const sameFlow = (a: FlowTree, b: FlowTree) => canonicalString(linkFlow(a)) === canonicalString(linkFlow(b));
+
+export const flowIdOf = (tree: FlowTree): string | null =>
+  tree.flow['id'] ? String(tree.flow['id']) : null;
+
+export const isNewFlow = (tree: FlowTree): boolean => !flowIdOf(tree) || tree.flow['_new'] === true;
+
+/** Rebuild a tree from an API flow row, for the read path and for verification. */
+export const treeFromApi = (row: Row): FlowTree => unlinkFlow(row);