@jacebenson/jsn 4.3.7 → 4.3.8-dev.46

package/README.md

@@ -31,6 +31,19 @@ npm install -g @jacebenson/jsn
 
 **Note:** git installs build `better-sqlite3` (docs search) from source, so the machine needs build tools (Python, make, a C++ compiler).
 
+## Direct MID installation
+
+```sh
+jsn midservers add --install-method direct --name worker1
+```
+
+Official x86-64 ZIPs for Linux and Windows, selected from the instance's
+`mid.version`. Credentials are prompted and validated before installation.
+Linux supports a user-owned background runtime. Windows currently prepares
+private files and offers a foreground console, not native service registration.
+See [direct MID installation](docs/mid-direct-install.md) for security boundaries,
+lifecycle commands and the untested Windows host phases. Docker remains available.
+
 ## Quick Start
 
 ```bash
@@ -59,6 +72,7 @@ jsn flows executions --since "2026-08-25 00:00:00" --until "2026-08-26 00:00:00"
 jsn flows executions --summary                 # Server totals + sampled duration metrics by flow
 jsn flows executions --limit 100               # Inspect more rows from the matching population
 jsn flows executions --record <sys_id>        # Executions for one source record
+jsn flows create --data-file flow.manifest.json # Create a draft record-triggered flow
 jsn rules list --query "collection=incident"
 jsn updatesets set "My Feature"
 
@@ -72,10 +86,19 @@ jsn records bulk --table incident --query "priority=1" --set '{"state":"3"}'  #
 jsn records get --table incident --sys-id 8a1234abcd5678 --attachments        # record + its files
 jsn records list --table incident --limit 10 --csv                            # output CSV
 
+# Read-only cross-profile record diff
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --ignore state
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --no-ignore
+
 # Script execution
 jsn eval "gs.info('Hello World')"
 cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)
 
+# Now GraphQL (documents may contain mutations; read-only profiles are blocked)
+jsn graphql --query '{ GlideRecord_Query { incident(pagination: {limit: 2}) { _results { number { value } } } } }'
+cat incident.graphql | jsn graphql --stdin --variables '{"limit":2}'
+
 # Saved query snippets (stored locally, run against the active profile)
 jsn snippets save open-inc --table incident --query "active=true"
 jsn snippets run open-inc
@@ -84,8 +107,223 @@ jsn snippets run open-inc
 jsn logs follow --level error --tail 10
 ```
 
+### Update set completion
+
+```bash
+jsn updatesets complete                         # Current set, opens a notes editor in a human terminal
+jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
+```
+
+`complete [name]` saves concise bullet-list notes in the selected set's Description
+and marks it complete. Omit the name to use the current set. Explicit names
+must be unique; for duplicate names, select the intended set with `updatesets set`
+and complete it without a name. ServiceNow's normal batch completion rules still
+apply: completing a parent can complete its children. Notes are not copied to children.
+
+Existing Description text is preserved exactly. The command shows it and asks
+before appending notes, unless `--force` or the profile's `skip_confirmations`
+policy explicitly allows the append. Scripts and JSON output must supply
+nonempty `--notes`; they never open prompts. Separate multiple notes with real
+newlines. Success requires readback of both Description and state. If verification
+fails, inspect the set before retrying because the write may have partially succeeded.
+
+### Flow Designer actions
+
+`actions` and `action` are the same command. `list`, `show`, and explicit
+`delete` remain available. In a human terminal, omit the target to open a
+searchable picker. Create and edit guide you through provider schemas and save
+full Process Flow definitions, not ordinary table-field updates.
+
+```bash
+jsn actions create                 # Guided scope, name, schemas, inputs and script
+jsn actions edit                   # Pick an action, edit its saved definition
+jsn actions definition             # Pick and inspect a complete definition
+jsn actions test --wait            # Pick an action, supply saved-schema inputs, confirm
+jsn actions step-types             # Pick the exact transaction scope
+```
+
+Script inputs offer a file path or your `$VISUAL`/`$EDITOR`. New script steps can
+declare outputs and map them to action outputs. Variable declarations reuse
+provider schema templates and receive fresh UI identities. Unknown nested
+schema fields are retained. Unsupported input types stop with instructions to
+use `--data-file`; JSN does not silently omit them or invent schema defaults.
+Creation waits for an explicit final confirmation before allocating a parent.
+It saves a draft only and never publishes or runs it automatically.
+
+For automation, keep using explicit identifiers and full JSON:
+
+```bash
+jsn actions step-types --scope <scope_sys_id> --get data > step-types.json
+jsn actions create --scope <scope_sys_id> --data-file new-action.json --json
+jsn actions definition <action_sys_id> --get data > action.json
+# Edit action.json, retaining its ID, scope, lifecycle fields and all arrays.
+jsn actions update <action_sys_id> --data-file action.json --json
+jsn action edit <action_sys_id> --data-file action.json --json  # same operation
+jsn actions test <action_sys_id> --force --output-map '{"response":"hello"}' --wait --timeout 60 --json
+jsn actions test <action_sys_id> --force --data-file action.json --output-map '{"response":"hello"}' --wait --get data.outputs.response.value
+jsn actions delete <action_sys_id> --force  # explicit cleanup, never automatic
+```
+
+Existing targets infer their exact transaction scope from the action record.
+An explicit `--scope` must match that record byte-for-byte and exist in
+`sys_scope`. For Global, use the literal sys_id `global`.
+
+This **illustrative create document** shows an input/script/output mapping.
+Replace `<SCRIPT_STEP_TYPE_SYS_ID>` with the target's `step-types` result.
+Start from that step type's full input/output schemas, preserving runtime
+settings, status outputs and any other required fields. The shortened example
+is not a captured or instance-verified template. New steps/variables need their
+own identifiers; do not clone another action's record IDs. Leave new steps'
+`step_id` and `action` blank or omitted. Create binds their `action` to the newly
+allocated parent; persisted step IDs or parent bindings are rejected before creation.
+
+```json
+{
+  "name": "Echo response",
+  "description": "Return the supplied response",
+  "internal_name": "echo_response",
+  "inputs": [{"name": "response", "label": "Response", "type": "string", "mandatory": true}],
+  "outputs": [{"name": "response", "label": "Response", "type": "string", "value": "{{step[11111111-2222-4333-8444-555555555555].response}}"}],
+  "steps": [{
+    "cid": "11111111-2222-4333-8444-555555555555",
+    "step_type": "SCRIPT",
+    "step_type_id": "<SCRIPT_STEP_TYPE_SYS_ID>",
+    "label": "Echo script",
+    "order": 1,
+    "inputs": [
+      {"name": "required_run_time", "type": "choice", "value": "instance"},
+      {"name": "script", "type": "script", "value": "(function execute(inputs, outputs) { outputs.response = inputs.response; })(inputs, outputs);"}
+    ],
+    "outputs": [],
+    "extended_inputs": [{"name": "response", "type": "string", "value": "{{inputs.response}}", "extended": true}],
+    "extended_outputs": [{"name": "response", "type": "string", "extended": true}]
+  }]
+}
+```
+
+Create first inserts the parent in `sys_hub_action_type_definition`, reads that
+parent's own Process Flow defaults, then saves the inputs, outputs and nonempty
+steps with the internal `/api/now/processflow/action/action_types/{id}` PUT.
+It retains fresh lifecycle/status metadata instead of copying source snapshot
+or status IDs. A subsequent definition GET plus `/step_instances` GET verifies
+scripts, mappings and schemas. Update requires a complete document from
+`definition`, including target-owned lifecycle fields. Omitted fields are
+rejected before mutation. A PUT timeout triggers readback, not another PUT;
+`persisted_after_timeout` means persistence was verified, not that HTTP success
+was received. Failed creation reports the parent ID and leaves cleanup to you.
+
+Test sends `action`, `outputMap`, `runOnThread` and `tracingEnabled` to `/test`.
+Despite its wire name, `--output-map` supplies **action inputs**. Without
+`--wait`, success means dispatch only, with `status: dispatched` and no outputs.
+With `--wait`, JSN requires a `COMPLETE` context, blank `error_message`, and each
+declared user output's actual value from `sys_flow_runtime_value`. Output entries
+have `value`, `displayValue` and `hasValue`; false, zero and empty strings count.
+Failures, denied/missing outputs and timeouts exit nonzero. The wait budget
+starts after dispatch, defaults to 60 seconds, and is capped at 3600 seconds.
+Timeout does not cancel the server execution. Draft actions can be tested without
+publication. Testing runs their scripts and can have side effects. It requires
+interactive confirmation or `--force`, unless the profile explicitly skips
+confirmations. Read-only profiles block create/update/delete/test. No publish
+or snapshot command is added.
+These internal endpoints and runtime-table permissions can vary by instance.
+
 ### Flow execution fields
 
+### Flow Designer terminal workflows
+
+```bash
+jsn flows create         # Guided record trigger and published action inputs
+jsn flows edit           # Pick an inactive Draft, edit condition or existing inputs
+jsn flows show           # Pick a flow to inspect
+jsn flows status         # Pick a flow to diagnose
+jsn flows test           # Pick flow and a record from its actual trigger table, confirm
+jsn flows publish        # Pick a flow, explicitly confirm activation
+# Automation must explicitly confirm publication too:
+jsn flows publish <flow_sys_id> --force --json
+```
+
+Wizards and omitted-target pickers require both a prompt-capable terminal and
+`auto` output. `--json`, explicit formats, `--get`, `--data`, `--data-file`,
+`--output-map`, pipes, `CI`, `NONINTERACTIVE` and `JSN_NO_PROMPTS=1` never open a
+wizard. In those modes provide identifiers and required scope/record/data
+explicitly. Tests, publish and deletion require `--force` or the profile's
+existing explicit skip-confirmations setting when prompting is unavailable.
+Read-only profiles still block mutations before authentication or prompting.
+Press Escape in record pickers or Ctrl+C in any wizard to cancel. Refusing a
+final confirmation leaves the instance untouched.
+
+Existing action/flow scopes come from saved raw identifiers. New scopes offer
+the active application preference if available, then a searchable scope picker.
+No scope name is guessed. Input pills are passed through unchanged.
+
+Flow edits are limited to the existing manifest contract. They do not rename
+flows, add/remove steps, implement Flow Logic, subflows, variables or error
+handling. Flow deletion remains unsupported. Action deletion retains its
+existing explicit parent-record cleanup and absence readback, not a new native
+builder deletion lifecycle. See [command coverage and local proof](docs/flow-designer-interactive.md).
+
+### Flow creation manifest
+
+`jsn flows create` accepts `--data-file` or inline `--data`, or guides human
+terminal users without those options. The supported slice
+supports one `record_create_or_update` trigger and published Action types whose
+input schemas are available from the instance. JSN resolves action metadata,
+defaults, and typed inputs from ServiceNow; callers do not provide GraphQL or
+editor-generated identifiers.
+
+```json
+{
+  "name": "JSN-STUDY-ticket-log",
+  "description": "Log JSN study tickets",
+  "scope": "<SCOPE_SYS_ID>",
+  "trigger": {
+    "type": "record_create_or_update",
+    "table": "ticket",
+    "condition": "short_descriptionSTARTSWITHJSN-STUDY-"
+  },
+  "actions": [
+    { "type": "Log", "inputs": { "log_level": "info", "log_message": "Ticket received" } }
+  ]
+}
+```
+
+`scope` is required; JSN never defaults it to a tenant-specific or captured
+scope. The record-trigger condition currently accepts one simple encoded-query
+predicate (`fieldSTARTSWITHvalue`, `field=value`, `fieldLIKEvalue`, and the
+equivalent single-predicate operators). Compound `^`/`^OR` expressions are
+rejected until their predicate AST mapping is proven against the instance.
+
+Creation leaves the flow in Draft and inactive, then creates and reads back an
+Autosave version. `flows publish` remains a separate lifecycle operation: it
+reads the saved ProcessFlow definition, POSTs `/snapshot`, creates an
+`Activate/Publish` version, reads version history, and verifies `active=true`.
+Do not use it in a dry-run: publishing activates the flow.
+
+`jsn flows test <identifier> --record <sys_id>` is also a mutating operation.
+It requires confirmation (or `--force`), reads the saved definition, verifies
+that the supplied record exists in the record-trigger table, and POSTs the full
+definition to the ProcessFlow test endpoint. A response with only a context ID
+is reported as accepted, not completed. Test runs execute actions and can have
+side effects; this slice does not execute test flows during development.
+
+Flow Logic, subflows, flow-variable lifecycle, and error handling are deferred
+and rejected by this slice rather than silently ignored.
+
+`jsn flows update <identifier> --data-file update.json` updates supported fields
+of existing inactive Draft flows. The manifest may contain only `trigger` (with
+`table` and/or `condition`) and `actions`. Each action selects one saved instance
+by its one-based `order` and reusable action `type` (name or sys_id). Its `inputs`
+object may change only inputs already present in that saved Action. The CLI reads
+the saved component identities itself; manifests never carry UI UUIDs. Omitted
+trigger fields, Action inputs, metadata, and other flow components are preserved.
+Names must resolve to exactly one flow, and the protected `jace-test-flow` is
+rejected. Update sends the captured GraphQL `triggerInstances.update` and/or
+`actions.update` shapes, reads the full ProcessFlow definition back, creates an
+Autosave version, and reports update-set captures. It never publishes or
+activates the flow. Unsupported Flow Logic, subflows, variables, error handling,
+new Action inputs, ambiguous selectors, active flows, and non-Draft flows are
+rejected before mutation.
+
 `jsn flows executions` reads `sys_flow_context` and returns both the raw row and a normalized `execution` object. JSN discovers the runtime columns from `sys_dictionary` first, then uses these mappings:
 
 - `started`: `started`, `start_time`, `started_at`, then `sys_created_on`
@@ -110,10 +348,31 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 **User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`
 
-**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
+**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `diff record` (cross-profile read-only comparison), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
+
+**Platform** — `platform health` (cluster records) and `platform stats` (bounded, read-only `/xmlstats.do` summary; allowlisted metrics only)
 
 Every command supports `--json`, `--query`, and `--help`.
 
+For multiline script fields, `--data-file` parses the file as UTF-8 JSON and
+passes the resulting values through unchanged. On Windows PowerShell, generate
+the payload as JSON text and inspect it before invoking JSN, for example:
+
+```powershell
+$script = [string](Get-Content -Path .\Example.script.js -Raw)
+$payload = @{ script = $script; description = 'Example' } |
+  ConvertTo-Json -Depth 5 -Compress
+Set-Content -Path .\Example.update.json -Value $payload -Encoding UTF8
+Get-Content .\Example.update.json -Raw | ConvertFrom-Json | Select-Object -ExpandProperty script
+jsn includes update Example --data-file .\Example.update.json --json
+```
+
+`JSON.parse` preserves a JSON string as a JavaScript string, and the SDK
+serializes update payloads with `JSON.stringify`. If the file already contains
+a `{value=...}` or FileSystem-provider representation, that text is external
+to JSN and must be corrected before the update. Use a read-back command or
+`records update --strict` where applicable to verify persisted fields.
+
 ## Instances
 
 Switch between instances without re-authenticating.
@@ -162,6 +421,12 @@ export SERVICENOW_OAUTH_TOKEN="***"
 jsn incidents list
 ```
 
+For the credential identity, auth-method, diagnostics, migration, and concurrency contract, see [`docs/AUTH_LIFECYCLE.md`](docs/AUTH_LIFECYCLE.md).
+
+GraphQL uses ServiceNow's `/api/now/graphql` endpoint and sends `{query, variables}` through the authenticated SDK transport. The command preserves GraphQL `data` and `errors`; introspection and available namespaces depend on the target instance.
+
+`jsn platform stats` uses a fixed `GET /xmlstats.do` request. It never accepts a processor path, query parameters, or request body, and it does not emit raw XML, cookies, credentials, or full node identifiers. Oversized, HTML/login, permission, unsupported, timeout, and malformed responses are reported with bounded collector statuses; missing metrics remain unavailable rather than being reported as zero.
+
 ## Local data
 
 JSN stores durable local data under `~/.jsn/`. Documentation lives in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.7",
+  "version": "4.3.8-dev.46",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/skills/servicenow/SKILL.md

@@ -73,6 +73,22 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 | **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
 | **Developer** | `eval`, `rest`, `skill`, `version` |
 
+### Complete an update set
+
+```bash
+jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
+```
+
+`complete [name]` defaults to the current set when the name is omitted. Explicit
+names must be unique. Supply nonempty `--notes` in automation; real newlines
+separate bullets. A human terminal opens a notes editor when `--notes` is absent.
+Existing Description text is preserved and appended after confirmation. Use
+`--force` only after approval, or the profile's `skip_confirmations` policy.
+Notes apply only to the selected set. ServiceNow's normal batch rules can complete
+child sets when the parent completes; their descriptions are not replaced.
+Both selected-set Description and state are read back before success. On
+verification failure, inspect the set before retrying.
+
 ### Table and raw REST examples
 
 ```bash

package/src/app.js

@@ -14,6 +14,7 @@ import { saveConfig } from './config.js';
 import { resolveSession, applySession, contextFromSession, requireSessionInstance } from './session.js';
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
+import { canPrompt } from './helpers.js';
 import { isMutationCommand } from './mutations.js';
 import process from 'node:process';
 
@@ -190,8 +191,14 @@ export class App {
     this.output.err(error);
   }
 
+  /**
+   * True only when a human can actually answer a prompt. Delegates to
+   * canPrompt() so the check is "both stdio descriptors are TTYs AND no
+   * agent/CI/opt-out marker is set" — a PTY allocated for an agent
+   * (stdout.isTTY true, JSN_NO_PROMPTS/CI set) is NOT interactive.
+   */
   isInteractive() {
-    return process.stdout.isTTY === true;
+    return canPrompt();
   }
 
   requireInstance() {

package/src/auth.js

@@ -41,30 +41,32 @@ function credKey(instance, username) {
 
 // ─── PKCE state persistence (shared with Go version) ───
 
-function pkceStatePath(instance) {
+function pkceStatePath(instance, username) {
   const dir = path.join(globalConfigDir(), 'pkce');
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const filename = sanitizeKeyPart(instance) + '.json';
+  // A known profile identity gets its own pending-login slot. Keep the bare
+  // instance slot for legacy/no-profile flows, where no identity exists yet.
+  const filename = credKey(instance, username) + '.json';
   return path.join(dir, filename);
 }
 
-function savePKCEState(instance, pkce) {
-  const filePath = pkceStatePath(instance);
+function savePKCEState(instance, pkce, username) {
+  const filePath = pkceStatePath(instance, username);
   fs.writeFileSync(filePath, JSON.stringify(pkce, null, 2), { mode: 0o600 });
 }
 
-function loadPKCEState(instance) {
+function loadPKCEState(instance, username) {
   try {
-    const data = fs.readFileSync(pkceStatePath(instance), 'utf-8');
+    const data = fs.readFileSync(pkceStatePath(instance, username), 'utf-8');
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 
-function removePKCEState(instance) {
+function removePKCEState(instance, username) {
   try {
-    fs.unlinkSync(pkceStatePath(instance));
+    fs.unlinkSync(pkceStatePath(instance, username));
   } catch {
     // ignore
   }
@@ -746,7 +748,7 @@ export class AuthManager {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = generatePKCE();
-    savePKCEState(instanceURL, pkce);
+    savePKCEState(instanceURL, pkce, username);
     const url = buildAuthURL(instanceURL, clientID, pkce);
     if (waitFile) {
       console.log(url);
@@ -766,7 +768,7 @@ export class AuthManager {
         const code = fs.readFileSync(filePath, 'utf-8').trim();
         if (code) {
           console.log(`\nAuthorization code found in ${filePath}`);
-          removePKCEState(instanceURL);
+          removePKCEState(instanceURL, username);
           const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
           this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
           console.log('Token exchange successful!\n');
@@ -838,7 +840,7 @@ export class AuthManager {
   async loginWithCode(instanceURL, code, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
-    const pkce = loadPKCEState(instanceURL);
+    const pkce = loadPKCEState(instanceURL, username);
     if (!pkce) {
       throw errAuth(
         `No pending login session for ${instanceURL}.\n\n` +
@@ -848,7 +850,7 @@ export class AuthManager {
         `  jsn auth login ${instanceURL} --code CODE`
       );
     }
-    removePKCEState(instanceURL);
+    removePKCEState(instanceURL, username);
 
     const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
     this.saveCredentials(instanceURL, newCreds, username || newCreds.username);