@tenonhq/dovetail-servicenow 0.0.20 → 0.0.22

package/dist/cli.js

@@ -706,6 +706,10 @@ function printHelp() {
         "                      --columns \"Label:type:max, ...\"  OR  --from-json <spec.json>\n" +
         "                      [--extends <t>] [--number-prefix <p>] [--user-role <r>]\n" +
         "                      [--no-acls] [--no-menu] [--update-set <sys_id>] [--dry-run] [--json])\n" +
+        "  add-column         Add ONE column to an EXISTING table via the Studio form save, then verify\n" +
+        "                     (--table <name|sys_id> --label <l> --type <t>\n" +
+        "                      [--name <element>] [--max-length <n>] [--reference <table>]\n" +
+        "                      [--scope <s>] [--update-set <sys_id>] [--dry-run] [--json])\n" +
         "  test-flow          Validate (default) or run a flow/subflow\n" +
         "                     (--sys-id <sys_id> [--execute --confirm] [--inputs <json>] [--json])\n" +
         "  edit-flow          Patch a flow/subflow (rename, description, step inputs)\n" +
@@ -806,6 +810,67 @@ async function runCreateTable(flags) {
         return 2;
     return 0;
 }
+/**
+ * dove-sn add-column:
+ *   --table x_cadso_journey --label URL --type url
+ *   [--name url] [--max-length 1024] [--reference <table>]
+ *   [--scope x_cadso_journey] [--update-set <sys_id>] [--save-action <sys_id>]
+ *   [--columns-rel-id <sys_id>] [--from-json <spec.json>] [--dry-run] [--debug] [--json]
+ */
+async function runAddColumn(flags) {
+    var spec = {};
+    if (flags["from-json"]) {
+        spec = JSON.parse(fs.readFileSync(path.resolve(flags["from-json"]), "utf8"));
+    }
+    var table = flags.table || spec.table;
+    var column = spec.column;
+    if (flags.label || flags.type) {
+        column = { label: flags.label || "", type: flags.type || "string" };
+        if (flags.name)
+            column.name = flags.name;
+        if (flags["max-length"])
+            column.max_length = flags["max-length"];
+        if (flags.reference)
+            column.reference = flags.reference;
+    }
+    if (!table || !column || !column.label) {
+        process.stderr.write("add-column: --table and --label (with --type) are required (or --from-json)\n");
+        return 1;
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        table: table,
+        column: column
+    };
+    var scope = flags.scope || spec.scope;
+    if (scope)
+        params.scope = scope;
+    var us = flags["update-set"] || spec.updateSetSysId;
+    if (us)
+        params.updateSetSysId = us;
+    var sa = flags["save-action"] || spec.saveActionSysId;
+    if (sa)
+        params.saveActionSysId = sa;
+    var relId = flags["columns-rel-id"] || spec.columnsRelId;
+    if (relId)
+        params.columnsRelId = relId;
+    if (flags["dry-run"] === "true" || spec.dryRun === true)
+        params.dryRun = true;
+    if (flags.debug === "true" || spec.debug === true)
+        params.debug = true;
+    var result = await (0, table_1.addColumn)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write("[" + result.status + "] " + result.table + "." + result.element + " (" + result.internalType + ")"
+            + (result.verified ? " — verified" : "")
+            + "\n" + result.note + "\n");
+    }
+    if (result.status === "failed")
+        return 2;
+    return 0;
+}
 async function main() {
     var parsed = parseArgs(process.argv.slice(2));
     // Load credentials before any command runs. `--env`/`--env-file` (or the
@@ -837,6 +902,9 @@ async function main() {
     if (parsed.command === "create-table") {
         return await runCreateTable(parsed.flags);
     }
+    if (parsed.command === "add-column") {
+        return await runAddColumn(parsed.flags);
+    }
     if (parsed.command === "test-flow") {
         return await runTestFlow(parsed.flags);
     }

package/dist/createClientFromEnvFile.d.ts

@@ -0,0 +1,29 @@
+import type { ServiceNowClient } from "./client";
+import type { ServiceNowClientConfig } from "./types";
+/**
+ * Build a ServiceNowClientConfig from a `.env`-style file WITHOUT mutating the
+ * global process.env.
+ *
+ * Unlike `loadEnvFile` (which calls `dotenv.config()` and is correct for a
+ * one-shot CLI), this reads the file into a local object via `dotenv.parse` so
+ * it is safe to call repeatedly inside a long-lived process — e.g. a per-call
+ * retarget in the MCP server, where a global dotenv mutation would race across
+ * concurrent reads.
+ *
+ * Instance/auth precedence within the file mirrors `createClient`'s env
+ * precedence (SN_* > SN_DEV_* > SN_PROD_*) so a file written for either the
+ * dev-style or prod-style variable names resolves the same way. The resolved
+ * values are returned as an explicit config object — they are never read from
+ * the surrounding process.env, so the file fully determines the target.
+ *
+ * Throws if the file cannot be read, or if it does not define an instance and
+ * a complete credential pair — failing loudly rather than silently falling
+ * back to whatever instance the host process happens to be pointed at.
+ */
+export declare function resolveConfigFromEnvFile(envPath: string): ServiceNowClientConfig;
+/**
+ * Construct a ServiceNowClient bound to the instance/credentials defined in a
+ * `.env`-style file, without touching the global process.env. See
+ * `resolveConfigFromEnvFile` for the precedence and failure rules.
+ */
+export declare function createClientFromEnvFile(envPath: string): ServiceNowClient;

package/dist/createClientFromEnvFile.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfigFromEnvFile = resolveConfigFromEnvFile;
+exports.createClientFromEnvFile = createClientFromEnvFile;
+const fs_1 = __importDefault(require("fs"));
+const dotenv_1 = __importDefault(require("dotenv"));
+const client_1 = require("./client");
+/**
+ * Build a ServiceNowClientConfig from a `.env`-style file WITHOUT mutating the
+ * global process.env.
+ *
+ * Unlike `loadEnvFile` (which calls `dotenv.config()` and is correct for a
+ * one-shot CLI), this reads the file into a local object via `dotenv.parse` so
+ * it is safe to call repeatedly inside a long-lived process — e.g. a per-call
+ * retarget in the MCP server, where a global dotenv mutation would race across
+ * concurrent reads.
+ *
+ * Instance/auth precedence within the file mirrors `createClient`'s env
+ * precedence (SN_* > SN_DEV_* > SN_PROD_*) so a file written for either the
+ * dev-style or prod-style variable names resolves the same way. The resolved
+ * values are returned as an explicit config object — they are never read from
+ * the surrounding process.env, so the file fully determines the target.
+ *
+ * Throws if the file cannot be read, or if it does not define an instance and
+ * a complete credential pair — failing loudly rather than silently falling
+ * back to whatever instance the host process happens to be pointed at.
+ */
+function resolveConfigFromEnvFile(envPath) {
+    if (typeof envPath !== "string" || envPath.length === 0) {
+        throw new Error("resolveConfigFromEnvFile: envPath must be a non-empty string.");
+    }
+    var raw;
+    try {
+        raw = fs_1.default.readFileSync(envPath, "utf8");
+    }
+    catch (e) {
+        throw new Error("Cannot read env file '" + envPath + "': " + (e && e.message ? e.message : String(e)));
+    }
+    var parsed = dotenv_1.default.parse(raw);
+    var instance = parsed.SN_INSTANCE || parsed.SN_DEV_INSTANCE || parsed.SN_PROD_INSTANCE || "";
+    var user = parsed.SN_USER || parsed.SN_DEV_USERNAME || parsed.SN_PROD_USERNAME || "";
+    var password = parsed.SN_PASSWORD || parsed.SN_DEV_PASSWORD || parsed.SN_PROD_PASSWORD || "";
+    if (!instance) {
+        throw new Error("env file '" + envPath + "' does not define a ServiceNow instance — " +
+            "set SN_INSTANCE (preferred) or SN_DEV_INSTANCE / SN_PROD_INSTANCE.");
+    }
+    if (!user || !password) {
+        throw new Error("env file '" + envPath + "' is missing ServiceNow credentials — " +
+            "set SN_USER/SN_PASSWORD (preferred) or SN_DEV_USERNAME/SN_DEV_PASSWORD (or SN_PROD_*).");
+    }
+    return { instance: instance, user: user, password: password };
+}
+/**
+ * Construct a ServiceNowClient bound to the instance/credentials defined in a
+ * `.env`-style file, without touching the global process.env. See
+ * `resolveConfigFromEnvFile` for the precedence and failure rules.
+ */
+function createClientFromEnvFile(envPath) {
+    return (0, client_1.createClient)(resolveConfigFromEnvFile(envPath));
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  * REST API so every change lands in the target update set and scope.
  */
 export { createClient } from "./client";
+export { createClientFromEnvFile, resolveConfigFromEnvFile } from "./createClientFromEnvFile";
 export type { ServiceNowClient, TableQueryOptions, TableSchema, TableSchemaField } from "./client";
 export { addChoicesToField } from "./choices";
 export { formatAddChoicesResult } from "./formatter";
@@ -17,5 +18,5 @@ export { sincPlugin } from "./plugin";
 export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, publishActionType, editActionType, readFlow, readActionType, publishFlow, copyFlow, createFlow, buildPublishModel, editFlow, testFlow, DEFAULT_RUN_FLOW_PATH, generateSysId, topoSort, executeWritePlan, WriteOrderError } from "./flowDesigner";
 export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, EditActionTypeParams, EditActionTypeResult, EditActionTypeOps, ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable, ReadActionTypeParams, ReadActionTypeResult, ActionIo, PublishFlowParams, PublishFlowResult, CopyFlowParams, CopyFlowResult, CreateFlowParams, CreateFlowResult, EditFlowParams, EditFlowResult, EditFlowOps, StepInputPatch, TestFlowParams, TestFlowResult, WriteOp, WriteOpResult } from "./flowDesigner";
 export type { ServiceNowClientConfig, ChoiceValue, ChoiceType, AddChoicesParams, AddChoicesResult, ChoiceActionResult, DictionaryRecord, UpdateSetRecord, LayoutAction, LayoutRecordResult, LayoutResult, CreateViewParams, CreateViewResult, FormSectionSpec, SetFormLayoutParams, SetListLayoutParams, SetRelatedListsParams } from "./types";
-export { createTable, projectTableGraph, buildColumnXml, normalizeColumns, resolveType, applyTableSaveOverlay, defaultAccessFlags, TYPE_MAP, DEFAULT_SUPER_CLASS, DEFAULT_SAVE_ACTION } from "./table";
-export type { CreateTableParams, CreateTableResult, TableGraph, NormalizedColumn, ColumnSpec, AccessFlags, OverlaySpec } from "./table";
+export { createTable, projectTableGraph, buildColumnXml, normalizeColumns, resolveType, applyTableSaveOverlay, defaultAccessFlags, TYPE_MAP, DEFAULT_SUPER_CLASS, DEFAULT_SAVE_ACTION, addColumn, deriveElement, applyAddColumnOverlay } from "./table";
+export type { CreateTableParams, CreateTableResult, AddColumnParams, AddColumnResult, TableGraph, NormalizedColumn, ColumnSpec, AccessFlags, OverlaySpec } from "./table";

package/dist/index.js

@@ -6,9 +6,12 @@
  * REST API so every change lands in the target update set and scope.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.TYPE_MAP = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = exports.normalizeColumns = exports.buildColumnXml = exports.projectTableGraph = exports.createTable = exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.createClient = void 0;
+exports.applyAddColumnOverlay = exports.deriveElement = exports.addColumn = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.TYPE_MAP = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = exports.normalizeColumns = exports.buildColumnXml = exports.projectTableGraph = exports.createTable = exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.resolveConfigFromEnvFile = exports.createClientFromEnvFile = exports.createClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
+var createClientFromEnvFile_1 = require("./createClientFromEnvFile");
+Object.defineProperty(exports, "createClientFromEnvFile", { enumerable: true, get: function () { return createClientFromEnvFile_1.createClientFromEnvFile; } });
+Object.defineProperty(exports, "resolveConfigFromEnvFile", { enumerable: true, get: function () { return createClientFromEnvFile_1.resolveConfigFromEnvFile; } });
 var choices_1 = require("./choices");
 Object.defineProperty(exports, "addChoicesToField", { enumerable: true, get: function () { return choices_1.addChoicesToField; } });
 var formatter_1 = require("./formatter");
@@ -58,3 +61,6 @@ Object.defineProperty(exports, "defaultAccessFlags", { enumerable: true, get: fu
 Object.defineProperty(exports, "TYPE_MAP", { enumerable: true, get: function () { return table_1.TYPE_MAP; } });
 Object.defineProperty(exports, "DEFAULT_SUPER_CLASS", { enumerable: true, get: function () { return table_1.DEFAULT_SUPER_CLASS; } });
 Object.defineProperty(exports, "DEFAULT_SAVE_ACTION", { enumerable: true, get: function () { return table_1.DEFAULT_SAVE_ACTION; } });
+Object.defineProperty(exports, "addColumn", { enumerable: true, get: function () { return table_1.addColumn; } });
+Object.defineProperty(exports, "deriveElement", { enumerable: true, get: function () { return table_1.deriveElement; } });
+Object.defineProperty(exports, "applyAddColumnOverlay", { enumerable: true, get: function () { return table_1.applyAddColumnOverlay; } });

package/dist/mcp/registry.d.ts

@@ -10,7 +10,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { ToolAnnotations } from "@tenonhq/dovetail-mcp-kit";
 import type { ServiceNowClient } from "../client";
-export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "flow_view", "action_view", "flow_publish", "flow_copy", "flow_create", "flow_test", "flow_edit", "create_table"];
+export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "flow_view", "action_view", "flow_publish", "flow_copy", "flow_create", "flow_test", "flow_edit", "create_table", "add_column"];
 export type ToolName = typeof TOOL_NAMES[number];
 export interface RegistryDeps {
     /** Optional client injection for tests; defaults to createClient({}). */

package/dist/mcp/registry.js

@@ -40,7 +40,8 @@ exports.TOOL_NAMES = [
     "flow_create",
     "flow_test",
     "flow_edit",
-    "create_table"
+    "create_table",
+    "add_column"
 ];
 // Annotation presets (READ_ONLY / WRITE_ADDITIVE_IDEMPOTENT / WRITE_CREATE /
 // WRITE_OVERWRITE / WRITE_EXECUTE) come from @tenonhq/dovetail-mcp-kit.
@@ -263,6 +264,35 @@ function buildDescriptors(deps = {}) {
                     dryRun: p.dryRun
                 });
             }
+        },
+        {
+            name: "add_column",
+            annotations: dovetail_mcp_kit_1.WRITE_CREATE,
+            description: "Add ONE column to an EXISTING ServiceNow table, headless and faithfully. Creating a column is a "
+                + "sys_dictionary insert; a REST/createRecord insert reliably 500s for a scoped-app column. This "
+                + "replays the Studio table-form save (POST /sys_db_object.do) against the existing table record, "
+                + "embedding the new column as list-edit XML, then READS THE COLUMN BACK from sys_dictionary to prove "
+                + "it landed (a 302 that did not create the field is reported failed, not created). table is the table "
+                + "name or its sys_db_object sys_id; column is { label, type, name?, max_length?, reference? } with "
+                + "friendly types mapped to internal types (string -> string_full_utf8); element is derived from label "
+                + "unless column.name is given. dryRun:true returns the plan + column XML with no session and no writes. "
+                + "NOTE: the live write path is pending a validated-live spike — prefer dryRun until confirmed, and "
+                + "always verify the sys_update_xml landed in the intended update set.",
+            shape: schemas_1.addColumnSchema.shape,
+            handler: async function (args) {
+                var p = schemas_1.addColumnSchema.parse(args);
+                return (0, table_1.addColumn)({
+                    client: client(),
+                    table: p.table,
+                    column: p.column,
+                    scope: p.scope,
+                    updateSetSysId: p.updateSetSysId,
+                    saveActionSysId: p.saveActionSysId,
+                    columnsRelId: p.columnsRelId,
+                    dryRun: p.dryRun,
+                    debug: p.debug
+                });
+            }
         }
     ];
 }

package/dist/mcp/schemas.d.ts

@@ -480,3 +480,61 @@ export declare var createTableSchema: z.ZodObject<{
     saveActionSysId?: string | undefined;
     columnsRelId?: string | undefined;
 }>;
+export declare var addColumnSchema: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodObject<{
+        label: z.ZodString;
+        type: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        max_length: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+        reference: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        label: string;
+        name?: string | undefined;
+        max_length?: string | number | undefined;
+        reference?: string | undefined;
+    }, {
+        type: string;
+        label: string;
+        name?: string | undefined;
+        max_length?: string | number | undefined;
+        reference?: string | undefined;
+    }>;
+    scope: z.ZodOptional<z.ZodString>;
+    updateSetSysId: z.ZodOptional<z.ZodString>;
+    saveActionSysId: z.ZodOptional<z.ZodString>;
+    columnsRelId: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    table: string;
+    column: {
+        type: string;
+        label: string;
+        name?: string | undefined;
+        max_length?: string | number | undefined;
+        reference?: string | undefined;
+    };
+    dryRun?: boolean | undefined;
+    debug?: boolean | undefined;
+    scope?: string | undefined;
+    updateSetSysId?: string | undefined;
+    saveActionSysId?: string | undefined;
+    columnsRelId?: string | undefined;
+}, {
+    table: string;
+    column: {
+        type: string;
+        label: string;
+        name?: string | undefined;
+        max_length?: string | number | undefined;
+        reference?: string | undefined;
+    };
+    dryRun?: boolean | undefined;
+    debug?: boolean | undefined;
+    scope?: string | undefined;
+    updateSetSysId?: string | undefined;
+    saveActionSysId?: string | undefined;
+    columnsRelId?: string | undefined;
+}>;

package/dist/mcp/schemas.js

@@ -4,7 +4,7 @@
  * own file so registry.ts stays focused on wiring.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTableSchema = exports.columnSpecSchema = exports.editFlowSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.createFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
+exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.editFlowSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.createFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
 const zod_1 = require("zod");
 exports.createViewSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
@@ -137,3 +137,13 @@ exports.createTableSchema = zod_1.z.object({
     dryRun: zod_1.z.boolean().optional(),
     debug: zod_1.z.boolean().optional()
 });
+exports.addColumnSchema = zod_1.z.object({
+    table: zod_1.z.string().min(1),
+    column: exports.columnSpecSchema,
+    scope: zod_1.z.string().optional(),
+    updateSetSysId: zod_1.z.string().optional(),
+    saveActionSysId: zod_1.z.string().optional(),
+    columnsRelId: zod_1.z.string().optional(),
+    dryRun: zod_1.z.boolean().optional(),
+    debug: zod_1.z.boolean().optional()
+});

package/dist/table/addColumn.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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`.
+ */
+import type { ServiceNowClient } from "../client";
+import { ColumnSpec } from "./buildTableSave";
+export interface AddColumnParams {
+    /** REST client for table/scope resolution + the read-back verify. */
+    client: ServiceNowClient;
+    /** Existing table — its name ("x_cadso_journey") OR its sys_db_object sys_id. */
+    table: string;
+    /** The single column to add. `name` (the element) is optional; derived from label when omitted. */
+    column: ColumnSpec;
+    /** Scope name or sys_scope sys_id to run the form session in. Defaults to the table's own scope. */
+    scope?: string;
+    /** Update set sys_id to pin the writes to. Strongly recommended. */
+    updateSetSysId?: string;
+    /** Override the Save UI-action sys_id (defaults to the well-known global Save). */
+    saveActionSysId?: string;
+    /** Override the "Table Columns" relationship sys_id (fallback only — the existing form normally yields it). */
+    columnsRelId?: string;
+    /** Emit diagnostic detail in the result note. */
+    debug?: boolean;
+    /** Instance/creds for the form session (default: env, same precedence as the client). */
+    instance?: string;
+    user?: string;
+    password?: string;
+    /** Plan only — no session, no writes. Pure + deterministic. */
+    dryRun?: boolean;
+}
+export interface AddColumnResult {
+    status: "created" | "dry-run" | "failed";
+    /** The table's name (resolved; echoes the input on dry-run). */
+    table: string;
+    /** sys_db_object sys_id ("" on dry-run / when unresolved). */
+    tableSysId: string;
+    /** The dictionary element (column name) — derived from label or the explicit `name`. */
+    element: string;
+    /** The column's display label. */
+    label: string;
+    /** Resolved ServiceNow internal_type (friendly -> internal). */
+    internalType: string;
+    /** Client-generated sys_id sent for the new sys_dictionary row. */
+    columnSysId: string;
+    /** Update set the write was pinned to ("" if none). */
+    updateSetSysId: string;
+    httpStatus: number;
+    /** 302 Location on a successful POST. */
+    location: string;
+    /** The embedded column XML (always populated — it is pure). */
+    columnXml: string;
+    /** True only when the column was READ BACK from sys_dictionary after the POST. */
+    verified: boolean;
+    /** Human-readable note (success summary, the read-back result, or the failure body). */
+    note: string;
+}
+/**
+ * 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.
+ */
+export declare function deriveElement(label: string, explicit?: string): string;
+/**
+ * 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.
+ */
+export declare function applyAddColumnOverlay(base: Record<string, string>, o: {
+    tableSysId: string;
+    saveActionSysId: string;
+    listEditKey: string;
+    columnXml: string;
+}): Record<string, string>;
+export declare function addColumn(params: AddColumnParams): Promise<AddColumnResult>;

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";

package/dist/table/index.js

@@ -5,7 +5,7 @@
  * live-validation caveat.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scrapeCk = exports.postForm = exports.parseFormInputs = exports.getNewRecordForm = exports.setCurrentApplication = exports.openFormSession = exports.resolveFormAuth = exports.TYPE_MAP = exports.listEditKey = exports.showInMenuKey = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = exports.normalizeColumns = exports.xmlEscape = exports.buildColumnXml = exports.DEFAULT_COLUMNS_REL_ID = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.parseSysIdFromLocation = exports.projectTableGraph = exports.createTable = void 0;
+exports.applyAddColumnOverlay = exports.deriveElement = exports.addColumn = exports.scrapeCk = exports.postForm = exports.parseFormInputs = exports.getNewRecordForm = exports.getRecordForm = exports.setCurrentApplication = exports.openFormSession = exports.resolveFormAuth = exports.TYPE_MAP = exports.listEditKey = exports.showInMenuKey = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = exports.normalizeColumns = exports.xmlEscape = exports.buildColumnXml = exports.DEFAULT_COLUMNS_REL_ID = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.parseSysIdFromLocation = exports.projectTableGraph = exports.createTable = void 0;
 var createTable_1 = require("./createTable");
 Object.defineProperty(exports, "createTable", { enumerable: true, get: function () { return createTable_1.createTable; } });
 Object.defineProperty(exports, "projectTableGraph", { enumerable: true, get: function () { return createTable_1.projectTableGraph; } });
@@ -28,7 +28,12 @@ var formSession_1 = require("./formSession");
 Object.defineProperty(exports, "resolveFormAuth", { enumerable: true, get: function () { return formSession_1.resolveFormAuth; } });
 Object.defineProperty(exports, "openFormSession", { enumerable: true, get: function () { return formSession_1.openFormSession; } });
 Object.defineProperty(exports, "setCurrentApplication", { enumerable: true, get: function () { return formSession_1.setCurrentApplication; } });
+Object.defineProperty(exports, "getRecordForm", { enumerable: true, get: function () { return formSession_1.getRecordForm; } });
 Object.defineProperty(exports, "getNewRecordForm", { enumerable: true, get: function () { return formSession_1.getNewRecordForm; } });
 Object.defineProperty(exports, "parseFormInputs", { enumerable: true, get: function () { return formSession_1.parseFormInputs; } });
 Object.defineProperty(exports, "postForm", { enumerable: true, get: function () { return formSession_1.postForm; } });
 Object.defineProperty(exports, "scrapeCk", { enumerable: true, get: function () { return formSession_1.scrapeCk; } });
+var addColumn_1 = require("./addColumn");
+Object.defineProperty(exports, "addColumn", { enumerable: true, get: function () { return addColumn_1.addColumn; } });
+Object.defineProperty(exports, "deriveElement", { enumerable: true, get: function () { return addColumn_1.deriveElement; } });
+Object.defineProperty(exports, "applyAddColumnOverlay", { enumerable: true, get: function () { return addColumn_1.applyAddColumnOverlay; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-servicenow",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "engines": {
     "node": ">=22"
   },