@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/apply/execute.js

@@ -0,0 +1,277 @@
+import { writeJson } from "../util/fsx.js";
+import { debug, dim, green, red, yellow } from "../util/log.js";
+import { Progress } from "../util/tui.js";
+import { IdMap } from "./idmap.js";
+const pluck = (obj, path) => {
+    let cur = obj;
+    for (const key of path) {
+        if (cur && typeof cur === 'object' && key in cur) {
+            cur = cur[key];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+};
+export const execute = async (plan, opts) => {
+    const idMap = new IdMap(plan.idMap);
+    plan.status = 'running';
+    /**
+     * The step list, live. A plan is a queue of network calls whose count and
+     * order the user has already seen in `pipe plan`, so showing that same list
+     * fill in is the honest progress indicator — and in a dry run it shows exactly
+     * what would be sent, in order, without sending it.
+     */
+    const ui = new Progress({
+        title: opts.dryRun ? `dry run · ${plan.steps.length} steps` : `applying ${plan.steps.length} steps`,
+    });
+    for (const s of plan.steps) {
+        ui.add({
+            id: s.id,
+            label: s.description,
+            state: s.status === 'done' ? 'done' : 'pending',
+            tags: [
+                ...(s.destructive ? ['destructive'] : []),
+                ...(s.unverified ? ['unverified'] : []),
+                ...(s.kind.startsWith('internal') ? ['internal-api'] : []),
+            ],
+        });
+    }
+    ui.start();
+    const persist = async () => {
+        if (!opts.dryRun)
+            await writeJson(opts.planPath, plan);
+    };
+    for (const s of plan.steps) {
+        if (s.status === 'done') {
+            // Resume: a completed create still has to re-register its placeholder so
+            // later steps can resolve against it.
+            if (s.produces && s.result !== undefined) {
+                const id = Number(pluck(s.result, s.produces.path));
+                if (Number.isFinite(id))
+                    idMap.resolvePlaceholder(s.produces.placeholder, id, s.produces.aliases ?? []);
+            }
+            continue;
+        }
+        const unresolved = idMap.unresolved(s.request.variables ?? s.request.form ?? s.request.path ?? null);
+        if (unresolved.length) {
+            s.status = 'skipped';
+            s.error = `depends on ids that were never created: ${unresolved.join(', ')}`;
+            ui.update(s.id, { state: 'skipped', detail: s.error });
+            await persist();
+            continue;
+        }
+        const request = {
+            ...s.request,
+            variables: s.request.variables ? idMap.rewrite(s.request.variables) : undefined,
+            form: s.request.form ? idMap.rewrite(s.request.form) : undefined,
+            path: s.request.path ? idMap.rewrite({ p: s.request.path }).p : undefined,
+        };
+        /**
+         * Nothing leaves here still carrying a placeholder.
+         *
+         * A *registered* placeholder passes the unresolved check above, but is only
+         * substituted if its key is known to hold an id — so a new id-bearing key
+         * that nobody added to ID_BEARING_KEYS sends the marker to the API verbatim.
+         * That happened with `fieldConditionIds`, and the resulting error named the
+         * field but said nothing about the cause. This refuses to send, and says
+         * which key.
+         */
+        const leftovers = [];
+        const findMarkers = (v, path) => {
+            if (typeof v === 'string') {
+                if (v.includes('_new:'))
+                    leftovers.push(`${path} = ${v}`);
+                return;
+            }
+            if (Array.isArray(v)) {
+                v.forEach((x, i) => findMarkers(x, `${path}[${i}]`));
+                return;
+            }
+            if (v && typeof v === 'object') {
+                for (const [k, val] of Object.entries(v)) {
+                    findMarkers(val, path ? `${path}.${k}` : k);
+                }
+            }
+        };
+        findMarkers(request.variables ?? null, '');
+        findMarkers(request.form ?? null, '');
+        if (leftovers.length) {
+            s.status = 'failed';
+            s.error =
+                `unsubstituted placeholder at ${leftovers.join(', ')} — that key is not in ID_BEARING_KEYS, ` +
+                    'so nothing replaced it. Not sent.';
+            s.finishedAt = new Date().toISOString();
+            ui.update(s.id, { state: 'failed', detail: s.error });
+            await persist();
+            if (!opts.continueOnError)
+                break;
+            continue;
+        }
+        if (opts.dryRun) {
+            s.status = 'skipped';
+            /**
+             * A dry run marks each step done in the display rather than skipped: the
+             * step is complete as far as this run goes, and painting a whole plan
+             * yellow suggests something went wrong when nothing did. The title says
+             * "dry run", and nothing was sent.
+             */
+            ui.update(s.id, { state: 'done', detail: 'not sent' });
+            debug(JSON.stringify(request.variables ?? request.form ?? {}).slice(0, 400));
+            opts.onProgress?.(s, plan);
+            continue;
+        }
+        s.status = 'running';
+        s.startedAt = new Date().toISOString();
+        await persist();
+        ui.update(s.id, { state: 'running' });
+        try {
+            let result;
+            if (s.kind === 'graphql') {
+                try {
+                    result = await opts.client.raw(request.query, request.variables, s.request.mutation);
+                }
+                catch (e) {
+                    /**
+                     * `phaseSettings` is known to answer "Something went wrong" for a change
+                     * it has just made — observed twice, on two different runs, with the
+                     * `phase_team_memberships` row present in the read-back both times and
+                     * timestamped to the failing call. Its failures are therefore
+                     * inconclusive, not negative, and saying so is the difference between
+                     * an operator re-running a harmless write and an operator hunting a
+                     * change that already exists.
+                     */
+                    if (s.request.mutation === 'phaseSettings') {
+                        throw new Error(`${e.message} — note that phaseSettings has been observed reporting this ` +
+                            'for a change it did apply. Re-read the phase before assuming nothing happened.');
+                    }
+                    throw e;
+                }
+            }
+            else if (s.kind === 'internal-graphql') {
+                result = await runInternalAutomationStep(opts.internal, s, request.variables ?? {});
+            }
+            else if (s.kind === 'internal-rest') {
+                result = await runInternalRestStep(opts.internal, s, request);
+            }
+            else {
+                result = { noop: true };
+            }
+            s.result = result;
+            s.status = 'done';
+            s.finishedAt = new Date().toISOString();
+            ui.update(s.id, { state: 'done' });
+            if (s.produces) {
+                const raw = pluck(result, s.produces.path);
+                const id = Number(raw);
+                if (Number.isFinite(id)) {
+                    idMap.resolvePlaceholder(s.produces.placeholder, id, s.produces.aliases ?? []);
+                }
+                else {
+                    ui.note(yellow('! ') + `${s.id} succeeded but produced no id at ${s.produces.path.join('.')} — later steps may skip`);
+                }
+            }
+            opts.onProgress?.(s, plan);
+        }
+        catch (e) {
+            s.status = 'failed';
+            s.error = e.message;
+            s.finishedAt = new Date().toISOString();
+            ui.update(s.id, { state: 'failed', detail: s.error });
+            await persist();
+            opts.onProgress?.(s, plan);
+            if (!opts.continueOnError)
+                break;
+        }
+        await persist();
+    }
+    const counts = plan.steps.reduce((acc, s) => {
+        acc[s.status] = (acc[s.status] ?? 0) + 1;
+        return acc;
+    }, {});
+    plan.status =
+        (counts['failed'] ?? 0) > 0
+            ? (counts['done'] ?? 0) > 0
+                ? 'partially-applied'
+                : 'failed'
+            : opts.dryRun
+                ? 'planned'
+                : 'applied';
+    await persist();
+    const done = counts['done'] ?? 0;
+    const failed = counts['failed'] ?? 0;
+    const skipped = counts['skipped'] ?? 0;
+    /**
+     * A dry run's steps are recorded as skipped, which is right for the plan file
+     * and wrong as a headline: "0 done, 2 skipped" reads like something went
+     * wrong. Nothing did — nothing was sent.
+     */
+    ui.stop(opts.dryRun
+        ? '  ' + green(`${plan.steps.length} step${plan.steps.length === 1 ? '' : 's'} simulated`) + dim(', nothing sent')
+        : '  ' +
+            [
+                done ? green(`${done} done`) : dim('0 done'),
+                failed ? red(`${failed} failed`) : dim('0 failed'),
+                skipped ? yellow(`${skipped} skipped`) : dim('0 skipped'),
+            ].join(dim(' · ')) +
+            dim(` · ${(ui.elapsed / 1000).toFixed(1)}s`));
+    return {
+        plan,
+        done: counts['done'] ?? 0,
+        failed: counts['failed'] ?? 0,
+        skipped: counts['skipped'] ?? 0,
+        pending: counts['pending'] ?? 0,
+        idMap,
+    };
+};
+const runInternalAutomationStep = async (internal, s, variables) => {
+    if (s.request.mutation === 'createAutomation') {
+        const created = await internal.createAutomation(variables);
+        if (!created)
+            throw new Error('createAutomation returned no automation (internal API unavailable or rejected)');
+        return { createAutomation: { automation: created } };
+    }
+    if (s.request.mutation === 'deleteAutomation') {
+        const success = await internal.deleteAutomation(String(variables['id']));
+        if (!success)
+            throw new Error(`deleteAutomation(${String(variables['id'])}) did not report success`);
+        return { deleteAutomation: { success } };
+    }
+    if (s.request.mutation === 'updateAutomation') {
+        const res = await internal.gql(`mutation updateAutomation($input: UpdateAutomationInput!) {
+        updateAutomation(input: $input) { automation { id } error_details { object_key messages } }
+      }`, { input: variables }, 'updateAutomation');
+        if (!res)
+            throw new Error('updateAutomation failed on the internal endpoint');
+        return res;
+    }
+    throw new Error(`unknown internal mutation ${s.request.mutation}`);
+};
+const runInternalRestStep = async (internal, s, request) => {
+    const phaseId = /\/phases\/([^/?]+)/.exec(request.path ?? '')?.[1];
+    if (!phaseId)
+        throw new Error(`could not read a phase id out of ${request.path}`);
+    const targets = (request.form?.['phase[jump_target_ids][]'] ?? []).filter((t) => t !== '');
+    /**
+     * A jump target is an id and nothing else.
+     *
+     * The endpoint answers a malformed target with a bare 404, which reads as
+     * "that phase does not exist" and sends you looking in the wrong place. Every
+     * such 404 so far has been a substitution that did not happen — a placeholder
+     * rewritten to `%{344123894}` rather than to `344123894`. Checking the shape
+     * here names the real cause.
+     */
+    const malformed = targets.filter((t) => !/^[0-9]+$/.test(t));
+    if (malformed.length) {
+        throw new Error(`jump target(s) ${malformed.join(', ')} are not ids — an id substitution did not happen. Not sent.`);
+    }
+    const res = await internal.setPhaseJumpTargets(phaseId, targets);
+    /**
+     * Assert on the echoed next_phase_ids, not on the HTTP status — PLAN.md §2.1.
+     * A 200 from an unversioned endpoint is not evidence that anything changed.
+     */
+    if (!res.ok)
+        throw new Error(res.error ?? 'phase jump write could not be confirmed from the response');
+    return res;
+};

package/dist/apply/flowops.js

@@ -0,0 +1,293 @@
+import { linkFlow } from "../codec/flow.js";
+/** The node as an operation request: the whole node, minus link and volatile keys. */
+const nodeRequest = (node) => {
+    const { _nextAction, _firstLoopAction, _children, ...rest } = node;
+    const out = {
+        name: rest['name'],
+        type: rest['type'],
+        valid: rest['valid'] ?? true,
+        settings: rest['settings'] ?? {},
+    };
+    if (rest['displayName'] !== undefined)
+        out['displayName'] = rest['displayName'];
+    if (rest['skip'] !== undefined)
+        out['skip'] = rest['skip'];
+    return out;
+};
+/**
+ * Where a new node hangs. `ADD_ACTION` takes the parent it follows, plus a
+ * location for the cases where "after" is ambiguous.
+ *
+ * A bare `{ parentStep }` with no location is only unambiguous when the
+ * parent is a plain step. When the parent is itself a `LOOP_ON_ITEMS`,
+ * "after it" could mean *inside* the loop or *exiting* it, and the endpoint
+ * refuses to guess: measured live (`research/ipaas/probe-loop-shape-3.ts`),
+ * the identical omitted-location request answers `Loop step parent undefined
+ * not found`, and adding `stepLocationRelativeToParent: 'AFTER'` is what
+ * makes the same add succeed. Every flow this tool wrote before had no loop
+ * at all, so this was never exercised.
+ */
+const parentOf = (tree, nodeName) => {
+    for (const candidate of tree.nodes) {
+        if (candidate['_nextAction'] === nodeName) {
+            return { parentStep: candidate.name, ...(candidate['type'] === 'LOOP_ON_ITEMS' ? { location: 'AFTER' } : {}) };
+        }
+        if (candidate['_firstLoopAction'] === nodeName) {
+            return { parentStep: candidate.name, location: 'INSIDE_LOOP' };
+        }
+        const children = candidate['_children'] ?? [];
+        const at = children.indexOf(nodeName);
+        if (at >= 0)
+            return { parentStep: candidate.name, location: 'INSIDE_BRANCH', branchIndex: at };
+    }
+    return null;
+};
+/** Every `{{connections['x']}}` a flow references, with the piece that needs it. */
+export const connectionsUsedBy = (tree) => {
+    const out = new Map();
+    const CONN = /connections\['([^']+)'\]/g;
+    for (const node of tree.nodes) {
+        const settings = (node['settings'] ?? {});
+        const piece = String(settings['pieceName'] ?? '');
+        const text = JSON.stringify(settings['input'] ?? {});
+        for (const m of text.matchAll(CONN)) {
+            const id = m[1];
+            if (!out.has(id))
+                out.set(id, piece);
+        }
+    }
+    return [...out].map(([externalId, pieceName]) => ({ externalId, pieceName }));
+};
+export const compileFlows = (cs, opts = {}) => {
+    const steps = [];
+    const blocked = [];
+    const warnings = [];
+    const emit = (partial) => {
+        steps.push({ id: `f${String(steps.length + 1).padStart(3, '0')}`, index: steps.length, status: 'pending', ...partial });
+    };
+    /**
+     * Order matters and is not the diff's order.
+     *
+     * Creates before the changes that reference them; node deletes before node
+     * adds, so a rename that is really a delete-plus-add does not collide on a
+     * name; and status last, because arming a flow should be the final thing that
+     * happens to it, after its contents are what they should be.
+     */
+    const order = {
+        'flow.create': 0,
+        'flow.rename': 1,
+        'node.delete': 2,
+        'trigger.update': 3,
+        'node.create': 4,
+        'node.update': 5,
+        'flow.delete': 6,
+        'flow.status': 7,
+    };
+    const sorted = [...cs.changes].sort((a, b) => order[a.op] - order[b.op]);
+    /**
+     * Connections first: a flow cannot be created referencing one the project does
+     * not have. A missing connection used to be a refusal, which stalled the whole
+     * build for something the flow structure does not depend on.
+     */
+    if (opts.connections) {
+        const needed = new Map();
+        for (const c of cs.changes) {
+            const tree = (c.afterFlow ?? null);
+            if (!tree)
+                continue;
+            for (const use of connectionsUsedBy(tree)) {
+                if (opts.connections.has(use.externalId))
+                    continue;
+                if (!needed.has(use.externalId))
+                    needed.set(use.externalId, use.pieceName);
+            }
+        }
+        for (const [externalId, pieceName] of needed) {
+            emit({
+                changeKey: `connection:${externalId}`,
+                flowId: null,
+                createConnection: {
+                    pieceName,
+                    externalId,
+                    displayName: `${pieceName.split('/').pop()} (placeholder, reconnect me)`,
+                },
+                description: `create placeholder connection ${externalId} for ${pieceName}`,
+            });
+            warnings.push(`connection ${externalId} does not exist in this project and will be created with a ` +
+                'placeholder credential — reconnect it in the product before enabling any flow that uses it');
+        }
+    }
+    for (const c of sorted) {
+        switch (c.op) {
+            case 'flow.create': {
+                const tree = c.afterFlow;
+                emit({
+                    changeKey: c.key,
+                    flowId: null,
+                    createFlow: { displayName: c.flowName, tree },
+                    description: `create flow "${c.flowName}" and add its ${tree.nodes.length} nodes`,
+                });
+                break;
+            }
+            case 'flow.delete': {
+                emit({
+                    changeKey: c.key,
+                    flowId: c.flowId,
+                    deleteFlow: true,
+                    description: `delete flow "${c.flowName}"`,
+                    destructive: true,
+                });
+                break;
+            }
+            case 'flow.rename': {
+                emit({
+                    changeKey: c.key,
+                    flowId: c.flowId,
+                    operation: { type: 'CHANGE_NAME', request: { displayName: c.flowName } },
+                    description: `CHANGE_NAME — "${c.flowName}"`,
+                });
+                break;
+            }
+            case 'flow.status': {
+                const status = String(c.deltas[0]?.after ?? '');
+                if (status !== 'ENABLED' && status !== 'DISABLED') {
+                    blocked.push({ key: c.key, label: c.label, reason: `status ${JSON.stringify(status)} is not ENABLED or DISABLED` });
+                    break;
+                }
+                /**
+                 * Enabling a flow points it at live traffic. It is refused unless asked
+                 * for explicitly, the same way a phase delete needs --allow-card-moves:
+                 * the cost of a wrong one is paid by the client, not by the person running
+                 * the apply.
+                 */
+                const usesPlaceholder = [...(opts.connections ?? new Map())].some(([, c]) => c['status'] === 'PLACEHOLDER');
+                if (status === 'ENABLED' && usesPlaceholder) {
+                    blocked.push({
+                        key: c.key,
+                        label: c.label,
+                        reason: 'this project has a placeholder connection — reconnect it before enabling a flow, ' +
+                            'or the flow will run and fail on every trigger',
+                    });
+                    break;
+                }
+                if (status === 'ENABLED' && !opts.allowArm) {
+                    blocked.push({
+                        key: c.key,
+                        label: c.label,
+                        reason: 'enabling a flow arms it against live traffic — re-run with --allow-flow-enable to do it deliberately',
+                    });
+                    break;
+                }
+                emit({
+                    changeKey: c.key,
+                    flowId: c.flowId,
+                    operation: { type: 'CHANGE_STATUS', request: { status } },
+                    description: `CHANGE_STATUS — ${status}`,
+                    arms: status === 'ENABLED',
+                });
+                break;
+            }
+            case 'trigger.update': {
+                emit({
+                    changeKey: c.key,
+                    flowId: c.flowId,
+                    operation: { type: 'UPDATE_TRIGGER', request: nodeRequest(c.after) },
+                    description: `UPDATE_TRIGGER — flow "${c.flowName}"`,
+                });
+                break;
+            }
+            case 'node.update': {
+                emit({
+                    changeKey: c.key,
+                    flowId: c.flowId,
+                    operation: { type: 'UPDATE_ACTION', request: nodeRequest(c.after) },
+                    description: `UPDATE_ACTION — ${c.nodeName} in "${c.flowName}"`,
+                });
+                break;
+            }
+            case 'node.delete': {
+                emit({
+                    changeKey: c.key,
+                    flowId: c.flowId,
+                    // `names` is an array — a single `name` is rejected.
+                    operation: { type: 'DELETE_ACTION', request: { names: [c.nodeName] } },
+                    description: `DELETE_ACTION — ${c.nodeName} in "${c.flowName}"`,
+                    destructive: true,
+                });
+                break;
+            }
+            case 'node.create': {
+                const tree = c.afterFlow;
+                const where = tree ? parentOf(tree, c.nodeName) : null;
+                if (!where) {
+                    // Unreachable from the chain — nothing points `_nextAction` /
+                    // `_firstLoopAction` / a branch's `_children` at this node, so there is
+                    // no parent to hang it from. The same case `buildFlowOperations` skips
+                    // for a brand-new flow.
+                    blocked.push({
+                        key: c.key,
+                        label: c.label,
+                        reason: `${c.nodeName} is not reachable from the trigger — nothing in the authored flow ` +
+                            'points to it, so there is no parent to add it after.',
+                    });
+                    break;
+                }
+                emit({
+                    changeKey: c.key,
+                    flowId: c.flowId,
+                    operation: {
+                        type: 'ADD_ACTION',
+                        request: {
+                            parentStep: where.parentStep,
+                            ...(where.location ? { stepLocationRelativeToParent: where.location } : {}),
+                            ...(where.branchIndex !== undefined ? { branchIndex: where.branchIndex } : {}),
+                            action: nodeRequest(c.after),
+                        },
+                    },
+                    description: `ADD_ACTION — ${c.nodeName} [${c.after.type}] after ${where.parentStep}${where.location ? ` (${where.location})` : ''} in "${c.flowName}"`,
+                });
+                break;
+            }
+        }
+    }
+    if (blocked.length) {
+        warnings.push(`${blocked.length} flow change(s) have no write path yet`);
+    }
+    return { steps, blocked, warnings };
+};
+/**
+ * The operations that build a brand-new flow's contents.
+ *
+ * A created flow arrives with an `EMPTY` trigger and nothing else, so the tree is
+ * laid down trigger-first and then each node in execution order — every node's
+ * parent already exists by the time it is added, because execution order is a
+ * topological order of the chain.
+ */
+export const buildFlowOperations = (tree) => {
+    const ops = [];
+    const trigger = tree.nodes[0];
+    if (!trigger)
+        return ops;
+    ops.push({ type: 'UPDATE_TRIGGER', request: nodeRequest(trigger), describe: `trigger [${trigger.type}]` });
+    for (const node of tree.nodes.slice(1)) {
+        const where = parentOf(tree, node.name);
+        if (!where) {
+            // Unreachable from the chain: the codec would have dropped it anyway, and
+            // adding it with a guessed parent would put it somewhere nobody asked for.
+            continue;
+        }
+        ops.push({
+            type: 'ADD_ACTION',
+            request: {
+                parentStep: where.parentStep,
+                ...(where.location ? { stepLocationRelativeToParent: where.location } : {}),
+                ...(where.branchIndex !== undefined ? { branchIndex: where.branchIndex } : {}),
+                action: nodeRequest(node),
+            },
+            describe: `${node.name} [${node.type}] after ${where.parentStep}${where.location ? ` (${where.location})` : ''}`,
+        });
+    }
+    return ops;
+};
+/** The API flow row a tree would produce, for verification after an apply. */
+export const intendedFlow = (tree) => linkFlow(tree);