@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/dist/commands/misc.js

@@ -0,0 +1,562 @@
+import { resolve } from 'node:path';
+import { loadReference } from "../workspace/reference.js";
+import { bool, int, requirePositional, str } from "../cli/args.js";
+import { ENDPOINTS, writeToken } from "../config.js";
+import { readJson, writeFile, writeJson } from "../util/fsx.js";
+import { UserError, bold, dim, green, info, ok, out, red, step, warn, yellow } from "../util/log.js";
+import { ENTITY_NAMES } from "../model/payload.js";
+import { unpack } from "../codec/unpack.js";
+import { pack } from "../codec/pack.js";
+import { assertRoundTrip, compare } from "../codec/roundtrip.js";
+import { missingMutations } from "../pipefy/capability.js";
+import { RECONSTRUCTION_GAPS } from "../pipefy/reconstruct.js";
+import { readTree } from "../workspace/read.js";
+import { registryRows } from "../apply/registry.js";
+import { validateTree, renderFindings, blockingErrors } from "../validate/index.js";
+import { connect, openWorkspace } from "./context.js";
+// ── 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) => {
+    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, UPGRADE_HINT } = await import("../pipefy/toolkit.js");
+        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`);
+        }
+        if (!toolkit.usable) {
+            throw new UserError(`the Pipefy AI toolkit is installed but this tool cannot use it: ${toolkit.error}`, `${UPGRADE_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.js");
+    const client = new PipefyClient({ token });
+    const me = await client.tryRaw('query { me { name email } }', undefined, 'me');
+    if (!me?.me)
+        throw new UserError('that token was rejected by ' + ENDPOINTS.graphql);
+    const orgs = await client.tryRaw('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.js");
+    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.js");
+    const client = new PipefyClient({ token: credential.token });
+    const me = await client.tryRaw('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) => {
+    const { resolveCredential } = await import("../config.js");
+    const { inspectToolkit, toolkitAuthStatus, INSTALL_HINT, UPGRADE_HINT } = await import("../pipefy/toolkit.js");
+    out(bold('endpoints'));
+    out(`  graphql   ${ENDPOINTS.graphql}`);
+    out(`  internal  ${ENDPOINTS.internal}`);
+    out('');
+    out(bold('credential'));
+    const toolkit = await inspectToolkit();
+    const credential = await resolveCredential();
+    if (!toolkit.installed) {
+        out(`  toolkit   ${red('not installed')}${dim(`  ${INSTALL_HINT}`)}`);
+    }
+    else if (!toolkit.usable) {
+        out(`  toolkit   ${yellow('installed, unusable')}${dim(`  ${toolkit.cliPath ?? toolkit.interpreter}`)}`);
+        out(`            ${dim(toolkit.error)}`);
+        out(`            ${dim(UPGRADE_HINT)}`);
+    }
+    else {
+        out(`  toolkit   ${green('installed')}${dim(`  ${toolkit.cliPath ?? toolkit.interpreter}`)}`);
+    }
+    if (toolkit.installed && toolkit.usable) {
+        const status = await toolkitAuthStatus();
+        if (status) {
+            const identity = status['identity'];
+            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
+            ? `${INSTALL_HINT}, or \`pipe login --token <token>\``
+            : !toolkit.usable
+                ? `${UPGRADE_HINT}, or \`pipe login --token <token>\``
+                : 'run `pipe login` for the browser flow');
+    }
+    const net = await connect(p);
+    const caps = await net.capabilities();
+    out('');
+    out(bold('capabilities'));
+    const row = (label, present, consequence) => 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'));
+    // Validates the query documents themselves, with ids that match nothing —
+    // "status unknown" used to be all this said, while every automation read in
+    // a pull was failing on a query the schema had stopped accepting.
+    const checks = await net.internal.checkQueries();
+    if (!checks)
+        out(`  queries   ${red('no answer')}${dim('  the endpoint could not be reached')}`);
+    else {
+        for (const c of checks) {
+            out(`  ${c.ok ? green('ok  ') : red('FAIL')}  ${c.label.padEnd(18)}${c.ok ? '' : ` ${dim(c.message ?? '')}`}`);
+        }
+    }
+    const status = net.internal.status;
+    out(`  status ${status === 'ok'
+        ? green('ok')
+        : status === 'incompatible'
+            ? red('incompatible') + dim('  a query this version of pipe sends is refused — a bug in pipe, worth reporting')
+            : 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, repoId) => {
+    const data = await net.client.tryRaw('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) => {
+    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;
+    if (useSnapshot) {
+        const { payload, versionId } = await net.snapshots.pull(repoId);
+        const { fullCoverage } = await import("../model/payload.js");
+        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) => {
+    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(path);
+        const env = 'payload' in raw && raw.payload
+            ? raw
+            : {
+                source: 'snapshot',
+                versionId: null,
+                readAt: new Date().toISOString(),
+                repoKind: 'pipe',
+                coverage: (await import("../model/payload.js")).fullCoverage('complete'),
+                notes: [],
+                payload: raw,
+            };
+        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(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, result) => {
+    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) => {
+    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.js");
+    const reference = await loadReference(root);
+    let errors = 0;
+    const all = [];
+    for (const repo of repos) {
+        const tree = await readTree(resolve(root, repo.dir));
+        const { readAgents } = await import("../workspace/agents.js");
+        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) => {
+    const { root, lock } = await openWorkspace(p);
+    const { readWorkspace } = await import("../workspace/lock.js");
+    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.js");
+    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(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) => {
+    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) => {
+    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, repoId, versionId, caps) => {
+    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(`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(`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) => {
+    const { run: runDiff } = await import("./diff.js");
+    p.flags['open'] = true;
+    return runDiff(p);
+};
+export const writeViewModel = (path, model) => writeJson(path, model);
+export const unusedInt = int;