@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

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;
+};

package/dist/report/run.js

@@ -0,0 +1,356 @@
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { mkdirp, writeFile, writeJson, exists } from "../util/fsx.js";
+import { paths } from "../workspace/layout.js";
+import { integrationsFrom, renderIntegrations } from "./integrations.js";
+import { TOOL } from "../version.js";
+const stamp = (d = new Date()) => d.toISOString().replace(/[:.]/g, '-').replace(/-\d{3}Z$/, 'Z');
+/**
+ * The command as typed, for reproduction — with any token elided. `--token` is
+ * the one flag whose value must never reach a file, and `pipe login --token` is
+ * a real invocation someone might run inside a workspace.
+ */
+export const invocation = (argv = process.argv.slice(2)) => {
+    const parts = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (/^--token(=|$)/.test(a)) {
+            parts.push('--token <elided>');
+            if (!a.includes('=') && argv[i + 1] && !argv[i + 1].startsWith('-'))
+                i++;
+            continue;
+        }
+        parts.push(a);
+    }
+    return `pipe ${parts.join(' ')}`.trim();
+};
+/** `runs/` lives at the workspace root, not under `.ppc/` — these are for reading. */
+export const runsDir = (root) => join(paths(root).root, 'runs');
+export const runDir = (root, id) => join(runsDir(root), id);
+/**
+ * Collects what happened while a command runs.
+ *
+ * Deliberately tolerant: a recorder that throws would turn a successful apply
+ * into a failed command, and the record is worth less than the work it
+ * describes. Everything here is additive and total.
+ */
+export class RunRecorder {
+    id;
+    startedAt;
+    notes = [];
+    warnings = [];
+    plan = null;
+    verification;
+    beforeEnv = null;
+    afterEnv = null;
+    kind;
+    ctx;
+    constructor(kind, ctx) {
+        this.kind = kind;
+        this.ctx = ctx;
+        /**
+         * `startedAt` is passed in by commands that only learn where the workspace
+         * is at the end — a pull cannot name its own output directory until
+         * discovery has run, and a run that reports 0.0s for a 60-second snapshot is
+         * worse than no timing at all.
+         */
+        this.startedAt = ctx.startedAt ?? new Date();
+        this.id = `${stamp(this.startedAt)}--${kind}`;
+    }
+    note(text) {
+        this.notes.push(text);
+    }
+    warn(text) {
+        this.warnings.push(text);
+    }
+    /** The plan is the step list; recording it is how the report gets its detail. */
+    fromPlan(plan) {
+        this.plan = plan;
+    }
+    verified(ok, detail) {
+        this.verification = { ran: true, ok, ...(detail ? { detail } : {}) };
+    }
+    /** The payload the run started from, when the command knows it. */
+    before(env) {
+        this.beforeEnv = env;
+    }
+    after(env) {
+        this.afterEnv = env;
+    }
+    build(outcome, summary) {
+        const finished = new Date();
+        const steps = (this.plan?.steps ?? []).map((s) => {
+            const started = s.startedAt ? Date.parse(s.startedAt) : NaN;
+            const ended = s.finishedAt ? Date.parse(s.finishedAt) : NaN;
+            return {
+                index: s.index,
+                id: s.id,
+                description: s.description,
+                entity: String(s.entity),
+                op: s.op,
+                kind: s.kind,
+                status: s.status,
+                tags: [
+                    ...(s.destructive ? ['destructive'] : []),
+                    ...(s.unverified ? ['unverified'] : []),
+                    ...(s.kind.startsWith('internal') ? ['internal-api'] : []),
+                ],
+                ...(s.error ? { error: s.error } : {}),
+                ...(producedId(s.result) !== undefined ? { produced: producedId(s.result) } : {}),
+                ...(Number.isFinite(started) && Number.isFinite(ended) ? { durationMs: ended - started } : {}),
+            };
+        });
+        const count = (status) => steps.filter((s) => s.status === status).length;
+        const env = this.afterEnv;
+        return {
+            id: this.id,
+            kind: this.kind,
+            command: this.ctx.command,
+            tool: { ...TOOL },
+            startedAt: this.startedAt.toISOString(),
+            finishedAt: finished.toISOString(),
+            durationMs: finished.getTime() - this.startedAt.getTime(),
+            workspace: this.ctx.workspace,
+            repo: this.ctx.repo,
+            outcome,
+            summary,
+            ...(this.plan ? { planId: this.plan.id, preApplyVersionId: this.plan.preApplyVersionId ?? null } : {}),
+            counts: {
+                steps: steps.length,
+                done: count('done'),
+                failed: count('failed'),
+                skipped: count('skipped'),
+                pending: count('pending'),
+                blocked: this.plan?.blocked.length ?? 0,
+            },
+            steps,
+            blocked: (this.plan?.blocked ?? []).map((b) => ({
+                label: b.label,
+                entity: String(b.entity),
+                op: b.op,
+                ...(b.reason ? { reason: b.reason } : {}),
+                ...(b.ask ? { ask: b.ask } : {}),
+            })),
+            // Deduplicated: a multi-repo pull collects the same coverage note from
+            // every tree, and three copies of it read as three problems.
+            warnings: [...new Set([...(this.plan?.warnings ?? []), ...this.warnings])],
+            notes: [...new Set(this.notes)],
+            ...(this.verification ? { verification: this.verification } : {}),
+            ...(env ? { coverage: env.coverage } : {}),
+            integrations: {
+                ...(this.beforeEnv ? { before: integrationsFrom(this.beforeEnv).counts } : {}),
+                ...(this.afterEnv ? { after: integrationsFrom(this.afterEnv).counts } : {}),
+            },
+            artifacts: [],
+        };
+    }
+    /**
+     * Write the run folder. Never throws: a failure to record is reported as a
+     * note and nothing more, because the alternative is a command that did its
+     * work and then reported failure.
+     */
+    async write(outcome, summary) {
+        try {
+            const record = this.build(outcome, summary);
+            const dir = runDir(this.ctx.workspace, record.id);
+            await mkdirp(dir);
+            const written = [];
+            const put = async (name, value) => {
+                await writeJson(join(dir, name), value);
+                written.push(name);
+            };
+            if (this.afterEnv) {
+                await put('pipe.json', this.afterEnv);
+                await put('integrations.json', integrationsFrom(this.afterEnv));
+            }
+            if (this.beforeEnv && this.kind !== 'pull') {
+                await put('pipe.before.json', this.beforeEnv);
+                await put('integrations.before.json', integrationsFrom(this.beforeEnv));
+            }
+            record.artifacts = [...written, 'report.md', 'run.json'];
+            await writeJson(join(dir, 'run.json'), record);
+            await writeFile(join(dir, 'report.md'), renderRunReport(record, this.afterEnv, this.beforeEnv));
+            await appendIndex(this.ctx.workspace, record);
+            return { dir };
+        }
+        catch (e) {
+            return { dir: runDir(this.ctx.workspace, this.id), error: e.message };
+        }
+    }
+}
+/** The created id, from whatever shape the mutation answered with. */
+const producedId = (result) => {
+    if (!result || typeof result !== 'object')
+        return undefined;
+    const seen = new Set();
+    const walk = (v, depth) => {
+        if (depth > 4 || !v || typeof v !== 'object' || seen.has(v))
+            return undefined;
+        seen.add(v);
+        const o = v;
+        if (typeof o['id'] === 'string' || typeof o['id'] === 'number')
+            return o['id'];
+        for (const val of Object.values(o)) {
+            const hit = walk(val, depth + 1);
+            if (hit !== undefined)
+                return hit;
+        }
+        return undefined;
+    };
+    return walk(result, 0);
+};
+const OUTCOME_WORD = {
+    ok: 'succeeded',
+    partial: 'partially applied',
+    failed: 'failed',
+    refused: 'refused before sending anything',
+    'no-op': 'had nothing to do',
+};
+export const renderRunReport = (r, after, before) => {
+    const L = [];
+    const secs = (r.durationMs / 1000).toFixed(1);
+    L.push(`# ${r.kind} — ${r.repo.name} (${r.repo.id})`, '');
+    L.push(`**${OUTCOME_WORD[r.outcome]}** · ${r.summary}`, '');
+    L.push('| | |', '| --- | --- |');
+    L.push(`| Run | \`${r.id}\` |`);
+    L.push(`| Command | \`${r.command}\` |`);
+    L.push(`| Started | ${r.startedAt} |`);
+    L.push(`| Duration | ${secs}s |`);
+    L.push(`| Workspace | \`${r.workspace}\` |`);
+    if (r.planId)
+        L.push(`| Plan | \`${r.planId}\` |`);
+    if (r.preApplyVersionId)
+        L.push(`| Pre-apply snapshot | \`${r.preApplyVersionId}\` |`);
+    if (after)
+        L.push(`| Read path | ${after.source}${after.versionId ? ` \`${after.versionId.slice(0, 8)}\`` : ''} |`);
+    if (r.counts.steps) {
+        L.push(`| Steps | ${r.counts.steps} — ${r.counts.done} done, ${r.counts.failed} failed, ` +
+            `${r.counts.skipped} skipped${r.counts.pending ? `, ${r.counts.pending} never attempted` : ''} |`);
+    }
+    if (r.verification)
+        L.push(`| Verification | ${r.verification.ok ? 'clean' : 'found differences'} |`);
+    L.push('');
+    if (r.steps.length) {
+        L.push('## Steps', '');
+        L.push('| # | Step | Entity | Op | Status | Result |', '| --- | --- | --- | --- | --- | --- |');
+        for (const s of r.steps) {
+            const result = s.error
+                ? `\`${s.error.replace(/\|/g, '\\|').slice(0, 160)}\``
+                : s.produced !== undefined
+                    ? `id ${s.produced}`
+                    : s.status === 'done'
+                        ? 'applied'
+                        : '—';
+            const tags = s.tags.length ? ` <sub>${s.tags.join(' ')}</sub>` : '';
+            L.push(`| ${s.index} | ${s.description.replace(/\|/g, '\\|')}${tags} | ${s.entity} | ${s.op} | ` +
+                `${statusMark(s.status)} | ${result} |`);
+        }
+        L.push('');
+        const failures = r.steps.filter((s) => s.status === 'failed' || s.status === 'skipped');
+        if (failures.length) {
+            L.push('### What did not land', '');
+            for (const s of failures) {
+                L.push(`- **${s.description}** (${s.status}) — ${s.error ?? 'no reason recorded'}`);
+            }
+            L.push('');
+        }
+    }
+    if (r.blocked.length) {
+        L.push('## Refused before sending', '');
+        L.push('These changes are in the workspace and have no write path. Nothing was attempted.', '');
+        for (const b of r.blocked) {
+            L.push(`- **${b.label}** — ${b.reason ?? 'no write path'}${b.ask ? ` (ask ${b.ask})` : ''}`);
+        }
+        L.push('');
+    }
+    if (r.warnings.length) {
+        L.push('## Warnings', '');
+        for (const w of r.warnings)
+            L.push(`- ${w}`);
+        L.push('');
+    }
+    if (after) {
+        const t = after.payload.relations;
+        L.push('## The pipe, as of the end of this run', '');
+        L.push('| Group | Count | Coverage |', '| --- | --- | --- |');
+        for (const [name, rows] of Object.entries(t)) {
+            const cov = (r.coverage ?? {})[name] ?? 'unknown';
+            if (!rows.length && cov === 'complete')
+                continue;
+            L.push(`| ${name} | ${rows.length} | ${cov}${cov === 'complete' ? '' : ' ⚠'} |`);
+        }
+        L.push('');
+        const gaps = Object.entries(r.coverage ?? {}).filter(([, c]) => c !== 'complete');
+        if (gaps.length) {
+            L.push(`⚠ ${gaps.length} group${gaps.length === 1 ? '' : 's'} not fully read. ` +
+                'A count of 0 there means "not read", not "empty".', '');
+        }
+        L.push('## Integrations', '');
+        if (before) {
+            const b = integrationsFrom(before).counts;
+            const a = integrationsFrom(after).counts;
+            const moved = Object.keys(a).filter((k) => a[k] !== b[k]);
+            if (moved.length) {
+                L.push(`Changed by this run: ${moved.map((k) => `${k} ${b[k]} → ${a[k]}`).join(', ')}.`, '');
+            }
+        }
+        L.push(...renderIntegrations(integrationsFrom(after)));
+        L.push('');
+    }
+    if (r.notes.length) {
+        L.push('## Notes', '');
+        for (const n of r.notes)
+            L.push(`- ${n}`);
+        L.push('');
+    }
+    L.push('---', '', `Artifacts in this folder: ${r.artifacts.map((a) => `\`${a}\``).join(', ')}.`);
+    L.push('', '`pipe.json` and `integrations.json` are full copies of the pipe and include ' +
+        'webhook URLs and HTTP-request credentials. This report does not.');
+    return L.join('\n') + '\n';
+};
+const statusMark = (status) => status === 'done' ? 'done' : status === 'failed' ? '**failed**' : status === 'skipped' ? 'skipped' : status;
+/**
+ * One line per run in `runs/index.md`, newest last.
+ *
+ * Appended rather than regenerated so that a run folder someone has deleted or
+ * moved does not silently vanish from the history.
+ */
+const appendIndex = async (root, r) => {
+    const path = join(runsDir(root), 'index.md');
+    const header = [
+        '# Runs',
+        '',
+        'Every invocation that read or wrote this pipe, oldest first. Each row links to',
+        'the run folder, which holds the report, the payload, and the integration surface',
+        'as of the end of that run.',
+        '',
+        '| When | Run | Kind | Outcome | Steps | Summary |',
+        '| --- | --- | --- | --- | --- | --- |',
+    ].join('\n');
+    if (!(await exists(path)))
+        await writeFile(path, header + '\n');
+    const row = `| ${r.startedAt.replace('T', ' ').slice(0, 19)} | [${r.id}](${r.id}/report.md) | ${r.kind} | ` +
+        `${r.outcome} | ${r.counts.steps ? `${r.counts.done}/${r.counts.steps}` : '—'} | ` +
+        `${r.summary.replace(/\|/g, '\\|')} |\n`;
+    await fs.appendFile(path, row, 'utf8');
+};
+/** Read every run record in a workspace, oldest first. */
+export const listRuns = async (root) => {
+    const dir = runsDir(root);
+    if (!(await exists(dir)))
+        return [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const out = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        try {
+            out.push(JSON.parse(await fs.readFile(join(dir, e.name, 'run.json'), 'utf8')));
+        }
+        catch {
+            // A run folder without a readable run.json is skipped, not fatal: the
+            // report beside it may still be the thing someone wants to read.
+        }
+    }
+    return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+};

package/dist/util/fsx.js

@@ -0,0 +1,50 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pretty } from "./json.js";
+export const mkdirp = (p) => fs.mkdir(p, { recursive: true });
+export const writeFile = async (p, content) => {
+    await mkdirp(dirname(p));
+    await fs.writeFile(p, content, 'utf8');
+};
+export const writeJson = (p, v) => writeFile(p, pretty(v));
+export const readJson = async (p) => {
+    const raw = await fs.readFile(p, 'utf8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${p}: invalid JSON - ${e.message}`);
+    }
+};
+export const exists = async (p) => {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Every .json file under a directory, recursively, sorted. */
+export const listJson = async (dir) => {
+    const acc = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = (await fs.readdir(d, { withFileTypes: true }));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = join(d, e.name);
+            if (e.isDirectory())
+                await walk(full);
+            else if (e.name.endsWith('.json'))
+                acc.push(full);
+        }
+    };
+    await walk(dir);
+    return acc.sort();
+};
+export const rmrf = (p) => fs.rm(p, { recursive: true, force: true });

package/dist/util/git.js

@@ -0,0 +1,25 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Best-effort, and never throws: a workspace with no local version control is
+ * an advisory, not a blocker. `pipe rollback` only restores the *latest*
+ * snapshot (commands/misc.ts), so it stops covering a rollback the moment
+ * anything re-snapshots the repo — which a normal `pipe apply` does on its own
+ * read-back. A local git history is what covers the gap.
+ */
+export const checkGit = async (root) => {
+    try {
+        await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root });
+        return { installed: true, tracked: true };
+    }
+    catch {
+        try {
+            await execFileAsync('git', ['--version']);
+            return { installed: true, tracked: false };
+        }
+        catch {
+            return { installed: false, tracked: false };
+        }
+    }
+};

package/dist/util/json.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical JSON. PLAN.md §3: the round-trip exit criterion is *semantic*
+ * equality under a canonical form, never byte equality — `JSON.parse` turns
+ * `index: 6.0` into `6`, and fractional indices invite float noise.
+ */
+/** Normalise a number to a stable representation. -0 -> 0, 6.0 -> 6. */
+const num = (n) => {
+    if (!Number.isFinite(n))
+        return n;
+    if (Object.is(n, -0))
+        return 0;
+    // Collapse float noise past 10 significant decimals; index and lateness are
+    // the only fractional numbers in the payload and never need more.
+    const r = Number(n.toFixed(10));
+    return Object.is(r, -0) ? 0 : r;
+};
+export const canonical = (v) => {
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v === 'number')
+        return num(v);
+    if (typeof v === 'boolean' || typeof v === 'string')
+        return v;
+    if (Array.isArray(v))
+        return v.map(canonical);
+    if (typeof v === 'object') {
+        const o = v;
+        const res = {};
+        for (const k of Object.keys(o).sort()) {
+            if (o[k] === undefined)
+                continue;
+            res[k] = canonical(o[k]);
+        }
+        return res;
+    }
+    return String(v);
+};
+export const canonicalString = (v) => JSON.stringify(canonical(v));
+export const deepEqual = (a, b) => canonicalString(a) === canonicalString(b);
+/** Stable pretty JSON for files a human and Claude will read and edit. */
+export const pretty = (v) => JSON.stringify(v, null, 2) + '\n';
+export const clone = (v) => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+/** Walk every string in a structure, replacing it. Used by the %{id} rewriter. */
+export const mapStrings = (v, fn) => {
+    if (typeof v === 'string')
+        return fn(v);
+    if (Array.isArray(v))
+        return v.map((x) => mapStrings(x, fn));
+    if (v && typeof v === 'object') {
+        const res = {};
+        for (const [k, val] of Object.entries(v))
+            res[k] = mapStrings(val, fn);
+        return res;
+    }
+    return v;
+};