@jacebenson/jsn 4.3.3 → 4.3.4-dev.5

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 (see `engines` in package.json). macOS, Linux, Windows.
+Node.js 22.5.0 or newer. macOS, Linux, Windows.
 
 The install also copies an AI agent skill file to `~/.agents/skills/servicenow/SKILL.md`.
 
@@ -63,7 +63,7 @@ jsn rules list --query "collection=incident"
 jsn updatesets set "My Feature"
 
 # Generic table access
-jsn records list --table incident --limit 50 --json | jq '.[].number'
+jsn records list --table incident --limit 50 --json | jq '.data.records[].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
@@ -145,12 +145,15 @@ jsn auth modify dev12345                          # Toggle read-only / skip conf
 
 ## Authentication
 
-OAuth 2.0 with PKCE. Credentials in `~/.config/servicenow/credentials/`.
+JSN supports OAuth 2.0 with PKCE, Basic Auth, and browser-session auth. Credentials are stored in the operating system's credential store, with a file fallback under `~/.config/servicenow/credentials/` when the keyring is unavailable.
 
 ```bash
 jsn auth login https://dev12345.service-now.com
 ```
 
+For Basic Auth, set `SN_USERNAME` and `SN_PASSWORD`, then run `jsn auth login --basic <instance>`.
+For browser-session auth, run `jsn auth login --gck <instance>` and paste the request headers when prompted.
+
 For CI/CD, set environment variables:
 
 ```bash
@@ -164,7 +167,7 @@ jsn incidents list
 JSN stores durable local data under `~/.jsn/`. Documentation lives in
 `~/.jsn/docs/`, including `docs.db`, the ServiceNowDocs source checkout, and
 community markdown. Configuration stays under `~/.config/servicenow/` and
-credentials stay under `~/.config/servicenow/credentials/`.
+credentials use the operating system's credential store, with a file fallback under `~/.config/servicenow/credentials/`.
 
 Existing installations migrate documentation from
 `~/.cache/servicenow-cli/docs/` automatically the first time the docs data is
@@ -190,7 +193,7 @@ npm install
 npm test
 ```
 
-Releases: `npm run release -- patch` (or `minor`, `major`). Tags, pushes, and publishes to npm via GitHub Actions.
+Releases are manual. After changes land on `main`, run `npm run release -- patch` (or `minor`, `major`) to test, bump the version, and push the commit and tag. When ready, publish to npm with `npm publish --access public`. Git tags mark releases; GitHub Release entries are not required.
 
 ## License
 

package/bin/jsn.js

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 
+// A pipeline consumer may exit before JSN finishes writing. Treat that
+// expected closed-pipe condition as a clean CLI exit, not an unhandled error.
+process.stdout.on('error', (err) => {
+  if (err.code === 'EPIPE') process.exit(0);
+  throw err;
+});
+
 // Suppress the node:sqlite experimental warning on Node 22.x.
 // SQLite is stable in Node 24+. The patch must be applied before any
 // module imports node:sqlite, so we use a dynamic import after patching.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.3",
+  "version": "4.3.4-dev.5",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "automation"
   ],
   "author": "Jace Benson",
+  "repository": "https://github.com/jacebenson/jsn",
   "license": "MIT",
   "engines": {
     "node": ">=22.5.0"
@@ -31,14 +32,11 @@
     "@inquirer/core": "^10.1.0",
     "@inquirer/prompts": "^7.5.1",
     "better-sqlite3": "^13.0.3",
-    "gray-matter": "^4.0.3",
-    "turndown": "^7.2.4",
-    "yargs": "^17.7.2"
+    "js-yaml": "^4.1.1",
+    "turndown": "^7.2.4"
   },
   "devDependencies": {
-    "@11ty/eleventy": "^3.1.6",
     "@eslint/js": "^10.0.1",
-    "@inquirer/search": "^4.2.1",
     "globals": "^17.6.0"
   },
   "files": [

package/src/cli-adapter.js

@@ -0,0 +1,251 @@
+import { parseArgs } from 'node:util';
+import process from 'node:process';
+
+const camel = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+const names = (x) => typeof x === 'string' ? [x] : (x || []);
+const commandName = (command) => command.trim().split(/\s+/)[0];
+const positionSpec = (command) => [...command.matchAll(/([<[])([^>\]]+)[>\]]/g)].map((m) => ({ name: m[2], required: m[1] === '<' }));
+
+class CommandNode {
+  constructor(definition) {
+    this.definition = typeof definition === 'string' ? { command: definition } : definition;
+    this.name = commandName(this.definition.command || '');
+    this.aliases = names(this.definition.aliases || this.definition.alias);
+    this.children = [];
+    this.options = new Map();
+    this.positionals = new Map();
+    this.middlewares = [];
+    this.built = false;
+  }
+
+  build() {
+    if (this.built) return;
+    this.built = true;
+    if (typeof this.definition.builder === 'function') this.definition.builder(this.api());
+  }
+
+  api() {
+    const node = this;
+    return {
+      command(definition, builder, handler) {
+        node.children.push(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
+        return this;
+      },
+      option(name, config = {}) { node.options.set(name, { ...config, name }); return this; },
+      options(config = {}) { for (const [name, value] of Object.entries(config)) this.option(name, value); return this; },
+      positional(name, config = {}) { node.positionals.set(name, { ...config, name }); return this; },
+      demandCommand(count, message) { node.demand = { count, message }; return this; },
+      middleware(fn) { node.middlewares.push(...(Array.isArray(fn) ? fn : [fn])); return this; },
+      strict() { return this; },
+      check() { return this; },
+      usage(value) { node.usageText = value; return this; },
+      epilogue(value) { node.epilogueText = value; return this; },
+      help() { return this; },
+    };
+  }
+}
+
+export class LocalCLI {
+  constructor(args = []) {
+    this.args = [...args];
+    this.root = new CommandNode({ command: '' });
+    this.root.build = () => {};
+    this.root.api = this.root.api.bind(this.root);
+    this.middlewares = [];
+    this.failHandler = null;
+    this.script = 'jsn';
+    this.completionCommand = '__completion';
+  }
+
+  scriptName(value) { this.script = value; return this; }
+  usage(value) { this.root.usageText = 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; }
+  command(definition, builder, handler) {
+    const node = new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition);
+    this.root.children.push(node);
+    return this;
+  }
+  demandCommand(count, message) { this.root.demand = { count, message }; return this; }
+  completion(name, _description, handler) { this.completionCommand = name; this.completionHandler = handler; return this; }
+  help() { this.helpEnabled = true; return this; }
+  version() { return this; }
+  strictCommands() { this.strictCmd = true; return this; }
+  strictOptions() { return this; }
+  fail(fn) { this.failHandler = fn; return this; }
+  getInternalMethods() {
+    const all = this.root.children;
+    return { getCommandInstance: () => ({
+      getCommands: () => all.flatMap((n) => [n.name, ...n.aliases]),
+      getCommandHandlers: () => Object.fromEntries(all.map((n) => [n.name, n.definition.handler])),
+    }) };
+  }
+  showCompletionScript() {
+    process.stdout.write(`###-begin-jsn-completions-###\n_jsn_yargs_completions() {\n  local completions=$(jsn --get-yargs-completions "$@")\n  COMPREPLY=( $(compgen -W "$completions" -- "\${COMP_WORDS[COMP_CWORD]}") )\n}\ncomplete -F _jsn_yargs_completions jsn\n###-end-jsn-completions-###\n`);
+  }
+
+  _lookup(list, value) { return list.find((n) => n.name === value || n.aliases.includes(value)); }
+  _knownOptions(nodes) {
+    const map = new Map();
+    for (const node of [this.root, ...nodes]) for (const [name, spec] of node.options) {
+      map.set(name, spec); for (const alias of names(spec.alias)) map.set(alias, spec);
+    }
+    return map;
+  }
+  _findPath(args) {
+    const path = [], nodes = [this.root], consumed = new Set(), discoveryConsumed = new Set(); let i = 0;
+    while (i < args.length) {
+      const token = args[i];
+      if (token === '--') break;
+      if (token.startsWith('-')) {
+        const key = token.replace(/^-+/, '').split('=')[0];
+        const spec = this._knownOptions(path).get(key);
+        if (!token.includes('=') && (!spec || spec.type !== 'boolean') && args[i + 1] && !args[i + 1].startsWith('-')) {
+          discoveryConsumed.add(i + 1);
+          i++;
+        }
+        discoveryConsumed.add(i);
+        i++; continue;
+      }
+      const node = this._lookup(nodes[nodes.length - 1].children, token);
+      if (!node) break;
+      consumed.add(i);
+      path.push(node); nodes.push(node); node.build(); i++;
+    }
+    return {
+      path,
+      commandArgs: args.filter((_, index) => !consumed.has(index)),
+      discoveryConsumed: new Set([...consumed, ...discoveryConsumed]),
+    };
+  }
+  _optionConfig(path) { return this._knownOptions(path); }
+  _specFor(options, key, value) {
+    return options.get(key) || [...options.values()].find((spec) => spec.name === key || names(spec.alias).includes(key))
+      || { name: key, type: typeof value === 'boolean' ? 'boolean' : 'string' };
+  }
+  _assign(argv, key, value, spec) {
+    const actual = spec?.name || key;
+    const values = spec?.type === 'array' ? (Array.isArray(value) ? value : [value]) : [value];
+    if (spec?.choices && values.some((item) => !spec.choices.includes(item))) {
+      this._fail(`Invalid value for --${actual}: ${value}. Choose from: ${spec.choices.join(', ')}`);
+      return false;
+    }
+    if (spec?.type === 'number' && values.some((item) => item === '' || !Number.isFinite(Number(item)))) {
+      this._fail(`Invalid number for --${actual}: ${value}`);
+      return false;
+    }
+    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];
+    else argv[actual] = converted;
+    argv[camel(actual)] = argv[actual];
+    for (const alias of names(spec?.alias)) argv[alias] = argv[actual];
+  }
+  _parseOptions(args, path) {
+    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',
+    };
+    args = args.map((arg) => {
+      if (/^-[^-]=/.test(arg)) return `--${arg.slice(1)}`;
+      if (!arg.startsWith('--no-')) return arg;
+      const [key, rawValue] = arg.slice(5).split('=', 2);
+      const spec = this._specFor(options, key);
+      if (spec.type !== 'boolean') return arg;
+      const value = rawValue === undefined ? 'false' : rawValue === 'false' ? 'true' : 'false';
+      return `--${key}=${value}`;
+    });
+    for (const [key, spec] of options) for (const alias of names(spec.alias)) if (!defs[alias]) defs[alias] = defs[key];
+    let parsed;
+    try { parsed = parseArgs({ args, options: defs, allowPositionals: true, strict: false, tokens: true }); }
+    catch (err) { this._fail(err.message, err); return { values: {}, positionals: [] }; }
+    const argv = { _: path.map((n) => n.name) };
+    for (const [key, value] of Object.entries(parsed.values)) {
+      const spec = this._specFor(options, key, value);
+      if (this._assign(argv, key, value, spec) === false) return null;
+    }
+    for (const [key, spec] of options) if (argv[spec.name] === undefined && spec.default !== undefined) this._assign(argv, key, spec.default, spec);
+    return { values: argv, positionals: parsed.positionals };
+  }
+  _fail(message, error) {
+    if (this.failHandler) return this.failHandler(message, error);
+    throw error || new Error(message);
+  }
+  _help(node, path = []) {
+    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'));
+    if (node.options.size) lines.push('\nOptions:\n' + [...node.options].map(([name, s]) => `  --${name}${s.alias ? `, -${names(s.alias).join(', -')}` : ''}  ${s.describe || s.description || ''}`).join('\n'));
+    if (node.epilogueText) lines.push(`\n${node.epilogueText}`);
+    process.stdout.write(lines.join('\n') + '\n');
+  }
+  async parse() {
+    if (this.args.includes('--get-yargs-completions')) {
+      const prefix = this.args.at(-1) || '';
+      let completionArgs = this.args.slice(this.args.indexOf('--get-yargs-completions') + 1, -1);
+      if (completionArgs[0] === this.script) completionArgs = completionArgs.slice(1);
+      const { path } = this._findPath(completionArgs);
+      const node = path.at(-1) || this.root;
+      node.build();
+      const argv = { _: path.map((n) => n.name) };
+      const completionFilter = (callback) => {
+        const values = [...node.children].filter((n) => n.name !== this.completionCommand)
+          .flatMap((n) => path.length ? [n.name] : [n.name, ...n.aliases]);
+        const opts = [...this._optionConfig(path)].map(([name]) => `--${name}`);
+        callback(null, [...new Set([...values, ...opts])]);
+      };
+      const finish = (values) => process.stdout.write([...new Set(values || [])]
+        .filter((x) => x.startsWith(prefix) || prefix.startsWith('-') && x.startsWith(prefix)).join('\n') + '\n');
+      if (this.completionHandler) {
+        this.completionHandler(prefix, argv, completionFilter, finish);
+      } else {
+        completionFilter((err, values) => finish(values));
+      }
+      return;
+    }
+    if (this.args[0] === 'help') {
+      const target = this._findPath(this.args.slice(1));
+      if (this.args.length === 1 || target.path.length) {
+        const node = target.path.at(-1) || this.root;
+        node.build();
+        this._help(node, target.path.map((n) => n.name));
+        return;
+      }
+    }
+    const { path, commandArgs, discoveryConsumed } = this._findPath(this.args);
+    const node = path.at(-1) || this.root;
+    node.build();
+    if (commandArgs.includes('--help') || commandArgs.includes('-h')) { this._help(node, path.map((n) => n.name)); return; }
+    const firstWord = this.args.find((arg, index) => !discoveryConsumed.has(index) && !arg.startsWith('-'));
+    if (this.strictCmd && !path.length && firstWord && !this._lookup(this.root.children, firstWord)) {
+      return this._fail(`Unknown command: ${firstWord}`);
+    }
+    if (this.strictCmd && path.length && node.children.length && firstWord
+      && !this._lookup(node.children, firstWord)) {
+      return this._fail(`Unknown command: ${firstWord}`);
+    }
+    if (!path.length && this.root.demand) return this._fail(this.root.demand.message);
+    const parsed = this._parseOptions(commandArgs, path);
+    if (!parsed) return;
+    const argv = parsed.values;
+    const specs = [...this._optionConfig(path).values()];
+    const positions = positionSpec(node.definition.command || '').map((position) => ({
+      ...position, ...node.positionals.get(position.name), name: position.name,
+    }));
+    parsed.positionals.forEach((value, i) => { if (positions[i]) argv[positions[i].name] = value; });
+    for (const spec of specs) if (spec.demandOption && argv[spec.name] === undefined) return this._fail(`Missing required argument: --${spec.name}`);
+    for (const pos of positions) if (pos.required && argv[pos.name] === undefined) return this._fail(`Missing required argument: ${pos.name}`);
+    for (const middleware of this.middlewares) await middleware(argv);
+    for (const commandNode of path) for (const middleware of commandNode.middlewares) await middleware(argv);
+    if (node.definition.handler) await node.definition.handler(argv);
+    else if (node.demand?.count && !path.length) return this._fail(node.demand.message);
+  }
+}
+
+export function yargs(args = []) { return new LocalCLI(args); }
+export function hideBin(argv) { return argv.slice(2); }
+export default yargs;

package/src/cli.js

@@ -1,7 +1,6 @@
-// Root CLI using yargs
+// Root CLI using the local yargs-compatible adapter
 
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
+import yargs, { hideBin } from './cli-adapter.js';
 import process from 'node:process';
 import path from 'node:path';
 import fs from 'node:fs';
@@ -387,14 +386,13 @@ export function buildCLI() {
     // 2. When the current word is an exact ALIAS (e.g. "inc" for incidents),
     //    yargs descends into that command's subcommands, so a still-being-
     //    typed "jsn inc<TAB>" offers subcommands that can't match the prefix.
-    //    When completing the FIRST word (depth 1, the command slot), merge
-    //    in the root command list — the shell's compgen prefix-filters the
-    //    final list anyway.
+    //    When completing the FIRST word, merge in the root command list — the
+    //    shell's compgen prefix-filters the final list anyway.
     .completion('__completion', false, (current, argv, completionFilter, done) => {
       completionFilter((err, completions) => {
         let out = completions || [];
         const depth = (argv._ || []).length;
-        if (current && !current.startsWith('-') && depth <= 2) {
+        if (current && !current.startsWith('-') && depth === 0) {
           out = [...new Set([...out, ...rootCommands])];
         }
         done([...new Set(out)]);

package/src/commands/docs/community.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import TurndownService from 'turndown';
-import matter from 'gray-matter';
+import { parseFrontmatter, stringifyFrontmatter } from '../../frontmatter.js';
 import Database from 'better-sqlite3';
 import { getDocsCommunityDir, getDocsDbPath, docsDbExists } from './db.js';
 import { refreshDocs } from './refresh.js';
@@ -166,7 +166,7 @@ export function slugify(title, fallback = 'untitled') {
 }
 
 function frontmatter(body, data) {
-  return matter.stringify(body, data);
+  return stringifyFrontmatter(body, data);
 }
 
 // --- Write a community doc to disk ---
@@ -311,7 +311,7 @@ function buildUrlIndex() {
       if (entry.isDirectory()) walk(full);
       else if (entry.name.toLowerCase().endsWith('.md')) {
         try {
-          const parsed = matter(fs.readFileSync(full, 'utf8'));
+          const parsed = parseFrontmatter(fs.readFileSync(full, 'utf8'));
           if (parsed.data.canonical_url) index.set(parsed.data.canonical_url, full);
         } catch { /* ignore */ }
       }

package/src/commands/docs/ingest.js

@@ -2,7 +2,7 @@
 
 import fs from 'node:fs';
 import { createHash } from 'node:crypto';
-import matter from 'gray-matter';
+import { parseFrontmatter } from '../../frontmatter.js';
 import { openDocsDb, closeDocsDb, initDocsSchema, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
@@ -35,7 +35,7 @@ export function ingestDocs(opts = {}) {
       let data = {};
       let body = raw;
       try {
-        const parsed = matter(raw);
+        const parsed = parseFrontmatter(raw);
         data = parsed.data || {};
         body = parsed.content || '';
       } catch {

package/src/commands/docs/refresh.js

@@ -3,7 +3,7 @@
 
 import fs from 'node:fs';
 import { createHash } from 'node:crypto';
-import matter from 'gray-matter';
+import { parseFrontmatter } from '../../frontmatter.js';
 import { openDocsDb, closeDocsDb, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
@@ -72,7 +72,7 @@ export function refreshDocs(opts = {}) {
       const stat = fs.statSync(file);
       let data = {}, body = raw;
       try {
-        const parsed = matter(raw);
+        const parsed = parseFrontmatter(raw);
         data = parsed.data || {};
         body = parsed.content || '';
       } catch {

package/src/commands/setup.js

@@ -1,3 +1,4 @@
+import { createPrompt, useKeypress, usePagination, useState, isDownKey, isEnterKey, isUpKey } from '@inquirer/core';
 import { loginWizard, modifyProfile, removeProfile, pickProfile } from './auth.js';
 import { setActiveProfile } from '../config.js';
 import { errUsage } from '../errors.js';
@@ -7,18 +8,44 @@ import { declareCapabilities } from '../capabilities.js';
 // (Not in the daily-check skip-list: legacy behavior checks for updates here.)
 declareCapabilities('setup', { noInstance: true });
 
-/** Interactive hub: what do you want to do? Returns 'add' | 'switch' | 'remove' | 'modify'. */
-export async function authHubMenu() {
-  const { select } = await import('@inquirer/prompts');
-  return select({
-    message: 'What would you like to do?',
-    choices: [
-      { name: 'Add a new instance', value: 'add' },
-      { name: 'Switch to a different instance', value: 'switch' },
-      { name: 'Remove an instance', value: 'remove' },
-      { name: 'Modify an instance', value: 'modify' },
-    ],
+const HUB_CHOICES = [
+  { name: 'Add a new instance', value: 'add' },
+  { name: 'Switch to a different instance', value: 'switch' },
+  { name: 'Remove an instance', value: 'remove' },
+  { name: 'Modify an instance', value: 'modify' },
+];
+
+/** The setup hub prompt; q and Escape resolve with no selected action. */
+export const authHubPrompt = createPrompt((config, done) => {
+  const [active, setActive] = useState(0);
+  const choices = config.choices;
+
+  useKeypress((key) => {
+    if (key.name === 'q' || key.name === 'escape') {
+      done(undefined);
+      return;
+    }
+    if (isEnterKey(key)) {
+      done(choices[active].value);
+      return;
+    }
+    if (isUpKey(key) && active > 0) setActive(active - 1);
+    if (isDownKey(key) && active < choices.length - 1) setActive(active + 1);
   });
+
+  const page = usePagination({
+    items: choices,
+    active,
+    pageSize: choices.length,
+    loop: false,
+    renderItem: ({ item, isActive }) => `${isActive ? '❯' : ' '} ${item.name}`,
+  });
+  return `${config.message}\n${page}\n\n↑↓ navigate • ⏎ select • q/Esc exit`;
+});
+
+/** Interactive hub: what do you want to do? Returns an action or undefined on exit. */
+export async function authHubMenu({ promptFn = authHubPrompt, input, output } = {}) {
+  return promptFn({ message: 'What would you like to do?', choices: HUB_CHOICES }, { input, output });
 }
 
 /**
@@ -36,7 +63,7 @@ export async function dispatchSetupAction(app, argv, action) {
   } else if (action === 'remove') {
     const name = await pickProfile(app, 'Remove which instance?');
     await removeProfile(app, name);
-  } else { // modify
+  } else if (action === 'modify') {
     await modifyProfile(app, argv);
   }
 }
@@ -60,6 +87,7 @@ export function setupCmd(wrap) {
         return;
       }
       const action = await authHubMenu();
+      if (action === undefined) return;
       await dispatchSetupAction(app, argv, action);
     }),
   };

package/src/commands/skill.js

@@ -330,7 +330,7 @@ export function skillCmd(wrap) {
                 ? `Where should the jsn skill be installed? (${outdated.length} outdated)`
                 : 'Where should the jsn skill be installed?';
 
-              const { default: checkbox } = await import('@inquirer/checkbox');
+              const { checkbox } = await import('@inquirer/prompts');
               const choices = Object.entries(TARGET_NAMES).map(([key, label]) => {
                 const dir = AGENT_SKILL_DIRS[key];
                 const targetPath = key === 'cursor'

package/src/frontmatter.js

@@ -0,0 +1,48 @@
+import yaml from 'js-yaml';
+
+const DEFAULT_DELIMITERS = ['---', '---'];
+
+function delimiters(options = {}) {
+  const value = options.delimiters || DEFAULT_DELIMITERS;
+  if (!Array.isArray(value) || value.length !== 2 || value.some((item) => typeof item !== 'string')) {
+    throw new TypeError('delimiters must be a two-item string array');
+  }
+  return value;
+}
+
+/** Parse the YAML frontmatter format used by the docs commands. */
+export function parseFrontmatter(input, options = {}) {
+  const source = String(input).replace(/^\uFEFF/, '');
+  const [open, close] = delimiters(options);
+  const empty = { data: {}, content: source };
+
+  if (!source.startsWith(open) || source.charAt(open.length) === open.slice(-1)) return empty;
+
+  let frontmatter = source.slice(open.length);
+  // gray-matter accepts an optional language suffix, which is only relevant
+  // here for the YAML spelling (`---yaml`).
+  if (frontmatter.startsWith('yaml\r\n') || frontmatter.startsWith('yaml\n')) {
+    frontmatter = frontmatter.slice(4);
+  }
+
+  const closeIndex = frontmatter.indexOf(`\n${close}`);
+  const raw = closeIndex === -1 ? frontmatter : frontmatter.slice(0, closeIndex);
+  const parsed = yaml.load(raw);
+  const data = parsed === undefined ? {} : parsed;
+
+  if (closeIndex === -1) return { data, content: '' };
+
+  let content = frontmatter.slice(closeIndex + close.length + 1);
+  if (content.startsWith('\r')) content = content.slice(1);
+  if (content.startsWith('\n')) content = content.slice(1);
+  return { data, content };
+}
+
+/** Serialize docs metadata and body using gray-matter-compatible YAML framing. */
+export function stringifyFrontmatter(body, data, options = {}) {
+  const [open, close] = delimiters(options);
+  const yamlText = yaml.dump(data, options).trim();
+  const prefix = yamlText === '{}' ? '' : `${open}\n${yamlText}\n${close}\n`;
+  const content = String(body);
+  return prefix + (content.endsWith('\n') ? content : `${content}\n`);
+}

package/src/sdk.js

@@ -75,7 +75,11 @@ export class SDKClient {
       case 'oauth':
         if (!skipOAuthSession) {
           const cookies = await this._warmSession();
-          if (cookies) req.headers.set('Cookie', cookies);
+          if (cookies && this.sessionUserToken) {
+            req.headers.set('Cookie', cookies);
+            req.headers.set('X-UserToken', this.sessionUserToken);
+            break;
+          }
         }
         req.headers.set('Authorization', `Bearer ${creds.access_token}`);
         break;
@@ -262,6 +266,8 @@ export class SDKClient {
 
   /**
    * Upload a file as a new attachment on a record.
+   * Uses ServiceNow's binary attachment endpoint so file bytes are not expanded
+   * into base64 or embedded in a sys.scripts.do form body.
    * @param {string} table - parent table name (e.g. 'incident')
    * @param {string} sysID - parent record sys_id
    * @param {Buffer|string} content - file bytes or path
@@ -270,29 +276,30 @@ export class SDKClient {
    */
   async addAttachment(table, sysID, content, fileName) {
     const contentBuffer = Buffer.isBuffer(content) ? content : Buffer.from(String(content));
-    const script = [
-      '(function() {',
-      `  var record = new GlideRecord(${scriptString(table)});`,
-      `  if (!record.get(${scriptString(sysID)})) throw new Error('Record not found');`,
-      '  var attachment = new GlideSysAttachment();',
-      `  var fileName = ${scriptString(fileName)};`,
-      `  var content = ${scriptString(contentBuffer.toString('base64'))};`,
-      '  var sysId;',
-      "  if (typeof attachment.writeBase64 === 'function') {",
-      "    sysId = attachment.writeBase64(record, fileName, 'application/octet-stream', content);",
-      '  } else {',
-      "    sysId = new Attachment().write(record.getTableName(), record.getUniqueValue(), fileName, 'application/octet-stream', GlideStringUtil.base64DecodeAsBytes(content));",
-      '  }',
-      "  if (!sysId) throw new Error('Attachment was not created');",
-      "  gs.print('JSN_ATTACHMENT_RESULT:' + JSON.stringify({ sys_id: sysId }));",
-      '}());',
-    ].join('\n');
-    const output = await this.executeScript(script, '');
-    const result = parseAttachmentResult(output);
-    if (!result?.sys_id) {
-      throw new Error('Attachment upload returned no attachment sys_id');
+    const params = new URLSearchParams({
+      table_name: String(table),
+      table_sys_id: String(sysID),
+      file_name: String(fileName),
+    });
+    const endpoint = `${this.baseURL}/api/now/attachment/file?${params.toString()}`;
+
+    try {
+      const response = await this.request(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/octet-stream' },
+        body: contentBuffer,
+      });
+      const result = response?.result;
+      if (!result?.sys_id) {
+        throw new Error('Attachment upload returned no attachment sys_id');
+      }
+      return result;
+    } catch (err) {
+      if (err?.status === 413) {
+        throw errAPI(413, 'Attachment is too large for the ServiceNow attachment endpoint. Reduce the file size or increase the instance attachment limit.');
+      }
+      throw err;
     }
-    return result;
   }
 
   async getCurrentUser({ touchLastSeen = true } = {}) {
@@ -824,10 +831,12 @@ export class SDKClient {
           method: 'GET',
           headers: serializeCookies(cookieJar) ? { Cookie: serializeCookies(cookieJar) } : {},
         }));
-        collectSetCookies(cookieJar, await this._fetchWithAuth(login, {
+        const finalLogin = await fetch(new Request(login, {
           method: 'POST',
           headers: serializeCookies(cookieJar) ? { Cookie: serializeCookies(cookieJar) } : {},
         }));
+        collectSetCookies(cookieJar, finalLogin);
+        this.sessionUserToken = finalLogin.headers.get('x-usertoken-response') || '';
         const cookies = serializeCookies(cookieJar);
         this.oauthCookies = cookies;
         return cookies;
@@ -915,27 +924,6 @@ export class SDKClient {
   }
 }
 
-function scriptString(value) {
-  return JSON.stringify(String(value)).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
-}
-
-function parseAttachmentResult(output) {
-  if (!output) return null;
-  const lines = String(output).split(/\r?\n/).reverse();
-  for (const line of lines) {
-    const candidate = line.replace(/^\*\*\* Script:\s*/, '').trim();
-    const markerCandidate = candidate.replace(/^JSN_ATTACHMENT_RESULT:\s*/, '');
-    if (!markerCandidate.startsWith('{')) continue;
-    try {
-      const result = JSON.parse(markerCandidate);
-      if (result && typeof result === 'object') return result;
-    } catch {
-      // Ignore unrelated script output and keep looking for the result marker.
-    }
-  }
-  return null;
-}
-
 function detectScriptError(output) {
   const lines = String(output || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
   const errorLine = lines.find(line => /(?:ReferenceError|TypeError|RhinoEcmaError|Script execution error|undefined is not a function|is not defined)/i.test(line));