@pipefy/pipefy-process-coder 0.1.0

package/src/commands/misc.ts

@@ -0,0 +1,644 @@
+import { resolve } from 'node:path';
+import { loadReference } from '../workspace/reference.ts';
+import { bool, int, requirePositional, str, type Parsed } from '../cli/args.ts';
+import { ENDPOINTS, writeToken } from '../config.ts';
+import { readJson, writeFile, writeJson } from '../util/fsx.ts';
+import { UserError, bold, dim, green, info, ok, out, red, step, warn, yellow } from '../util/log.ts';
+import { ENTITY_NAMES, type PayloadEnvelope } from '../model/payload.ts';
+import { unpack } from '../codec/unpack.ts';
+import { pack } from '../codec/pack.ts';
+import { assertRoundTrip, compare } from '../codec/roundtrip.ts';
+import { missingMutations } from '../pipefy/capability.ts';
+import { RECONSTRUCTION_GAPS } from '../pipefy/reconstruct.ts';
+import { readTree } from '../workspace/read.ts';
+import { registryRows } from '../apply/registry.ts';
+import { validateTree, renderFindings, blockingErrors } from '../validate/index.ts';
+import { connect, openWorkspace } from './context.ts';
+
+// ── login ────────────────────────────────────────────────────────────────────
+
+export const loginHelp = `pipe login [options]
+
+  With no options: runs the Pipefy browser sign-in through the official AI
+  toolkit (github.com/pipefy/ai-toolkit), which stores the session in your OS
+  keychain. That one session is then shared by \`pipe\`, the \`pipefy\` CLI and the
+  Pipefy MCP server — this tool never holds a long-lived credential of its own.
+
+  --token <token>   store a personal API token in ~/.ppc/credentials.json
+                    instead. For machines without the toolkit, and for CI.
+  --org <id>        pin the organization used by the internal automations query
+  --device          pass --device to the toolkit flow (headless machines)
+  --status          just report which credential would be used
+
+  Resolution order: PIPEFY_TOKEN in the environment, then the toolkit, then
+  ~/.ppc/credentials.json.`;
+
+export const login = async (p: Parsed) => {
+  if (bool(p, 'status')) return loginStatus();
+
+  const token = str(p, 'token');
+
+  // ── the intended path: delegate to the toolkit's OAuth flow ───────────────
+  if (!token) {
+    const { inspectToolkit, runToolkitLogin, INSTALL_HINT } = await import('../pipefy/toolkit.ts');
+    const toolkit = await inspectToolkit();
+    if (!toolkit.installed) {
+      throw new UserError(
+        'the Pipefy AI toolkit is not installed, so there is no browser login to run',
+        `${INSTALL_HINT} — or use \`pipe login --token <token>\` for a personal API token`,
+      );
+    }
+
+    step('running `pipefy auth login` (browser sign-in)');
+    const code = await runToolkitLogin(bool(p, 'device') ? ['--device'] : []);
+    if (code !== 0) {
+      throw new UserError(`the toolkit login exited with code ${code}`, 'run `pipefy auth login` directly to see its output');
+    }
+    return loginStatus();
+  }
+
+  // ── the fallback: this tool's own token store ─────────────────────────────
+  const { PipefyClient } = await import('../pipefy/client.ts');
+  const client = new PipefyClient({ token });
+  const me = await client.tryRaw<{ me: { name?: string; email?: string } | null }>('query { me { name email } }', undefined, 'me');
+  if (!me?.me) throw new UserError('that token was rejected by ' + ENDPOINTS.graphql);
+
+  const orgs = await client.tryRaw<{ organizations: Array<{ id: string; name: string }> | null }>(
+    'query { organizations { id name } }',
+    undefined,
+    'organizations',
+  );
+  const org = str(p, 'org') ?? orgs?.organizations?.[0]?.id;
+
+  const path = await writeToken(token, org);
+  ok(`token stored for ${me.me.name ?? me.me.email ?? 'this account'} — ${dim(path)}`);
+  if (orgs?.organizations?.length) {
+    info(dim('organizations: ' + orgs.organizations.map((o) => `${o.id} (${o.name})`).join(', ')));
+    if (org) info(dim(`using organization ${org} for internal automation queries`));
+  }
+  warn('a personal API token outranks nothing: PIPEFY_TOKEN and the toolkit session are both checked first');
+  return 0;
+};
+
+/** Which credential would be used, and who it belongs to. */
+const loginStatus = async () => {
+  const { resolveCredential } = await import('../config.ts');
+  const credential = await resolveCredential();
+  if (!credential) {
+    warn('no credential found');
+    info(dim('  run `pipe login`, `pipe login --token <token>`, or set PIPEFY_TOKEN'));
+    return 1;
+  }
+
+  const { PipefyClient } = await import('../pipefy/client.ts');
+  const client = new PipefyClient({ token: credential.token });
+  const me = await client.tryRaw<{ me: { name?: string; email?: string } | null }>(
+    'query { me { name email } }',
+    undefined,
+    'me',
+  );
+
+  ok(
+    `signed in as ${me?.me?.name ?? me?.me?.email ?? 'an unknown identity'} ` +
+      dim(`via ${credential.source}${credential.detail ? ` — ${credential.detail}` : ''}`),
+  );
+  if (!me?.me) warn('the credential resolved but the API did not accept it');
+  return me?.me ? 0 : 1;
+};
+
+// ── doctor ───────────────────────────────────────────────────────────────────
+
+export const doctorHelp = `pipe doctor [--repo <pipeId>]
+
+  Reports what this endpoint can actually do, before you start work.
+  With --repo it also probes that pipe's read paths.`;
+
+export const doctor = async (p: Parsed) => {
+  const { resolveCredential } = await import('../config.ts');
+  const { inspectToolkit, toolkitAuthStatus, INSTALL_HINT } = await import('../pipefy/toolkit.ts');
+
+  out(bold('endpoints'));
+  out(`  graphql   ${ENDPOINTS.graphql}`);
+  out(`  internal  ${ENDPOINTS.internal}`);
+
+  out('');
+  out(bold('credential'));
+  const toolkit = await inspectToolkit();
+  const credential = await resolveCredential();
+
+  out(
+    `  toolkit   ${toolkit.installed ? green('installed') : red('not installed')}` +
+      (toolkit.installed ? dim(`  ${toolkit.cliPath ?? toolkit.interpreter}`) : dim(`  ${INSTALL_HINT}`)),
+  );
+  if (toolkit.installed) {
+    const status = await toolkitAuthStatus();
+    if (status) {
+      const identity = status['identity'] as { name?: string; email?: string } | null;
+      out(
+        `  session   ${status['signed_in'] ? green('signed in') : yellow('not signed in')}` +
+          dim(
+            `  ${identity?.name ?? identity?.email ?? ''}` +
+              `${status['auth_source'] ? ` via ${String(status['auth_source'])}` : ''}` +
+              `${status['access_expires_at'] ? `, access expires ${String(status['access_expires_at'])}` : ''}`,
+          ),
+      );
+    } else if (!toolkit.credential.ok) {
+      out(`  session   ${yellow('not signed in')} ${dim(toolkit.credential.message)}`);
+    }
+  }
+  out(
+    `  in use    ${credential ? green(credential.source) : red('none')}` +
+      dim(credential?.detail ? `  ${credential.detail}` : ''),
+  );
+
+  if (!credential) {
+    info('');
+    throw new UserError(
+      'no credential',
+      toolkit.installed ? 'run `pipe login` for the browser flow' : `${INSTALL_HINT}, or \`pipe login --token <token>\``,
+    );
+  }
+
+  const net = await connect(p);
+  const caps = await net.capabilities();
+
+  out('');
+  out(bold('capabilities'));
+  const row = (label: string, present: boolean, consequence: string) =>
+    out(`  ${present ? green('yes') : red(' no')}  ${label.padEnd(24)} ${dim(consequence)}`);
+
+  row('snapshots', caps.snapshots, caps.snapshots ? 'pulls use the snapshot payload' : 'pulls reconstruct over GraphQL');
+  /**
+   * "atomic rollback available" was the old text and it would now be a lie in the
+   * other direction: the mutation exists, and it only accepts the newest
+   * snapshot, so it cannot undo an apply whose own read-back has since become
+   * the newest. The row names the mutation and the constraint instead.
+   */
+  row(
+    caps.restoreMutation ?? 'restore',
+    caps.restoreRepoSnapshot,
+    caps.restoreRepoSnapshot
+      ? caps.restoreLatestOnly
+        ? 'restores the LATEST snapshot only — cannot undo a completed apply'
+        : 'atomic rollback available'
+      : 'no one-command rollback',
+  );
+  row('createRepoDraft', caps.createRepoDraft, caps.createRepoDraft ? 'draft rehearsal possible' : 'no free rehearsal environment');
+  row('importRepoSnapshot', caps.importRepoSnapshot, caps.importRepoSnapshot ? 'Route B is available' : 'writes go through the mutation compiler');
+
+  const missing = missingMutations(caps);
+  out('');
+  out(bold('mutations'));
+  out(`  ${Object.keys(caps.mutations).length - missing.length} of ${Object.keys(caps.mutations).length} present`);
+  if (missing.length) {
+    warn(`missing: ${missing.join(', ')}`);
+    info(dim('   changes needing these will be refused by `pipe plan` rather than attempted'));
+  }
+
+  const repoId = str(p, 'repo');
+  if (repoId) {
+    out('');
+    out(bold(`probing repo ${repoId}`));
+    const jumps = await net.internal.getPhaseSettings(await firstPhaseId(net, repoId));
+    out(`  internal settings endpoint  ${jumps ? green('answers') : red('no answer')}`);
+    const autos = net.organizationId ? await net.internal.listAutomations(net.organizationId, repoId) : null;
+    out(
+      `  internal automations query   ${
+        autos ? green(`answers (${autos.length} automations)`) : net.organizationId ? red('no answer') : yellow('needs --org')
+      }`,
+    );
+  }
+
+  out('');
+  out(bold('internal API'));
+  out(`  status ${net.internal.status === 'ok' ? green('ok') : net.internal.status === 'unavailable' ? red('unavailable') : dim('unknown')}`);
+  info(
+    dim(
+      '  Unversioned, no compatibility contract (PLAN.md §2.1). When it breaks, automation\n' +
+        '  detail and phase-jump editing degrade to unknown rather than failing an apply.',
+    ),
+  );
+
+  if (!caps.snapshots) {
+    out('');
+    out(bold('what a reconstructed pull cannot see'));
+    for (const g of RECONSTRUCTION_GAPS) out(`  ${dim('-')} ${g}`);
+  }
+
+  return 0;
+};
+
+const firstPhaseId = async (net: Awaited<ReturnType<typeof connect>>, repoId: string): Promise<string> => {
+  const data = await net.client.tryRaw<{ pipe: { phases: Array<{ id: string }> } | null }>(
+    'query($id: ID!) { pipe(id: $id) { phases { id } } }',
+    { id: repoId },
+    'first phase',
+  );
+  return data?.pipe?.phases?.[0]?.id ?? '0';
+};
+
+// ── export ───────────────────────────────────────────────────────────────────
+
+export const exportHelp = `pipe export <pipeId> [options]
+
+  Writes one repo's structure as a single snapshot-shaped JSON payload, with no
+  workspace and no tree. This is the standalone exporter: it works whether or not
+  the organization has snapshots, because the reconstruction path produces the
+  same shape.
+
+  --out <file>       write here instead of stdout
+  --no-snapshot      force GraphQL reconstruction
+  --no-internal      skip the internal API
+  --envelope         include the coverage/provenance envelope, not just the payload
+  --pretty           indent the JSON`;
+
+export const exportCmd = async (p: Parsed) => {
+  const repoId = Number(requirePositional(p, 0, 'a pipe id'));
+  const net = await connect(p);
+  const caps = await net.capabilities();
+  const useSnapshot = caps.snapshots && !bool(p, 'no-snapshot');
+
+  let env: PayloadEnvelope;
+  if (useSnapshot) {
+    const { payload, versionId } = await net.snapshots.pull(repoId);
+    const { fullCoverage } = await import('../model/payload.ts');
+    env = {
+      source: 'snapshot',
+      versionId,
+      readAt: new Date().toISOString(),
+      repoKind: 'pipe',
+      coverage: fullCoverage('complete'),
+      notes: [],
+      payload,
+    };
+  } else {
+    env = await net.reconstructor.reconstruct(repoId, {
+      organizationId: net.organizationId,
+      noInternal: bool(p, 'no-internal'),
+    });
+  }
+
+  /**
+   * A bare payload has no provenance, and for a reconstructed read that matters.
+   *
+   * `pull --from-file` cannot tell a payload that was fully read from one where
+   * webhooks or automations were never readable, so it has to assume the former —
+   * and absence then means deletion. Exporting a reconstruction without the
+   * envelope silently converts "I could not see this" into "this does not exist".
+   */
+  if (!bool(p, 'envelope')) {
+    const gaps = Object.entries(env.coverage).filter(([, c]) => c !== 'complete');
+    if (gaps.length) {
+      warn(
+        `${gaps.length} entity group(s) were not fully read, and a bare payload cannot carry that: ` +
+          `${gaps.map(([g]) => g).join(', ')}`,
+      );
+      info(dim('   re-run with --envelope so `pipe pull --from-file` knows what was unreadable,'));
+      info(dim('   otherwise it will treat every absence as a deletion.'));
+    }
+  }
+
+  const body = bool(p, 'envelope') ? env : env.payload;
+  const json = bool(p, 'pretty') ? JSON.stringify(body, null, 2) : JSON.stringify(body);
+
+  const outFile = str(p, 'out');
+  if (outFile) {
+    await writeFile(resolve(outFile), json + '\n');
+    ok(`wrote ${outFile}`);
+    const counts = ENTITY_NAMES.map((n) => `${n} ${env.payload.relations[n]?.length ?? 0}`).join(', ');
+    info(dim(`  ${env.source} · ${counts}`));
+  } else {
+    out(json);
+  }
+  return 0;
+};
+
+// ── roundtrip ────────────────────────────────────────────────────────────────
+
+export const roundtripHelp = `pipe roundtrip <payload.json | workspace>
+
+  The Phase 0 exit criterion: pack(unpack(P)) must equal P under a canonical
+  form. Run it on any exported payload, or on a workspace to check every repo's
+  baseline. A failure means the codec would lose data, and planning is refused.`;
+
+export const roundtrip = async (p: Parsed) => {
+  const target = requirePositional(p, 0, 'a payload file or workspace directory');
+  const path = resolve(target);
+
+  const { stat } = await import('node:fs/promises');
+  const s = await stat(path).catch(() => null);
+  if (!s) throw new UserError(`${path} does not exist`);
+
+  if (s.isFile()) {
+    const raw = await readJson<PayloadEnvelope | { relations?: unknown }>(path);
+    const env: PayloadEnvelope =
+      'payload' in raw && raw.payload
+        ? (raw as PayloadEnvelope)
+        : {
+            source: 'snapshot',
+            versionId: null,
+            readAt: new Date().toISOString(),
+            repoKind: 'pipe',
+            coverage: (await import('../model/payload.ts')).fullCoverage('complete'),
+            notes: [],
+            payload: raw as PayloadEnvelope['payload'],
+          };
+    const result = assertRoundTrip(env);
+    reportRoundTrip(path, result);
+    return result.ok ? 0 : 1;
+  }
+
+  const { root, lock } = await openWorkspace(p);
+  let failures = 0;
+  for (const repo of lock.repos) {
+    const env = await readJson<PayloadEnvelope>(resolve(root, '.ppc', 'baseline', `${repo.id}.json`));
+    const result = assertRoundTrip(env);
+    reportRoundTrip(`${repo.name} (${repo.id})`, result);
+    if (!result.ok) failures++;
+
+    // Also check that the files on disk still round-trip through the writer and
+    // reader, which is what an edit loop actually depends on.
+    const tree = await readTree(resolve(root, repo.dir));
+    const viaDisk = compare(env.payload, pack(tree));
+    if (!viaDisk.ok) {
+      const editedKeys = viaDisk.differences.length;
+      info(dim(`  ${editedKeys} difference(s) between the baseline payload and the files on disk (expected if you have edited them)`));
+    }
+  }
+  return failures ? 1 : 0;
+};
+
+const reportRoundTrip = (label: string, result: ReturnType<typeof assertRoundTrip>) => {
+  if (result.ok) {
+    ok(`${label}: round trip clean`);
+    return;
+  }
+  warn(`${label}: round trip lost or invented data`);
+  for (const d of result.differences.slice(0, 15)) out(`    ${d.where}: ${dim(d.detail)}`);
+  if (result.differences.length > 15) out(dim(`    …and ${result.differences.length - 15} more`));
+};
+
+// ── validate ─────────────────────────────────────────────────────────────────
+
+export const validateHelp = `pipe validate [workspace] [--repo <id>] [--json]
+
+  JSON shape, then referential integrity. Offline and instant — this is the loop
+  Claude should iterate against before proposing anything.`;
+
+export const validate = async (p: Parsed) => {
+  const { lock, root } = await openWorkspace(p);
+  const wanted = str(p, 'repo');
+  const repos = wanted ? lock.repos.filter((r) => String(r.id) === wanted || r.apiId === wanted) : lock.repos;
+
+  const { loadBaselineQuiet } = await import('./diff.ts');
+  const reference = await loadReference(root);
+  let errors = 0;
+  const all: Array<{ repo: string; findings: ReturnType<typeof validateTree> }> = [];
+  for (const repo of repos) {
+    const tree = await readTree(resolve(root, repo.dir));
+    const { readAgents } = await import('../workspace/agents.ts');
+    const findings = validateTree(tree, {
+      knownRepoIds: lock.repos.map((r) => r.id),
+      baseline: await loadBaselineQuiet(root, repo.id),
+      reference,
+      agents: await readAgents(resolve(root, repo.dir)),
+    });
+    all.push({ repo: `${repo.name} (${repo.id})`, findings });
+    errors += blockingErrors(findings).length;
+  }
+
+  if (bool(p, 'json')) {
+    out(JSON.stringify(all, null, 2));
+  } else {
+    for (const { repo, findings } of all) {
+      out(renderFindings(findings, repo));
+      out('');
+    }
+    /**
+     * One verdict for the workspace, after the per-repo blocks.
+     *
+     * Each block ends with its own "0 errors" line, so in a multi-repo workspace
+     * the last block's summary reads like the answer — and a real error two
+     * blocks up goes unread. It did, once.
+     */
+    if (all.length > 1) {
+      const line = `${all.length} repos · ${errors} blocking error${errors === 1 ? '' : 's'}`;
+      out(errors ? red(`x ${line}`) : green(`+ ${line}`));
+      if (errors) {
+        for (const { repo, findings } of all) {
+          const n = blockingErrors(findings).length;
+          if (n) out(dim(`    ${repo}: ${n}`));
+        }
+      }
+      out('');
+    }
+  }
+  return errors ? 1 : 0;
+};
+
+// ── status ───────────────────────────────────────────────────────────────────
+
+export const statusHelp = `pipe status [workspace]
+
+  What is in this workspace, how it was read, and what is pending.`;
+
+export const status = async (p: Parsed) => {
+  const { root, lock } = await openWorkspace(p);
+  const { readWorkspace } = await import('../workspace/lock.ts');
+  const ws = await readWorkspace(root);
+
+  out(bold(root));
+  out(dim(`pulled ${ws?.createdAt ?? '?'} · depth ${lock.depth} · org ${lock.organizationId ?? 'unknown'}`));
+  out('');
+
+  for (const repo of lock.repos) {
+    const unknown = Object.entries(repo.coverage).filter(([, c]) => c === 'unknown').map(([e]) => e);
+    const partial = Object.entries(repo.coverage).filter(([, c]) => c === 'partial').map(([e]) => e);
+    out(
+      `${repo.id === lock.rootRepoId ? green('*') : ' '} ${bold(String(repo.name))} ${dim(`${repo.kind} ${repo.id}` + (repo.apiId !== String(repo.id) ? ` (api id ${repo.apiId})` : ''))}`,
+    );
+    out(`    read from ${repo.source}${repo.versionId ? dim(` ${repo.versionId.slice(0, 8)}`) : ''} at ${dim(repo.readAt)}`);
+    out(`    ${repo.dir}`);
+    if (repo.via.length) out(dim(`    found via ${repo.via.join(', ')}`));
+    if (partial.length) out(yellow(`    partial: ${partial.join(', ')}`));
+    if (unknown.length) out(yellow(`    unknown: ${unknown.join(', ')}`));
+  }
+
+  const { listJson } = await import('../util/fsx.ts');
+  const plans = await listJson(resolve(root, '.ppc', 'plans'));
+  if (plans.length) {
+    out('');
+    out(bold('plans'));
+    for (const path of plans.slice(-8)) {
+      const plan = await readJson<{ id: string; status: string; steps: Array<{ status: string }> }>(path);
+      const done = plan.steps.filter((s) => s.status === 'done').length;
+      const mark = plan.status === 'applied' ? green('applied') : plan.status === 'failed' ? red('failed') : plan.status === 'partially-applied' ? yellow('partial') : dim(plan.status);
+      out(`  ${mark.padEnd(20)} ${plan.id} ${dim(`${done}/${plan.steps.length} steps`)}`);
+    }
+  }
+  return 0;
+};
+
+// ── capabilities ─────────────────────────────────────────────────────────────
+
+export const capsHelp = `pipe capabilities [--json]
+
+  The write-coverage registry: what pipe can change, how, and what it refuses.`;
+
+export const capabilities = async (p: Parsed) => {
+  const rows = registryRows().sort((a, b) => a.key.localeCompare(b.key));
+  if (bool(p, 'json')) {
+    out(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  const width = Math.max(...rows.map((r) => r.key.length)) + 2;
+  for (const r of rows) {
+    const mark = r.status === 'SUPPORTED' ? green('yes   ') : r.status === 'PARTIAL' ? yellow('partly') : red('no    ');
+    out(`${mark} ${r.key.padEnd(width)} ${dim(r.via ?? '')}`);
+    if (r.status !== 'SUPPORTED' && r.reason) out(`       ${dim(r.reason)}${r.ask ? dim(` (ask ${r.ask})`) : ''}`);
+  }
+  return 0;
+};
+
+// ── rollback ─────────────────────────────────────────────────────────────────
+
+export const rollbackHelp = `pipe rollback --repo <pipeId> --version <versionId>
+
+  Restores a repo to a snapshot. The endpoint only accepts the **latest**
+  snapshot, so this usually cannot undo an apply — see \`pipe doctor\`.
+
+  Scoped to pipe structure — phases, fields, automations, field conditions,
+  labels and the like, everything \`createRepoSnapshot\` reads. It does not
+  touch iPaaS flows or connections (a separate system entirely), and it
+  cannot un-send an email or un-fire a webhook an automation already
+  triggered. If a flow was applied after this snapshot and references a
+  field or phase the restore is about to change, the flow is not rewound
+  with it.`;
+
+/**
+ * `pipe rollback` — and the reason it is narrower than it sounds.
+ *
+ * This used to probe for `restoreRepoSnapshot` and refuse, because that mutation
+ * does not exist here. The endpoint has **`restoreRepoToSnapshot`**, which it
+ * never looked for, so the command refused a restore that was available and every
+ * apply printed "no one-command rollback" beside a usable snapshot.
+ *
+ * Fixed, and then measured, which is where the real limit turned up: a restore
+ * only accepts the **latest** uploaded snapshot. An older versionId is refused
+ * with "Version_id must reference the latest uploaded snapshot of the Pipe". So a
+ * pre-apply snapshot stops being restorable as soon as anything else snapshots
+ * the repo — and `pipe apply` reads the repo back to verify, which does exactly
+ * that. The check below therefore runs *before* the mutation, so the answer names
+ * the snapshot that would be restored instead of coming back as a bare error.
+ *
+ * The restore itself is asynchronous change management, reported through
+ * `operations`, so this polls rather than claiming success on the mutation
+ * returning.
+ */
+export const rollback = async (p: Parsed) => {
+  const repoId = str(p, 'repo');
+  const versionId = str(p, 'version');
+  if (!repoId || !versionId) throw new UserError('--repo and --version are both required');
+
+  const net = await connect(p);
+  const caps = await net.capabilities();
+  if (!caps.restoreMutation) {
+    throw new UserError(
+      'no restore mutation exists on this endpoint',
+      'the pre-apply snapshot is still a record of the previous state, but restoring it must be done by Pipefy',
+    );
+  }
+
+  /**
+   * Refuse before sending when the target is not the latest, because the
+   * endpoint's own error names neither the snapshot asked for nor the one it
+   * wanted.
+   */
+  if (caps.restoreLatestOnly) {
+    const latest = (await net.snapshots.list(repoId, 1))[0];
+    if (latest && latest.versionId !== versionId) {
+      throw new UserError(
+        `this endpoint restores only the latest snapshot, and the latest is ${latest.versionId}`,
+        `${versionId} is older, so it cannot be restored. A pre-apply snapshot usually loses this race to the ` +
+          'read-back that `pipe apply` takes to verify. Recover forward instead: `pipe pull` to re-read the live ' +
+          'state, or re-apply the workspace, whose files still hold the intent.',
+      );
+    }
+  }
+
+  return restoreToVersion(net, repoId, versionId, caps);
+};
+
+/**
+ * The mutation-and-poll half of a rollback, shared with `pipe apply`'s own
+ * post-failure prompt (apply.ts) so there is exactly one place that sends
+ * `restoreRepoToSnapshot`/`restoreRepoSnapshot` and waits on the RESTORE
+ * operation. `pipe rollback` wraps this with argument parsing and the
+ * latest-snapshot pre-check above; a caller that has already done its own
+ * capability/latest check (as apply.ts does) can call this directly.
+ */
+export const restoreToVersion = async (
+  net: Awaited<ReturnType<typeof connect>>,
+  repoId: string | number,
+  versionId: string,
+  caps: { restoreMutation: 'restoreRepoToSnapshot' | 'restoreRepoSnapshot' | null },
+): Promise<0 | 1> => {
+  const mutation = caps.restoreMutation;
+  if (!mutation) {
+    warn('no restore mutation exists on this endpoint');
+    return 1;
+  }
+  const inputType = mutation === 'restoreRepoToSnapshot' ? 'RestoreRepoToSnapshotInput' : 'RestoreRepoSnapshotInput';
+  await net.client.raw<Record<string, unknown>>(
+    `mutation($input: ${inputType}!) { ${mutation}(input: $input) { clientMutationId } }`,
+    { input: { repoId: String(repoId), versionId } },
+    mutation,
+  );
+  ok(`restore requested via ${mutation} — ${versionId}`);
+
+  /**
+   * A restore reports through `operations`, not through the mutation, so waiting
+   * on it is the only way to know it landed. Bounded: a restore that is still
+   * running when this gives up is still running, and saying so beats a spinner
+   * that never ends.
+   */
+  info(dim('   waiting for the RESTORE operation…'));
+  for (let i = 0; i < 20; i++) {
+    const r = await net.client
+      .tryRaw<{ pipe: { operations: Array<{ kind: string; status: string; error: string | null }> } | null }>(
+        `query ($id: ID!) { pipe(id: $id) { operations { kind status error } } }`,
+        { id: String(repoId) },
+        'restore operations',
+      )
+      .catch(() => null);
+    const op = r?.pipe?.operations?.find((o) => o.kind === 'RESTORE');
+    if (op && !['PENDING', 'RUNNING'].includes(op.status)) {
+      if (op.error) {
+        warn(`the restore finished as ${op.status}: ${op.error}`);
+        return 1;
+      }
+      ok(`restore ${op.status.toLowerCase()}`);
+      info(dim('   run `pipe pull` to bring the restored structure back to disk'));
+      return 0;
+    }
+    await new Promise((r2) => setTimeout(r2, 3000));
+  }
+  warn('the restore is still running — check `pipe status` or the Pipefy UI, then `pipe pull`');
+  return 0;
+};
+
+// ── viewer ───────────────────────────────────────────────────────────────────
+
+export const viewerHelp = `pipe viewer [workspace] [--repo <id>] [--against <target>]
+
+  Build the HTML diff view and open it in the OS browser.`;
+
+export const viewer = async (p: Parsed) => {
+  const { run: runDiff } = await import('./diff.ts');
+  p.flags['open'] = true;
+  return runDiff(p);
+};
+
+export const writeViewModel = (path: string, model: unknown) => writeJson(path, model);
+
+export const unusedInt = int;