@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/dist/validate/schema.js

@@ -0,0 +1,278 @@
+/**
+ * Field types, as a **fallback only**.
+ *
+ * The authority is `REFERENCE.md` / `.ppc/reference.json`, read from the API on
+ * the last pull and checked in `validate/reference.ts`. This list is what remains
+ * when a workspace has no reference yet, and it is kept a warning because a
+ * hand-maintained list of what an API accepts goes stale invisibly: this one
+ * carried `time_range`, which the API does not offer, and omitted
+ * `dynamic_content`, which it does — warning about a valid type and passing an
+ * invalid one, with nothing to reveal either.
+ */
+const FIELD_TYPES = new Set([
+    'assignee_select',
+    'attachment',
+    'checklist_horizontal',
+    'checklist_vertical',
+    'cnpj',
+    'connector',
+    'cpf',
+    'currency',
+    'date',
+    'datetime',
+    'due_date',
+    'dynamic_content',
+    'email',
+    'id',
+    'label_select',
+    'long_text',
+    'number',
+    'phone',
+    'radio_horizontal',
+    'radio_vertical',
+    'select',
+    'short_text',
+    'statement',
+    'time',
+    'time_range',
+]);
+const isNewEntity = (row) => row['id'] === null || row['id'] === undefined || row['_new'] === true;
+const requireString = (row, key, entity, file, findings) => {
+    const v = row[key];
+    if (typeof v !== 'string' || !v.trim()) {
+        findings.push({ severity: 'error', file, entity, message: `${key} is required and must be a non-empty string` });
+    }
+};
+export const validateSchema = (tree) => {
+    const findings = [];
+    // ── repo ───────────────────────────────────────────────────────────────────
+    if (!tree.repo['id']) {
+        findings.push({ severity: 'error', file: 'pipe.json', entity: 'repo', message: 'id is missing — the repo row must keep its server-owned id' });
+    }
+    requireString(tree.repo, 'name', 'repo', 'pipe.json', findings);
+    // ── the start form is a phase, and must stay one ───────────────────────────
+    const startForm = tree.phases.find((p) => Number(p['index']) === 0);
+    if (!startForm) {
+        findings.push({
+            severity: 'error',
+            entity: 'phases',
+            message: 'no phase at index 0 — the start form is a real phase and must exist',
+            fix: 'restore the phase file whose index is 0, or re-pull',
+        });
+    }
+    const seenPhaseIndex = new Map();
+    const seenUuid = new Map();
+    const seenFieldId = new Map();
+    const seenFieldLabel = new Map();
+    const checkUuid = (row, entity, file, required) => {
+        const uuid = row['uuid'];
+        if (uuid === undefined || uuid === null || uuid === '') {
+            if (required && isNewEntity(row)) {
+                findings.push({
+                    severity: 'error',
+                    file,
+                    entity,
+                    message: `new ${entity} "${String(row['name'] ?? row['label'] ?? '?')}" has no uuid`,
+                    fix: `add a fresh v4 uuid — ${entity} is one of the four entity types identified by uuid`,
+                });
+            }
+            return;
+        }
+        if (typeof uuid !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid)) {
+            findings.push({ severity: 'error', file, entity, message: `uuid "${String(uuid)}" is not a v4 uuid` });
+            return;
+        }
+        const prior = seenUuid.get(uuid);
+        if (prior) {
+            findings.push({
+                severity: 'error',
+                file,
+                entity,
+                message: `uuid ${uuid} is used twice (also in ${prior})`,
+                fix: 'two entities can never share a uuid — generate a new one',
+            });
+        }
+        else {
+            seenUuid.set(uuid, file);
+        }
+    };
+    for (const phase of tree.phases) {
+        const file = `phases/… ${String(phase['name'] ?? '')}`;
+        requireString(phase, 'name', 'phases', file, findings);
+        checkUuid(phase, 'phases', file, true);
+        const index = Number(phase['index']);
+        if (!Number.isFinite(index)) {
+            findings.push({ severity: 'error', file, entity: 'phases', message: 'index must be a number' });
+        }
+        else {
+            const prior = seenPhaseIndex.get(index);
+            if (prior) {
+                findings.push({
+                    severity: 'error',
+                    file,
+                    entity: 'phases',
+                    message: `index ${index} is used by two phases (also "${prior}")`,
+                    fix: 'phase indexes must be unique — note that reordering phases is not applicable at all',
+                });
+            }
+            seenPhaseIndex.set(index, String(phase['name'] ?? ''));
+        }
+        if (!Array.isArray(phase.fields)) {
+            findings.push({ severity: 'error', file, entity: 'phases', message: 'fields must be an array' });
+            continue;
+        }
+        for (const f of phase.fields) {
+            const ffile = `${file} / ${String(f['label'] ?? '')}`;
+            requireString(f, 'label', 'fields', ffile, findings);
+            checkUuid(f, 'fields', ffile, true);
+            const type = String(f['type_id'] ?? '');
+            if (!type) {
+                findings.push({ severity: 'error', file: ffile, entity: 'fields', message: 'type_id is required' });
+            }
+            else if (!FIELD_TYPES.has(type)) {
+                findings.push({
+                    severity: 'warning',
+                    file: ffile,
+                    entity: 'fields',
+                    message: `type_id "${type}" is not one this build has seen`,
+                    fix: 'run pipe pull to read the accepted list from the API — see REFERENCE.md',
+                });
+            }
+            if (type === 'connector' && !f['connected_pipe_id']) {
+                findings.push({
+                    severity: 'error',
+                    file: ffile,
+                    entity: 'fields',
+                    message: 'a connector field must name the repo it connects to in connected_pipe_id',
+                });
+            }
+            if ((type === 'select' || type === 'radio_vertical' || type === 'radio_horizontal') && !Array.isArray(f['options'])) {
+                findings.push({ severity: 'error', file: ffile, entity: 'fields', message: `a ${type} field needs an options array` });
+            }
+            const id = f['id'];
+            if (id !== null && id !== undefined) {
+                const prior = seenFieldId.get(String(id));
+                if (prior) {
+                    findings.push({
+                        severity: 'error',
+                        file: ffile,
+                        entity: 'fields',
+                        message: `field id ${String(id)} appears twice (also in ${prior})`,
+                    });
+                }
+                seenFieldId.set(String(id), ffile);
+            }
+            /**
+             * A duplicate label is not refused on create — `createPhaseField` happily
+             * minted two fields both labelled "Classification" (one in another phase,
+             * one in the same phase) and just disambiguated the slug underneath,
+             * confirmed live against pipe 307321096. It bites later instead:
+             * `UpdatePhaseFieldInput.label` is non-null, so *every* `updatePhaseField`
+             * call resends the field's current label whether or not it changed, and
+             * that is where a pipe-wide duplicate surfaces as "Field label has already
+             * been taken" — the exact error this rule exists to catch before an apply
+             * reaches that step. Scoped to the whole repo, not the phase, matching the
+             * already-measured table rule (a table field label is unique per table).
+             */
+            const fieldLabel = String(f['label'] ?? '').trim();
+            if (fieldLabel) {
+                const priorLabel = seenFieldLabel.get(fieldLabel);
+                if (priorLabel) {
+                    findings.push({
+                        severity: 'error',
+                        file: ffile,
+                        entity: 'fields',
+                        message: `label "${fieldLabel}" is also used by another field in this pipe (${priorLabel})`,
+                        fix: 'updatePhaseField resends the current label on every call and the API rejects a repeat with "Field label has already been taken" — rename one of the two before either is updated for any reason',
+                    });
+                }
+                else {
+                    seenFieldLabel.set(fieldLabel, ffile);
+                }
+            }
+        }
+        if (!Array.isArray(phase.jump_target_ids)) {
+            findings.push({ severity: 'error', file, entity: 'phase_jumps', message: 'jump_target_ids must be an array of phase ids' });
+        }
+    }
+    for (const a of tree.automations) {
+        const file = `automations/${String(a['name'] ?? '')}`;
+        requireString(a, 'name', 'automations', file, findings);
+        requireString(a, 'event_id', 'automations', file, findings);
+        requireString(a, 'action_id', 'automations', file, findings);
+        checkUuid(a, 'automations', file, true);
+        if (a['_incomplete']) {
+            findings.push({
+                severity: 'warning',
+                file,
+                entity: 'automations',
+                message: 'this automation was read without its action_params — the internal API did not return its full definition',
+                fix: 'do not edit it; re-pull once the internal endpoint answers, or it will be recreated with an empty configuration',
+            });
+        }
+    }
+    for (const fc of tree.field_conditions) {
+        const file = `field-conditions/${String(fc['name'] ?? '')}`;
+        requireString(fc, 'name', 'field_conditions', file, findings);
+        if (!fc['phase_id']) {
+            findings.push({
+                severity: 'error',
+                file,
+                entity: 'field_conditions',
+                message: 'phase_id is required',
+                fix: 'for a phase being created in the same edit, use the placeholder "%{_new:<phase uuid>}"',
+            });
+        }
+        if (!Array.isArray(fc.actions) || fc.actions.length === 0) {
+            findings.push({ severity: 'error', file, entity: 'field_conditions', message: 'a field condition with no actions does nothing' });
+        }
+        /**
+         * A condition must not test the field it shows or hides.
+         *
+         * "Hide this field while it is empty" reads sensibly and is a trap: the
+         * field's visibility depends on its own value, so nobody can ever fill it,
+         * and the phase form failed to open until the condition was deleted.
+         *
+         * The API is no help here. Measured on a live pipe: it stores a
+         * self-referential condition, an `is_empty` operation and even
+         * `not_a_real_operation` without complaint, so nothing surfaces until the
+         * form is opened by a person. Every field condition read from real pipes
+         * points its expressions at one field and its actions at another.
+         *
+         * Reported as an error rather than a warning because the damage is to a form
+         * humans use, and the fix — test a different field, or drop the expression
+         * for an unconditional hide — is always available.
+         */
+        const targets = new Set((Array.isArray(fc.actions) ? fc.actions : [])
+            .map((a) => String(a['field_id'] ?? ''))
+            .filter(Boolean));
+        const cond = fc['condition'];
+        for (const e of (cond?.['expressions'] ?? [])) {
+            /**
+             * `field_address` is not always a field: real conditions address
+             * `assignees` and `created_by` too. Only a numeric id can collide with an
+             * action target, and a placeholder is compared as written because a field
+             * created in this edit is referenced the same way on both sides.
+             */
+            const addr = String(e['field_address'] ?? e['field_id'] ?? '');
+            if (!addr || !targets.has(addr))
+                continue;
+            findings.push({
+                severity: 'error',
+                file,
+                entity: 'field_conditions',
+                message: `the condition tests field ${addr}, which is also the field it shows or hides`,
+                fix: 'test a different field, or remove the expression so the action applies unconditionally',
+            });
+        }
+    }
+    for (const l of tree.labels)
+        checkUuid(l, 'labels', 'labels.json', true);
+    for (const w of tree.webhooks) {
+        requireString(w, 'url', 'webhooks', 'webhooks.json', findings);
+        if (typeof w['url'] === 'string' && !/^https?:\/\//.test(w['url'])) {
+            findings.push({ severity: 'error', file: 'webhooks.json', entity: 'webhooks', message: `url "${w['url']}" is not http(s)` });
+        }
+    }
+    return findings;
+};

package/dist/version.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The tool's identity as recorded in workspace.json and every run.json.
+ *
+ * The version is read from package.json, the same file `pipe --version` reads,
+ * because it used to be a literal `'0.1.0'` in three places that a release did
+ * not touch — so 0.1.1 stamped 0.1.0 on everything it wrote, and the one field
+ * meant to say which build produced a workspace said the wrong one.
+ *
+ * `dist/` mirrors `src/` one-for-one, so `../package.json` from here is the
+ * package root from either tree.
+ */
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+export const PACKAGE_NAME = pkg.name;
+export const TOOL_VERSION = pkg.version;
+export const TOOL = { name: 'pipefy-process-coder', version: TOOL_VERSION };

package/dist/workspace/agents.js

@@ -0,0 +1,245 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { mkdirp, exists, writeJson, readJson } from "../util/fsx.js";
+import { agentBaselineFile } from "./layout.js";
+import { slug } from "../util/slug.js";
+import { unfoldCondition } from "../codec/pack.js";
+/**
+ * The `agents/` half of a workspace.
+ *
+ * AI agents are entities of the pipe but not of the snapshot payload (ROUTE-B-V2.md
+ * ask 5), so — same as `flows/` — they are read by a different query and kept
+ * beside `pipes/<id>--<name>/`, not folded into the payload tree:
+ *
+ *   pipes/<id>--<name>/agents/
+ *     _meta.json                    coverage, readAt, count
+ *     <uuid>--<slug>/
+ *       agent.json                  name, instruction, disabledAt, needReview, dataSourceIds
+ *       behaviors/<slug>.json       the agent's behaviors — each one an ordinary
+ *                                   automation (action_id: "ai_behavior"), the
+ *                                   same shape a file in automations/ has
+ *
+ * A behavior is not stored twice and not cross-referenced by id either: which
+ * agent it belongs to is not a column on the automation (the API only answers
+ * that question from the agent's side, `AiAgent.behaviors`), so *location on
+ * disk is the only record of the link*. `workspace/read.ts` tags each behavior
+ * it finds here with `_agent_dir` (which agent's folder it came from) when it
+ * folds them into `tree.automations`, and `workspace/write.ts` reads that tag
+ * back off to route the file to the same place — the same "folding is movement
+ * only" rule phases and fields already follow, just carried by a tag instead of
+ * a `phase_id` column, because automations do not have one to spare.
+ *
+ * A behavior's *content* comes only from `pipefy/agents.ts` — the snapshot
+ * payload's copy of the same automation is a stub (`behavior_uuid` plus two
+ * field-id lists, no `instruction`, no `actionsAttributes`), so a fresh pull
+ * discards it and uses this query's answer instead (`foldFreshBehaviors`,
+ * below), rather than merely tagging it in place the way `tagBehaviors` does
+ * for a tree that already has the real content — a live read-back after an
+ * apply, or an already-pulled workspace's own files.
+ *
+ * Writing a behavior is a single `createAiAgent` / `updateAiAgent` call, not
+ * `createAutomation` — confirmed against real Pipefy web UI traffic and
+ * reproduced directly. Both take the **entire** agent, including every
+ * existing behavior unchanged (by `id`) alongside whatever is new — omitting
+ * one deletes it. Not yet built in `pipe apply`.
+ */
+export const AGENTS_DIR = 'agents';
+/** The tag `workspace/read.ts` puts on a behavior automation, and `workspace/write.ts` reads back. */
+export const AGENT_DIR_TAG = '_agent_dir';
+export const agentsRoot = (repoDir) => join(repoDir, AGENTS_DIR);
+export const agentDirName = (agent) => `${agent.uuid}--${slug(agent.name)}`;
+/** The empty section, for a pipe whose agents could not be read. */
+export const unknownAgents = (reason) => ({
+    meta: { coverage: 'unknown', readAt: new Date().toISOString(), reason, notes: [reason] },
+    agents: [],
+});
+/** id -> the directory of the agent it is a behavior of. */
+export const behaviorDirMapFrom = (agents) => {
+    const dirById = new Map();
+    for (const agent of agents) {
+        const dir = agentDirName(agent);
+        for (const b of agent.behaviors)
+            dirById.set(String(b['id']), dir);
+    }
+    return dirById;
+};
+/**
+ * A fresh pull's `tree.automations` holds the *stub* the snapshot payload
+ * gives a behavior — `behavior_uuid` plus a couple of field-id lists, no
+ * `instruction`, no `actionsAttributes`. `pipefy/agents.ts` reads the real
+ * content of the same rows over a different query, so those stubs are
+ * dropped here and replaced with it — not merely tagged, the way an already-
+ * pulled workspace's behaviors are (see `tagBehaviors`) — because the stub
+ * has nothing worth keeping.
+ */
+export const foldFreshBehaviors = (automations, agents) => {
+    const dirById = behaviorDirMapFrom(agents);
+    if (!dirById.size)
+        return automations;
+    const withoutStubs = automations.filter((a) => !dirById.has(String(a['id'])));
+    const behaviors = agents.flatMap((agent) => {
+        const dir = agentDirName(agent);
+        return agent.behaviors.map((b) => ({ ...b, [AGENT_DIR_TAG]: dir }));
+    });
+    return [...withoutStubs, ...behaviors];
+};
+/**
+ * The same replacement, done on the raw envelope instead of a `Tree` — for the
+ * *baseline* a fresh pull records, which is a payload envelope, not a tree.
+ *
+ * Skipping this leaves the baseline holding the snapshot's stub forever: the
+ * workspace files get the rich content (`foldFreshBehaviors`, above), the
+ * baseline does not, and `pipe diff` reports a phantom change on every single
+ * behavior on every single pull, forever, since the two can never agree.
+ *
+ * Reuses `codec/pack.ts`'s own unfolding — the exact inverse of what
+ * `codec/unpack.ts` does to build `condition` back up from `relations.conditions`
+ * / `relations.condition_expressions` — so a condition this replaces is found
+ * correctly on the next read, not silently dropped for want of a `condition_id`
+ * nothing points at.
+ */
+export const foldBehaviorsIntoEnvelope = (env, agents) => {
+    const behaviorIds = new Set(agents.flatMap((a) => a.behaviors.map((b) => String(b['id']))));
+    if (!behaviorIds.size)
+        return env;
+    const relations = env.payload['relations'];
+    const isRemovedAutomation = (id) => behaviorIds.has(String(id));
+    const automations = (relations['automations'] ?? []).filter((a) => !isRemovedAutomation(a['id']));
+    const removedConditionIds = new Set((relations['conditions'] ?? [])
+        .filter((c) => c['source_type'] === 'Automation' && isRemovedAutomation(c['source_id']))
+        .map((c) => String(c['id'])));
+    const conditions = (relations['conditions'] ?? []).filter((c) => !(c['source_type'] === 'Automation' && isRemovedAutomation(c['source_id'])));
+    const conditionExpressions = (relations['condition_expressions'] ?? []).filter((e) => !removedConditionIds.has(String(e['condition_id'])));
+    const fieldMaps = (relations['field_maps'] ?? []).filter((m) => !(m['owner_type'] === 'Automation' && isRemovedAutomation(m['owner_id'])));
+    for (const agent of agents) {
+        for (const raw of agent.behaviors) {
+            const { condition, field_maps: behaviorFieldMaps, ...autoRow } = raw;
+            const id = Number(autoRow['id']);
+            automations.push({ ...autoRow, id });
+            if (condition)
+                unfoldCondition(condition, 'Automation', id, conditions, conditionExpressions);
+            for (const m of behaviorFieldMaps ?? [])
+                fieldMaps.push({ ...m, owner_type: 'Automation', owner_id: id });
+        }
+    }
+    return {
+        ...env,
+        payload: {
+            ...env.payload,
+            relations: {
+                ...relations,
+                automations,
+                conditions,
+                condition_expressions: conditionExpressions,
+                field_maps: fieldMaps,
+            },
+        },
+    };
+};
+/**
+ * The same map, rebuilt by reading whichever agent directories already exist
+ * on disk, rather than from a fresh fetch.
+ *
+ * Needed wherever a tree gets read back from the *live* pipe rather than from
+ * this workspace — `pipe apply`'s and `pipe verify --update`'s "adopt what the
+ * server has" step, both of which `unpack()` a fresh envelope with no agent
+ * folders in sight to derive `_agent_dir` from. Without this, adopting a
+ * verified apply would write every behavior straight into `automations/`,
+ * undoing the split on every single successful apply.
+ */
+export const behaviorDirMapOnDisk = async (workspace) => {
+    const root = agentsRoot(workspace);
+    const dirById = new Map();
+    if (!(await exists(root)))
+        return dirById;
+    for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const behaviorsDir = join(root, entry.name, 'behaviors');
+        if (!(await exists(behaviorsDir)))
+            continue;
+        for (const file of await fs.readdir(behaviorsDir)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const row = await readJson(join(behaviorsDir, file));
+            if (row['id'] !== undefined && row['id'] !== null)
+                dirById.set(String(row['id']), entry.name);
+        }
+    }
+    return dirById;
+};
+/**
+ * Tag each automation that is some agent's behavior with the directory it
+ * belongs under, by id. `workspace/write.ts` reads the tag back off to route
+ * the file; `workspace/read.ts` sets the same tag itself, from wherever it
+ * actually found the file, so this is only needed for a tree that did not come
+ * from `readTree` — a fresh pull, or a live read-back adopted after an apply.
+ */
+export const tagBehaviors = (automations, dirById) => {
+    if (!dirById.size)
+        return automations;
+    return automations.map((a) => {
+        const dir = dirById.get(String(a['id']));
+        return dir ? { ...a, [AGENT_DIR_TAG]: dir } : a;
+    });
+};
+// ── write ───────────────────────────────────────────────────────────────────
+export const writeAgents = async (workspace, section) => {
+    const root = agentsRoot(workspace);
+    /**
+     * Rewritten wholesale, same reasoning as `flows/`: an agent deleted upstream
+     * must disappear from the workspace too. Behaviors are not touched here —
+     * `writeTree` owns `behaviors/`, and runs after this, so an agent's folder
+     * exists (even empty) by the time it needs somewhere to put them.
+     */
+    if (await exists(root))
+        await fs.rm(root, { recursive: true, force: true });
+    await mkdirp(root);
+    const written = [];
+    const put = async (path, value) => {
+        await writeJson(path, value);
+        written.push(path);
+    };
+    await put(join(root, '_meta.json'), section.meta);
+    for (const agent of section.agents) {
+        const dir = join(root, agentDirName(agent));
+        await mkdirp(join(dir, 'behaviors'));
+        const { behaviors: _behaviors, ...persisted } = agent;
+        await put(join(dir, 'agent.json'), persisted);
+    }
+    return written;
+};
+// ── read ────────────────────────────────────────────────────────────────────
+export const readAgents = async (workspace) => {
+    const root = agentsRoot(workspace);
+    if (!(await exists(root)))
+        return null;
+    const meta = (await readJson(join(root, '_meta.json')).catch(() => null)) ?? {
+        coverage: 'unknown',
+        readAt: new Date().toISOString(),
+        notes: ['agents/_meta.json is missing, so coverage is unknown'],
+    };
+    const agents = [];
+    for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const agentJson = join(root, entry.name, 'agent.json');
+        if (!(await exists(agentJson)))
+            continue;
+        const persisted = await readJson(agentJson);
+        agents.push({ ...persisted, behaviors: [] });
+    }
+    return { meta, agents };
+};
+/** Record what was just read as the baseline, so the next diff needs no network. */
+export const writeAgentBaseline = (workspaceRoot, repoId, section) => writeJson(agentBaselineFile(workspaceRoot, repoId), section);
+/** The recorded agent baseline, or null when this repo has never been pulled. */
+export const readAgentBaseline = async (workspaceRoot, repoId) => {
+    try {
+        return await readJson(agentBaselineFile(workspaceRoot, repoId));
+    }
+    catch {
+        return null;
+    }
+};
+export const isNewAgent = (agent) => !agent['uuid'] || agent['_new'] === true;