@pipefy/pipefy-process-coder 0.1.0 → 0.1.1

package/dist/apply/idmap.js

@@ -0,0 +1,233 @@
+import { debug } from "../util/log.js";
+/**
+ * Id substitution — the single subtlest thing in the write path.
+ *
+ * Two jobs, both learned from the Change Migrator recipes:
+ *
+ *  1. **Placeholders.** A new field has no id until it is created, so an
+ *     automation created in the same plan references `%{_new:<key>}` and the
+ *     executor swaps in the real id once the field exists. PLAN.md §9 flags
+ *     that this "fails only on the combination create field + reference it in
+ *     the same plan" — i.e. constantly.
+ *
+ *  2. **Cross-repo remapping.** Recipe step 120 rewrites every dev field id
+ *     inside an automation's JSON to its prod equivalent, looking each one up
+ *     through a Pipefy table with one API call per id. Same transformation
+ *     here, from the map the diff already built, with no API calls.
+ *
+ * Ids hide inside opaque JSON: `"%{<fieldId>}"`, `"field_address": "<fieldId>"`,
+ * `"trigger_field_ids": ["<fieldId>"]`. So substitution walks the whole
+ * structure. `%{...}` is rewritten anywhere it appears; a bare id is rewritten
+ * only under a key known to hold one, because rewriting every number that
+ * happens to match an id would corrupt values that merely look like ids.
+ */
+/** Keys whose values are ids, and may therefore be remapped when bare. */
+export const ID_BEARING_KEYS = new Set([
+    'field_address',
+    'field_id',
+    'fieldId',
+    'field_ids',
+    'fieldIds',
+    'phase_id',
+    'phaseId',
+    'phaseFieldId',
+    'to_phase_id',
+    'toPhaseId',
+    'from_phase_id',
+    'fromPhaseId',
+    'in_phase_id',
+    'inPhaseId',
+    'trigger_field_ids',
+    'triggerFieldIds',
+    'trigger_automation_id',
+    'triggerAutomationId',
+    'card_id',
+    'cardId',
+    'title_field_id',
+    'connected_pipe_id',
+    'connected_repo_id',
+    'submitter_email_field_id',
+    'email_template_id',
+    'source_id',
+    'owner_id',
+    'skills_ids',
+    'skillsIds',
+    'jump_target_ids',
+    'target_phase_id',
+    'source_phase_id',
+    // Id *lists* count too. Omitting fieldConditionIds meant a placeholder inside
+    // the array was never substituted and went to the API verbatim, which came
+    // back as "Invalid input: fieldConditionIds ([0])" — an error that says
+    // nothing about the real cause.
+    'fieldConditionIds',
+    'field_condition_ids',
+    /**
+     * The field ids an `update_card_field` automation writes, in order.
+     *
+     * Fourth omission from this list, and the most quietly damaging: nothing
+     * rejected it. `fields_map_order: ["%{433584976}"]` was stored by the API
+     * verbatim, braces and all. The automation was created, reported valid,
+     * verified clean, and selected **no fields to update** — because the UI and the
+     * engine read this list to know which fields the automation writes, and
+     * `"%{433584976}"` is not a field id. Every working automation in the org
+     * stores bare ids here.
+     *
+     * `field_map[].field_id` was substituted correctly the whole time, so the
+     * automation looked right in the workspace and did nothing on the pipe.
+     */
+    'fields_map_order',
+    'fieldsMapOrder',
+    /**
+     * The internal settings endpoint's form key, brackets and all.
+     *
+     * Substitution is keyed on the *key name*, and this one is
+     * `phase[jump_target_ids][]` — nothing like the camel or snake spellings above.
+     * Without it a target naming a phase created in the same plan was rewritten to
+     * `%{344123894}` instead of `344123894`, and the endpoint answered 404 with no
+     * hint about which value it disliked. Third time this list has been the cause;
+     * `runInternalRestStep` now asserts on the value shape as well, so a fourth
+     * omission fails loudly instead.
+     */
+    'phase[jump_target_ids][]',
+    'teamMemberIds',
+    'team_member_ids',
+    'phaseFieldIds',
+]);
+/**
+ * Captures the whole token including the `_new:` prefix, because that is the key
+ * placeholders are *stored* under (`placeholderFor` emits `_new:fields:<key>`).
+ * Capturing only the tail silently makes every lookup miss.
+ */
+const PLACEHOLDER_RE = /%\{(_new:[^}]+)\}/g;
+const REFERENCE_RE = /%\{(\d+)\}/g;
+export const placeholderFor = (entity, key) => `_new:${entity}:${key}`;
+export const placeholderToken = (p) => `%{${p}}`;
+export class IdMap {
+    /** placeholder → real id, filled in as creating steps succeed. */
+    placeholders = new Map();
+    /** old id → new id, for cross-repo migration. */
+    remap = new Map();
+    constructor(seed = {}) {
+        for (const [k, v] of Object.entries(seed))
+            this.remap.set(String(k), Number(v));
+    }
+    resolvePlaceholder(p, id, aliases = []) {
+        this.placeholders.set(p, id);
+        for (const a of aliases)
+            if (a)
+                this.placeholders.set(a, id);
+        debug(`resolved placeholder ${p}${aliases.length ? ` (+${aliases.length} alias)` : ''} -> ${id}`);
+    }
+    hasPlaceholder(p) {
+        return this.placeholders.has(p);
+    }
+    placeholderValue(p) {
+        return this.placeholders.get(p);
+    }
+    addRemap(oldId, newId) {
+        this.remap.set(String(oldId), newId);
+    }
+    lookup(id) {
+        return this.remap.get(String(id));
+    }
+    /** Which placeholders a value still depends on. Empty means it is ready to send. */
+    unresolved(value) {
+        const out = new Set();
+        const walk = (v) => {
+            if (typeof v === 'string') {
+                for (const m of v.matchAll(PLACEHOLDER_RE)) {
+                    const key = m[1];
+                    if (!this.placeholders.has(key))
+                        out.add(key);
+                }
+                // A bare placeholder, as compile.ts emits for phase_id on a new field.
+                if (v.startsWith('_new:') && !this.placeholders.has(v))
+                    out.add(v);
+                return;
+            }
+            if (Array.isArray(v)) {
+                v.forEach(walk);
+                return;
+            }
+            if (v && typeof v === 'object')
+                Object.values(v).forEach(walk);
+        };
+        walk(value);
+        return [...out];
+    }
+    rewriteString(s) {
+        let out = s.replace(PLACEHOLDER_RE, (whole, key) => {
+            const id = this.placeholders.get(key);
+            return id === undefined ? whole : `%{${id}}`;
+        });
+        out = out.replace(REFERENCE_RE, (whole, id) => {
+            const mapped = this.remap.get(id);
+            return mapped === undefined ? whole : `%{${mapped}}`;
+        });
+        return out;
+    }
+    /** A bare id value, remapped if it is under an id-bearing key. */
+    rewriteBare(v) {
+        if (typeof v === 'number') {
+            const mapped = this.remap.get(String(v));
+            return mapped ?? v;
+        }
+        if (typeof v === 'string') {
+            if (/^_new:/.test(v)) {
+                const id = this.placeholders.get(v);
+                return id === undefined ? v : String(id);
+            }
+            if (/^\d+$/.test(v)) {
+                const mapped = this.remap.get(v);
+                return mapped === undefined ? v : String(mapped);
+            }
+            /**
+             * A value under an id-bearing key that is *entirely* one reference is an
+             * id, not a template: `"phase_id": "%{_new:<uuid>}"` must become `"344…"`,
+             * not `"%{344…}"`. Only `createFieldCondition` and friends care, but they
+             * care absolutely — a braced id is rejected as a malformed ID.
+             */
+            const whole = /^%\{(_new:[^}]+|\d+)\}$/.exec(v);
+            if (whole) {
+                const key = whole[1];
+                const resolved = key.startsWith('_new:') ? this.placeholders.get(key) : this.remap.get(key);
+                if (resolved !== undefined)
+                    return String(resolved);
+                // A numeric reference with no remapping is already the id it names.
+                if (!key.startsWith('_new:'))
+                    return key;
+                return v;
+            }
+            return this.rewriteString(v);
+        }
+        if (Array.isArray(v))
+            return v.map((x) => this.rewriteBare(x));
+        return v;
+    }
+    /** Deep-rewrite a request payload. Returns a new value; the input is untouched. */
+    rewrite(value) {
+        const walk = (v, keyIsIdBearing) => {
+            if (typeof v === 'string')
+                return keyIsIdBearing ? this.rewriteBare(v) : this.rewriteString(v);
+            if (typeof v === 'number')
+                return keyIsIdBearing ? this.rewriteBare(v) : v;
+            if (Array.isArray(v))
+                return v.map((x) => walk(x, keyIsIdBearing));
+            if (v && typeof v === 'object') {
+                const out = {};
+                for (const [k, val] of Object.entries(v)) {
+                    out[k] = walk(val, ID_BEARING_KEYS.has(k));
+                }
+                return out;
+            }
+            return v;
+        };
+        return walk(value, false);
+    }
+    snapshot() {
+        return {
+            placeholders: Object.fromEntries(this.placeholders),
+            remap: Object.fromEntries(this.remap),
+        };
+    }
+}