@pipefy/pipefy-process-coder 0.1.0

package/src/codec/unpack.ts

@@ -0,0 +1,198 @@
+import { rel, type EntityName, type PayloadEnvelope, type RepoPayload, type Row } from '../model/payload.ts';
+import { stripVolatile } from '../model/volatile.ts';
+import type { AutomationNode, ConditionNode, FieldConditionNode, PhaseNode, Tree } from '../model/tree.ts';
+
+/**
+ * payload → tree.
+ *
+ * Folding is *movement only*: a folded row is the payload row, unchanged, moved
+ * under its owner. The only rewriting is (a) stripping volatile columns and
+ * (b) dropping the owner-pointer columns that folding makes redundant, both of
+ * which `pack` restores. That is what makes `pack(unpack(P)) ≡ P` a property of
+ * the design rather than of the care taken.
+ *
+ * Keys beginning with `_` are tool metadata, not pipe structure. They survive a
+ * round trip and are ignored by every comparator.
+ */
+
+const idOf = (r: Row): string => String(r['id'] ?? '');
+
+const num = (v: unknown): number | null => {
+  if (v === null || v === undefined || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+const byIndex = (a: Row, b: Row) => {
+  const ai = num(a['index']);
+  const bi = num(b['index']);
+  if (ai !== null && bi !== null && ai !== bi) return ai - bi;
+  return (num(a['id']) ?? 0) - (num(b['id']) ?? 0);
+};
+
+/** Which key a phase_team_memberships row uses for the user id. */
+const teamMemberKey = (row: Row): string | null => {
+  for (const k of ['user_id', 'member_id', 'team_member_id', 'user']) {
+    if (k in row && num(row[k]) !== null) return k;
+  }
+  return null;
+};
+
+/**
+ * Attach a condition to its owner. `conditions` rows point at their owner with
+ * (source_type, source_id); expressions point at the condition with
+ * `condition_id`, except in a reconstructed payload where no condition id
+ * exists and `_condition_owner` carries the same information.
+ */
+const takeCondition = (
+  payload: RepoPayload,
+  sourceType: 'Automation' | 'FieldCondition',
+  sourceId: string,
+): ConditionNode | null => {
+  const cond = rel(payload, 'conditions').find(
+    (c) => String(c['source_type']) === sourceType && String(c['source_id']) === sourceId,
+  );
+  if (!cond) return null;
+
+  const condId = idOf(cond);
+  const expressions = rel(payload, 'condition_expressions')
+    .filter((e) => {
+      if (condId && String(e['condition_id'] ?? '') === condId) return true;
+      const owner = e['_condition_owner'] as Row | undefined;
+      return Boolean(owner && String(owner['source_type']) === sourceType && String(owner['source_id']) === sourceId);
+    })
+    .map((e) => {
+      const row = stripVolatile({ ...e });
+      // Restored by pack from the owning condition.
+      delete row['condition_id'];
+      delete row['_condition_owner'];
+      return row;
+    })
+    .sort((a, b) => (num(a['structure_id']) ?? 0) - (num(b['structure_id']) ?? 0) || (num(a['id']) ?? 0) - (num(b['id']) ?? 0));
+
+  const node = stripVolatile({ ...cond }) as ConditionNode;
+  // Restored by pack from the owner it is nested under.
+  delete (node as Row)['source_type'];
+  delete (node as Row)['source_id'];
+  node.expressions = expressions;
+  return node;
+};
+
+export const unpack = (env: PayloadEnvelope): Tree => {
+  const p = env.payload;
+
+  const root: Row = {};
+  for (const [k, v] of Object.entries(p)) {
+    if (k === 'relations') continue;
+    root[k] = v;
+  }
+
+  const fieldsByPhase = new Map<string, Row[]>();
+  for (const f of rel(p, 'fields')) {
+    const key = String(f['phase_id'] ?? '');
+    const arr = fieldsByPhase.get(key) ?? [];
+    arr.push(f);
+    fieldsByPhase.set(key, arr);
+  }
+
+  const phases: PhaseNode[] = [...rel(p, 'phases')].sort(byIndex).map((raw) => {
+    const phaseId = idOf(raw);
+    const node = stripVolatile({ ...raw }) as PhaseNode;
+
+    node.fields = (fieldsByPhase.get(phaseId) ?? [])
+      .slice()
+      .sort(byIndex)
+      .map((f) => stripVolatile({ ...f }));
+
+    node.jump_target_ids = rel(p, 'phase_jumps')
+      .filter((j) => String(j['source_phase_id']) === phaseId)
+      .map((j) => num(j['target_phase_id']))
+      .filter((v): v is number => v !== null)
+      .sort((a, b) => a - b);
+
+    const memberships = rel(p, 'phase_team_memberships').filter((m) => String(m['phase_id']) === phaseId);
+    const key = memberships.length ? teamMemberKey(memberships[0] as Row) : null;
+    node.team_member_ids = key
+      ? memberships.map((m) => num(m[key])).filter((v): v is number => v !== null).sort((a, b) => a - b)
+      : [];
+    if (key && key !== 'user_id') (node as Row)['_team_member_key'] = key;
+
+    return node;
+  });
+
+  const automations: AutomationNode[] = rel(p, 'automations').map((raw) => {
+    const id = idOf(raw);
+    const node = stripVolatile({ ...raw }) as AutomationNode;
+    node.condition = takeCondition(p, 'Automation', id);
+    node.field_maps = rel(p, 'field_maps')
+      .filter((m) => String(m['owner_type']) === 'Automation' && String(m['owner_id']) === id)
+      .map((m) => {
+        const row = stripVolatile({ ...m });
+        delete row['owner_type'];
+        delete row['owner_id'];
+        return row;
+      });
+    node.distribute_assignments = rel(p, 'distribute_assignments')
+      .filter((d) => String(d['automation_id'] ?? d['owner_id'] ?? '') === id)
+      .map((d) => {
+        const row = stripVolatile({ ...d });
+        delete row['automation_id'];
+        return row;
+      });
+    node.response_schemas = rel(p, 'response_schemas')
+      .filter((s) => String(s['automation_id'] ?? s['owner_id'] ?? '') === id)
+      .map((s) => {
+        const row = stripVolatile({ ...s });
+        delete row['automation_id'];
+        return row;
+      });
+    return node;
+  });
+
+  const field_conditions: FieldConditionNode[] = [...rel(p, 'field_conditions')].sort(byIndex).map((raw) => {
+    const id = idOf(raw);
+    const node = stripVolatile({ ...raw }) as FieldConditionNode;
+    node.actions = rel(p, 'field_condition_actions')
+      .filter((a) => String(a['field_condition_id']) === id)
+      .map((a) => {
+        const row = stripVolatile({ ...a });
+        delete row['field_condition_id'];
+        return row;
+      });
+    node.condition = takeCondition(p, 'FieldCondition', id);
+    return node;
+  });
+
+  const simple = (n: EntityName): Row[] => rel(p, n).map((r) => stripVolatile({ ...r }));
+
+  return {
+    meta: {
+      source: env.source,
+      versionId: env.versionId ?? null,
+      readAt: env.readAt,
+      repoKind: env.repoKind,
+      coverage: env.coverage,
+      repo_columns: env.repo_columns ?? 'complete',
+      notes: env.notes,
+    },
+    repo: stripVolatile(root),
+    phases,
+    automations,
+    field_conditions,
+    labels: simple('labels'),
+    webhooks: simple('webhooks'),
+    pipe_relations: simple('pipe_relations'),
+    public_form: simple('public_forms')[0] ?? null,
+    preferences: simple('repo_preferences')[0] ?? null,
+    readonly: {
+      email_templates: simple('email_templates'),
+      email_inboxes: simple('email_inboxes'),
+      visibilities: simple('visibilities'),
+      // owner_type/owner_id kept — see model/tree.ts. The automation-owned half
+      // above already claimed and stripped its rows; this is everything left.
+      field_maps: rel(p, 'field_maps')
+        .filter((m) => String(m['owner_type']) !== 'Automation')
+        .map((m) => stripVolatile({ ...m })),
+    },
+  };
+};

package/src/commands/agents.ts

@@ -0,0 +1,184 @@
+import { info, dim, ok, warn, debug } from '../util/log.ts';
+import { fetchAgents } from '../pipefy/agents.ts';
+import type { PipefyClient } from '../pipefy/client.ts';
+import {
+  writeAgents,
+  writeAgentBaseline,
+  readAgents,
+  readAgentBaseline,
+  unknownAgents,
+  agentDirName,
+  type AgentsSection,
+} from '../workspace/agents.ts';
+import { readTree } from '../workspace/read.ts';
+import { diffAgents, groupBehaviorsByAgentDir, type AgentChangeSet } from '../diff/agents.ts';
+import { compileAgents, type AgentPlan, type AgentStep } from '../apply/agentops.ts';
+import type { Tree } from '../model/tree.ts';
+
+/**
+ * The agent half of the pipe loop: read, diff, plan, apply.
+ *
+ * A behavior's own edits already flow through the ordinary automation
+ * diff/plan/apply once it is placed under its agent's `behaviors/`
+ * (workspace/agents.ts) — the row is folded into `tree.automations` like any
+ * other automation. But *sending* one is not the automation mutations: this
+ * pipe's action catalogue does not offer `ai_behavior` to `createAutomation`
+ * (confirmed live, refused), and the confirmed write path — captured from
+ * real Pipefy web UI traffic and reproduced directly — is a single
+ * `createAiAgent` / `updateAiAgent` call carrying the agent's *entire*
+ * behaviors list. So `diff/diff.ts` and `apply/compile.ts` are taught to skip
+ * any automation tagged `_agent_dir`, and this module is the whole agent-side
+ * pipeline instead: read the agent's fields plus its current behaviors
+ * (grouped from the already-read tree, since `agent.json` never carries them),
+ * diff against the baseline, compile straight to `createAiAgent` /
+ * `updateAiAgent` / `deleteAiAgent`, and send.
+ */
+
+/** Read a pipe's AI agents, or record why they could not be read. */
+export const pullAgentsFor = async (client: PipefyClient, repoUuid: string | null | undefined): Promise<AgentsSection> => {
+  if (!repoUuid) return unknownAgents('this repo has no uuid on the row that was read, so agents cannot be looked up');
+
+  const read = await fetchAgents(client, repoUuid);
+  return {
+    meta: {
+      coverage: read.status,
+      readAt: new Date().toISOString(),
+      agents: read.status === 'complete' ? read.agents.length : undefined,
+      notes: read.note ? [read.note] : [],
+    },
+    agents: read.agents,
+  };
+};
+
+/** Pull and write, mirroring `pullAndWriteFlows`. Returns what was read. */
+export const pullAndWriteAgents = async (
+  client: PipefyClient,
+  repoId: number,
+  repoUuid: string | null | undefined,
+  repoDir: string,
+  opts: { workspaceRoot?: string } = {},
+): Promise<AgentsSection> => {
+  const section = await pullAgentsFor(client, repoUuid);
+  await writeAgents(repoDir, section);
+  if (opts.workspaceRoot) await writeAgentBaseline(opts.workspaceRoot, repoId, section);
+  return section;
+};
+
+/**
+ * The agent diff: baseline against the workspace's own files.
+ *
+ * `tree`, if the caller already read one for the pipe half, is reused rather
+ * than reading the whole workspace a second time — `agent.json` alone cannot
+ * answer "what are this agent's current behaviors", only `tree.automations`
+ * (filtered to what `_agent_dir` tags) can.
+ */
+export const diffAgentsFor = async (
+  root: string,
+  repoId: number,
+  dir: string,
+  opts: { tree?: Tree } = {},
+): Promise<AgentChangeSet> => {
+  const baseline = await readAgentBaseline(root, repoId);
+  const authored = await readAgents(dir);
+  const tree = opts.tree ?? (await readTree(dir));
+  const behaviorsByDir = groupBehaviorsByAgentDir(tree.automations);
+  return diffAgents(baseline, authored, behaviorsByDir);
+};
+
+export const planAgents = (client: PipefyClient | null, cs: AgentChangeSet): Promise<AgentPlan> => compileAgents(client, cs);
+
+/**
+ * The revert change set, given both sides already read — the pure half of
+ * `planAgentRevert`, mirroring `buildFlowRevertPlan` (commands/flows.ts).
+ *
+ * A live agent read is self-contained — `AgentRow.behaviors` carries the full
+ * list (pipefy/agents.ts), unlike the authored-files side, which needs a
+ * whole tree to answer the same question because a behavior's file lives
+ * under its agent's `behaviors/` folder, not inside `agent.json`. So `before`
+ * alone is enough to build the map `diffAgents` needs for the *target* side.
+ *
+ * Direction is the mirror of an ordinary apply: `live` is the current state
+ * (baseline), `before` is the old pre-apply one (intended target).
+ */
+export const buildAgentRevertChangeSet = (live: AgentsSection, before: AgentsSection): AgentChangeSet => {
+  const behaviorsByDir = new Map(before.agents.map((a) => [agentDirName(a), a.behaviors ?? []]));
+  return diffAgents(live, before, behaviorsByDir);
+};
+
+/**
+ * What reverting to a pre-apply agent state would take — computed, not sent.
+ *
+ * `before` is a live read taken right before this apply's own agent diff was
+ * computed — the only rollback point agents have, since they are not part of
+ * the snapshot payload at all (ROUTE-B-V2.md ask 5) and their diff is
+ * ordinarily computed offline against the local baseline, which never took
+ * this read on its own. `live` here is read fresh, because some steps may
+ * have landed since `before` was taken.
+ */
+export const planAgentRevert = async (
+  client: PipefyClient,
+  repoUuid: string | null | undefined,
+  before: AgentsSection,
+): Promise<{ plan: AgentPlan; live: AgentsSection }> => {
+  const live = await pullAgentsFor(client, repoUuid);
+  const changeSet = buildAgentRevertChangeSet(live, before);
+  return { plan: await planAgents(client, changeSet), live };
+};
+
+export const renderAgentPlan = (plan: AgentPlan): string => {
+  const lines: string[] = [];
+  if (!plan.steps.length) {
+    lines.push('  agents: nothing to apply');
+    return lines.join('\n');
+  }
+  lines.push('');
+  lines.push(`  ${plan.steps.length} agent step(s)`);
+  for (const s of plan.steps) {
+    lines.push(`    ${s.id} ${s.description}${s.destructive ? '  destructive' : ''}`);
+  }
+  return lines.join('\n');
+};
+
+export type AgentApplyResult = { done: number; failed: number; skipped: number; steps: AgentStep[] };
+
+/**
+ * Execute the agent steps.
+ *
+ * No resumability, no placeholder substitution — unlike the pipe half's
+ * executor, an agent step never depends on an id created earlier in the same
+ * plan (an agent's own uuid is not referenced by anything else this tool
+ * writes), so the machinery `apply/execute.ts` needs for that would be
+ * unused weight here. Same simplification the flow half already makes.
+ */
+export const applyAgentSteps = async (
+  client: PipefyClient,
+  plan: AgentPlan,
+  opts: { dryRun?: boolean; continueOnError?: boolean } = {},
+): Promise<AgentApplyResult> => {
+  for (const step of plan.steps) {
+    if (opts.dryRun) {
+      step.status = 'skipped';
+      info(dim(`   (dry run) ${step.id} ${step.description} — not sent`));
+      continue;
+    }
+
+    step.status = 'running';
+    try {
+      if (step.request.missingRequired?.length) {
+        throw new Error(`missing required field(s): ${step.request.missingRequired.join(', ')}`);
+      }
+      debug(JSON.stringify(step.request.variables ?? {}).slice(0, 400));
+      step.result = await client.raw(step.request.query ?? '', step.request.variables, step.description);
+      step.status = 'done';
+      ok(`${step.id} ${step.description}`);
+    } catch (e) {
+      step.status = 'failed';
+      step.error = (e as Error).message;
+      warn(`${step.id} ${step.description} — ${step.error}`);
+      if (!opts.continueOnError) break;
+    }
+  }
+
+  const count = (s: AgentStep['status']) => plan.steps.filter((x) => x.status === s).length;
+  return { done: count('done'), failed: count('failed'), skipped: count('skipped'), steps: plan.steps };
+};