@pipefy/pipefy-process-coder 0.1.0

package/src/apply/registry.ts

@@ -0,0 +1,430 @@
+import type { EntityName } from '../model/payload.ts';
+
+/**
+ * The capability registry — PLAN.md §2.3.
+ *
+ * Hand-maintained deliberately: the names are not derivable by convention
+ * (`createFieldConditionInput` is lowercase-c, `UpdateFieldConditionInput`
+ * isn't; `phaseSettings` takes `SettingsInput`; `updatePhaseField.label` is
+ * NON_NULL). It is also the evidence-backed API ask list — every wall an FDE
+ * hits is a logged data point, and the `ask` field points at the entry in
+ * ROUTE-B-V2.md §8 that would remove it.
+ *
+ * The worst failure mode this exists to prevent: Claude edits something with no
+ * write path and the apply reports success having ignored it.
+ */
+
+export type Op = 'create' | 'update' | 'delete' | 'reorder' | 'archive' | 'change_type' | 'move_phase';
+
+export type Status = 'SUPPORTED' | 'PARTIAL' | 'UNSUPPORTED';
+
+export type Support = {
+  status: Status;
+  /** Mutation name, or the REST route for internal calls. */
+  via?: string;
+  transport?: 'graphql' | 'internal';
+  /** Why it is PARTIAL or UNSUPPORTED, in words an FDE can relay to a client. */
+  reason?: string;
+  /** Which platform ask would fix it (ROUTE-B-V2.md §8 / PLAN.md §8). */
+  ask?: number;
+  /** Fields that cannot be changed by this path even when the entity is writable. */
+  immutableFields?: string[];
+  /**
+   * When set, the *only* columns this path can write. A change touching anything
+   * else is refused by name.
+   *
+   * Entity-level PARTIAL is not enough on its own: `repo_preferences.update`
+   * exists, so a change to `start_form_title` compiled into a mutation that
+   * succeeded and changed nothing, leaving the workspace permanently dirty and
+   * the author with no way to tell. Which is the failure mode the registry is
+   * here to prevent.
+   */
+  settableColumns?: string[];
+};
+
+type Key = `${EntityName | 'repo'}.${Op}`;
+
+export const REGISTRY: Partial<Record<Key, Support>> = {
+  '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: Partial<Record<Key, Support>> = {
+  '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<EntityName>([
+  '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: EntityName | 'repo', op: Op, kind: 'pipe' | 'table' = 'pipe'): Support => {
+  if (kind === 'table') {
+    const hit = TABLE_REGISTRY[`${entity}.${op}` as Key];
+    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}` as Key];
+  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 = (): Array<{ key: string; entity: string; op: string } & Support> =>
+  Object.entries(REGISTRY).map(([key, v]) => {
+    const [entity, op] = key.split('.') as [string, string];
+    return { key, entity, op, ...(v as Support) };
+  });
+
+/** Distinct asks referenced by the registry — the evidence-backed ask list. */
+export const registryAsks = (): number[] =>
+  [...new Set(registryRows().map((r) => r.ask).filter((a): a is number => typeof a === 'number'))].sort((a, b) => a - b);

package/src/apply/types.ts

@@ -0,0 +1,134 @@
+import type { EntityName } from '../model/payload.ts';
+import type { Change, ChangeSet } from '../diff/diff.ts';
+import type { Op, Status, Support } from './registry.ts';
+
+export type StepKind =
+  /** Public GraphQL mutation. */
+  | 'graphql'
+  /** GraphQL over the internal endpoint (automations). */
+  | 'internal-graphql'
+  /** REST over the internal endpoint (phase jumps). */
+  | 'internal-rest'
+  /** Recorded for the log but sends nothing. */
+  | 'noop';
+
+export type StepRequest = {
+  /** graphql / internal-graphql */
+  query?: string;
+  variables?: Record<string, unknown>;
+  mutation?: string;
+  /** internal-rest */
+  method?: string;
+  path?: string;
+  form?: Record<string, string[]>;
+  /**
+   * Required input fields this request has no value for. Such a request is
+   * certain to be rejected, so the compiler refuses to emit the step and names
+   * the missing field instead of discovering it mid-apply.
+   */
+  missingRequired?: string[];
+};
+
+/**
+ * A placeholder for an id that does not exist yet. New entities have no id
+ * until applied, so any step that references one carries the placeholder and
+ * the executor substitutes the real id after the creating step succeeds.
+ * PLAN.md §9 — this fails only on the combination "create field + reference it
+ * in the same plan", which is exactly the common case.
+ */
+export type Placeholder = string;
+
+export type StepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+
+export type Step = {
+  id: string;
+  index: number;
+  /** The change this step serves, so the viewer can line them up. */
+  changeKey: string;
+  entity: EntityName | 'repo';
+  op: Op;
+  kind: StepKind;
+  description: string;
+  request: StepRequest;
+  /**
+   * Records the created id under this placeholder, plus any aliases an author
+   * might have written by hand (`%{_new:<uuid>}`, per the generated AGENTS.md).
+   */
+  produces?: { placeholder: Placeholder; path: string[]; aliases?: Placeholder[] };
+  /** Placeholders this step's request depends on. */
+  needs: Placeholder[];
+  /** True when the shape of this call could not be verified against the schema. */
+  unverified?: boolean;
+  /** Destructive steps require confirmation before a non-dry run. */
+  destructive?: boolean;
+  status: StepStatus;
+  result?: unknown;
+  error?: string;
+  startedAt?: string;
+  finishedAt?: string;
+};
+
+export type Classification = {
+  changeKey: string;
+  entity: EntityName | 'repo';
+  op: Op;
+  status: Status;
+  via?: string;
+  reason?: string;
+  ask?: number;
+  /** The change, kept so a plan file is self-contained for the viewer. */
+  label: string;
+};
+
+export type PlanOptions = {
+  /** Recreate automations instead of calling updateAutomation (the recipes' choice). */
+  automationStrategy: 'recreate' | 'update';
+  /** Permit steps that move cards (phase deletes). */
+  allowCardMoves: boolean;
+  /** Apply even though some changes are unsupported. Never the default. */
+  force: boolean;
+};
+
+export type Plan = {
+  id: string;
+  createdAt: string;
+  workspace: string;
+  repoId: number;
+  repoUuid: string | null;
+  mode: ChangeSet['mode'];
+  options: PlanOptions;
+  steps: Step[];
+  classifications: Classification[];
+  /** UNSUPPORTED classifications — the plan cannot execute while any remain. */
+  blocked: Classification[];
+  warnings: string[];
+  /** Pre-seeded id map: cross-repo migration mappings from the diff. */
+  idMap: Record<string, number>;
+  /** Snapshot taken before applying, for rollback. */
+  preApplyVersionId?: string | null;
+  status: 'planned' | 'running' | 'applied' | 'failed' | 'partially-applied';
+};
+
+export const stepSummary = (plan: Plan) => {
+  const byStatus = plan.steps.reduce<Record<StepStatus, number>>(
+    (acc, s) => {
+      acc[s.status]++;
+      return acc;
+    },
+    { pending: 0, running: 0, done: 0, failed: 0, skipped: 0 },
+  );
+  return byStatus;
+};
+
+export const changeByKey = (cs: ChangeSet, key: string): Change | undefined => cs.changes.find((c) => c.key === key);
+
+export const supportToClassification = (c: Change, s: Support, op: Op): Classification => ({
+  changeKey: c.key,
+  entity: c.entity,
+  op,
+  status: s.status,
+  via: s.via,
+  reason: s.reason,
+  ask: s.ask,
+  label: c.label,
+});

package/src/cli/args.ts

@@ -0,0 +1,88 @@
+import { UserError } from '../util/log.ts';
+
+/**
+ * Argument parsing. Hand-rolled because the whole CLI has zero runtime
+ * dependencies — `node src/cli.ts` works on a clean checkout with no install,
+ * which matters a lot for a tool an FDE will run on a client's laptop.
+ */
+
+export type Parsed = {
+  command: string;
+  positionals: string[];
+  flags: Record<string, string | boolean | string[]>;
+};
+
+export const parse = (argv: string[]): Parsed => {
+  const [command = 'help', ...rest] = argv;
+  const positionals: string[] = [];
+  const flags: Record<string, string | boolean | string[]> = {};
+
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i] as string;
+    if (arg === '--') {
+      positionals.push(...rest.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('--')) {
+      const [rawName, inlineValue] = arg.slice(2).split('=', 2);
+      const name = rawName as string;
+      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: Parsed['flags'], name: string, value: string) => {
+  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: Parsed, name: string, fallback?: string): string | undefined => {
+  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: Parsed, name: string, fallback = false): boolean => {
+  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: Parsed, name: string, fallback: number): number => {
+  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: Parsed, index: number, what: string): string => {
+  const v = p.positionals[index];
+  if (!v) throw new UserError(`missing ${what}`, `see \`pipe help ${p.command}\``);
+  return v;
+};