@jacebenson/jsn 4.0.0 → 4.0.2

package/src/commands/skill.js

@@ -14,7 +14,7 @@ const SKILL_REPO_PATH = path.join(
   '..', '..', 'skills', SKILL_NAME, 'SKILL.md'
 );
 
-const SKILL_RAW_URL = 'https://raw.githubusercontent.com/jacebenson/jsn/nodejs/skills/servicenow/SKILL.md';
+const SKILL_RAW_URL = 'https://raw.githubusercontent.com/jacebenson/jsn/main/skills/servicenow/SKILL.md';
 
 /**
  * Resolve the user's real home directory, even when Hermes overrides $HOME.
@@ -62,11 +62,6 @@ function hermesSkillDir() {
   return path.join(base, 'skills', SKILL_NAME);
 }
 
-/** Resolve the installed SKILL.md path for Hermes. */
-function hermesSkillPath() {
-  return path.join(hermesSkillDir(), 'SKILL.md');
-}
-
 // Known agent skill directories (personal/user-level)
 // Keyed by agent name for the --target flag
 // Each value is the directory for the <name>/SKILL.md file

package/src/commands/tickets.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
 
 export function ticketsCmd(wrap) {
   return {
@@ -60,6 +60,7 @@ export function ticketsCmd(wrap) {
           aliases: ['get'],
           describe: 'Show a ticket',
           handler: wrap(async (argv, app) => {
+            assertSafeExactMatch(argv.number);
             const params = new URLSearchParams();
             params.set('sysparm_query', `number=${argv.number}`);
             params.set('sysparm_limit', '1');
@@ -87,6 +88,7 @@ export function ticketsCmd(wrap) {
           builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
           handler: wrap(async (argv, app) => {
             const recordData = JSON.parse(argv.data);
+            assertSafeExactMatch(argv.number);
             const findParams = new URLSearchParams();
             findParams.set('sysparm_query', `number=${argv.number}`);
             findParams.set('sysparm_limit', '1');
@@ -103,6 +105,7 @@ export function ticketsCmd(wrap) {
           command: 'delete <number>',
           describe: 'Delete a ticket',
           handler: wrap(async (argv, app) => {
+            assertSafeExactMatch(argv.number);
             const findParams = new URLSearchParams();
             findParams.set('sysparm_query', `number=${argv.number}`);
             findParams.set('sysparm_limit', '1');

package/src/commands/users.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
 
 export function usersCmd(wrap) {
   return {
@@ -57,6 +57,7 @@ export function usersCmd(wrap) {
           describe: 'Show a user by user_name or sys_id',
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
+            assertSafeExactMatch(id);
             const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
             const params = new URLSearchParams();
             params.set('sysparm_query', isSysID ? `sys_id=${id}` : `user_name=${id}`);
@@ -104,6 +105,7 @@ export function usersCmd(wrap) {
             .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
+            assertSafeExactMatch(id);
             const recordData = JSON.parse(argv.data);
             const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
             const params = new URLSearchParams();
@@ -130,6 +132,7 @@ export function usersCmd(wrap) {
           describe: 'Delete a user by user_name or sys_id',
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
+            assertSafeExactMatch(id);
             const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
             const params = new URLSearchParams();
             params.set('sysparm_query', isSysID ? `sys_id=${id}` : `user_name=${id}`);

package/src/errors.js

@@ -126,3 +126,29 @@ export function asError(err) {
 export function isErrorCode(err, code) {
   return err instanceof AppError && err.code === code;
 }
+
+/**
+ * Format a safety-guard failure (mutation guard middleware in cli.js).
+ * In JSON mode writes the documented error envelope to stdout so piped
+ * consumers (`jsn ... --json | jq`) get a structured error instead of a
+ * raw stderr message. Otherwise writes human text to stderr.
+ * Always exits non-zero via guardExit.
+ */
+export function guardError(argv, { code, message, hint = '' }) {
+  if (argv?.format === 'json') {
+    return {
+      stream: 'stdout',
+      text: JSON.stringify({ ok: false, error: message, code, hint }) + '\n',
+    };
+  }
+  let text = `Error: ${message}\n`;
+  if (hint) text += `\n${hint}\n`;
+  return { stream: 'stderr', text };
+}
+
+export function guardExit(argv, opts) {
+  const { stream, text } = guardError(argv, opts);
+  if (stream === 'stdout') process.stdout.write(text);
+  else process.stderr.write(text);
+  process.exit(1);
+}

package/src/helpers.js

@@ -1,8 +1,47 @@
 // Shared helper utilities
 
 import fs from 'node:fs';
+import readline from 'node:readline';
 import { paginatedSearch } from './paginated-search.js';
 import { isTTY, FormatAuto } from './output.js';
+import { getActiveProfile } from './config.js';
+
+/**
+ * Confirm a destructive action before executing.
+ *
+ * Default posture is ASK: interactive terminals get a y/N prompt;
+ * non-interactive invocation (pipes, scripts, AI agents) is rejected
+ * unless --force is passed. A profile can opt out entirely with the
+ * per-instance `skip_confirmations` flag (set via `auth login
+ * --skip-confirmations`).
+ *
+ * @param {object} app — app instance (reads active profile from app.config)
+ * @param {object} argv — parsed args (checks argv.force)
+ * @param {string} question — e.g. `Delete incident INC0010001?`
+ * @returns {Promise<boolean>} true when the action may proceed
+ * @throws when confirmation is required but denied/unavailable
+ */
+export async function confirmDelete(app, argv, question) {
+  const profile = getActiveProfile(app.config);
+  if (profile?.skip_confirmations === true) return true;
+  if (argv.force) return true;
+  if (isTTY(process.stdout) && isTTY(process.stdin)) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question(`${question} (y/N): `, resolve);
+    });
+    rl.close();
+    const response = answer.trim().toLowerCase();
+    if (response !== 'y' && response !== 'yes') {
+      throw new Error('Deletion cancelled');
+    }
+    return true;
+  }
+  throw new Error(
+    `${question} — confirmation required. Pass --force to skip, or set skip_confirmations on the profile to disable prompts.`
+  );
+}
+
 
 export function getStringField(record, field) {
   if (!record || typeof record !== 'object') return '';
@@ -74,6 +113,29 @@ export function resolveFieldsParam(columns) {
   return ['sys_id', ...columns].join(',');
 }
 
+// ServiceNow encoded-query metacharacters. In sysparm_query, `^` is the
+// AND-separator (^OR starts an OR clause), `= < > ~ !` are operators,
+// and `,` is used by IN lists. An identifier containing any of these
+// silently broadens an exact-match lookup — with sysparm_limit=1 the
+// wrong record wins (issue #143 finding #5). Exact-match identifiers
+// (numbers, sys_ids, names) never legitimately contain them.
+const QUERY_METACHARS = /[\^=<>~!,]/;
+
+/**
+ * Validate that an identifier is safe to use in an exact-match encoded
+ * query (field=value). Throws when the value contains characters that
+ * would change the query semantics.
+ * @param {string} value — identifier (number, sys_id, name)
+ */
+export function assertSafeExactMatch(value) {
+  if (value && QUERY_METACHARS.test(value)) {
+    throw new Error(
+      `Unsafe identifier for exact-match lookup: contains ServiceNow query characters (^ = < > ~ ! ,). ` +
+      `Refusing to build a query that could match more than the named record.`
+    );
+  }
+}
+
 /**
  * Shared interactive list helper with search-as-you-type.
  * All list commands that want an interactive TTY picker should use this.
@@ -89,12 +151,7 @@ export function resolveFieldsParam(columns) {
  * @param {string} opts.labelField — field used to match selection (default: 'name')
  * @returns {Promise<void>|null} null if no selection made or non-interactive
  */
-function vowelArticle(word) {
-  const first = word.charAt(0).toLowerCase();
-  return first === 'a' || first === 'e' || first === 'i' || first === 'o' || first === 'u' ? 'an' : 'a';
-}
-
-export async function interactiveList({ app, table, singular, columns, limit = 50, query = '', formatLabel, labelField = 'name' }) {
+export async function interactiveList({ app, table, singular, columns, limit = 50, _query = '', formatLabel, labelField = 'name' }) {
   app.requireInstance();
   const effectiveFormat = app.output.getFormat() === FormatAuto ? (isTTY(process.stdout) ? FormatAuto : FormatAuto) : app.output.getFormat();
   if (effectiveFormat !== FormatAuto || !isTTY(process.stdout) || !isTTY(process.stdin)) {
@@ -105,7 +162,7 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
   const pickerFields = pickerColumns.join(',');
 
   // Get total count
-  let totalCount = 0;
+  let totalCount;
   try {
     totalCount = await app.sdk.aggregateCount(table, '');
   } catch {
@@ -114,7 +171,7 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
   if (totalCount === 0) return null;
 
   // Paginated source adapter: (term, offset, { signal }) => choices[]
-  async function serverSource(term, offset, { signal } = {}) {
+  async function serverSource(term, offset, { signal: _signal } = {}) {
     try {
       const params = new URLSearchParams();
       params.set('sysparm_limit', String(limit));

package/src/mutations.js

@@ -62,8 +62,14 @@ export const MUTATION_COMMANDS = [
   ['catalog', 'create-item'],
   // Dev CRUD commands (root + `jsn dev` forms)
   ...DEV_CRUD_COMMANDS.flatMap(devCrudPaths),
-  // Dev eval (no sub-action)
+  // Dev eval (no sub-action) — both spellings must be gated:
+  // `jsn eval` (root) and legacy `jsn dev eval`
+  ['eval'],
   ['dev', 'eval'],
+  // Raw REST passthrough — can hit any endpoint with any method,
+  // so the whole command is a mutation surface on read-only profiles
+  ['rest'],
+  ['dev', 'rest'],
   // Scopes: create + set (root + dev forms)
   ['scopes', 'create'],
   ['scopes', 'set'],

package/src/output.js

@@ -200,12 +200,15 @@ export class OutputWriter {
           // Show lock icon for read-only profiles
           const lockIcon = p.read_only ? ' 🔒' : '';
 
+          // Show confirmations-off badge for skip_confirmations profiles
+          const confirmBadge = p.skip_confirmations ? ' ⚡' : '';
+
           if (p.name) {
-            this.writer.write(`${prefix}${authIcon} ${p.name} — ${p.instance}${lockIcon}${verifiedStr}${staleStr}\n`);
+            this.writer.write(`${prefix}${authIcon} ${p.name} — ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`);
           } else if (p.username) {
-            this.writer.write(`${prefix}${authIcon} ${p.instance} (as ${p.username})${lockIcon}${verifiedStr}${staleStr}\n`);
+            this.writer.write(`${prefix}${authIcon} ${p.instance} (as ${p.username})${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`);
           } else {
-            this.writer.write(`${prefix}${authIcon} ${p.instance}${lockIcon}${verifiedStr}${staleStr}\n`);
+            this.writer.write(`${prefix}${authIcon} ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`);
           }
         }
       }

package/src/paginated-search.js

@@ -43,7 +43,7 @@ export const paginatedSearch = createPrompt((config, done) => {
           setActive(0);
           setStatus('done');
         }
-      } catch (err) {
+      } catch {
         if (!controller.signal.aborted) {
           setStatus('done');
           setChoices([]);

package/src/records/inspect.js

@@ -1,4 +1,4 @@
-import { isHexString, getStringField } from '../helpers.js';
+import { isHexString, getStringField, assertSafeExactMatch } from '../helpers.js';
 
 export async function resolveIdentifier(app, table, identifier) {
   // If it looks like a sys_id (32 hex chars), use it directly
@@ -7,6 +7,7 @@ export async function resolveIdentifier(app, table, identifier) {
   }
 
   // Otherwise, assume it's a record number — query the table
+  assertSafeExactMatch(identifier);
   const params = new URLSearchParams();
   params.set('sysparm_query', `number=${identifier}`);
   params.set('sysparm_limit', '1');