@tenonhq/dovetail-servicenow 0.0.21 → 0.0.23

package/dist/table/addColumn.js

@@ -0,0 +1,384 @@
+"use strict";
+/**
+ * Add ONE column to an EXISTING ServiceNow table — headless, the faithful way.
+ * Creating a column is inserting a `sys_dictionary` record; a REST / Dovetail
+ * createRecord insert into sys_dictionary reliably 500s for a scoped-app column
+ * (scope-policy + the dictionary engine being wired to the form transaction, not
+ * the REST insert). The faithful path is the one the Studio UI drives: a single
+ * `POST /sys_db_object.do` against the EXISTING table record whose body embeds the
+ * new column as the same list-edit XML blob create-table uses.
+ *
+ * This REUSES the create-table machinery wholesale (buildColumnXml, formSession,
+ * the list-edit key + type normalization) and differs in exactly two ways:
+ *   1. It GETs the EXISTING table form (sys_id=<tableSysId>), which renders the
+ *      "Columns" related list — so the real listEditKey is harvested, not faked.
+ *   2. It overlays ONLY the column XML + the save machinery, preserving every
+ *      existing table field from the harvest (name/label/scope/ACLs untouched).
+ * Then it READS THE COLUMN BACK from sys_dictionary to prove it landed — a write
+ * that 302s but didn't create the field is reported as failed, never "created".
+ *
+ * Validated live 2026-06-19 on tenonworkstudio (a smoke-test scoped table): the
+ * form save creates the column (HTTP 200 re-render, not a 302), the before/after
+ * sys_dictionary diff confirms it, and a scoped insert into the new column
+ * round-trips — proving the physical column, not just the dictionary row. ES6
+ * only, no optional chaining, no `any`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveElement = deriveElement;
+exports.applyAddColumnOverlay = applyAddColumnOverlay;
+exports.addColumn = addColumn;
+const crypto = __importStar(require("crypto"));
+const buildColumnXml_1 = require("./buildColumnXml");
+const buildTableSave_1 = require("./buildTableSave");
+const formSession_1 = require("./formSession");
+const createTable_1 = require("./createTable");
+var SYS_ID = /^[0-9a-f]{32}$/i;
+/**
+ * Read a ServiceNow Table API field value. Reference fields (e.g. sys_scope) come
+ * back as a { link, value } object — the API includes the reference link unless
+ * excluded — so a bare String() would yield "[object Object]". Returns the
+ * sys_id/value for a reference object, the string otherwise.
+ */
+function fieldValue(v) {
+    if (v && typeof v === "object") {
+        var o = v;
+        return o.value === undefined || o.value === null ? "" : String(o.value);
+    }
+    return v === undefined || v === null ? "" : String(v);
+}
+/**
+ * Derive the dictionary element (column name) from a label the way Studio does for
+ * a scoped table: lower-case, every run of non-alphanumerics -> a single
+ * underscore, trimmed. Scoped custom columns are NOT u_-prefixed (that is a
+ * global-scope-on-OOB-table behaviour), so "URL" -> "url". Pass `column.name`
+ * explicitly for anything non-trivial.
+ */
+function deriveElement(label, explicit) {
+    if (explicit && explicit.trim())
+        return explicit.trim();
+    // Single linear pass: lower-case, collapse each run of non-alphanumerics to one
+    // underscore, then trim leading/trailing underscores. Deliberately NOT a regex —
+    // an anchored-quantifier trim (/^_+|_+$/) is a polynomial-ReDoS on attacker-shaped
+    // input (CodeQL js/polynomial-redos); a char scan is O(n).
+    var lower = String(label || "").toLowerCase();
+    var collapsed = "";
+    var prevUnderscore = false;
+    for (var i = 0; i < lower.length; i += 1) {
+        var ch = lower.charAt(i);
+        var isAlnum = (ch >= "a" && ch <= "z") || (ch >= "0" && ch <= "9");
+        if (isAlnum) {
+            collapsed += ch;
+            prevUnderscore = false;
+        }
+        else if (!prevUnderscore) {
+            collapsed += "_";
+            prevUnderscore = true;
+        }
+    }
+    var start = 0;
+    var end = collapsed.length;
+    while (start < end && collapsed.charAt(start) === "_")
+        start += 1;
+    while (end > start && collapsed.charAt(end - 1) === "_")
+        end -= 1;
+    var e = collapsed.slice(start, end);
+    if (!e)
+        throw new Error("addColumn: cannot derive a column name from label '" +
+            label +
+            "' — pass column.name.");
+    return e;
+}
+/**
+ * Overlay ONLY the new-column list-edit XML and the form-save machinery onto the
+ * fields harvested from the EXISTING table form. Returns a NEW object; every
+ * existing table field (name, label, scope, access, super_class, …) is preserved
+ * from `base` untouched — an add-column must not re-stamp the table. Mirrors the
+ * harvested-defaults-preserved contract of applyTableSaveOverlay.
+ */
+function applyAddColumnOverlay(base, o) {
+    var f = Object.assign({}, base);
+    f["sys_target"] = "sys_db_object";
+    f["sys_uniqueName"] = "sys_id";
+    f["sys_uniqueValue"] = o.tableSysId;
+    f["sys_row"] = o.tableSysId;
+    f["sys_action"] = o.saveActionSysId;
+    f["isFormPage"] = "true";
+    f["sysparm_modify_check"] = "true";
+    f["personalizer_sys_db_object"] = "true";
+    if (o.listEditKey) {
+        f[o.listEditKey] = o.columnXml;
+    }
+    return f;
+}
+function newSysId() {
+    return crypto.randomBytes(16).toString("hex");
+}
+function validate(params) {
+    if (!params || typeof params !== "object")
+        throw new Error("addColumn: params object required.");
+    if (!params.client)
+        throw new Error("addColumn: client is required.");
+    if (!params.table || !String(params.table).trim())
+        throw new Error("addColumn: table is required.");
+    if (!params.column || typeof params.column !== "object")
+        throw new Error("addColumn: column is required.");
+}
+/**
+ * Map every existing column on a table to its internal_type, via sys_dictionary.
+ * Used to snapshot before/after the save so the new column is found by diff —
+ * robust against ServiceNow's server-side element derivation (trailing-digit
+ * underscoring, cross-scope prefixing) that makes predicting the element brittle.
+ */
+async function elementTypeMap(client, tableName) {
+    var rows = await client.table.query("sys_dictionary", "name=" + tableName + "^element!=NULL", 1000);
+    var map = {};
+    for (var i = 0; i < rows.length; i += 1) {
+        var el = fieldValue(rows[i].element);
+        if (el)
+            map[el] = fieldValue(rows[i].internal_type);
+    }
+    return map;
+}
+/** Resolve the table by name or sys_id; returns its name, sys_id, and sys_scope. */
+async function resolveTable(client, table) {
+    var query = SYS_ID.test(table) ? "sys_id=" + table : "name=" + table;
+    var rows = await client.table.query("sys_db_object", query, 1);
+    if (rows.length === 0) {
+        throw new Error("addColumn: table '" + table + "' not found in sys_db_object.");
+    }
+    return {
+        name: fieldValue(rows[0].name) || table,
+        sysId: fieldValue(rows[0].sys_id),
+        scopeSysId: fieldValue(rows[0].sys_scope),
+    };
+}
+/** Resolve a scope name-or-sysid to the sys_app sys_id used by setCurrentApplication. */
+async function resolveAppSysId(client, scope) {
+    if (!scope)
+        return "";
+    var query = SYS_ID.test(scope) ? "sys_id=" + scope : "scope=" + scope;
+    var apps = await client.table.query("sys_app", query, 1);
+    return apps.length > 0 ? fieldValue(apps[0].sys_id) : "";
+}
+async function addColumn(params) {
+    validate(params);
+    var client = params.client;
+    // Normalize the single column (validates type, reference target, dedup is trivial).
+    var normalized = (0, buildTableSave_1.normalizeColumns)([params.column]);
+    var col = normalized[0];
+    var element = deriveElement(col.label, params.column.name);
+    var columnSysId = newSysId();
+    // The column XML is pure — build it now (used by dry-run AND the live POST).
+    var columnXml = (0, buildColumnXml_1.buildColumnXml)(normalized, [columnSysId]);
+    if (params.dryRun) {
+        return {
+            status: "dry-run",
+            table: params.table,
+            tableSysId: SYS_ID.test(params.table) ? params.table : "",
+            element: element,
+            label: col.label,
+            internalType: col.type,
+            columnSysId: columnSysId,
+            updateSetSysId: params.updateSetSysId ? params.updateSetSysId : "",
+            httpStatus: 0,
+            location: "",
+            columnXml: columnXml,
+            verified: false,
+            note: "dry-run: no session opened, no writes. Would add column '" +
+                element +
+                "' (" +
+                col.type +
+                ") to '" +
+                params.table +
+                "' via the table form save, then read it back from sys_dictionary.",
+        };
+    }
+    // ---- LIVE PATH (NOT YET VALIDATED END-TO-END) -----------------------------
+    // Resolve the existing table + its scope.
+    var resolved = await resolveTable(client, params.table);
+    var scopeForApp = params.scope && params.scope.trim()
+        ? params.scope.trim()
+        : resolved.scopeSysId;
+    var appSysId = await resolveAppSysId(client, scopeForApp);
+    var saveAction = params.saveActionSysId && params.saveActionSysId.trim()
+        ? params.saveActionSysId.trim()
+        : createTable_1.DEFAULT_SAVE_ACTION;
+    // Open the form session and put it in the table's scope before the save.
+    var auth = (0, formSession_1.resolveFormAuth)({
+        instance: params.instance,
+        user: params.user,
+        password: params.password,
+    });
+    var session = await (0, formSession_1.openFormSession)(auth);
+    var appSwitch = { ok: false, status: 0, body: "no app resolved" };
+    if (appSysId) {
+        appSwitch = await (0, formSession_1.setCurrentApplication)(auth, session, appSysId);
+    }
+    if (params.updateSetSysId) {
+        try {
+            await client.claude.changeUpdateSet({ sysId: params.updateSetSysId });
+        }
+        catch (e) {
+            /* best-effort */
+        }
+    }
+    // Harvest the EXISTING table form — its rendered related list yields the real key.
+    var harvest = await (0, formSession_1.getRecordForm)(auth, session, resolved.sysId);
+    var relId = params.columnsRelId && params.columnsRelId.trim()
+        ? params.columnsRelId.trim()
+        : createTable_1.DEFAULT_COLUMNS_REL_ID;
+    var colKey = harvest.listEditKey ? harvest.listEditKey : (0, buildTableSave_1.listEditKey)(relId);
+    var fields = applyAddColumnOverlay(harvest.fields, {
+        tableSysId: resolved.sysId,
+        saveActionSysId: saveAction,
+        listEditKey: colKey,
+        columnXml: columnXml,
+    });
+    // Snapshot the table's columns BEFORE the save so the new column is found by diff.
+    // ServiceNow derives the element from the column label server-side (the element
+    // field is sent empty), and normalizes it — a trailing digit gains an underscore,
+    // a cross-scope add gets a scope prefix — so predicting the element name is
+    // unreliable. The diff reports whatever element SN actually assigned.
+    var beforeMap = await elementTypeMap(client, resolved.name);
+    var resp = await (0, formSession_1.postForm)(auth, session, "/sys_db_object.do", fields);
+    // A form save's HTTP status does NOT prove the column landed: an EXISTING-record
+    // save re-renders the form with 200 on success (only a NEW record 302s to its
+    // assigned sys_id). So the sys_dictionary diff is the source of truth; only a hard
+    // HTTP error (4xx/5xx) skips it.
+    var hardError = resp.status >= 400;
+    var verified = false;
+    var actualElement = "";
+    var readBackType = "";
+    var added = [];
+    if (!hardError) {
+        var afterMap = await elementTypeMap(client, resolved.name);
+        added = Object.keys(afterMap).filter(function (e) {
+            return !Object.prototype.hasOwnProperty.call(beforeMap, e);
+        });
+        if (added.length > 0) {
+            verified = true;
+            // Prefer the new element that matches our derived guess; else take the first.
+            var exact = added.filter(function (e) {
+                return e === element || e.indexOf(element) !== -1;
+            });
+            actualElement = exact.length > 0 ? exact[0] : added[0];
+            readBackType = afterMap[actualElement];
+        }
+    }
+    var reportElement = actualElement || element;
+    var status = verified ? "created" : "failed";
+    var note;
+    if (status === "created") {
+        note =
+            "Added column '" +
+                reportElement +
+                "' (" +
+                col.type +
+                ") to " +
+                resolved.name +
+                " — verified present in sys_dictionary (HTTP " +
+                resp.status +
+                ")" +
+                (actualElement && actualElement !== element
+                    ? " (NOTE: ServiceNow assigned element '" +
+                        actualElement +
+                        "', not the requested '" +
+                        element +
+                        "')"
+                    : "") +
+                (readBackType && readBackType !== col.type
+                    ? " (NOTE: internal_type read back as '" + readBackType + "')"
+                    : "") +
+                (added.length > 1
+                    ? " (NOTE: " +
+                        added.length +
+                        " new columns appeared: " +
+                        added.join(", ") +
+                        ")"
+                    : "") +
+                ". Confirm a scoped insert + the sys_update_xml landed in the update set.";
+    }
+    else if (!hardError) {
+        note =
+            "save POST returned " +
+                resp.status +
+                " but no new column appeared on " +
+                resolved.name +
+                " — the form likely rejected the column. " +
+                resp.body.slice(0, 300);
+    }
+    else {
+        note =
+            "save POST returned " +
+                resp.status +
+                " (HTTP error). " +
+                resp.body.slice(0, 300);
+    }
+    if (params.debug) {
+        note +=
+            " [debug: appSwitch=" +
+                appSwitch.status +
+                (appSwitch.ok ? "/ok" : "/FAIL:" + appSwitch.body) +
+                " appSysId=" +
+                (appSysId || "(none)") +
+                " harvestedListEditKey=" +
+                (harvest.listEditKey ? "yes" : "no") +
+                " colKey=" +
+                colKey +
+                " fieldCount=" +
+                Object.keys(fields).length +
+                " location=" +
+                resp.location +
+                " readBackType=" +
+                (readBackType || "(none)") +
+                "]";
+    }
+    return {
+        status: status,
+        table: resolved.name,
+        tableSysId: resolved.sysId,
+        element: reportElement,
+        label: col.label,
+        internalType: col.type,
+        columnSysId: columnSysId,
+        updateSetSysId: params.updateSetSysId ? params.updateSetSysId : "",
+        httpStatus: resp.status,
+        location: resp.location,
+        columnXml: columnXml,
+        verified: verified,
+        note: note,
+    };
+}

package/dist/table/formSession.d.ts

@@ -53,12 +53,24 @@ export interface HarvestedForm {
     listEditKey: string;
 }
 /**
- * GET the new sys_db_object form and harvest every hidden/input field the browser
- * would submit (sysparm_ck, sysparm_encoded_record, the dynamic `<sysid>_text`
- * field, every sys_original.* default). The caller overlays capability params onto
- * `fields` before POSTing. NOTE: the new-record (sys_id=-1) form does NOT render
- * related lists, so `listEditKey` is normally empty — the caller falls back to the
- * constant "Table Columns" relId. Validated live 2026-06-13.
+ * GET a sys_db_object form (record `sysId`) and harvest every hidden/input field
+ * the browser would submit (sysparm_ck, sysparm_encoded_record, the dynamic
+ * `<sysid>_text` field, every sys_original.* default) plus the discovered list-edit
+ * key. The caller overlays capability params onto `fields` before POSTing.
+ *
+ * `sysId = "-1"` is the new-record form (table create). An EXISTING record's form
+ * renders the "Columns" related list inline, so for add-column the real
+ * `ListEditFormatterAction[sys_db_object.REL:<relId>]` key IS present and harvested
+ * here — unlike the new-record form, which renders no related lists (listEditKey
+ * empty, the create-table caller falls back to the constant relId). Validated live
+ * 2026-06-13 for the new-record path.
+ */
+export declare function getRecordForm(auth: FormAuth, session: FormSession, sysId: string): Promise<HarvestedForm>;
+/**
+ * GET the new-record (sys_id=-1) sys_db_object form. Thin wrapper over getRecordForm
+ * preserved for the create-table caller. The new-record form renders no related
+ * lists, so `listEditKey` is normally empty — the caller falls back to the constant
+ * "Table Columns" relId. Validated live 2026-06-13.
  */
 export declare function getNewRecordForm(auth: FormAuth, session: FormSession): Promise<HarvestedForm>;
 /**

package/dist/table/formSession.js

@@ -17,34 +17,54 @@ exports.resolveFormAuth = resolveFormAuth;
 exports.scrapeCk = scrapeCk;
 exports.openFormSession = openFormSession;
 exports.setCurrentApplication = setCurrentApplication;
+exports.getRecordForm = getRecordForm;
 exports.getNewRecordForm = getNewRecordForm;
 exports.parseFormInputs = parseFormInputs;
 exports.postForm = postForm;
 /** Env precedence mirrors client.ts: explicit > SN_* > SN_DEV_* > SN_PROD_*. */
 function resolveFormAuth(cfg) {
     var c = cfg || {};
-    var rawHost = c.instance
-        || process.env.SN_INSTANCE
-        || process.env.SN_DEV_INSTANCE
-        || process.env.SN_PROD_INSTANCE
-        || "";
+    var rawHost = c.instance ||
+        process.env.SN_INSTANCE ||
+        process.env.SN_DEV_INSTANCE ||
+        process.env.SN_PROD_INSTANCE ||
+        "";
     if (!rawHost) {
         throw new Error("ServiceNow instance not configured. Set SN_INSTANCE or pass { instance }.");
     }
-    var host = rawHost.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    // Strip the scheme, then trim trailing slashes by index. NOT /\/+$/ — an
+    // anchored one-or-more quantifier is a polynomial-ReDoS on a host with many
+    // trailing slashes (CodeQL js/polynomial-redos); the index walk is O(n).
+    var host = rawHost.replace(/^https?:\/\//, "");
+    var hostEnd = host.length;
+    while (hostEnd > 0 && host.charAt(hostEnd - 1) === "/")
+        hostEnd -= 1;
+    host = host.slice(0, hostEnd);
     if (host.indexOf(".") === -1)
         host = host.toLowerCase() + ".service-now.com";
-    var user = c.user || process.env.SN_USER || process.env.SN_DEV_USERNAME || process.env.SN_PROD_USERNAME || "";
-    var password = c.password || process.env.SN_PASSWORD || process.env.SN_DEV_PASSWORD || process.env.SN_PROD_PASSWORD || "";
+    var user = c.user ||
+        process.env.SN_USER ||
+        process.env.SN_DEV_USERNAME ||
+        process.env.SN_PROD_USERNAME ||
+        "";
+    var password = c.password ||
+        process.env.SN_PASSWORD ||
+        process.env.SN_DEV_PASSWORD ||
+        process.env.SN_PROD_PASSWORD ||
+        "";
     if (!user || !password) {
         throw new Error("ServiceNow credentials missing — set SN_USER/SN_PASSWORD (or SN_DEV_*/SN_PROD_*).");
     }
     return { host: host, user: user, password: password };
 }
-function base(auth) { return "https://" + auth.host; }
+function base(auth) {
+    return "https://" + auth.host;
+}
 function jarFrom(res, jar) {
     var anyHeaders = res.headers;
-    var setCookies = typeof anyHeaders.getSetCookie === "function" ? anyHeaders.getSetCookie() : [];
+    var setCookies = typeof anyHeaders.getSetCookie === "function"
+        ? anyHeaders.getSetCookie()
+        : [];
     for (var i = 0; i < setCookies.length; i += 1) {
         var kv = setCookies[i].split(";")[0];
         var eq = kv.indexOf("=");
@@ -54,40 +74,60 @@ function jarFrom(res, jar) {
     return jar;
 }
 function cookieHeader(jar) {
-    return Object.keys(jar).map(function (k) { return k + "=" + jar[k]; }).join("; ");
+    return Object.keys(jar)
+        .map(function (k) {
+        return k + "=" + jar[k];
+    })
+        .join("; ");
 }
 /** Scrape an authenticated g_ck (or form sysparm_ck) out of a page's HTML. */
 function scrapeCk(html) {
-    var m = html.match(/var g_ck = ['"]([0-9a-f]{40,})['"]/)
-        || html.match(/window\.g_ck = ['"]([0-9a-f]{40,})['"]/)
-        || html.match(/name="sysparm_ck"\s+value="([0-9a-f]{40,})"/);
+    var m = html.match(/var g_ck = ['"]([0-9a-f]{40,})['"]/) ||
+        html.match(/window\.g_ck = ['"]([0-9a-f]{40,})['"]/) ||
+        html.match(/name="sysparm_ck"\s+value="([0-9a-f]{40,})"/);
     return m ? m[1] : "";
 }
 /** Form-login (login.do) and return an authenticated { ck, jar }. */
 async function openFormSession(auth) {
     var B = base(auth);
     var jar = {};
-    var res = await fetch(B + "/login.do", { headers: { Accept: "text/html" }, redirect: "manual" });
+    var res = await fetch(B + "/login.do", {
+        headers: { Accept: "text/html" },
+        redirect: "manual",
+    });
     jarFrom(res, jar);
     var formCk = scrapeCk(await res.text());
     var body = new URLSearchParams({
-        user_name: auth.user, user_password: auth.password, sysparm_ck: formCk,
-        not_important: "", sys_action: "sysverb_login"
+        user_name: auth.user,
+        user_password: auth.password,
+        sysparm_ck: formCk,
+        not_important: "",
+        sys_action: "sysverb_login",
     }).toString();
     res = await fetch(B + "/login.do", {
         method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded", Cookie: cookieHeader(jar), Accept: "text/html" },
-        body: body, redirect: "manual"
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Cookie: cookieHeader(jar),
+            Accept: "text/html",
+        },
+        body: body,
+        redirect: "manual",
     });
     jarFrom(res, jar);
     var loc = res.headers.get("location");
     if (loc) {
-        var url = loc.indexOf("http") === 0 ? loc : B + (loc.indexOf("/") === 0 ? loc : "/" + loc);
-        res = await fetch(url, { headers: { Cookie: cookieHeader(jar), Accept: "text/html" }, redirect: "manual" });
+        var url = loc.indexOf("http") === 0
+            ? loc
+            : B + (loc.indexOf("/") === 0 ? loc : "/" + loc);
+        res = await fetch(url, {
+            headers: { Cookie: cookieHeader(jar), Accept: "text/html" },
+            redirect: "manual",
+        });
         jarFrom(res, jar);
     }
     res = await fetch(B + "/sys_db_object.do?sys_id=-1&sysparm_stack=no", {
-        headers: { Cookie: cookieHeader(jar), Accept: "text/html" }
+        headers: { Cookie: cookieHeader(jar), Accept: "text/html" },
     });
     jarFrom(res, jar);
     var ck = scrapeCk(await res.text());
@@ -114,12 +154,12 @@ async function setCurrentApplication(auth, session, appSysId) {
             "X-UserToken": session.ck,
             Cookie: cookieHeader(session.jar),
             "Content-Type": "application/json",
-            Accept: "application/json"
+            Accept: "application/json",
         },
         // The picker's ApplicationProcessor expects `app_id` (a `value` body returns
         // 400 "Missing Application Id").
         body: JSON.stringify({ app_id: appSysId }),
-        redirect: "manual"
+        redirect: "manual",
     });
     jarFrom(res, session.jar);
     var body = "";
@@ -133,17 +173,26 @@ async function setCurrentApplication(auth, session, appSysId) {
     return { ok: ok, status: res.status, body: body.slice(0, 200) };
 }
 /**
- * GET the new sys_db_object form and harvest every hidden/input field the browser
- * would submit (sysparm_ck, sysparm_encoded_record, the dynamic `<sysid>_text`
- * field, every sys_original.* default). The caller overlays capability params onto
- * `fields` before POSTing. NOTE: the new-record (sys_id=-1) form does NOT render
- * related lists, so `listEditKey` is normally empty — the caller falls back to the
- * constant "Table Columns" relId. Validated live 2026-06-13.
+ * GET a sys_db_object form (record `sysId`) and harvest every hidden/input field
+ * the browser would submit (sysparm_ck, sysparm_encoded_record, the dynamic
+ * `<sysid>_text` field, every sys_original.* default) plus the discovered list-edit
+ * key. The caller overlays capability params onto `fields` before POSTing.
+ *
+ * `sysId = "-1"` is the new-record form (table create). An EXISTING record's form
+ * renders the "Columns" related list inline, so for add-column the real
+ * `ListEditFormatterAction[sys_db_object.REL:<relId>]` key IS present and harvested
+ * here — unlike the new-record form, which renders no related lists (listEditKey
+ * empty, the create-table caller falls back to the constant relId). Validated live
+ * 2026-06-13 for the new-record path.
  */
-async function getNewRecordForm(auth, session) {
+async function getRecordForm(auth, session, sysId) {
     var B = base(auth);
-    var res = await fetch(B + "/sys_db_object.do?sys_id=-1&sysparm_stack=no", {
-        headers: { Cookie: cookieHeader(session.jar), Accept: "text/html" }
+    var id = sysId && String(sysId).trim() ? String(sysId).trim() : "-1";
+    var res = await fetch(B +
+        "/sys_db_object.do?sys_id=" +
+        encodeURIComponent(id) +
+        "&sysparm_stack=no", {
+        headers: { Cookie: cookieHeader(session.jar), Accept: "text/html" },
     });
     jarFrom(res, session.jar);
     var html = await res.text();
@@ -161,6 +210,15 @@ async function getNewRecordForm(auth, session) {
     }
     return { fields: fields, listEditKey: listEditKey };
 }
+/**
+ * GET the new-record (sys_id=-1) sys_db_object form. Thin wrapper over getRecordForm
+ * preserved for the create-table caller. The new-record form renders no related
+ * lists, so `listEditKey` is normally empty — the caller falls back to the constant
+ * "Table Columns" relId. Validated live 2026-06-13.
+ */
+async function getNewRecordForm(auth, session) {
+    return getRecordForm(auth, session, "-1");
+}
 /**
  * Parse `<input>` (and hidden) name/value pairs out of form HTML. Best-effort —
  * handles double/single-quoted attributes in either order. Exported for testing.
@@ -189,12 +247,15 @@ function attr(tag, name) {
     return null;
 }
 function decodeHtml(s) {
+    // Unescape &amp; LAST. Doing it first double-unescapes inputs like "&amp;lt;"
+    // ("&amp;lt;" -> "&lt;" -> "<"), the js/double-escaping vulnerability. With the
+    // ampersand handled last, each entity is unescaped exactly once.
     return s
-        .replace(/&amp;/g, "&")
         .replace(/&lt;/g, "<")
         .replace(/&gt;/g, ">")
         .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'");
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&");
 }
 /** POST a form-urlencoded field map to a `.do` path. Follows nothing — returns the 302. */
 async function postForm(auth, session, path, fields) {
@@ -210,10 +271,10 @@ async function postForm(auth, session, path, fields) {
             "X-UserToken": session.ck,
             Cookie: cookieHeader(session.jar),
             "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
-            Accept: "text/html"
+            Accept: "text/html",
         },
         body: params.toString(),
-        redirect: "manual"
+        redirect: "manual",
     });
     jarFrom(res, session.jar);
     var location = res.headers.get("location") || "";

package/dist/table/index.d.ts

@@ -9,5 +9,7 @@ export { buildColumnXml, xmlEscape } from "./buildColumnXml";
 export type { NormalizedColumn } from "./buildColumnXml";
 export { normalizeColumns, resolveType, applyTableSaveOverlay, defaultAccessFlags, showInMenuKey, listEditKey, TYPE_MAP } from "./buildTableSave";
 export type { ColumnSpec, AccessFlags, OverlaySpec } from "./buildTableSave";
-export { resolveFormAuth, openFormSession, setCurrentApplication, getNewRecordForm, parseFormInputs, postForm, scrapeCk } from "./formSession";
+export { resolveFormAuth, openFormSession, setCurrentApplication, getRecordForm, getNewRecordForm, parseFormInputs, postForm, scrapeCk } from "./formSession";
 export type { FormAuth, FormSession, HarvestedForm, PostResult } from "./formSession";
+export { addColumn, deriveElement, applyAddColumnOverlay } from "./addColumn";
+export type { AddColumnParams, AddColumnResult } from "./addColumn";