@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/dist/commands/pull.js

@@ -0,0 +1,549 @@
+import { resolve } from 'node:path';
+import { bool, int, str, requirePositional } from "../cli/args.js";
+import { mkdirp, writeFile, writeJson } from "../util/fsx.js";
+import { bold, dim, green, info, ok, out, step, UserError, warn, yellow } from "../util/log.js";
+import { fullCoverage } from "../model/payload.js";
+import { unpack } from "../codec/unpack.js";
+import { Progress } from "../util/tui.js";
+import { assertRoundTrip } from "../codec/roundtrip.js";
+import { discover, resolveRepo } from "../pipefy/discovery.js";
+import { pullAndWriteAgents } from "./agents.js";
+import { foldFreshBehaviors, foldBehaviorsIntoEnvelope } from "../workspace/agents.js";
+import { repoDir } from "../workspace/layout.js";
+import { emptyLock, upsertRepo, writeLock, writeWorkspace } from "../workspace/lock.js";
+import { writeTree } from "../workspace/write.js";
+import { writeDocs } from "../workspace/docs.js";
+import { readReference } from "../pipefy/reference.js";
+import { loadReference } from "../workspace/reference.js";
+import { baselineFile, paths } from "../workspace/layout.js";
+import { connect } from "./context.js";
+import { RunRecorder, invocation } from "../report/run.js";
+import { pullAndWriteFlows } from "./flows.js";
+import { TOOL } from "../version.js";
+/**
+ * `pipe pull <pipeId>` — the read path.
+ *
+ * Snapshots when the organization has them, reconstruction over GraphQL and the
+ * internal API when it does not. Both produce the same payload shape, so
+ * everything downstream is identical; only `_meta.json` and the coverage map
+ * record which one happened.
+ *
+ * A pull always costs at least one snapshot when snapshots are used, because a
+ * snapshot of an unchanged pipe still creates a new row and a new S3 object
+ * (PLAN.md §1.1). `--reuse-snapshot` uses the newest complete one instead, which
+ * costs nothing.
+ */
+export const help = `pipe pull <pipeId> [options]
+
+  --out <dir>          workspace directory (default: ./<pipe-name>-workspace)
+  --depth <n>          how far to walk connected repos (default 1)
+  --org <id>           organization id, for the internal automations query
+  --reuse-snapshot     use the newest complete snapshot instead of creating one
+  --no-snapshot        force GraphQL reconstruction even if snapshots exist
+  --no-fallback        if a snapshot read fails, fail rather than reconstruct over GraphQL
+  --no-internal        skip the internal API (automations and jumps become unknown)
+  --label <text>       label the snapshot this pull creates
+  --skip-roundtrip     do not run the codec self-check (not recommended)
+  --no-flows           skip the pipe's iPaaS flows (they are read by default)
+  --report             write a run report into runs/ (payload copy included)
+  --from-file <path>   build the workspace from an exported payload instead of the
+                       network. Pairs with \`pipe export\`, needs no token, and is how
+                       you work on a pipe you can only read once.`;
+export const run = async (p) => {
+    const fromFile = str(p, 'from-file');
+    if (fromFile)
+        return pullFromFile(p, fromFile);
+    const repoIdArg = requirePositional(p, 0, 'a pipe or database id');
+    const depth = int(p, 'depth', 1);
+    const forceReconstruct = bool(p, 'no-snapshot');
+    const noInternal = bool(p, 'no-internal');
+    const reuseSnapshot = bool(p, 'reuse-snapshot');
+    const skipRoundTrip = bool(p, 'skip-roundtrip');
+    const noFallback = bool(p, 'no-fallback');
+    const label = str(p, 'label');
+    const startedAt = new Date();
+    const net = await connect(p);
+    const caps = await net.capabilities();
+    const useSnapshots = caps.snapshots && !forceReconstruct;
+    /**
+     * Resolve the argument before anything else uses it.
+     *
+     * A database answers to two ids — the numeric internal one that connector
+     * fields carry, and the api id that the API returns — so both spellings have
+     * to work on the command line. Everything downstream keys on the numeric form
+     * (`discover`, the caches, `emptyLock`, `baselineFile`), so the raw argument is
+     * resolved once here and never threaded past this point. That is also what
+     * stops one database being pulled twice under two identities.
+     */
+    const resolved = await resolveRepo(net.client, repoIdArg);
+    if (!resolved) {
+        throw new UserError(`"${repoIdArg}" is not a repo this token can see`, 'pass a pipe id, a database id, or a database api id such as dzmxcuxz');
+    }
+    const rootRepoId = resolved.id;
+    info('');
+    info(bold(`pipe pull ${rootRepoId}` +
+        (resolved.kind === 'table' ? ` ${dim(`database ${resolved.apiId}`)}` : '')));
+    info(dim(`read path: ${useSnapshots ? (reuseSnapshot ? 'existing snapshots' : 'new snapshots') : 'GraphQL reconstruction'}` +
+        `${caps.snapshots ? '' : ' (this endpoint has no snapshots)'}` +
+        ` · depth ${depth}${noInternal ? ' · internal API skipped' : ''}`));
+    info('');
+    /**
+     * One read of one repo, whichever path applies, cached for discovery reuse.
+     *
+     * Failures are cached too. Discovery reads a repo and then the write loop
+     * reads it again; without caching the failure, a repo that could not be read
+     * gets a *second* snapshot created for it — and a snapshot is a fresh S3
+     * object every time (PLAN.md §1.1). One failed pull should cost one snapshot,
+     * not two.
+     */
+    const cache = new Map();
+    const failed = new Set();
+    const readRepo = async (ref) => {
+        const hit = cache.get(ref.id);
+        if (hit)
+            return hit;
+        if (failed.has(ref.id))
+            return null;
+        try {
+            let env;
+            /**
+             * Databases take the snapshot path too.
+             *
+             * This used to refuse them, on the grounds that ask 10 — whether
+             * `createRepoSnapshot` accepts a table id — was untested and nobody wanted
+             * to find out on a client's data. It was tested on a five-record throwaway:
+             * it does, `SnapshotClient` needed no change because it reaches snapshots
+             * through `pipe(id:)`, and the payload that comes back has the same twenty
+             * relation arrays a pipe's does (VALIDATION.md §3g).
+             */
+            if (useSnapshots) {
+                try {
+                    env = await readViaSnapshot(net, ref, { reuseSnapshot, label });
+                }
+                catch (e) {
+                    /**
+                     * A failed snapshot read falls back to reconstruction rather than
+                     * leaving the repo out. Found live: Pipefy's storage answered every
+                     * signed snapshot URL with HTTP 500 — the creation succeeded, the
+                     * download did not, on every pipe tried — and the pull wrote a
+                     * workspace with no pipe in it. Reconstruction is less complete, and
+                     * says so per group: what it cannot see is `unknown`, never empty, so
+                     * the fallback cannot license a delete.
+                     */
+                    if (noFallback)
+                        throw e;
+                    warn(`snapshot read failed for ${ref.kind} ${ref.id} (${ref.name ?? '?'}): ${e.message} — ` +
+                        'reading it over GraphQL instead (--no-fallback to stop here)');
+                    env = await net.reconstructor.reconstruct(ref.id, {
+                        organizationId: net.organizationId,
+                        noInternal,
+                    });
+                }
+            }
+            else {
+                env = await net.reconstructor.reconstruct(ref.id, {
+                    organizationId: net.organizationId,
+                    noInternal,
+                });
+            }
+            cache.set(ref.id, env);
+            return env;
+        }
+        catch (e) {
+            failed.add(ref.id);
+            warn(`could not read ${ref.kind} ${ref.id} (${ref.name ?? '?'}): ${e.message}`);
+            return null;
+        }
+    };
+    /**
+     * A pull is mostly waiting: ~63s per snapshot, plus an N+1 automation read on
+     * the reconstruction path. One task per repo, with the current stage as its
+     * detail, is what makes that legible rather than looking hung.
+     */
+    const ui = new Progress({ title: `pulling repo ${rootRepoId}` });
+    ui.add({ id: 'discover', label: 'discovering connected repos', state: 'running' });
+    ui.start();
+    const repoTask = (ref) => {
+        const id = `repo:${ref.id}`;
+        if (!ui.has(id))
+            ui.add({ id, label: `${ref.kind} ${ref.id} ${ref.name ?? ''}`.trim(), depth: 1 });
+        return id;
+    };
+    let currentTask = null;
+    net.snapshots.onProgress = (text) => {
+        if (currentTask)
+            ui.update(currentTask, { detail: text });
+    };
+    const discovery = await discover(net.client, rootRepoId, {
+        depth,
+        read: async (ref) => {
+            currentTask = repoTask(ref);
+            ui.update(currentTask, { state: 'running', detail: 'reading' });
+            return (await readRepo(ref))?.payload ?? null;
+        },
+    });
+    ui.update('discover', {
+        state: 'done',
+        detail: `${discovery.repos.length} repo${discovery.repos.length === 1 ? '' : 's'}`,
+    });
+    const rootRef = discovery.repos.find((r) => r.id === rootRepoId);
+    const outDir = resolve(str(p, 'out') ?? `${slugName(rootRef.name ?? String(rootRepoId))}-workspace`);
+    /**
+     * The root repo is the workspace. Without it there is nothing to validate,
+     * diff or plan against — and writing lock.json and workspace.json anyway
+     * did worse than produce an empty directory: re-pulling into an existing
+     * workspace replaced its lock with one that no longer listed the pipe, so
+     * the next diff had no baseline. This used to finish with exit code 0 and a
+     * "next: pipe validate", which scripts and agents believed.
+     */
+    if (!(await readRepo(rootRef))) {
+        ui.stop();
+        throw new UserError(`could not read the root repo ${rootRepoId}${rootRef.name ? ` (${rootRef.name})` : ''} — nothing was written to ${outDir}`, useSnapshots && noFallback
+            ? 'drop --no-fallback to read it over GraphQL, or run with --verbose for the cause'
+            : 'run with --verbose for the cause');
+    }
+    await mkdirp(outDir);
+    const lock = emptyLock(rootRepoId, net.organizationId, depth);
+    lock.edges = discovery.edges;
+    const trees = [];
+    const sources = new Set();
+    const flowSummaries = [];
+    const flowNotes = [];
+    const agentNotes = [];
+    for (const ref of discovery.repos) {
+        let env = await readRepo(ref);
+        if (!env)
+            continue;
+        if (!skipRoundTrip) {
+            const rt = assertRoundTrip(env);
+            if (!rt.ok) {
+                warn(`codec round trip is not clean for ${ref.kind} ${ref.id}:`);
+                for (const d of rt.differences.slice(0, 8))
+                    warn(`   ${d.where}: ${d.detail}`);
+                warn('planning will refuse on this repo until the codec is fixed — see src/codec/');
+            }
+        }
+        const tree = unpack(env);
+        const task = repoTask(ref);
+        ui.update(task, { state: 'running', detail: 'writing files' });
+        const dir = repoDir(outDir, ref);
+        /**
+         * The repo's AI agents, read and written *before* the tree — agents.json
+         * files must exist and `automations/` has to know which rows are actually
+         * behaviors before `writeTree` decides where each one goes.
+         *
+         * Not in the payload at all (ROUTE-B-V2.md ask 5), so fetched separately and
+         * kept in `agents/`, mirroring `flows/`. Recording whether the read
+         * succeeded is what lets the validator distinguish "this pipe has no
+         * agents" from "I could not read them" — and only refuse an AI-referencing
+         * automation in the first case.
+         */
+        if (ref.kind === 'pipe') {
+            ui.update(task, { detail: 'reading AI agents' });
+            try {
+                const agentsSection = await pullAndWriteAgents(net.client, ref.id, tree.repo['uuid'], dir, {
+                    workspaceRoot: outDir,
+                });
+                if (agentsSection.meta.coverage === 'complete') {
+                    tree.automations = foldFreshBehaviors(tree.automations, agentsSection.agents);
+                    /**
+                     * The baseline gets the same replacement, or it is left holding the
+                     * snapshot's stub forever — `pipe diff` would report a phantom
+                     * change on every behavior on every pull, since the workspace files
+                     * and the baseline could never agree.
+                     */
+                    env = foldBehaviorsIntoEnvelope(env, agentsSection.agents);
+                }
+                else {
+                    agentNotes.push(`${ref.name ?? ref.id}: agents unknown — ${agentsSection.meta.reason ?? agentsSection.meta.notes.join('; ') ?? 'not readable'}`);
+                }
+            }
+            catch (e) {
+                agentNotes.push(`${ref.name ?? ref.id}: agents could not be read — ${e.message}`);
+            }
+        }
+        trees.push(tree);
+        sources.add(env.source);
+        const written = await writeTree(dir, tree);
+        await writeJson(baselineFile(outDir, ref.id), env);
+        upsertRepo(lock, ref, outDir, tree);
+        /**
+         * The repo's iPaaS flows, read as part of the same pull.
+         *
+         * Not behind a flag because they are not an extra: a flow lives in exactly
+         * one pipe's iPaaS workspace, and this pipe's own webhook URLs carry the ids
+         * of its flows. Reading the automations without them gives a wrong picture of
+         * what the process does — iPaaS is where a process reaches other pipes and
+         * other systems, which the automation engine cannot.
+         *
+         * A pipe without iPaaS costs one refused token mint and records 'unknown'.
+         */
+        if (!bool(p, 'no-flows') && ref.kind === 'pipe') {
+            ui.update(task, { detail: 'reading iPaaS flows' });
+            try {
+                const flowsSection = await pullAndWriteFlows(net.ipaas, ref.id, dir, { workspaceRoot: outDir });
+                if (flowsSection.meta.coverage === 'complete') {
+                    flowSummaries.push(`${ref.name ?? ref.id}: ${flowsSection.flows.length} flow(s), ${flowsSection.connections.length} connection(s)`);
+                    for (const n of flowsSection.meta.notes)
+                        flowNotes.push(n);
+                }
+                else {
+                    flowNotes.push(`${ref.name ?? ref.id}: flows unknown — ${flowsSection.meta.reason ?? 'not readable'}`);
+                }
+            }
+            catch (e) {
+                flowNotes.push(`${ref.name ?? ref.id}: flows could not be read — ${e.message}`);
+            }
+        }
+        const gaps = Object.entries(env.coverage).filter(([, c]) => c !== 'complete');
+        const fieldCount = tree.phases.reduce((n, ph) => n + ph.fields.length, 0);
+        /**
+         * A database is counted in its own terms.
+         *
+         * Its payload is a pipe's, so it does have phases — a start form plus one
+         * per record status. Reporting "3 phases" for a database with three columns
+         * and two statuses would be true and useless, so the statuses are named as
+         * what they are.
+         */
+        const detail = ref.kind === 'table'
+            ? `${fieldCount} fields, ${Math.max(0, tree.phases.length - 1)} record statuses, ${written.length} files`
+            : `${tree.phases.length} phases, ${fieldCount} fields, ` +
+                `${tree.automations.length} automations, ${written.length} files`;
+        ui.update(task, {
+            state: 'done',
+            detail: detail + (gaps.length ? `, ${gaps.length} groups partial or unknown` : ''),
+        });
+    }
+    await writeLock(outDir, lock);
+    await writeWorkspace(outDir, {
+        name: rootRef.name ?? String(rootRepoId),
+        createdAt: new Date().toISOString(),
+        rootRepoId,
+        organizationId: net.organizationId,
+        depth,
+        lastPullSource: sources.size > 1 ? 'mixed' : (sources.values().next().value ?? 'reconstructed'),
+        tool: { ...TOOL },
+    });
+    /**
+     * Read the closed sets while the client is open. Two queries, and it is what
+     * lets validate refuse a bad enum value or automation parameter offline with
+     * the value named, instead of the API answering `is invalid` partway through
+     * an apply.
+     */
+    const reference = await readReference(net.client, rootRepoId);
+    if (reference)
+        await writeJson(paths(outDir).reference, reference);
+    await writeDocs(outDir, lock, trees, caps, reference);
+    ui.stop();
+    /**
+     * A pull records itself only when asked. The workspace it just wrote already
+     * *is* the pipe, and the baseline envelope under `.ppc/baseline/` already is
+     * the payload, so a report here duplicates both. It earns its place when a
+     * sequence of runs is being kept side by side: this is the one that captures
+     * the pipe as it was before anyone edited anything.
+     */
+    if (bool(p, 'report')) {
+        const rootEnv = cache.get(rootRepoId) ?? null;
+        const rec = new RunRecorder('pull', {
+            workspace: outDir,
+            repo: {
+                id: rootRepoId,
+                uuid: rootRef.uuid ?? null,
+                name: rootRef.name ?? String(rootRepoId),
+                kind: rootRef.kind,
+            },
+            command: invocation(),
+            startedAt,
+        });
+        rec.after(rootEnv);
+        rec.note(`${discovery.repos.length} repo(s) discovered at depth ${depth}; ` +
+            `${trees.length} written (${lock.repos.filter((r) => r.kind === 'table').length} database(s))`);
+        for (const t of trees)
+            for (const n of t.meta.notes)
+                rec.note(n);
+        const res = await rec.write(rootEnv ? 'ok' : 'failed', rootEnv
+            ? `pulled ${trees.length} repo(s) via ${[...sources].join(' + ')}`
+            : `could not read the root repo ${rootRepoId}`);
+        if (res?.error)
+            warn(`could not write the run report: ${res.error}`);
+        else if (res)
+            info(dim(`run recorded in runs/${rec.id}/`));
+    }
+    info('');
+    out(bold(outDir));
+    out(dim('  AGENTS.md · MAPPING.md · CAPABILITIES.md · REFERENCE.md written'));
+    if (flowSummaries.length) {
+        info('');
+        for (const s of flowSummaries)
+            ok(`iPaaS ${s}`);
+    }
+    for (const n of flowNotes)
+        info(dim(`   ${n}`));
+    for (const n of agentNotes)
+        info(dim(`   ${n}`));
+    const databases = lock.repos.filter((r) => r.kind === 'table');
+    if (databases.length) {
+        info('');
+        ok(`${databases.length} database(s): ` +
+            databases.map((r) => `${r.name} (${r.apiId})`).join(', '));
+        info(dim('   a database is a repo: its columns are fields on a start form, and the phases'));
+        info(dim('   after it are record statuses. Neither the statuses nor the records can be written.'));
+    }
+    const anyUnknown = lock.repos.flatMap((r) => Object.entries(r.coverage).filter(([, c]) => c === 'unknown').map(([e]) => e));
+    if (anyUnknown.length) {
+        const distinct = [...new Set(anyUnknown)].sort();
+        info('');
+        warn(`${distinct.length} entity group(s) are unknown, not empty: ${distinct.join(', ')}`);
+        info(dim('   They are never diffed and never applied. See AGENTS.md for what that means for edits.'));
+    }
+    const hasSecrets = trees.some((t) => t.webhooks.length > 0 || JSON.stringify(t.automations).includes('authentication'));
+    if (hasSecrets) {
+        info('');
+        warn('this workspace contains webhook URLs or HTTP-request credentials — possession is authorization');
+        info(dim('   a .gitignore was written; do not commit or share these files'));
+    }
+    info('');
+    info(`${yellow('next')}  ${dim('cd')} ${outDir}  ${dim('&&')}  pipe validate`);
+};
+const readViaSnapshot = async (net, ref, opts) => {
+    let versionId;
+    if (opts.reuseSnapshot) {
+        const latest = await net.snapshots.latestComplete(ref.id);
+        if (!latest)
+            throw new Error('no complete snapshot exists to reuse — drop --reuse-snapshot');
+        versionId = latest.versionId;
+        step(`reusing snapshot ${versionId.slice(0, 8)} of ${ref.name ?? ref.id}`);
+    }
+    else {
+        versionId = await net.snapshots.create(ref.id);
+        await net.snapshots.waitFor(ref.id, versionId);
+        if (opts.label)
+            await net.snapshots.rename(ref.id, versionId, opts.label);
+    }
+    const { payload, gzip } = await net.snapshots.download(ref.id, versionId);
+    return {
+        source: 'snapshot',
+        versionId,
+        readAt: new Date().toISOString(),
+        repoKind: ref.kind,
+        coverage: fullCoverage('complete'),
+        notes: [],
+        payload,
+        ...(gzip ? { _gzip: gzip } : {}),
+    };
+};
+/*
+ * There was a `cacheSnapshotBytes` here, writing the raw .gz into
+ * `.ppc/snapshots/`. Nothing ever called it, so the directory was never created
+ * and the feature it implied — a local snapshot cache — did not exist.
+ *
+ * It is not missed. A re-pull already costs nothing with `--reuse-snapshot`,
+ * which reads the newest complete snapshot Pipefy already holds, and `pipe export`
+ * plus `pipe pull --from-file` covers working with no network at all. The baseline
+ * envelope keeps the payload itself, which is the part anything downstream reads.
+ */
+const slugName = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'pipefy';
+export const writeRawPayload = (path, env) => writeFile(path, JSON.stringify(env.payload, null, 2));
+/**
+ * Build a workspace from an exported payload, with no network at all.
+ *
+ * Two reasons this is a first-class path rather than a test hook: a snapshot
+ * costs ~63s and a fresh S3 object every time (PLAN.md §1.1), and an FDE often
+ * gets one read of a client's pipe and then works offline. `pipe export` writes
+ * the file; this consumes it. Connected repos are recorded as edges but cannot
+ * be pulled, so they are reported rather than silently skipped.
+ */
+const pullFromFile = async (p, fromFile) => {
+    const { readJson } = await import("../util/fsx.js");
+    const { edgesFromPayload } = await import("../pipefy/discovery.js");
+    const raw = await readJson(resolve(fromFile));
+    const bare = !('payload' in raw && raw['payload']);
+    const env = bare
+        ? {
+            /**
+             * A file with no envelope gets the only usable assumption — that every
+             * group was read in full — because the alternative, marking them all
+             * unknown, makes the file undiffable and unappliable.
+             *
+             * It is an assumption and it is announced below, because if the export
+             * came from a reconstruction it is wrong in the dangerous direction: a
+             * group nobody could read looks empty, and empty means delete.
+             */
+            source: 'snapshot',
+            versionId: null,
+            readAt: new Date().toISOString(),
+            repoKind: 'pipe',
+            coverage: fullCoverage('complete'),
+            notes: [`read from ${fromFile}, not from the API`, 'no coverage envelope: every group assumed fully read'],
+            payload: raw,
+        }
+        : raw;
+    const repoIdNum = Number(env.payload.id);
+    const rootRef = {
+        kind: env.repoKind,
+        id: repoIdNum,
+        apiId: String(repoIdNum),
+        name: String(env.payload['name'] ?? repoIdNum),
+        uuid: env.payload['uuid'] ?? null,
+        via: ['file'],
+        depth: 0,
+    };
+    const outDir = resolve(str(p, 'out') ?? `${slugName(rootRef.name ?? String(repoIdNum))}-workspace`);
+    await mkdirp(outDir);
+    info('');
+    info(bold(`pipe pull --from-file ${fromFile}`));
+    info(dim(`read path: file (${env.source} payload) · no network`));
+    info('');
+    if (bare) {
+        warn(`${fromFile} is a bare payload with no coverage envelope`);
+        info(dim('   every entity group is assumed to have been read in full, so an absent'));
+        info(dim('   webhook or automation will be treated as one to delete. If this came from'));
+        info(dim('   `pipe export` on an endpoint without snapshots, re-export with --envelope.'));
+        info('');
+    }
+    if (!bool(p, 'skip-roundtrip')) {
+        const rt = assertRoundTrip(env);
+        if (rt.ok)
+            ok('codec round trip clean');
+        else {
+            warn('codec round trip is not clean for this payload:');
+            for (const d of rt.differences.slice(0, 8))
+                warn(`   ${d.where}: ${d.detail}`);
+        }
+    }
+    const tree = unpack(env);
+    const lock = emptyLock(repoIdNum, str(p, 'org') ?? null, 0);
+    lock.edges = edgesFromPayload(env.payload).map((e) => ({ from: repoIdNum, ...e }));
+    const dir = repoDir(outDir, rootRef);
+    const written = await writeTree(dir, tree);
+    await writeJson(baselineFile(outDir, repoIdNum), env);
+    upsertRepo(lock, rootRef, outDir, tree);
+    await writeLock(outDir, lock);
+    await writeWorkspace(outDir, {
+        name: rootRef.name ?? String(repoIdNum),
+        createdAt: new Date().toISOString(),
+        rootRepoId: repoIdNum,
+        organizationId: str(p, 'org') ?? null,
+        depth: 0,
+        lastPullSource: env.source,
+        tool: { ...TOOL },
+    });
+    await writeDocs(outDir, lock, [tree], null, await loadReference(outDir));
+    ok(`${rootRef.kind} ${repoIdNum} ${green(rootRef.name ?? '')} — ${tree.phases.length} phases, ` +
+        `${tree.phases.reduce((n, ph) => n + ph.fields.length, 0)} fields, ${tree.automations.length} automations ` +
+        dim(`(${written.length} files)`));
+    const unreachable = [...new Set(lock.edges.map((e) => e.to))].filter((id) => id !== repoIdNum);
+    if (unreachable.length) {
+        info('');
+        warn(`this pipe connects to ${unreachable.length} other repo(s) that a file pull cannot fetch: ${unreachable.join(', ')}`);
+        info(dim('   export those too and pull them into their own workspaces, or pull from the API with --depth'));
+    }
+    info('');
+    out(bold(outDir));
+    info(`${yellow('next')}  ${dim('cd')} ${outDir}  ${dim('&&')}  pipe validate`);
+    return 0;
+};

package/dist/commands/runs.js

@@ -0,0 +1,74 @@
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { bool, str } from "../cli/args.js";
+import { bold, dim, green, info, out, red, UserError, yellow } from "../util/log.js";
+import { exists } from "../util/fsx.js";
+import { listRuns, runDir } from "../report/run.js";
+import { resolveWorkspace } from "./context.js";
+export const help = `pipe runs [workspace] [options]
+
+  --show <id>    print one run's report
+  --last         print the most recent run's report
+  --kind <kind>  only pull / apply / dry-run / verify
+  --failed       only runs that failed or partly applied
+  --json         machine-readable
+
+Every run folder holds report.md (readable, no credentials), run.json, and a copy
+of the pipe and its integration surface as of the end of that run.`;
+export const run = async (p) => {
+    const root = await resolveWorkspace(p);
+    const runs = await listRuns(root);
+    const showId = str(p, 'show');
+    if (showId || bool(p, 'last')) {
+        const record = showId
+            ? (runs.find((r) => r.id === showId) ?? runs.find((r) => r.id.includes(showId)))
+            : runs[runs.length - 1];
+        if (!record) {
+            throw new UserError(showId ? `no run "${showId}" in ${root}` : `no runs recorded in ${root} yet`, 'run `pipe runs` to list what is there');
+        }
+        const path = join(runDir(root, record.id), 'report.md');
+        if (!(await exists(path)))
+            throw new UserError(`${record.id} has no report.md`);
+        out(await fs.readFile(path, 'utf8'));
+        return 0;
+    }
+    let filtered = runs;
+    const kind = str(p, 'kind');
+    if (kind)
+        filtered = filtered.filter((r) => r.kind === kind);
+    if (bool(p, 'failed'))
+        filtered = filtered.filter((r) => r.outcome === 'failed' || r.outcome === 'partial');
+    if (bool(p, 'json')) {
+        out(JSON.stringify(filtered, null, 2));
+        return 0;
+    }
+    if (!filtered.length) {
+        info(runs.length ? 'no runs match that filter' : `no runs recorded in ${root} yet`);
+        return 0;
+    }
+    out('');
+    out(bold(`${filtered.length} run${filtered.length === 1 ? '' : 's'} in ${root}`));
+    out('');
+    for (const r of filtered) {
+        out(`  ${dim(r.startedAt.replace('T', ' ').slice(0, 19))}  ${outcomeTag(r)}  ${bold(r.kind.padEnd(8))} ${r.summary}`);
+        const parts = [
+            r.counts.steps ? `${r.counts.done}/${r.counts.steps} steps` : null,
+            r.counts.blocked ? red(`${r.counts.blocked} blocked`) : null,
+            r.verification ? (r.verification.ok ? 'verified' : red('verify failed')) : null,
+            `${(r.durationMs / 1000).toFixed(1)}s`,
+        ].filter(Boolean);
+        out(`    ${dim(r.id)}  ${dim(parts.join(' · '))}`);
+    }
+    out('');
+    out(dim(`  pipe runs --last            the newest report in full`));
+    out(dim(`  pipe runs --show <run id>   any of them`));
+    out('');
+    return 0;
+};
+const outcomeTag = (r) => r.outcome === 'ok'
+    ? green('ok      ')
+    : r.outcome === 'partial'
+        ? yellow('partial ')
+        : r.outcome === 'failed'
+            ? red('failed  ')
+            : dim(r.outcome.padEnd(8));