@jacebenson/jsn 4.1.0 → 4.2.1

package/README.md

@@ -10,7 +10,7 @@ Works standalone or with AI agents (Claude Code, OpenCode, Hermes, Cursor, Copil
 npm install -g @jacebenson/jsn
 ```
 
-Node.js 18+. macOS, Linux, Windows.
+Node.js (see `engines` in package.json). macOS, Linux, Windows.
 
 The install also copies an AI agent skill file to `~/.agents/skills/servicenow/SKILL.md`.
 
@@ -59,9 +59,23 @@ jsn updatesets set "My Feature"
 # Generic table access
 jsn records list --table incident --limit 50 --json | jq '.[].number'
 jsn records create --table incident --data '{"short_description":"test"}'
+jsn records list --table incident --limit 50 --get "data.records.0.number"   # no jq needed
+jsn records list --table incident --query "active=true"                       # totals included by default
+jsn records list --table incident --limit 10 --no-count                       # opt out of the total query
+jsn records bulk --table incident --query "priority=1" --set '{"state":"3"}'  # dry-run by default
+jsn records get --table incident --sys-id 8a1234abcd5678 --attachments        # record + its files
+jsn records list --table incident --limit 10 --csv                            # output CSV
 
 # Script execution
 jsn eval "gs.info('Hello World')"
+cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)
+
+# 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
+
+# Live log tailing (Ctrl+C to stop)
+jsn logs follow --level error --tail 10
 ```
 
 ## Commands
@@ -76,7 +90,7 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 **User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`
 
-**Data** — `records`, `tables`, `columns`, `includes`, `import`, `logs`, `users`, `groups`
+**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
 
 Every command supports `--json`, `--query`, and `--help`.
 
@@ -106,6 +120,8 @@ jsn auth modify dev12345                          # Toggle read-only / skip conf
 | `--json` | Pipelines, scripts |
 | `--markdown` | Documentation |
 | `--quiet` / `-q` | Data only, no envelope |
+| `--csv` | Spreadsheets (opens straight into Excel) |
+| `--get <path>` | Pull one value out of the JSON envelope — no jq (e.g. `--get "data.records.0.number"`) |
 
 ## Authentication
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -11,6 +11,8 @@
     "test": "node --experimental-test-module-mocks --test $(find test -name '*.test.js')",
     "lint": "npx eslint src/ bin/ test/",
     "start": "node bin/jsn.js",
+    "docs": "npm --prefix docs run build",
+    "docs:serve": "npm --prefix docs run serve",
     "tag-reminder": "node scripts/tag-reminder.js",
     "release": "node scripts/release.js"
   },
@@ -34,6 +36,7 @@
     "yargs": "^17.7.2"
   },
   "devDependencies": {
+    "@11ty/eleventy": "^3.1.6",
     "@eslint/js": "^10.0.1",
     "@inquirer/search": "^4.2.1",
     "globals": "^17.6.0"

package/src/app.js

@@ -1,10 +1,17 @@
 // App context: bundles config, auth, SDK, output, and runtime context
+//
+// Identity ("which instance, as whom, with what profile flags") is owned by
+// the SESSION (src/session.js): the constructor resolves one from the
+// config, the cli.js middleware re-applies it once --instance/--profile are
+// known (applySession), and getEffectiveInstance()/requireInstance()/
+// setEffectiveInstance() are thin session-backed shims kept for the many
+// command handlers that already call them.
 
 import { AuthManager } from './auth.js';
 import { SDKClient } from './sdk.js';
-import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled } from './output.js';
-import { getEffectiveInstance, normalizeInstanceURL, saveConfig } from './config.js';
-import { extractProfileName } from './helpers.js';
+import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled, hyperlink } from './output.js';
+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 { isMutationCommand } from './mutations.js';
@@ -14,52 +21,47 @@ 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, {
-        domain: this._profileDomain(cfg),
-      });
+    // Back-compat field: flag-provided instance override (--instance /
+    // --profile). Written by applySession only; mirrored on argv no longer.
+    this._overrideInstance = null;
+    // Pinned argv flags for session re-resolution after config edits
+    // (auth switch / login / remove change the config under a pinned
+    // --profile). Set by applySession; {} means "no flags seen".
+    this._sessionArgv = {};
+
+    // Resolve the initial session from config alone (no argv yet — the
+    // middleware re-applies with argv). AuthManager is TOLD the identity:
+    // it reads username/instance through this provider over the session
+    // instead of reaching into config.profiles itself.
+    this.session = resolveSession({}, cfg);
+    this.auth = new AuthManager({
+      getUsername: () => this.session?.username || null,
+      getEffectiveInstance: () => this.session?.instance || '',
+    });
+
+    if (this.session.instance) {
+      this._buildSdk(this.session.instance, this.session);
     }
 
-    this.context = {
-      profileName: '',
-      username: '',
-      scope: '',
-      updateSet: '',
-    };
-
+    this.context = { profileName: '', username: '', scope: '', updateSet: '' };
     this.loadContext();
   }
 
-  loadContext() {
-    const activeName = this.config.activeProfile || this.config.defaultProfile;
-    if (activeName && this.config.profiles[activeName]) {
-      this.context.profileName = activeName;
-      this.context.username = this.config.profiles[activeName].username || '';
-      return;
-    }
+  /** Build (or rebuild) the SDK client for an instance + session. */
+  _buildSdk(instance, session = this.session) {
+    this.sdk = new SDKClient(instance, this.auth, {
+      domain: session?.domain || '',
+    });
+  }
 
-    // Fallback: no active profile name — find by instance URL (legacy config)
-    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;
-      }
-    }
+  loadContext() {
+    this.context = contextFromSession(this.session, this.config);
   }
 
   getEffectiveInstance() {
-    // Command-line override (--instance, --profile) takes precedence
-    if (this._overrideInstance) return this._overrideInstance;
-    return getEffectiveInstance(this.config);
+    return this.session?.instance || '';
   }
 
   async printContextHeader(argv = {}) {
@@ -124,16 +126,15 @@ export class App {
 
     // Read-only profiles get a lock badge on every command run, so the
     // armed safety is always visible (not just in `auth status`).
-    const activeProfile = this.context.profileName ? this.config.profiles[this.context.profileName] : null;
-    const roBadge = activeProfile?.read_only === true ? ' 🔒' : '';
+    const roBadge = this.session?.readOnly === true ? ' 🔒' : '';
 
     process.stderr.write('# Use `jsn scopes` to change scope, `jsn updatesets set` to change updateset\n');
     process.stderr.write('PROFILE   USER      [SCOPE]           UPDATE SET\n');
 
-    const profileStr = `\u001b]8;;${instanceLink}\x07${String(this.context.profileName).padEnd(9)}${roBadge}\u001b]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`;
+    const profileStr = hyperlink(`${String(this.context.profileName).padEnd(9)}${roBadge}`, instanceLink);
+    const userStr = hyperlink(String(displayUserName).padEnd(9), userLink);
+    const scopeStr = hyperlink(String(scopeFormatted).padEnd(17), scopeLink);
+    const updateSetStr = hyperlink(updateSet, updateSetLink);
 
     process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
 
@@ -185,9 +186,7 @@ export class App {
   }
 
   requireInstance() {
-    if (!this.getEffectiveInstance()) {
-      throw errUsage('Instance URL required. Set via --instance flag, SERVICENOW_INSTANCE_URL env, or config file.');
-    }
+    requireSessionInstance(this.session);
   }
 
   requireAuth() {
@@ -197,26 +196,11 @@ export class App {
   }
 
   /**
-   * Override the effective instance for this command run.
-   * Rebuilds the SDK client for the new instance.
+   * Back-compat shim: override the effective instance for this command run.
+   * Routes through the session resolver (rebuilds the SDK client).
    */
   setEffectiveInstance(url) {
-    const normalizedUrl = normalizeInstanceURL(url);
-    if (normalizedUrl) {
-      this._overrideInstance = normalizedUrl;
-      this.sdk = new SDKClient(normalizedUrl, this.auth, {
-        domain: this._profileDomain(this.config),
-      });
-    }
-  }
-
-  /** Read the configured domain for the active profile (empty = no scoping). */
-  _profileDomain(cfg) {
-    const name = cfg.activeProfile || cfg.defaultProfile;
-    if (name && cfg.profiles[name]) {
-      return cfg.profiles[name].domain || '';
-    }
-    return '';
+    applySession(this, { instance: url });
   }
 
   /** Set (or clear with '') the domain for the active profile. */

package/src/auth.js

@@ -272,23 +272,40 @@ function askHidden(promptText) {
 }
 
 export class AuthManager {
-  constructor(configProvider) {
-    this.configProvider = configProvider;
+  /**
+   * @param {object} identity — the resolved-identity provider. Production
+   *   wiring (src/app.js) hands an adapter over app.session:
+   *   { getUsername(), getEffectiveInstance() }. AuthManager no longer
+   *   reaches into config.profiles itself — the session owns "who am I".
+   *
+   *   Transitional back-compat: a legacy configProvider ({ config, ...
+   *   getEffectiveInstance() }) is adapted to the identity surface, so the
+   *   existing test fixtures (which predate the session) keep working.
+   */
+  constructor(identity) {
+    if (identity && identity.config && typeof identity.getUsername !== 'function') {
+      const provider = identity;
+      this.identity = {
+        getUsername: () => {
+          const cfg = provider.config;
+          const name = cfg.activeProfile || cfg.defaultProfile;
+          return (name && cfg.profiles?.[name]?.username) || null;
+        },
+        getEffectiveInstance: () => provider.getEffectiveInstance(),
+      };
+    } else {
+      this.identity = identity;
+    }
     this.httpClient = { timeout: 30000 };
   }
 
   /**
-   * Resolve the username for credential keying from the active profile.
+   * The username for credential keying, from the resolved session identity.
    * Returns null when no profile is configured — callers fall back to bare
    * instance key for backward compatibility with legacy / no-profile usage.
    */
   _activeUsername() {
-    const cfg = this.configProvider.config;
-    const name = cfg.activeProfile || cfg.defaultProfile;
-    if (name && cfg.profiles[name] && cfg.profiles[name].username) {
-      return cfg.profiles[name].username;
-    }
-    return null;
+    return this.identity.getUsername() || null;
   }
 
   getLastSeen(instance) {
@@ -334,7 +351,7 @@ export class AuthManager {
   isAuthenticated() {
     if (process.env.SERVICENOW_OAUTH_TOKEN) return true;
     if (getBasicAuthFromEnv()) return true;
-    const instance = this.configProvider.getEffectiveInstance();
+    const instance = this.identity.getEffectiveInstance();
     if (!instance) return false;
     try {
       this.getCredentialsFor(instance);
@@ -357,7 +374,7 @@ export class AuthManager {
     if (process.env.SERVICENOW_OAUTH_TOKEN) {
       return { auth_method: 'oauth', access_token: process.env.SERVICENOW_OAUTH_TOKEN, auth_source: 'env_token' };
     }
-    const instance = this.configProvider.getEffectiveInstance();
+    const instance = this.identity.getEffectiveInstance();
     if (!instance) {
       throw errAuth('No instance configured');
     }
@@ -581,6 +598,24 @@ export class AuthManager {
     }
     deleteCredentials(instance, this._activeUsername());
   }
+
+  /**
+   * Migrate legacy bare-instance-keyed credentials to <user>@<instance>
+   * keying after an OAuth login verifies the username. Re-saves under the
+   * compound key and removes the bare key. Returns true when a migration
+   * happened. Credential-store internals (key shapes, legacy bare keys)
+   * live behind this seam — command handlers must not import
+   * loadCredentials/saveCredentials/deleteCredentials to do this themselves.
+   */
+  migrateLegacyCredential(instance, username) {
+    if (!instance || !username) return false;
+    const stored = loadCredentials(instance);
+    if (!stored || !stored.access_token) return false;
+    stored.username = username;
+    saveCredentials(instance, stored, username);
+    deleteCredentials(instance); // remove bare-instance legacy key
+    return true;
+  }
 }
 
 export { saveCredentials, loadCredentials, deleteCredentials, askHidden };

package/src/capabilities.js

@@ -0,0 +1,128 @@
+// Command capability registry — the single source of truth for command
+// metadata that middleware cares about.
+//
+// Each command module declares its capabilities ONCE at the definition site
+// via declareCapabilities(name, caps):
+//
+//   {
+//     // Subcommand verbs that mutate instance state. The mutation guard
+//     // (src/mutations.js) derives its command-path list from these.
+//     mutationSubcommands: ['create', 'update', 'delete'],
+//     // Also registered under `jsn dev <name>` — derive both spellings.
+//     devAlias: true,
+//     // Command runs without a configured instance (joins the middleware
+//     // skip-list for the instance guard).
+//     noInstance: true,
+//     // Skip the once-per-day npm-version / skill freshness checks and the
+//     // interactive context header.
+//     skipDailyChecks: true,
+//   }
+//
+// cli.js derives every skip-list and the mutation guard's path list from
+// this registry. Hand-maintained string lists of command names are a bug
+// farm — see the catalogitems create read-only bypass that shipped because
+// mutations.js listed `catalog create-item` while the real command is
+// `catalogitems create`.
+//
+// Note: yargs strips custom properties off command modules when it
+// registers them (only original/description/handler/builder survive in
+// getCommandHandlers()), so declarations live in this module-level map,
+// keyed by root command name. Declaration happens when the command module
+// factory runs — i.e. during cli.js's registration chain — so the registry
+// is complete once buildCLI() returns.
+
+const REGISTRY = new Map();
+
+/**
+ * Declare a command's capabilities. Called by command factories and
+ * hand-written command modules at definition time.
+ *
+ * @param {string} name — root command name (as typed: `jsn <name>`)
+ * @param {object} caps — capability declaration (see module header)
+ * @returns {object} the caps object (for convenient inline use)
+ */
+export function declareCapabilities(name, caps) {
+  REGISTRY.set(name, { devAlias: false, ...caps });
+  return caps;
+}
+
+/**
+ * The collected capability registry: root command name → capabilities.
+ * Includes the implicit declarations for yargs built-ins ('help') and the
+ * shell plumbing ('completion') which have no factory to declare from.
+ *
+ * @returns {Map<string, object>}
+ */
+export function collectCapabilities() {
+  const caps = new Map(REGISTRY);
+  if (!caps.has('help')) caps.set('help', { noInstance: true, skipDailyChecks: true });
+  if (!caps.has('version')) caps.set('version', { noInstance: true, skipDailyChecks: true });
+  if (!caps.has('completion')) caps.set('completion', { noInstance: true, skipDailyChecks: true });
+  return caps;
+}
+
+/**
+ * Derive the set of root command names that run without an instance.
+ * Preserves the legacy skip-list semantics exactly: help, version,
+ * completion, setup, auth, skill, docs.
+ *
+ * @param {Map<string, object>} [caps] — from collectCapabilities()
+ * @returns {Set<string>}
+ */
+export function noInstanceCommands(caps = collectCapabilities()) {
+  const out = new Set();
+  for (const [name, c] of caps) {
+    if (c.noInstance) out.add(name);
+  }
+  return out;
+}
+
+/**
+ * Derive the set of root command names that skip the daily npm-version /
+ * skill checks and the interactive context header. Legacy semantics:
+ * help, version, completion, skill, docs (a subset of noInstanceCommands).
+ *
+ * @param {Map<string, object>} [caps] — from collectCapabilities()
+ * @returns {Set<string>}
+ */
+export function dailyCheckSkipCommands(caps = collectCapabilities()) {
+  const out = new Set();
+  for (const [name, c] of caps) {
+    if (c.skipDailyChecks) out.add(name);
+  }
+  return out;
+}
+
+/**
+ * Derive the mutation command-path list (argv._ token arrays) from the
+ * capability registry. Each entry is a prefix pattern: an argv._ path that
+ * begins with the pattern IS that mutation (trailing positionals like a
+ * sys_id don't change intent).
+ *
+ * Commands with `devAlias: true` are also registered under `jsn dev <name>`,
+ * so both spellings are emitted.
+ *
+ * A whole-command mutation surface (e.g. `jsn eval`, `jsn rest` — the
+ * command itself is the mutation, there is no mutating sub-verb) declares
+ * `mutationSubcommands: ['']`.
+ *
+ * @param {Map<string, object>} [caps] — from collectCapabilities()
+ * @returns {Array<string[]>}
+ */
+export function mutationPaths(caps = collectCapabilities()) {
+  const paths = [];
+  for (const [name, c] of caps) {
+    if (!c.mutationSubcommands) continue;
+    for (const sub of c.mutationSubcommands) {
+      const parts = sub === '' ? [] : sub.split(' ');
+      paths.push([name, ...parts]);
+      if (c.devAlias) paths.push(['dev', name, ...parts]);
+    }
+  }
+  return paths;
+}
+
+/** Test hook: clear the registry between isolated buildCLI() runs. */
+export function _resetCapabilities() {
+  REGISTRY.clear();
+}