@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/dist/pipefy/reference.js

@@ -0,0 +1,172 @@
+import { debug } from "../util/log.js";
+/**
+ * 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',
+];
+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, repoId) => {
+    try {
+        const [schema, cat] = await Promise.all([
+            client.raw(ENUMS_QUERY),
+            client.raw(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)]));
+        const enums = {};
+        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 = {
+            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.message}`);
+        return null;
+    }
+};
+/** The cached reference, in the shape the automation param check already takes. */
+export const toCatalogue = (ref) => ({
+    events: new Map(ref.events.map((e) => [e.id, e])),
+    actions: new Map(ref.actions.map((a) => [a.id, a])),
+});
+export const enumValues = (ref, name) => {
+    const v = ref?.enums[name];
+    return v?.length ? v : null;
+};
+const table = (rows, head) => {
+    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) => {
+    const lines = ['# 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(', ')]);
+    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/dist/pipefy/snapshot.js

@@ -0,0 +1,185 @@
+import { gunzipSync } from 'node:zlib';
+import { LIMITS } from "../config.js";
+import { debug, progress, progressDone, step } from "../util/log.js";
+import { retry, sleep } from "../util/pool.js";
+/**
+ * `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) => DONE.has(String(s ?? '').toLowerCase());
+export const isFailed = (s) => FAILED.has(String(s ?? '').toLowerCase());
+export class SnapshotClient {
+    client;
+    /** Whether this endpoint has snapshots at all — decided once, cached. */
+    available = null;
+    constructor(client) {
+        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 = null;
+    report(text) {
+        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() {
+        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, limit = 20) {
+        const data = await this.client.tryRaw(`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, versionId) {
+        const data = await this.client.tryRaw(`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) {
+        const data = await this.client.raw(`mutation($input: CreateRepoSnapshotInput!) {
+        createRepoSnapshot(input: $input) { repoSnapshot { versionId status } }
+      }`, { input: { repoId: Number(repoId) } }, 'createRepoSnapshot');
+        return data.createRepoSnapshot.repoSnapshot.versionId;
+    }
+    async rename(repoId, versionId, label) {
+        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, versionId) {
+        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, versionId) {
+        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);
+            if (!res.ok) {
+                const err = new Error(`snapshot download HTTP ${res.status}`);
+                err.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')), gzip: gzipped ? bytes : null, raw };
+    }
+    /** Create, wait, download — the whole read in one call. */
+    async pull(repoId, label) {
+        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) {
+        const rows = await this.list(repoId);
+        return rows.find((r) => isDone(r.status)) ?? null;
+    }
+}

package/dist/pipefy/toolkit.js

@@ -0,0 +1,174 @@
+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.js";
+/**
+ * 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');
+const WINDOWS = process.platform === 'win32';
+/** `pipefy` / `pipefy-mcp-server`, wherever uv put them. */
+const toolBinDir = () => {
+    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) => {
+    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 () => {
+    const roots = [];
+    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;
+    }
+};
+let cachedInterpreter;
+/** Is the toolkit usable on this machine, and does it currently hold a credential? */
+export const inspectToolkit = async () => {
+    cachedInterpreter ??= await findInterpreter();
+    if (!cachedInterpreter)
+        return { installed: false };
+    const run = await runHelper();
+    if (!run)
+        return { installed: false };
+    if ('error' in run) {
+        return { installed: true, usable: false, cliPath: toolkitBinary('pipefy'), interpreter: cachedInterpreter.command, error: run.error };
+    }
+    return {
+        installed: true,
+        usable: true,
+        cliPath: toolkitBinary('pipefy'),
+        mcpServerPath: toolkitBinary('pipefy-mcp-server'),
+        interpreter: cachedInterpreter.command,
+        credential: run.result,
+    };
+};
+/**
+ * Run the helper. `null` means there is nothing to run it with; `{ error }`
+ * means it ran and could not use the toolkit, carrying its own explanation
+ * (the helper prints which `pipefy_auth` version it found and what it lacks).
+ */
+const runHelper = async () => {
+    cachedInterpreter ??= await findInterpreter();
+    if (!cachedInterpreter)
+        return null;
+    if (!existsSync(HELPER)) {
+        debug(`toolkit helper missing at ${HELPER}`);
+        return { error: `this install of pipe is missing its toolkit helper (${HELPER})` };
+    }
+    try {
+        const { stdout } = await exec(cachedInterpreter.command, [...cachedInterpreter.args, HELPER], { timeout: 60_000, maxBuffer: 1024 * 1024 });
+        const parsed = JSON.parse(stdout.trim());
+        debug(`toolkit credential: ${parsed.ok ? parsed.source : parsed.reason}`);
+        return { result: parsed };
+    }
+    catch (e) {
+        const err = e;
+        debug(`toolkit bearer helper failed: ${err.message}`);
+        const said = err.stderr?.trim().split(/\r?\n/).filter(Boolean).pop();
+        return { error: said || err.message.split(/\r?\n/)[0] || 'the toolkit helper failed' };
+    }
+};
+/**
+ * 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 () => {
+    const run = await runHelper();
+    return run && 'result' in run ? run.result : null;
+};
+/** Run `pipefy auth login`, inheriting the terminal so the browser flow works. */
+export const runToolkitLogin = async (extraArgs = []) => {
+    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 () => {
+    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());
+    }
+    catch (e) {
+        debug(`pipefy auth status failed: ${e.message}`);
+        return null;
+    }
+};
+export const UPGRADE_HINT = 'reinstall the toolkit: `uv tool install --force --reinstall pipefy-cli` (any pipefy-auth from 0.3.0a1 to 0.5.4b1 on PyPI works)';
+export const INSTALL_HINT = 'install the Pipefy AI toolkit (github.com/pipefy/ai-toolkit): `uv tool install pipefy-cli`, then `pipefy auth login`';

package/{src → dist}/pipefy/toolkit_bearer.py

@@ -31,22 +31,63 @@ def _fail(reason: str, message: str) -> int:
 
 
 def main() -> int:
+    # Import the module, then look the names up one by one, so an incompatible
+    # install says which names it lacks and which version it is — rather than
+    # one ImportError that left `pipe doctor` reporting the toolkit as "not
+    # installed" on a machine where it plainly was. Every pipefy-auth release on
+    # PyPI (0.3.0a1 through 0.5.4b1) exports all of these; a field report of
+    # one that lacked ServiceAccountAuth came from an install none of them
+    # explain, so this names what it found instead of guessing why.
     try:
-        from pipefy_auth import (  # noqa: PLC0415
-            AuthSettings,
-            OidcClient,
-            ServiceAccountAuth,
-            StaticTokenAuth,
-            StoredSessionAuth,
-            configure_keychain_backend,
-            ensure_fresh_session,
-            resolve_pipefy_auth,
-        )
-        from pipefy_auth.resolver import ServiceAccount  # noqa: PLC0415
+        import pipefy_auth  # noqa: PLC0415
     except Exception as exc:  # pragma: no cover - environment problem
         print(f"pipefy_auth is not importable: {exc}", file=sys.stderr)
         return 3
 
+    version = getattr(pipefy_auth, "__version__", None)
+    if version is None:
+        try:
+            from importlib.metadata import version as dist_version  # noqa: PLC0415
+
+            version = dist_version("pipefy-auth")
+        except Exception:
+            version = "unknown"
+    where = getattr(pipefy_auth, "__file__", "?")
+
+    # Required for every credential this helper can return.
+    required = (
+        "AuthSettings",
+        "OidcClient",
+        "StaticTokenAuth",
+        "StoredSessionAuth",
+        "ensure_fresh_session",
+        "resolve_pipefy_auth",
+    )
+    missing = [n for n in required if not hasattr(pipefy_auth, n)]
+    if missing:
+        print(
+            f"pipefy_auth {version} at {where} is incompatible: it lacks {', '.join(missing)}",
+            file=sys.stderr,
+        )
+        return 3
+
+    AuthSettings = pipefy_auth.AuthSettings
+    OidcClient = pipefy_auth.OidcClient
+    StaticTokenAuth = pipefy_auth.StaticTokenAuth
+    StoredSessionAuth = pipefy_auth.StoredSessionAuth
+    ensure_fresh_session = pipefy_auth.ensure_fresh_session
+    resolve_pipefy_auth = pipefy_auth.resolve_pipefy_auth
+    # Only a service-account credential needs these, so their absence costs
+    # that one method, not the static token or the browser session.
+    ServiceAccountAuth = getattr(pipefy_auth, "ServiceAccountAuth", None)
+    ServiceAccount = getattr(pipefy_auth, "ServiceAccount", None)
+    if ServiceAccount is None:
+        try:
+            from pipefy_auth.resolver import ServiceAccount  # noqa: PLC0415
+        except Exception:
+            ServiceAccount = None
+    configure_keychain_backend = getattr(pipefy_auth, "configure_keychain_backend", None)
+
     settings = AuthSettings()
 
     # Select the keyring backend before any session read. On Windows the default
@@ -54,10 +95,15 @@ def main() -> int:
     # ~2.5 KB), so machines set `keychain_backend = "file"` — and a reader that
     # skips this looks in the empty store and reports "not signed in" while
     # `pipefy auth status` says otherwise.
-    configure_keychain_backend(settings.keychain_backend)
+    if configure_keychain_backend is not None:
+        configure_keychain_backend(settings.keychain_backend)
 
     service_account = None
-    if settings.service_account_client_id and settings.service_account_client_secret:
+    if (
+        ServiceAccount is not None
+        and settings.service_account_client_id
+        and settings.service_account_client_secret
+    ):
         service_account = ServiceAccount(
             token_url=settings.service_account_url,
             client_id=settings.service_account_client_id,
@@ -107,7 +153,7 @@ def main() -> int:
         )
         return 0
 
-    if isinstance(resolved, ServiceAccountAuth):
+    if ServiceAccountAuth is not None and isinstance(resolved, ServiceAccountAuth):
         # The client-credentials exchange happens here so the secret never
         # crosses the process boundary — only the short-lived bearer does.
         import httpx  # noqa: PLC0415