@tenonhq/dovetail-servicenow 0.0.40 → 0.0.42

package/README.md

@@ -55,6 +55,33 @@ Reads ServiceNow credentials from env vars in this order of precedence:
 | User     | `SN_USER`       | `SN_DEV_USERNAME`   | `SN_PROD_USERNAME`   |
 | Password | `SN_PASSWORD`   | `SN_DEV_PASSWORD`   | `SN_PROD_PASSWORD`   |
 
+### Flow Designer identity (`SN_FLOW_*`)
+
+`/api/now/processflow/*` — every Flow Designer authoring call (view/edit/clone/
+publish an action, create/copy/publish a flow) — **cannot carry a REST API access
+policy** on ServiceNow, so under API-key auth (`SN_API_KEY`) those calls 401. They
+authenticate instead with a dedicated basic-auth identity used **only** for
+processflow paths; every other path keeps the main identity:
+
+| Field    | Preferred          | Dev fallback           | Prod fallback           |
+|----------|--------------------|------------------------|-------------------------|
+| User     | `SN_FLOW_USER`     | `SN_DEV_FLOW_USER`     | `SN_PROD_FLOW_USER`     |
+| Password | `SN_FLOW_PASSWORD` | `SN_DEV_FLOW_PASSWORD` | `SN_PROD_FLOW_PASSWORD` |
+
+- **Key mode + flow identity** → processflow requests go out as basic auth with the
+  flow identity and **no** `x-sn-apikey` header; table/Dovetail requests keep the key.
+- **Basic mode, no flow identity** → unchanged: processflow uses the main `SN_USER`.
+- **Key mode, no flow identity** → a processflow call **throws before sending**, naming
+  `SN_FLOW_USER` / `SN_FLOW_PASSWORD` (it would only 401). A half-set pair also throws.
+- Programmatic: `createClient({ apiKey, flowUser, flowPassword })` — explicit config beats
+  env. A config that pins the main identity (apiKey or user/password — e.g. one resolved
+  from an `--env` file) takes the flow identity from the config only, never from
+  `process.env`, so a per-call retarget can't borrow another instance's flow creds.
+- `--env <file>` fully determines both identities: the `SN_FLOW_*` / `SN_DEV_FLOW_*` /
+  `SN_PROD_FLOW_*` keys are connection keys, replaced (or cleared) from the file.
+
+The flow password is never logged; errors name the variables, never their values.
+
 The dev/prod fallbacks match the names documented in the committed
 `Craftsman/.env.example`, so existing developer setups work out of the box.
 Bare instance names (e.g. `TenonWorkStudio`) get `.service-now.com` appended
@@ -266,8 +293,67 @@ npx dove-sn edit-action --sys-id <id> --scope <scope> --set-script ./script.js \
 npx dove-sn edit-action --sys-id <id> --scope <scope> --from-json ops.json             # dry-run
 npx dove-sn edit-action --sys-id <id> --scope <scope> --from-json ops.json \
   --apply --update-set <id>                                                            # publish + verify
+
+# Clone a Custom Action Type (every step + its step IO) into a scope and publish it
+npx dove-sn clone-action --from <source_sys_id> --name "Send REST (Spoke)" \
+  --scope x_cadso_email_spok --ops ops.json                                            # dry-run (plan)
+npx dove-sn clone-action --from <source_sys_id> --name "Send REST (Spoke)" \
+  --scope x_cadso_email_spok --ops ops.json --update-set <id> --confirm                # write + publish + verify
+```
+
+### Cloning an action type (`clone-action` / `action_clone`)
+
+`clone-action` copies a Custom Action Type headlessly — **multi-step capable** — and
+publishes the copy:
+
+1. **Reads** (Table API only — `sn_build_agent` is never used) the parent
+   `sys_hub_action_type_definition`, its `sys_hub_action_input` / `sys_hub_action_output`
+   (`model_id` → parent), every `sys_hub_step_instance` (**`action`** → parent), and each
+   step's `sys_hub_step_ext_input` / `sys_hub_step_ext_output` (`model_id` → step).
+2. **Plans** fresh sys_ids for every record (old→new step map), the target scope,
+   `name` = `--name`, `internal_name` = `--internal-name` or the slug of the name
+   (lowercase, non-alphanumerics → `_`), `state = draft`, and strips system/snapshot
+   fields (`master_snapshot`, `latest_snapshot`, `sys_update_name`, audit fields, …).
+3. **Writes** the graph through Dovetail `createRecord`, pinned to `--update-set`, scope
+   set per record.
+4. **Publishes**: the SOURCE action's steps are fetched from
+   `/processflow/action/action_types/{source}/step_instances`, each step's `action` and
+   `sys_id` remapped onto the clone, `--ops` applied, then grafted onto the clone's model
+   and POSTed to `/snapshot` — no steps fixture needed.
+5. **Verifies** by reading the clone's steps back (script hash + step IO per step, plus
+   the step count). A mismatch exits `1`.
+
+`--scope` takes a scope **name** (resolved via `sys_scope`) or a 32-hex sys_id. The
+clone is **idempotent** on `(name, scope)`: an existing match returns `unchanged` and
+writes nothing. **Dry-run by default** — without `--confirm` it prints the plan (records
+per table, step summary, the effect of every op) and writes nothing; `--update-set` is
+required with `--confirm`. Exit `0` on success (incl. dry-run / unchanged), `1` on error.
+
+`--ops` takes the same step ops as `edit-action --from-json`, plus **`setStepInputs`** —
+set an **existing** step input's value (and its `display_value` when present), e.g. a
+REST step's HTTP method. An unknown input fails with the list of inputs on that step:
+
+```json
+{
+  "setStepInputs": [
+    { "step": "REST Step", "input": "http_method", "value": "post" }
+  ],
+  "patchStepScripts": [
+    { "step": "Parse Response", "patchScript": { "find": "v1", "replace": "v2" } }
+  ],
+  "addStepOutputs": [{ "step": "Parse Response", "name": "isRetryable", "type": "boolean" }],
+  "addStepInputs": [
+    { "step": "Handle Error", "name": "isRetryable", "type": "boolean",
+      "pillFrom": { "step": "Parse Response", "output": "isRetryable" } }
+  ]
+}
 ```
 
+The MCP tool **`action_clone`** takes the same inputs — `from`, `name`, `scope`,
+`internalName`, `description`, `updateSetSysId`, `ops` (inline object), `confirm`,
+`dryRun` — with the same dry-run-unless-`confirm:true` gate. `setStepInputs` is also
+accepted by `edit-action` / `action_edit`.
+
 ### Editing an action type's steps (`--from-json`)
 
 The flag form above patches the one auto-detected script. When you need to touch
@@ -725,7 +811,9 @@ and read-back-verified — `host_assets` (deploy a built dist/), plus the Flow D
 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
-publish is read back and verified), `flow_publish` (compile a flow/subflow snapshot), `flow_copy`
+publish is read back and verified), `action_clone` (clone an action type — every step
+and its step IO — into a scope and publish + verify it; dry-run by default),
+`flow_publish` (compile a flow/subflow snapshot), `flow_copy`
 (copy a flow as an inactive draft), `flow_create` (create a NEW flow from scratch +
 publish, grafting a template), `flow_test` (validate or run a flow), and
 `flow_edit` (patch a flow), plus `invoke_rest` (invoke an arbitrary authenticated

package/dist/cli.js

@@ -83,6 +83,7 @@ const copyFlow_1 = require("./flowDesigner/copyFlow");
 const createFlow_1 = require("./flowDesigner/createFlow");
 const editFlow_1 = require("./flowDesigner/editFlow");
 const editActionType_1 = require("./flowDesigner/editActionType");
+const cloneActionType_1 = require("./flowDesigner/cloneActionType");
 const testFlow_1 = require("./flowDesigner/testFlow");
 const table_1 = require("./table");
 const setField_1 = require("./setField");
@@ -929,6 +930,170 @@ async function runEditAction(flags) {
     }
     return 0;
 }
+/**
+ * dove-sn clone-action:
+ *   --from <sys_id>            Required. Source sys_hub_action_type_definition sys_id.
+ *   --name <name>              Required. Display name of the clone (idempotency key with --scope).
+ *   --scope <name|sys_id>      Required. Target scope — a scope name (x_cadso_email_spok) or 32-hex sys_id.
+ *   --internal-name <name>     Optional. Default: slug of --name.
+ *   --description <text>       Optional.
+ *   --ops <path>               Optional. JSON StepOps applied to the cloned steps before publish:
+ *                              patchStepScripts / setStepInputs / addStepOutputs / addStepInputs.
+ *   --update-set <sys_id>      Required with --confirm. Every write + the publish land here.
+ *   --confirm                  Execute (write the graph, publish, verify). WITHOUT it: dry-run.
+ *   --dry-run                  Force a dry-run even with --confirm.
+ *   --json                     Emit the structured CloneActionTypeResult.
+ *
+ * Clones a Custom Action Type — parent, inputs, outputs, every step instance and
+ * its step-level ext inputs/outputs — into the target scope, then publishes it
+ * headlessly through the snapshot path (multi-step capable) and reads the steps
+ * back to verify. Idempotent on (name, scope). DRY-RUN BY DEFAULT.
+ *
+ * --ops shape:
+ *   {
+ *     "setStepInputs":    [{ "step": "REST Step", "input": "http_method", "value": "post" }],
+ *     "patchStepScripts": [{ "step": "Parse", "patchScript": { "find": "a", "replace": "b" } }],
+ *     "addStepOutputs":   [{ "step": "Parse", "name": "isRetryable", "type": "boolean" }],
+ *     "addStepInputs":    [{ "step": "Handle", "name": "isRetryable", "type": "boolean",
+ *                            "pillFrom": { "step": "Parse", "output": "isRetryable" } }]
+ *   }
+ * `step` is a step cid or label; `scriptFile` (resolved relative to the ops file)
+ * is sugar for `setScript` in patchStepScripts.
+ */
+var CLONE_OPS_KEYS = ["patchStepScripts", "setStepInputs", "addStepOutputs", "addStepInputs"];
+async function runCloneAction(flags, bare) {
+    var bareErr = bareStringFlagError("clone-action", bare, [
+        "from",
+        "name",
+        "scope",
+        "internal-name",
+        "description",
+        "ops",
+        "update-set",
+    ]);
+    if (bareErr) {
+        process.stderr.write(bareErr);
+        return 1;
+    }
+    var from = flags.from;
+    var name = flags.name;
+    var scope = flags.scope;
+    if (!from || !name || !scope) {
+        process.stderr.write("clone-action: --from <sys_id>, --name <name> and --scope <scope name|sys_id> are required\n");
+        return 1;
+    }
+    var confirm = flags.confirm === "true";
+    var dryRun = flags["dry-run"] === "true";
+    var updateSet = flags["update-set"] || flags.updateSetSysId;
+    if (confirm && !dryRun && !updateSet) {
+        process.stderr.write("clone-action: --update-set <sys_id> is required with --confirm\n");
+        return 1;
+    }
+    var stepOps;
+    if (flags.ops) {
+        var parsedOps = JSON.parse(fs.readFileSync(flags.ops, "utf8"));
+        if (!parsedOps || typeof parsedOps !== "object" || Array.isArray(parsedOps)) {
+            process.stderr.write("clone-action: --ops must contain a StepOps object\n");
+            return 1;
+        }
+        var opsObj = parsedOps;
+        var opsKeys = Object.keys(opsObj);
+        for (var k = 0; k < opsKeys.length; k += 1) {
+            if (CLONE_OPS_KEYS.indexOf(opsKeys[k]) === -1) {
+                process.stderr.write("clone-action: unknown --ops key '" +
+                    opsKeys[k] +
+                    "' (allowed: " +
+                    CLONE_OPS_KEYS.join(", ") +
+                    ")\n");
+                return 1;
+            }
+        }
+        resolveScriptFiles(opsObj, flags.ops);
+        stepOps = opsObj;
+    }
+    var result = await (0, cloneActionType_1.cloneActionType)({
+        client: (0, client_1.createClient)({}),
+        sourceSysId: from,
+        newName: name,
+        internalName: flags["internal-name"],
+        newScope: scope,
+        updateSetSysId: updateSet,
+        description: flags.description,
+        stepOps: stepOps,
+        confirm: confirm,
+        dryRun: dryRun,
+    });
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return result.verify && !result.verify.ok ? 1 : 0;
+    }
+    process.stdout.write("[" + result.action + "] " + name + " (" + result.internalName + ") -> " + result.sysId + "\n");
+    if (result.action === "unchanged") {
+        process.stdout.write("  an action with this name already exists in the target scope — nothing written\n");
+        return 0;
+    }
+    if (result.plan) {
+        process.stdout.write("  scope: " +
+            result.plan.scope.name +
+            " (" +
+            result.plan.scope.sysId +
+            ")  source scope: " +
+            result.plan.sourceScopeSysId +
+            "\n  records: " +
+            result.plan.total +
+            "\n");
+        var tables = Object.keys(result.plan.counts);
+        for (var t = 0; t < tables.length; t += 1) {
+            process.stdout.write("    " + tables[t] + ": " + result.plan.counts[tables[t]] + "\n");
+        }
+    }
+    if (result.steps) {
+        process.stdout.write("\n--- steps (as published) ---\n");
+        for (var si = 0; si < result.steps.after.length; si += 1) {
+            var step = result.steps.after[si];
+            process.stdout.write("  " +
+                step.label +
+                " (" +
+                step.cid +
+                ")" +
+                (step.scriptChars !== null ? " script " + step.scriptChars + " chars" : "") +
+                (step.extendedInputs.length ? " in:" + step.extendedInputs.length : "") +
+                (step.extendedOutputs.length ? " out:" + step.extendedOutputs.length : "") +
+                "\n");
+        }
+        for (var ci = 0; ci < result.steps.changes.length; ci += 1) {
+            process.stdout.write("  + " + result.steps.changes[ci] + "\n");
+        }
+        for (var wi = 0; wi < result.steps.warnings.length; wi += 1) {
+            process.stdout.write("  ! " + result.steps.warnings[wi] + "\n");
+        }
+    }
+    if (result.action === "planned") {
+        process.stdout.write("\nDRY RUN — nothing written. Re-run with --confirm --update-set <sys_id> to clone + publish.\n");
+        return 0;
+    }
+    process.stdout.write("\nwritten: " +
+        result.written.length +
+        " record(s)" +
+        (result.publish
+            ? "; published (HTTP " +
+                result.publish.httpStatus +
+                (result.publish.snapshotSysId ? ", snapshot " + result.publish.snapshotSysId : "") +
+                ")"
+            : "") +
+        "\n");
+    if (result.verify) {
+        process.stdout.write("\n--- verify (read back from the instance) ---\n");
+        process.stdout.write("  " + (result.verify.ok ? "OK" : "FAILED") + "\n");
+        for (var vi = 0; vi < result.verify.notes.length; vi += 1) {
+            process.stdout.write("  " + (result.verify.ok ? "+ " : "! ") + result.verify.notes[vi] + "\n");
+        }
+        if (!result.verify.ok) {
+            return 1;
+        }
+    }
+    return 0;
+}
 async function runMcp(flags) {
     if (flags.smoke === "true") {
         await (0, server_1.runSmoke)();
@@ -1041,6 +1206,15 @@ function printHelp() {
         "                                              (per-step scripts + step IO + data-pill wiring)\n" +
         '                      | --patch-script "<find>::<replace>" | --set-script <path> | --merge-outputs <path>\n' +
         "                      [--script-input <name>] [--update-set <sys_id>] [--apply] [--json])\n" +
+        "  clone-action       Clone a Custom Action Type (all steps + step IO) into a scope and publish it\n" +
+        "                     DRY-RUN BY DEFAULT — nothing is written without --confirm\n" +
+        "                     (--from <sys_id> --name <n> --scope <scope name|sys_id>\n" +
+        "                      [--internal-name <n>] [--description <d>]\n" +
+        "                      [--ops <ops.json>]  ops: setStepInputs / patchStepScripts /\n" +
+        "                                          addStepOutputs / addStepInputs\n" +
+        "                      [--update-set <sys_id> (required with --confirm)] [--confirm] [--dry-run] [--json])\n" +
+        "                     Idempotent on (name, scope). Publishes via the snapshot path and\n" +
+        "                     reads the steps back to verify.\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, the company application\n" +
@@ -1077,7 +1251,10 @@ function printHelp() {
         "                     or the DOVETAIL_ENV_FILE env var). A bare name like 'prod'\n" +
         "                     resolves to .env.prod in the cwd. The file's SN_* connection\n" +
         "                     vars replace any already exported; a missing or incomplete\n" +
-        "                     file is an error (no fallback). Default: .env in the cwd.\n");
+        "                     file is an error (no fallback). Default: .env in the cwd.\n" +
+        "  Flow Designer auth /api/now/processflow/* can't carry an API access policy, so\n" +
+        "                     under SN_API_KEY those calls use a dedicated basic-auth identity:\n" +
+        "                     SN_FLOW_USER / SN_FLOW_PASSWORD (or SN_DEV_FLOW_* / SN_PROD_FLOW_*).\n");
 }
 /** Parse inline `--columns "Label:type:max, Other:choice, ..."` into ColumnSpec[]. */
 function parseColumnsInline(input) {
@@ -2244,6 +2421,9 @@ async function main() {
     if (parsed.command === "edit-action") {
         return await runEditAction(parsed.flags);
     }
+    if (parsed.command === "clone-action") {
+        return await runCloneAction(parsed.flags, parsed.bare);
+    }
     if (parsed.command === "create-view") {
         await runCreateView(parsed.flags);
         return 0;

package/dist/client.d.ts

@@ -29,6 +29,33 @@ export type ResolvedAuth = {
     user: string;
     password: string;
 };
+/** Path prefix of the Flow Designer authoring API — the only paths the flow identity is used for. */
+export declare var PROCESSFLOW_PATH_PREFIX: string;
+/**
+ * Resolved Flow Designer (processflow) identity:
+ *   - "basic"   — a complete SN_FLOW_USER / SN_FLOW_PASSWORD pair;
+ *   - "partial" — only one half was set (reported, never sent);
+ *   - "none"    — no flow identity configured.
+ */
+export type ResolvedFlowAuth = {
+    mode: "basic";
+    user: string;
+    password: string;
+} | {
+    mode: "partial";
+    missing: string;
+} | {
+    mode: "none";
+};
+/**
+ * Explicit config beats env. When the config pins the MAIN identity (apiKey or
+ * user/password — e.g. a config resolved from an --env file), the flow identity
+ * is taken from the config ONLY, so a per-call retarget can never borrow the
+ * process's flow credentials for a different instance.
+ */
+export declare function resolveFlowAuth(cfg: ServiceNowClientConfig): ResolvedFlowAuth;
+/** True when an instance-relative request URL targets the processflow API. */
+export declare function isProcessflowPath(url: unknown): boolean;
 export interface TableQueryOptions {
     limit?: number;
     fields?: string[];
@@ -137,7 +164,9 @@ export interface ServiceNowClient {
     now: {
         /**
          * GET an arbitrary native ServiceNow REST path (e.g. /api/now/processflow/...).
-         * Basic auth, same credentials/retry/throttle as the rest of the client.
+         * Same credentials/retry/throttle as the rest of the client, except that
+         * /api/now/processflow/* paths authenticate with the dedicated Flow Designer
+         * identity (SN_FLOW_USER / SN_FLOW_PASSWORD) when one is configured.
          * Use for endpoints that aren't the Table API or the Dovetail Scripted REST API
          * — currently the Flow Designer processflow endpoints. Returns the raw response body.
          */

package/dist/client.js

@@ -24,6 +24,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROCESSFLOW_PATH_PREFIX = void 0;
+exports.resolveFlowAuth = resolveFlowAuth;
+exports.isProcessflowPath = isProcessflowPath;
 exports.createClient = createClient;
 const axios_1 = __importDefault(require("axios"));
 /**
@@ -86,6 +89,46 @@ function resolveAuth(cfg) {
     }
     return { mode: "basic", user: user, password: password };
 }
+/** Path prefix of the Flow Designer authoring API — the only paths the flow identity is used for. */
+exports.PROCESSFLOW_PATH_PREFIX = "/api/now/processflow/";
+/**
+ * Explicit config beats env. When the config pins the MAIN identity (apiKey or
+ * user/password — e.g. a config resolved from an --env file), the flow identity
+ * is taken from the config ONLY, so a per-call retarget can never borrow the
+ * process's flow credentials for a different instance.
+ */
+function resolveFlowAuth(cfg) {
+    var cfgPinsIdentity = Boolean(cfg.apiKey || cfg.user || cfg.password || cfg.flowUser || cfg.flowPassword);
+    var user = cfg.flowUser || "";
+    var password = cfg.flowPassword || "";
+    if (!cfgPinsIdentity) {
+        user = process.env.SN_FLOW_USER
+            || process.env.SN_DEV_FLOW_USER
+            || process.env.SN_PROD_FLOW_USER
+            || "";
+        password = process.env.SN_FLOW_PASSWORD
+            || process.env.SN_DEV_FLOW_PASSWORD
+            || process.env.SN_PROD_FLOW_PASSWORD
+            || "";
+    }
+    if (user && password) {
+        return { mode: "basic", user: user, password: password };
+    }
+    if (user) {
+        return { mode: "partial", missing: "SN_FLOW_PASSWORD" };
+    }
+    if (password) {
+        return { mode: "partial", missing: "SN_FLOW_USER" };
+    }
+    return { mode: "none" };
+}
+/** True when an instance-relative request URL targets the processflow API. */
+function isProcessflowPath(url) {
+    if (typeof url !== "string") {
+        return false;
+    }
+    return url.toLowerCase().indexOf(exports.PROCESSFLOW_PATH_PREFIX) === 0;
+}
 function sleep(ms) {
     return new Promise(function (resolve) {
         setTimeout(resolve, ms);
@@ -130,6 +173,49 @@ function createClient(config = {}) {
         headers: baseHeaders,
         validateStatus: function () { return true; }
     });
+    // Flow Designer (processflow) identity. processflow cannot carry a REST API
+    // access policy, so under API-key auth those calls must go out as basic auth
+    // with a dedicated identity. The transport is created lazily on the first
+    // processflow request and deliberately carries NO x-sn-apikey header.
+    var flowAuth = resolveFlowAuth(config);
+    var flowHttp = null;
+    /**
+     * Pick the transport for a request. Non-processflow paths always use the
+     * main client. A processflow path uses the flow identity when configured,
+     * the main client when it is already basic auth, and otherwise throws BEFORE
+     * sending — an API-key processflow call is a guaranteed 401.
+     */
+    function transportFor(cfg) {
+        if (!isProcessflowPath(cfg.url)) {
+            return { http: http, flow: false };
+        }
+        if (flowAuth.mode === "partial") {
+            throw new Error("Flow Designer identity is incomplete: " + flowAuth.missing + " is not set. " +
+                "Set both SN_FLOW_USER and SN_FLOW_PASSWORD (or SN_DEV_FLOW_* / SN_PROD_FLOW_*) " +
+                "to authenticate /api/now/processflow/* requests.");
+        }
+        if (flowAuth.mode === "basic") {
+            if (!flowHttp) {
+                flowHttp = axios_1.default.create({
+                    baseURL: "https://" + host,
+                    auth: { username: flowAuth.user, password: flowAuth.password },
+                    headers: {
+                        accept: "application/json",
+                        "content-type": "application/json"
+                    },
+                    validateStatus: function () { return true; }
+                });
+            }
+            return { http: flowHttp, flow: true };
+        }
+        if (creds.mode === "basic") {
+            return { http: http, flow: false };
+        }
+        throw new Error("Flow Designer requests (/api/now/processflow/*) cannot use API-key auth: ServiceNow " +
+            "cannot attach a REST API access policy to processflow, so the call would 401. " +
+            "Set SN_FLOW_USER and SN_FLOW_PASSWORD (a dedicated basic-auth identity used ONLY for " +
+            "processflow) in your env file, or pass { flowUser, flowPassword } to createClient.");
+    }
     var lastAt = 0;
     // Dovetail core Scripted REST API: prefer the Dovetail-app path
     // /api/cadso/dovetail_core/* and fall back to the legacy global-scope path
@@ -148,6 +234,12 @@ function createClient(config = {}) {
     async function requestRaw(cfg, ctx, passThrough) {
         var attempt429 = 0;
         var attempt5xx = 0;
+        // Resolved before the first send: a processflow call with no usable
+        // identity throws here, never reaching the network.
+        var transport = transportFor(cfg);
+        var authHint = transport.flow
+            ? "check SN_FLOW_USER/SN_FLOW_PASSWORD (the Flow Designer identity) and its roles."
+            : "check SN_USER/SN_PASSWORD and ACLs.";
         // eslint-disable-next-line no-constant-condition
         while (true) {
             var elapsed = Date.now() - lastAt;
@@ -157,7 +249,7 @@ function createClient(config = {}) {
             lastAt = Date.now();
             var res;
             try {
-                res = await http.request(cfg);
+                res = await transport.http.request(cfg);
             }
             catch (netErr) {
                 if (attempt5xx >= max5xx) {
@@ -191,7 +283,7 @@ function createClient(config = {}) {
                 return { status: res.status, data: res.data };
             }
             if (res.status === 401 || res.status === 403) {
-                throw new Error("SN auth error " + res.status + " on " + ctx + " — check SN_USER/SN_PASSWORD and ACLs.");
+                throw new Error("SN auth error " + res.status + " on " + ctx + " — " + authHint);
             }
             if (res.status === 404) {
                 throw new Error("SN 404 on " + ctx + " — endpoint or record not found.");

package/dist/createClientFromEnvFile.js

@@ -49,19 +49,35 @@ function resolveConfigFromEnvFile(envPath) {
         throw new Error("env file '" + envPath + "' does not define a ServiceNow instance — " +
             "set SN_INSTANCE (preferred) or SN_DEV_INSTANCE / SN_PROD_INSTANCE.");
     }
+    // Dedicated Flow Designer (processflow) identity — optional. Carried only
+    // when the file sets it, so a file without it resolves exactly as before.
+    // Because the returned config pins the main identity, createClient takes the
+    // flow identity from this config ONLY: a file without SN_FLOW_* never
+    // borrows the host process's flow credentials.
+    var flowUser = parsed.SN_FLOW_USER || parsed.SN_DEV_FLOW_USER || parsed.SN_PROD_FLOW_USER || "";
+    var flowPassword = parsed.SN_FLOW_PASSWORD || parsed.SN_DEV_FLOW_PASSWORD || parsed.SN_PROD_FLOW_PASSWORD || "";
+    var withFlow = function (cfg) {
+        if (flowUser) {
+            cfg.flowUser = flowUser;
+        }
+        if (flowPassword) {
+            cfg.flowPassword = flowPassword;
+        }
+        return cfg;
+    };
     if (apiKey) {
         // Key is the default auth mode when the file defines one. Returning the
         // key WITHOUT user/password keeps the resolved config fully explicit —
         // resolveAuth treats a config that names user/password as a deliberate
         // basic-auth pin, so leaking them here would flip the mode.
-        return { instance: instance, apiKey: apiKey };
+        return withFlow({ instance: instance, apiKey: apiKey });
     }
     if (!user || !password) {
         throw new Error("env file '" + envPath + "' is missing ServiceNow credentials — " +
             "set SN_API_KEY (inbound API key, preferred), SN_USER/SN_PASSWORD, " +
             "or SN_DEV_USERNAME/SN_DEV_PASSWORD (or SN_PROD_*).");
     }
-    return { instance: instance, user: user, password: password };
+    return withFlow({ instance: instance, user: user, password: password });
 }
 /**
  * Construct a ServiceNowClient bound to the instance/credentials defined in a

package/dist/flowDesigner/actionTypeApi.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared processflow helpers for Custom Action Type authoring — the path
+ * builder, the `{ result: ... }` envelope unwrap, and the `/step_instances`
+ * read that editActionType and cloneActionType both depend on.
+ *
+ *   GET /api/now/processflow/action/action_types/{id}/step_instances?sysparm_transaction_scope={scope}
+ *     -> { steps: [...] }   (bare or under `result`)
+ *
+ * The action-type model GET returns `steps: null`; this is where the Designer
+ * (and we) get the real step graph.
+ */
+import type { ServiceNowClient } from "../client";
+import type { StepRecord } from "./stepOps";
+/** Build `/api/now/processflow/action/action_types/{sysId}{suffix}?sysparm_transaction_scope={scope}`. */
+export declare function actionTypePath(sysId: string, scopeSysId: string, suffix: string): string;
+/** Normalize the `{ result: ... }` envelope the processflow endpoints sometimes use. */
+export declare function unwrapProcessflow(data: unknown): unknown;
+/**
+ * GET an action type's step graph from `/step_instances` and unwrap `{ steps }`.
+ * Returns [] when the response carries no steps array — callers decide whether
+ * an empty graph is an error.
+ */
+export declare function fetchActionSteps(client: ServiceNowClient, sysId: string, scopeSysId: string): Promise<Array<StepRecord>>;

package/dist/flowDesigner/actionTypeApi.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Shared processflow helpers for Custom Action Type authoring — the path
+ * builder, the `{ result: ... }` envelope unwrap, and the `/step_instances`
+ * read that editActionType and cloneActionType both depend on.
+ *
+ *   GET /api/now/processflow/action/action_types/{id}/step_instances?sysparm_transaction_scope={scope}
+ *     -> { steps: [...] }   (bare or under `result`)
+ *
+ * The action-type model GET returns `steps: null`; this is where the Designer
+ * (and we) get the real step graph.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actionTypePath = actionTypePath;
+exports.unwrapProcessflow = unwrapProcessflow;
+exports.fetchActionSteps = fetchActionSteps;
+/** Build `/api/now/processflow/action/action_types/{sysId}{suffix}?sysparm_transaction_scope={scope}`. */
+function actionTypePath(sysId, scopeSysId, suffix) {
+    return "/api/now/processflow/action/action_types/" + encodeURIComponent(sysId)
+        + suffix
+        + "?sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+/** Normalize the `{ result: ... }` envelope the processflow endpoints sometimes use. */
+function unwrapProcessflow(data) {
+    if (data && typeof data === "object") {
+        var rec = data;
+        if (rec.result && typeof rec.result === "object") {
+            return rec.result;
+        }
+    }
+    return data;
+}
+/**
+ * GET an action type's step graph from `/step_instances` and unwrap `{ steps }`.
+ * Returns [] when the response carries no steps array — callers decide whether
+ * an empty graph is an error.
+ */
+async function fetchActionSteps(client, sysId, scopeSysId) {
+    var resp = unwrapProcessflow(await client.now.get(actionTypePath(sysId, scopeSysId, "/step_instances")));
+    if (resp && typeof resp === "object") {
+        var steps = resp.steps;
+        if (Array.isArray(steps)) {
+            return steps;
+        }
+    }
+    return [];
+}

package/dist/flowDesigner/buildFlowOrchestrator.d.ts

@@ -57,7 +57,7 @@ export interface BuildFlowResult {
     /** Filled when clone/create produced a new artifact. */
     artifact?: {
         sysId: string;
-        action: "created" | "unchanged";
+        action: "created" | "unchanged" | "planned";
         writtenCount: number;
     };
     verify?: VerifyReport;