@tenonhq/dovetail-servicenow 0.0.30 → 0.0.31

package/README.md

@@ -406,6 +406,45 @@ Programmatic: `invokeRest({ method, path, body, confirm })` is exported, and the
 client gained `now.put` / `now.delete` / `now.invoke` (the latter returns
 `{ status, body }` verbatim) alongside the existing `now.get` / `now.post`.
 
+### Publish an app to the Store / application repository
+
+Publish a scoped application to the **ServiceNow Store**, the **company
+application repository**, or both — headlessly, with the publish's progress
+tracker polled to completion.
+
+```bash
+# Dry-run — the DEFAULT: resolves the app, prints the plan, publishes NOTHING
+npx dove-sn publish-app --app x_cadso_filter --version 6.0.20260716 --target both
+
+# Publish for real (store, then repo, same version)
+npx dove-sn publish-app --app x_cadso_filter --version 6.0.20260716 \
+  --target both --dev-notes "July release" --confirm --json
+```
+
+**Store publish is EXTERNALLY VISIBLE on the ServiceNow Store — treat
+`--target store --confirm` as a release.** `publish-app` is dry-run by default:
+without `--confirm` it prints the resolved plan and exits `1` (a deliberate
+refusal). `--target both` runs store then repo sequentially and short-circuits
+if the store leg fails.
+
+The two targets ride different transports:
+
+- **store** replays the `sys_app` form's upload flow (`xmlhttp.do` +
+  `sn_appauthor.ScopedAppUploaderAJAX`) over a form-login session — basic auth
+  alone no-ops there. It needs the Store account credentials in the loaded env
+  file as `SN_STORE_USERNAME` / `SN_STORE_PASSWORD`. The password is **never
+  accepted as a flag** and never appears in output, dry-run previews included.
+- **repo** uses the supported CI/CD REST API (`POST /api/sn_cicd/app_repo/publish`
+  + `GET /api/sn_cicd/progress/{id}`) over basic auth. The API user needs the
+  `sn_cicd` role (or admin).
+
+`--app` accepts a scope name, `sys_app` sys_id, or app name; `--version` must be
+above the currently published version. The result carries the progress-tracker
+id, per-step states ("Packaging application", "Uploading application"), the
+Store `appLink`, and the publish's update-set sys_id where the instance reports
+one. Exit codes: `0` published or dry-run, `1` bad args/unconfirmed, `2`
+failed/timeout. Programmatic: `publishApp({ app, version, target, confirm })`.
+
 `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).
@@ -488,8 +527,10 @@ publish is read back and verified), `flow_publish` (compile a flow/subflow snaps
 publish, grafting a template), `flow_test` (validate or run a flow), and
 `flow_edit` (patch a flow), plus `invoke_rest` (invoke an arbitrary authenticated
 REST operation — Scripted REST included — with GET/POST/PUT/DELETE; dry-run by
-default, response passed through verbatim, bodies never logged). It reads
-ServiceNow credentials from the same env vars as the CLI.
+default, response passed through verbatim, bodies never logged) and `app_publish`
+(publish a scoped app to the ServiceNow Store and/or the application repository;
+dry-run by default, Store credentials env-only — they never transit tool
+arguments). It reads ServiceNow credentials from the same env vars as the CLI.
 
 ```bash
 npx dove-sn mcp --smoke   # list the registered tools and exit

package/dist/cli.js

@@ -83,6 +83,7 @@ const table_1 = require("./table");
 const setField_1 = require("./setField");
 const createRecord_1 = require("./createRecord");
 const invokeRest_1 = require("./invokeRest");
+const publishApp_1 = require("./publishApp");
 const hostAssets_1 = require("./hostAssets");
 const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
 function parseArgs(argv) {
@@ -918,6 +919,15 @@ function printHelp() {
         "                      [--script-input <name>] [--update-set <sys_id>] [--apply] [--json])\n" +
         "  edit-flow          Patch a flow/subflow (rename, description, step inputs)\n" +
         "                     (--sys-id <sys_id> --from-json <ops.json> [--apply] [--update-set <sys_id>] [--scope <sys_id>] [--json])\n" +
+        "  publish-app        Publish a scoped app to the ServiceNow Store and/or the company\n" +
+        "                     application repository, then poll the publish to completion.\n" +
+        "                     STORE PUBLISH IS EXTERNALLY VISIBLE on the ServiceNow Store.\n" +
+        "                     DRY-RUN BY DEFAULT — nothing is published without --confirm\n" +
+        "                     (--app <scope|sys_id|name> --version <v> --target store|repo|both\n" +
+        "                      [--dev-notes <text>] [--store-user <email>] [--timeout-ms <n>]\n" +
+        "                      [--dry-run] [--json] [--confirm])\n" +
+        "                     Store creds: SN_STORE_USERNAME/SN_STORE_PASSWORD in the --env file;\n" +
+        "                     the password is never a flag. Repo publish needs the sn_cicd role.\n" +
         "  mcp                Run the MCP stdio server (--smoke lists tools and exits)\n" +
         "\nGlobal flags:\n" +
         "  --env <path>       Load credentials from a specific .env file (also --env-file,\n" +
@@ -1511,6 +1521,104 @@ async function runInvokeRest(flags) {
     }
     return 0;
 }
+/**
+ * dove-sn publish-app:
+ *   --app <scope|sys_id|name>   Required. The sys_app to publish.
+ *   --version <v>               Required. Version to publish (e.g. 6.0.20260716).
+ *   --target store|repo|both    Required. STORE PUBLISH IS EXTERNALLY VISIBLE.
+ *   [--dev-notes <text>]        Optional developer notes.
+ *   [--store-user <email>]      Store account email (else SN_STORE_USERNAME).
+ *                               The password comes ONLY from SN_STORE_PASSWORD —
+ *                               there is no flag for it, ever.
+ *   [--timeout-ms <n>]          Progress-poll budget (default 120000).
+ *   [--dry-run] [--json] [--confirm]
+ *
+ * DRY-RUN unless --confirm: without it the resolved plan is printed and the
+ * command exits 1 (a deliberate refusal, not success). --target both publishes
+ * store then repo sequentially with the same version and short-circuits if the
+ * store leg fails; --json emits an array of per-target results.
+ * Exit codes: 0 published/dry-run, 1 bad args/unconfirmed, 2 failed/timeout.
+ */
+async function runPublishApp(flags) {
+    var app = flags.app;
+    var version = flags.version;
+    var target = flags.target;
+    if (!app || !version || !target) {
+        process.stderr.write("publish-app: --app, --version and --target store|repo|both are required\n");
+        return 1;
+    }
+    if (target !== "store" && target !== "repo" && target !== "both") {
+        process.stderr.write("publish-app: --target must be store, repo or both (got '" +
+            target +
+            "')\n");
+        return 1;
+    }
+    var targets = target === "both" ? ["store", "repo"] : [target];
+    var dryRun = flags["dry-run"] === "true";
+    var confirmed = flags.confirm === "true";
+    var client = (0, client_1.createClient)({});
+    var results = [];
+    var exitCode = 0;
+    for (var i = 0; i < targets.length; i += 1) {
+        var params = {
+            client: client,
+            app: app,
+            version: version,
+            target: targets[i],
+            confirm: confirmed,
+            dryRun: dryRun,
+        };
+        if (flags["dev-notes"])
+            params.devNotes = flags["dev-notes"];
+        if (flags["store-user"])
+            params.storeUsername = flags["store-user"];
+        if (flags["timeout-ms"]) {
+            // A NaN timeout would make the poll-loop budget check always false —
+            // an infinite loop. Validate here, exit 1 on garbage.
+            var timeoutMs = Number(flags["timeout-ms"]);
+            if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+                process.stderr.write("publish-app: --timeout-ms must be a positive integer (got '" +
+                    flags["timeout-ms"] +
+                    "')\n");
+                return 1;
+            }
+            params.timeoutMs = timeoutMs;
+        }
+        var result = await (0, publishApp_1.publishApp)(params);
+        results.push(result);
+        if (flags.json !== "true") {
+            process.stdout.write("[" +
+                result.status +
+                "] " +
+                result.target +
+                " — " +
+                result.appName +
+                " (" +
+                result.appScope +
+                ") v" +
+                result.version +
+                (result.appLink ? " — " + result.appLink : "") +
+                (result.updateSetSysId
+                    ? " — update set " + result.updateSetSysId
+                    : "") +
+                "\n" +
+                result.note +
+                "\n");
+        }
+        if (result.status === "failed" || result.status === "timeout") {
+            exitCode = 2;
+            break; // Short-circuit: never repo-publish after a failed store leg.
+        }
+    }
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+    }
+    if (exitCode === 0 && !dryRun && !confirmed) {
+        process.stderr.write("publish-app: refusing to publish without --confirm (the plan above is a dry-run).\n");
+        return 1;
+    }
+    return exitCode;
+}
 async function main() {
     var parsed = parseArgs(process.argv.slice(2));
     // Load credentials before any command runs. `--env`/`--env-file` (or the
@@ -1585,6 +1693,9 @@ async function main() {
         await runSetRelatedLists(parsed.flags);
         return 0;
     }
+    if (parsed.command === "publish-app") {
+        return await runPublishApp(parsed.flags);
+    }
     if (parsed.command === "mcp") {
         return await runMcp(parsed.flags);
     }

package/dist/index.d.ts

@@ -27,3 +27,5 @@ export type { RecordWriteResult, SetFieldParams, SetFieldResult, } from "./setFi
 export type { CreateRecordParams, CreateRecordResult } from "./createRecord";
 export { invokeRest, INVOKE_REST_METHODS } from "./invokeRest";
 export type { InvokeRestParams, InvokeRestResult } from "./invokeRest";
+export { publishApp, buildStartFields, parseXmlAnswer, parseProgressTree, classifyProgress, flattenSteps, harvestProgressResults, parseCicdPublishResponse, parseCicdProgress, DEFAULT_PUBLISH_TIMEOUT_MS, PUBLISH_POLL_DELAYS_MS, } from "./publishApp";
+export type { PublishAppParams, PublishAppResult, PublishTarget, PublishStep, ProgressNode, CicdProgress, PublishTransport, } from "./publishApp";

package/dist/index.js

@@ -7,7 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 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.formatStepPill = exports.summarizeSteps = exports.verifySteps = exports.applyStepOps = 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.INVOKE_REST_METHODS = exports.invokeRest = exports.createRecord = exports.setField = exports.toStoredValue = exports.resolveAttributes = exports.setColumn = exports.deriveElement = void 0;
+exports.PUBLISH_POLL_DELAYS_MS = exports.DEFAULT_PUBLISH_TIMEOUT_MS = exports.parseCicdProgress = exports.parseCicdPublishResponse = exports.harvestProgressResults = exports.flattenSteps = exports.classifyProgress = exports.parseProgressTree = exports.parseXmlAnswer = exports.buildStartFields = exports.publishApp = exports.INVOKE_REST_METHODS = exports.invokeRest = exports.createRecord = exports.setField = exports.toStoredValue = exports.resolveAttributes = exports.setColumn = exports.deriveElement = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 var createClientFromEnvFile_1 = require("./createClientFromEnvFile");
@@ -82,3 +82,15 @@ Object.defineProperty(exports, "createRecord", { enumerable: true, get: function
 var invokeRest_1 = require("./invokeRest");
 Object.defineProperty(exports, "invokeRest", { enumerable: true, get: function () { return invokeRest_1.invokeRest; } });
 Object.defineProperty(exports, "INVOKE_REST_METHODS", { enumerable: true, get: function () { return invokeRest_1.INVOKE_REST_METHODS; } });
+var publishApp_1 = require("./publishApp");
+Object.defineProperty(exports, "publishApp", { enumerable: true, get: function () { return publishApp_1.publishApp; } });
+Object.defineProperty(exports, "buildStartFields", { enumerable: true, get: function () { return publishApp_1.buildStartFields; } });
+Object.defineProperty(exports, "parseXmlAnswer", { enumerable: true, get: function () { return publishApp_1.parseXmlAnswer; } });
+Object.defineProperty(exports, "parseProgressTree", { enumerable: true, get: function () { return publishApp_1.parseProgressTree; } });
+Object.defineProperty(exports, "classifyProgress", { enumerable: true, get: function () { return publishApp_1.classifyProgress; } });
+Object.defineProperty(exports, "flattenSteps", { enumerable: true, get: function () { return publishApp_1.flattenSteps; } });
+Object.defineProperty(exports, "harvestProgressResults", { enumerable: true, get: function () { return publishApp_1.harvestProgressResults; } });
+Object.defineProperty(exports, "parseCicdPublishResponse", { enumerable: true, get: function () { return publishApp_1.parseCicdPublishResponse; } });
+Object.defineProperty(exports, "parseCicdProgress", { enumerable: true, get: function () { return publishApp_1.parseCicdProgress; } });
+Object.defineProperty(exports, "DEFAULT_PUBLISH_TIMEOUT_MS", { enumerable: true, get: function () { return publishApp_1.DEFAULT_PUBLISH_TIMEOUT_MS; } });
+Object.defineProperty(exports, "PUBLISH_POLL_DELAYS_MS", { enumerable: true, get: function () { return publishApp_1.PUBLISH_POLL_DELAYS_MS; } });

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

package/dist/mcp/registry.js

@@ -31,6 +31,7 @@ const hostAssets_1 = require("../hostAssets");
 const setField_1 = require("../setField");
 const createRecord_1 = require("../createRecord");
 const invokeRest_1 = require("../invokeRest");
+const publishApp_1 = require("../publishApp");
 const schemas_1 = require("./schemas");
 exports.TOOL_NAMES = [
     "create_view",
@@ -53,6 +54,7 @@ exports.TOOL_NAMES = [
     "create_record",
     "host_assets",
     "invoke_rest",
+    "app_publish",
 ];
 // Annotation presets (READ_ONLY / WRITE_ADDITIVE_IDEMPOTENT / WRITE_CREATE /
 // WRITE_OVERWRITE / WRITE_EXECUTE) come from @tenonhq/dovetail-mcp-kit.
@@ -491,6 +493,39 @@ function buildDescriptors(deps = {}) {
                 return (0, invokeRest_1.invokeRest)(params);
             },
         },
+        {
+            name: "app_publish",
+            annotations: dovetail_mcp_kit_1.WRITE_EXECUTE,
+            description: "Publish a scoped ServiceNow application to ONE target per call — the ServiceNow Store " +
+                "(target 'store') or the company Application Repository (target 'repo'); call twice to " +
+                "publish to both — then poll the publish to completion. STORE PUBLISH IS EXTERNALLY " +
+                "VISIBLE on the ServiceNow Store — treat it as a release. DRY-RUN BY DEFAULT: without " +
+                "confirm:true the resolved plan (app, current version, target) is returned and nothing is " +
+                "published. target 'store' replays the sys_app form's upload flow over a form-login session " +
+                "and requires SN_STORE_USERNAME/SN_STORE_PASSWORD in the server's env file — credentials " +
+                "never transit tool arguments. target 'repo' uses the supported CI/CD REST API " +
+                "(/api/sn_cicd/app_repo/publish) and requires the sn_cicd role. app is a scope name, " +
+                "sys_app sys_id, or app name; version must be above the currently published version. The " +
+                "result carries the progress-tracker id, per-step states, the Store appLink, and the " +
+                "publish's update-set sys_id where the instance reports one.",
+            shape: schemas_1.publishAppSchema.shape,
+            handler: async function (args) {
+                var p = schemas_1.publishAppSchema.parse(args);
+                var params = {
+                    app: p.app,
+                    version: p.version,
+                    target: p.target,
+                    devNotes: p.devNotes,
+                    confirm: p.confirm,
+                    dryRun: p.dryRun,
+                    timeoutMs: p.timeoutMs,
+                };
+                if (deps.client) {
+                    params.client = deps.client;
+                }
+                return (0, publishApp_1.publishApp)(params);
+            },
+        },
     ];
 }
 function registerAllTools(server, deps = {}) {

package/dist/mcp/schemas.d.ts

@@ -958,6 +958,31 @@ export declare var createRecordSchema: z.ZodObject<{
     dryRun?: boolean | undefined;
     ifAbsentQuery?: string | undefined;
 }>;
+export declare var publishAppSchema: z.ZodObject<{
+    app: z.ZodString;
+    version: z.ZodString;
+    devNotes: z.ZodOptional<z.ZodString>;
+    target: z.ZodUnion<[z.ZodLiteral<"store">, z.ZodLiteral<"repo">]>;
+    confirm: z.ZodOptional<z.ZodBoolean>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    target: "store" | "repo";
+    version: string;
+    app: string;
+    confirm?: boolean | undefined;
+    dryRun?: boolean | undefined;
+    devNotes?: string | undefined;
+    timeoutMs?: number | undefined;
+}, {
+    target: "store" | "repo";
+    version: string;
+    app: string;
+    confirm?: boolean | undefined;
+    dryRun?: boolean | undefined;
+    devNotes?: string | undefined;
+    timeoutMs?: number | undefined;
+}>;
 export declare var invokeRestSchema: z.ZodObject<{
     method: z.ZodEffects<z.ZodEnum<["GET", "POST", "PUT", "DELETE"]>, "GET" | "DELETE" | "POST" | "PUT", unknown>;
     path: z.ZodString;

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.invokeRestSchema = exports.createRecordSchema = exports.setFieldSchema = exports.setColumnSchema = exports.columnAttributesSchema = exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = exports.editFlowSchema = exports.editActionSchema = 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.invokeRestSchema = exports.publishAppSchema = exports.createRecordSchema = exports.setFieldSchema = exports.setColumnSchema = exports.columnAttributesSchema = exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = exports.editFlowSchema = exports.editActionSchema = 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),
@@ -261,6 +261,19 @@ exports.createRecordSchema = zod_1.z.object({
     ifAbsentQuery: zod_1.z.string().optional(),
     dryRun: zod_1.z.boolean().optional(),
 });
+// app_publish: publish a scoped app to the ServiceNow Store or the company
+// application repository. Deliberately NO credential fields — the Store
+// account resolves from SN_STORE_USERNAME/SN_STORE_PASSWORD inside the verb,
+// so credentials never transit MCP arguments or telemetry.
+exports.publishAppSchema = zod_1.z.object({
+    app: zod_1.z.string().min(1),
+    version: zod_1.z.string().min(1),
+    devNotes: zod_1.z.string().optional(),
+    target: zod_1.z.union([zod_1.z.literal("store"), zod_1.z.literal("repo")]),
+    confirm: zod_1.z.boolean().optional(),
+    dryRun: zod_1.z.boolean().optional(),
+    timeoutMs: zod_1.z.number().int().positive().optional(),
+});
 // invoke_rest: transport primitive for arbitrary authenticated REST operations
 // (Scripted REST included). The dry-run-unless-confirm gate lives in invokeRest
 // itself; the regex here rejects absolute URLs and non-/api/ paths early.

package/dist/publishApp.d.ts

@@ -0,0 +1,173 @@
+/**
+ * dove-sn publish-app — publish a scoped application to the ServiceNow Store
+ * and/or the company Application Repository, headlessly, then poll the
+ * publish's progress tracker until it terminates.
+ *
+ * Two engines, one result shape:
+ *
+ *   STORE  — replays the sys_app form's "Publish to ServiceNow Store" flow
+ *            (ground truth: HAR capture, 2026-07-16): a form-login session
+ *            POSTs /xmlhttp.do with sysparm_processor=
+ *            sn_appauthor.ScopedAppUploaderAJAX & sysparm_name=start (plus the
+ *            Store account credentials), then polls AJAXProgressStatusChecker/
+ *            getStatus with the returned execution sys_id. Basic auth alone
+ *            NO-OPS on xmlhttp.do — the form session + X-UserToken is required
+ *            (proven by the sn-undo-default-push headless revert).
+ *
+ *   REPO   — uses the supported CI/CD REST API: POST /api/sn_cicd/app_repo/publish
+ *            (basic auth via the shared client), then polls
+ *            GET /api/sn_cicd/progress/{id}. Requires the sn_cicd role (or admin).
+ *
+ * STORE PUBLISH IS EXTERNALLY VISIBLE on the ServiceNow Store — the verb
+ * refuses to run either engine without confirm:true (dry-run is the default).
+ *
+ * Store account credentials resolve ONLY inside this module, from
+ * SN_STORE_USERNAME / SN_STORE_PASSWORD (or injected params for tests). The
+ * password is never logged, never echoed into notes or dry-run previews, and
+ * never accepted as a CLI flag.
+ */
+import type { ServiceNowClient } from "./client";
+import type { FormAuth, FormSession, PostResult } from "./table";
+export type PublishTarget = "store" | "repo";
+export interface PublishTransport {
+    openSession?: (auth: FormAuth) => Promise<FormSession>;
+    post?: (auth: FormAuth, session: FormSession, path: string, fields: Record<string, string>) => Promise<PostResult>;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface PublishAppParams {
+    /** Injectable for tests; defaults to createClient({}). */
+    client?: ServiceNowClient;
+    /** App selector: scope name (x_cadso_*), sys_app sys_id, or app name. */
+    app: string;
+    /** Version to publish, e.g. 6.0.20260716. Required — callers derive defaults. */
+    version: string;
+    devNotes?: string;
+    /** One target per call — "both" is CLI-level sequencing. */
+    target: PublishTarget;
+    /** Store account email; falls back to SN_STORE_USERNAME (store target only). */
+    storeUsername?: string;
+    /** Test seam only — the CLI never passes this; env SN_STORE_PASSWORD is the real source. */
+    storePassword?: string;
+    instance?: string;
+    user?: string;
+    password?: string;
+    /** The live gate: without confirm:true the result is a dry-run plan. */
+    confirm?: boolean;
+    dryRun?: boolean;
+    timeoutMs?: number;
+    /** Test seam — defaults to the real formSession functions + setTimeout sleep. */
+    transport?: PublishTransport;
+}
+export interface PublishStep {
+    name: string;
+    state: string;
+    percentComplete: string;
+    message: string;
+}
+/** The AJAXProgressStatusChecker getStatus answer, decoded. state "2" = success. */
+export interface ProgressNode {
+    state: string;
+    percent_complete?: string;
+    message?: string;
+    name?: string;
+    result?: Record<string, string> | null;
+    children?: Array<ProgressNode>;
+}
+export interface PublishAppResult {
+    status: "dry-run" | "published" | "failed" | "timeout";
+    target: PublishTarget;
+    appSysId: string;
+    appScope: string;
+    appName: string;
+    /** sys_app.version at plan time (before the publish). */
+    versionBefore: string;
+    /** The version that was (or would be) published. */
+    version: string;
+    /** Store: the progress-tracker sys_id. Repo: the CI/CD progress id. */
+    executionSysId: string;
+    /** Store leg only — root result["sys_update_set.sys_id"]; "" when absent. */
+    updateSetSysId: string;
+    /** Store: tpp.servicenow.com editapplication URL. Repo: "". */
+    appLink: string;
+    steps: Array<PublishStep>;
+    polls: number;
+    /** Root progress message (failure diagnostics live here). */
+    message: string;
+    /** Dry-run only — the request that would be sent, credentials MASKED. */
+    requestPreview?: Record<string, string>;
+    note: string;
+}
+export declare var DEFAULT_PUBLISH_TIMEOUT_MS: number;
+/** Repeat the LAST delay until the budget is spent — a publish can outrun 15s. */
+export declare var PUBLISH_POLL_DELAYS_MS: ReadonlyArray<number>;
+/**
+ * Build the exact ScopedAppUploaderAJAX start-call field map the browser sends
+ * (HAR ground truth). The repo variant is kept for parity/fixtures even though
+ * the repo leg ships on the CI/CD API: publish_to_store=false, empty username,
+ * and NO sysparm_password key at all.
+ */
+export declare function buildStartFields(p: {
+    appSysId: string;
+    version: string;
+    devNotes: string;
+    target: PublishTarget;
+    storeUsername: string;
+    storePassword: string;
+}): Record<string, string>;
+/**
+ * Extract the `answer` attribute from an xmlhttp.do response envelope
+ * (`<xml answer="..." .../>`) and entity-decode it. A missing/empty answer is
+ * returned as an error, never thrown — callers fold it into a failed result.
+ */
+export declare function parseXmlAnswer(xml: string): {
+    answer: string;
+    error: string;
+};
+/**
+ * Parse a decoded getStatus answer (a JSON progress tree). Throws a clear
+ * error on malformed JSON or an unexpected shape — the poll loop surfaces it
+ * as a failed result rather than a raw stack.
+ */
+export declare function parseProgressTree(decodedAnswer: string): ProgressNode;
+/**
+ * Terminal-state classification for the AJAX progress tracker.
+ * "2" = Succeeded (HAR ground truth). "3"/"4" = Failed/Cancelled per the
+ * GlideExecutionTracker state model. Anything else keeps polling until the
+ * timeout budget — conservative on purpose: an unknown state must not be
+ * reported as success OR failure.
+ */
+export declare function classifyProgress(root: ProgressNode): {
+    terminal: boolean;
+    success: boolean;
+};
+/** Flatten the progress tree's children into an ordered step list. */
+export declare function flattenSteps(root: ProgressNode): Array<PublishStep>;
+/**
+ * Harvest the interesting result values from the progress tree, walking
+ * root-down: the FIRST non-empty appLink/appName/update-set sys_id encountered
+ * wins and is never overwritten. In the observed HAR trees each value appears
+ * on exactly one node, so first-wins is equivalent — the rule just needs to be
+ * deterministic.
+ */
+export declare function harvestProgressResults(root: ProgressNode): {
+    appLink: string;
+    appName: string;
+    updateSetSysId: string;
+};
+/** CI/CD publish response: harvest the progress id (and echo status_label). */
+export declare function parseCicdPublishResponse(body: unknown): {
+    progressId: string;
+    statusLabel: string;
+    error: string;
+};
+export interface CicdProgress {
+    /** "0" pending, "1" running, "2" successful, "3" failed, "4" cancelled. */
+    status: string;
+    statusLabel: string;
+    statusMessage: string;
+    statusDetail: string;
+    percentComplete: string;
+}
+/** CI/CD progress response → a typed snapshot. Unknown shapes become status "". */
+export declare function parseCicdProgress(body: unknown): CicdProgress;
+export declare function publishApp(params: PublishAppParams): Promise<PublishAppResult>;

package/dist/publishApp.js

@@ -0,0 +1,664 @@
+"use strict";
+/**
+ * dove-sn publish-app — publish a scoped application to the ServiceNow Store
+ * and/or the company Application Repository, headlessly, then poll the
+ * publish's progress tracker until it terminates.
+ *
+ * Two engines, one result shape:
+ *
+ *   STORE  — replays the sys_app form's "Publish to ServiceNow Store" flow
+ *            (ground truth: HAR capture, 2026-07-16): a form-login session
+ *            POSTs /xmlhttp.do with sysparm_processor=
+ *            sn_appauthor.ScopedAppUploaderAJAX & sysparm_name=start (plus the
+ *            Store account credentials), then polls AJAXProgressStatusChecker/
+ *            getStatus with the returned execution sys_id. Basic auth alone
+ *            NO-OPS on xmlhttp.do — the form session + X-UserToken is required
+ *            (proven by the sn-undo-default-push headless revert).
+ *
+ *   REPO   — uses the supported CI/CD REST API: POST /api/sn_cicd/app_repo/publish
+ *            (basic auth via the shared client), then polls
+ *            GET /api/sn_cicd/progress/{id}. Requires the sn_cicd role (or admin).
+ *
+ * STORE PUBLISH IS EXTERNALLY VISIBLE on the ServiceNow Store — the verb
+ * refuses to run either engine without confirm:true (dry-run is the default).
+ *
+ * Store account credentials resolve ONLY inside this module, from
+ * SN_STORE_USERNAME / SN_STORE_PASSWORD (or injected params for tests). The
+ * password is never logged, never echoed into notes or dry-run previews, and
+ * never accepted as a CLI flag.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUBLISH_POLL_DELAYS_MS = exports.DEFAULT_PUBLISH_TIMEOUT_MS = void 0;
+exports.buildStartFields = buildStartFields;
+exports.parseXmlAnswer = parseXmlAnswer;
+exports.parseProgressTree = parseProgressTree;
+exports.classifyProgress = classifyProgress;
+exports.flattenSteps = flattenSteps;
+exports.harvestProgressResults = harvestProgressResults;
+exports.parseCicdPublishResponse = parseCicdPublishResponse;
+exports.parseCicdProgress = parseCicdProgress;
+exports.publishApp = publishApp;
+const client_1 = require("./client");
+const table_1 = require("./table");
+exports.DEFAULT_PUBLISH_TIMEOUT_MS = 120000;
+/** Repeat the LAST delay until the budget is spent — a publish can outrun 15s. */
+exports.PUBLISH_POLL_DELAYS_MS = [
+    1000, 1000, 2000, 2000, 5000,
+];
+var SYS_ID_RE = /^[0-9a-f]{32}$/;
+var MASK = "***";
+/**
+ * Build the exact ScopedAppUploaderAJAX start-call field map the browser sends
+ * (HAR ground truth). The repo variant is kept for parity/fixtures even though
+ * the repo leg ships on the CI/CD API: publish_to_store=false, empty username,
+ * and NO sysparm_password key at all.
+ */
+function buildStartFields(p) {
+    var fields = {
+        sysparm_processor: "sn_appauthor.ScopedAppUploaderAJAX",
+        sysparm_name: "start",
+        sysparm_scope: "global",
+        sysparm_want_session_messages: "true",
+        sysparm_sys_id: p.appSysId,
+        // The UI sends a single space when the notes box is empty — mirror it.
+        sysparm_dev_notes: p.devNotes || " ",
+        sysparm_version: p.version,
+        sysparm_target_upload_URL: "",
+        sysparm_is_customization: "",
+        "ni.nolog.x_referer": "ignore",
+        x_referer: "sys_app.do?sys_id=" + p.appSysId,
+    };
+    if (p.target === "store") {
+        fields.sysparm_publish_to_store = "true";
+        fields.sysparm_username = p.storeUsername;
+        fields.sysparm_password = p.storePassword;
+    }
+    else {
+        fields.sysparm_publish_to_store = "false";
+        fields.sysparm_username = "";
+    }
+    return fields;
+}
+/**
+ * Extract the `answer` attribute from an xmlhttp.do response envelope
+ * (`<xml answer="..." .../>`) and entity-decode it. A missing/empty answer is
+ * returned as an error, never thrown — callers fold it into a failed result.
+ */
+function parseXmlAnswer(xml) {
+    if (typeof xml !== "string" || xml.length === 0) {
+        return { answer: "", error: "empty xmlhttp.do response body" };
+    }
+    var m = /\banswer\s*=\s*"([^"]*)"/.exec(xml);
+    if (!m) {
+        return {
+            answer: "",
+            error: "no answer attribute in xmlhttp.do response: " + xml.slice(0, 200),
+        };
+    }
+    return { answer: (0, table_1.decodeHtmlEntities)(m[1]), error: "" };
+}
+function isProgressNode(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.state === "string");
+}
+/**
+ * Parse a decoded getStatus answer (a JSON progress tree). Throws a clear
+ * error on malformed JSON or an unexpected shape — the poll loop surfaces it
+ * as a failed result rather than a raw stack.
+ */
+function parseProgressTree(decodedAnswer) {
+    var parsed;
+    try {
+        parsed = JSON.parse(decodedAnswer);
+    }
+    catch (e) {
+        throw new Error("publish-app: getStatus answer is not valid JSON: " +
+            decodedAnswer.slice(0, 200));
+    }
+    if (!isProgressNode(parsed)) {
+        throw new Error("publish-app: getStatus answer is not a progress tree (no state field): " +
+            decodedAnswer.slice(0, 200));
+    }
+    return parsed;
+}
+/**
+ * Terminal-state classification for the AJAX progress tracker.
+ * "2" = Succeeded (HAR ground truth). "3"/"4" = Failed/Cancelled per the
+ * GlideExecutionTracker state model. Anything else keeps polling until the
+ * timeout budget — conservative on purpose: an unknown state must not be
+ * reported as success OR failure.
+ */
+function classifyProgress(root) {
+    if (root.state === "2")
+        return { terminal: true, success: true };
+    if (root.state === "3" || root.state === "4") {
+        return { terminal: true, success: false };
+    }
+    return { terminal: false, success: false };
+}
+/** Flatten the progress tree's children into an ordered step list. */
+function flattenSteps(root) {
+    var out = [];
+    function walk(node) {
+        if (node !== root && node.name) {
+            out.push({
+                name: node.name,
+                state: node.state,
+                percentComplete: node.percent_complete || "",
+                message: node.message || "",
+            });
+        }
+        var children = node.children;
+        if (Array.isArray(children)) {
+            for (var i = 0; i < children.length; i += 1) {
+                if (isProgressNode(children[i]))
+                    walk(children[i]);
+            }
+        }
+    }
+    walk(root);
+    return out;
+}
+/**
+ * Harvest the interesting result values from the progress tree, walking
+ * root-down: the FIRST non-empty appLink/appName/update-set sys_id encountered
+ * wins and is never overwritten. In the observed HAR trees each value appears
+ * on exactly one node, so first-wins is equivalent — the rule just needs to be
+ * deterministic.
+ */
+function harvestProgressResults(root) {
+    var appLink = "";
+    var appName = "";
+    var updateSetSysId = "";
+    function walk(node) {
+        var result = node.result;
+        if (result && typeof result === "object") {
+            if (typeof result.appLink === "string" && result.appLink && !appLink) {
+                appLink = result.appLink;
+            }
+            if (typeof result.appName === "string" && result.appName && !appName) {
+                appName = result.appName;
+            }
+            var us = result["sys_update_set.sys_id"];
+            if (typeof us === "string" && us && !updateSetSysId) {
+                updateSetSysId = us;
+            }
+        }
+        var children = node.children;
+        if (Array.isArray(children)) {
+            for (var i = 0; i < children.length; i += 1) {
+                if (isProgressNode(children[i]))
+                    walk(children[i]);
+            }
+        }
+    }
+    walk(root);
+    return { appLink: appLink, appName: appName, updateSetSysId: updateSetSysId };
+}
+/** CI/CD publish response: harvest the progress id (and echo status_label). */
+function parseCicdPublishResponse(body) {
+    if (typeof body !== "object" || body === null) {
+        return { progressId: "", statusLabel: "", error: "empty CI/CD response" };
+    }
+    var result = body.result;
+    if (typeof result !== "object" || result === null) {
+        return {
+            progressId: "",
+            statusLabel: "",
+            error: "CI/CD response has no result object",
+        };
+    }
+    var r = result;
+    var id = "";
+    if (r.links &&
+        typeof r.links === "object" &&
+        r.links.progress &&
+        typeof r.links.progress === "object" &&
+        typeof r.links.progress.id === "string") {
+        id = r.links.progress.id;
+    }
+    var label = typeof r.status_label === "string" ? r.status_label : "";
+    if (!id) {
+        return {
+            progressId: "",
+            statusLabel: label,
+            error: "CI/CD response carries no progress id",
+        };
+    }
+    return { progressId: id, statusLabel: label, error: "" };
+}
+/** CI/CD progress response → a typed snapshot. Unknown shapes become status "". */
+function parseCicdProgress(body) {
+    var empty = {
+        status: "",
+        statusLabel: "",
+        statusMessage: "",
+        statusDetail: "",
+        percentComplete: "",
+    };
+    if (typeof body !== "object" || body === null)
+        return empty;
+    var result = body.result;
+    if (typeof result !== "object" || result === null)
+        return empty;
+    var r = result;
+    function str(v) {
+        if (typeof v === "string")
+            return v;
+        if (typeof v === "number")
+            return String(v);
+        return "";
+    }
+    return {
+        status: str(r.status),
+        statusLabel: str(r.status_label),
+        statusMessage: str(r.status_message),
+        statusDetail: str(r.status_detail),
+        percentComplete: str(r.percent_complete),
+    };
+}
+function realSleep(ms) {
+    return new Promise(function (resolve) {
+        setTimeout(resolve, ms);
+    });
+}
+async function resolveApp(client, selector) {
+    var fields = ["sys_id", "scope", "name", "version"];
+    var queries = [];
+    if (SYS_ID_RE.test(selector)) {
+        queries.push("sys_id=" + selector);
+    }
+    else {
+        queries.push("scope=" + selector);
+        queries.push("name=" + selector);
+    }
+    for (var i = 0; i < queries.length; i += 1) {
+        var rows = await client.table.query("sys_app", queries[i], { limit: 2, fields: fields });
+        if (rows.length === 1) {
+            return {
+                sysId: rows[0].sys_id || "",
+                scope: rows[0].scope || "",
+                name: rows[0].name || "",
+                version: rows[0].version || "",
+            };
+        }
+        if (rows.length > 1) {
+            throw new Error("publish-app: app selector '" +
+                selector +
+                "' matches more than one sys_app row — use the scope or sys_id.");
+        }
+    }
+    throw new Error("publish-app: no sys_app row matches '" +
+        selector +
+        "' (tried " +
+        queries.join(", then ") +
+        ").");
+}
+function baseResult(target, app, version) {
+    return {
+        status: "failed",
+        target: target,
+        appSysId: app.sysId,
+        appScope: app.scope,
+        appName: app.name,
+        versionBefore: app.version,
+        version: version,
+        executionSysId: "",
+        updateSetSysId: "",
+        appLink: "",
+        steps: [],
+        polls: 0,
+        message: "",
+        note: "",
+    };
+}
+function resolveStoreCreds(params) {
+    var username = params.storeUsername || process.env.SN_STORE_USERNAME || "";
+    var password = params.storePassword || process.env.SN_STORE_PASSWORD || "";
+    if (!username || !password) {
+        throw new Error("publish-app: Store credentials missing — set SN_STORE_USERNAME and " +
+            "SN_STORE_PASSWORD in the env file the verb loads (--env). The " +
+            "password is never accepted as a flag.");
+    }
+    return { username: username, password: password };
+}
+async function publishToStore(params, app) {
+    var result = baseResult("store", app, params.version);
+    var creds = resolveStoreCreds(params);
+    var transport = params.transport || {};
+    var openSession = transport.openSession || table_1.openFormSession;
+    var post = transport.post || table_1.postForm;
+    var sleepFn = transport.sleep || realSleep;
+    var timeoutMs = params.timeoutMs != null ? params.timeoutMs : exports.DEFAULT_PUBLISH_TIMEOUT_MS;
+    var auth = (0, table_1.resolveFormAuth)({
+        instance: params.instance,
+        user: params.user,
+        password: params.password,
+    });
+    var session = await openSession(auth);
+    var startFields = buildStartFields({
+        appSysId: app.sysId,
+        version: params.version,
+        devNotes: params.devNotes || "",
+        target: "store",
+        storeUsername: creds.username,
+        storePassword: creds.password,
+    });
+    var startRes = await post(auth, session, "/xmlhttp.do", startFields);
+    if (startRes.status < 200 || startRes.status >= 300) {
+        result.message = "start call returned HTTP " + startRes.status;
+        result.note =
+            "publish-app: the ScopedAppUploaderAJAX start call failed (HTTP " +
+                startRes.status +
+                "): " +
+                (startRes.body || "").slice(0, 200);
+        return result;
+    }
+    var startAnswer = parseXmlAnswer(startRes.body);
+    if (startAnswer.error || !SYS_ID_RE.test(startAnswer.answer)) {
+        result.message = startAnswer.error || "answer is not a sys_id";
+        result.note =
+            "publish-app: the start call did not return an execution sys_id — " +
+                (startAnswer.error ||
+                    "got '" + startAnswer.answer.slice(0, 64) + "'") +
+                ". The upload never started.";
+        return result;
+    }
+    result.executionSysId = startAnswer.answer;
+    var startedAt = Date.now();
+    var pollIndex = 0;
+    while (true) {
+        var delay = exports.PUBLISH_POLL_DELAYS_MS[Math.min(pollIndex, exports.PUBLISH_POLL_DELAYS_MS.length - 1)];
+        if (Date.now() - startedAt + delay > timeoutMs) {
+            result.status = "timeout";
+            result.note =
+                "publish-app: progress tracker " +
+                    result.executionSysId +
+                    " did not terminate within " +
+                    timeoutMs +
+                    "ms after " +
+                    result.polls +
+                    " poll(s). Check /sys_execution_tracker.do?sys_id=" +
+                    result.executionSysId +
+                    " on the instance.";
+            return result;
+        }
+        await sleepFn(delay);
+        pollIndex += 1;
+        result.polls += 1;
+        var pollRes = await post(auth, session, "/xmlhttp.do", {
+            sysparm_processor: "AJAXProgressStatusChecker",
+            sysparm_name: "getStatus",
+            sysparm_scope: "global",
+            sysparm_want_session_messages: "true",
+            sysparm_execution_id: result.executionSysId,
+            "ni.nolog.x_referer": "ignore",
+            x_referer: "sys_app.do?sys_id=" + app.sysId,
+        });
+        if (pollRes.status < 200 || pollRes.status >= 300) {
+            result.message = "getStatus returned HTTP " + pollRes.status;
+            result.note =
+                "publish-app: progress poll failed (HTTP " +
+                    pollRes.status +
+                    ") — tracker " +
+                    result.executionSysId +
+                    " may still be running on the instance.";
+            return result;
+        }
+        var pollAnswer = parseXmlAnswer(pollRes.body);
+        if (pollAnswer.error) {
+            result.message = pollAnswer.error;
+            result.note =
+                "publish-app: could not read the progress answer — " + pollAnswer.error;
+            return result;
+        }
+        var tree;
+        try {
+            tree = parseProgressTree(pollAnswer.answer);
+        }
+        catch (e) {
+            result.message = e instanceof Error ? e.message : String(e);
+            result.note = result.message;
+            return result;
+        }
+        var state = classifyProgress(tree);
+        if (!state.terminal)
+            continue;
+        result.steps = flattenSteps(tree);
+        result.message = tree.message || "";
+        var harvested = harvestProgressResults(tree);
+        result.appLink = harvested.appLink;
+        result.updateSetSysId = harvested.updateSetSysId;
+        if (state.success) {
+            result.status = "published";
+            result.note =
+                "Published " +
+                    app.name +
+                    " v" +
+                    params.version +
+                    " to the ServiceNow Store" +
+                    (result.appLink ? " — " + result.appLink : "") +
+                    " (" +
+                    result.polls +
+                    " poll(s)).";
+        }
+        else {
+            result.status = "failed";
+            result.note =
+                "publish-app: store publish terminated in state " +
+                    tree.state +
+                    (result.message ? " — " + result.message : "") +
+                    ". Tracker " +
+                    result.executionSysId +
+                    ".";
+        }
+        return result;
+    }
+}
+async function publishToRepo(params, app, client) {
+    var result = baseResult("repo", app, params.version);
+    var transport = params.transport || {};
+    var sleepFn = transport.sleep || realSleep;
+    var timeoutMs = params.timeoutMs != null ? params.timeoutMs : exports.DEFAULT_PUBLISH_TIMEOUT_MS;
+    var path = "/api/sn_cicd/app_repo/publish?sys_id=" +
+        encodeURIComponent(app.sysId) +
+        "&version=" +
+        encodeURIComponent(params.version);
+    if (params.devNotes) {
+        path += "&dev_notes=" + encodeURIComponent(params.devNotes);
+    }
+    var res = await client.now.invoke({ method: "POST", path: path });
+    if (res.status === 401 || res.status === 403) {
+        result.message = "HTTP " + res.status + " from the CI/CD API";
+        result.note =
+            "publish-app: the CI/CD publish was refused (HTTP " +
+                res.status +
+                ") — the API user needs the sn_cicd role (or admin) and the CI/CD " +
+                "plugin must be active.";
+        return result;
+    }
+    if (res.status < 200 || res.status >= 300) {
+        result.message = "HTTP " + res.status + " from the CI/CD API";
+        result.note =
+            "publish-app: POST /api/sn_cicd/app_repo/publish failed (HTTP " +
+                res.status +
+                "): " +
+                JSON.stringify(res.body).slice(0, 300) +
+                " — a version at or below the app's current repo version is the usual cause.";
+        return result;
+    }
+    var publishRes = parseCicdPublishResponse(res.body);
+    if (publishRes.error) {
+        result.message = publishRes.error;
+        result.note =
+            "publish-app: the CI/CD publish response is missing its progress link — " +
+                publishRes.error;
+        return result;
+    }
+    result.executionSysId = publishRes.progressId;
+    var startedAt = Date.now();
+    var pollIndex = 0;
+    while (true) {
+        var delay = exports.PUBLISH_POLL_DELAYS_MS[Math.min(pollIndex, exports.PUBLISH_POLL_DELAYS_MS.length - 1)];
+        if (Date.now() - startedAt + delay > timeoutMs) {
+            result.status = "timeout";
+            result.note =
+                "publish-app: CI/CD progress " +
+                    result.executionSysId +
+                    " did not terminate within " +
+                    timeoutMs +
+                    "ms after " +
+                    result.polls +
+                    " poll(s). Check GET /api/sn_cicd/progress/" +
+                    result.executionSysId +
+                    ".";
+            return result;
+        }
+        await sleepFn(delay);
+        pollIndex += 1;
+        result.polls += 1;
+        var progRes = await client.now.invoke({
+            method: "GET",
+            path: "/api/sn_cicd/progress/" + encodeURIComponent(result.executionSysId),
+        });
+        if (progRes.status < 200 || progRes.status >= 300) {
+            result.message = "HTTP " + progRes.status + " from the CI/CD progress API";
+            result.note =
+                "publish-app: CI/CD progress poll failed (HTTP " +
+                    progRes.status +
+                    ") — progress id " +
+                    result.executionSysId +
+                    ".";
+            return result;
+        }
+        var progress = parseCicdProgress(progRes.body);
+        result.message = progress.statusMessage || progress.statusLabel;
+        if (progress.status === "2") {
+            result.status = "published";
+            result.steps = [
+                {
+                    name: "CI/CD app_repo publish",
+                    state: progress.status,
+                    percentComplete: progress.percentComplete,
+                    message: result.message,
+                },
+            ];
+            result.note =
+                "Published " +
+                    app.name +
+                    " v" +
+                    params.version +
+                    " to the application repository (" +
+                    result.polls +
+                    " poll(s)).";
+            return result;
+        }
+        if (progress.status === "3" || progress.status === "4") {
+            result.status = "failed";
+            result.steps = [
+                {
+                    name: "CI/CD app_repo publish",
+                    state: progress.status,
+                    percentComplete: progress.percentComplete,
+                    message: progress.statusDetail || result.message,
+                },
+            ];
+            result.note =
+                "publish-app: CI/CD publish terminated " +
+                    (progress.statusLabel || "in state " + progress.status) +
+                    (progress.statusDetail ? " — " + progress.statusDetail : "") +
+                    ".";
+            return result;
+        }
+        // "0" pending / "1" running / unknown — keep polling until the budget ends.
+    }
+}
+function maskedPreview(target, app, params) {
+    if (target === "store") {
+        var username = params.storeUsername || process.env.SN_STORE_USERNAME || "";
+        var hasPassword = Boolean(params.storePassword || process.env.SN_STORE_PASSWORD);
+        var fields = buildStartFields({
+            appSysId: app.sysId,
+            version: params.version,
+            devNotes: params.devNotes || "",
+            target: "store",
+            storeUsername: username || MASK,
+            storePassword: hasPassword ? MASK : "(MISSING — set SN_STORE_PASSWORD)",
+        });
+        // Belt and braces: the preview never carries a real password.
+        fields.sysparm_password = hasPassword
+            ? MASK
+            : "(MISSING — set SN_STORE_PASSWORD)";
+        return fields;
+    }
+    var preview = {
+        method: "POST",
+        path: "/api/sn_cicd/app_repo/publish?sys_id=" +
+            app.sysId +
+            "&version=" +
+            params.version,
+    };
+    if (params.devNotes)
+        preview.dev_notes = params.devNotes;
+    return preview;
+}
+async function publishApp(params) {
+    if (!params || typeof params !== "object") {
+        throw new Error("publish-app: params object is required.");
+    }
+    if (!params.app) {
+        throw new Error("publish-app: app (scope, sys_id, or name) is required.");
+    }
+    if (!params.version) {
+        throw new Error("publish-app: version is required.");
+    }
+    if (params.target !== "store" && params.target !== "repo") {
+        throw new Error("publish-app: target must be 'store' or 'repo' (got '" +
+            String(params.target) +
+            "').");
+    }
+    // A NaN/non-positive timeout would make the poll-loop budget check always
+    // false — an infinite loop. Refuse it here so every caller is covered.
+    if (params.timeoutMs != null &&
+        (typeof params.timeoutMs !== "number" ||
+            !isFinite(params.timeoutMs) ||
+            params.timeoutMs <= 0)) {
+        throw new Error("publish-app: timeoutMs must be a positive number (got '" +
+            String(params.timeoutMs) +
+            "').");
+    }
+    var live = params.confirm === true && params.dryRun !== true;
+    // Fail fast on missing Store creds BEFORE any network work — a live run that
+    // resolves the app and only then discovers the missing password wastes the
+    // caller's confirm. Dry-runs still render (with the gap flagged in the preview).
+    if (live && params.target === "store") {
+        resolveStoreCreds(params);
+    }
+    var client = params.client || (0, client_1.createClient)({});
+    var app = await resolveApp(client, params.app);
+    if (!live) {
+        var dry = baseResult(params.target, app, params.version);
+        dry.status = "dry-run";
+        dry.requestPreview = maskedPreview(params.target, app, params);
+        dry.note =
+            "dry-run: nothing was published. Would publish " +
+                app.name +
+                " (" +
+                app.scope +
+                ", current version " +
+                app.version +
+                ") as v" +
+                params.version +
+                " to the " +
+                (params.target === "store"
+                    ? "ServiceNow Store (EXTERNALLY VISIBLE)"
+                    : "application repository") +
+                ". Re-run with confirm to publish.";
+        return dry;
+    }
+    if (params.target === "store") {
+        return publishToStore(params, app);
+    }
+    return publishToRepo(params, app, client);
+}

package/dist/table/formSession.d.ts

@@ -78,6 +78,14 @@ export declare function getNewRecordForm(auth: FormAuth, session: FormSession):
  * handles double/single-quoted attributes in either order. Exported for testing.
  */
 export declare function parseFormInputs(html: string): Record<string, string>;
+/**
+ * Decode the HTML entities ServiceNow uses in attribute values. Unescape &amp;
+ * LAST. Doing it first double-unescapes inputs like "&amp;lt;" ("&amp;lt;" ->
+ * "&lt;" -> "<"), the js/double-escaping vulnerability. With the ampersand
+ * handled last, each entity is unescaped exactly once. Exported for the
+ * xmlhttp.do consumers (publishApp's progress-tree answers arrive entity-encoded).
+ */
+export declare function decodeHtmlEntities(s: string): string;
 export interface PostResult {
     status: number;
     location: string;

package/dist/table/formSession.js

@@ -20,6 +20,7 @@ exports.setCurrentApplication = setCurrentApplication;
 exports.getRecordForm = getRecordForm;
 exports.getNewRecordForm = getNewRecordForm;
 exports.parseFormInputs = parseFormInputs;
+exports.decodeHtmlEntities = decodeHtmlEntities;
 exports.postForm = postForm;
 /** Env precedence mirrors client.ts: explicit > SN_* > SN_DEV_* > SN_PROD_*. */
 function resolveFormAuth(cfg) {
@@ -246,10 +247,14 @@ function attr(tag, name) {
         return decodeHtml(sq[1]);
     return null;
 }
-function decodeHtml(s) {
-    // Unescape & LAST. Doing it first double-unescapes inputs like "<"
-    // ("&amp;lt;" -> "&lt;" -> "<"), the js/double-escaping vulnerability. With the
-    // ampersand handled last, each entity is unescaped exactly once.
+/**
+ * Decode the HTML entities ServiceNow uses in attribute values. Unescape &amp;
+ * LAST. Doing it first double-unescapes inputs like "&amp;lt;" ("&amp;lt;" ->
+ * "&lt;" -> "<"), the js/double-escaping vulnerability. With the ampersand
+ * handled last, each entity is unescaped exactly once. Exported for the
+ * xmlhttp.do consumers (publishApp's progress-tree answers arrive entity-encoded).
+ */
+function decodeHtmlEntities(s) {
     return s
         .replace(/&lt;/g, "<")
         .replace(/&gt;/g, ">")
@@ -257,6 +262,9 @@ function decodeHtml(s) {
         .replace(/&#39;/g, "'")
         .replace(/&amp;/g, "&");
 }
+function decodeHtml(s) {
+    return decodeHtmlEntities(s);
+}
 /** POST a form-urlencoded field map to a `.do` path. Follows nothing — returns the 302. */
 async function postForm(auth, session, path, fields) {
     var B = base(auth);

package/dist/table/index.d.ts

@@ -9,7 +9,7 @@ export { buildColumnXml, xmlEscape } from "./buildColumnXml";
 export type { NormalizedColumn } from "./buildColumnXml";
 export { normalizeColumns, resolveType, applyTableSaveOverlay, defaultAccessFlags, showInMenuKey, listEditKey, TYPE_MAP, } from "./buildTableSave";
 export type { ColumnSpec, AccessFlags, OverlaySpec } from "./buildTableSave";
-export { resolveFormAuth, openFormSession, setCurrentApplication, getRecordForm, getNewRecordForm, parseFormInputs, postForm, scrapeCk, } from "./formSession";
+export { resolveFormAuth, openFormSession, setCurrentApplication, getRecordForm, getNewRecordForm, parseFormInputs, postForm, scrapeCk, decodeHtmlEntities, } from "./formSession";
 export type { FormAuth, FormSession, HarvestedForm, PostResult, } from "./formSession";
 export { addColumn, deriveElement } from "./addColumn";
 export type { AddColumnParams, AddColumnResult } from "./addColumn";

package/dist/table/index.js

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

package/package.json

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