@jacebenson/jsn 4.3.13-dev.87.1 → 4.3.13-dev.89.1

package/package.json

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

package/skills/servicenow/SKILL.md

@@ -1,154 +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.12"
+  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 create ATFs and instance scans to verify the outcomes.
+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. **Verify the intended instance** — Use `--profile <name>` for explicit targeting; never assume the default is right. `jsn auth switch <name>` changes the default.
-4. **Eval safety** — Prefer purpose-built or `records` commands. Never use `eval` to bypass a blocked business rule, ACL, or other ServiceNow protection. If eval is genuinely needed, explain why and obtain explicit user approval.
-5. **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
-
-Use `jsn customizations --help` to discover bounded read-only capture and offline
-review/comparison. For example:
-
-```sh
-jsn customizations capture --label review --customer-scope x_acme_app --json
-jsn customizations show <run_id> --json
-```
-
-Read the CLI's interpretation, coverage and per-artifact triage before drawing
-conclusions. Verify ownership and current behavior before proposing changes;
-never recommend automatic reversion.
-
-### Complete an update set
-
-Before development changes, identify the intended application scope and update
-set. Keep related changes together, use the appropriate update-set or application
-deployment mechanism, and report where changes were captured. Not all changes
-are update-set tracked. Only complete a set when the human explicitly asks,
-including sets you created; completing the current set returns selection to Default.
-
-```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 discovery
-
-Use `jsn records list --help`, `jsn records get --help`, and `jsn rest --help`
-for syntax and examples. REST is blocked on read-only connections, including GET.
-
-### `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
-
-Use `jsn setup` for interactive configuration. `jsn setup --help` lists the
-scriptable `jsn auth` equivalents and secure authentication input options.
+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/commands/_generic.js

@@ -1,3 +1,4 @@
+import { constrainQuery, constrainedQueryHelp } from '../constrained-query.js';
 import { enrichRelatedLists, relatedListOptions } from '../related-lists.js';
 // Generic table-based CRUD command builder
 
@@ -122,19 +123,24 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         command: 'list',
         aliases: ['ls'],
         describe: `List ${name}`,
-        builder: (y) => recordOptions(y)
-          .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true^priority=1")' })
-          .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "name,label,super_class")' })
-          .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
+        builder: (y) => {
+          const command = recordOptions(y)
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true^priority=1")' })
+            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "name,label,super_class")' })
+            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' });
+          const help = [opts.help, extraQuery ? constrainedQueryHelp(extraQuery) : ''].filter(Boolean).join('\n');
+          return help ? command.epilogue(help) : command;
+        },
         handler: wrap(async (argv, app) => {
           const query = argv.query || '';
+          const constrainedQuery = constrainQuery(query, extraQuery);
           const columns = argv.columns ? argv.columns.split(',') : defaultColumns;
           const limit = argv.limit;
 
           // Interactive picker with pagination
           if (canPrompt() && app.output.getFormat() === FormatAuto && !query) {
             const picked = await interactiveList({
-              app, table, singular, columns: ['name', 'sys_scope'], limit, query: extraQuery,
+              app, table, singular, columns: ['name', 'sys_scope'], limit, query: constrainedQuery,
               labelField: 'name',
               message: `Select ${vowelArticle(singular)} ${singular}`,
               formatLabel: (r) => {
@@ -162,8 +168,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           }
 
           // Non-interactive: text/table output
-          const baseQ = extraQuery ? extraQuery + '^' : '';
-          const q = query ? query + '^ORDERBYDESCsys_updated_on' : (baseQ + 'ORDERBYDESCsys_updated_on');
+          const q = `${constrainedQuery}${constrainedQuery ? '^' : ''}ORDERBYDESCsys_updated_on`;
           const params = recordListParams({ limit, fields: ['sys_id', ...columns], query: q });
           const records = await listRecords(app.sdk, { table, params, displayValues: argv.displayValues ?? opts.referenceMode });
           app.ok({
@@ -277,13 +282,14 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         });
     }
 
-    return y;
+    const help = [opts.help, extraQuery ? constrainedQueryHelp(extraQuery) : ''].filter(Boolean).join('\n');
+    return help ? y.epilogue(help) : y;
   };
 
   return {
     command: `${name} [subcommand]`,
     aliases: aliases || [],
-    describe: `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
+    describe: opts.describe || `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
     discovery: {
       table,
       defaultColumns,

package/src/commands/b4rules.js

@@ -1,5 +1,10 @@
 import { buildDevCmd } from './_generic.js';
 
-// Before-query business rules — applies filters to GlideRecord queries before they execute.
-// These are sys_script records with order < 100.
-export const b4rulesCmd = (wrap) => buildDevCmd('b4rules', 'sys_script', ['b4rule'], ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, { singular: 'before-query business rule', scopeValidation: true, extraQuery: 'when=before' });
+// Query rules are explicitly marked; their order is not a classification rule.
+export const b4rulesCmd = wrap => buildDevCmd('b4rules', 'sys_script', ['b4rule'],
+  ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, {
+    singular: 'before-query business rule', scopeValidation: true,
+    extraQuery: 'when=before^action_query=true',
+    describe: 'Inspect before-query business rules that can filter record reads',
+    help: 'Before-query business rules use when=before and the Boolean action_query=true. Filter collection and active status for the affected table. For field behavior, see jsn columns --help; do not bypass server rules or ACLs.',
+  });

package/src/commands/columns.js

@@ -1,9 +1,10 @@
+import { fieldBehaviorHelp } from '../field-behavior.js';
 import { buildDevCmd } from './_generic.js';
 
 export const columnsCmd = (wrap) => {
   const base = buildDevCmd('columns', 'sys_dictionary', ['column', 'col'],
     ['element', 'column_label', 'internal_type', 'mandatory', 'max_length', 'active'],
-    wrap, { singular: 'column', scopeValidation: true });
+    wrap, { singular: 'column', scopeValidation: true, help: fieldBehaviorHelp });
 
   // Add --table filter
   const origBuilder = base.builder;

package/src/constrained-query.js

@@ -0,0 +1,20 @@
+import { errUsageHint } from './errors.js';
+
+/** Constrained table views accept literal AND filters. Encoded queries have no
+ * portable parenthesization; OR/NQ/dynamic clauses must not escape fixed filters. */
+export function constrainQuery(query = '', constraint = '') {
+  if (!constraint) return query;
+  const clauses = String(query).split('^').filter((clause, index, values) => clause !== 'EQ' || index !== values.length - 1);
+  if (!query) return constraint;
+  const literal = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*(?:(?:!=|>=|<=|=|>|<|NOT LIKE|STARTSWITH|ENDSWITH|LIKE|NOT IN|IN)[^^]*|ISEMPTY|ISNOTEMPTY)$/;
+  const ordering = /^ORDERBY(?:DESC)?[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*$/;
+  const allowed = clause => ordering.test(clause) || (literal.test(clause)
+    && (!/^(?:NQ|OR)/i.test(clause) || /^order(?:!=|>=|<=|=|>|<|NOT LIKE|STARTSWITH|ENDSWITH|LIKE|NOT IN|IN|ISEMPTY|ISNOTEMPTY)/.test(clause)));
+  if (/javascript\s*:/i.test(query) || clauses.some(clause => !allowed(clause))) {
+    throw errUsageHint('This constrained command accepts literal AND filters and ORDERBY only; OR, NQ and dynamic query clauses are unsupported.',
+      `The fixed filter is ${constraint}. Use literal AND clauses, or explicitly use records list for advanced queries and retain the intended constraints in every branch.`);
+  }
+  return clauses.length ? `${constraint}^${clauses.join('^')}` : constraint;
+}
+
+export const constrainedQueryHelp = constraint => `Always includes: ${constraint}. Additional --query filters use literal AND clauses (plus ORDERBY). OR, NQ and dynamic query clauses are rejected before requests so they cannot bypass this view's fixed filter.`;

package/src/field-behavior.js

@@ -0,0 +1,15 @@
+// Schema-backed investigation paths; no universal priority order is assumed.
+export const fieldBehaviorHelp = [
+  'Investigate the observed symptom; there is no fixed priority order for every field problem.',
+  'Query filtering: jsn b4rules list --query "collection=incident^active=true" --json',
+  'Before-query rules use sys_script.when=before and the Boolean action_query=true.',
+  'Dictionary entry: jsn records list --table sys_dictionary --query "name=incident^element=caller_id" --json',
+  'Inherited dictionary overrides: jsn records list --table sys_dictionary_override --query "name=incident^element=caller_id" --json',
+  'Inspect base_table and inherited tables as needed; the dictionary entry is separate from its overrides.',
+  'Access controls: jsn acls list --query "nameINincident,incident.*,incident.caller_id,*.caller_id,*,*.*" --json',
+  'Also inspect inherited-table and wildcard ACLs. Exact name=incident alone omits field/wildcard rules.',
+  'ACL rows are evidence, not proof of effective access: operation, roles, conditions and scripts matter.',
+  'Form behavior: jsn clientscripts list --query "table=incident^active=true" --json',
+  'Form policies: jsn uipolicies list --query "table=incident^active=true" --json',
+  'Use the command help and show output to inspect the relevant records. Never bypass a business rule, ACL or other protection to make a symptom disappear.',
+].join('\n');

package/src/record-command-profiles.js

@@ -18,7 +18,7 @@ export default {
   appmenu: { table: 'sys_app_application', aliases: ['app-menu', 'menu'], columns: ['name', 'active', 'sys_scope'],
     options: { singular: 'application menu', scopeValidation: true } },
   acls: { table: 'sys_security_acl', aliases: ['acl'], columns: ['name', 'operation', 'type', 'active', 'sys_scope'],
-    options: { singular: 'ACL', scopeValidation: true } },
+    options: { singular: 'ACL', scopeValidation: true, help: 'Investigate table, field, wildcard and inherited ACL names for the relevant operation. Exact name=incident alone does not cover incident.caller_id, incident.*, *.caller_id or inherited-table ACLs. Roles, conditions and scripts affect effective access; rows alone do not prove access. See jsn columns --help for field investigation paths.' } },
   roles: { table: 'sys_user_role', aliases: ['role', 'r'], columns: ['name', 'description', 'elevated_privilege', 'sys_scope'],
     options: { singular: 'role', scopeValidation: true } },
   properties: { table: 'sys_properties', aliases: ['property', 'prop'], columns: ['name', 'value', 'description', 'sys_scope'],