@pipefy/pipefy-process-coder 0.1.0

package/src/diff/render.ts

@@ -0,0 +1,101 @@
+import { bold, dim, green, red, yellow, blue, magenta } from '../util/log.ts';
+import type { Change, ChangeSet, FieldDelta } from './diff.ts';
+
+/** Text rendering of a ChangeSet, for the CLI. */
+
+const OP_MARK: Record<Change['op'], string> = {
+  create: '+',
+  delete: '-',
+  update: '~',
+  reorder: '>',
+  archive: 'a',
+  unarchive: 'u',
+};
+
+const colorFor = (op: Change['op']) =>
+  op === 'create' ? green : op === 'delete' ? red : op === 'reorder' ? magenta : yellow;
+
+const short = (v: unknown, max = 90): string => {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'string') return v.length > max ? JSON.stringify(v.slice(0, max) + '…') : JSON.stringify(v);
+  const s = JSON.stringify(v);
+  return s.length > max ? s.slice(0, max) + '…' : s;
+};
+
+const renderDelta = (d: FieldDelta, indent: string): string =>
+  `${indent}${dim(d.key)}: ${red(short(d.before))} ${dim('->')} ${green(short(d.after))}`;
+
+export const renderChange = (c: Change, opts: { verbose?: boolean } = {}): string[] => {
+  const paint = colorFor(c.op);
+  const lines: string[] = [];
+  const flags = c.flags.length ? ' ' + dim(`[${c.flags.join(' ')}]`) : '';
+  lines.push(`  ${paint(OP_MARK[c.op])} ${bold(c.entity)} ${c.label}${flags}`);
+
+  const deltas = opts.verbose ? c.deltas : c.deltas.slice(0, 6);
+  for (const d of deltas) lines.push(renderDelta(d, '      '));
+  if (c.deltas.length > deltas.length) {
+    lines.push(`      ${dim(`…and ${c.deltas.length - deltas.length} more field${c.deltas.length - deltas.length === 1 ? '' : 's'}`)}`);
+  }
+
+  if (c.op === 'create' && c.after && !c.deltas.length) {
+    const keys = Object.keys(c.after).filter((k) => !k.startsWith('_')).slice(0, 8);
+    lines.push(`      ${dim(keys.map((k) => `${k}=${short(c.after?.[k], 30)}`).join(' '))}`);
+  }
+  return lines;
+};
+
+export const renderChangeSet = (cs: ChangeSet, opts: { verbose?: boolean } = {}): string => {
+  const lines: string[] = [];
+  const header =
+    cs.mode === 'cross-repo'
+      ? `${cs.from.name} (${cs.from.repoId}) -> ${cs.to.name} (${cs.to.repoId})`
+      : `${cs.to.name} (${cs.to.repoId})`;
+  lines.push(bold(`${cs.mode} diff — ${header}`));
+  lines.push(dim(`baseline read from ${cs.from.source}; compared tree read from ${cs.to.source}`));
+  lines.push('');
+
+  if (!cs.changes.length) {
+    lines.push(green('  no changes'));
+  } else {
+    const byEntity = new Map<string, Change[]>();
+    for (const c of cs.changes) {
+      const arr = byEntity.get(c.entity) ?? [];
+      arr.push(c);
+      byEntity.set(c.entity, arr);
+    }
+    for (const [entity, group] of byEntity) {
+      lines.push(blue(`${entity} (${group.length})`));
+      for (const c of group) lines.push(...renderChange(c, opts));
+      lines.push('');
+    }
+  }
+
+  if (cs.skipped.length) {
+    lines.push(yellow('not diffed — no read path on one side:'));
+    for (const s of cs.skipped) lines.push(`  ${s.entity}: ${dim(s.reason)}`);
+    lines.push('');
+  }
+
+  const counts = cs.changes.reduce<Record<string, number>>((acc, c) => {
+    acc[c.op] = (acc[c.op] ?? 0) + 1;
+    return acc;
+  }, {});
+  const summary = Object.entries(counts)
+    .map(([op, n]) => `${n} ${op}`)
+    .join(', ');
+  lines.push(bold(summary || 'nothing to do'));
+  return lines.join('\n');
+};
+
+/** Machine-readable form, for `--json` and for the HTML view. */
+export const toJson = (cs: ChangeSet) => ({
+  mode: cs.mode,
+  from: cs.from,
+  to: cs.to,
+  summary: cs.changes.reduce<Record<string, number>>((acc, c) => {
+    acc[c.op] = (acc[c.op] ?? 0) + 1;
+    return acc;
+  }, {}),
+  skipped: cs.skipped,
+  changes: cs.changes,
+});

package/src/model/payload.ts

@@ -0,0 +1,154 @@
+/**
+ * The snapshot payload: the `repos` row (snake_case DB columns) plus
+ * `relations` with twenty flat entity arrays. This shape is the canonical
+ * intermediate for BOTH read paths — snapshot download and GraphQL
+ * reconstruction — so everything downstream (codec, diff, plan) is written
+ * once. PLAN.md §1.3.
+ */
+
+export type Row = Record<string, unknown>;
+
+export const ENTITY_NAMES = [
+  'phases',
+  'phase_team_memberships',
+  'phase_jumps',
+  'fields',
+  'field_conditions',
+  'field_condition_actions',
+  'automations',
+  'conditions',
+  'condition_expressions',
+  'field_maps',
+  'distribute_assignments',
+  'response_schemas',
+  'repo_preferences',
+  'labels',
+  'pipe_relations',
+  'email_inboxes',
+  'webhooks',
+  'public_forms',
+  'email_templates',
+  'visibilities',
+] as const;
+
+export type EntityName = (typeof ENTITY_NAMES)[number];
+
+export type Relations = Record<EntityName, Row[]>;
+
+export type RepoPayload = Row & { id: number; relations: Relations };
+
+export const emptyRelations = (): Relations =>
+  Object.fromEntries(ENTITY_NAMES.map((n) => [n, [] as Row[]])) as Relations;
+
+/**
+ * How much of an entity array a given read actually knows about.
+ *
+ * This is the safety mechanism a non-snapshot read requires and that neither
+ * PLAN.md nor PLAN-ROUTE-B.md has: a reconstructed payload cannot distinguish
+ * "this pipe has no webhooks" from "I have no way to read webhooks". Recording
+ * `unknown` keeps pack and diff from ever reading absence as deletion
+ * (PLAN-ROUTE-B.md §7 — "a dropped entity means the importer deletes it").
+ */
+export type Coverage = 'complete' | 'partial' | 'unknown';
+
+export type PayloadEnvelope = {
+  /** Where the structure came from. */
+  source: 'snapshot' | 'reconstructed';
+  /** Snapshot version id, when source === 'snapshot'. */
+  versionId?: string | null;
+  /** ISO time of the read. */
+  readAt: string;
+  repoKind: 'pipe' | 'table';
+  coverage: Record<EntityName, Coverage>;
+  /** Whether the repo row's own columns were all readable. */
+  repo_columns?: Coverage;
+  /** What the read path could not see, for the docs and the diff header. */
+  notes: string[];
+  payload: RepoPayload;
+};
+
+export const fullCoverage = (c: Coverage): Record<EntityName, Coverage> =>
+  Object.fromEntries(ENTITY_NAMES.map((n) => [n, c])) as Record<EntityName, Coverage>;
+
+export type Identity = 'uuid' | 'id' | 'owned';
+
+export type EntitySpec = {
+  name: EntityName;
+  /**
+   * How an entity is recognised across two reads.
+   * `uuid` is present on only 4 of 20 arrays (PLAN.md §1.3); `owned` entities
+   * have no identity of their own and are diffed as a replace-set under their
+   * owner, exactly as ROUTE-B-V2.md §4 proposes the importer treat them.
+   */
+  identity: Identity;
+  /** For `owned`: the columns naming the owner, in precedence order. */
+  ownerKeys?: string[];
+  /** Fallback natural key, used when matching across two different repos. */
+  naturalKey?: string[];
+  /** No public write path exists — PLAN.md §2. */
+  readonly?: boolean;
+  /** Written through the internal API rather than public GraphQL. */
+  internal?: boolean;
+  /** Folded into the owner's file by the codec rather than getting its own. */
+  foldedInto?: EntityName;
+};
+
+export const ENTITIES: Record<EntityName, EntitySpec> = {
+  phases: { name: 'phases', identity: 'uuid', naturalKey: ['name'] },
+  fields: { name: 'fields', identity: 'uuid', naturalKey: ['phase_id', 'label'], foldedInto: 'phases' },
+  automations: { name: 'automations', identity: 'uuid', naturalKey: ['name'] },
+  labels: { name: 'labels', identity: 'uuid', naturalKey: ['name'] },
+
+  field_conditions: { name: 'field_conditions', identity: 'id', naturalKey: ['phase_id', 'name'] },
+  webhooks: { name: 'webhooks', identity: 'id', naturalKey: ['name', 'url'] },
+  pipe_relations: { name: 'pipe_relations', identity: 'id', naturalKey: ['parent_id', 'child_id', 'name'] },
+
+  conditions: { name: 'conditions', identity: 'owned', ownerKeys: ['source_type', 'source_id'] },
+  condition_expressions: { name: 'condition_expressions', identity: 'owned', ownerKeys: ['condition_id'] },
+  field_maps: { name: 'field_maps', identity: 'owned', ownerKeys: ['owner_type', 'owner_id'] },
+  field_condition_actions: {
+    name: 'field_condition_actions',
+    identity: 'owned',
+    ownerKeys: ['field_condition_id'],
+    foldedInto: 'field_conditions',
+  },
+  phase_jumps: { name: 'phase_jumps', identity: 'owned', ownerKeys: ['source_phase_id'], internal: true },
+  phase_team_memberships: {
+    name: 'phase_team_memberships',
+    identity: 'owned',
+    ownerKeys: ['phase_id'],
+    foldedInto: 'phases',
+  },
+  distribute_assignments: {
+    name: 'distribute_assignments',
+    identity: 'owned',
+    ownerKeys: ['automation_id'],
+    foldedInto: 'automations',
+  },
+  response_schemas: {
+    name: 'response_schemas',
+    identity: 'owned',
+    ownerKeys: ['automation_id'],
+    foldedInto: 'automations',
+  },
+
+  public_forms: { name: 'public_forms', identity: 'owned', ownerKeys: ['repo_id'] },
+  repo_preferences: { name: 'repo_preferences', identity: 'owned', ownerKeys: ['repo_id'] },
+
+  visibilities: { name: 'visibilities', identity: 'owned', ownerKeys: ['resource_type', 'resource_id'], readonly: true },
+  email_templates: { name: 'email_templates', identity: 'id', readonly: true },
+  email_inboxes: { name: 'email_inboxes', identity: 'id', readonly: true },
+};
+
+export const READONLY_ENTITIES = ENTITY_NAMES.filter((n) => ENTITIES[n].readonly);
+
+export const rel = (p: RepoPayload, n: EntityName): Row[] => p.relations?.[n] ?? [];
+
+export const numId = (r: Row): number | null => {
+  const v = r['id'];
+  if (typeof v === 'number') return v;
+  if (typeof v === 'string' && /^\d+$/.test(v)) return Number(v);
+  return null;
+};
+
+export const strId = (r: Row): string => String(r['id'] ?? '');

package/src/model/tree.ts

@@ -0,0 +1,99 @@
+import type { Coverage, EntityName, Row } from './payload.ts';
+
+/**
+ * The workspace tree — what Claude and the FDE actually edit. PLAN.md §4.
+ *
+ * Folding is *movement only*: a folded row is the payload row, unchanged, moved
+ * under its owner. Nothing is renamed or reshaped, which is what makes
+ * `pack(unpack(P))` equal to `P` by construction rather than by care.
+ */
+
+export type ConditionNode = Row & {
+  /** condition_expressions rows belonging to this condition. */
+  expressions: Row[];
+};
+
+export type PhaseNode = Row & {
+  /** fields rows whose phase_id is this phase, ordered by index. */
+  fields: Row[];
+  /**
+   * phase_jumps targets for this phase, as a set. The internal settings
+   * endpoint is set-replacing (PLAN.md §2.1), so a set is the honest shape and
+   * there is no add/remove diffing to get wrong.
+   */
+  jump_target_ids: Array<number | string>;
+  /** phase_team_memberships, flattened to the user ids phaseSettings takes. */
+  team_member_ids: Array<number | string>;
+};
+
+export type AutomationNode = Row & {
+  condition?: ConditionNode | null;
+  field_maps: Row[];
+  distribute_assignments: Row[];
+  response_schemas: Row[];
+};
+
+export type FieldConditionNode = Row & {
+  actions: Row[];
+  condition?: ConditionNode | null;
+};
+
+export type TreeMeta = {
+  source: 'snapshot' | 'reconstructed';
+  versionId?: string | null;
+  readAt: string;
+  repoKind: 'pipe' | 'table';
+  coverage: Record<EntityName, Coverage>;
+  /**
+   * Whether the repo row itself was read in full. The public API has no
+   * `color_uuid`, `authorization` or `draft`, so a reconstructed root is
+   * partial — and the diff must not read those absences as "set to null".
+   */
+  repo_columns: Coverage;
+  notes: string[];
+};
+
+export type Tree = {
+  meta: TreeMeta;
+  /** The `repos` row, volatile columns stripped. */
+  repo: Row;
+  phases: PhaseNode[];
+  automations: AutomationNode[];
+  field_conditions: FieldConditionNode[];
+  labels: Row[];
+  webhooks: Row[];
+  pipe_relations: Row[];
+  public_form: Row | null;
+  preferences: Row | null;
+  /** PLAN.md §4: first-class, so the planner can reject edits by path alone. */
+  readonly: {
+    email_templates: Row[];
+    email_inboxes: Row[];
+    visibilities: Row[];
+    /**
+     * `field_maps` owned by a **field**, not an automation — a connector
+     * field's own "copy this value from the connected card" configuration.
+     * `unpack`/`pack` only ever modelled the automation-owned half of this
+     * entity (PLAN.md, ROUTE-B-V2.md both describe it that way), so these rows
+     * were silently dropped on every pull until the round-trip check caught it.
+     * `owner_type`/`owner_id` are kept, unlike the automation-nested form,
+     * because this is a flat bucket spanning however many fields own one.
+     */
+    field_maps: Row[];
+  };
+};
+
+export const repoId = (t: Tree): number => Number(t.repo['id']);
+export const repoName = (t: Tree): string => String(t.repo['name'] ?? `repo ${repoId(t)}`);
+
+/** The start form is a phase (id/index 0). PLAN.md §4 — deleting it is catastrophic. */
+export const startFormPhase = (t: Tree): PhaseNode | undefined =>
+  t.phases.find((p) => Number(p['index']) === 0) ?? t.phases[0];
+
+export const allFields = (t: Tree): Row[] => t.phases.flatMap((p) => p.fields);
+
+export const fieldById = (t: Tree, id: string | number): Row | undefined =>
+  allFields(t).find((f) => String(f['id']) === String(id));
+
+export const phaseById = (t: Tree, id: string | number): PhaseNode | undefined =>
+  t.phases.find((p) => String(p['id']) === String(id));

package/src/model/volatile.ts

@@ -0,0 +1,55 @@
+/**
+ * PLAN.md 9: "Volatile fields will make every diff pure noise." These change
+ * with no structural edit, so the codec strips them on unpack and the
+ * comparator ignores them. Without this, `pipe diff` is unusable on day one.
+ */
+
+export const VOLATILE_KEYS = new Set([
+  'created_at',
+  'updated_at',
+  'deleted_at',
+  'created_by_id',
+  'updated_by_id',
+  'run_count',
+  'cards_count',
+  'users_count',
+  'opened_cards_count',
+  'last_updated_by_card',
+  'cloning',
+  'sequential_id',
+  'clone_from_id',
+  'cloned_from_id',
+  'cloned_from_phase_uuid',
+  'cloned_from_field_uuid',
+  'migrated_from_repo_uuid',
+]);
+
+/**
+ * Server-owned identity and ownership columns. Kept in the files (Claude needs
+ * to read them for a field reference to mean anything) but never diffed as
+ * content, because they are consequences of structure rather than structure.
+ */
+export const SERVER_OWNED_KEYS = new Set([
+  'id',
+  'repo_id',
+  'organization_id',
+  'organization_uuid',
+  'suid',
+  'slug',
+]);
+
+export const stripVolatile = <T extends Record<string, unknown>>(row: T): T => {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (VOLATILE_KEYS.has(k)) continue;
+    out[k] = v;
+  }
+  return out as T;
+};
+
+/** The volatile values we drop, kept aside so the UI can still show them. */
+export const takeVolatile = (row: Record<string, unknown>): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(row)) if (VOLATILE_KEYS.has(k)) out[k] = v;
+  return out;
+};

package/src/pipefy/agents.ts

@@ -0,0 +1,165 @@
+import { debug } from '../util/log.ts';
+import type { Row } from '../model/payload.ts';
+import type { PipefyClient } from './client.ts';
+
+/**
+ * AI agents — not in the snapshot payload at all (ROUTE-B-V2.md ask 5), so read
+ * separately over the public GraphQL API, keyed by the pipe's **uuid**, not its
+ * numeric id.
+ *
+ * `AiAgent.behaviors` answers with full `Automation` rows — a behavior is not a
+ * new kind of thing, it is an automation with `action_id: "ai_behavior"`. But
+ * the *snapshot* payload's row for one is a stub: `behavior_uuid` plus a couple
+ * of field-id lists, no `instruction`, no `actionsAttributes` — the actual
+ * configuration only exists behind this query. So this is the one source for a
+ * behavior's real content; the snapshot's copy of it is never used.
+ *
+ * The query aliases every field to the snake_case name the rest of this tool
+ * already uses on disk (matching `automations/*.json`), so nothing downstream
+ * has to know these rows came from a different endpoint.
+ */
+
+export type AgentRow = Row & {
+  uuid: string;
+  name: string;
+  /** Full automation-shaped rows — same content `workspace/agents.ts` files under `behaviors/`. */
+  behaviors: Row[];
+};
+
+export type AgentsRead = {
+  agents: AgentRow[];
+  /** `complete` means this pull read them; `unknown` means it could not. */
+  status: 'complete' | 'unknown';
+  note?: string;
+};
+
+type Edge = { node: Row & { behaviors?: Row[] | null } };
+type Page = { edges: Edge[]; pageInfo: { hasNextPage: boolean; endCursor: string | null } };
+
+const QUERY = `
+  query($repoUuid: ID!, $after: String) {
+    aiAgents(repoUuid: $repoUuid, first: 50, after: $after) {
+      edges {
+        node {
+          uuid
+          name
+          instruction
+          repoUuid
+          disabledAt
+          needReview
+          dataSourceIds
+          createdAt
+          updatedAt
+          behaviors {
+            id
+            uuid
+            name
+            active
+            event_id
+            action_id
+            event_params {
+              to_phase_id
+              from_phase_id: fromPhaseId
+              in_phase_id: inPhaseId
+              trigger_field_ids: triggerFieldIds
+              kind_of_sla: kindOfSla
+              trigger_automation_id: triggerAutomationId
+            }
+            condition {
+              id
+              expressions_structure
+              expressions { id field_address operation value structure_id }
+            }
+            action_params {
+              ai_behavior_params: aiBehaviorParams {
+                data_source_ids: dataSourceIds
+                instruction
+                referenced_field_ids: referencedFieldIds
+                provider_id: providerId
+                system_provider_id: systemProviderId
+                actions_attributes: actionsAttributes {
+                  id
+                  name
+                  action_type: actionType
+                  reference_id: referenceId
+                  metadata {
+                    destination_phase_id: destinationPhaseId
+                    pipe_id: pipeId
+                    table_id: tableId
+                    email_template_id: emailTemplateId
+                    allow_template_modifications: allowTemplateModifications
+                    mcp_server_id: mcpServerId
+                    tool_name: toolName
+                    title
+                    emails
+                    tool_inputs: toolInputs { name source value field_id: fieldId }
+                    fields_attributes: fieldsAttributes { field_id: fieldId input_mode: inputMode value }
+                  }
+                }
+                capabilities_attributes: capabilitiesAttributes { capability_type: capabilityType enabled }
+              }
+            }
+          }
+        }
+      }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+`;
+
+/**
+ * `event_params` always comes back with every key this query asked for, most
+ * of them null for any given event — `card_created` genuinely accepts none of
+ * them. An ordinary automation's `event_params` only ever has the keys its
+ * own event actually uses, and `pipe validate` checks a present key against
+ * the event's catalogue regardless of its value, so a null one reads as one
+ * more thing this event does not accept. Dropped to match.
+ */
+const pruneNulls = (o: Row): Row => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== null && v !== undefined));
+
+/** A behavior as the query returns it, given the shape `tree.automations` (AutomationNode) needs. */
+const normaliseBehavior = (b: Row): Row => ({
+  ...b,
+  event_params: pruneNulls((b['event_params'] as Row) ?? {}),
+  condition: b['condition'] ?? null,
+  field_maps: [],
+  distribute_assignments: [],
+  response_schemas: [],
+});
+
+export const fetchAgents = async (client: PipefyClient, repoUuid: string): Promise<AgentsRead> => {
+  const queryFields = await client.typeFields('Query');
+  if (!queryFields?.has('aiAgents')) {
+    debug('no aiAgents query on this schema');
+    return { agents: [], status: 'unknown', note: 'agents: no aiAgents query on this endpoint — AI agents cannot be read or checked' };
+  }
+
+  const agents: AgentRow[] = [];
+  let after: string | null = null;
+  for (let page = 0; page < 50; page++) {
+    const data: { aiAgents: Page | null } | null = await client.tryRaw(QUERY, { repoUuid, after }, 'ai agents');
+    const result: Page | null | undefined = data?.aiAgents;
+    if (!result) {
+      return {
+        agents: [],
+        status: 'unknown',
+        note: 'agents: aiAgents exists but did not answer — AI agent configuration is unverified',
+      };
+    }
+
+    for (const { node } of result.edges) {
+      const { behaviors, ...rest } = node;
+      agents.push({
+        ...rest,
+        uuid: String(rest['uuid']),
+        name: String(rest['name'] ?? ''),
+        behaviors: (behaviors ?? []).map(normaliseBehavior),
+      });
+    }
+
+    if (!result.pageInfo.hasNextPage) break;
+    after = result.pageInfo.endCursor;
+  }
+
+  return { agents, status: 'complete' };
+};