@tenonhq/dovetail-servicenow 0.0.47 → 0.0.48

package/README.md

@@ -110,6 +110,19 @@ file — handy for CI.
 
 ## CLI
 
+### Getting help
+
+```bash
+npx dove-sn help                    # verb index
+npx dove-sn help add-choices        # one verb: required/optional flags, value formats, write gate, example
+npx dove-sn add-choices --help      # same — never loads credentials or touches the instance
+```
+
+Every verb's usage is rendered from one table (`src/cliUsage.ts`), so the help
+and the dispatcher cannot drift — a test fails if a verb is missing an entry. A
+`Missing required flags` error prints that verb's usage block under the error
+line; a mistyped verb lists the closest matches and exits 1.
+
 ```bash
 # Inline form
 npx dove-sn add-choices \
@@ -127,8 +140,19 @@ npx dove-sn remove-choices \
   --column state \
   --update-set 0083c3bb33d003507b18bc534d5c7b6d \
   --values "expired,failed"
+
+# Preview either verb — reads happen, NOTHING is written
+npx dove-sn add-choices    --table ... --column ... --update-set ... --choices "..." --dry-run
+npx dove-sn remove-choices --table ... --column ... --update-set ... --values  "..." --dry-run
 ```
 
+`--dry-run` still resolves the field and the update set (so a mistyped column or a
+closed update set fails exactly as it would live), then reports what the live run
+would do without sending a single write. Rows are tagged `[would create]` /
+`[would update]` / `[would deactivate]` — never `[created]` — and the header reads
+`(DRY RUN — nothing written)`. The `--json` result carries `dryRun: true` and the
+same `would-*` action values.
+
 JSON payload shape:
 
 ```json
@@ -154,6 +178,14 @@ place of `choices`.
   left alone — retiring values does not un-make the column a choice field.
 - **Idempotent.** `deactivated` (a live row was flipped) / `unchanged` (already
   inactive) / `missing` (no such value on the field). Re-running writes nothing.
+- **Case-sensitive, with a hint.** `sys_choice.value` is case-sensitive, so
+  `--values DELIVERED` does **not** match a stored `delivered` — it reports
+  `missing`. When the field holds the same spelling in a different case, the row
+  carries `nearMatches` (the stored spelling(s)) and the CLI prints
+  `[missing] DELIVERED — no exact match; did you mean "delivered"? (choice values are case-sensitive)`.
+  Matching is never case-folded: a field holding both `delivered` and
+  `Delivered` treats them as two distinct values, and a request for either one
+  touches only its own row.
 - **Duplicates.** `sys_choice` has no uniqueness constraint on
   `(name, element, value, language)`, so a field can hold several live rows for
   one value. Every live row is deactivated, and `sysIds` lists all of them — a
@@ -181,8 +213,8 @@ var result = await addChoicesToField(client, { /* ... */ });
 
 console.log(result.choices);
 // [
-//   { value: "delivered", label: "Delivered", sysId: "...", action: "created" },
-//   { value: "failed",    label: "Failed",    sysId: "...", action: "created" }
+//   { value: "delivered", label: "Delivered", sysId: "...", sysIds: ["..."], action: "created" },
+//   { value: "failed",    label: "Failed",    sysId: "...", sysIds: ["..."], action: "created" }
 // ]
 
 var removed = await removeChoicesFromField(client, {
@@ -192,8 +224,48 @@ var removed = await removeChoicesFromField(client, {
   values: ["expired"],
 });
 // removed.choices[0] -> { value: "expired", sysId: "...", sysIds: ["..."], action: "deactivated" }
+
+// Plan without writing — identical reads, zero writes, `would-*` actions
+var plan = await addChoicesToField(client, { /* ... */ dryRun: true });
+// plan.dryRun -> true;  plan.choices[0].action -> "would-create" | "would-update" | "unchanged"
+```
+
+### Result shape
+
+Both verbs return the **same `field` envelope**, so one consumer can format either:
+
+```ts
+interface ChoiceFieldRef {
+  table: string;
+  column: string;
+  language: string;        // remove: the language matched; add: the default for choices without one
+  scope: string;           // sys_scope sys_id of the dictionary record
+  dictionarySysId: string;
+}
+
+interface AddChoicesResult {
+  field: ChoiceFieldRef;
+  dictionary: { choiceWas: ChoiceType; choiceNow: ChoiceType };  // add-only transition
+  updateSet: { sysId: string; name: string };
+  dryRun: boolean;
+  choices: Array<ChoiceActionResult>;    // action: created | updated | unchanged | would-create | would-update
+}
+
+interface RemoveChoicesResult {
+  field: ChoiceFieldRef;
+  updateSet: { sysId: string; name: string };
+  dryRun: boolean;
+  choices: Array<ChoiceRemovalResult>;   // action: deactivated | unchanged | missing | would-deactivate
+}                                        // + nearMatches?: string[] on a case-only "missing"
 ```
 
+> **Breaking change (0.0.x).** Earlier releases returned
+> `AddChoicesResult.dictionary: { sysId, scope, choiceWas, choiceNow }` and a
+> `RemoveChoicesResult.field` without `scope`. The dictionary sys_id now lives at
+> `field.dictionarySysId` on both verbs and `scope` at `field.scope`;
+> `dictionary` keeps only the choice-type transition. Consumers reading
+> `result.dictionary.sysId` or `result.dictionary.scope` must move to `result.field`.
+
 Both verbs write one value at a time. If a write fails partway through they
 throw a **`ChoiceWriteError`** carrying `completed` (the values that already
 landed, in result shape), `failedValue` (the one that threw — its state on the
@@ -769,10 +841,70 @@ already matches a row). Exit codes: `0` created / skipped-in-sync / dry-run, `1`
 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:
+#### Field sources (`--fields`, `--from-json`, `--from-stdin`)
+
+Both verbs take their field map from any combination of three sources; on a shared
+key the file / stdin value wins over the inline one.
+
+| Source | Use it for |
+| --- | --- |
+| `--fields "k=v,k2=v2"` | Short scalar values. Splits on commas and trims, so it cannot carry a comma, newline or `=`. |
+| `--from-json <path>` | A flat JSON object `{ "field": "value" }` — any character, any size (script bodies, HTML, JSON blobs). |
+| `--from-stdin` (alias `--from-json -`) | The same JSON object, piped in: `cat fields.json \| npx dove-sn create-record ... --from-stdin`. |
+
+**stdin is read only when you ask for it.** Without `--from-stdin` / `--from-json -`
+no `dove-sn` verb touches stdin at all, so a process launched with an open-but-idle
+stdin pipe (an agent harness running it in the background) returns immediately instead
+of waiting for input that never comes; a missing field source is an immediate usage
+error (exit `1`), never a prompt. `--from-stdin` refuses a terminal stdin and an empty
+stream with an actionable message.
+
+#### Read-back verification and the HTML sanitizer
+
+After the write both verbs re-query the record and compare every requested value to
+what was stored. ServiceNow's HTML sanitizer rewrites characters in `html` /
+`translated_html` / `wiki` fields on save (for example `@` becomes `&#64;`), which used
+to surface as a false **mismatch** on a record that was in fact correct. The compare is
+now strict byte-for-byte first, and only when the **stored** value contains an HTML
+entity reference are both sides entity-decoded and compared again; a match found that
+way is reported as verified with a note naming the normalized field(s). A genuinely
+different value still decodes to something different and still reports `failed`
+(exit `2`), and the failure note names the mismatched field(s).
+
+### Delete a record
+
+Delete **one** existing data record by table + sys_id, with the record read back **before** (so the dry-run shows exactly what would go,
+and a missing record is an error rather than a "successful" delete of nothing) and
+**after** (success is never reported until the record is confirmed gone).
+
+```bash
+# Dry-run (the default) — prints the record snapshot, deletes nothing
+npx dove-sn delete-record \
+  --table x_cadso_core_metric_point_type --sys-id <32-hex sys_id> \
+  --update-set <sys_id>
+
+# Apply — deletes, then reads back and verifies the record is gone
+npx dove-sn delete-record \
+  --table x_cadso_core_metric_point_type --sys-id <32-hex sys_id> \
+  --update-set <sys_id> --apply --json
+```
+
+`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.
+
+All three verbs are exported for programmatic use:
 
 ```ts
-import { createClient, setField, createRecord } from "@tenonhq/dovetail-servicenow";
+import { createClient, setField, createRecord, deleteRecord } from "@tenonhq/dovetail-servicenow";
 
 var client = createClient({});
 var r = await setField({
@@ -1027,8 +1159,13 @@ does not exist) / `index_create` (create an index, composite and non-unique incl
 replaying the platform index-creator form; dry-run by default, idempotent, read back from
 `v_db_index` - and **not** captured in an update set, because a database index is a
 physical per-instance change), 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
+existing record), `create_record` (insert one record) and `delete_record` (delete one
+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
+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
 scripts, step-level inputs/outputs, data-pill wiring — dry-run by default, and the
@@ -1060,6 +1197,10 @@ npx dove-sn mcp           # run the stdio server (wire into .mcp.json)
 
 This server is separate from `@tenonhq/dovetail-mcp` (the read-only cross-system
 aggregator) — `dovetail-servicenow`'s server is the ServiceNow **write** surface.
+`dovetail-mcp` intentionally does **not** get `delete_record` (or any other ServiceNow
+write): record writes — create, set, delete — live on `dove-sn mcp` only, where every
+one takes an update set, previews before writing and is read-back-verified (the delete's
+update set is honoured server-side once #297 ships).
 
 ## Publishing a Custom Action Type
 

package/dist/choices.d.ts

@@ -36,6 +36,11 @@ export declare function encodeQueryValue(v: string): string;
  * Upsert choices for a field and (optionally) toggle sys_dictionary.choice.
  * Idempotent: re-running with the same inputs returns `action: "unchanged"`
  * for every row and skips the dictionary write when no change is required.
+ *
+ * `params.dryRun` plans instead of writing: every read still happens (so a missing field
+ * or a closed update set still fails loudly), but no pushWithUpdateSet / createRecord
+ * call is made, and rows report "would-create" / "would-update" in place of
+ * "created" / "updated". The result's `dryRun` flag is true.
  */
 export declare function addChoicesToField(client: ServiceNowClient, params: AddChoicesParams): Promise<AddChoicesResult>;
 /**
@@ -48,7 +53,13 @@ export declare function addChoicesToField(client: ServiceNowClient, params: AddC
  *   - active value     -> "deactivated" (every live row for it flipped to inactive —
  *                         usually one write, but more when the field holds duplicates)
  *   - already inactive -> "unchanged"  (no write)
- *   - value not found  -> "missing"    (no write)
+ *   - value not found  -> "missing"    (no write; `nearMatches` lists any value on the
+ *                         field that differs by letter case alone — matching is strictly
+ *                         case-sensitive, this is a hint so the caller can tell a typo'd
+ *                         casing from a genuinely absent value)
+ *
+ * `params.dryRun` plans instead of writing: reads still happen, no pushWithUpdateSet is
+ * sent, and a live row reports "would-deactivate" in place of "deactivated".
  *
  * The dictionary row is fetched only to PROVE the field exists — without that guard a
  * mistyped column reports every value as "missing", the silent-failure this family

package/dist/choices.js

@@ -231,6 +231,40 @@ function dedupe(values) {
     });
     return out;
 }
+/**
+ * Values on the field (same language) that differ from `value` by letter case ALONE.
+ *
+ * sys_choice.value is case-sensitive, so "DELIVERED" is NOT "delivered" and the lookup
+ * must not fold case — but the two outcomes "that value is absent" and "that value is
+ * present, spelled with different casing" are otherwise indistinguishable to the caller.
+ * This surfaces the second so it can be reported as a hint next to "missing".
+ *
+ * Best-effort by design: it inspects the rows the scoped read already returned, and
+ * sends no extra request. ServiceNow's `IN` / `=` on string columns are case-insensitive
+ * at the database layer, which is exactly how a differently-cased row comes back for a
+ * `valueIN DELIVERED` query in the first place.
+ *
+ * Distinct values only, in first-seen order; a value that exactly equals `value` is
+ * excluded — that one is a real match and is handled by the caller before this runs.
+ */
+function findCaseOnlyMatches(rows, language, value) {
+    var wanted = value.toLowerCase();
+    var out = [];
+    rows.forEach(function (row) {
+        if ((row.language || "en") !== language)
+            return;
+        if (typeof row.value !== "string")
+            return;
+        if (row.value === value)
+            return;
+        if (row.value.toLowerCase() !== wanted)
+            return;
+        if (out.indexOf(row.value) !== -1)
+            return;
+        out.push(row.value);
+    });
+    return out;
+}
 function buildChoiceFields(table, column, choice, scope) {
     var fields = {
         name: table,
@@ -260,6 +294,11 @@ function isUnchanged(existing, choice) {
  * Upsert choices for a field and (optionally) toggle sys_dictionary.choice.
  * Idempotent: re-running with the same inputs returns `action: "unchanged"`
  * for every row and skips the dictionary write when no change is required.
+ *
+ * `params.dryRun` plans instead of writing: every read still happens (so a missing field
+ * or a closed update set still fails loudly), but no pushWithUpdateSet / createRecord
+ * call is made, and rows report "would-create" / "would-update" in place of
+ * "created" / "updated". The result's `dryRun` flag is true.
  */
 async function addChoicesToField(client, params) {
     if (!params.updateSetSysId) {
@@ -268,6 +307,9 @@ async function addChoicesToField(client, params) {
     if (!params.choices || params.choices.length === 0) {
         throw new Error("choices must be a non-empty array.");
     }
+    // Strict equality on purpose: a truthy-but-not-true value (the string "false" from a
+    // mis-parsed flag, say) must not silently turn a planned run into a live write.
+    var dryRun = params.dryRun === true;
     var dict = await fetchDictionary(client, params.table, params.column);
     var updateSet = await fetchUpdateSet(client, params.updateSetSysId);
     var scopeName = await resolveScopeName(client, dict.sys_scope);
@@ -279,12 +321,14 @@ async function addChoicesToField(client, params) {
     var choiceWas = Number(dict.choice);
     var choiceNow = choiceWas;
     if (params.choiceType !== null && Number(dict.choice) !== targetChoiceType) {
-        await client.claude.pushWithUpdateSet({
-            update_set_sys_id: params.updateSetSysId,
-            table: "sys_dictionary",
-            record_sys_id: dict.sys_id,
-            fields: { choice: String(targetChoiceType) },
-        });
+        if (!dryRun) {
+            await client.claude.pushWithUpdateSet({
+                update_set_sys_id: params.updateSetSysId,
+                table: "sys_dictionary",
+                record_sys_id: dict.sys_id,
+                fields: { choice: String(targetChoiceType) },
+            });
+        }
         choiceNow = targetChoiceType;
     }
     // Collapse repeats on language::value, last spec wins. Without this a value listed
@@ -329,6 +373,16 @@ async function addChoicesToField(client, params) {
             if (choice.sequence != null) {
                 updFields.sequence = String(choice.sequence);
             }
+            if (dryRun) {
+                results.push({
+                    value: choice.value,
+                    label: choice.label,
+                    sysId: matchSysIds[0],
+                    sysIds: matchSysIds,
+                    action: "would-update",
+                });
+                continue;
+            }
             try {
                 for (var s = 0; s < stale.length; s += 1) {
                     await client.claude.pushWithUpdateSet({
@@ -351,6 +405,18 @@ async function addChoicesToField(client, params) {
             });
             continue;
         }
+        if (dryRun) {
+            // No row exists yet, so there is no sys_id to report — "" mirrors the layout
+            // verbs' convention for a create that was only planned.
+            results.push({
+                value: choice.value,
+                label: choice.label,
+                sysId: "",
+                sysIds: [],
+                action: "would-create",
+            });
+            continue;
+        }
         var created;
         try {
             created = await client.claude.createRecord({
@@ -372,13 +438,19 @@ async function addChoicesToField(client, params) {
         });
     }
     return {
-        dictionary: {
-            sysId: dict.sys_id,
+        field: {
+            table: params.table,
+            column: params.column,
+            language: "en",
             scope: dict.sys_scope,
+            dictionarySysId: dict.sys_id,
+        },
+        dictionary: {
             choiceWas: choiceWas,
             choiceNow: choiceNow,
         },
         updateSet: { sysId: updateSet.sys_id, name: updateSet.name },
+        dryRun: dryRun,
         choices: results,
     };
 }
@@ -392,7 +464,13 @@ async function addChoicesToField(client, params) {
  *   - active value     -> "deactivated" (every live row for it flipped to inactive —
  *                         usually one write, but more when the field holds duplicates)
  *   - already inactive -> "unchanged"  (no write)
- *   - value not found  -> "missing"    (no write)
+ *   - value not found  -> "missing"    (no write; `nearMatches` lists any value on the
+ *                         field that differs by letter case alone — matching is strictly
+ *                         case-sensitive, this is a hint so the caller can tell a typo'd
+ *                         casing from a genuinely absent value)
+ *
+ * `params.dryRun` plans instead of writing: reads still happen, no pushWithUpdateSet is
+ * sent, and a live row reports "would-deactivate" in place of "deactivated".
  *
  * The dictionary row is fetched only to PROVE the field exists — without that guard a
  * mistyped column reports every value as "missing", the silent-failure this family
@@ -419,6 +497,8 @@ async function removeChoicesFromField(client, params) {
         throw new Error("values must be a non-empty array.");
     }
     var language = params.language || "en";
+    // Strict equality on purpose — see addChoicesToField.
+    var dryRun = params.dryRun === true;
     // fetchDictionary throws a clear error when the field does not exist; fetchUpdateSet
     // throws unless the set is in progress. Both mirror the add path's guards.
     var dict = await fetchDictionary(client, params.table, params.column);
@@ -435,7 +515,19 @@ async function removeChoicesFromField(client, params) {
         var value = values[i];
         var matches = existingByValue[language + "::" + value] || [];
         if (matches.length === 0) {
-            results.push({ value: value, sysId: "", sysIds: [], action: "missing" });
+            // Exact match first, hint second: nearMatches is only ever computed once the
+            // strict lookup has come up empty, so it can never shadow a real match.
+            var missing = {
+                value: value,
+                sysId: "",
+                sysIds: [],
+                action: "missing",
+            };
+            var near = findCaseOnlyMatches(existing, language, value);
+            if (near.length > 0) {
+                missing.nearMatches = near;
+            }
+            results.push(missing);
             continue;
         }
         var sysIds = matches.map(function (row) {
@@ -455,6 +547,15 @@ async function removeChoicesFromField(client, params) {
             });
             continue;
         }
+        if (dryRun) {
+            results.push({
+                value: value,
+                sysId: sysIds[0],
+                sysIds: sysIds,
+                action: "would-deactivate",
+            });
+            continue;
+        }
         try {
             for (var a = 0; a < active.length; a += 1) {
                 await client.claude.pushWithUpdateSet({
@@ -480,9 +581,11 @@ async function removeChoicesFromField(client, params) {
             table: params.table,
             column: params.column,
             language: language,
+            scope: dict.sys_scope,
             dictionarySysId: dict.sys_id,
         },
         updateSet: { sysId: updateSet.sys_id, name: updateSet.name },
+        dryRun: dryRun,
         choices: results,
     };
 }

package/dist/cli.d.ts

@@ -3,22 +3,30 @@
  * dove-sn — thin CLI adapter for @tenonhq/dovetail-servicenow.
  *
  * Usage:
- *   dove-sn add-choices \
- *     --table x_cadso_core_event \
- *     --column state \
- *     --update-set <sys_id> \
- *     --choices 'delivered=Delivered,failed=Failed,...' \
- *     [--choice-type 3] [--json]
+ *   dove-sn help                 verb index
+ *   dove-sn help <verb>          one verb's flags, value formats, write gate, example
+ *   dove-sn <verb> --help        same — never loads an env file or builds a client
+ *   dove-sn <verb> [flags]
  *
- *   dove-sn add-choices --from-json path/to/choices.json
- *
- * JSON payload shape:
- *   {
- *     "table": "x_cadso_core_event",
- *     "column": "state",
- *     "updateSetSysId": "...",
- *     "choiceType": 3,
- *     "choices": [{ "value": "delivered", "label": "Delivered" }, ...]
- *   }
+ * Every verb's usage is rendered from VERB_USAGE in ./cliUsage — add the entry there
+ * when you add a dispatch site below; cliHelp.test.ts fails on a missing one.
  */
+interface ParsedArgs {
+    command: string;
+    flags: Record<string, string>;
+    /**
+     * Flags that arrived with no value at all (`--label` followed by another flag, or by
+     * nothing). They land in `flags` as the string "true", which is right for a boolean and
+     * a trap for a string: `--label` with a forgotten value would rename a column to "true".
+     * Recorded here so a verb can tell the two apart and refuse.
+     */
+    bare: Record<string, boolean>;
+    /**
+     * Non-flag tokens after the command that no flag consumed as its value —
+     * `dove-sn help add-choices` carries the verb here.
+     */
+    positional: Array<string>;
+}
+export declare function parseArgs(argv: Array<string>): ParsedArgs;
+export declare function main(argv: Array<string>): Promise<number>;
 export {};