@jacebenson/jsn 1.0.7 → 2.0.2

package/package.json

@@ -1,43 +1,46 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "1.0.7",
+  "version": "2.0.2",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
-  "homepage": "https://github.com/jacebenson/jsn#readme",
-  "bugs": {
-    "url": "https://github.com/jacebenson/jsn/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jacebenson/jsn.git"
-  },
-  "license": "MIT",
-  "author": "Jace Benson",
-  "type": "commonjs",
-  "files": [
-    "bin",
-    "scripts",
-    "README.md",
-    "LICENSE"
-  ],
+  "type": "module",
   "bin": {
     "jsn": "bin/jsn.js"
   },
+  "main": "src/cli.js",
   "scripts": {
-    "postinstall": "node scripts/npm-install.js"
+    "test": "node --test $(find test -name '*.test.js')",
+    "lint": "npx eslint src/ bin/ test/",
+    "start": "node bin/jsn.js",
+    "tag-reminder": "node scripts/tag-reminder.js",
+    "release": "node scripts/release.js"
   },
+  "keywords": [
+    "servicenow",
+    "cli",
+    "rest-api",
+    "automation"
+  ],
+  "author": "Jace Benson",
+  "license": "MIT",
   "engines": {
-    "node": ">=14"
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.1",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "yargs": "^17.7.2"
   },
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
-  "cpu": [
-    "x64",
-    "arm64"
-  ],
   "devDependencies": {
-    "@servicenow/sdk": "^4.7.0"
-  }
-}
+    "@eslint/js": "^10.0.1",
+    "@inquirer/search": "^4.2.0",
+    "globals": "^17.6.0"
+  },
+  "files": [
+    "bin/jsn.js",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skills/servicenow/SKILL.md

@@ -0,0 +1,137 @@
+---
+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.
+license: MIT
+compatibility: |
+  Requires jsn CLI (github.com/jacebenson/jsn). Install via:
+  curl -fsSL https://jsn.jace.pro/install | bash
+  Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
+  
+  Windows users: Download from GitHub releases. If jsn is not in your PATH, the setup
+  command will automatically detect its location and show the correct command path
+  (e.g., `.\jsn.exe tables list` instead of `jsn tables list`).
+metadata:
+  author: jacebenson
+  version: "1.0.0"
+  repository: https://github.com/jacebenson/jsn
+---
+
+# Jace's ServiceNow CLI
+
+Explore and manage ServiceNow instances. Works standalone or with AI agents.
+
+## Discovery
+
+Commands are self-documenting. Use these to learn what's available:
+
+```bash
+jsn --help                # Root help with all top-level commands
+jsn <command> --help        # Detailed usage, flags, and examples for any command
+jsn dev                     # Shows categorized dev subcommands
+```
+
+## Agent Rules
+
+1. **Output modes** — `--json` when parsing data; `--md` when presenting to humans; `--agent` for automation
+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 dev 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.
+
+## 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.
+
+## Configuration
+
+```
+~/.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

package/src/app.js

@@ -0,0 +1,194 @@
+// App context: bundles config, auth, SDK, output, and runtime context
+
+import { AuthManager } from './auth.js';
+import { SDKClient } from './sdk.js';
+import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled } from './output.js';
+import { getEffectiveInstance } from './config.js';
+import { extractProfileName } from './helpers.js';
+import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
+import { errUsage, errAuth } from './errors.js';
+import process from 'node:process';
+
+
+export class App {
+  constructor(cfg) {
+    this.config = cfg;
+    this.auth = new AuthManager(this);
+    this.output = new OutputWriter({ format: resolveFormat(cfg.format) });
+    this.sdk = null;
+
+    const instance = getEffectiveInstance(cfg);
+    if (instance) {
+      this.sdk = new SDKClient(instance, this.auth);
+    }
+
+    this.context = {
+      profileName: '',
+      username: '',
+      scope: '',
+      updateSet: '',
+    };
+
+    this.loadContext();
+  }
+
+  loadContext() {
+    const instance = getEffectiveInstance(this.config);
+    if (!instance) return;
+    this.context.profileName = extractProfileName(instance);
+    for (const [name, profile] of Object.entries(this.config.profiles || {})) {
+      if (profile.instance_url === instance) {
+        this.context.profileName = name;
+        this.context.username = profile.username || '';
+        break;
+      }
+    }
+  }
+
+  getEffectiveInstance() {
+    return getEffectiveInstance(this.config);
+  }
+
+  async printContextHeader() {
+    if (!this.getEffectiveInstance() || !this.sdk) return;
+    if (process.env.JSN_NO_HEADER) return;
+    if (this.output.getFormat() === FormatJSON || this.output.getFormat() === FormatQuiet) return;
+
+    let userDisplayName = 'Unknown';
+    let userSysID = '';
+
+    try {
+      const user = await getCurrentUser(this.sdk);
+      if (user) {
+        userDisplayName = user.name || user.user_name;
+        userSysID = user.sys_id;
+        this.context.username = userDisplayName;
+      }
+    } catch {
+      // ignore
+    }
+
+    let displayUserName = userDisplayName;
+    if (displayUserName.length > 10) {
+      displayUserName = displayUserName.slice(0, 6) + '...';
+    }
+
+    let scope = 'global';
+    if (userSysID) {
+      try {
+        const app = await getCurrentApplication(this.sdk, userSysID);
+        if (app && app.scope) scope = app.scope;
+      } catch {
+        // ignore
+      }
+    }
+    this.context.scope = scope;
+
+    let updateSet = 'Default';
+    let updateSetSysID = '';
+    if (userSysID) {
+      try {
+        const us = await getCurrentUpdateSet(this.sdk, userSysID);
+        if (us && us.name && us.name !== '-') {
+          updateSet = us.name;
+          updateSetSysID = us.sys_id;
+        }
+      } catch {
+        // ignore
+      }
+    }
+    this.context.updateSet = updateSet;
+
+    const instance = this.getEffectiveInstance();
+    const instanceLink = instance;
+    const userLink = `${instance}/sys_user_list.do?sysparm_query=sys_id=${userSysID}`;
+    const scopeLink = `${instance}/sys_scope.do?sysparm_query=scope=${scope}`;
+    const updateSetLink = updateSetSysID
+      ? `${instance}/sys_update_set.do?sys_id=${updateSetSysID}`
+      : `${instance}/sys_update_set_list.do`;
+
+    const scopeFormatted = `[${scope}]`;
+
+    process.stderr.write('# Use `jsn dev scopes` to change scope, `jsn dev updatesets set` to change updateset\n');
+    process.stderr.write('PROFILE   USER      [SCOPE]           UPDATE SET\n');
+
+    const profileStr = `]8;;${instanceLink}\x07${String(this.context.profileName).padEnd(9)}]8;;\x07`;
+    const userStr = `]8;;${userLink}\x07${String(displayUserName).padEnd(9)}]8;;\x07`;
+    const scopeStr = `]8;;${scopeLink}\x07${String(scopeFormatted).padEnd(17)}]8;;\x07`;
+    const updateSetStr = `]8;;${updateSetLink}\x07${updateSet}]8;;\x07`;
+
+    process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
+
+    // ⚠️  Warning if in the Default update set
+    if (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 dev updatesets create --name "My Feature"       ┃\n' +
+          '┃                                                        ┃\n' +
+          '┃  Or switch to a scoped scope first:                    ┃\n' +
+          '┃    jsn dev scopes list                                 ┃\n' +
+          '┃                                                        ┃\n' +
+          '┃  (Run jsn updatesets yolo to silence this check)       ┃\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' +
+          '  (Run \x1b[1mjsn updatesets yolo\x1b[22m to silence this warning)\n' +
+          '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
+          '\x1b[0m' // reset
+        );
+      }
+    }
+  }
+
+  ok(data, opts = {}) {
+    this.output.ok(data, opts);
+  }
+
+  err(error) {
+    this.output.err(error);
+  }
+
+  isInteractive() {
+    return process.stdout.isTTY === true;
+  }
+
+  requireInstance() {
+    if (!this.getEffectiveInstance()) {
+      throw errUsage('Instance URL required. Set via --instance flag, SERVICENOW_INSTANCE_URL env, or config file.');
+    }
+  }
+
+  requireAuth() {
+    if (!this.auth.isAuthenticated()) {
+      throw errAuth('Not authenticated');
+    }
+  }
+}
+
+function resolveFormat(fmt) {
+  switch (fmt) {
+    case 'json': return FormatJSON;
+    case 'markdown':
+    case 'md': return FormatMarkdown;
+    case 'quiet': return FormatQuiet;
+    case 'styled': return FormatStyled;
+    default: return FormatAuto;
+  }
+}