@pipefy/pipefy-process-coder 0.1.0

package/src/commands/pull.ts

@@ -0,0 +1,567 @@
+import { resolve } from 'node:path';
+import { bool, int, str, requirePositional, type Parsed } from '../cli/args.ts';
+import { mkdirp, writeFile, writeJson } from '../util/fsx.ts';
+import { bold, dim, green, info, ok, out, step, UserError, warn, yellow } from '../util/log.ts';
+import { fullCoverage, type PayloadEnvelope } from '../model/payload.ts';
+import { unpack } from '../codec/unpack.ts';
+import { Progress } from '../util/tui.ts';
+import { assertRoundTrip } from '../codec/roundtrip.ts';
+import { discover, resolveRepo, type RepoRef } from '../pipefy/discovery.ts';
+import { pullAndWriteAgents } from './agents.ts';
+import { foldFreshBehaviors, foldBehaviorsIntoEnvelope } from '../workspace/agents.ts';
+import { repoDir } from '../workspace/layout.ts';
+import { emptyLock, upsertRepo, writeLock, writeWorkspace } from '../workspace/lock.ts';
+import { writeTree } from '../workspace/write.ts';
+import { writeDocs } from '../workspace/docs.ts';
+import { readReference } from '../pipefy/reference.ts';
+import { loadReference } from '../workspace/reference.ts';
+import { baselineFile, paths } from '../workspace/layout.ts';
+import { connect } from './context.ts';
+import type { Tree } from '../model/tree.ts';
+import { RunRecorder, invocation } from '../report/run.ts';
+import { pullAndWriteFlows } from './flows.ts';
+
+/**
+ * `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-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: Parsed) => {
+  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 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<number, PayloadEnvelope>();
+  const failed = new Set<number>();
+  const readRepo = async (ref: RepoRef): Promise<PayloadEnvelope | null> => {
+    const hit = cache.get(ref.id);
+    if (hit) return hit;
+    if (failed.has(ref.id)) return null;
+
+    try {
+      let env: PayloadEnvelope;
+      /**
+       * 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) {
+        env = await readViaSnapshot(net, ref, { reuseSnapshot, label });
+      } 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 as Error).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: RepoRef) => {
+    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: string | null = 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) as RepoRef;
+  const outDir = resolve(str(p, 'out') ?? `${slugName(rootRef.name ?? String(rootRepoId))}-workspace`);
+  await mkdirp(outDir);
+
+  const lock = emptyLock(rootRepoId, net.organizationId, depth);
+  lock.edges = discovery.edges;
+
+  const trees: Tree[] = [];
+  const sources = new Set<string>();
+
+  const flowSummaries: string[] = [];
+  const flowNotes: string[] = [];
+  const agentNotes: string[] = [];
+
+  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'] as string | undefined, 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 as Error).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 as Error).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') as 'snapshot' | 'reconstructed'),
+    tool: { name: 'pipefy-process-coder', version: '0.1.0' },
+  });
+  /**
+   * 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: Awaited<ReturnType<typeof connect>>,
+  ref: RepoRef,
+  opts: { reuseSnapshot: boolean; label?: string },
+): Promise<PayloadEnvelope> => {
+  let versionId: string;
+  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 } : {}),
+  } as PayloadEnvelope;
+};
+
+/*
+ * 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: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'pipefy';
+
+export const writeRawPayload = (path: string, env: PayloadEnvelope) => 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: Parsed, fromFile: string) => {
+  const { readJson } = await import('../util/fsx.ts');
+  const { edgesFromPayload } = await import('../pipefy/discovery.ts');
+  const raw = await readJson<PayloadEnvelope | Record<string, unknown>>(resolve(fromFile));
+
+  const bare = !('payload' in raw && raw['payload']);
+  const env: PayloadEnvelope = 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 as PayloadEnvelope['payload'],
+      }
+    : (raw as PayloadEnvelope);
+
+  const repoIdNum = Number(env.payload.id);
+  const rootRef: RepoRef = {
+    kind: env.repoKind,
+    id: repoIdNum,
+    apiId: String(repoIdNum),
+    name: String(env.payload['name'] ?? repoIdNum),
+    uuid: (env.payload['uuid'] as string | undefined) ?? 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: { name: 'pipefy-process-coder', version: '0.1.0' },
+  });
+  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/src/commands/runs.ts

@@ -0,0 +1,83 @@
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { bool, str, type Parsed } from '../cli/args.ts';
+import { bold, dim, green, info, out, red, UserError, yellow } from '../util/log.ts';
+import { exists } from '../util/fsx.ts';
+import { listRuns, runDir, type RunRecord } from '../report/run.ts';
+import { resolveWorkspace } from './context.ts';
+
+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: Parsed) => {
+  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: RunRecord) =>
+  r.outcome === 'ok'
+    ? green('ok      ')
+    : r.outcome === 'partial'
+      ? yellow('partial ')
+      : r.outcome === 'failed'
+        ? red('failed  ')
+        : dim(r.outcome.padEnd(8));