@tenonhq/dovetail-servicenow 0.0.22 → 0.0.24

package/dist/cli.js

@@ -79,6 +79,9 @@ 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) {
     var command = argv[0] || "";
@@ -710,6 +713,15 @@ 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" +
         "  test-flow          Validate (default) or run a flow/subflow\n" +
         "                     (--sys-id <sys_id> [--execute --confirm] [--inputs <json>] [--json])\n" +
         "  edit-flow          Patch a flow/subflow (rename, description, step inputs)\n" +
@@ -871,6 +883,153 @@ 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.
+ *   --app <sys_id>          Required. Application record sys_id (m2m `application`).
+ *   --scope <namespace>     Required. Carrier scope, e.g. x_cadso_app_shell.
+ *   --update-set <sys_id>   Optional. Defaults to the scope's current update set.
+ *   --max-bytes <n>         Optional. Per-chunk serve cap (default ~5 MB).
+ *   --allow-oversize        Optional. Warn instead of failing on an oversize chunk.
+ *   --dry-run               Optional. Plan only; no writes/uploads/prunes.
+ *   --json                  Optional. Emit the structured HostAssetsResult.
+ *
+ * Exit codes: 0 done/dry-run, 1 bad args, 2 a write landed but read-back is unverified.
+ */
+async function runHostAssets(flags) {
+    var dir = flags.dir;
+    var app = flags.app;
+    var scope = flags.scope;
+    if (!dir || !app || !scope) {
+        process.stderr.write("host-assets: --dir, --app and --scope are required\n");
+        return 1;
+    }
+    var params = { dir: path.resolve(dir), app: app, scope: scope };
+    var us = flags["update-set"] || flags.updateSetSysId;
+    if (us)
+        params.updateSetSysId = us;
+    if (flags["max-bytes"])
+        params.maxBytes = Number(flags["max-bytes"]);
+    if (flags["allow-oversize"] === "true")
+        params.allowOversize = true;
+    if (flags["dry-run"] === "true")
+        params.dryRun = true;
+    var client = (0, client_1.createClient)({});
+    var result = await (0, hostAssets_1.hostAssets)(client, params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write((0, hostAssets_1.formatHostAssetsResult)(result) + "\n");
+    }
+    var unverified = !result.dryRun && result.chunks.some(function (c) { return !c.verified; });
+    return unverified ? 2 : 0;
+}
 async function main() {
     var parsed = parseArgs(process.argv.slice(2));
     // Load credentials before any command runs. `--env`/`--env-file` (or the
@@ -905,6 +1064,15 @@ 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);
+    }
     if (parsed.command === "test-flow") {
         return await runTestFlow(parsed.flags);
     }

package/dist/client.d.ts

@@ -34,6 +34,15 @@ export interface TableSchema {
     fields: Array<TableSchemaField>;
     primary_key: string;
 }
+/** A sys_attachment row, as returned by the native Attachment API. */
+export interface AttachmentMeta {
+    sys_id: string;
+    file_name: string;
+    content_type: string;
+    /** SHA-256 hex of the file content, computed by ServiceNow. Absent on older instances. */
+    hash?: string;
+    size_bytes?: string;
+}
 export interface ServiceNowClient {
     table: {
         /** GET /api/now/table/<t>?sysparm_query=...&sysparm_limit=N — returns result array. */
@@ -113,5 +122,31 @@ export interface ServiceNowClient {
         /** POST an arbitrary native ServiceNow REST path with a JSON body. See `get`. */
         post: <T = any>(path: string, body: any) => Promise<T>;
     };
+    attachment: {
+        /**
+         * GET /api/now/attachment?sysparm_query=table_name=<t>^table_sys_id=<id> —
+         * list the sys_attachment rows on a record. Read-only.
+         */
+        listFor: (params: {
+            table: string;
+            sysId: string;
+        }) => Promise<Array<AttachmentMeta>>;
+        /**
+         * POST /api/now/attachment/file — upload raw bytes as a sys_attachment on a record.
+         * The Buffer is sent verbatim with `contentType` as the request Content-Type (binary,
+         * not JSON). Reuses the shared auth/retry/throttle transport — not a bespoke HTTP path.
+         */
+        upload: (params: {
+            table: string;
+            sysId: string;
+            fileName: string;
+            contentType: string;
+            data: Buffer;
+        }) => Promise<AttachmentMeta>;
+        /** DELETE /api/now/attachment/<sysId> — remove a single attachment. */
+        remove: (params: {
+            sysId: string;
+        }) => Promise<void>;
+    };
 }
 export declare function createClient(config?: ServiceNowClientConfig): ServiceNowClient;

package/dist/client.js

@@ -316,6 +316,37 @@ function createClient(config = {}) {
             post: function (path, body) {
                 return request({ method: "POST", url: path, data: body }, "now.post(" + path + ")");
             }
+        },
+        attachment: {
+            listFor: async function (params) {
+                var data = await request({
+                    method: "GET",
+                    url: "/api/now/attachment",
+                    params: {
+                        sysparm_query: "table_name=" + params.table + "^table_sys_id=" + params.sysId,
+                        sysparm_fields: "sys_id,file_name,content_type,hash,size_bytes"
+                    }
+                }, "attachment.listFor(" + params.table + ")");
+                return (data && data.result) || [];
+            },
+            upload: async function (params) {
+                var data = await request({
+                    method: "POST",
+                    url: "/api/now/attachment/file",
+                    params: {
+                        table_name: params.table,
+                        table_sys_id: params.sysId,
+                        file_name: params.fileName
+                    },
+                    data: params.data,
+                    // Binary upload: override the client's default application/json.
+                    headers: { "content-type": params.contentType }
+                }, "attachment.upload(" + params.fileName + ")");
+                return (data && data.result) || data;
+            },
+            remove: async function (params) {
+                await request({ method: "DELETE", url: "/api/now/attachment/" + params.sysId }, "attachment.remove(" + params.sysId + ")");
+            }
         }
     };
 }

package/dist/createRecord.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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";
+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 {
+    status: "dry-run" | "created" | "skipped" | "failed";
+    table: string;
+    sysId: string;
+    scope: string;
+    updateSetSysId: string;
+    fields: Record<string, string>;
+    after: Record<string, string>;
+    verified: boolean;
+    note: 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/hostAssets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * hostAssets — deploy a pre-built front-end bundle to ServiceNow.
+ *
+ * For each chunk in a built dist/ (index.html + assets/*.{js,css}) this:
+ *   1. Upserts a carrier sys_ui_script named `app_shell_asset:<vite-relative-path>`.
+ *      The name carries the rotating hash on purpose — the Scripted REST serving
+ *      resource resolves an asset request to its carrier by this exact name, so the
+ *      verb's naming MUST match the path the built index.html references, or the
+ *      asset 404s on serve.
+ *   2. Stores the chunk's bytes as a sys_attachment on that record (the script field
+ *      caps at 65 KB; real chunks are far larger). Identical bytes are detected by
+ *      SHA-256 and left in place.
+ *   3. Wires an x_cadso_app_shell_m2m_app_script row (application, script, chunk_role,
+ *      order) so the app shell loads the chunk.
+ *   4. Prunes carriers + m2m rows for chunks no longer in the build — hashes rotate
+ *      every build, so last build's records would otherwise pile up.
+ *
+ * The sys_ui_script + m2m writes route through the Dovetail Scripted REST API and are
+ * captured in the target update set. Attachments are data, not customizations, so they
+ * are not part of the update set. Re-runnable per build, per instance; idempotent for
+ * an identical dist/.
+ *
+ * The serving layer streams each chunk via GlideSysAttachment.getContentStream(), capped
+ * at ~5 MB (glide.scriptable.excel.max_file_size). A chunk at/over the cap truncates on
+ * serve, so the verb fails fast on an oversize chunk unless allowOversize is set.
+ */
+import type { ServiceNowClient } from "./client";
+import type { ChunkInfo, HostAssetsParams, HostAssetsResult } from "./types";
+/**
+ * Classify build files into ordered ChunkInfo. Pure — no filesystem access — so the
+ * naming + role + order logic is unit-testable in isolation.
+ */
+export declare function classifyChunks(files: Array<{
+    viteRelPath: string;
+    ext: string;
+    isIndexHtml: boolean;
+}>): Array<ChunkInfo>;
+/**
+ * Deploy a built dist/ to ServiceNow as app-shell carrier scripts + attachments + m2m
+ * wiring. Idempotent; re-running an identical dist/ reports every chunk unchanged.
+ */
+export declare function hostAssets(client: ServiceNowClient, params: HostAssetsParams): Promise<HostAssetsResult>;
+/** Human-readable one-line-per-chunk summary for the CLI. */
+export declare function formatHostAssetsResult(r: HostAssetsResult): string;