@pipefy/pipefy-process-coder 0.1.0

package/bin/pipe.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Thin launcher so `pipe` works when the package is linked or installed
+// globally. Node >=22.18 strips the types in src/*.ts natively, so there is no
+// build step.
+//
+// The path must be converted to a file:// URL before import(): on Windows a
+// bare path like C:\...\src\cli.ts is rejected with
+// ERR_UNSUPPORTED_ESM_URL_SCHEME, since `C:` reads as a protocol.
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+await import(pathToFileURL(join(here, '..', 'src', 'cli.ts')).href);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@pipefy/pipefy-process-coder",
+  "version": "0.1.0",
+  "description": "Pull a Pipefy pipe to disk as readable JSON, edit it with an agent, diff it, push it back.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Guilherme-CA-Dias/pipefy-process-coder.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    ".agents/skills",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "bin": {
+    "pipe": "bin/pipe.js"
+  },
+  "scripts": {
+    "pipe": "node src/cli.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"test/*.test.ts\""
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/apply/adopt.ts

@@ -0,0 +1,150 @@
+import type { Row } from '../model/payload.ts';
+import type { Tree } from '../model/tree.ts';
+import type { ChangeSet } from '../diff/diff.ts';
+import type { Plan } from './types.ts';
+import { changeByKey } from './types.ts';
+import type { IdMap } from './idmap.ts';
+
+/**
+ * Adopting a created entity's real id without reading the pipe back.
+ *
+ * A create mutation's response already carries the id — that is where `IdMap`
+ * gets it from, to substitute `%{_new:<uuid>}` into *later* steps in the same
+ * run (idmap.ts). This is the other half: writing that same id into the
+ * workspace file the entity was authored in, so it stops reading `"id": null,
+ * "_new": true` and a re-plan does not create it a second time.
+ *
+ * No network read is needed because nothing about *which* row this is has to
+ * be guessed: `change.after` (from the same ChangeSet apply.ts already
+ * computed) is not a copy — `diff/diff.ts` builds every `Change` by reference
+ * into the authored tree — so mutating it here mutates the tree that gets
+ * written back.
+ *
+ * Scoped to creates on purpose. An update or delete that succeeded already
+ * matches what the file states (that is what "succeeded" means for those
+ * ops); a create is the only case where the file is missing information the
+ * mutation response just supplied.
+ */
+
+export type Adopted = { entity: string; label: string; id: number };
+
+export const adoptCreatedIds = (changeSet: ChangeSet, plan: Plan, idMap: IdMap): Adopted[] => {
+  const adopted: Adopted[] = [];
+
+  for (const step of plan.steps) {
+    if (step.status !== 'done' || !step.produces) continue;
+    const id = idMap.placeholderValue(step.produces.placeholder);
+    if (id === undefined) continue;
+
+    const change = changeByKey(changeSet, step.changeKey);
+    if (!change || change.op !== 'create' || change.entity === 'repo' || !change.after) continue;
+
+    const row = change.after as Row;
+    if (Number(row['id']) === id && row['_new'] !== true) continue; // a resumed step, already adopted
+    row['id'] = id;
+    delete row['_new'];
+    adopted.push({ entity: change.entity, label: change.label, id });
+  }
+
+  return adopted;
+};
+
+/**
+ * Where an adopted row belongs in a baseline tree — additive only.
+ *
+ * A created entity is pure addition: the previous baseline has no row for it
+ * at all, by definition, so there is nothing to overwrite and no unapplied
+ * edit to lose. `entity` and `id` are enough to find it in the already
+ * id-and-reference-resolved tree (`patched`, the output of `idMap.rewrite`),
+ * because the id this run just adopted is unique within its array.
+ */
+const findAdoptedRow = (patched: Tree, a: Adopted): Row | undefined => {
+  switch (a.entity) {
+    case 'phases':
+      return patched.phases.find((p) => Number(p['id']) === a.id);
+    case 'fields':
+      return patched.phases.flatMap((p) => p.fields).find((f) => Number(f['id']) === a.id);
+    case 'automations':
+      return patched.automations.find((au) => Number(au['id']) === a.id);
+    case 'labels':
+      return patched.labels.find((l) => Number(l['id']) === a.id);
+    case 'field_conditions':
+      return patched.field_conditions.find((fc) => Number(fc['id']) === a.id);
+    case 'webhooks':
+      return patched.webhooks.find((w) => Number(w['id']) === a.id);
+    case 'pipe_relations':
+      return patched.pipe_relations.find((r) => Number(r['id']) === a.id);
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Merge every adopted row into a baseline tree, in the order they were
+ * adopted — a new field's phase must land in `baseline.phases` before the
+ * field itself is pushed into it, and `plan.steps` already runs creates in
+ * that order (registry/compile.ts), so `adopted` does too.
+ *
+ * Mutates and returns `baseline`. Never touches a row baseline already has
+ * an opinion about — this is append-only, which is what makes it safe without
+ * a live read: the alternative (replaying an update or delete too) would
+ * require knowing the *current* baseline row to update, which is exactly the
+ * information a network read would supply and this path does not have.
+ */
+export const mergeAdoptedIntoBaseline = (baseline: Tree, patched: Tree, adopted: Adopted[]): boolean => {
+  let changed = false;
+  for (const a of adopted) {
+    const row = findAdoptedRow(patched, a);
+    if (!row) continue;
+    const clone = { ...row } as Row;
+
+    switch (a.entity) {
+      case 'phases':
+        if (baseline.phases.some((p) => Number(p['id']) === a.id)) continue;
+        baseline.phases.push(clone as Tree['phases'][number]);
+        break;
+      case 'fields': {
+        const phaseId = Number(clone['phase_id']);
+        const phase = baseline.phases.find((p) => Number(p['id']) === phaseId);
+        if (!phase || phase.fields.some((f) => Number(f['id']) === a.id)) continue;
+        phase.fields.push(clone);
+        break;
+      }
+      case 'automations':
+        if (baseline.automations.some((au) => Number(au['id']) === a.id)) continue;
+        baseline.automations.push(clone as Tree['automations'][number]);
+        break;
+      case 'labels':
+        if (baseline.labels.some((l) => Number(l['id']) === a.id)) continue;
+        baseline.labels.push(clone);
+        break;
+      case 'field_conditions':
+        if (baseline.field_conditions.some((fc) => Number(fc['id']) === a.id)) continue;
+        baseline.field_conditions.push(clone as Tree['field_conditions'][number]);
+        break;
+      case 'webhooks':
+        if (baseline.webhooks.some((w) => Number(w['id']) === a.id)) continue;
+        baseline.webhooks.push(clone);
+        break;
+      case 'pipe_relations':
+        if (baseline.pipe_relations.some((r) => Number(r['id']) === a.id)) continue;
+        baseline.pipe_relations.push(clone);
+        break;
+      default:
+        continue;
+    }
+    changed = true;
+  }
+  return changed;
+};
+
+export const renderAdopted = (adopted: Adopted[]): string[] => {
+  if (!adopted.length) return [];
+  const lines = [
+    `adopted ${adopted.length} server-assigned id${adopted.length === 1 ? '' : 's'} directly from the create ` +
+      `response(s) — no read-back needed, so a re-plan will not create them again`,
+  ];
+  for (const a of adopted.slice(0, 8)) lines.push(`   ${a.entity} ${a.label} → ${a.id}`);
+  if (adopted.length > 8) lines.push(`   …and ${adopted.length - 8} more`);
+  return lines;
+};

package/src/apply/agentops.ts

@@ -0,0 +1,71 @@
+import { createAiAgent, updateAiAgent, deleteAiAgent } from './mutations.ts';
+import type { StepRequest } from './types.ts';
+import type { AgentChangeSet } from '../diff/agents.ts';
+import type { PipefyClient } from '../pipefy/client.ts';
+
+/**
+ * Compiling agent changes into GraphQL steps.
+ *
+ * Kept separate from `apply/compile.ts`, same reasoning as the flow half:
+ * agents are not part of the `Tree` this tool folds a pipe into (they are not
+ * in the snapshot payload at all — `workspace/agents.ts`), so there is no
+ * `EntityName` for the generic compiler to key a `Change` on. Unlike flows,
+ * the requests themselves are ordinary public GraphQL — `buildGraphql`,
+ * `apply/mutations.ts` — so this stays a thin compiler over that, not a
+ * second protocol.
+ */
+
+export type AgentStep = {
+  id: string;
+  index: number;
+  changeKey: string;
+  op: 'create' | 'update' | 'delete';
+  description: string;
+  request: StepRequest;
+  destructive?: boolean;
+  status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+  error?: string;
+  result?: unknown;
+};
+
+export type AgentPlan = { steps: AgentStep[] };
+
+export const compileAgents = async (client: PipefyClient | null, cs: AgentChangeSet): Promise<AgentPlan> => {
+  const steps: AgentStep[] = [];
+  for (const [i, c] of cs.changes.entries()) {
+    const id = `a${String(i + 1).padStart(3, '0')}`;
+    if (c.op === 'create') {
+      steps.push({
+        id,
+        index: i,
+        changeKey: c.key,
+        op: 'create',
+        description: `createAiAgent — ${c.label}`,
+        request: await createAiAgent(client, c.after ?? {}, c.behaviors),
+        status: 'pending',
+      });
+    } else if (c.op === 'update') {
+      steps.push({
+        id,
+        index: i,
+        changeKey: c.key,
+        op: 'update',
+        description: `updateAiAgent — ${c.label}`,
+        request: await updateAiAgent(client, String(c.before?.['uuid'] ?? ''), c.after ?? {}, c.behaviors),
+        status: 'pending',
+      });
+    } else {
+      steps.push({
+        id,
+        index: i,
+        changeKey: c.key,
+        op: 'delete',
+        description: `deleteAiAgent — ${c.label}`,
+        destructive: true,
+        request: await deleteAiAgent(client, String(c.before?.['uuid'] ?? '')),
+        status: 'pending',
+      });
+    }
+  }
+  return { steps };
+};