@jacebenson/jsn 4.3.12 → 4.3.13-dev.101.1

package/README.md

@@ -13,6 +13,87 @@ jsn setup
 
 See the [setup guide](docs/docs-setup.md) to connect an instance safely.
 
+### Dev channel
+
+For the newest changes from `main`, including changes that may be unstable:
+
+```bash
+npm install -g @jacebenson/jsn@dev
+```
+
+Dev builds check the dev channel for updates during normal use, at most once
+per day. Run `jsn version --check` to check immediately. To install the newest
+dev build, run `npm install -g @jacebenson/jsn@dev` again. Updates are manual.
+Return to stable with `npm install -g @jacebenson/jsn@latest`.
+
+Pushes to `main` promote the commit to `dev` and publish a tested prerelease
+under npm's `dev` tag. Versions include the workflow run number and attempt
+(for example, `4.3.9-dev.123.1`); they do not move npm's stable `latest` tag.
+The npm trusted publisher for `publish-dev.yml` must authorize the repository's
+`dev` GitHub environment, alongside the production publishing configuration.
+
+### Instance Scan
+
+`jsn scan` manages checks and suites and runs scans against an explicit target.
+Use `jsn scan --help` and each subcommand's `--help` to discover the options.
+
+```bash
+jsn scan checks list --profile dev
+jsn scan checks create --type table --data-file check.json --profile dev
+jsn scan checks activate <check-id> --profile dev
+jsn scan suites add-check <suite-id> --check <check-id> --profile dev
+jsn scan run --update-set "My change" --suite "My suite" --wait --profile dev
+jsn scan run --table sys_script_include --record <record-id> --profile dev
+jsn scan results <execution-id> --profile dev
+```
+
+Check types are `table`, `column`, `linter`, and `script`. Definitions are created
+inactive unless the payload explicitly sets `active: true`; activation never
+starts a scan. Both checks and suites support list/show/create/update/delete and
+activate/deactivate. Suites also support add-check/remove-check.
+
+Runs require an update set, scope, record plus table, or explicit `--full`.
+Instance-wide scans may traverse many tables even when a check's script only
+examines a few records. Starting and cancelling a scan require confirmation;
+use `--force` only after approving that operation. `--wait --timeout 120` bounds
+the wait, not the scan's lifetime. A timed-out wait keeps the execution id and
+does not cancel or resubmit the scan. Use `status`, `results`, or `cancel` next.
+
+Update-set scans examine current instance records, not the historical XML
+versions. Inactive records may be skipped. Script-only checks do not participate
+in record/update-set scans; use an explicitly instance-wide suite run to execute
+them. Execution success does not mean zero findings or complete test coverage:
+results report recorded check executions, finding counts, unreadable sources,
+and truncated lists separately. A result's rerun hint preserves the previous
+target combination and requires `--full` again for instance-wide scans.
+
+Every command returns next-step breadcrumbs in human and JSON output, retaining
+an explicitly selected profile or instance. `updatesets show` also offers a scan
+hint. Recommendation/generation of new checks is not part of this command;
+JSN contains no AI and does not infer missing business requirements.
+
+### Supported versions
+
+Only the current release and the two preceding releases in each channel are
+supported (three stable releases and three dev builds). For example, with
+stable `4.3.11`, versions `4.3.11`, `4.3.10`, and `4.3.9` are supported.
+Update to the newest version in your channel before reporting an issue.
+
+After each successful npm publish, deployment deprecates older versions in that
+channel. Deprecated versions remain installable and appear in history, but npm
+prints an update warning on installation. Existing deprecation messages are
+preserved. No versions are unpublished.
+
+The deprecation step uses the repository's `NPM_TOKEN` secret with permission to
+modify `@jacebenson/jsn` and noninteractive authentication (including bypass 2FA
+where required). Publishing continues to use OIDC. A deprecation failure fails
+the workflow after publishing; it does not roll back the published package.
+To retry only deprecation after fixing authentication, use the matching release
+checkout and run `node scripts/deprecate-old-versions.mjs latest --apply` (or
+`dev --apply`) with npm authentication configured and `NODE_AUTH_TOKEN` set.
+Omit `--apply` to preview the affected versions without changing npm. The script
+requires the checkout's package version to match the channel's current npm tag.
+
 ## Try it
 
 ```bash
@@ -37,3 +118,17 @@ npm test
 ## License
 
 MIT
+
+
+### Commands for the connected account
+
+Login and OAuth refresh check for the current account's `admin` role. Profiles
+without that role show a compact command list focused on tickets, generic
+records, people/groups, documentation, and connection management. If the role
+check is unavailable, the profile also uses compact help; this does not assert
+that the account lacks admin. Existing profiles keep full help until renewed.
+
+This applies to root help, root JSON, `discover`, and root shell completion.
+Use `jsn --all-commands --help` or `jsn discover --all-commands --json` to inspect
+every registered command. Explicit command paths remain available and ServiceNow
+ACLs decide access. Reauthenticate (or refresh OAuth) after roles change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.12",
+  "version": "4.3.13-dev.101.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -32,6 +32,7 @@
     "@inquirer/prompts": "^7.5.1",
     "better-sqlite3": "^13.0.3",
     "js-yaml": "^5.5.0",
+    "saxes": "^6.0.0",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/skills/servicenow/SKILL.md

@@ -1,185 +1,33 @@
 ---
 name: servicenow
-description: |
-  Interact with ServiceNow instances via the jsn CLI. Use when working with ServiceNow
-  development, administration, or data exploration. Handles tables, records, business rules,
-  flows, script includes, ACLs, update sets, and more. Triggered by ServiceNow URLs
-  (service-now.com, servicenow.com) or when the user mentions ServiceNow, jsn, servicenow,
-  or related terms like tables, records, business rules, flows, script includes, ACLs,
-  update sets, or encoded queries.
+description: Use the jsn CLI for ServiceNow development, administration, and data exploration.
 license: MIT
-compatibility: |
-  Requires jsn CLI (github.com/jacebenson/jsn). Install via:
-  npm install -g @jacebenson/jsn
-  Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
 metadata:
   author: jacebenson
-  version: "4.3.6"
+  version: "4.3.13"
   repository: https://github.com/jacebenson/jsn
 ---
 
-# Jace's ServiceNow CLI (jsn)
+# ServiceNow with JSN
 
-Explore and manage ServiceNow instances. Interactive paginated pickers with server-side search on all list commands.
+Discover commands with `jsn --help`, `jsn discover "search words"`, and
+`jsn <command> --help`.
 
-## Discovery
+- Verify the intended instance and select it explicitly with `--profile <name>`.
+- Prefer purpose-built or records commands over `eval`. Explain the need and get
+  approval before using eval; avoid bypassing ServiceNow protections.
+- Honor delete confirmations. Get approval for destructive work and Global +
+  Default mutations; use `--force` only for the approved operation.
 
-```bash
-jsn --help                # All commands grouped by domain
-jsn <command> --help      # Flags, subcommands, and examples
-```
+For development:
 
-## Interactive Picker
+1. Choose or create the application scope and update set.
+2. Do the work, keeping related changes together.
+3. Verify the results on the instance and report where changes were captured.
+4. Offer to run relevant existing ATFs and instance scans, or create missing checks.
+5. Ask whether anything else belongs in the update set. If the user confirms
+   it is finished, complete it with notes.
 
-All `list` subcommands use a paginated interactive picker in TTY mode:
-- Arrow through items (10 per page)
-- Type to search (server-side LIKE query)
-- Scroll past last loaded item to load next page
-- Enter to select, Esc to cancel
-- Falls back to table output with `--json`
-
-## Agent Rules
-
-1. **Output modes** — `--json` when parsing data; text when presenting to humans
-2. **Use sys_id for updates** — All update/delete operations require sys_id
-3. **Check auth first** — Run `jsn auth status` before operations
-4. **NEVER logout** — Only run `jsn auth logout` if the user explicitly asks
-5. **Use `--profile <name>`** to target a specific instance, or `jsn auth switch <name>` to change the default
-6. **Before using `eval` or `rest`** — Ask: *"Is there a more specific jsn command?"* Prefer specific over generic over escape hatch over eval.
-7. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
-
-## Command Hierarchy
-
-Pick the most specific tool for the job. **Never default to eval** — it's the last resort:
-
-1. **Specific commands** — `jsn flows`, `jsn rules`, `jsn catalogitems`, etc.
-2. **`jsn records --table <name>`** — generic CRUD on any table
-3. **`jsn docs search <query>`** — offline ServiceNow documentation search (no instance needed)
-4. **`jsn rest`** — raw Table API escape hatch
-5. **`jsn eval`** — ⚠️ **LAST RESORT ONLY**
-6. **Ask the human** — if none of the above work
-
-## Key Commands
-
-| Domain | Commands |
-|--------|---------|
-| **Core** | `incidents`, `changes`, `requests`, `tasks` |
-| **Catalog** | `catalogitems list/show/create` — items with variables and flow info |
-| **Automation** | `flows`, `actions`, `rules`, `triggers`, `scheduledjobs` |
-| **Access** | `acls`, `b4rules`, `roles`, `groups`, `users` |
-| **UX** | `forms` (section/element layout), `lists`, `clientscripts`, `uipolicies` |
-| **Data** | `tables`, `columns`, `includes`, `logs`, `properties`, `records` |
-| **Config** | `setup`, `auth`, `updatesets`, `scopes` |
-| **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
-| **Developer** | `eval`, `rest`, `skill`, `version` |
-
-### Customization evidence
-
-```sh
-jsn customizations capture --label review --customer-scope x_acme_app --json
-jsn customizations list --json
-jsn customizations show <run_id> --get data.categories
-jsn customizations show <run_id> --get data.triage
-jsn customizations html <run_id> [--out review.html]
-jsn customizations compare <baseline_id> <new_id> --json
-```
-
-Capture performs bounded GET-only table reads and saves local reports. It never
-evals or creates, updates or deletes instance records. Standard authentication
-may refresh OAuth tokens, store refreshed credentials locally and bootstrap a
-session/GCK using authentication POSTs. List/show/compare are offline.
-Declare customer ownership with repeatable `--customer-scope` values or sys_ids;
-never infer customer ownership from a non-global scope. The declaration is
-caller evidence, not independent publisher verification. OOTB findings reflect
-historical upgrade skips, not a current verified baseline deviation. The upgrade
-history is read server-side for the skip dispositions and every observed skipped
-`file_name` is resolved against `sys_metadata` by chunked
-`sys_update_nameIN<chunk>` lookups, so the OOTB inventory covers the observed
-skipped artifacts; the broad `sys_metadata` read is an arbitrary `sys_id`-ordered
-slice and is reported as a bounded sample, not an inventory, describing only the
-unclassified and declared-customer categories. Unresolved skipped names and
-failed lookup chunks stay explicit rather than becoming absent artifacts, and a
-resolved artifact can lack a scope name when its scope record was outside the
-bounded `sys_scope` read. Missing
-ACL access, pagination limits and unmatched evidence remain explicit. All
-reports are incomplete; no findings is not proof of no customizations.
-Comparisons cover captured metadata/evidence, not source payloads. Removals mean
-no longer observed, not proven deletion. Reversion impact and dependencies
-remain unknown until separately investigated. Never recommend automatic reversion.
-
-Upgrade history joins `file_name` to metadata `sys_update_name`. Raw disposition
-`4` or `104` is skipped-customization evidence; resolution `reviewed_reverted`
-excludes that history row. Use raw values, not display labels or other skip reasons.
-
-### 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
-# Query a table with the normal records command
-jsn records list --table incident --query "active=true" --limit 5 --json
-
-# Get a single record
-jsn records get --table incident --sys-id abc123... --json
-
-# Raw endpoint access when no specific command fits
-jsn rest "/api/now/table/incident?sysparm_limit=3" --json
-```
-
-### `jsn docs` — offline documentation search
-
-No ServiceNow instance required. Searches the full ServiceNow docs locally with FTS5 + semantic hybrid search.
-
-```bash
-# First run: download docs and build the index (~45k files, ~3-5 min)
-jsn docs sync
-
-# Check state
-jsn docs status
-
-# Search (keyword + semantic hybrid)
-jsn docs search "GlideRecord query" --limit 5 --json
-
-# Filter by bundle
-jsn docs search "REST API" --bundle it-service-management --json
-
-# Start the web UI
-jsn docs serve
-
-```
-
-**Re-running `jsn docs sync`** does a smart incremental refresh — pulls latest docs and only rebuilds changed files (seconds, not minutes).
-
-## Troubleshooting Field Behavior
-
-Check order (priority):
-
-1. **Before-query business rules** — `sys_script` with `when=before`, `action=query`
-   ```bash
-   jsn b4rules list --query "collection=sys_user"
-   ```
-2. **ACLs** — `jsn acls list --query "name=incident"`
-3. **Dictionary overrides** — `jsn records list --table sys_dictionary --query "name=incident^element=caller_id"`
-4. **Client scripts** / **UI policies** — form-level field behavior
-
-## Configuration
-
-```
-~/.config/servicenow/
-├── config.json               # Profiles and settings
-└── credentials/              # Auth tokens (fallback, one file per key)
-```
+For incoming update sets: import the XML, preview the set, and resolve preview
+errors with the human where needed. Once the preview is clear, commit the set
+and verify the results.

package/src/app.js

@@ -7,7 +7,9 @@
 // setEffectiveInstance() are thin session-backed shims kept for the many
 // command handlers that already call them.
 
+import { appendMutation } from './mutation-history.js';
 import { AuthManager } from './auth.js';
+import { createAuthRecovery } from './auth-recovery.js';
 import { SDKClient } from './sdk.js';
 import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled, hyperlink } from './output.js';
 import { saveConfig } from './config.js';
@@ -15,7 +17,7 @@ import { resolveSession, applySession, contextFromSession, requireSessionInstanc
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
 import { canPrompt } from './helpers.js';
-import { isMutationCommand } from './mutations.js';
+import { guardMutationContext } from './mutation-context.js';
 import process from 'node:process';
 
 
@@ -53,8 +55,12 @@ export class App {
 
   /** Build (or rebuild) the SDK client for an instance + session. */
   _buildSdk(instance, session = this.session) {
-    this.sdk = new SDKClient(instance, this.auth, {
+    this.sdk = new SDKClient(instance, this.auth.createProfileProvider(instance, {
+      username: session?.username, authMethod: session?.profile?.auth_method,
+    }), {
       domain: session?.domain || '',
+      recovery: createAuthRecovery({ app: this, session }),
+      onMutation: event => this.recordMutation(instance, session?.profileName, event),
     });
   }
 
@@ -63,9 +69,21 @@ export class App {
     const profile = options.profile || {};
     return new SDKClient(instance, this.auth.createProfileProvider(instance, options), {
       domain: options.domain ?? profile.domain ?? '',
+      onMutation: event => this.recordMutation(instance, options.profileName || null, event),
     });
   }
 
+  recordMutation(instance, profile, event) {
+    if (!this._authArgv) return;
+    try { appendMutation({ ...event, instance, profile, reason: this._authArgv.reason }); }
+    catch {
+      if (!this._historyWarningShown) {
+        process.stderr.write('Warning: local mutation history could not be saved. The remote result is unchanged.\n');
+        this._historyWarningShown = true;
+      }
+    }
+  }
+
   loadContext() {
     this.context = contextFromSession(this.session, this.config);
   }
@@ -74,7 +92,7 @@ export class App {
     return this.session?.instance || '';
   }
 
-  async printContextHeader(argv = {}) {
+  async printContextHeader(_argv = {}) {
     if (!this.getEffectiveInstance() || !this.sdk) return;
     if (process.env.JSN_NO_HEADER) return;
     if (this.output.getFormat() === FormatJSON || this.output.getFormat() === FormatQuiet) return;
@@ -100,12 +118,12 @@ export class App {
 
     // Both lookups depend on the user, but not on one another.
     const [application, selectedUpdateSet] = userSysID ? await Promise.all([
-      getCurrentApplication(this.sdk, userSysID).catch(() => null),
+      getCurrentApplication(this.sdk, userSysID, { unknownWhenMissing: true }).catch(() => null),
       getCurrentUpdateSet(this.sdk, userSysID).catch(() => null),
     ]) : [null, null];
-    const scope = application?.scope || 'global';
+    const scope = application?.scope || 'unknown';
     const updateSet = selectedUpdateSet?.name && selectedUpdateSet.name !== '-'
-      ? selectedUpdateSet.name : 'Default';
+      ? selectedUpdateSet.name : 'unknown';
     const updateSetSysID = selectedUpdateSet?.name && selectedUpdateSet.name !== '-'
       ? selectedUpdateSet.sys_id : '';
     this.context.scope = scope;
@@ -135,43 +153,14 @@ export class App {
 
     process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
 
-    // ⚠️  Warning if in the Default update set (mutation commands only)
-    if (isMutationCommand(argv) && updateSet && updateSet.toLowerCase().includes('default')) {
-      const isGlobal = scope === 'global';
-      if (isGlobal) {
-        // 🔴 HARD WARNING — Global + Default
-        process.stderr.write(
-          '\x1b[31m' + // red
-          '┏━ GLOBAL + DEFAULT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n' +
-          '┃  You are in Global scope with the Default update set.  ┃\n' +
-          '┃  Changes ARE captured — in the Default update set.     ┃\n' +
-          '┃  Moving them to a named update set later requires      ┃\n' +
-          '┃  manual surgery, one change at a time. Avoid the mess. ┃\n' +
-          '┃                                                        ┃\n' +
-          '┃  Create a named update set now:                        ┃\n' +
-          '┃    jsn updatesets create --name "My Feature"       ┃\n' +
-          '┃                                                        ┃\n' +
-          '┃  Or switch to a scoped scope first:                    ┃\n' +
-          '┃    jsn scopes list                                 ┃\n' +
-          '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\x1b[0m\n'
-        );
-      } else {
-        // 🟡 SOFT WARNING — Scope + Default
-        process.stderr.write(
-          '\x1b[33m' + // yellow
-          '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
-          '  ⚠  Default update set in scope [' + scope + ']\n' +
-          '  Changes are contained to this scope, but a named\n' +
-          '  update set is still recommended for tracking.\n' +
-          '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
-          '\x1b[0m' // reset
-        );
-      }
-    }
+  }
+
+  async guardMutationContext(argv) {
+    this.mutationContext = await guardMutationContext(this, argv);
   }
 
   ok(data, opts = {}) {
-    this.output.ok(data, opts);
+    this.output.ok(data, this.mutationContext ? { ...opts, context: { ...opts.context, mutation: this.mutationContext } } : opts);
   }
 
   err(error) {

package/src/auth-recovery.js

@@ -0,0 +1,83 @@
+import { errAPI, errAuth } from './errors.js';
+import { canUsePicker, quoteShellArg } from './helpers.js';
+import { confirm } from './prompts.js';
+
+// Recovery is scoped to the SDK's resolved identity, never the mutable default.
+// error supplies the same safe guidance if the single retry is also rejected.
+export function createAuthRecovery({ app, session, argv = () => app._authArgv || {},
+  canInteract = canUsePicker, prompt = confirm,
+  renewBrowser = async (request, targetApp) => {
+    const { refreshProfile } = await import('./commands/auth.js');
+    return refreshProfile(request, targetApp);
+  },
+}) {
+  const { instance, profileName, username, profile } = session;
+  const target = profileName ? `--profile ${quoteShellArg(profileName)}` : quoteShellArg(instance);
+  const label = profileName ? `profile ${quoteShellArg(profileName)}` : 'the active profile';
+  function failure(method = profile?.auth_method) {
+    const error = errAPI(401, '');
+    const login = `jsn auth login ${target}`;
+    error.message = `Authentication rejected for ${label} (HTTP 401).`;
+    error.profile = profileName || null;
+    error.recovery = method === 'basic'
+      ? `jsn auth login --basic ${quoteShellArg(instance)}${profileName ? ` --profile ${quoteShellArg(profileName)}` : ''}`
+      : method === 'gck' ? `jsn auth refresh ${target} --browser`
+      : method === 'oauth' ? `jsn auth refresh ${target}` : login;
+    error.hint = method === 'basic'
+      ? `Set SN_USERNAME/SN_PASSWORD to the correct credentials, then run: ${error.recovery}`
+      : method === 'oauth'
+        ? `Run interactively: ${error.recovery}. If refresh fails, run: ${login}`
+        : `Run: ${error.recovery}`;
+    return error;
+  }
+  // Keep the settled promise too: this provider gets only one recovery attempt.
+  let recoveryAttempt;
+  const provider = {
+    error: failure(),
+    credentialError(cause) {
+      // Local validation can fail before any HTTP response. Keep its precise
+      // reason, but target recovery to this invocation rather than the default.
+      const error = errAuth(`${cause.message} (${label}).`);
+      error.profile = profileName || null;
+      error.recovery = `jsn auth login ${target}`;
+      error.hint = `Run: ${error.recovery}`;
+      return error;
+    },
+    async recover({ status }) {
+      if (status !== 401) return false;
+      return recoveryAttempt ??= recoverOnce();
+    },
+  };
+  async function recoverOnce() {
+    let creds;
+    try {
+      creds = await app.auth.getCredentialsFor(instance, username, {
+        username, authMethod: profile?.auth_method, refresh: false,
+      });
+    } catch { throw provider.error; }
+    const method = profile?.auth_method || creds.auth_method;
+    provider.error = failure(method);
+    if (method === 'oauth' && creds.refresh_token) {
+      try {
+        await app.auth.refreshToken(instance, creds, username ?? null);
+        return true;
+      } catch { throw provider.error; }
+    }
+    if (method === 'gck' && profileName && ['auto', 'confirm'].includes(profile?.reauth ?? 'confirm')
+      && canInteract(app, argv())) {
+      try {
+        if ((profile?.reauth ?? 'confirm') === 'confirm'
+          && !await prompt({ message: `Sign in again in a browser for ${label}?`, default: false })) throw provider.error;
+        // Reuse the canonical GCK refresh/login operation without emitting a
+        // second success envelope or replacing the in-flight command's SDK.
+        const targetApp = Object.create(app);
+        targetApp.ok = () => {};
+        targetApp.sdk = app.getSDKForProfile(instance, { profile, authMethod: 'gck', username });
+        await renewBrowser({ profile: profileName, browser: true }, targetApp);
+        return true;
+      } catch { throw provider.error; }
+    }
+    throw provider.error;
+  }
+  return provider;
+}

package/src/auth.js

@@ -612,7 +612,9 @@ export class AuthManager {
     if (!instance) {
       throw errAuth('No instance specified');
     }
+    const existed = !!this.credentialStore.load(instance, username);
     this.credentialStore.delete(instance, username);
+    return existed && !this.credentialStore.load(instance, username);
   }
 
   /**

package/src/capabilities.js

@@ -16,6 +16,10 @@
 //     skipDailyChecks: true,
 //     // Suppress the current instance header for profile management commands.
 //     skipContextHeader: true,
+//     // Remediation commands bypass mutation capture-context approval only.
+//     mutationContextExemptSubcommands: ['create', 'set'],
+//     // REST methods that are reads (read-only profile policy is separate).
+//     mutationContextReadMethods: ['GET', 'HEAD', 'OPTIONS'],
 //   }
 //
 // cli.js derives every skip-list and the mutation guard's path list from
@@ -130,3 +134,8 @@ export function mutationPaths(caps = collectCapabilities()) {
 export function _resetCapabilities() {
   REGISTRY.clear();
 }
+
+/** Declared local-only previews bypass instance access, including context headers. */
+export function isLocalPreview(argv, caps = collectCapabilities()) {
+  return argv.dryRun === true && caps.get(argv._?.[0])?.localPreviewSubcommands?.includes(argv._?.[1]) === true;
+}

package/src/cli-adapter.js

@@ -3,6 +3,14 @@ import process from 'node:process';
 
 const camel = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 const names = (x) => typeof x === 'string' ? [x] : (x || []);
+
+/**
+ * A repeatable option may be declared either way: `type: 'array'` (this
+ * adapter's historic spelling) or `array: true` (the yargs spelling most
+ * contributors reach for). Both must accumulate; honoring only the first
+ * silently kept the LAST value of `-f a=1 -f b=2` and dropped the rest.
+ */
+const isArrayOption = (spec) => spec?.type === 'array' || spec?.array === true;
 const commandName = (command) => command.trim().split(/\s+/)[0];
 const positionSpec = (command) => [...command.matchAll(/([<[])([^>\]]+)[>\]]/g)].map((m) => ({ name: m[2], required: m[1] === '<' }));
 
@@ -108,6 +116,7 @@ export class LocalCLI {
 
   scriptName(value) { this.script = value; return this; }
   usage(value) { this.root.usageText = value; return this; }
+  epilogue(value) { this.root.epilogueText = value; return this; }
   middleware(fn) { this.middlewares.push(...(Array.isArray(fn) ? fn : [fn])); return this; }
   option(name, config) { this.root.options.set(name, { ...config, name }); return this; }
   options(config) { for (const [name, value] of Object.entries(config)) this.option(name, value); return this; }
@@ -189,7 +198,7 @@ export class LocalCLI {
   _assign(argv, key, value, spec, opts = {}) {
     const validate = opts.validate !== false;
     const actual = spec?.name || key;
-    const values = spec?.type === 'array' ? (Array.isArray(value) ? value : [value]) : [value];
+    const values = isArrayOption(spec) ? (Array.isArray(value) ? value : [value]) : [value];
     if (validate && spec?.choices && values.some((item) => !spec.choices.includes(item))) {
       this._fail(`Invalid value for --${actual}: ${value}. Choose from: ${spec.choices.join(', ')}`);
       return false;
@@ -201,7 +210,7 @@ export class LocalCLI {
     const converted = spec?.type === 'boolean'
       ? (value === 'true' ? true : value === 'false' ? false : value)
       : spec?.type === 'number' ? Number(value) : value;
-    if (spec?.type === 'array') argv[actual] = [...(argv[actual] || []), ...values];
+    if (isArrayOption(spec)) argv[actual] = [...(argv[actual] || []), ...values];
     else argv[actual] = converted;
     argv[camel(actual)] = argv[actual];
     for (const alias of names(spec?.alias)) argv[alias] = argv[actual];
@@ -210,8 +219,8 @@ export class LocalCLI {
     const options = this._optionConfig(path);
     const defs = {};
     for (const [key, spec] of options) defs[key] = {
-      type: spec.type === 'number' || spec.type === 'array' ? 'string' : (spec.type || 'boolean'),
-      multiple: spec.type === 'array',
+      type: spec.type === 'number' || isArrayOption(spec) ? 'string' : (spec.type || 'boolean'),
+      multiple: isArrayOption(spec),
     };
     args = args.map((arg) => {
       if (/^-[^-]=/.test(arg)) return `--${arg.slice(1)}`;
@@ -286,6 +295,13 @@ export class LocalCLI {
         aliases: [...node.aliases],
         description: node.definition.describe || '',
         subcommands: node.children.filter(visible).map((child) => child.name),
+        discovery: node.definition.discovery || null,
+        help: `jsn ${node.name} --help`,
+        actions: node.children.filter(visible).map((child) => ({
+          name: child.name,
+          description: child.definition.describe || '',
+          help: `jsn ${node.name} ${child.name} --help`,
+        })),
       };
     };
     return {
@@ -316,6 +332,10 @@ export class LocalCLI {
   }
 
   _help(node, path = []) {
+    if (!path.length && this.rootHelpRenderer) {
+      process.stdout.write(this.rootHelpRenderer() + "\n");
+      return;
+    }
     const lines = [node.usageText || `Usage: ${this.script} ${path.join(' ') || '<command>'}`];
     if (node.definition.describe) lines.push(`\n${node.definition.describe}`);
     if (node.children.length) lines.push('\nCommands:\n' + node.children.filter((n) => n.name !== this.completionCommand).map((n) => `  ${n.definition.command}  ${n.definition.describe || ''}`).join('\n'));