@tenonhq/dovetail-servicenow 0.0.42 → 0.0.44

package/README.md

@@ -299,6 +299,11 @@ 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
+
+# Define an action type's inputs, outputs and steps (script + REST, pill-wired) like the Designer's Save
+npx dove-sn define-action --sys-id <id> --scope x_cadso_email_spok --spec spec.json      # dry-run (diff)
+npx dove-sn define-action --sys-id <id> --scope x_cadso_email_spok --spec spec.json \
+  --update-set <id> --confirm --publish                                                # save + verify + publish
 ```
 
 ### Cloning an action type (`clone-action` / `action_clone`)
@@ -354,6 +359,150 @@ The MCP tool **`action_clone`** takes the same inputs — `from`, `name`, `scope
 `dryRun` — with the same dry-run-unless-`confirm:true` gate. `setStepInputs` is also
 accepted by `edit-action` / `action_edit`.
 
+### Defining an action type's body (`define-action` / `action_define`)
+
+`define-action` authors a Custom Action Type's **action inputs, outputs and steps** —
+script steps and REST steps, wired together with data pills — headlessly, the way
+the Flow Designer's **Save** button does, and optionally publishes it.
+
+```bash
+npx dove-sn define-action --sys-id <action_sys_id> --scope x_cadso_email_spok \
+  --spec spec.json                                                  # dry-run: the planned diff
+npx dove-sn define-action --sys-id <action_sys_id> --scope x_cadso_email_spok \
+  --spec spec.json --update-set <id> --confirm                      # save + verify
+npx dove-sn define-action --sys-id <action_sys_id> --scope x_cadso_email_spok \
+  --spec spec.json --update-set <id> --confirm --publish            # save + verify + publish
+```
+
+How it works (established from two captured Designer saves):
+
+1. `GET /api/now/processflow/action/action_types/{id}` — the model (43 keys; `steps` is null).
+2. `GET …/{id}/step_instances` — the real step graph.
+3. Merge the spec. Existing steps keep their `cid`; new steps are built from the
+   Designer's own step shape for that type (script / REST) with a fresh `cid`.
+4. `PUT …/{id}` with the **full** model — the Designer's save is not a delta. Each
+   step is sent in the Designer's 11-key shape (`DB_TYPE`, `cid`, `step_type_id`,
+   `section`, `label`, `action`, `order`, `inputs`, `extended_inputs`,
+   `extended_outputs`, `error_handling_type`).
+5. Read the model + steps back and compare them with the plan (a mismatch exits `1`).
+6. `--publish`: snapshot through the existing `publishActionType` path.
+
+**Dry-run by default** — without `--confirm` it prints the planned diff (inputs,
+outputs and steps added / changed / removed, with each step's input values) and makes
+no write. **Idempotent** — a spec that is already in effect is `unchanged` and makes no
+PUT. `--update-set` is optional; when given, the REST session is pinned to it before the
+save and the publish. Exit `0` on success (incl. dry-run / unchanged), `1` on error or a
+failed verify.
+
+**The action shell must already exist.** Creating a brand-new empty action headlessly is
+out of scope: make it with `clone-action` or in the Designer, then define its body here.
+
+#### Spec
+
+Every part is optional, so a spec can be a small incremental edit.
+
+| Key | Shape | Notes |
+|---|---|---|
+| `action` | `{ name?, description?, access?: "public" \| "package_private" }` | `name` sets `name` + `displayName` |
+| `inputs[]` | `{ name, label?, type?, mandatory?, choices?: [{value, label?}], default?, order?, maxLength?, remove? }` | Upsert by `name`. `type`: `string` (default) \| `choice` \| `boolean` \| `integer`. `choice` needs `choices`; `default` must be one of them. Changing an input's type makes ServiceNow mint a new variable record |
+| `outputs[]` | `{ name, label?, type?, value?, remove? }` | Upsert by `name`. `value` is the pill the output is wired to. System outputs (`__action_status__`, `__dont_treat_as_error__`) cannot be named |
+| `steps[]` | `{ ref, type: "script" \| "rest", label?, match?, remove?, errorHandling?, script?, inputs?, outputs?, values? }` | See below |
+
+Steps:
+
+- **Matching.** `match` (an existing step's cid or current label — use it to rename),
+  else `label`, else position (the spec's Nth step against the action's Nth step, same
+  type, flagged in the diff as `matched by order`). Unmatched steps are created and
+  placed before the next existing step the spec lists after them (else appended).
+  Existing steps are never reordered; `remove: true` deletes one.
+- **`script`** (script steps) — the script body. On the CLI, `scriptFile` (relative
+  to the spec file) is sugar for it.
+- **`inputs`** (script steps) — the step's own input variables (`extended_inputs`):
+  `{ "<name>": "<value or pill>" }` or `{ "<name>": { value?, type?, label?, mandatory?, remove? } }`.
+- **`outputs`** (script steps) — the step's own output variables (`extended_outputs`):
+  `[{ name, label?, type?, remove? }]`.
+- **`values`** — the step type's own inputs by name (unknown names are an error that
+  lists the valid ones). For a REST step: `connection` (`use_connection_alias`),
+  `connection_alias` (a `sys_alias` sys_id — its display name is looked up — or
+  `{ value, display }`), `override_base_url`, `base_url`, `resource_path`,
+  `http_method` (`get` / `post` / `put` / `delete` …), `headers` and `query_params`
+  (`[{ name, value }]` → the Designer's `ADV_NV` list), `body`, `request_type`,
+  `connection_timeout`, `retry_policy`, … Booleans take `true` / `false`.
+- **`errorHandling`** — `EVAL_ERRORS` (the default) or `NEXT_STEP` (continue on error).
+
+Pills (in `values`, script `inputs` and `outputs[].value`):
+
+| Pill | Means |
+|---|---|
+| `{{action.<input>}}` | an action input — must exist after the merge |
+| `{{steps.<ref>.<output>}}` | another spec step's output — resolved to `{{step[<cid>].<output>}}`. Inside a step it must point at an **earlier** step |
+| `{{step[<cid>].<output>}}` | the raw form — the cid must exist |
+
+REST steps expose `status_code`, `response_body`, `response_headers`, `error_message`,
+`error_code`, `response_stream`; a script step exposes its `outputs`. An **action
+output is wired by putting the pill in the output's own `value`** (the Designer also
+mirrors it into `display_value` and records the pill's label in `label_cache` — both
+handled for you). Everything is checked before any write: unknown keys, names with `^`
+or path characters (names must match `^[A-Za-z_][A-Za-z0-9_]*$`), an unknown step type,
+an unknown step ref / action input / step output in a pill, and any pill the spec would
+leave dangling (e.g. removing an input a step still reads).
+
+Example — the complete body of *Email Service Request GET*:
+
+```json
+{
+  "inputs": [
+    { "name": "host", "type": "choice", "mandatory": true, "default": "api",
+      "choices": [
+        { "value": "api", "label": "API" },
+        { "value": "storage_us_east4", "label": "US East 4" },
+        { "value": "storage_us_west1", "label": "US West 1" },
+        { "value": "storage_europe_west1", "label": "Europe West 1" }
+      ] },
+    { "name": "path", "type": "string", "mandatory": true },
+    { "name": "content_type", "type": "string", "mandatory": false },
+    { "name": "body", "type": "string", "mandatory": false }
+  ],
+  "steps": [
+    { "ref": "guard", "type": "script", "label": "Guard", "match": "Gaurd",
+      "scriptFile": "guard.js",
+      "inputs": {
+        "host_1": { "value": "{{action.host}}", "mandatory": true },
+        "path_1": { "value": "{{action.path}}", "mandatory": true }
+      },
+      "outputs": [
+        { "name": "base_url", "label": "Base URL", "type": "string" },
+        { "name": "error", "label": "Error", "type": "string" }
+      ] },
+    { "ref": "call", "type": "rest", "label": "Call email service", "match": "REST step",
+      "errorHandling": "NEXT_STEP",
+      "values": {
+        "connection": "use_connection_alias",
+        "connection_alias": "956cc622c3ee4a1085b196c4e401317e",
+        "override_base_url": true,
+        "base_url": "{{steps.guard.base_url}}",
+        "resource_path": "{{action.path}}",
+        "http_method": "get",
+        "headers": [{ "name": "Content-Type", "value": "{{action.content_type}}" }],
+        "connection_timeout": "25000"
+      } }
+  ],
+  "outputs": [
+    { "name": "status_code", "label": "Status Code", "type": "string", "value": "{{steps.call.status_code}}" },
+    { "name": "response_body", "label": "Response Body", "type": "string", "value": "{{steps.call.response_body}}" },
+    { "name": "error", "label": "Error", "type": "string", "value": "{{steps.call.error_message}}" }
+  ]
+}
+```
+
+The MCP tool **`action_define`** takes `sysId`, `scope`, `spec` (inline — `script`, not
+`scriptFile`), `updateSetSysId`, `publish`, `confirm`, `dryRun`, with the same
+dry-run-unless-`confirm:true` gate.
+
+Not yet covered (no Designer capture of the shape yet): step types other than script
+and REST, reference / object / array variable types, and the action's error-status
+conditions (`action_status_metadata`, which is carried through unchanged).
+
 ### Editing an action type's steps (`--from-json`)
 
 The flag form above patches the one auto-detected script. When you need to touch
@@ -813,6 +962,9 @@ type's model), `action_edit` (structurally edit a published action type — per-
 scripts, step-level inputs/outputs, data-pill wiring — dry-run by default, and the
 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),
+`action_define` (define an existing action type's inputs, outputs and script/REST
+steps with data-pill wiring, the way the Designer's Save does; dry-run by default,
+idempotent, read back and verified, optional publish),
 `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

package/dist/cli.js

@@ -84,6 +84,7 @@ 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 defineActionType_1 = require("./flowDesigner/defineActionType");
 const testFlow_1 = require("./flowDesigner/testFlow");
 const table_1 = require("./table");
 const setField_1 = require("./setField");
@@ -1094,6 +1095,145 @@ async function runCloneAction(flags, bare) {
     }
     return 0;
 }
+/**
+ * dove-sn define-action:
+ *   --sys-id <sys_id>          Required. The sys_hub_action_type_definition to define (the shell must
+ *                              exist — make it with clone-action or the Flow Designer).
+ *   --scope <name|sys_id>      Required. The action's own scope (x_cadso_email_spok or a 32-hex sys_id).
+ *   --spec <spec.json>         Required. The definition — action inputs, outputs, steps (see below).
+ *   --update-set <sys_id>      Optional. Pin the REST session to this update set before the save/publish.
+ *   --publish                  With --confirm: also publish (snapshot) after the save.
+ *   --confirm                  Execute (PUT the model, verify, optionally publish). WITHOUT it: dry-run.
+ *   --dry-run                  Force a dry-run even with --confirm.
+ *   --json                     Emit the structured DefineActionTypeResult.
+ *
+ * Saves the action the way the Flow Designer's Save does: GET the model + the
+ * step graph, merge the spec, PUT the FULL model back to
+ * /api/now/processflow/action/action_types/{id}, read it back to verify.
+ * DRY-RUN BY DEFAULT: prints the planned diff, writes nothing. Idempotent: a
+ * spec already in effect is "unchanged" and makes no PUT.
+ *
+ * --spec shape (every part optional — incremental edits are fine):
+ *   {
+ *     "action":  { "name": "...", "description": "...", "access": "public" | "package_private" },
+ *     "inputs":  [{ "name": "host", "type": "choice", "mandatory": true, "default": "api",
+ *                   "choices": [{ "value": "api", "label": "API" }] }],      // upsert by name; "remove": true
+ *     "outputs": [{ "name": "status_code", "value": "{{steps.call.status_code}}" }],
+ *     "steps": [
+ *       { "ref": "guard", "type": "script", "label": "Guard", "scriptFile": "guard.js",
+ *         "inputs":  { "host_1": "{{action.host}}" }, "outputs": [{ "name": "base_url" }] },
+ *       { "ref": "call", "type": "rest", "label": "Call", "values": { "base_url": "{{steps.guard.base_url}}",
+ *         "http_method": "get", "headers": [{ "name": "Accept", "value": "application/json" }] } }
+ *     ]
+ *   }
+ * `scriptFile` (resolved relative to the spec file) is sugar for `script`.
+ */
+async function runDefineAction(flags, bare) {
+    var bareErr = bareStringFlagError("define-action", bare, ["sys-id", "scope", "spec", "update-set"]);
+    if (bareErr) {
+        process.stderr.write(bareErr);
+        return 1;
+    }
+    var sysId = flags["sys-id"] || flags.sysId;
+    var scope = flags.scope;
+    var specPath = flags.spec;
+    if (!sysId || !scope || !specPath) {
+        process.stderr.write("define-action: --sys-id <sys_id>, --scope <scope name|sys_id> and --spec <spec.json> are required\n");
+        return 1;
+    }
+    var rawSpec = JSON.parse(fs.readFileSync(specPath, "utf8"));
+    if (!rawSpec || typeof rawSpec !== "object" || Array.isArray(rawSpec)) {
+        process.stderr.write("define-action: --spec must contain a JSON object\n");
+        return 1;
+    }
+    resolveStepScriptFiles(rawSpec, specPath);
+    var result = await (0, defineActionType_1.defineActionType)({
+        client: (0, client_1.createClient)({}),
+        sysId: sysId,
+        scope: scope,
+        spec: rawSpec,
+        confirm: flags.confirm === "true",
+        dryRun: flags["dry-run"] === "true",
+        publish: flags.publish === "true",
+        updateSetSysId: flags["update-set"],
+    });
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return result.verify && !result.verify.ok ? 1 : 0;
+    }
+    var d = result.diff;
+    process.stdout.write("[" + result.status + "] " + result.after.action.name + " (" + result.sysId + ") in " +
+        result.scope.name + "\n");
+    d.action.forEach(function (c) {
+        process.stdout.write("  action." + c.field + ": '" + c.before + "' -> '" + c.after + "'\n");
+    });
+    var named = function (kind, part) {
+        part.added.forEach(function (n) {
+            process.stdout.write("  + " + kind + " " + n + "\n");
+        });
+        part.changed.forEach(function (c) {
+            process.stdout.write("  ~ " + kind + " " + c.name + ": " +
+                c.changes.map(function (f) {
+                    return f.field + " '" + f.before + "' -> '" + f.after + "'";
+                }).join(", ") + "\n");
+        });
+        part.removed.forEach(function (n) {
+            process.stdout.write("  - " + kind + " " + n + "\n");
+        });
+    };
+    named("input", d.inputs);
+    named("output", d.outputs);
+    var stepLine = function (sign, s) {
+        process.stdout.write("  " + sign + " step " + s.order + " '" + s.label + "' [" + s.type + "] " + s.cid +
+            (s.ref ? " (ref " + s.ref + (s.matchedBy ? ", matched by " + s.matchedBy : "") + ")" : "") + "\n");
+        s.changes.forEach(function (c) {
+            process.stdout.write("      " + c + "\n");
+        });
+    };
+    d.steps.added.forEach(function (s) { stepLine("+", s); });
+    d.steps.changed.forEach(function (s) { stepLine("~", s); });
+    d.steps.removed.forEach(function (s) { stepLine("-", s); });
+    if (d.empty) {
+        process.stdout.write("  no changes — the spec is already in effect\n");
+    }
+    result.warnings.forEach(function (w) {
+        process.stdout.write("  ! " + w + "\n");
+    });
+    if (result.status === "planned") {
+        process.stdout.write("\nDRY RUN — nothing written. Re-run with --confirm (and --publish to snapshot) to save.\n");
+        return 0;
+    }
+    if (result.verify) {
+        process.stdout.write("\n--- verify (read back from the instance) ---\n  " + (result.verify.ok ? "OK" : "FAILED") + "\n");
+        result.verify.notes.forEach(function (n) {
+            process.stdout.write("  " + (result.verify && result.verify.ok ? "+ " : "! ") + n + "\n");
+        });
+    }
+    if (result.publish) {
+        process.stdout.write("published (HTTP " + result.publish.httpStatus +
+            (result.publish.snapshotSysId ? ", snapshot " + result.publish.snapshotSysId : "") + ")\n");
+    }
+    return result.verify && !result.verify.ok ? 1 : 0;
+}
+/** Replace each step's `scriptFile` with `script`, read relative to the spec file. */
+function resolveStepScriptFiles(spec, specPath) {
+    var steps = spec.steps;
+    if (!Array.isArray(steps)) {
+        return;
+    }
+    var specDir = path.dirname(path.resolve(specPath));
+    for (var i = 0; i < steps.length; i += 1) {
+        var step = steps[i];
+        if (!step || typeof step !== "object" || typeof step.scriptFile !== "string") {
+            continue;
+        }
+        if (typeof step.script === "string") {
+            throw new Error("define-action: step '" + String(step.ref) + "' sets both scriptFile and script — pick one.");
+        }
+        step.script = fs.readFileSync(path.resolve(specDir, step.scriptFile), "utf8");
+        delete step.scriptFile;
+    }
+}
 async function runMcp(flags) {
     if (flags.smoke === "true") {
         await (0, server_1.runSmoke)();
@@ -1215,6 +1355,13 @@ function printHelp() {
         "                      [--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" +
+        "  define-action      Define a Custom Action Type's inputs, outputs and steps (script + REST,\n" +
+        "                     data-pill wired) the way the Designer's Save does, then optionally publish\n" +
+        "                     DRY-RUN BY DEFAULT — nothing is written without --confirm\n" +
+        "                     (--sys-id <sys_id> --scope <scope name|sys_id> --spec <spec.json>\n" +
+        "                      [--update-set <sys_id>] [--publish] [--confirm] [--dry-run] [--json])\n" +
+        "                     Idempotent: a spec already in effect makes no write. The action shell\n" +
+        "                     must exist (clone-action or the Designer).\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" +
@@ -2424,6 +2571,9 @@ async function main() {
     if (parsed.command === "clone-action") {
         return await runCloneAction(parsed.flags, parsed.bare);
     }
+    if (parsed.command === "define-action") {
+        return await runDefineAction(parsed.flags, parsed.bare);
+    }
     if (parsed.command === "create-view") {
         await runCreateView(parsed.flags);
         return 0;

package/dist/flowDesigner/actionDefineTemplates.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Designer-shaped templates for `defineActionType` — GENERATED from two real
+ * Flow Designer saves of a Custom Action Type (the PUT to
+ * /api/now/processflow/action/action_types/{id}). Do not hand-edit the shapes:
+ * they are the exact key sets the Designer sends, with values reset to the
+ * step type's defaults. Record ids that belong to the STEP TYPE (each step
+ * input's `id` is its sys_hub_step_type input definition) are kept; ids that
+ * belong to one action (variable records, cids, uiUniqueIds) are blanked and
+ * minted fresh per use.
+ *
+ * Regenerate from new captures rather than editing by hand.
+ */
+export interface StepTypeTemplate {
+    /** sys_hub_step_type sys_id. */
+    stepTypeId: string;
+    /** The PUT body's DB_TYPE for this step type. */
+    dbType: string;
+    /** Outputs every step of this type exposes (`{{step[cid].<name>}}`). */
+    builtinOutputs: Array<{
+        name: string;
+        label: string;
+        type: string;
+    }>;
+    /** One PUT-shaped step with values at their defaults. */
+    template: Record<string, unknown>;
+}
+export declare var STEP_TYPE_TEMPLATES: Record<"script" | "rest", StepTypeTemplate>;
+/** A new action input (sys_hub_action_input) as the Designer first sends it. */
+export declare var ACTION_INPUT_TEMPLATE: Record<string, unknown>;
+/** A new action output (sys_hub_action_output) wired to a data pill. */
+export declare var ACTION_OUTPUT_TEMPLATE: Record<string, unknown>;
+/** A new script-step input variable (extended_inputs entry). */
+export declare var STEP_EXT_INPUT_TEMPLATE: Record<string, unknown>;
+/** A new script-step output variable (extended_outputs entry). */
+export declare var STEP_EXT_OUTPUT_TEMPLATE: Record<string, unknown>;