@tenonhq/dovetail-servicenow 0.0.23 → 0.0.25

package/README.md

@@ -253,6 +253,72 @@ adds diagnostics (app-switch status, resolved column key, assigned sys_id) to th
 result note. Ground truth (the HAR dissection) lives in the CTO repo's create-table
 docs.
 
+### Set a field on a record
+
+Set scalar field value(s) on an **existing** data record, capture the change into
+an update set, then read it back and verify.
+
+```bash
+# Target by sys_id
+npx dove-sn set-field \
+  --table x_cadso_core_metric_point_type --sys-id <sys_id> \
+  --fields "order=20" --update-set <sys_id> --dry-run --json
+
+# Or target by a query that resolves to EXACTLY one row
+npx dove-sn set-field \
+  --table x_cadso_core_metric_point_type --query "name=send_size" \
+  --fields "order=20,label=Send Size" --update-set <sys_id>
+```
+
+`set-field` wraps the update-set-aware `pushWithUpdateSet` core op (update-set +
+scope switching handled server-side, so no `sys_user_preference` is touched), then
+re-queries the record and verifies each value landed. It **refuses** schema tables
+(`sys_db_object` / `sys_dictionary`) — use `add-column` / `create-table` for those.
+`--fields` is a comma-separated `key=value` map (values are sent as strings;
+ServiceNow coerces); `--update-set` is required so the change is captured;
+`--dry-run` reads the current values and prints the plan without writing. Exit
+codes: `0` applied / dry-run, `1` bad args, `2` write landed but read-back did not
+verify.
+
+### Create a record
+
+Insert **one** new data record, owned by an explicit scope and captured into an
+update set, then read it back and verify.
+
+```bash
+npx dove-sn create-record \
+  --table x_cadso_core_metric_point_type \
+  --fields "name=avg_message_parts,label=Avg. Message Parts,order=35" \
+  --scope x_cadso_core --update-set <sys_id> \
+  --if-absent "name=avg_message_parts" --dry-run --json
+```
+
+`create-record` wraps the scope- and update-set-aware `createRecord` core op, which
+switches the executing user's app scope + update set server-side, inserts, and
+restores both — so the record is owned by the right app and the insert is captured
+in the right update set. Like `set-field` it **refuses** schema tables and verifies
+via read-back. `--scope` and `--update-set` are required; `--if-absent
+"<encoded-query>"` makes re-runs idempotent (the insert is skipped when the query
+already matches a row). Exit codes: `0` created / skipped-in-sync / dry-run, `1` bad
+args, `2` write landed unverified (or skipped with drift). To **update** an existing
+record instead, use `set-field`.
+
+Both verbs are exported for programmatic use:
+
+```ts
+import { createClient, setField, createRecord } from "@tenonhq/dovetail-servicenow";
+
+var client = createClient({});
+var r = await setField({
+  client: client,
+  table: "x_cadso_core_metric_point_type",
+  sysId: "<sys_id>",
+  fields: { order: "20" },
+  updateSetSysId: "<sys_id>"
+});
+console.log(r.status, r.verified); // "applied" true
+```
+
 `test-flow` defaults to **validate** — a safe pre-flight (published? inputs match
 declared variables?) that never runs the flow; `--execute --confirm` runs it via
 the server-side FlowAPI runner (deploy `resources/runFlow.md` first).
@@ -323,8 +389,11 @@ console.log(formatLayoutResult("form layout", result));
 
 `dove-sn mcp` runs a self-contained MCP stdio server exposing the tools to
 Claude Code and agents: `create_view`, `set_list_layout`, `set_form_layout`,
-`set_related_lists`, `add_choices_to_field`, plus the Flow Designer tools
-`flow_view` (read a flow/subflow's step graph), `action_view` (read an action
+`set_related_lists`, `add_choices_to_field`, the schema verbs `create_table` /
+`add_column`, the record-write verbs `set_field` (update scalar fields on an
+existing record) and `create_record` (insert one record) — both update-set-captured
+and read-back-verified — `host_assets` (deploy a built dist/), plus the Flow Designer
+tools `flow_view` (read a flow/subflow's step graph), `action_view` (read an action
 type's model), `flow_publish` (compile a flow/subflow snapshot), `flow_copy`
 (copy a flow as an inactive draft), `flow_create` (create a NEW flow from scratch +
 publish, grafting a template), `flow_test` (validate or run a flow), and

package/dist/cli.js

@@ -79,6 +79,8 @@ const editFlow_1 = require("./flowDesigner/editFlow");
 const editActionType_1 = require("./flowDesigner/editActionType");
 const testFlow_1 = require("./flowDesigner/testFlow");
 const table_1 = require("./table");
+const setField_1 = require("./setField");
+const createRecord_1 = require("./createRecord");
 const hostAssets_1 = require("./hostAssets");
 const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
 function parseArgs(argv) {
@@ -711,6 +713,12 @@ function printHelp() {
         "                     (--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" +
+        "  set-field          Set scalar field value(s) on an EXISTING record, into an update set, then verify\n" +
+        "                     (--table <t> --sys-id <id>|--query <q> --fields \"k=v,k2=v2\"\n" +
+        "                      --update-set <sys_id> [--dry-run] [--json])\n" +
+        "  create-record      Create ONE NEW record in a data table, into an update set, then verify\n" +
+        "                     (--table <t> --fields \"k=v,k2=v2\" --scope <s> --update-set <sys_id>\n" +
+        "                      [--if-absent <encoded-query>] [--dry-run] [--json])\n" +
         "  host-assets        Deploy a built dist/ to ServiceNow (carrier sys_ui_script + attachment + m2m)\n" +
         "                     (--dir <dist> --app <sys_id> --scope <namespace>\n" +
         "                      [--update-set <sys_id>] [--max-bytes <n>] [--allow-oversize] [--dry-run] [--json])\n" +
@@ -875,6 +883,111 @@ async function runAddColumn(flags) {
         return 2;
     return 0;
 }
+/** Parse inline `--fields "k=v, k2=v2"` into a field map. */
+function parseFieldsInline(input) {
+    var out = {};
+    if (!input)
+        return out;
+    var parts = input.split(",");
+    for (var i = 0; i < parts.length; i += 1) {
+        var piece = parts[i].trim();
+        if (!piece)
+            continue;
+        var eq = piece.indexOf("=");
+        if (eq === -1)
+            continue;
+        var key = piece.slice(0, eq).trim();
+        if (key)
+            out[key] = piece.slice(eq + 1).trim();
+    }
+    return out;
+}
+/**
+ * dove-sn set-field:
+ *   --table x_cadso_core_metric_point_type
+ *   --sys-id <id>  |  --query "name=send_size"   (query must resolve to exactly 1 row)
+ *   --fields "order=20"                          (comma-separated key=value pairs)
+ *   --update-set <sys_id>                        (required — the change is captured here)
+ *   [--dry-run] [--json]
+ * Exit codes: 0 applied/dry-run, 1 bad args, 2 write landed but read-back unverified.
+ */
+async function runSetField(flags) {
+    var table = flags.table;
+    var fields = parseFieldsInline(flags.fields || "");
+    var hasTarget = Boolean(flags["sys-id"] || flags.query);
+    if (!table || Object.keys(fields).length === 0 || !hasTarget || !flags["update-set"]) {
+        process.stderr.write("set-field: --table, --fields \"k=v\", one of --sys-id/--query, and --update-set are required\n");
+        return 1;
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        table: table,
+        fields: fields,
+        updateSetSysId: flags["update-set"]
+    };
+    if (flags["sys-id"])
+        params.sysId = flags["sys-id"];
+    if (flags.query)
+        params.query = flags.query;
+    if (flags["dry-run"] === "true")
+        params.dryRun = true;
+    var result = await (0, setField_1.setField)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write("[" + result.status + "] " + result.table + "/" + result.sysId + " "
+            + JSON.stringify(result.fields) + (result.verified ? " — verified" : "")
+            + "\n" + result.note + "\n");
+    }
+    if (result.status === "failed")
+        return 2;
+    return 0;
+}
+/**
+ * dove-sn create-record:
+ *   --table x_cadso_core_metric_point_type
+ *   --fields "name=avg_message_parts,label=Avg. Message Parts,order=35"
+ *   --scope x_cadso_core                         (the app that owns the new record)
+ *   --update-set <sys_id>                        (required — the insert is captured here)
+ *   [--if-absent "name=avg_message_parts"]       (skip the insert when this query already matches)
+ *   [--dry-run] [--json]
+ * Exit codes: 0 created/skipped-in-sync/dry-run, 1 bad args, 2 write landed but read-back unverified
+ * (or skipped with drift).
+ */
+async function runCreateRecord(flags) {
+    var table = flags.table;
+    var fields = parseFieldsInline(flags.fields || "");
+    if (!table || Object.keys(fields).length === 0 || !flags.scope || !flags["update-set"]) {
+        process.stderr.write("create-record: --table, --fields \"k=v\", --scope and --update-set are required\n");
+        return 1;
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        table: table,
+        fields: fields,
+        scope: flags.scope,
+        updateSetSysId: flags["update-set"]
+    };
+    if (flags["if-absent"])
+        params.ifAbsentQuery = flags["if-absent"];
+    if (flags["dry-run"] === "true")
+        params.dryRun = true;
+    var result = await (0, createRecord_1.createRecord)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write("[" + result.status + "] " + result.table + "/" + (result.sysId || "(new)") + " "
+            + JSON.stringify(result.fields) + (result.verified ? " — verified" : "")
+            + "\n" + result.note + "\n");
+    }
+    if (result.status === "failed")
+        return 2;
+    if (result.status === "skipped" && !result.verified)
+        return 2;
+    return 0;
+}
 /**
  * dove-sn host-assets:
  *   --dir <dist>            Required. Path to the pre-built dist/ directory.
@@ -951,6 +1064,12 @@ async function main() {
     if (parsed.command === "add-column") {
         return await runAddColumn(parsed.flags);
     }
+    if (parsed.command === "set-field") {
+        return await runSetField(parsed.flags);
+    }
+    if (parsed.command === "create-record") {
+        return await runCreateRecord(parsed.flags);
+    }
     if (parsed.command === "host-assets") {
         return await runHostAssets(parsed.flags);
     }

package/dist/client.d.ts

@@ -74,7 +74,7 @@ export interface ServiceNowClient {
         /** POST /api/cadso/dovetail_core/createRecord (legacy: /api/cadso/dovetail/createRecord). */
         createRecord: (params: {
             table: string;
-            fields: Record<string, any>;
+            fields: Record<string, unknown>;
             scope?: string;
             update_set_sys_id?: string;
             sys_id?: string;
@@ -87,7 +87,7 @@ export interface ServiceNowClient {
             update_set_sys_id: string;
             table: string;
             record_sys_id: string;
-            fields: Record<string, any>;
+            fields: Record<string, unknown>;
         }) => Promise<{
             sys_id: string;
             [k: string]: any;

package/dist/createRecord.d.ts

@@ -0,0 +1,33 @@
+/**
+ * dove-sn create-record — create ONE new record in a data table, captured
+ * into a specified update set, then read back and verify.
+ *
+ * Wraps the Dovetail core Scripted REST `createRecord` op, which switches the
+ * executing user's app scope and update set server-side, inserts, and
+ * restores both — so the record is owned by the right app and the insert is
+ * captured in the right update set without touching sys_user_preference.
+ * The INSERT counterpart to `set-field`.
+ *
+ * NOT for schema tables (sys_db_object / sys_dictionary) — that's
+ * create-table / add-column. To UPDATE an existing record, use `set-field`.
+ */
+import type { ServiceNowClient } from "./client";
+import type { RecordWriteResult } from "./setField";
+export interface CreateRecordParams {
+    client?: ServiceNowClient;
+    table: string;
+    /** Field name -> value for the new record. Values are sent as strings; ServiceNow coerces. */
+    fields: Record<string, string>;
+    /** App scope that will own the record. Required — session-scope stamping is the #1 wrong-scope cause. */
+    scope?: string;
+    /** Update set to capture the insert into. Required for a tracked write. */
+    updateSetSysId?: string;
+    /** Encoded query; when it already matches a row the insert is skipped (idempotent re-runs). */
+    ifAbsentQuery?: string;
+    dryRun?: boolean;
+}
+export interface CreateRecordResult extends RecordWriteResult {
+    status: "dry-run" | "created" | "skipped" | "failed";
+    scope: string;
+}
+export declare function createRecord(params: CreateRecordParams): Promise<CreateRecordResult>;

package/dist/createRecord.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * dove-sn create-record — create ONE new record in a data table, captured
+ * into a specified update set, then read back and verify.
+ *
+ * Wraps the Dovetail core Scripted REST `createRecord` op, which switches the
+ * executing user's app scope and update set server-side, inserts, and
+ * restores both — so the record is owned by the right app and the insert is
+ * captured in the right update set without touching sys_user_preference.
+ * The INSERT counterpart to `set-field`.
+ *
+ * NOT for schema tables (sys_db_object / sys_dictionary) — that's
+ * create-table / add-column. To UPDATE an existing record, use `set-field`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRecord = createRecord;
+const client_1 = require("./client");
+const setField_1 = require("./setField");
+// Same guard as set-field: schema tables are never written as data — routed to
+// the dedicated schema verbs instead so we never orphan or corrupt metadata.
+var REFUSED_TABLES = ["sys_db_object", "sys_dictionary"];
+async function createRecord(params) {
+    var client = params.client || (0, client_1.createClient)({});
+    var table = params.table;
+    if (!table) {
+        throw new Error("create-record: --table is required.");
+    }
+    if (REFUSED_TABLES.indexOf(table) !== -1) {
+        throw new Error("create-record: refusing to write " + table + " as data — it is a schema table. "
+            + "Use add-column / create-table for schema changes.");
+    }
+    var fieldNames = params.fields ? Object.keys(params.fields) : [];
+    if (fieldNames.length === 0) {
+        throw new Error("create-record: at least one field (--fields key=value) is required.");
+    }
+    if (!params.scope) {
+        throw new Error("create-record: --scope is required so the record is owned by the right app.");
+    }
+    if (!params.updateSetSysId) {
+        throw new Error("create-record: --update-set <sys_id> is required so the insert is captured.");
+    }
+    var readFields = ["sys_id"].concat(fieldNames);
+    // Idempotent re-runs: skip the insert when the guard query already matches.
+    if (params.ifAbsentQuery) {
+        var existing = await client.table.query(table, params.ifAbsentQuery, {
+            limit: 1,
+            fields: readFields
+        });
+        if (existing.length > 0) {
+            var existingSysId = (0, setField_1.fieldToString)(existing[0].sys_id);
+            var existingValues = (0, setField_1.pickFields)(existing[0], fieldNames);
+            var matches = true;
+            for (var i = 0; i < fieldNames.length; i += 1) {
+                if (existingValues[fieldNames[i]] !== (0, setField_1.fieldToString)(params.fields[fieldNames[i]])) {
+                    matches = false;
+                }
+            }
+            return {
+                status: "skipped",
+                table: table,
+                sysId: existingSysId,
+                scope: params.scope,
+                updateSetSysId: params.updateSetSysId,
+                fields: params.fields,
+                after: existingValues,
+                verified: matches,
+                note: matches
+                    ? "skipped: --if-absent matched " + table + "/" + existingSysId
+                        + " and its values already match."
+                    : "skipped: --if-absent matched " + table + "/" + existingSysId
+                        + " but its values differ from the requested fields — use set-field to update it."
+            };
+        }
+    }
+    if (params.dryRun) {
+        return {
+            status: "dry-run",
+            table: table,
+            sysId: "",
+            scope: params.scope,
+            updateSetSysId: params.updateSetSysId,
+            fields: params.fields,
+            after: {},
+            verified: false,
+            note: "dry-run: no write. Would create a " + table + " record with "
+                + JSON.stringify(params.fields) + " in scope " + params.scope
+                + ", captured into update set " + params.updateSetSysId + "."
+        };
+    }
+    // Insert via the scope- and update-set-aware core REST op.
+    var created = await client.claude.createRecord({
+        table: table,
+        fields: params.fields,
+        scope: params.scope,
+        update_set_sys_id: params.updateSetSysId
+    });
+    var sysId = (0, setField_1.fieldToString)(created && created.sys_id);
+    if (!sysId) {
+        return {
+            status: "failed",
+            table: table,
+            sysId: "",
+            scope: params.scope,
+            updateSetSysId: params.updateSetSysId,
+            fields: params.fields,
+            after: {},
+            verified: false,
+            note: "createRecord returned no sys_id — the insert may not have landed; check the instance."
+        };
+    }
+    // Read back and verify each field equals what we sent.
+    var afterRows = await client.table.query(table, "sys_id=" + sysId, {
+        limit: 1,
+        fields: readFields
+    });
+    var after = (0, setField_1.pickFields)(afterRows[0] || {}, fieldNames);
+    var verified = afterRows.length > 0;
+    for (var j = 0; j < fieldNames.length; j += 1) {
+        if (after[fieldNames[j]] !== (0, setField_1.fieldToString)(params.fields[fieldNames[j]])) {
+            verified = false;
+        }
+    }
+    return {
+        status: verified ? "created" : "failed",
+        table: table,
+        sysId: sysId,
+        scope: params.scope,
+        updateSetSysId: params.updateSetSysId,
+        fields: params.fields,
+        after: after,
+        verified: verified,
+        note: verified
+            ? "Created " + table + "/" + sysId + " and verified via read-back."
+            : "Insert landed as " + sysId
+                + " but read-back does not match the requested values — check field types / ACLs."
+    };
+}

package/dist/index.d.ts

@@ -21,3 +21,7 @@ export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFo
 export type { ServiceNowClientConfig, ChoiceValue, ChoiceType, AddChoicesParams, AddChoicesResult, ChoiceActionResult, DictionaryRecord, UpdateSetRecord, LayoutAction, LayoutRecordResult, LayoutResult, CreateViewParams, CreateViewResult, FormSectionSpec, SetFormLayoutParams, SetListLayoutParams, SetRelatedListsParams, ChunkRole, ChunkInfo, ChunkResult, PrunedResult, HostAssetsParams, HostAssetsResult } from "./types";
 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";
+export { setField } from "./setField";
+export { createRecord } from "./createRecord";
+export type { RecordWriteResult, SetFieldParams, SetFieldResult } from "./setField";
+export type { CreateRecordParams, CreateRecordResult } from "./createRecord";

package/dist/index.js

@@ -6,7 +6,7 @@
  * REST API so every change lands in the target update set and scope.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.formatHostAssetsResult = exports.classifyChunks = exports.hostAssets = exports.addChoicesToField = exports.resolveConfigFromEnvFile = exports.createClientFromEnvFile = exports.createClient = void 0;
+exports.createRecord = exports.setField = 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.formatHostAssetsResult = exports.classifyChunks = exports.hostAssets = 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");
@@ -68,3 +68,7 @@ Object.defineProperty(exports, "DEFAULT_SAVE_ACTION", { enumerable: true, get: f
 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; } });
+var setField_1 = require("./setField");
+Object.defineProperty(exports, "setField", { enumerable: true, get: function () { return setField_1.setField; } });
+var createRecord_1 = require("./createRecord");
+Object.defineProperty(exports, "createRecord", { enumerable: true, get: function () { return createRecord_1.createRecord; } });

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", "add_column", "host_assets"];
+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", "set_field", "create_record", "host_assets"];
 export type ToolName = typeof TOOL_NAMES[number];
 export interface RegistryDeps {
     /** Optional client injection for tests; defaults to createClient({}). */

package/dist/mcp/registry.js

@@ -27,6 +27,8 @@ const editFlow_1 = require("../flowDesigner/editFlow");
 const testFlow_1 = require("../flowDesigner/testFlow");
 const table_1 = require("../table");
 const hostAssets_1 = require("../hostAssets");
+const setField_1 = require("../setField");
+const createRecord_1 = require("../createRecord");
 const schemas_1 = require("./schemas");
 exports.TOOL_NAMES = [
     "create_view",
@@ -43,6 +45,8 @@ exports.TOOL_NAMES = [
     "flow_edit",
     "create_table",
     "add_column",
+    "set_field",
+    "create_record",
     "host_assets"
 ];
 // Annotation presets (READ_ONLY / WRITE_ADDITIVE_IDEMPOTENT / WRITE_CREATE /
@@ -296,6 +300,56 @@ function buildDescriptors(deps = {}) {
                 });
             }
         },
+        {
+            name: "set_field",
+            annotations: dovetail_mcp_kit_1.WRITE_OVERWRITE,
+            description: "Set scalar field value(s) on an EXISTING ServiceNow data record, captured into a specified "
+                + "update set, then READ BACK to verify each value landed. Wraps the update-set-aware "
+                + "pushWithUpdateSet core op (no sys_user_preference mutation). Target the record by sysId, or "
+                + "by a query that resolves to EXACTLY one row. REFUSES schema tables (sys_db_object / "
+                + "sys_dictionary) — use add_column / create_table for those. fields is a flat name->string map "
+                + "(sent as strings; ServiceNow coerces); updateSetSysId is required so the change is tracked; "
+                + "dryRun:true reads the current values and returns the plan without writing. To INSERT a new "
+                + "record use create_record.",
+            shape: schemas_1.setFieldSchema.shape,
+            handler: async function (args) {
+                var p = schemas_1.setFieldSchema.parse(args);
+                return (0, setField_1.setField)({
+                    client: client(),
+                    table: p.table,
+                    sysId: p.sysId,
+                    query: p.query,
+                    fields: p.fields,
+                    updateSetSysId: p.updateSetSysId,
+                    dryRun: p.dryRun
+                });
+            }
+        },
+        {
+            name: "create_record",
+            annotations: dovetail_mcp_kit_1.WRITE_CREATE,
+            description: "Create ONE new ServiceNow data record, owned by an explicit app scope and captured into a "
+                + "specified update set, then READ BACK to verify. Wraps the scope- and update-set-aware "
+                + "createRecord core op (switches app scope + update set server-side, inserts, restores both — "
+                + "so the record lands in the right scope without sys_user_preference mutation). REFUSES schema "
+                + "tables (sys_db_object / sys_dictionary) — use create_table / add_column for those. fields is a "
+                + "flat name->string map; scope and updateSetSysId are required; ifAbsentQuery makes re-runs "
+                + "idempotent (skips the insert when it already matches a row); dryRun:true returns the plan "
+                + "without writing. To UPDATE an existing record use set_field.",
+            shape: schemas_1.createRecordSchema.shape,
+            handler: async function (args) {
+                var p = schemas_1.createRecordSchema.parse(args);
+                return (0, createRecord_1.createRecord)({
+                    client: client(),
+                    table: p.table,
+                    fields: p.fields,
+                    scope: p.scope,
+                    updateSetSysId: p.updateSetSysId,
+                    ifAbsentQuery: p.ifAbsentQuery,
+                    dryRun: p.dryRun
+                });
+            }
+        },
         {
             name: "host_assets",
             annotations: dovetail_mcp_kit_1.WRITE_OVERWRITE,

package/dist/mcp/schemas.d.ts

@@ -563,3 +563,47 @@ export declare var addColumnSchema: z.ZodObject<{
     saveActionSysId?: string | undefined;
     columnsRelId?: string | undefined;
 }>;
+export declare var setFieldSchema: z.ZodObject<{
+    table: z.ZodString;
+    sysId: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    updateSetSysId: z.ZodString;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    table: string;
+    fields: Record<string, string>;
+    updateSetSysId: string;
+    query?: string | undefined;
+    sysId?: string | undefined;
+    dryRun?: boolean | undefined;
+}, {
+    table: string;
+    fields: Record<string, string>;
+    updateSetSysId: string;
+    query?: string | undefined;
+    sysId?: string | undefined;
+    dryRun?: boolean | undefined;
+}>;
+export declare var createRecordSchema: z.ZodObject<{
+    table: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    scope: z.ZodString;
+    updateSetSysId: z.ZodString;
+    ifAbsentQuery: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    table: string;
+    fields: Record<string, string>;
+    scope: string;
+    updateSetSysId: string;
+    dryRun?: boolean | undefined;
+    ifAbsentQuery?: string | undefined;
+}, {
+    table: string;
+    fields: Record<string, string>;
+    scope: string;
+    updateSetSysId: string;
+    dryRun?: boolean | undefined;
+    ifAbsentQuery?: 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.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = 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.createRecordSchema = exports.setFieldSchema = exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = 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),
@@ -156,3 +156,23 @@ exports.addColumnSchema = zod_1.z.object({
     dryRun: zod_1.z.boolean().optional(),
     debug: zod_1.z.boolean().optional()
 });
+// Data-record write verbs. Kept as plain z.object (no .refine wrapper) so
+// registry.ts can read `.shape`; the deeper rules — one of sysId/query, at
+// least one field, the schema-table refusal — are enforced by the core
+// setField / createRecord functions, which throw clear errors.
+exports.setFieldSchema = zod_1.z.object({
+    table: zod_1.z.string().min(1),
+    sysId: zod_1.z.string().optional(),
+    query: zod_1.z.string().optional(),
+    fields: zod_1.z.record(zod_1.z.string()),
+    updateSetSysId: zod_1.z.string().min(1),
+    dryRun: zod_1.z.boolean().optional()
+});
+exports.createRecordSchema = zod_1.z.object({
+    table: zod_1.z.string().min(1),
+    fields: zod_1.z.record(zod_1.z.string()),
+    scope: zod_1.z.string().min(1),
+    updateSetSysId: zod_1.z.string().min(1),
+    ifAbsentQuery: zod_1.z.string().optional(),
+    dryRun: zod_1.z.boolean().optional()
+});

package/dist/setField.d.ts

@@ -0,0 +1,50 @@
+/**
+ * dove-sn set-field — set scalar field value(s) on an EXISTING ServiceNow
+ * record, captured into a specified update set, then read back and verify.
+ *
+ * Wraps the Dovetail core Scripted REST `pushWithUpdateSet` op (update-set +
+ * scope switching handled atomically server-side), so the change lands in the
+ * right update set without touching sys_user_preference. This is the
+ * change-and-KEEP counterpart to sn-capture-fields' change-and-revert capture.
+ *
+ * NOT for schema tables (sys_db_object / sys_dictionary) — that's add-column /
+ * create-table. To INSERT a new record, use `dove create`.
+ */
+import type { ServiceNowClient } from "./client";
+export interface SetFieldParams {
+    client?: ServiceNowClient;
+    table: string;
+    /** Target record by sys_id, OR by a query that resolves to EXACTLY one row. */
+    sysId?: string;
+    query?: string;
+    /** Field name -> value to set. Values are sent as strings; ServiceNow coerces. */
+    fields: Record<string, string>;
+    /** Update set to capture the change into. Required for a tracked write. */
+    updateSetSysId?: string;
+    dryRun?: boolean;
+}
+/**
+ * Fields common to every record-write verb's result: the target, the update set
+ * the change was captured into, the requested field map, the read-back values,
+ * whether the read-back matched, and a human note. `set-field` and
+ * `create-record` each extend this with their own `status` union (and
+ * set-field's `before` snapshot / create-record's owning `scope`).
+ */
+export interface RecordWriteResult {
+    table: string;
+    sysId: string;
+    updateSetSysId: string;
+    fields: Record<string, string>;
+    after: Record<string, string>;
+    verified: boolean;
+    note: string;
+}
+export interface SetFieldResult extends RecordWriteResult {
+    status: "dry-run" | "applied" | "failed";
+    before: Record<string, string>;
+}
+/** Coerce a Table-API field value to a comparable string. Reference/display
+ *  fields (sysparm_display_value=false) come back as { link, value } objects. */
+export declare function fieldToString(value: unknown): string;
+export declare function pickFields(row: Record<string, unknown>, names: Array<string>): Record<string, string>;
+export declare function setField(params: SetFieldParams): Promise<SetFieldResult>;

package/dist/setField.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * dove-sn set-field — set scalar field value(s) on an EXISTING ServiceNow
+ * record, captured into a specified update set, then read back and verify.
+ *
+ * Wraps the Dovetail core Scripted REST `pushWithUpdateSet` op (update-set +
+ * scope switching handled atomically server-side), so the change lands in the
+ * right update set without touching sys_user_preference. This is the
+ * change-and-KEEP counterpart to sn-capture-fields' change-and-revert capture.
+ *
+ * NOT for schema tables (sys_db_object / sys_dictionary) — that's add-column /
+ * create-table. To INSERT a new record, use `dove create`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fieldToString = fieldToString;
+exports.pickFields = pickFields;
+exports.setField = setField;
+const client_1 = require("./client");
+// Platform/schema tables that must not be written as data — routed to the
+// dedicated schema verbs instead so we never orphan or corrupt metadata.
+var REFUSED_TABLES = ["sys_db_object", "sys_dictionary"];
+/** Coerce a Table-API field value to a comparable string. Reference/display
+ *  fields (sysparm_display_value=false) come back as { link, value } objects. */
+function fieldToString(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "object") {
+        if ("value" in value && value.value !== undefined && value.value !== null) {
+            return String(value.value);
+        }
+        return "";
+    }
+    return String(value);
+}
+function pickFields(row, names) {
+    var out = {};
+    for (var i = 0; i < names.length; i += 1) {
+        out[names[i]] = fieldToString(row ? row[names[i]] : undefined);
+    }
+    return out;
+}
+async function setField(params) {
+    var client = params.client || (0, client_1.createClient)({});
+    var table = params.table;
+    if (!table) {
+        throw new Error("set-field: --table is required.");
+    }
+    if (REFUSED_TABLES.indexOf(table) !== -1) {
+        throw new Error("set-field: refusing to write " + table + " as data — it is a schema table. "
+            + "Use add-column / create-table for schema changes.");
+    }
+    var fieldNames = params.fields ? Object.keys(params.fields) : [];
+    if (fieldNames.length === 0) {
+        throw new Error("set-field: at least one field (--fields key=value) is required.");
+    }
+    if (!params.updateSetSysId) {
+        throw new Error("set-field: --update-set <sys_id> is required so the change is captured.");
+    }
+    // Resolve the target sys_id (explicit, or a single-match query).
+    var sysId = params.sysId;
+    if (!sysId) {
+        if (!params.query) {
+            throw new Error("set-field: one of --sys-id or --query is required.");
+        }
+        var matches = await client.table.query(table, params.query, { limit: 2, fields: ["sys_id"] });
+        if (matches.length === 0) {
+            throw new Error("set-field: --query matched no rows on " + table + ".");
+        }
+        if (matches.length > 1) {
+            throw new Error("set-field: --query matched 2+ rows on " + table + " — refine to exactly one.");
+        }
+        sysId = fieldToString(matches[0].sys_id);
+    }
+    // Read current values (also confirms the record exists).
+    var readFields = ["sys_id"].concat(fieldNames);
+    var beforeRows = await client.table.query(table, "sys_id=" + sysId, { limit: 1, fields: readFields });
+    if (beforeRows.length === 0) {
+        throw new Error("set-field: no record " + sysId + " found on " + table + ".");
+    }
+    var before = pickFields(beforeRows[0], fieldNames);
+    if (params.dryRun) {
+        return {
+            status: "dry-run",
+            table: table,
+            sysId: sysId,
+            updateSetSysId: params.updateSetSysId,
+            fields: params.fields,
+            before: before,
+            after: before,
+            verified: false,
+            note: "dry-run: no write. Would set " + JSON.stringify(params.fields)
+                + " on " + table + "/" + sysId + " into update set " + params.updateSetSysId + "."
+        };
+    }
+    // Write via the update-set-aware core REST op.
+    await client.claude.pushWithUpdateSet({
+        update_set_sys_id: params.updateSetSysId,
+        table: table,
+        record_sys_id: sysId,
+        fields: params.fields
+    });
+    // Read back and verify each field equals what we set.
+    var afterRows = await client.table.query(table, "sys_id=" + sysId, { limit: 1, fields: readFields });
+    var after = pickFields(afterRows[0] || {}, fieldNames);
+    var verified = true;
+    for (var j = 0; j < fieldNames.length; j += 1) {
+        if (after[fieldNames[j]] !== fieldToString(params.fields[fieldNames[j]])) {
+            verified = false;
+        }
+    }
+    return {
+        status: verified ? "applied" : "failed",
+        table: table,
+        sysId: sysId,
+        updateSetSysId: params.updateSetSysId,
+        fields: params.fields,
+        before: before,
+        after: after,
+        verified: verified,
+        note: verified
+            ? "Set " + fieldNames.join(", ") + " on " + table + "/" + sysId + " and verified via read-back."
+            : "Write landed but read-back does not match the requested values — check field types / ACLs."
+    };
+}

package/package.json

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