@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/apply/registry.js

@@ -0,0 +1,348 @@
+export const REGISTRY = {
+    'repo.update': {
+        status: 'PARTIAL',
+        via: 'updatePipe',
+        transport: 'graphql',
+        reason: 'covers name, noun, icon, color, title_field_id, expiration_*, public and preferences; other repo columns have no input',
+        /**
+         * `UpdatePipeInput` has fifteen fields and the repos row has thirty-six, so
+         * most of what the payload shows about a pipe cannot be written back.
+         *
+         * `description` is the one that matters in practice: there is no input for
+         * it, so a workspace that sets it compiled a mutation that succeeded, changed
+         * nothing, and left the file permanently disagreeing with the pipe. Exactly
+         * the `start_form_title` failure, one entity up. Introspection filtering
+         * dropped the argument silently; naming the settable columns refuses it out
+         * loud instead.
+         */
+        settableColumns: [
+            'name',
+            'noun',
+            'icon',
+            'color',
+            'public',
+            'title_field_id',
+            'expiration_time',
+            'only_admin_can_remove_cards',
+            'only_assignees_can_edit_cards',
+        ],
+    },
+    'phases.create': { status: 'SUPPORTED', via: 'createPhase', transport: 'graphql' },
+    'phases.update': { status: 'SUPPORTED', via: 'updatePhase + phaseSettings', transport: 'graphql' },
+    'phases.delete': {
+        status: 'PARTIAL',
+        via: 'deletePhase',
+        transport: 'graphql',
+        reason: 'cards in the phase must be moved first. The Change Migrator recipes create an "Archive(Migration)" phase and move cards into it; pipe refuses unless --allow-card-moves is given',
+    },
+    'phases.reorder': {
+        status: 'UNSUPPORTED',
+        reason: 'createPhase takes index: Float, updatePhase does not — there is no way to change an existing phase index',
+        ask: 4,
+    },
+    'fields.create': { status: 'SUPPORTED', via: 'createPhaseField', transport: 'graphql' },
+    'fields.update': {
+        status: 'SUPPORTED',
+        via: 'updatePhaseField',
+        transport: 'graphql',
+        immutableFields: ['type_id', 'phase_id', 'slug'],
+        reason: 'label is NON_NULL, so every update resends the full object rather than a sparse patch',
+    },
+    'fields.delete': {
+        status: 'SUPPORTED',
+        via: 'deletePhaseField',
+        transport: 'graphql',
+        reason: 'requires pipeUuid alongside the field id, and destroys every existing value',
+    },
+    'fields.archive': {
+        status: 'SUPPORTED',
+        via: 'archiveField / unarchiveField',
+        transport: 'graphql',
+        reason: "keyed on the field's uuid, not its id",
+    },
+    'fields.reorder': { status: 'SUPPORTED', via: 'updatePhaseField (index: Float)', transport: 'graphql' },
+    'fields.change_type': {
+        status: 'UNSUPPORTED',
+        reason: 'updatePhaseField has no type_id input. Changing a field type requires delete + create, which destroys every existing value — so pipe refuses instead of doing it silently',
+        ask: 2,
+    },
+    'fields.move_phase': {
+        status: 'UNSUPPORTED',
+        reason: 'updatePhaseField has no phase_id input; moving a field between phases would destroy its data',
+        ask: 3,
+    },
+    'labels.create': { status: 'SUPPORTED', via: 'createLabel', transport: 'graphql' },
+    'labels.update': { status: 'SUPPORTED', via: 'updateLabel', transport: 'graphql' },
+    'labels.delete': { status: 'SUPPORTED', via: 'deleteLabel', transport: 'graphql' },
+    /**
+     * All three are on the PUBLIC endpoint, and were being sent to the internal
+     * one — inherited from the Change Migrator recipes and never re-checked.
+     * `createAutomation`, `updateAutomation` and `deleteAutomation` are documented
+     * public mutations with introspectable inputs; the internal endpoint has no
+     * compatibility contract and answered a bad parameter with the single word
+     * "is invalid".
+     */
+    'automations.create': {
+        status: 'SUPPORTED',
+        via: 'createAutomation',
+        transport: 'graphql',
+        reason: 'conditions, field_maps, distribute strategy and responseSchema all go in nested. Event and action parameters are checked against automationEvents/automationActions before sending, because both endpoints answer a wrong one with only "is invalid"',
+    },
+    'automations.update': {
+        status: 'SUPPORTED',
+        via: 'updateAutomation',
+        transport: 'graphql',
+        reason: 'updateAutomation in place, keeping the id, uuid and run history. The recipes delete and recreate instead, on the grounds that action_params does not round-trip; measured against the live API and it does, across every field map dimension, action_id and event_id. UpdateAutomationInput accepts every field CreateAutomationInput does. --automation-recreate restores delete+create for the case where an update is refused',
+    },
+    'automations.delete': { status: 'SUPPORTED', via: 'deleteAutomation', transport: 'graphql' },
+    /**
+     * Start form only. The mutation authorizes `phaseId` and then ignores it,
+     * placing every condition on the start form; the UI can target any phase, so
+     * there is no equivalent public write path for the rest.
+     */
+    'field_conditions.create': {
+        status: 'PARTIAL',
+        via: 'createFieldCondition',
+        transport: 'graphql',
+        reason: 'input takes phaseId (camel) while update takes phase_id (snake) — recipe steps 85/109. ' +
+            'And phaseId appears to be ignored: a create with phaseId set to a regular phase put the ' +
+            'condition on the start form instead. Verification catches it; there is no known way to ' +
+            'target a non-start-form phase on create',
+    },
+    'field_conditions.update': { status: 'SUPPORTED', via: 'updateFieldCondition', transport: 'graphql' },
+    'field_conditions.delete': { status: 'SUPPORTED', via: 'deleteFieldCondition', transport: 'graphql' },
+    'field_conditions.reorder': { status: 'SUPPORTED', via: 'setFieldConditionOrder', transport: 'graphql' },
+    'webhooks.create': { status: 'SUPPORTED', via: 'createWebhook', transport: 'graphql' },
+    'webhooks.update': { status: 'SUPPORTED', via: 'updateWebhook', transport: 'graphql' },
+    'webhooks.delete': { status: 'SUPPORTED', via: 'deleteWebhook', transport: 'graphql' },
+    'pipe_relations.create': { status: 'SUPPORTED', via: 'createPipeRelation', transport: 'graphql' },
+    'pipe_relations.update': { status: 'SUPPORTED', via: 'updatePipeRelation', transport: 'graphql' },
+    'pipe_relations.delete': { status: 'SUPPORTED', via: 'deletePipeRelation', transport: 'graphql' },
+    'phase_jumps.update': {
+        status: 'PARTIAL',
+        via: 'PUT /internal_api/settings/phases/:id',
+        transport: 'internal',
+        reason: 'no public mutation exists. Unversioned internal endpoint with no compatibility contract — isolated in one adapter, asserted on the echoed next_phase_ids, degrades to UNSUPPORTED rather than throwing',
+        ask: 1,
+    },
+    'phase_team_memberships.update': { status: 'SUPPORTED', via: 'phaseSettings (teamMemberIds)', transport: 'graphql' },
+    'repo_preferences.update': {
+        status: 'PARTIAL',
+        via: 'updateRepoPreferences (repoUuid) + updatePipe.preferences',
+        transport: 'graphql',
+        settableColumns: [
+            'hidden_start_form_attributes',
+            'hidden_top_buttons',
+            'findable',
+            'inbox_email_enabled',
+            'main_tab_views',
+        ],
+        reason: 'the surface is small and split. updateRepoPreferences accepts only hiddenStartFormAttributes ' +
+            'and hiddenTopButtons; updatePipe.preferences accepts findable, inboxEmailEnabled and ' +
+            'mainTabViews. Every other column in the payload row — start_form_title, custom_sorting_*, ' +
+            'the AI toggles, guests_can_follow_tickets, default_view — has no input on this endpoint',
+    },
+    'public_forms.update': {
+        status: 'PARTIAL',
+        via: 'updatePipe.publicFormSettings',
+        transport: 'graphql',
+        settableColumns: [
+            'title',
+            'description',
+            'submit_button_text',
+            'after_submit_message',
+            'brand_color',
+            'background_color',
+            'background_image',
+            'logo',
+            'display_pipefy_logo',
+            'show_submit_another_response_button',
+            'submitter_email_collection_enabled',
+            'submitter_email_required',
+            'submitter_email_field_id',
+            'reuse_last_submission_response',
+            'active',
+        ],
+        reason: 'PublicFormSettingsInput covers title, description, submitButtonText, afterSubmitMessage, ' +
+            'brandColor, backgroundColor/Image, logo, displayPipefyLogo, showSubmitAnotherResponseButton, ' +
+            'submitterEmail* and reuseLastSubmissionResponse. The html and css columns have no input',
+    },
+    'visibilities.update': {
+        status: 'UNSUPPORTED',
+        reason: 'only reachable through updatePipe.public_form, and slug is not settable',
+    },
+    'email_templates.create': { status: 'UNSUPPORTED', reason: 'EmailTemplate is read-only; no Input types exist', ask: 5 },
+    'email_templates.update': { status: 'UNSUPPORTED', reason: 'EmailTemplate is read-only; no Input types exist', ask: 5 },
+    'email_templates.delete': { status: 'UNSUPPORTED', reason: 'EmailTemplate is read-only; no Input types exist', ask: 5 },
+    'email_inboxes.create': { status: 'UNSUPPORTED', reason: 'no mutation found' },
+    'email_inboxes.update': { status: 'UNSUPPORTED', reason: 'no mutation found' },
+    'email_inboxes.delete': { status: 'UNSUPPORTED', reason: 'no mutation found' },
+};
+/**
+ * What can be written on a **database**, which is a different question from the
+ * same entity on a pipe.
+ *
+ * A database's payload is a pipe's — its columns are `fields`, its record
+ * statuses are `phases` — so the diff produces the same entity names for both
+ * kinds. The *mutations* are not the same: `createTableField` rather than
+ * `createPhaseField`, `updateTable` rather than `updatePipe`, and a whole class
+ * of pipe entities that a database simply does not have.
+ *
+ * So this table is authoritative for a database, and anything absent from it is
+ * refused. Falling through to the pipe registry would be worse than useless: it
+ * would report `automations.create` as SUPPORTED for a repo with no workflow, and
+ * then send `createAutomation` at it.
+ *
+ * Identifier facts behind these rows are in VALIDATION.md §3g, all measured.
+ */
+const TABLE_REGISTRY = {
+    'repo.update': {
+        status: 'PARTIAL',
+        via: 'updateTable',
+        transport: 'graphql',
+        settableColumns: [
+            'name',
+            'noun',
+            'icon',
+            'color',
+            'public',
+            'description',
+            'authorization',
+            'create_card_label',
+            'title_field_id',
+        ],
+        reason: 'updateTable covers those nine. labels and members can only be set when the database is created — UpdateTableInput has no input for either — and statuses, uuid, url and the record count have none at all. title_field_id takes the field slug or uuid, never the numeric id',
+    },
+    'fields.create': {
+        status: 'SUPPORTED',
+        via: 'createTableField',
+        transport: 'graphql',
+        reason: 'CreateTableFieldInput has no index, so a new column lands at the end and its position is a separate setTableFieldOrder call',
+    },
+    'fields.update': {
+        status: 'SUPPORTED',
+        via: 'updateTableField',
+        transport: 'graphql',
+        immutableFields: ['type_id', 'index', 'slug', 'uuid', 'phase_id', 'is_multiple'],
+        settableColumns: [
+            'label',
+            'options',
+            'description',
+            'help',
+            'required',
+            'unique',
+            'minimal_view',
+            'custom_validation',
+            'can_search_connected_cards',
+            'can_connect_multiple_cards',
+            'can_create_connected_cards',
+            'child_must_exist_to_finish_parent',
+            'all_children_must_be_done_to_finish_parent',
+        ],
+        reason: 'addressed by the field slug, with table_id alongside it. type and index have no input on UpdateTableFieldInput',
+    },
+    'fields.delete': {
+        status: 'SUPPORTED',
+        via: 'deleteTableField',
+        transport: 'graphql',
+        reason: 'addressed by the field slug. Deleting a column destroys its value in every record of the database',
+    },
+    'fields.reorder': {
+        status: 'SUPPORTED',
+        via: 'setTableFieldOrder',
+        transport: 'graphql',
+        reason: 'set-replacing per database: the whole ordered list of field slugs is sent. It returns the applied order, so the step asserts its own effect rather than trusting a 200',
+    },
+    'fields.change_type': {
+        status: 'UNSUPPORTED',
+        ask: 2,
+        reason: 'UpdateTableFieldInput has no type. Changing it would mean delete + create, which destroys that column in every record — the same wall as a pipe field, one repo kind over',
+    },
+    'fields.archive': {
+        status: 'UNSUPPORTED',
+        reason: 'there is no archiveTableField. A database column can only be deleted, and that destroys data — so there is no non-destructive way to retire one',
+    },
+    'fields.move_phase': {
+        status: 'UNSUPPORTED',
+        reason: 'a database has one form. There is nowhere to move a column to',
+    },
+    /**
+     * Labels work on a database exactly as they do on a pipe — measured as full
+     * CRUD. The catch is only in the create: `CreateLabelInput` has both `pipe_id`
+     * and `table_id`, and a database id sent as `pipe_id` is refused with `Pipe not
+     * found with id: <the database id>`, which reads like a missing capability and
+     * is not one.
+     */
+    'labels.create': {
+        status: 'SUPPORTED',
+        via: 'createLabel',
+        transport: 'graphql',
+        reason: 'CreateLabelInput.table_id, not pipe_id — the latter is refused with "Pipe not found"',
+    },
+    'labels.update': { status: 'SUPPORTED', via: 'updateLabel', transport: 'graphql' },
+    'labels.delete': { status: 'SUPPORTED', via: 'deleteLabel', transport: 'graphql' },
+    /**
+     * Webhooks are refused on a database, and this one is a judgement rather than a
+     * missing path — so the measurement is recorded to stop someone "fixing" it.
+     *
+     * `createWebhook` with a database id **is accepted**, and the webhook really
+     * attaches: it reads back under `Table.webhooks`. But Pipefy does not offer
+     * webhooks on a database, no database in this org has one, and the actions on
+     * offer are card-shaped (`card.create` and friends) while a database holds
+     * records. A write path that is accepted and inert is worse than one that is
+     * refused, so it is refused until somebody needs it and can say what it should
+     * fire on.
+     */
+    'webhooks.create': {
+        status: 'UNSUPPORTED',
+        reason: 'createWebhook accepts a database id and the webhook does attach — measured — but Pipefy does not offer webhooks on a database and the available actions are card-shaped, so one would sit there doing nothing. Refused rather than left as a trap',
+    },
+    'webhooks.update': { status: 'UNSUPPORTED', reason: 'see webhooks.create — not offered on a database' },
+    'webhooks.delete': { status: 'UNSUPPORTED', reason: 'see webhooks.create — not offered on a database' },
+};
+/** Entities a database does not have, refused with the reason rather than a shrug. */
+const NO_WORKFLOW = new Set([
+    'phases',
+    'phase_jumps',
+    'phase_team_memberships',
+    'automations',
+    'conditions',
+    'condition_expressions',
+    'field_maps',
+    'distribute_assignments',
+    'response_schemas',
+    'field_conditions',
+    'field_condition_actions',
+]);
+export const support = (entity, op, kind = 'pipe') => {
+    if (kind === 'table') {
+        const hit = TABLE_REGISTRY[`${entity}.${op}`];
+        if (hit)
+            return hit;
+        if (entity !== 'repo' && NO_WORKFLOW.has(entity)) {
+            return {
+                status: 'UNSUPPORTED',
+                reason: `a database has no workflow, so ${entity} cannot be changed on one. Its phases are record statuses ` +
+                    'and its only form holds the columns. If this change is meant to automate something, it belongs on a pipe',
+            };
+        }
+        return {
+            status: 'UNSUPPORTED',
+            reason: `${entity}.${op} is not proven on a database. The mutation may exist and accept a table id, but it has ` +
+                'not been measured, and this tool refuses rather than finding out on your data',
+        };
+    }
+    const hit = REGISTRY[`${entity}.${op}`];
+    if (hit)
+        return hit;
+    return {
+        status: 'UNSUPPORTED',
+        reason: `no write path is registered for ${entity}.${op} — if one exists, add it to src/apply/registry.ts`,
+    };
+};
+export const registryRows = () => Object.entries(REGISTRY).map(([key, v]) => {
+    const [entity, op] = key.split('.');
+    return { key, entity, op, ...v };
+});
+/** Distinct asks referenced by the registry — the evidence-backed ask list. */
+export const registryAsks = () => [...new Set(registryRows().map((r) => r.ask).filter((a) => typeof a === 'number'))].sort((a, b) => a - b);

package/dist/apply/types.js

@@ -0,0 +1,18 @@
+export const stepSummary = (plan) => {
+    const byStatus = plan.steps.reduce((acc, s) => {
+        acc[s.status]++;
+        return acc;
+    }, { pending: 0, running: 0, done: 0, failed: 0, skipped: 0 });
+    return byStatus;
+};
+export const changeByKey = (cs, key) => cs.changes.find((c) => c.key === key);
+export const supportToClassification = (c, s, op) => ({
+    changeKey: c.key,
+    entity: c.entity,
+    op,
+    status: s.status,
+    via: s.via,
+    reason: s.reason,
+    ask: s.ask,
+    label: c.label,
+});

package/dist/cli/args.js

@@ -0,0 +1,79 @@
+import { UserError } from "../util/log.js";
+export const parse = (argv) => {
+    const [command = 'help', ...rest] = argv;
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--') {
+            positionals.push(...rest.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith('--')) {
+            const [rawName, inlineValue] = arg.slice(2).split('=', 2);
+            const name = rawName;
+            if (inlineValue !== undefined) {
+                addFlag(flags, name, inlineValue);
+                continue;
+            }
+            const next = rest[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                addFlag(flags, name, next);
+                i++;
+            }
+            else {
+                flags[name] = true;
+            }
+            continue;
+        }
+        if (arg.startsWith('-') && arg.length > 1) {
+            for (const ch of arg.slice(1))
+                flags[ch] = true;
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return { command, positionals, flags };
+};
+const addFlag = (flags, name, value) => {
+    const existing = flags[name];
+    if (existing === undefined) {
+        flags[name] = value;
+        return;
+    }
+    if (Array.isArray(existing))
+        existing.push(value);
+    else
+        flags[name] = [String(existing), value];
+};
+export const str = (p, name, fallback) => {
+    const v = p.flags[name];
+    if (v === undefined || v === true)
+        return fallback;
+    if (Array.isArray(v))
+        return v[v.length - 1];
+    return String(v);
+};
+export const bool = (p, name, fallback = false) => {
+    const v = p.flags[name];
+    if (v === undefined)
+        return fallback;
+    if (v === 'false' || v === '0' || v === 'no')
+        return false;
+    return Boolean(v);
+};
+export const int = (p, name, fallback) => {
+    const v = str(p, name);
+    if (v === undefined)
+        return fallback;
+    const n = Number(v);
+    if (!Number.isInteger(n))
+        throw new UserError(`--${name} must be an integer, got "${v}"`);
+    return n;
+};
+export const requirePositional = (p, index, what) => {
+    const v = p.positionals[index];
+    if (!v)
+        throw new UserError(`missing ${what}`, `see \`pipe help ${p.command}\``);
+    return v;
+};

package/dist/cli.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import { parse, bool } from "./cli/args.js";
+import { UserError, bold, dim, error as logError, info, out, setVerbose, yellow } from "./util/log.js";
+const commands = {
+    login: {
+        summary: 'store a Pipefy API token',
+        help: async () => (await import("./commands/misc.js")).loginHelp,
+        run: async (p) => (await import("./commands/misc.js")).login(p),
+    },
+    doctor: {
+        summary: 'report what this endpoint can actually do',
+        help: async () => (await import("./commands/misc.js")).doctorHelp,
+        run: async (p) => (await import("./commands/misc.js")).doctor(p),
+    },
+    skills: {
+        summary: 'the Claude Code skills this install ships with; install them for every project',
+        help: async () => (await import("./commands/skills.js")).help,
+        run: async (p) => (await import("./commands/skills.js")).run(p),
+    },
+    create: {
+        summary: 'create an empty pipe and pull it, ready to be built from files',
+        help: async () => (await import("./commands/create.js")).help,
+        run: async (p) => (await import("./commands/create.js")).run(p),
+    },
+    pull: {
+        summary: 'pull a pipe and everything it connects to into a workspace',
+        help: async () => (await import("./commands/pull.js")).help,
+        run: async (p) => (await import("./commands/pull.js")).run(p),
+    },
+    export: {
+        summary: 'export one repo as a single snapshot-shaped payload',
+        help: async () => (await import("./commands/misc.js")).exportHelp,
+        run: async (p) => (await import("./commands/misc.js")).exportCmd(p),
+    },
+    validate: {
+        summary: 'check JSON shape and referential integrity, offline',
+        help: async () => (await import("./commands/misc.js")).validateHelp,
+        run: async (p) => (await import("./commands/misc.js")).validate(p),
+    },
+    diff: {
+        summary: 'what changed — against the baseline, live, or another pipe',
+        help: async () => (await import("./commands/diff.js")).help,
+        run: async (p) => (await import("./commands/diff.js")).run(p),
+    },
+    plan: {
+        summary: 'classify every change and order the applicable ones',
+        help: async () => (await import("./commands/plan.js")).help,
+        run: async (p) => (await import("./commands/plan.js")).run(p),
+    },
+    apply: {
+        summary: 'snapshot, apply step by step, verify',
+        help: async () => (await import("./commands/apply.js")).help,
+        run: async (p) => (await import("./commands/apply.js")).run(p),
+    },
+    verify: {
+        summary: 'read the pipe back and diff it against the workspace',
+        help: async () => (await import("./commands/verify.js")).help,
+        run: async (p) => (await import("./commands/verify.js")).run(p),
+    },
+    rollback: {
+        summary: 'restore a snapshot',
+        help: async () => (await import("./commands/misc.js")).rollbackHelp,
+        run: async (p) => (await import("./commands/misc.js")).rollback(p),
+    },
+    runs: {
+        summary: 'every run recorded in this workspace, and what each one did',
+        help: async () => (await import("./commands/runs.js")).help,
+        run: async (p) => (await import("./commands/runs.js")).run(p),
+    },
+    status: {
+        summary: 'what is in this workspace and how it was read',
+        help: async () => (await import("./commands/misc.js")).statusHelp,
+        run: async (p) => (await import("./commands/misc.js")).status(p),
+    },
+    capabilities: {
+        summary: 'the write-coverage registry',
+        help: async () => (await import("./commands/misc.js")).capsHelp,
+        run: async (p) => (await import("./commands/misc.js")).capabilities(p),
+    },
+    roundtrip: {
+        summary: 'codec self-check: pack(unpack(P)) must equal P',
+        help: async () => (await import("./commands/misc.js")).roundtripHelp,
+        run: async (p) => (await import("./commands/misc.js")).roundtrip(p),
+    },
+    viewer: {
+        summary: 'build the HTML diff view and open it',
+        help: async () => (await import("./commands/misc.js")).viewerHelp,
+        run: async (p) => (await import("./commands/misc.js")).viewer(p),
+    },
+};
+const usage = () => {
+    const width = Math.max(...Object.keys(commands).map((k) => k.length)) + 2;
+    out(bold('pipe') + ' — Pipefy process coder');
+    out('');
+    out('  Pull a pipe to disk as readable JSON, edit it with Claude, diff it, push it back.');
+    out('');
+    out(bold('usage'));
+    out('  pipe <command> [options]');
+    out('');
+    out(bold('commands'));
+    for (const [name, cmd] of Object.entries(commands)) {
+        out(`  ${name.padEnd(width)} ${dim(cmd.summary)}`);
+    }
+    out('');
+    out(bold('the loop'));
+    out(`  pipe pull <pipeId> --out ./my-pipe        ${dim('# snapshot, or GraphQL if there are none')}`);
+    out(`  pipe validate                             ${dim('# offline, instant')}`);
+    out(`  pipe diff --open                          ${dim('# see it')}`);
+    out(`  pipe plan --dry-run                       ${dim('# refuses what cannot be applied')}`);
+    out(`  pipe apply                                ${dim('# snapshot, apply, verify')}`);
+    out('');
+    out(bold('global options'));
+    out(`  --verbose      ${dim('log every request, retry and dropped argument')}`);
+    out(`  --help         ${dim('help for a command')}`);
+    out('');
+    out(dim('First run: pipe login --token <token>, then pipe doctor.'));
+};
+const main = async () => {
+    const argv = process.argv.slice(2);
+    const parsed = parse(argv);
+    setVerbose(bool(parsed, 'verbose') || bool(parsed, 'v'));
+    /**
+     * `--version` before anything else. It is the first thing anyone types to check
+     * an install worked, and answering it with `unknown command "--version"` makes a
+     * working install look broken.
+     *
+     * The path is included because `npm link` puts a symlink on PATH: when two
+     * clones exist, or one was moved, "which one am I running" is the actual
+     * question behind the version check.
+     */
+    if (parsed.command === '--version' || parsed.command === '-V' || parsed.command === 'version') {
+        const { readFile } = await import('node:fs/promises');
+        const { fileURLToPath } = await import('node:url');
+        const { dirname, join } = await import('node:path');
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(await readFile(join(here, '..', 'package.json'), 'utf8'));
+        out(`${pkg.name} ${pkg.version}`);
+        out(dim(`  node    ${process.version} (needs >=22.18 for native type stripping)`));
+        out(dim(`  running ${fileURLToPath(import.meta.url)}`));
+        return 0;
+    }
+    if (parsed.command === 'help' || parsed.command === '--help' || parsed.command === '-h' || !argv.length) {
+        const topic = parsed.positionals[0];
+        if (topic && commands[topic]) {
+            out(await commands[topic].help());
+            return 0;
+        }
+        usage();
+        return 0;
+    }
+    const cmd = commands[parsed.command];
+    if (!cmd) {
+        logError(`unknown command "${parsed.command}"`);
+        const near = Object.keys(commands).filter((k) => k.startsWith(parsed.command[0] ?? ''));
+        if (near.length)
+            info(dim(`did you mean: ${near.join(', ')}?`));
+        info(dim('run `pipe help` for the list'));
+        return 64;
+    }
+    if (bool(parsed, 'help') || bool(parsed, 'h')) {
+        out(await cmd.help());
+        return 0;
+    }
+    const code = await cmd.run(parsed);
+    return typeof code === 'number' ? code : 0;
+};
+main()
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((e) => {
+    if (e instanceof UserError) {
+        logError(e.message);
+        if (e.hint)
+            info(`${yellow('hint')}  ${e.hint}`);
+        process.exitCode = 65;
+        return;
+    }
+    logError(e.message);
+    if (process.env.PPC_DEBUG || bool(parse(process.argv.slice(2)), 'verbose')) {
+        info(dim(String(e.stack)));
+    }
+    else {
+        info(dim('run again with --verbose for a stack trace'));
+    }
+    process.exitCode = 70;
+});