@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/report/run.js

@@ -0,0 +1,355 @@
+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";
+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: { name: 'pipefy-process-coder', version: '0.1.0' },
+            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;
+};

package/dist/util/log.js

@@ -0,0 +1,69 @@
+const ESC = '\x1b[';
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code) => (s) => (useColor ? `${ESC}${code}m${s}${ESC}0m` : s);
+export const dim = c('2');
+export const bold = c('1');
+export const red = c('31');
+export const green = c('32');
+export const yellow = c('33');
+export const blue = c('36');
+export const magenta = c('35');
+let verbose = false;
+export const setVerbose = (v) => { verbose = v; };
+export const isVerbose = () => verbose;
+let sink = null;
+export const claimLogSink = (s) => {
+    sink = s;
+};
+export const hasLogSink = () => sink !== null;
+/** Colour is for a terminal. A report is a file, so it gets none. */
+export const stripAnsi = (s) => s.replace(/\u001b\[[0-9;]*m/g, '');
+export const out = (s = '') => process.stdout.write(s + '\n');
+export const info = (s) => {
+    if (sink)
+        sink.note(s);
+    else
+        process.stderr.write(s + '\n');
+};
+export const debug = (s) => { if (verbose)
+    process.stderr.write(dim('· ' + s) + '\n'); };
+export const warn = (s) => {
+    if (sink)
+        sink.note(yellow('! ') + s);
+    else
+        process.stderr.write(yellow('! ') + s + '\n');
+};
+export const error = (s) => {
+    if (sink)
+        sink.note(red('x ') + s);
+    else
+        process.stderr.write(red('x ') + s + '\n');
+};
+export const ok = (s) => {
+    if (sink)
+        sink.note(green('+ ') + s);
+    else
+        process.stderr.write(green('+ ') + s + '\n');
+};
+export const step = (s) => {
+    if (sink)
+        return;
+    process.stderr.write(blue('> ') + s + '\n');
+};
+const CLEAR_LINE = `\r${ESC}2K`;
+/** Single-line progress that collapses to nothing on a non-tty. */
+export const progress = (s) => {
+    if (!process.stderr.isTTY)
+        return;
+    process.stderr.write(CLEAR_LINE + dim('  ' + s));
+};
+export const progressDone = () => { if (process.stderr.isTTY)
+    process.stderr.write(CLEAR_LINE); };
+export class UserError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = 'UserError';
+        this.hint = hint;
+    }
+}

package/dist/util/pool.js

@@ -0,0 +1,42 @@
+import { debug } from "./log.js";
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Bounded-concurrency map that preserves input order. */
+export const mapPool = async (items, limit, fn) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+};
+/**
+ * Exponential backoff with jitter. PLAN.md §9: rate limits are unmeasured, so
+ * every network call goes through this and every retry is logged - which is how
+ * we measure the ceiling instead of discovering it during a client apply.
+ */
+export const retry = async (fn, opts = {}) => {
+    const tries = opts.tries ?? 5;
+    const base = opts.baseMs ?? 600;
+    let lastErr;
+    for (let attempt = 1; attempt <= tries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            lastErr = e;
+            const retryable = e.retryable !== false;
+            if (!retryable || attempt === tries)
+                break;
+            const wait = Math.round(base * 2 ** (attempt - 1) * (0.7 + Math.random() * 0.6));
+            debug(`retry ${attempt}/${tries - 1} in ${wait}ms${opts.label ? ` (${opts.label})` : ''}: ${e.message}`);
+            await sleep(wait);
+        }
+    }
+    throw lastErr;
+};

package/dist/util/slug.js

@@ -0,0 +1,23 @@
+/** Filesystem-safe, stable, human-readable name segment. */
+export const slug = (s, fallback = 'untitled') => {
+    const base = (s ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '');
+    const out = base
+        .toLowerCase()
+        .replace(/['"`]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60)
+        .replace(/-+$/g, '');
+    return out || fallback;
+};
+/** `01--new-request` - index-prefixed so directory order matches pipe order. */
+export const indexed = (i, name) => `${String(Math.trunc(i)).padStart(2, '0')}--${slug(name)}`;
+/** Disambiguate repeated slugs deterministically: name, name-2, name-3. */
+export const uniquify = () => {
+    const seen = new Map();
+    return (s) => {
+        const n = (seen.get(s) ?? 0) + 1;
+        seen.set(s, n);
+        return n === 1 ? s : `${s}-${n}`;
+    };
+};