@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/src/model/volatile.ts

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1,165 +0,0 @@
-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' };
-};

package/src/pipefy/automations.ts

@@ -1,219 +0,0 @@
-import { debug } from '../util/log.ts';
-import type { PipefyClient } from './client.ts';
-
-/**
- * The automation event and action catalogue, read from the **public** API.
- *
- * Pipefy publishes exactly what each event and each action accepts —
- * `automationEvents.acceptedParameters`, `automationActions.acceptedParameters` —
- * and which combinations are refused. Without reading it, a wrong parameter name
- * is only discovered by sending the mutation, and the answer is the single word
- * `is invalid`, from both the public and the internal endpoint. Nothing names the
- * parameter, the event, or the action.
- *
- * The case that motivated this: an automation meaning "when a card lands in
- * New Request, move it to Archived" was written as
- *
- *     event_id: 'card_moved', event_params: { inPhaseId: '<phaseId>' }
- *
- * `inPhaseId` is real — it belongs to `card_inbox_received_email`. `card_moved`
- * accepts only `to_phase_id`. Both endpoints answered `is invalid` and the apply
- * failed at step one with nothing to act on.
- */
-
-export type AutomationEventSpec = {
-  id: string;
-  /** Parameter names this event accepts, in the API's own snake_case. */
-  acceptedParameters: string[];
-  /** Actions this event cannot be paired with. */
-  actionsBlacklist: string[];
-};
-
-export type AutomationActionSpec = {
-  id: string;
-  acceptedParameters: string[];
-  eventsBlacklist: string[];
-};
-
-export type AutomationCatalogue = {
-  events: Map<string, AutomationEventSpec>;
-  actions: Map<string, AutomationActionSpec>;
-};
-
-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: PipefyClient,
-  repoId: number | string,
-): Promise<AutomationCatalogue> => {
-  const [ev, ac] = await Promise.all([
-    client.raw<{ automationEvents: AutomationEventSpec[] }>(EVENTS_QUERY),
-    client.raw<{ automationActions: AutomationActionSpec[] }>(ACTIONS_QUERY, { repoId: String(repoId) }),
-  ]);
-
-  const events = new Map<string, AutomationEventSpec>();
-  for (const e of ev?.automationEvents ?? []) {
-    events.set(e.id, {
-      id: e.id,
-      acceptedParameters: e.acceptedParameters ?? [],
-      actionsBlacklist: e.actionsBlacklist ?? [],
-    });
-  }
-  const actions = new Map<string, AutomationActionSpec>();
-  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: Record<string, string> = {
-  // 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: string) => 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']);
-
-export type ParamFinding = {
-  severity: 'error' | 'warning';
-  where: 'event' | 'action' | 'pairing';
-  message: string;
-  fix?: string;
-};
-
-/**
- * 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: Record<string, unknown>,
-  catalogue: AutomationCatalogue,
-): ParamFinding[] => {
-  const findings: ParamFinding[] = [];
-  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'] ?? {}) as Record<string, unknown>)) {
-      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'] ?? {}) as Record<string, unknown>)) {
-      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/src/pipefy/capability.ts

@@ -1,119 +0,0 @@
-import { debug } from '../util/log.ts';
-import type { PipefyClient } from './client.ts';
-import type { InternalApi } from './internal.ts';
-
-/**
- * Capability detection. PLAN.md §1.2: `restoreRepoSnapshot` and
- * `createRepoDraft` carry the entire safety model but do not exist on every
- * endpoint, so the app detects them at startup and degrades explicitly rather
- * than failing mid-apply.
- */
-
-export type Capabilities = {
-  /** Read paths. */
-  snapshots: boolean;
-  /** Safety primitives. */
-  restoreRepoSnapshot: boolean;
-  /** Which spelling this endpoint has, so the caller does not guess. */
-  restoreMutation: 'restoreRepoToSnapshot' | 'restoreRepoSnapshot' | null;
-  /** Whether a restore is limited to the newest snapshot. Measured, not assumed. */
-  restoreLatestOnly: boolean;
-  createRepoDraft: boolean;
-  /** Route B, tracked so `pipe doctor` reports the day it lands. */
-  importRepoSnapshot: boolean;
-  /** Public write paths this build depends on. */
-  mutations: Record<string, boolean>;
-  /** The internal endpoint — phase jumps and automation details. */
-  internalApi: 'ok' | 'unavailable' | 'unknown';
-  checkedAt: string;
-};
-
-/** 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',
-] as const;
-
-export const detect = async (client: PipefyClient, internal?: InternalApi): Promise<Capabilities> => {
-  const mutationFields = await client.typeFields('Mutation');
-  const pipeFields = await client.typeFields('Pipe');
-  const has = (n: string) => Boolean(mutationFields?.has(n));
-
-  const mutations: Record<string, boolean> = {};
-  for (const m of REQUIRED_MUTATIONS) mutations[m] = has(m);
-
-  const caps: Capabilities = {
-    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: Capabilities): string[] =>
-  Object.entries(c.mutations)
-    .filter(([, present]) => !present)
-    .map(([name]) => name);