@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/diff/render.js

@@ -0,0 +1,90 @@
+import { bold, dim, green, red, yellow, blue, magenta } from "../util/log.js";
+/** Text rendering of a ChangeSet, for the CLI. */
+const OP_MARK = {
+    create: '+',
+    delete: '-',
+    update: '~',
+    reorder: '>',
+    archive: 'a',
+    unarchive: 'u',
+};
+const colorFor = (op) => op === 'create' ? green : op === 'delete' ? red : op === 'reorder' ? magenta : yellow;
+const short = (v, max = 90) => {
+    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, indent) => `${indent}${dim(d.key)}: ${red(short(d.before))} ${dim('->')} ${green(short(d.after))}`;
+export const renderChange = (c, opts = {}) => {
+    const paint = colorFor(c.op);
+    const lines = [];
+    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, opts = {}) => {
+    const lines = [];
+    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();
+        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((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) => ({
+    mode: cs.mode,
+    from: cs.from,
+    to: cs.to,
+    summary: cs.changes.reduce((acc, c) => {
+        acc[c.op] = (acc[c.op] ?? 0) + 1;
+        return acc;
+    }, {}),
+    skipped: cs.skipped,
+    changes: cs.changes,
+});

package/dist/model/payload.js

@@ -0,0 +1,84 @@
+/**
+ * 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 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',
+];
+export const emptyRelations = () => Object.fromEntries(ENTITY_NAMES.map((n) => [n, []]));
+export const fullCoverage = (c) => Object.fromEntries(ENTITY_NAMES.map((n) => [n, c]));
+export const ENTITIES = {
+    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, n) => p.relations?.[n] ?? [];
+export const numId = (r) => {
+    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) => String(r['id'] ?? '');

package/dist/model/tree.js

@@ -0,0 +1,7 @@
+export const repoId = (t) => Number(t.repo['id']);
+export const repoName = (t) => 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) => t.phases.find((p) => Number(p['index']) === 0) ?? t.phases[0];
+export const allFields = (t) => t.phases.flatMap((p) => p.fields);
+export const fieldById = (t, id) => allFields(t).find((f) => String(f['id']) === String(id));
+export const phaseById = (t, id) => t.phases.find((p) => String(p['id']) === String(id));

package/dist/model/volatile.js

@@ -0,0 +1,54 @@
+/**
+ * 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 = (row) => {
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+        if (VOLATILE_KEYS.has(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+};
+/** The volatile values we drop, kept aside so the UI can still show them. */
+export const takeVolatile = (row) => {
+    const out = {};
+    for (const [k, v] of Object.entries(row))
+        if (VOLATILE_KEYS.has(k))
+            out[k] = v;
+    return out;
+};

package/dist/pipefy/agents.js

@@ -0,0 +1,122 @@
+import { debug } from "../util/log.js";
+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) => 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) => ({
+    ...b,
+    event_params: pruneNulls(b['event_params'] ?? {}),
+    condition: b['condition'] ?? null,
+    field_maps: [],
+    distribute_assignments: [],
+    response_schemas: [],
+});
+export const fetchAgents = async (client, repoUuid) => {
+    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 = [];
+    let after = null;
+    for (let page = 0; page < 50; page++) {
+        const data = await client.tryRaw(QUERY, { repoUuid, after }, 'ai agents');
+        const result = 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' };
+};

package/dist/pipefy/automations.js

@@ -0,0 +1,155 @@
+import { debug } from "../util/log.js";
+const EVENTS_QUERY = `query AutomationEvents {
+  automationEvents { id acceptedParameters actionsBlacklist }
+}`;
+const ACTIONS_QUERY = `query AutomationActions($repoId: ID!) {
+  automationActions(repoId: $repoId) { id acceptedParameters eventsBlacklist }
+}`;
+/**
+ * Read the catalogue for one pipe. Actions are per-repo (a pipe without AI
+ * enabled offers fewer), events are global.
+ */
+export const readAutomationCatalogue = async (client, repoId) => {
+    const [ev, ac] = await Promise.all([
+        client.raw(EVENTS_QUERY),
+        client.raw(ACTIONS_QUERY, { repoId: String(repoId) }),
+    ]);
+    const events = new Map();
+    for (const e of ev?.automationEvents ?? []) {
+        events.set(e.id, {
+            id: e.id,
+            acceptedParameters: e.acceptedParameters ?? [],
+            actionsBlacklist: e.actionsBlacklist ?? [],
+        });
+    }
+    const actions = new Map();
+    for (const a of ac?.automationActions ?? []) {
+        actions.set(a.id, {
+            id: a.id,
+            acceptedParameters: a.acceptedParameters ?? [],
+            eventsBlacklist: a.eventsBlacklist ?? [],
+        });
+    }
+    debug(`automation catalogue: ${events.size} events, ${actions.size} actions for repo ${repoId}`);
+    return { events, actions };
+};
+/**
+ * Parameter names the payload spells differently from the API.
+ *
+ * The stored row and the mutation input disagree in both directions, so a check
+ * against `acceptedParameters` has to normalise first or it reports correct
+ * automations as broken.
+ */
+const PARAM_ALIASES = {
+    // event params
+    inPhaseId: 'in_phase_id',
+    fromPhaseId: 'from_phase_id',
+    toPhaseId: 'to_phase_id',
+    triggerFieldIds: 'trigger_field_ids',
+    triggerAutomationId: 'trigger_automation_id',
+    kindOfSla: 'kind_of_sla',
+    // action params
+    fieldsMapOrder: 'fields_map_order',
+    cardId: 'card_id',
+    toPhaseIdAction: 'to_phase_id',
+    taskParams: 'task_params',
+    aiParams: 'ai_params',
+    aiBehaviorParams: 'ai_behavior_params',
+    slaParams: 'sla_params',
+    httpMethod: 'http_method',
+    emailTemplateId: 'email_template_id',
+    authenticationKey: 'authentication_key',
+    authenticationValue: 'authentication_value',
+    authenticationAddTo: 'authentication_add_to',
+    authenticationType: 'authentication_type',
+    oauth2Uuid: 'oauth2_uuid',
+};
+const canonical = (name) => PARAM_ALIASES[name] ?? name;
+/**
+ * Params the API accepts on every action regardless of the catalogue.
+ *
+ * `field_map` carries the values an `update_card_field` or `create_card` writes
+ * and is not listed in `acceptedParameters` — the catalogue lists
+ * `fields_map_order` beside it and stops. Flagging `field_map` would refuse every
+ * automation that writes a field, which is most of them.
+ */
+const ALWAYS_ALLOWED_ACTION_PARAMS = new Set(['field_map', 'schema']);
+/**
+ * Check one automation against the catalogue, before anything is sent.
+ *
+ * Returns findings rather than throwing, so the compiler can refuse the step and
+ * name the parameter — which is the whole point. An unknown event or action is an
+ * error; a catalogue this pipe does not offer is silence, not a guess.
+ */
+export const checkAutomationParams = (auto, catalogue) => {
+    const findings = [];
+    const eventId = String(auto['event_id'] ?? '');
+    const actionId = String(auto['action_id'] ?? '');
+    const event = catalogue.events.get(eventId);
+    const action = catalogue.actions.get(actionId);
+    if (eventId && !event) {
+        findings.push({
+            severity: 'error',
+            where: 'event',
+            message: `event_id ${JSON.stringify(eventId)} is not an event this endpoint offers`,
+            fix: `available: ${[...catalogue.events.keys()].join(', ')}`,
+        });
+    }
+    if (actionId && !action) {
+        findings.push({
+            severity: 'error',
+            where: 'action',
+            message: `action_id ${JSON.stringify(actionId)} is not an action this pipe offers`,
+            fix: `available: ${[...catalogue.actions.keys()].join(', ')}`,
+        });
+    }
+    if (event && action) {
+        if (event.actionsBlacklist.includes(actionId)) {
+            findings.push({
+                severity: 'error',
+                where: 'pairing',
+                message: `event ${eventId} cannot be paired with action ${actionId}`,
+            });
+        }
+        else if (action.eventsBlacklist.includes(eventId)) {
+            findings.push({
+                severity: 'error',
+                where: 'pairing',
+                message: `action ${actionId} cannot be triggered by event ${eventId}`,
+            });
+        }
+    }
+    if (event) {
+        const accepted = new Set(event.acceptedParameters.map(canonical));
+        for (const key of Object.keys((auto['event_params'] ?? {}))) {
+            const name = canonical(key);
+            if (accepted.has(name))
+                continue;
+            findings.push({
+                severity: 'error',
+                where: 'event',
+                message: `event ${eventId} does not accept event_params.${key}`,
+                fix: accepted.size
+                    ? `it accepts: ${[...accepted].join(', ')}`
+                    : `it accepts no parameters — remove event_params.${key}`,
+            });
+        }
+    }
+    if (action) {
+        const accepted = new Set(action.acceptedParameters.map(canonical));
+        for (const key of Object.keys((auto['action_params'] ?? {}))) {
+            const name = canonical(key);
+            if (accepted.has(name) || ALWAYS_ALLOWED_ACTION_PARAMS.has(name))
+                continue;
+            findings.push({
+                severity: 'error',
+                where: 'action',
+                message: `action ${actionId} does not accept action_params.${key}`,
+                fix: accepted.size
+                    ? `it accepts: ${[...accepted].join(', ')}`
+                    : `it accepts no parameters — remove action_params.${key}`,
+            });
+        }
+    }
+    return findings;
+};

package/dist/pipefy/capability.js

@@ -0,0 +1,84 @@
+import { debug } from "../util/log.js";
+/** Mutations the plan compiler emits, checked as a set so gaps are visible up front. */
+export const REQUIRED_MUTATIONS = [
+    'updatePipe',
+    'createPhase',
+    'updatePhase',
+    'deletePhase',
+    'createPhaseField',
+    'updatePhaseField',
+    'deletePhaseField',
+    'createLabel',
+    'updateLabel',
+    'deleteLabel',
+    'createWebhook',
+    'updateWebhook',
+    'deleteWebhook',
+    'createFieldCondition',
+    'updateFieldCondition',
+    'deleteFieldCondition',
+    'setFieldConditionOrder',
+    'createAutomation',
+    'updateAutomation',
+    'deleteAutomation',
+    'createPipeRelation',
+    'updatePipeRelation',
+    'deletePipeRelation',
+    'phaseSettings',
+    'updateRepoPreferences',
+    'archiveField',
+    'unarchiveField',
+    'moveCardToPhase',
+];
+export const detect = async (client, internal) => {
+    const mutationFields = await client.typeFields('Mutation');
+    const pipeFields = await client.typeFields('Pipe');
+    const has = (n) => Boolean(mutationFields?.has(n));
+    const mutations = {};
+    for (const m of REQUIRED_MUTATIONS)
+        mutations[m] = has(m);
+    const caps = {
+        snapshots: has('createRepoSnapshot') && Boolean(pipeFields?.has('snapshots') || pipeFields?.has('snapshot')),
+        /**
+         * Both spellings, because this build was looking for the wrong one.
+         *
+         * `restoreRepoSnapshot` does not exist on this endpoint and never did.
+         * **`restoreRepoToSnapshot`** does — "Restores a Pipe structure to its latest
+         * uploaded snapshot" — so every apply has printed "no one-command rollback"
+         * beside a snapshot that could in fact be restored, and `pipe rollback` has
+         * refused to try. That is the same failure as automations sitting on the
+         * internal endpoint: a name assumed once and never re-checked.
+         *
+         * The capability is still narrower than it sounds, and `restoreLatestOnly`
+         * below is what says so.
+         */
+        restoreRepoSnapshot: has('restoreRepoSnapshot') || has('restoreRepoToSnapshot'),
+        restoreMutation: has('restoreRepoToSnapshot')
+            ? 'restoreRepoToSnapshot'
+            : has('restoreRepoSnapshot')
+                ? 'restoreRepoSnapshot'
+                : null,
+        /**
+         * A restore only accepts the **latest** uploaded snapshot. Measured: an
+         * older versionId is refused with "Version_id must reference the latest
+         * uploaded snapshot of the Pipe".
+         *
+         * That is the whole story for rollback on this endpoint, and it is why the
+         * pre-apply snapshot is usually not restorable: `pipe apply` reads the repo
+         * back to verify, and that read takes a snapshot of its own, which becomes
+         * the latest. Recovery stays forward-first.
+         */
+        restoreLatestOnly: has('restoreRepoToSnapshot'),
+        createRepoDraft: has('createRepoDraft'),
+        importRepoSnapshot: has('importRepoSnapshot') || has('createRepoSnapshotFromPayload'),
+        mutations,
+        internalApi: internal?.status ?? 'unknown',
+        checkedAt: new Date().toISOString(),
+    };
+    debug(`capabilities: snapshots=${caps.snapshots} restore=${caps.restoreRepoSnapshot} ` +
+        `draft=${caps.createRepoDraft} import=${caps.importRepoSnapshot}`);
+    return caps;
+};
+export const missingMutations = (c) => Object.entries(c.mutations)
+    .filter(([, present]) => !present)
+    .map(([name]) => name);