@pipefy/pipefy-process-coder 0.1.0

package/src/pipefy/reference.ts

@@ -0,0 +1,251 @@
+import { debug } from '../util/log.ts';
+import type { PipefyClient } from './client.ts';
+import type { AutomationCatalogue, AutomationEventSpec, AutomationActionSpec } from './automations.ts';
+
+/**
+ * The closed sets — every place an authored value must come from a fixed list.
+ *
+ * This exists because of a structural gap, not a convenience. The schema
+ * publishes the lists:
+ *
+ *     AutomationsEvents   10 values   card_moved, field_updated, …
+ *     AutomationsActions  15 values   move_single_card, update_card_field, …
+ *     FieldTypeId         24 values   short_text, connector, …
+ *
+ * and then types the input fields that consume them as `ID` and `String`:
+ *
+ *     CreateAutomationInput.event_id    ID
+ *     CreateAutomationInput.action_id   ID
+ *     CreatePhaseFieldInput.type_id     String
+ *
+ * So GraphQL validates none of them. A wrong value passes query validation,
+ * reaches a runtime check, and comes back as the two words `is invalid` — no
+ * parameter name, no field name, no list of what would have been accepted. The
+ * list was always public; nothing was consulting it.
+ *
+ * Two consumers, and the split matters:
+ *
+ *  - `pipe validate`, `plan` and `apply` read the cached copy and refuse
+ *    offline, naming the value and what belongs there.
+ *  - `REFERENCE.md` puts the same lists in the workspace, so whoever is editing
+ *    the JSON — a person or an agent — reads what the API accepts instead of
+ *    guessing and waiting for `is invalid`.
+ *
+ * Read once per pull, cached in `.ppc/reference.json`. Never assumed: an
+ * absent reference means the checks are skipped, not that a value is wrong.
+ */
+
+/** Enums whose values get authored into workspace JSON by hand. */
+const TRACKED_ENUMS = [
+  'FieldTypeId',
+  'AutomationsEvents',
+  'AutomationsActions',
+  'Colors',
+  'FieldConditionFilter',
+  'AutomationHttpAuthentication',
+  'HttpRequestMethodTypeGQLEnum',
+  'HttpRequestAddAuthenticationTo',
+  'UpdateFieldValuesOperators',
+  'DistributeAssignmentAutomationStrategyGQLEnum',
+  'CardTypeEnum',
+] as const;
+
+export type Reference = {
+  readAt: string;
+  /** The repo the action catalogue was read for — actions are per-pipe. */
+  repoId: string;
+  /** Enum name -> its values, exactly as the endpoint spells them. */
+  enums: Record<string, string[]>;
+  events: AutomationEventSpec[];
+  actions: AutomationActionSpec[];
+};
+
+const ENUMS_QUERY = `query ClosedSets {
+  __schema { types { name kind enumValues { name } } }
+}`;
+
+const CATALOGUE_QUERY = `query AutomationCatalogue($repoId: ID!) {
+  automationEvents { id acceptedParameters actionsBlacklist }
+  automationActions(repoId: $repoId) { id acceptedParameters eventsBlacklist }
+}`;
+
+/**
+ * Read every closed set for one pipe.
+ *
+ * Returns null rather than throwing: a token that cannot introspect, or a pipe
+ * whose action catalogue is refused, must degrade to "no reference" — which
+ * skips the checks — and never to a guess that would report valid work as broken.
+ */
+export const readReference = async (
+  client: PipefyClient,
+  repoId: number | string,
+): Promise<Reference | null> => {
+  try {
+    const [schema, cat] = await Promise.all([
+      client.raw<{ __schema: { types: Array<{ name: string; kind: string; enumValues: Array<{ name: string }> | null }> } }>(
+        ENUMS_QUERY,
+      ),
+      client.raw<{
+        automationEvents: AutomationEventSpec[];
+        automationActions: AutomationActionSpec[];
+      }>(CATALOGUE_QUERY, { repoId: String(repoId) }),
+    ]);
+
+    const byName = new Map(
+      (schema?.__schema?.types ?? [])
+        .filter((t) => t.kind === 'ENUM')
+        .map((t) => [t.name, (t.enumValues ?? []).map((v) => v.name)] as const),
+    );
+
+    const enums: Record<string, string[]> = {};
+    for (const name of TRACKED_ENUMS) {
+      const values = byName.get(name);
+      /**
+       * An enum the endpoint no longer publishes is omitted, not recorded empty.
+       * An empty list would read as "nothing is valid here" and refuse every
+       * value in that position.
+       */
+      if (values?.length) enums[name] = values;
+    }
+
+    const ref: Reference = {
+      readAt: new Date().toISOString(),
+      repoId: String(repoId),
+      enums,
+      events: (cat?.automationEvents ?? []).map((e) => ({
+        id: e.id,
+        acceptedParameters: e.acceptedParameters ?? [],
+        actionsBlacklist: e.actionsBlacklist ?? [],
+      })),
+      actions: (cat?.automationActions ?? []).map((a) => ({
+        id: a.id,
+        acceptedParameters: a.acceptedParameters ?? [],
+        eventsBlacklist: a.eventsBlacklist ?? [],
+      })),
+    };
+    debug(
+      `reference: ${Object.keys(enums).length} enums, ${ref.events.length} events, ` +
+        `${ref.actions.length} actions for repo ${repoId}`,
+    );
+    return ref;
+  } catch (e) {
+    debug(`reference unavailable: ${(e as Error).message}`);
+    return null;
+  }
+};
+
+/** The cached reference, in the shape the automation param check already takes. */
+export const toCatalogue = (ref: Reference): AutomationCatalogue => ({
+  events: new Map(ref.events.map((e) => [e.id, e])),
+  actions: new Map(ref.actions.map((a) => [a.id, a])),
+});
+
+export const enumValues = (ref: Reference | null, name: string): string[] | null => {
+  const v = ref?.enums[name];
+  return v?.length ? v : null;
+};
+
+const table = (rows: Array<[string, string]>, head: [string, string]): string[] => {
+  const w = Math.max(head[0].length, ...rows.map(([a]) => a.length));
+  return [
+    `| ${head[0].padEnd(w)} | ${head[1]} |`,
+    `| ${'-'.repeat(w)} | ${'-'.repeat(Math.max(3, head[1].length))} |`,
+    ...rows.map(([a, b]) => `| ${a.padEnd(w)} | ${b} |`),
+  ];
+};
+
+/**
+ * REFERENCE.md — the closed sets, on disk, next to the JSON being edited.
+ *
+ * Deliberately generated rather than written by hand. A hand-written list of
+ * what an API accepts is wrong the first time the API changes, and nothing tells
+ * you it went wrong; this one is re-read on every pull and stamped with when.
+ */
+export const renderReferenceMd = (ref: Reference | null): string => {
+  const lines: string[] = ['# What the API accepts', ''];
+
+  if (!ref) {
+    lines.push(
+      'The closed sets could not be read on the last pull, so this file is empty and',
+      '`pipe validate` skips the checks that depend on it. That is not a claim that',
+      'any value is valid — it is the absence of a claim. Re-run `pipe pull` to fill it.',
+      '',
+    );
+    return lines.join('\n');
+  }
+
+  lines.push(
+    `Read from the API on ${ref.readAt} for pipe ${ref.repoId}. Regenerated by every`,
+    '`pipe pull` — edit the workspace JSON, never this file.',
+    '',
+    'These are the values the endpoint accepts in each position. They matter because',
+    'the schema publishes the lists but types the inputs that consume them as `ID`',
+    'and `String`, so a wrong value is not caught by GraphQL: it reaches a runtime',
+    'check and comes back as `is invalid`, naming nothing. `pipe validate` checks',
+    'these offline so a bad value is refused with its name before anything is sent.',
+    '',
+    '## Automation events',
+    '',
+    'Each event accepts **only** the parameters listed. A parameter that belongs to a',
+    'different event is still just `is invalid`.',
+    '',
+  );
+
+  for (const e of [...ref.events].sort((a, b) => a.id.localeCompare(b.id))) {
+    lines.push(`### \`${e.id}\``);
+    lines.push('');
+    lines.push(
+      e.acceptedParameters.length
+        ? `\`event_params\`: ${e.acceptedParameters.map((p) => `\`${p}\``).join(', ')}`
+        : '`event_params`: none — this event takes no parameters.',
+    );
+    if (e.actionsBlacklist.length) {
+      lines.push('');
+      lines.push(`Cannot be paired with: ${e.actionsBlacklist.map((a) => `\`${a}\``).join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(
+    '## Automation actions',
+    '',
+    'Actions are per-pipe: a pipe without AI enabled offers fewer than this list if',
+    'it was pulled from a different pipe. `field_map` is accepted on every action',
+    'that writes a field and is not listed below — the catalogue names',
+    '`fields_map_order` beside it and stops.',
+    '',
+  );
+
+  for (const a of [...ref.actions].sort((x, y) => x.id.localeCompare(y.id))) {
+    lines.push(`### \`${a.id}\``);
+    lines.push('');
+    lines.push(
+      a.acceptedParameters.length
+        ? `\`action_params\`: ${a.acceptedParameters.map((p) => `\`${p}\``).join(', ')}`
+        : '`action_params`: none — this action takes no parameters.',
+    );
+    if (a.eventsBlacklist.length) {
+      lines.push('');
+      lines.push(`Cannot be triggered by: ${a.eventsBlacklist.map((e) => `\`${e}\``).join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  const enumRows = Object.entries(ref.enums)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, values]) => [`\`${name}\``, values.map((v) => `\`${v}\``).join(', ')] as [string, string]);
+
+  if (enumRows.length) {
+    lines.push('## Other closed sets', '');
+    lines.push(
+      'Where these are used: `FieldTypeId` is a field\'s `type_id`; `Colors` is a',
+      'phase or pipe `color`; `FieldConditionFilter` is a field condition\'s',
+      '`filter`; the `Http*` sets belong to `send_http_request` action params.',
+      '',
+    );
+    lines.push(...table(enumRows, ['Set', 'Values']));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+};

package/src/pipefy/snapshot.ts

@@ -0,0 +1,245 @@
+import { gunzipSync } from 'node:zlib';
+import { LIMITS } from '../config.ts';
+import { debug, progress, progressDone, step } from '../util/log.ts';
+import { retry, sleep } from '../util/pool.ts';
+import type { PipefyClient } from './client.ts';
+import type { RepoPayload } from '../model/payload.ts';
+
+/**
+ * The snapshot read path. PLAN.md §1.1, all measured:
+ *   - generation takes ~63s, so this is an async job with backoff polling
+ *   - `signedUrl` lives ~16.5 min, so it is re-queried before every download
+ *     and never persisted
+ *   - a snapshot of an unchanged pipe still creates a new row and a new S3
+ *     object, so we only ever create one on an explicit action
+ */
+
+export type SnapshotRow = {
+  versionId: string;
+  status: string;
+  sequenceIndex?: number | null;
+  label?: string | null;
+  createdAt?: string | null;
+};
+
+export type SnapshotDetail = SnapshotRow & {
+  signedUrl?: string | null;
+  metrics?: unknown;
+  uploadedAt?: string | null;
+  error?: string | null;
+};
+
+/**
+ * `RepoSnapshotStatus` is `PENDING | UPLOADED | FAILED` — verified by
+ * introspection against api.pipefy.com. **UPLOADED is the success state**: the
+ * job has written the payload to S3 and `signedUrl` is available. The wider set
+ * is kept because this is an undocumented enum with no `schema_version`
+ * (ROUTE-B-V2.md ask 9), so a deployment that renames it degrades to a slow
+ * poll rather than a wrong answer.
+ */
+const DONE = new Set(['uploaded', 'done', 'succeeded', 'success', 'completed', 'finished', 'ready']);
+const FAILED = new Set(['failed', 'error', 'errored', 'cancelled', 'canceled']);
+
+export const isDone = (s: string | null | undefined) => DONE.has(String(s ?? '').toLowerCase());
+export const isFailed = (s: string | null | undefined) => FAILED.has(String(s ?? '').toLowerCase());
+
+export class SnapshotClient {
+  private client: PipefyClient;
+  /** Whether this endpoint has snapshots at all — decided once, cached. */
+  private available: boolean | null = null;
+
+  constructor(client: PipefyClient) {
+    this.client = client;
+  }
+
+  /**
+   * Where poll progress goes. The snapshot wait is the longest thing this tool
+   * does (~63s), so whoever owns the screen renders it, rather than this client
+   * scribbling its own line into someone else's frame.
+   */
+  onProgress: ((text: string) => void) | null = null;
+
+  private report(text: string) {
+    if (this.onProgress) this.onProgress(text);
+    else progress(text);
+  }
+
+  /**
+   * Snapshots are an entitlement, not a given. The whole point of the
+   * reconstruction path is that this can be false — so it is answered by
+   * introspection, up front, and never by a failed pull halfway through.
+   */
+  async isAvailable(): Promise<boolean> {
+    if (this.available !== null) return this.available;
+    const [mut, pipeFields] = await Promise.all([
+      this.client.hasMutation('createRepoSnapshot'),
+      this.client.typeFields('Pipe'),
+    ]);
+    this.available = mut && Boolean(pipeFields?.has('snapshot') || pipeFields?.has('snapshots'));
+    debug(`snapshot capability: createRepoSnapshot=${mut} pipe.snapshots=${pipeFields?.has('snapshots')}`);
+    return this.available;
+  }
+
+  /**
+   * `Pipe.snapshots` is a Relay `RepoSnapshotConnection`, not the flat array
+   * PLAN.md §1.1 recorded — so the rows come from `nodes`.
+   *
+   * `snapshots(last: N)` is not the most recent N — measured live, on a pipe
+   * with 86 snapshots: `last: 1` returned `sequenceIndex: 1`, the *oldest* one
+   * on record, while `first: 1` correctly returned `sequenceIndex: 86`. The
+   * connection is apparently ordered newest-first internally, the opposite of
+   * the usual Relay convention, which inverts what `first`/`last` each mean.
+   *
+   * This is not cosmetic: `pipe rollback`'s only-the-latest check, and
+   * `pipe apply`'s post-failure rollback offer, both call this to decide
+   * whether a version is still restorable. With `last`, that check compared
+   * against the *oldest* snapshot and refused every legitimate restore.
+   */
+  async list(repoId: string | number, limit = 20): Promise<SnapshotRow[]> {
+    const data = await this.client.tryRaw<{
+      pipe: { snapshots: { totalCount: number; nodes: SnapshotRow[] | null } | null } | null;
+    }>(
+      `query($id: ID!, $first: Int!) {
+        pipe(id: $id) {
+          snapshots(first: $first) {
+            totalCount
+            nodes { versionId status sequenceIndex label createdAt }
+          }
+        }
+      }`,
+      { id: String(repoId), first: limit },
+      'list snapshots',
+    );
+    const rows = data?.pipe?.snapshots?.nodes ?? [];
+    return [...rows].sort((a, b) => (b.sequenceIndex ?? 0) - (a.sequenceIndex ?? 0));
+  }
+
+  /** `snapshot(versionId:)` takes an `ID`; declaring `String!` fails the query. */
+  async detail(repoId: string | number, versionId: string): Promise<SnapshotDetail | null> {
+    const data = await this.client.tryRaw<{ pipe: { snapshot: SnapshotDetail | null } | null }>(
+      `query($id: ID!, $v: ID!) {
+        pipe(id: $id) {
+          snapshot(versionId: $v) { versionId status signedUrl metrics uploadedAt error }
+        }
+      }`,
+      { id: String(repoId), v: versionId },
+      'snapshot detail',
+    );
+    return data?.pipe?.snapshot ?? null;
+  }
+
+  async create(repoId: string | number): Promise<string> {
+    const data = await this.client.raw<{
+      createRepoSnapshot: { repoSnapshot: { versionId: string; status: string } };
+    }>(
+      `mutation($input: CreateRepoSnapshotInput!) {
+        createRepoSnapshot(input: $input) { repoSnapshot { versionId status } }
+      }`,
+      { input: { repoId: Number(repoId) } },
+      'createRepoSnapshot',
+    );
+    return data.createRepoSnapshot.repoSnapshot.versionId;
+  }
+
+  async rename(repoId: string | number, versionId: string, label: string): Promise<boolean> {
+    const res = await this.client.tryRaw(
+      `mutation($input: RenameRepoSnapshotInput!) {
+        renameRepoSnapshot(input: $input) { repoSnapshot { versionId label } }
+      }`,
+      { input: { repoId: Number(repoId), versionId, label } },
+      'renameRepoSnapshot',
+    );
+    return res !== null;
+  }
+
+  /** Poll to a terminal state. ~63s is normal, so the wait is visible and bounded. */
+  async waitFor(repoId: string | number, versionId: string): Promise<SnapshotDetail> {
+    const started = Date.now();
+    let unreadable = 0;
+
+    for (;;) {
+      const d = await this.detail(repoId, versionId);
+      const elapsed = Math.round((Date.now() - started) / 1000);
+
+      if (d && isDone(d.status)) {
+        if (!this.onProgress) progressDone();
+        return d;
+      }
+      if (d && isFailed(d.status)) {
+        if (!this.onProgress) progressDone();
+        throw new Error(`snapshot ${versionId} ${d.status}${d.error ? `: ${d.error}` : ''}`);
+      }
+
+      /**
+       * A null detail means the *query* failed, not that the snapshot is
+       * pending. Polling a broken query for five minutes and then reporting
+       * "still unknown" hides the real cause — which is how a schema drift in
+       * this query cost a wasted snapshot and a 303s wait. Fail fast and say so.
+       */
+      if (!d) {
+        unreadable++;
+        if (unreadable >= 3) {
+          if (!this.onProgress) progressDone();
+          throw new Error(
+            `snapshot ${versionId} status is unreadable — pipe.snapshot(versionId:) did not answer 3 times. ` +
+              `Run with --verbose to see the GraphQL error; the snapshot itself may well have been created.`,
+          );
+        }
+      } else {
+        unreadable = 0;
+      }
+
+      if (Date.now() - started > LIMITS.snapshotTimeoutMs) {
+        if (!this.onProgress) progressDone();
+        throw new Error(`snapshot ${versionId} still ${d?.status ?? 'unreadable'} after ${elapsed}s`);
+      }
+      this.report(`${String(d?.status ?? 'unreadable').toLowerCase()} ${elapsed}s (~63s typical)`);
+      await sleep(LIMITS.snapshotPollMs);
+    }
+  }
+
+  /**
+   * Download the payload. The signed URL is re-queried immediately before the
+   * fetch and never stored, and the raw gzip bytes are returned alongside the
+   * parsed payload so the caller can cache the compressed form.
+   */
+  async download(repoId: string | number, versionId: string): Promise<{ payload: RepoPayload; gzip: Buffer | null; raw: Buffer }> {
+    const d = await this.detail(repoId, versionId);
+    if (!d?.signedUrl) throw new Error(`snapshot ${versionId} has no signedUrl (status ${d?.status ?? 'unknown'})`);
+
+    const bytes = await retry(
+      async () => {
+        const res = await fetch(d.signedUrl as string);
+        if (!res.ok) {
+          const err = new Error(`snapshot download HTTP ${res.status}`);
+          (err as { retryable?: boolean }).retryable = res.status >= 500 || res.status === 429;
+          throw err;
+        }
+        return Buffer.from(await res.arrayBuffer());
+      },
+      { label: 'snapshot download' },
+    );
+
+    const gzipped = bytes.length > 2 && bytes[0] === 0x1f && bytes[1] === 0x8b;
+    const raw = gzipped ? gunzipSync(bytes) : bytes;
+    return { payload: JSON.parse(raw.toString('utf8')) as RepoPayload, gzip: gzipped ? bytes : null, raw };
+  }
+
+  /** Create, wait, download — the whole read in one call. */
+  async pull(repoId: string | number, label?: string): Promise<{ payload: RepoPayload; versionId: string; gzip: Buffer | null; raw: Buffer }> {
+    if (this.onProgress) this.report('requesting a snapshot');
+    else step(`creating snapshot of repo ${repoId}`);
+    const versionId = await this.create(repoId);
+    await this.waitFor(repoId, versionId);
+    if (label) await this.rename(repoId, versionId, label);
+    this.report('downloading');
+    const dl = await this.download(repoId, versionId);
+    return { ...dl, versionId };
+  }
+
+  /** Most recent already-complete snapshot, so a pull can cost zero snapshots. */
+  async latestComplete(repoId: string | number): Promise<SnapshotRow | null> {
+    const rows = await this.list(repoId);
+    return rows.find((r) => isDone(r.status)) ?? null;
+  }
+}

package/src/pipefy/toolkit.ts

@@ -0,0 +1,200 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { debug } from '../util/log.ts';
+
+/**
+ * Bridge to the official Pipefy AI toolkit (github.com/pipefy/ai-toolkit).
+ *
+ * `pipe` does not implement Pipefy login. When the toolkit is installed, its
+ * session *is* the credential: `pipefy auth login` runs the browser OAuth flow
+ * and stores a session in the OS keychain, and everything here does is ask the
+ * toolkit for the current bearer.
+ *
+ * That means one login for the MCP server, the `pipefy` CLI and this tool, and
+ * it means the keychain, the refresh grant and the credential precedence stay in
+ * one place — the toolkit's — rather than being reimplemented against a private
+ * store shape that can change under us.
+ *
+ * The bearer is short-lived and never persisted here. It is fetched per process
+ * and re-fetched when the API rejects it, which is why callers take a provider
+ * rather than a string.
+ */
+
+const exec = promisify(execFile);
+
+const here = dirname(fileURLToPath(import.meta.url));
+const HELPER = join(here, 'toolkit_bearer.py');
+
+export type ToolkitSource = 'static-token' | 'stored-session' | 'service-account';
+
+export type ToolkitBearer = {
+  ok: true;
+  source: ToolkitSource;
+  token: string;
+  base_url?: string;
+  issuer?: string;
+  expires_in?: number | null;
+};
+
+export type ToolkitNoCredential = {
+  ok: false;
+  reason: 'no-credentials' | 'session-expired' | 'service-account-failed' | 'unknown-method';
+  message: string;
+};
+
+export type ToolkitResult = ToolkitBearer | ToolkitNoCredential;
+
+const WINDOWS = process.platform === 'win32';
+
+/** `pipefy` / `pipefy-mcp-server`, wherever uv put them. */
+const toolBinDir = (): string | null => {
+  const home = process.env.USERPROFILE ?? process.env.HOME;
+  if (!home) return null;
+  const dir = join(home, '.local', 'bin');
+  return existsSync(dir) ? dir : null;
+};
+
+export const toolkitBinary = (name: 'pipefy' | 'pipefy-mcp-server'): string | null => {
+  const dir = toolBinDir();
+  if (!dir) return null;
+  const path = join(dir, WINDOWS ? `${name}.exe` : name);
+  return existsSync(path) ? path : null;
+};
+
+/**
+ * The interpreter that can import `pipefy_auth`.
+ *
+ * `uv tool install` gives each tool its own environment, and `uv tool dir` is
+ * the documented way to find them — so the layout is asked for rather than
+ * assumed. `uv run --with` is the fallback for a machine where the CLI is not
+ * installed as a tool but uv is available.
+ */
+const findInterpreter = async (): Promise<{ command: string; args: string[] } | null> => {
+  const roots: string[] = [];
+
+  try {
+    const { stdout } = await exec('uv', ['tool', 'dir'], { timeout: 15_000 });
+    const dir = stdout.trim();
+    if (dir) roots.push(dir);
+  } catch {
+    debug('uv tool dir failed — uv may not be installed');
+  }
+
+  const appdata = process.env.APPDATA;
+  if (appdata) roots.push(join(appdata, 'uv', 'tools'));
+  const home = process.env.USERPROFILE ?? process.env.HOME;
+  if (home) {
+    roots.push(join(home, '.local', 'share', 'uv', 'tools'));
+    roots.push(join(home, 'Library', 'Application Support', 'uv', 'tools'));
+  }
+
+  for (const root of roots) {
+    for (const tool of ['pipefy-cli', 'pipefy-mcp-server']) {
+      const python = WINDOWS
+        ? join(root, tool, 'Scripts', 'python.exe')
+        : join(root, tool, 'bin', 'python');
+      if (existsSync(python)) {
+        debug(`toolkit interpreter: ${python}`);
+        return { command: python, args: [] };
+      }
+    }
+  }
+
+  // No installed tool env: let uv build an ephemeral one. Slower, and it needs
+  // the network the first time, so it is deliberately the last resort.
+  try {
+    await exec('uv', ['--version'], { timeout: 15_000 });
+    debug('falling back to `uv run --with pipefy-auth`');
+    return { command: 'uv', args: ['run', '--quiet', '--with', 'pipefy-auth', 'python'] };
+  } catch {
+    return null;
+  }
+};
+
+export type ToolkitStatus =
+  | { installed: false }
+  | {
+      installed: true;
+      cliPath: string | null;
+      mcpServerPath: string | null;
+      interpreter: string;
+      credential: ToolkitResult;
+    };
+
+let cachedInterpreter: { command: string; args: string[] } | null | undefined;
+
+/** Is the toolkit usable on this machine, and does it currently hold a credential? */
+export const inspectToolkit = async (): Promise<ToolkitStatus> => {
+  cachedInterpreter ??= await findInterpreter();
+  if (!cachedInterpreter) return { installed: false };
+
+  const credential = await readBearer();
+  if (!credential) return { installed: false };
+
+  return {
+    installed: true,
+    cliPath: toolkitBinary('pipefy'),
+    mcpServerPath: toolkitBinary('pipefy-mcp-server'),
+    interpreter: cachedInterpreter.command,
+    credential,
+  };
+};
+
+/**
+ * Ask the toolkit for a bearer. `null` means the toolkit could not be used at
+ * all — distinct from a `{ ok: false }` result, which is the toolkit answering
+ * that it holds no credential.
+ */
+export const readBearer = async (): Promise<ToolkitResult | null> => {
+  cachedInterpreter ??= await findInterpreter();
+  if (!cachedInterpreter) return null;
+  if (!existsSync(HELPER)) {
+    debug(`toolkit helper missing at ${HELPER}`);
+    return null;
+  }
+
+  try {
+    const { stdout } = await exec(
+      cachedInterpreter.command,
+      [...cachedInterpreter.args, HELPER],
+      { timeout: 60_000, maxBuffer: 1024 * 1024 },
+    );
+    const parsed = JSON.parse(stdout.trim()) as ToolkitResult;
+    debug(`toolkit credential: ${parsed.ok ? parsed.source : parsed.reason}`);
+    return parsed;
+  } catch (e) {
+    debug(`toolkit bearer helper failed: ${(e as Error).message}`);
+    return null;
+  }
+};
+
+/** Run `pipefy auth login`, inheriting the terminal so the browser flow works. */
+export const runToolkitLogin = async (extraArgs: string[] = []): Promise<number> => {
+  const cli = toolkitBinary('pipefy');
+  const { spawn } = await import('node:child_process');
+  const command = cli ?? 'pipefy';
+  return new Promise((resolve) => {
+    const child = spawn(command, ['auth', 'login', ...extraArgs], { stdio: 'inherit' });
+    child.on('error', () => resolve(127));
+    child.on('exit', (code) => resolve(code ?? 1));
+  });
+};
+
+/** `pipefy auth status --json`, for `pipe doctor`. Null when unavailable. */
+export const toolkitAuthStatus = async (): Promise<Record<string, unknown> | null> => {
+  const cli = toolkitBinary('pipefy');
+  if (!cli) return null;
+  try {
+    const { stdout } = await exec(cli, ['auth', 'status', '--json'], { timeout: 60_000 });
+    return JSON.parse(stdout.trim()) as Record<string, unknown>;
+  } catch (e) {
+    debug(`pipefy auth status failed: ${(e as Error).message}`);
+    return null;
+  }
+};
+
+export const INSTALL_HINT =
+  'install the Pipefy AI toolkit (github.com/pipefy/ai-toolkit): `uv tool install pipefy-cli`, then `pipefy auth login`';