@tenonhq/dovetail-servicenow 0.0.51 → 0.0.52

package/README.md

@@ -742,8 +742,16 @@ substring-matched, because `"[owner_id]"` contains `"owner"`. `type` is `access_
 **Uniqueness is not readable.** `v_db_index` has no uniqueness field, so a unique index
 and an ordinary one are indistinguishable in it: `unique` is left **absent** rather than
 guessed, and `uniqueness-enforced` is reported in `unverified` on every result. Only a
-duplicate-insert test proves enforcement. An empty result more likely means the table name
-is wrong than that the table is unindexed - every physical table has a `PRIMARY`.
+duplicate-insert test proves enforcement. An empty result for a table that does not exist
+means the table name is wrong - every physical table has a `PRIMARY`.
+
+**Table-per-hierarchy children list their storage root's indexes.** `v_db_index` lists
+indexes by *physical* table, and a table stored in an ancestor's physical table (anything
+extending `task`, for example) has no rows under its own name. When the table exists but
+has no rows, its `super_class` chain is walked to the first ancestor that has them, and
+that root's indexes are listed - with `storageTable` and the note naming the root.
+`index-create` and `add-index` **refuse** such a child on the live path, naming the root,
+rather than build on it or report a false "NOT created".
 
 ### Create an index (composite and non-unique included)
 
@@ -792,6 +800,15 @@ was a silent no-op for that reason.)
 - **Idempotent.** On the live path `v_db_index` is read first, and an index over *exactly*
   these columns short-circuits to `already-exists` with no pin, no form session and no
   write. Column **order** is part of an index's identity - `[a;b]` is not `[b;a]`.
+- **Table-per-hierarchy children are refused.** A table with no `v_db_index` rows of its
+  own whose ancestor has them is stored in that ancestor's physical table; the run stops
+  before any write and names the root (run against the root if that is what you want).
+- **Identity check (warns, never refuses).** The pin runs through the REST client (an API
+  key when one is configured) but the build is scheduled by the form session (always
+  `SN_USER`), and the build captures into the *form* user's current set. The REST caller's
+  own `sys_user` row is read first; when it is not the form-login user (or cannot be read)
+  the run still goes ahead and every result note carries an `IDENTITY WARNING`. The capture
+  read-back then reports where the row actually landed (`captured` / `captureFoundIn`).
 - **The pin is read back.** The set is pinned with Dovetail's own `changeUpdateSet` and
   `currentUpdateSet` is read; a pin that did not take stops the run before the session
   opens.
@@ -804,7 +821,8 @@ was a silent no-op for that reason.)
   values (EMPTY counts). Then the capture row is looked for in the pinned set:
   `captured:true` only when it was read back; an index that exists but was not captured
   is `created:true, captured:false` with `update-set-capture` in `unverified` - and
-  exit code 2, because it will not travel.
+  exit code 2, because it will not travel. In that case the capture name is searched
+  across every set and the set(s) it actually landed in come back in `captureFoundIn`.
 - **Uniqueness is still never claimed.** `uniqueness-enforced` stays in `unverified` on
   every status.
 
@@ -859,7 +877,8 @@ npx dove-sn create-record \
 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
+via read-back. It also **refuses** `sys_update_set` — the op cannot set an update
+set's application, so create sets with `dove createUpdateSet` instead. `--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
@@ -916,14 +935,19 @@ npx dove-sn delete-record \
 `delete-record` wraps the core `deleteRecord` op. It is **dry-run by default** —
 nothing is deleted without `--apply` (`--dry-run` wins if both are given). `--sys-id`
 must be a 32-character lowercase hex id and `--table` a plain table name; both are
-validated before any network call. `--update-set` is **required** and sent with the
-delete, but **the capture is not pinned yet**: until
-[#297](https://github.com/TenonHQ/Dovetail/issues/297) ships server-side, the op ignores
-`update_set_sys_id` and captures the delete into the session's **current** update set —
-make that the set you want before `--apply`. Every result note repeats this caveat; the
-client keeps sending the field so it takes effect the moment the server honours it. Like its siblings it **refuses** schema tables (`sys_db_object` /
-`sys_dictionary`). Exit codes: `0` deleted / dry-run, `1` bad args or no such record,
-`2` the delete returned but the record is **still present** on read-back.
+validated before any network call. `--update-set` is **required**, must exist and be
+**in progress** (checked on the dry-run too). Until
+[#297](https://github.com/TenonHQ/Dovetail/issues/297) ships server-side the op ignores
+`update_set_sys_id` and captures the delete into the session's **current** update set, so
+the verb pins `--update-set` as current first (refusing, nothing deleted, if the pin does
+not read back) and then reads the DELETE row back from `sys_update_xml`. The result carries
+`captured`, `capturedInto` and `captureState` (`in-set` / `other-set` / `none` /
+`unverified`). Like its siblings it **refuses** schema tables (`sys_db_object` /
+`sys_dictionary`). A failed delete call never skips the read-back. Exit codes: `0` deleted
+and captured in the set, a table that writes no capture at all (`none`, with a note), or a
+dry-run; `1` bad args, no such record, or an unknown/closed update set; `2` the record is
+**still present** on read-back (including a server-refused delete), its state is unknown,
+the pin did not take, or the DELETE landed in a different set / could not be read back.
 
 All three verbs are exported for programmatic use:
 
@@ -941,6 +965,36 @@ var r = await setField({
 console.log(r.status, r.verified); // "applied" true
 ```
 
+### Register UI component events (sync-ux-events)
+
+UI Builder can only map an event a component dispatches when it exists as a
+`sys_ux_event` record **and** is listed in the component macroponent's
+`dispatched_events`. A component deploy does not reliably create either, so
+`sync-ux-events` reads the component's `now-ui.json` and reconciles every
+`components.<tag>.actions[]` entry against the instance.
+
+```bash
+# Dry-run (the default) — per action: ok / create / link / drift / ambiguous, plus orphans
+npx dove-sn sync-ux-events --file path/to/now-ui.json
+
+# Apply — creates the missing events and appends them to dispatched_events
+npx dove-sn sync-ux-events --file path/to/now-ui.json \
+  --component cadso-journey-builder --update-set <sys_id> --apply
+```
+
+The macroponent is the `sys_ux_macroponent` (category `component`) whose
+`root_component` is the `sys_ux_lib_component` with that tag; events are created in
+the macroponent's scope via the scope-aware `createRecord` op and the list edit goes
+through `pushWithUpdateSet`, both captured into `--update-set`. The write is
+**append-only** — existing `dispatched_events` entries are never dropped or reordered —
+and is re-read to verify. Label/description **drift** and **orphans** (linked but no
+longer declared) are reported, never changed; an event name carried by several records
+is **ambiguous** and never written. Event names and tags are charset-validated before
+they reach a query. Re-runs are no-ops. Exit codes: `0` in sync / dry-run / applied and
+verified; `1` bad args or unreadable file; `2` an unresolved or ambiguous
+component/event, or a write that did not verify. MCP: `sync_ux_events` (dry-run unless
+`confirm:true`).
+
 ### Invoke an arbitrary REST operation
 
 Invoke any authenticated ServiceNow REST operation — an application's own
@@ -1198,8 +1252,8 @@ existing record), `create_record` (insert one record) and `delete_record` (delet
 record — dry-run by default, `confirm:true` to apply, `updateSetSysId` required, the
 record read back before AND after so success is only reported once it is confirmed
 gone) — all read-back-verified; `set_field` / `create_record` are captured in the
-update set you pass, while `delete_record` captures into the session's current set
-until [#297](https://github.com/TenonHQ/Dovetail/issues/297) ships — `host_assets` (deploy a built
+update set you pass, while `delete_record` pins the set as current and reads the DELETE
+capture back (`captureState`) until [#297](https://github.com/TenonHQ/Dovetail/issues/297) ships — `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), `action_edit` (structurally edit a published action type — per-step

package/dist/cli.js

@@ -86,6 +86,7 @@ const deleteRecord_1 = require("./deleteRecord");
 const invokeRest_1 = require("./invokeRest");
 const publishApp_1 = require("./publishApp");
 const hostAssets_1 = require("./hostAssets");
+const uxEvents_1 = require("./uxEvents");
 const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
 function parseArgs(argv) {
     // `dove-sn --help` has no verb: a leading flag means an empty command and the
@@ -1572,7 +1573,14 @@ async function runIndexList(flags) {
         process.stdout.write(JSON.stringify(result, null, 2) + "\n");
         return 0;
     }
-    process.stdout.write(result.table + " — " + result.indexes.length + " index(es)\n");
+    process.stdout.write(result.table +
+        " — " +
+        result.indexes.length +
+        " index(es)" +
+        (result.storageTable && result.storageTable !== result.table
+            ? " (stored in " + result.storageTable + "'s physical table — these are its indexes)"
+            : "") +
+        "\n");
     for (var i = 0; i < result.indexes.length; i += 1) {
         var idx = result.indexes[i];
         process.stdout.write("  " +
@@ -2006,18 +2014,76 @@ async function runCreateRecord(flags) {
         return 2;
     return 0;
 }
+/**
+ * dove-sn sync-ux-events:
+ *   --file <path/to/now-ui.json>
+ *   [--component <tag>]
+ *   [--update-set <sys_id>]                      (required with --apply)
+ *   [--apply] [--dry-run] [--json]
+ * DRY-RUN BY DEFAULT. Exit codes: 0 in sync / dry-run / applied+verified, 1 bad args or
+ * unreadable file, 2 unresolved/ambiguous component or event, or an unverified write.
+ */
+async function runSyncUxEvents(flags, bare) {
+    var bareErr = bareStringFlagError("sync-ux-events", bare);
+    if (bareErr) {
+        process.stderr.write(bareErr);
+        return 1;
+    }
+    var file = flags.file;
+    if (!file) {
+        process.stderr.write("sync-ux-events: --file <now-ui.json> is required\n");
+        return 1;
+    }
+    var apply = flags.apply === "true" && flags["dry-run"] !== "true";
+    var nowUi;
+    try {
+        nowUi = JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
+    }
+    catch (err) {
+        process.stderr.write("sync-ux-events: cannot read " + file + ": " + (err instanceof Error ? err.message : String(err)) + "\n");
+        return 1;
+    }
+    var result;
+    try {
+        result = await (0, uxEvents_1.syncUxEvents)({
+            client: (0, client_1.createClient)({}),
+            nowUi: nowUi,
+            component: flags.component,
+            updateSetSysId: flags["update-set"],
+            apply: apply,
+        });
+    }
+    catch (err) {
+        var message = err instanceof Error ? err.message : String(err);
+        if (message.indexOf("ux-events: ") === 0)
+            message = message.slice("ux-events: ".length);
+        process.stderr.write("sync-ux-events: " + message + "\n");
+        return 1;
+    }
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write((0, uxEvents_1.formatUxEventSync)(result) + "\n");
+    }
+    return result.ok ? 0 : 2;
+}
 /**
  * dove-sn delete-record:
  *   --table x_cadso_core_metric_point_type
  *   --sys-id <32-hex sys_id>                     (the record to delete)
- *   --update-set <sys_id>                        (required — the delete is captured here, never the
- *                                                 session default; server honours it once #297 ships)
+ *   --update-set <sys_id>                        (required — must exist and be in progress; pinned as
+ *                                                 the session's current set before the delete, and the
+ *                                                 DELETE capture row is read back from sys_update_xml)
  *   [--apply]                                    (DRY-RUN BY DEFAULT — nothing is deleted without it)
  *   [--dry-run] [--json]                         (--dry-run wins over --apply)
  * Reads the record BEFORE (a missing record is an error, not a no-op delete) and AFTER
  * (success is only reported once the record is confirmed gone).
- * Exit codes: 0 deleted/dry-run, 1 bad args or missing record, 2 delete returned but the
- * record is STILL PRESENT on read-back.
+ * Exit codes: 0 deleted (and captured in the requested set) / dry-run, 1 bad args, missing
+ * record or unknown/closed update set, 2 the record is STILL PRESENT on read-back (including a
+ * delete the server refused with an error), its state is unknown, the update-set pin did not
+ * take (nothing deleted), or it was deleted but the DELETE capture landed in a different set or
+ * could not be read back. A table with no update-set capture at all exits 0 with a note.
  */
 async function runDeleteRecord(flags) {
     var table = flags.table;
@@ -2063,7 +2129,15 @@ async function runDeleteRecord(flags) {
             result.sysId +
             " → update set " +
             result.updateSetSysId +
+            (result.updateSetName ? " (" + result.updateSetName + ")" : "") +
             (result.verified ? " — verified gone" : "") +
+            (result.status === "deleted"
+                ? (result.captureState === "in-set"
+                    ? ", capture verified"
+                    : result.captureState === "none"
+                        ? ", no update-set capture (table not recorded?)"
+                        : ", NOT captured in that set")
+                : "") +
             "\n" +
             result.note +
             "\n");
@@ -2073,6 +2147,12 @@ async function runDeleteRecord(flags) {
     }
     if (result.status === "failed")
         return 2;
+    // Gone but the DELETE landed in ANOTHER set (the requested set would promote without it),
+    // or the capture could not be read back: neither may read as success to a script. A table
+    // that is not recorded in update sets at all ("none") is a plain data delete — exit 0, and
+    // the note says the delete will not travel.
+    if (result.status === "deleted" && (result.captureState === "other-set" || result.captureState === "unverified"))
+        return 2;
     return 0;
 }
 /**
@@ -2704,6 +2784,9 @@ async function dispatch(parsed) {
     if (parsed.command === "create-record") {
         return await runCreateRecord(parsed.flags);
     }
+    if (parsed.command === "sync-ux-events") {
+        return await runSyncUxEvents(parsed.flags, parsed.bare);
+    }
     if (parsed.command === "delete-record") {
         return await runDeleteRecord(parsed.flags);
     }

package/dist/cliUsage.js

@@ -408,7 +408,7 @@ exports.VERB_USAGE = {
             {
                 flag: "update-set",
                 value: "<sys_id>",
-                note: "Sent with the delete; see the #297 note below for where the capture lands today.",
+                note: "Must exist and be in progress (checked on the dry-run too); pinned as current before the delete.",
             },
         ],
         optional: [
@@ -420,10 +420,36 @@ exports.VERB_USAGE = {
         gateNote: "The dry-run prints the record snapshot that would be deleted.",
         example: "dove-sn delete-record --table x_cadso_core_metric_point_type --sys-id <32-hex sys_id> --update-set <sys_id> --apply",
         notes: [
-            "Reads the record BEFORE (a missing record is an error, never a no-op delete) and AFTER (exit 2 if it is still present).",
-            "Until TenonHQ/Dovetail#297 ships server-side the delete op IGNORES --update-set and captures into the session's current update set — make that the set you want before --apply.",
+            "Reads the record BEFORE (a missing record is an error, never a no-op delete) and AFTER (exit 2 if it is still present — including when the server refused the delete with an error).",
+            "Until TenonHQ/Dovetail#297 ships server-side the delete op IGNORES --update-set and captures into the session's current update set — so the verb pins --update-set as current first (refusing, nothing deleted, if the pin does not read back) and reads the DELETE row back from sys_update_xml: exit 2 when it landed in a different set or the read-back failed. A table that writes no update-set capture at all exits 0 with a note (captureState \"none\") — that delete will not travel.",
         ],
     },
+    "sync-ux-events": {
+        summary: "Register a UI component's now-ui.json actions as sys_ux_event records on its macroponent",
+        required: [
+            { flag: "file", value: "<now-ui.json>", note: "Path to the component's now-ui.json; every component with `actions` is synced." },
+        ],
+        optional: [
+            { flag: "component", value: "<tag>", note: "Limit to one component tag, e.g. cadso-journey-builder." },
+            {
+                flag: "update-set",
+                value: "<sys_id>",
+                note: "Required with --apply — the event creates and the macroponent edit are captured here.",
+            },
+            { flag: "apply", note: "Write (without it the run is a dry-run)." },
+            { flag: "dry-run", note: "Force a dry-run even with --apply." },
+            JSON_FLAG,
+        ],
+        gate: "apply",
+        gateNote: "The dry-run prints each action as ok / create / link / drift / ambiguous, plus orphans.",
+        example: "dove-sn sync-ux-events --file path/to/now-ui.json --component cadso-journey-builder --update-set <sys_id> --apply",
+        notes: [
+            "Macroponent = sys_ux_macroponent whose root_component is the sys_ux_lib_component with that tag (category component). Events are created in the macroponent's scope.",
+            "Append-only: missing events are created and their sys_ids appended to dispatched_events; existing entries are never dropped or reordered. Label/description drift and orphaned (linked but undeclared) events are reported, never changed.",
+            "Exit codes: 0 in sync / dry-run / applied and verified, 1 bad args or unreadable file, 2 unresolved or ambiguous component/event, or a write that did not verify.",
+        ],
+        stringFlags: ["file", "component", "update-set"],
+    },
     "host-assets": {
         summary: "Deploy a built dist/ to ServiceNow (carrier sys_ui_script + attachment + m2m)",
         required: [

package/dist/createRecord.d.ts

@@ -9,7 +9,8 @@
  * 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`.
+ * create-table / add-column. NOT for sys_update_set — that's
+ * `dove createUpdateSet`. To UPDATE an existing record, use `set-field`.
  */
 import type { ServiceNowClient } from "./client";
 import type { RecordWriteResult } from "./setField";

package/dist/createRecord.js

@@ -10,7 +10,8 @@
  * 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`.
+ * create-table / add-column. NOT for sys_update_set — that's
+ * `dove createUpdateSet`. To UPDATE an existing record, use `set-field`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRecord = createRecord;
@@ -19,6 +20,11 @@ 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"];
+// The generic createRecord op never sets `application`, so an update set
+// inserted through it lands in the session app while the read-back (name only)
+// still reports success. Update sets go through the scope-correct
+// createUpdateSet op instead.
+var UPDATE_SET_TABLE = "sys_update_set";
 async function createRecord(params) {
     var client = params.client || (0, client_1.createClient)({});
     var table = params.table;
@@ -29,6 +35,11 @@ async function createRecord(params) {
         throw new Error("create-record: refusing to write " + table + " as data — it is a schema table. "
             + "Use add-column / create-table for schema changes.");
     }
+    if (table === UPDATE_SET_TABLE) {
+        throw new Error("create-record: refusing to create a sys_update_set record — the generic createRecord op "
+            + "does not set its application, so the set would land in the session app. "
+            + "Use `dove createUpdateSet --name <name> --scope <scope>` instead.");
+    }
     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.");

package/dist/deleteRecord.d.ts

@@ -7,12 +7,15 @@
  *
  * Wraps the Dovetail core Scripted REST `deleteRecord` op. DRY-RUN BY DEFAULT:
  * without confirm:true nothing is deleted; dryRun:true forces a dry-run even
- * with confirm. updateSetSysId is REQUIRED and sent with the delete, but the
- * capture is NOT pinned yet: until TenonHQ/Dovetail#297 ships server-side the
- * op ignores update_set_sys_id and captures into the session's current update
- * set. Every result note says so, so no caller reads "pinned" into a delete
- * that was not. The client keeps sending the field so it takes effect the
- * moment the server honours it.
+ * with confirm. updateSetSysId is REQUIRED and resolved up front (it must exist
+ * and be in progress — checked on the dry-run too). Until TenonHQ/Dovetail#297
+ * ships the server op ignores update_set_sys_id and captures into the session's
+ * current update set, so the verb does what every other deleteRecord caller does:
+ * it pins the set as current (changeUpdateSet) and reads the pin back, refusing
+ * to delete when it did not take. After the delete it reads the DELETE row back
+ * from sys_update_xml and reports where it actually landed (captured /
+ * capturedInto) — the pin alone is not proof (#297 saw it not stick cross-scope).
+ * The client keeps sending the field so it takes effect once the server honours it.
  *
  * NOT for schema tables (sys_db_object / sys_dictionary) — dropping a table or
  * column is a privileged lifecycle op, not a data delete.
@@ -24,9 +27,9 @@ export interface DeleteRecordParams {
     /** sys_id of the record to delete — 32 lowercase hex characters. */
     sysId: string;
     /**
-     * Update set the delete should be captured into. Required and sent, but honoured only
-     * once TenonHQ/Dovetail#297 ships — until then the capture lands in the session's
-     * current update set (see UPDATE_SET_CAVEAT).
+     * Update set the delete should be captured into. Required; must exist and be in progress.
+     * Pinned as the session's current set before the delete (the server op ignores the field
+     * until TenonHQ/Dovetail#297 ships) and verified via the sys_update_xml capture row.
      */
     updateSetSysId?: string;
     /** The delete gate: the record is only deleted when confirm is exactly true. */
@@ -43,14 +46,34 @@ export interface DeleteRecordResult {
     before: Record<string, string>;
     /** True only when the post-delete read-back confirmed the record is gone. */
     verified: boolean;
+    /** Name of the requested update set, resolved before anything else is done. */
+    updateSetName: string;
+    /**
+     * True only when the DELETE's sys_update_xml capture row was read back IN the requested
+     * update set. A deleted record with captured:false will NOT travel with that set.
+     */
+    captured: boolean;
+    /** The update set the DELETE capture row actually landed in; null when none was found. */
+    capturedInto: {
+        sysId: string;
+        name: string;
+    } | null;
+    /**
+     * Where the DELETE capture stands: "in-set" (captured in the requested set), "other-set"
+     * (captured, but into a different set — the requested set promotes without it),
+     * "none" (no capture row anywhere — the table is likely not recorded in update sets),
+     * "unverified" (the capture read-back failed), or "n/a" (dry-run / nothing deleted).
+     */
+    captureState: "in-set" | "other-set" | "none" | "unverified" | "n/a";
     note: string;
 }
 export declare var TABLE_NAME_PATTERN: RegExp;
 export declare var SYS_ID_PATTERN: RegExp;
 /**
- * Appended to every result note while TenonHQ/Dovetail#297 is open: the server op does not
- * yet honour update_set_sys_id, so the capture lands in the session's current update set.
- * Delete this (and its test) when #297 ships.
+ * Appended to the dry-run and deleted notes while TenonHQ/Dovetail#297 is open: the server op
+ * does not yet honour update_set_sys_id, so the delete is captured into the session's current
+ * update set — which is why the verb pins it first and reads the capture row back. Revisit
+ * (and its test) when #297 ships.
  */
 export declare var UPDATE_SET_CAVEAT: string;
 export declare function validateDeleteTable(table: unknown): string;