@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/pipefy/reference.js

@@ -0,0 +1,172 @@
+import { debug } from "../util/log.js";
+/**
+ * The closed sets — every place an authored value must come from a fixed list.
+ *
+ * This exists because of a structural gap, not a convenience. The schema
+ * publishes the lists:
+ *
+ *     AutomationsEvents   10 values   card_moved, field_updated, …
+ *     AutomationsActions  15 values   move_single_card, update_card_field, …
+ *     FieldTypeId         24 values   short_text, connector, …
+ *
+ * and then types the input fields that consume them as `ID` and `String`:
+ *
+ *     CreateAutomationInput.event_id    ID
+ *     CreateAutomationInput.action_id   ID
+ *     CreatePhaseFieldInput.type_id     String
+ *
+ * So GraphQL validates none of them. A wrong value passes query validation,
+ * reaches a runtime check, and comes back as the two words `is invalid` — no
+ * parameter name, no field name, no list of what would have been accepted. The
+ * list was always public; nothing was consulting it.
+ *
+ * Two consumers, and the split matters:
+ *
+ *  - `pipe validate`, `plan` and `apply` read the cached copy and refuse
+ *    offline, naming the value and what belongs there.
+ *  - `REFERENCE.md` puts the same lists in the workspace, so whoever is editing
+ *    the JSON — a person or an agent — reads what the API accepts instead of
+ *    guessing and waiting for `is invalid`.
+ *
+ * Read once per pull, cached in `.ppc/reference.json`. Never assumed: an
+ * absent reference means the checks are skipped, not that a value is wrong.
+ */
+/** Enums whose values get authored into workspace JSON by hand. */
+const TRACKED_ENUMS = [
+    'FieldTypeId',
+    'AutomationsEvents',
+    'AutomationsActions',
+    'Colors',
+    'FieldConditionFilter',
+    'AutomationHttpAuthentication',
+    'HttpRequestMethodTypeGQLEnum',
+    'HttpRequestAddAuthenticationTo',
+    'UpdateFieldValuesOperators',
+    'DistributeAssignmentAutomationStrategyGQLEnum',
+    'CardTypeEnum',
+];
+const ENUMS_QUERY = `query ClosedSets {
+  __schema { types { name kind enumValues { name } } }
+}`;
+const CATALOGUE_QUERY = `query AutomationCatalogue($repoId: ID!) {
+  automationEvents { id acceptedParameters actionsBlacklist }
+  automationActions(repoId: $repoId) { id acceptedParameters eventsBlacklist }
+}`;
+/**
+ * Read every closed set for one pipe.
+ *
+ * Returns null rather than throwing: a token that cannot introspect, or a pipe
+ * whose action catalogue is refused, must degrade to "no reference" — which
+ * skips the checks — and never to a guess that would report valid work as broken.
+ */
+export const readReference = async (client, repoId) => {
+    try {
+        const [schema, cat] = await Promise.all([
+            client.raw(ENUMS_QUERY),
+            client.raw(CATALOGUE_QUERY, { repoId: String(repoId) }),
+        ]);
+        const byName = new Map((schema?.__schema?.types ?? [])
+            .filter((t) => t.kind === 'ENUM')
+            .map((t) => [t.name, (t.enumValues ?? []).map((v) => v.name)]));
+        const enums = {};
+        for (const name of TRACKED_ENUMS) {
+            const values = byName.get(name);
+            /**
+             * An enum the endpoint no longer publishes is omitted, not recorded empty.
+             * An empty list would read as "nothing is valid here" and refuse every
+             * value in that position.
+             */
+            if (values?.length)
+                enums[name] = values;
+        }
+        const ref = {
+            readAt: new Date().toISOString(),
+            repoId: String(repoId),
+            enums,
+            events: (cat?.automationEvents ?? []).map((e) => ({
+                id: e.id,
+                acceptedParameters: e.acceptedParameters ?? [],
+                actionsBlacklist: e.actionsBlacklist ?? [],
+            })),
+            actions: (cat?.automationActions ?? []).map((a) => ({
+                id: a.id,
+                acceptedParameters: a.acceptedParameters ?? [],
+                eventsBlacklist: a.eventsBlacklist ?? [],
+            })),
+        };
+        debug(`reference: ${Object.keys(enums).length} enums, ${ref.events.length} events, ` +
+            `${ref.actions.length} actions for repo ${repoId}`);
+        return ref;
+    }
+    catch (e) {
+        debug(`reference unavailable: ${e.message}`);
+        return null;
+    }
+};
+/** The cached reference, in the shape the automation param check already takes. */
+export const toCatalogue = (ref) => ({
+    events: new Map(ref.events.map((e) => [e.id, e])),
+    actions: new Map(ref.actions.map((a) => [a.id, a])),
+});
+export const enumValues = (ref, name) => {
+    const v = ref?.enums[name];
+    return v?.length ? v : null;
+};
+const table = (rows, head) => {
+    const w = Math.max(head[0].length, ...rows.map(([a]) => a.length));
+    return [
+        `| ${head[0].padEnd(w)} | ${head[1]} |`,
+        `| ${'-'.repeat(w)} | ${'-'.repeat(Math.max(3, head[1].length))} |`,
+        ...rows.map(([a, b]) => `| ${a.padEnd(w)} | ${b} |`),
+    ];
+};
+/**
+ * REFERENCE.md — the closed sets, on disk, next to the JSON being edited.
+ *
+ * Deliberately generated rather than written by hand. A hand-written list of
+ * what an API accepts is wrong the first time the API changes, and nothing tells
+ * you it went wrong; this one is re-read on every pull and stamped with when.
+ */
+export const renderReferenceMd = (ref) => {
+    const lines = ['# What the API accepts', ''];
+    if (!ref) {
+        lines.push('The closed sets could not be read on the last pull, so this file is empty and', '`pipe validate` skips the checks that depend on it. That is not a claim that', 'any value is valid — it is the absence of a claim. Re-run `pipe pull` to fill it.', '');
+        return lines.join('\n');
+    }
+    lines.push(`Read from the API on ${ref.readAt} for pipe ${ref.repoId}. Regenerated by every`, '`pipe pull` — edit the workspace JSON, never this file.', '', 'These are the values the endpoint accepts in each position. They matter because', 'the schema publishes the lists but 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`, naming nothing. `pipe validate` checks', 'these offline so a bad value is refused with its name before anything is sent.', '', '## Automation events', '', 'Each event accepts **only** the parameters listed. A parameter that belongs to a', 'different event is still just `is invalid`.', '');
+    for (const e of [...ref.events].sort((a, b) => a.id.localeCompare(b.id))) {
+        lines.push(`### \`${e.id}\``);
+        lines.push('');
+        lines.push(e.acceptedParameters.length
+            ? `\`event_params\`: ${e.acceptedParameters.map((p) => `\`${p}\``).join(', ')}`
+            : '`event_params`: none — this event takes no parameters.');
+        if (e.actionsBlacklist.length) {
+            lines.push('');
+            lines.push(`Cannot be paired with: ${e.actionsBlacklist.map((a) => `\`${a}\``).join(', ')}`);
+        }
+        lines.push('');
+    }
+    lines.push('## Automation actions', '', 'Actions are per-pipe: a pipe without AI enabled offers fewer than this list if', 'it was pulled from a different pipe. `field_map` is accepted on every action', 'that writes a field and is not listed below — the catalogue names', '`fields_map_order` beside it and stops.', '');
+    for (const a of [...ref.actions].sort((x, y) => x.id.localeCompare(y.id))) {
+        lines.push(`### \`${a.id}\``);
+        lines.push('');
+        lines.push(a.acceptedParameters.length
+            ? `\`action_params\`: ${a.acceptedParameters.map((p) => `\`${p}\``).join(', ')}`
+            : '`action_params`: none — this action takes no parameters.');
+        if (a.eventsBlacklist.length) {
+            lines.push('');
+            lines.push(`Cannot be triggered by: ${a.eventsBlacklist.map((e) => `\`${e}\``).join(', ')}`);
+        }
+        lines.push('');
+    }
+    const enumRows = Object.entries(ref.enums)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, values]) => [`\`${name}\``, values.map((v) => `\`${v}\``).join(', ')]);
+    if (enumRows.length) {
+        lines.push('## Other closed sets', '');
+        lines.push('Where these are used: `FieldTypeId` is a field\'s `type_id`; `Colors` is a', 'phase or pipe `color`; `FieldConditionFilter` is a field condition\'s', '`filter`; the `Http*` sets belong to `send_http_request` action params.', '');
+        lines.push(...table(enumRows, ['Set', 'Values']));
+        lines.push('');
+    }
+    return lines.join('\n');
+};

package/dist/pipefy/snapshot.js

@@ -0,0 +1,185 @@
+import { gunzipSync } from 'node:zlib';
+import { LIMITS } from "../config.js";
+import { debug, progress, progressDone, step } from "../util/log.js";
+import { retry, sleep } from "../util/pool.js";
+/**
+ * `RepoSnapshotStatus` is `PENDING | UPLOADED | FAILED` — verified by
+ * introspection against api.pipefy.com. **UPLOADED is the success state**: the
+ * job has written the payload to S3 and `signedUrl` is available. The wider set
+ * is kept because this is an undocumented enum with no `schema_version`
+ * (ROUTE-B-V2.md ask 9), so a deployment that renames it degrades to a slow
+ * poll rather than a wrong answer.
+ */
+const DONE = new Set(['uploaded', 'done', 'succeeded', 'success', 'completed', 'finished', 'ready']);
+const FAILED = new Set(['failed', 'error', 'errored', 'cancelled', 'canceled']);
+export const isDone = (s) => DONE.has(String(s ?? '').toLowerCase());
+export const isFailed = (s) => FAILED.has(String(s ?? '').toLowerCase());
+export class SnapshotClient {
+    client;
+    /** Whether this endpoint has snapshots at all — decided once, cached. */
+    available = null;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Where poll progress goes. The snapshot wait is the longest thing this tool
+     * does (~63s), so whoever owns the screen renders it, rather than this client
+     * scribbling its own line into someone else's frame.
+     */
+    onProgress = null;
+    report(text) {
+        if (this.onProgress)
+            this.onProgress(text);
+        else
+            progress(text);
+    }
+    /**
+     * Snapshots are an entitlement, not a given. The whole point of the
+     * reconstruction path is that this can be false — so it is answered by
+     * introspection, up front, and never by a failed pull halfway through.
+     */
+    async isAvailable() {
+        if (this.available !== null)
+            return this.available;
+        const [mut, pipeFields] = await Promise.all([
+            this.client.hasMutation('createRepoSnapshot'),
+            this.client.typeFields('Pipe'),
+        ]);
+        this.available = mut && Boolean(pipeFields?.has('snapshot') || pipeFields?.has('snapshots'));
+        debug(`snapshot capability: createRepoSnapshot=${mut} pipe.snapshots=${pipeFields?.has('snapshots')}`);
+        return this.available;
+    }
+    /**
+     * `Pipe.snapshots` is a Relay `RepoSnapshotConnection`, not the flat array
+     * PLAN.md §1.1 recorded — so the rows come from `nodes`.
+     *
+     * `snapshots(last: N)` is not the most recent N — measured live, on a pipe
+     * with 86 snapshots: `last: 1` returned `sequenceIndex: 1`, the *oldest* one
+     * on record, while `first: 1` correctly returned `sequenceIndex: 86`. The
+     * connection is apparently ordered newest-first internally, the opposite of
+     * the usual Relay convention, which inverts what `first`/`last` each mean.
+     *
+     * This is not cosmetic: `pipe rollback`'s only-the-latest check, and
+     * `pipe apply`'s post-failure rollback offer, both call this to decide
+     * whether a version is still restorable. With `last`, that check compared
+     * against the *oldest* snapshot and refused every legitimate restore.
+     */
+    async list(repoId, limit = 20) {
+        const data = await this.client.tryRaw(`query($id: ID!, $first: Int!) {
+        pipe(id: $id) {
+          snapshots(first: $first) {
+            totalCount
+            nodes { versionId status sequenceIndex label createdAt }
+          }
+        }
+      }`, { id: String(repoId), first: limit }, 'list snapshots');
+        const rows = data?.pipe?.snapshots?.nodes ?? [];
+        return [...rows].sort((a, b) => (b.sequenceIndex ?? 0) - (a.sequenceIndex ?? 0));
+    }
+    /** `snapshot(versionId:)` takes an `ID`; declaring `String!` fails the query. */
+    async detail(repoId, versionId) {
+        const data = await this.client.tryRaw(`query($id: ID!, $v: ID!) {
+        pipe(id: $id) {
+          snapshot(versionId: $v) { versionId status signedUrl metrics uploadedAt error }
+        }
+      }`, { id: String(repoId), v: versionId }, 'snapshot detail');
+        return data?.pipe?.snapshot ?? null;
+    }
+    async create(repoId) {
+        const data = await this.client.raw(`mutation($input: CreateRepoSnapshotInput!) {
+        createRepoSnapshot(input: $input) { repoSnapshot { versionId status } }
+      }`, { input: { repoId: Number(repoId) } }, 'createRepoSnapshot');
+        return data.createRepoSnapshot.repoSnapshot.versionId;
+    }
+    async rename(repoId, versionId, label) {
+        const res = await this.client.tryRaw(`mutation($input: RenameRepoSnapshotInput!) {
+        renameRepoSnapshot(input: $input) { repoSnapshot { versionId label } }
+      }`, { input: { repoId: Number(repoId), versionId, label } }, 'renameRepoSnapshot');
+        return res !== null;
+    }
+    /** Poll to a terminal state. ~63s is normal, so the wait is visible and bounded. */
+    async waitFor(repoId, versionId) {
+        const started = Date.now();
+        let unreadable = 0;
+        for (;;) {
+            const d = await this.detail(repoId, versionId);
+            const elapsed = Math.round((Date.now() - started) / 1000);
+            if (d && isDone(d.status)) {
+                if (!this.onProgress)
+                    progressDone();
+                return d;
+            }
+            if (d && isFailed(d.status)) {
+                if (!this.onProgress)
+                    progressDone();
+                throw new Error(`snapshot ${versionId} ${d.status}${d.error ? `: ${d.error}` : ''}`);
+            }
+            /**
+             * A null detail means the *query* failed, not that the snapshot is
+             * pending. Polling a broken query for five minutes and then reporting
+             * "still unknown" hides the real cause — which is how a schema drift in
+             * this query cost a wasted snapshot and a 303s wait. Fail fast and say so.
+             */
+            if (!d) {
+                unreadable++;
+                if (unreadable >= 3) {
+                    if (!this.onProgress)
+                        progressDone();
+                    throw new Error(`snapshot ${versionId} status is unreadable — pipe.snapshot(versionId:) did not answer 3 times. ` +
+                        `Run with --verbose to see the GraphQL error; the snapshot itself may well have been created.`);
+                }
+            }
+            else {
+                unreadable = 0;
+            }
+            if (Date.now() - started > LIMITS.snapshotTimeoutMs) {
+                if (!this.onProgress)
+                    progressDone();
+                throw new Error(`snapshot ${versionId} still ${d?.status ?? 'unreadable'} after ${elapsed}s`);
+            }
+            this.report(`${String(d?.status ?? 'unreadable').toLowerCase()} ${elapsed}s (~63s typical)`);
+            await sleep(LIMITS.snapshotPollMs);
+        }
+    }
+    /**
+     * Download the payload. The signed URL is re-queried immediately before the
+     * fetch and never stored, and the raw gzip bytes are returned alongside the
+     * parsed payload so the caller can cache the compressed form.
+     */
+    async download(repoId, versionId) {
+        const d = await this.detail(repoId, versionId);
+        if (!d?.signedUrl)
+            throw new Error(`snapshot ${versionId} has no signedUrl (status ${d?.status ?? 'unknown'})`);
+        const bytes = await retry(async () => {
+            const res = await fetch(d.signedUrl);
+            if (!res.ok) {
+                const err = new Error(`snapshot download HTTP ${res.status}`);
+                err.retryable = res.status >= 500 || res.status === 429;
+                throw err;
+            }
+            return Buffer.from(await res.arrayBuffer());
+        }, { label: 'snapshot download' });
+        const gzipped = bytes.length > 2 && bytes[0] === 0x1f && bytes[1] === 0x8b;
+        const raw = gzipped ? gunzipSync(bytes) : bytes;
+        return { payload: JSON.parse(raw.toString('utf8')), gzip: gzipped ? bytes : null, raw };
+    }
+    /** Create, wait, download — the whole read in one call. */
+    async pull(repoId, label) {
+        if (this.onProgress)
+            this.report('requesting a snapshot');
+        else
+            step(`creating snapshot of repo ${repoId}`);
+        const versionId = await this.create(repoId);
+        await this.waitFor(repoId, versionId);
+        if (label)
+            await this.rename(repoId, versionId, label);
+        this.report('downloading');
+        const dl = await this.download(repoId, versionId);
+        return { ...dl, versionId };
+    }
+    /** Most recent already-complete snapshot, so a pull can cost zero snapshots. */
+    async latestComplete(repoId) {
+        const rows = await this.list(repoId);
+        return rows.find((r) => isDone(r.status)) ?? null;
+    }
+}

package/dist/pipefy/toolkit.js

@@ -0,0 +1,158 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { debug } from "../util/log.js";
+/**
+ * Bridge to the official Pipefy AI toolkit (github.com/pipefy/ai-toolkit).
+ *
+ * `pipe` does not implement Pipefy login. When the toolkit is installed, its
+ * session *is* the credential: `pipefy auth login` runs the browser OAuth flow
+ * and stores a session in the OS keychain, and everything here does is ask the
+ * toolkit for the current bearer.
+ *
+ * That means one login for the MCP server, the `pipefy` CLI and this tool, and
+ * it means the keychain, the refresh grant and the credential precedence stay in
+ * one place — the toolkit's — rather than being reimplemented against a private
+ * store shape that can change under us.
+ *
+ * The bearer is short-lived and never persisted here. It is fetched per process
+ * and re-fetched when the API rejects it, which is why callers take a provider
+ * rather than a string.
+ */
+const exec = promisify(execFile);
+const here = dirname(fileURLToPath(import.meta.url));
+const HELPER = join(here, 'toolkit_bearer.py');
+const WINDOWS = process.platform === 'win32';
+/** `pipefy` / `pipefy-mcp-server`, wherever uv put them. */
+const toolBinDir = () => {
+    const home = process.env.USERPROFILE ?? process.env.HOME;
+    if (!home)
+        return null;
+    const dir = join(home, '.local', 'bin');
+    return existsSync(dir) ? dir : null;
+};
+export const toolkitBinary = (name) => {
+    const dir = toolBinDir();
+    if (!dir)
+        return null;
+    const path = join(dir, WINDOWS ? `${name}.exe` : name);
+    return existsSync(path) ? path : null;
+};
+/**
+ * The interpreter that can import `pipefy_auth`.
+ *
+ * `uv tool install` gives each tool its own environment, and `uv tool dir` is
+ * the documented way to find them — so the layout is asked for rather than
+ * assumed. `uv run --with` is the fallback for a machine where the CLI is not
+ * installed as a tool but uv is available.
+ */
+const findInterpreter = async () => {
+    const roots = [];
+    try {
+        const { stdout } = await exec('uv', ['tool', 'dir'], { timeout: 15_000 });
+        const dir = stdout.trim();
+        if (dir)
+            roots.push(dir);
+    }
+    catch {
+        debug('uv tool dir failed — uv may not be installed');
+    }
+    const appdata = process.env.APPDATA;
+    if (appdata)
+        roots.push(join(appdata, 'uv', 'tools'));
+    const home = process.env.USERPROFILE ?? process.env.HOME;
+    if (home) {
+        roots.push(join(home, '.local', 'share', 'uv', 'tools'));
+        roots.push(join(home, 'Library', 'Application Support', 'uv', 'tools'));
+    }
+    for (const root of roots) {
+        for (const tool of ['pipefy-cli', 'pipefy-mcp-server']) {
+            const python = WINDOWS
+                ? join(root, tool, 'Scripts', 'python.exe')
+                : join(root, tool, 'bin', 'python');
+            if (existsSync(python)) {
+                debug(`toolkit interpreter: ${python}`);
+                return { command: python, args: [] };
+            }
+        }
+    }
+    // No installed tool env: let uv build an ephemeral one. Slower, and it needs
+    // the network the first time, so it is deliberately the last resort.
+    try {
+        await exec('uv', ['--version'], { timeout: 15_000 });
+        debug('falling back to `uv run --with pipefy-auth`');
+        return { command: 'uv', args: ['run', '--quiet', '--with', 'pipefy-auth', 'python'] };
+    }
+    catch {
+        return null;
+    }
+};
+let cachedInterpreter;
+/** Is the toolkit usable on this machine, and does it currently hold a credential? */
+export const inspectToolkit = async () => {
+    cachedInterpreter ??= await findInterpreter();
+    if (!cachedInterpreter)
+        return { installed: false };
+    const credential = await readBearer();
+    if (!credential)
+        return { installed: false };
+    return {
+        installed: true,
+        cliPath: toolkitBinary('pipefy'),
+        mcpServerPath: toolkitBinary('pipefy-mcp-server'),
+        interpreter: cachedInterpreter.command,
+        credential,
+    };
+};
+/**
+ * Ask the toolkit for a bearer. `null` means the toolkit could not be used at
+ * all — distinct from a `{ ok: false }` result, which is the toolkit answering
+ * that it holds no credential.
+ */
+export const readBearer = async () => {
+    cachedInterpreter ??= await findInterpreter();
+    if (!cachedInterpreter)
+        return null;
+    if (!existsSync(HELPER)) {
+        debug(`toolkit helper missing at ${HELPER}`);
+        return null;
+    }
+    try {
+        const { stdout } = await exec(cachedInterpreter.command, [...cachedInterpreter.args, HELPER], { timeout: 60_000, maxBuffer: 1024 * 1024 });
+        const parsed = JSON.parse(stdout.trim());
+        debug(`toolkit credential: ${parsed.ok ? parsed.source : parsed.reason}`);
+        return parsed;
+    }
+    catch (e) {
+        debug(`toolkit bearer helper failed: ${e.message}`);
+        return null;
+    }
+};
+/** Run `pipefy auth login`, inheriting the terminal so the browser flow works. */
+export const runToolkitLogin = async (extraArgs = []) => {
+    const cli = toolkitBinary('pipefy');
+    const { spawn } = await import('node:child_process');
+    const command = cli ?? 'pipefy';
+    return new Promise((resolve) => {
+        const child = spawn(command, ['auth', 'login', ...extraArgs], { stdio: 'inherit' });
+        child.on('error', () => resolve(127));
+        child.on('exit', (code) => resolve(code ?? 1));
+    });
+};
+/** `pipefy auth status --json`, for `pipe doctor`. Null when unavailable. */
+export const toolkitAuthStatus = async () => {
+    const cli = toolkitBinary('pipefy');
+    if (!cli)
+        return null;
+    try {
+        const { stdout } = await exec(cli, ['auth', 'status', '--json'], { timeout: 60_000 });
+        return JSON.parse(stdout.trim());
+    }
+    catch (e) {
+        debug(`pipefy auth status failed: ${e.message}`);
+        return null;
+    }
+};
+export const INSTALL_HINT = 'install the Pipefy AI toolkit (github.com/pipefy/ai-toolkit): `uv tool install pipefy-cli`, then `pipefy auth login`';

package/dist/report/integrations.js

@@ -0,0 +1,165 @@
+/**
+ * The integration surface of a pipe, pulled out of the payload as its own
+ * artifact.
+ *
+ * "Integration" here means every way this pipe touches something outside
+ * itself, because those are the parts of a change whose blast radius leaves the
+ * pipe: a webhook fires at a third party, a pipe relation writes cards into
+ * another process, a cross-repo automation does both. They are also the parts
+ * that carry credentials, which is why the rendered summary is redacted and the
+ * raw rows go in a file the workspace .gitignore covers.
+ *
+ * Recorded per run rather than derived on demand: a run is the only moment when
+ * "what did this pipe reach, before and after" is knowable, and by the next
+ * apply the answer has changed.
+ */
+/** Automation actions that reach outside the pipe they are triggered in. */
+const OUTBOUND_ACTIONS = new Set([
+    'http_request',
+    'send_email',
+    'send_email_template',
+    'create_card',
+    'create_card_relation',
+    'move_single_card',
+    'create_table_record',
+    'update_table_record',
+]);
+const s = (v) => (v === null || v === undefined ? null : String(v));
+const hostOf = (url) => {
+    const raw = s(url);
+    if (!raw)
+        return '(no url)';
+    try {
+        return new URL(raw).host;
+    }
+    catch {
+        return raw.slice(0, 40);
+    }
+};
+/** Whether a row holds anything bearer-equivalent. */
+const bearsSecret = (row) => {
+    const j = JSON.stringify(row).toLowerCase();
+    return (j.includes('authentication_value') ||
+        j.includes('authentication_key') ||
+        j.includes('token') ||
+        j.includes('secret') ||
+        /[?&](key|token|sig|signature|auth)=/.test(j));
+};
+export const integrationsFrom = (env) => {
+    const rel = env.payload.relations;
+    const repoId = Number(env.payload.id);
+    const webhooks = rel.webhooks ?? [];
+    const relations = rel.pipe_relations ?? [];
+    const automations = rel.automations ?? [];
+    const inboxes = rel.email_inboxes ?? [];
+    const fields = rel.fields ?? [];
+    const outbound = automations.filter((a) => {
+        const action = s(a['action_id']) ?? '';
+        const target = s(a['action_repo_id']);
+        const crossRepo = target !== null && target !== s(a['event_repo_id']);
+        return crossRepo || OUTBOUND_ACTIONS.has(action);
+    });
+    const connectedFields = fields.filter((f) => s(f['connected_repo_id']) ?? s(f['connected_pipe_id']));
+    const edges = [
+        ...webhooks.map((w) => ({
+            kind: 'webhook',
+            target: hostOf(w['url']),
+            id: s(w['id']),
+            detail: `${s(w['name']) ?? 'unnamed'} on ` +
+                `${Array.isArray(w['actions']) ? w['actions'].join(', ') : (s(w['actions']) ?? 'no actions')}`,
+            bearsSecret: bearsSecret(w),
+        })),
+        ...relations.map((r) => ({
+            kind: 'pipe_relation',
+            target: `repo ${s(r['child_id']) ?? s(r['parent_id']) ?? '?'}`,
+            id: s(r['id']),
+            detail: `${s(r['name']) ?? 'unnamed'} — parent ${s(r['parent_id'])} to child ${s(r['child_id'])}`,
+        })),
+        ...outbound.map((a) => ({
+            kind: 'automation',
+            target: s(a['action_repo_id']) && s(a['action_repo_id']) !== String(repoId)
+                ? `repo ${s(a['action_repo_id'])}`
+                : (s(a['action_id']) ?? 'action'),
+            id: s(a['id']),
+            detail: `${s(a['name']) ?? 'unnamed'} — ${s(a['event_id'])} to ${s(a['action_id'])}` +
+                `${a['active'] === false ? ' (inactive)' : ''}`,
+            bearsSecret: bearsSecret(a),
+        })),
+        ...connectedFields.map((f) => ({
+            kind: 'connected_field',
+            target: `repo ${s(f['connected_repo_id']) ?? s(f['connected_pipe_id'])}`,
+            id: s(f['id']),
+            // Payload rows spell the type `type_id`; a reconstructed row may spell it
+            // `type`. Neither is guaranteed, so both are tried before giving up.
+            detail: `field "${s(f['label']) ?? s(f['name']) ?? '?'}" (${s(f['type_id']) ?? s(f['type']) ?? 'unknown type'})`,
+        })),
+        ...inboxes.map((i) => ({
+            kind: 'email_inbox',
+            target: s(i['email']) ?? s(i['name']) ?? 'inbox',
+            id: s(i['id']),
+            detail: 'inbound email',
+        })),
+    ];
+    const connected = new Set();
+    const note = (v) => {
+        const n = Number(v);
+        if (Number.isFinite(n) && n !== repoId && n !== 0)
+            connected.add(n);
+    };
+    for (const r of relations) {
+        note(r['parent_id']);
+        note(r['child_id']);
+    }
+    for (const a of outbound)
+        note(a['action_repo_id']);
+    for (const f of connectedFields)
+        note(f['connected_repo_id'] ?? f['connected_pipe_id']);
+    const form = (rel.public_forms ?? [])[0] ?? null;
+    return {
+        generatedAt: new Date().toISOString(),
+        repoId,
+        repoName: String(env.payload['name'] ?? repoId),
+        coverage: {
+            webhooks: env.coverage.webhooks,
+            pipe_relations: env.coverage.pipe_relations,
+            automations: env.coverage.automations,
+            email_inboxes: env.coverage.email_inboxes,
+        },
+        counts: {
+            webhooks: webhooks.length,
+            pipe_relations: relations.length,
+            outbound_automations: outbound.length,
+            connected_fields: connectedFields.length,
+        },
+        edges,
+        connected_repo_ids: [...connected].sort((a, b) => a - b),
+        webhooks,
+        pipe_relations: relations,
+        outbound_automations: outbound,
+        email_inboxes: inboxes,
+        public_form: form ? { open: Boolean(env.payload['public']), title: form['title'] ?? null } : null,
+    };
+};
+/** The integration surface as report prose. Hosts kept, credentials never. */
+export const renderIntegrations = (v) => {
+    const lines = [];
+    const gaps = Object.entries(v.coverage).filter(([, c]) => c !== 'complete');
+    if (gaps.length) {
+        lines.push(`> Coverage: ${gaps.map(([k, c]) => `${k} is ${c}`).join(', ')}. ` +
+            'An absent row below is not evidence that nothing is there.', '');
+    }
+    if (!v.edges.length) {
+        lines.push('This pipe reaches nothing outside itself.');
+        return lines;
+    }
+    lines.push('| Kind | Target | Id | Detail |', '| --- | --- | --- | --- |');
+    for (const e of v.edges) {
+        lines.push(`| ${e.kind.replace(/_/g, ' ')} | ${e.target}${e.bearsSecret ? ' (key)' : ''} | ${e.id ?? '-'} | ` +
+            `${e.detail.replace(/\|/g, '\\|')} |`);
+    }
+    if (v.edges.some((e) => e.bearsSecret)) {
+        lines.push('', '(key) marks a row that carries a credential. The value is in `integrations.json`, ' +
+            'which the workspace .gitignore covers.');
+    }
+    return lines;
+};