@jacebenson/jsn 3.1.0 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@inquirer/core": "^10.1.0",
     "@inquirer/prompts": "^7.5.1",
     "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
@@ -34,7 +35,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@inquirer/search": "^4.2.0",
+    "@inquirer/search": "^4.2.1",
     "globals": "^17.6.0"
   },
   "files": [

package/skills/servicenow/SKILL.md

@@ -12,151 +12,76 @@ 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.
-  
-  Windows users: Install Node.js first, then the npm command above. If jsn is not
-  in your PATH, the setup command will automatically detect its location and show
-  the correct command path.
 metadata:
   author: jacebenson
-  version: "1.1.0"
+  version: "3.1.1"
   repository: https://github.com/jacebenson/jsn
 ---
 
-# Jace's ServiceNow CLI
+# Jace's ServiceNow CLI (jsn)
 
-Explore and manage ServiceNow instances. Works standalone or with AI agents.
+Explore and manage ServiceNow instances. Interactive paginated pickers with server-side search on all list commands.
 
 ## Discovery
 
-Commands are self-documenting. Use these to learn what's available:
-
 ```bash
-jsn --help                # Root help with all top-level commands (grouped by category)
-jsn <command> --help        # Detailed usage, flags, and examples for any command
+jsn --help                # All commands grouped by domain
+jsn <command> --help      # Flags, subcommands, and examples
 ```
 
+## Interactive Picker
+
+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; `--md` when presenting to humans; `--agent` for automation
+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 profiles use <name>` to change default
-6. **Before using `eval` or `rest`** — Ask yourself: *"Have I checked if there's a more specific jsn command?"* Verify `jsn records --table <name> create` won't work first. Prefer specific over generic over escape hatch over eval.
-7. **CONFIRM before destructive operations** — Always show the user exactly what will be created, updated, or deleted and ask for explicit confirmation before executing. Never run `create`, `update`, `delete`, `set`, or `remove` commands without user approval.
-
-## ⚠️ Destructive Operations Require Confirmation
-
-**jsn does not have a `--confirm` or `--dry-run` flag.** It assumes you mean what you type. This means **YOU** (the agent) are the safety layer.
-
-**Before any write operation, you MUST:**
-
-1. **Show the user what you found** — Run a `list` or `show` command first
-2. **Present the exact command you plan to run** — Include the sys_id, table name, and data
-3. **Wait for explicit approval** — "Proceed? [y/N]" or similar
-
-**Examples of destructive commands that require confirmation:**
-- `jsn records --table <name> create`
-- `jsn records --table <name> update <sys_id>`
-- `jsn records --table <name> delete <sys_id>`
-- `jsn updatesets set <name>`
-- `jsn profiles remove <name>`
-- Any `delete`, `update`, `create`, `set`, or `remove` subcommand
-
-**Good pattern:**
-```
-User: "Delete that incident"
-Agent: "Found: INC0010001 'Server down' (sys_id: abc123...)
-       Command: jsn records --table incident delete abc123...
-       Proceed? [y/N]"
-User: "y"
-Agent: [runs command]
-```
-
-**Bad pattern:**
-```
-User: "Delete that incident"
-Agent: [immediately runs jsn records --table incident delete ...]
-```
-
-## ⚠️ AVOID `jsn eval` for Record Creation
-
-**Why:** `jsn eval` runs server-side JavaScript in the global scope. It returns HTTP 200 even when:
-- The insert fails due to ACL violations
-- Mandatory fields are missing
-- The record lands in the wrong scope
-- Logic errors prevent the insert entirely
-
-**The AI trap:** Agents see "success" and assume the record was created. It wasn't.
-
-**Always use instead:** `jsn records --table <name> create` — it returns the created record with sys_id or an explicit validation error.
-
-**Only use `eval` when:** No specific command exists, `records` lacks required fields, and `rest` doesn't work. This is rare.
+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 jobs`, etc. — curated views with domain-aware formatting and validation
-2. **`jsn records --table <name>`** — generic CRUD on any table (the workhorse, preferred for record creation)
-3. **`jsn rest`** — raw Table API escape hatch when records command lacks required fields
-4. **`jsn eval`** — ⚠️ **LAST RESORT ONLY** — server-side script execution when no other option exists
-5. **Ask the human** — if none of the above work. Never generate standalone GlideRecord scripts as a fallback.
-
-## JSON Envelope
-
-All commands support `--json`. The envelope structure:
-
-```json
-{
-  "ok": true,
-  "data": [ ... ],
-  "summary": "5 records",
-  "breadcrumbs": [
-    {"action": "show", "cmd": "jsn records --table incident <sys_id>", "description": "View details"}
-  ]
-}
-```
-
-Breadcrumbs suggest next commands — follow them for navigation.
+1. **Specific commands** — `jsn flows`, `jsn rules`, `jsn catalogitems`, etc.
+2. **`jsn records --table <name>`** — generic CRUD on any table
+3. **`jsn rest`** — raw Table API escape hatch
+4. **`jsn eval`** — ⚠️ **LAST RESORT ONLY**
+5. **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`, `workflows`, `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`, `profiles`, `updatesets`, `scopes` |
+| **Developer** | `eval`, `rest`, `skill`, `version` |
 
 ## Troubleshooting Field Behavior
 
-When a user asks about field behavior (why a picker won't show inactive users, why a field is read-only, why a reference qualifier behaves unexpectedly), do NOT just check dictionary records or ACLs. Field behavior is often controlled by **before-query business rules**.
-
-**Check order (priority):**
-
-1. **Before-query business rules** — `sys_script` with `when=before`, `action=query`, matching `collection` (table)
-   ```bash
-   jsn records list --table sys_script --query "collection=sys_user^when=before^action=query^active=true" --json
-   ```
-   A common case: inactive user filters on `sys_user` are implemented as a before-query BR that adds `active=true` to the query condition.
-
-2. **ACLs** — `sys_security_acl` — read/write/delete permissions on tables and fields
-   ```bash
-   jsn acls list --query "name=incident" --json
-   ```
+Check order (priority):
 
-3. **Dictionary overrides** — `sys_dictionary` — reference qualifiers, field attributes, default values
+1. **Before-query business rules** — `sys_script` with `when=before`, `action=query`
    ```bash
-   jsn records list --table sys_dictionary --query "name=incident^element=caller_id" --json
+   jsn b4rules list --query "collection=sys_user"
    ```
-
-4. **Client scripts** — `sys_script_client` — UI-side visibility, read-only, or value-change logic
-   ```bash
-   jsn records list --table sys_script_client --query "table=incident^active=true" --json
-   ```
-
-5. **UI policies** — `sys_ui_policy` — form-level field behavior (mandatory, read-only, visible)
-   ```bash
-   jsn records list --table sys_ui_policy --query "table=incident^active=true" --json
-   ```
-
-**Example:** "Why can't I pick an inactive user on the incident form?"
-- First guess: Dictionary reference qualifier on `caller_id`? → Check `sys_dictionary`
-- Most likely: Before-query BR on `sys_user` that filters `active=true` → Check `sys_script` first
-
-**Rule of thumb:** If a picker is silently filtering results (no error, just fewer options), it's a before-query BR. If it shows an error, it's an ACL or dictionary constraint.
+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
 
@@ -164,11 +89,4 @@ When a user asks about field behavior (why a picker won't show inactive users, w
 ~/.config/servicenow/
 ├── config.json               # Profiles and settings
 └── credentials.json          # Auth tokens (fallback)
-
-.servicenow/                  # Per-repo config (optional)
-└── config.json               # Project-specific settings
 ```
-
-**Environment variables:**
-- `SERVICENOW_TOKEN` — Override stored token
-- `SERVICENOW_INSTANCE` — Override instance URL