@jacebenson/jsn 4.0.4 → 4.2.0

package/src/commands/groups.js

@@ -1,4 +1,7 @@
 import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('groups', { mutationSubcommands: ['create', 'update', 'delete'] });
 
 export function groupsCmd(wrap) {
   return {

package/src/commands/records.js

@@ -1,4 +1,11 @@
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch } from '../helpers.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('records', {
+  mutationSubcommands: ['create', 'update', 'delete', 'bulk', 'attachments add'],
+});
 
 const tableDefaultColumns = {
   incident: ['number', 'short_description', 'priority', 'state', 'assigned_to'],
@@ -12,9 +19,50 @@ const tableDefaultColumns = {
   sys_user_group: ['name', 'manager', 'email'],
   cmdb_ci: ['name', 'operational_status', 'ip_address'],
   cmdb_ci_server: ['name', 'operational_status', 'ip_address'],
+  cmdb_rel_ci: ['parent', 'type', 'child'],
   kb_knowledge: ['number', 'short_description', 'workflow_state', 'author'],
 };
 
+/**
+ * Raw sys_id from a reference field (string or {display_value, link, value}).
+ */
+function refSysId(field) {
+  if (!field) return '';
+  if (typeof field === 'string') return field;
+  if (typeof field === 'object') {
+    if (field.value && typeof field.value === 'string') return field.value;
+    if (field.link && typeof field.link === 'string') {
+      const parts = field.link.split('/');
+      return parts[parts.length - 1];
+    }
+  }
+  return '';
+}
+
+/**
+ * Breadcrumbs from a cmdb_rel_ci record into the cmdb relationships walk.
+ */
+export function relationshipBreadcrumbs(record) {
+  const parentId = refSysId(record.parent);
+  const childId = refSysId(record.child);
+  const crumbs = [];
+  if (childId) {
+    crumbs.push({
+      action: 'relationships',
+      cmd: `jsn cmdb relationships --ci ${childId}`,
+      description: "Traverse from this relationship's child CI",
+    });
+  }
+  if (parentId) {
+    crumbs.push({
+      action: 'impact',
+      cmd: `jsn cmdb relationships --ci ${parentId} --impact`,
+      description: 'Impact analysis upstream from the parent CI',
+    });
+  }
+  return crumbs;
+}
+
 function getDefaultColumns(table) {
   return tableDefaultColumns[table] || ['sys_id'];
 }
@@ -34,7 +82,8 @@ export function recordsCmd(wrap) {
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { type: 'number', default: 20, describe: 'Max records' })
-            .option('offset', { type: 'number', default: 0, describe: 'Offset' }),
+            .option('offset', { type: 'number', default: 0, describe: 'Offset' })
+            .option('count', { type: 'boolean', default: true, describe: 'Include the total-matching count (use --no-count to opt out)' }),
           handler: wrap(async (argv, app) => {
             const table = argv.table;
             const columns = argv.columns ? argv.columns.split(',') : getDefaultColumns(table);
@@ -51,13 +100,24 @@ export function recordsCmd(wrap) {
               const picked = await interactiveList({
                 app, table, singular: 'record', columns, limit: argv.limit, query, labelField: 'sys_id',
                 formatLabel: r => {
+                  // Relationship rows read best as "parent <type> child [sys_id]"
+                  if (table === 'cmdb_rel_ci') {
+                    const parent = getStringField(r, 'parent');
+                    const type = getStringField(r, 'type') || 'Related to';
+                    const child = getStringField(r, 'child');
+                    return `${parent || '?'} ${type} ${child || '?'} [${getStringField(r, 'sys_id')}]`;
+                  }
                   const cols = getDefaultColumns(table);
                   return cols.map(c => `${c}: ${getStringField(r, c) || '-'}`).join(' | ');
                 },
               });
               if (picked) {
                 picked._context = { instance_url: app.getEffectiveInstance(), table };
-                return app.ok(picked, { summary: `Record from ${table}` });
+                const crumbs = table === 'cmdb_rel_ci' ? relationshipBreadcrumbs(picked) : [];
+                return app.ok(picked, {
+                  summary: `Record from ${table}`,
+                  ...(crumbs.length ? { breadcrumbs: crumbs } : {}),
+                });
               }
             }
 
@@ -71,6 +131,16 @@ export function recordsCmd(wrap) {
             if (query) params.set('sysparm_query', query);
             const records = await app.sdk.list(table, params);
             const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+
+            // include_counts: default opt-in on every list. Opt out per-profile
+            // (config include_counts:false) or per-invocation (--no-count).
+            const profile = (app.config.profiles || {})[app.config.activeProfile || app.config.defaultProfile] || {};
+            const countsOn = argv.count !== false && profile.include_counts !== false;
+            let total;
+            if (countsOn && !argv['sys-id']) {
+              try { total = await app.sdk.aggregateCount(table, query); } catch { total = undefined; }
+            }
+
             const breadcrumbs = [
               { action: 'create', cmd: `jsn records create --table ${table} --data '{...}'`, description: 'Create a new record' },
               { action: 'filter', cmd: `jsn records list --table ${table} --query "priority=1"`, description: 'Filter: priority 1 only' },
@@ -102,9 +172,12 @@ export function recordsCmd(wrap) {
               count: records.length,
               columns,
               records: displayRecords,
-              pagination: { limit: argv.limit, offset: argv.offset },
+              pagination: { limit: argv.limit, offset: argv.offset, ...(total != null ? { total } : {}) },
               context: { instance_url: app.getEffectiveInstance() },
-            }, { summary: `${records.length} record(s) from ${table}`, breadcrumbs });
+            }, {
+              summary: `${records.length} record(s) from ${table}${total != null ? ` of ${total}` : ''}`,
+              breadcrumbs,
+            });
           }),
         })
         .command({
@@ -113,19 +186,34 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
-            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' }),
+            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
+            .option('attachments', { type: 'boolean', default: false, describe: 'Also list the record\'s attachments' }),
           handler: wrap(async (argv, app) => {
             assertSafeExactMatch(argv['sys-id']);
             const params = new URLSearchParams();
             params.set('sysparm_query', `sys_id=${argv['sys-id']}`);
             params.set('sysparm_limit', '1');
             params.set('sysparm_display_value', 'true');
-            if (argv.columns && argv.columns !== '*') params.set('sysparm_fields', argv.columns);
+            if (argv.columns && argv.columns !== '*') params.set('sysparm_fields', `sys_id,${argv.columns}`);
             const records = await app.sdk.list(argv.table, params);
             if (records.length === 0) {
               throw new Error(`Record not found: ${argv['sys-id']}`);
             }
-            app.ok(records[0], { summary: `Record from ${argv.table}` });
+            const record = records[0];
+            if (argv.attachments) {
+              try {
+                const atts = await app.sdk.listAttachments(argv['sys-id']);
+                record._attachments = atts;
+              } catch {
+                record._attachments = [];
+              }
+            }
+            record._context = { instance_url: app.getEffectiveInstance(), table: argv.table };
+            const crumbs = argv.table === 'cmdb_rel_ci' ? relationshipBreadcrumbs(record) : [];
+            app.ok(record, {
+              summary: `Record from ${argv.table}${argv.attachments ? ` (${(record._attachments || []).length} attachment(s))` : ''}`,
+              ...(crumbs.length ? { breadcrumbs: crumbs } : {}),
+            });
           }),
         })
         .command({
@@ -135,7 +223,8 @@ export function recordsCmd(wrap) {
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
-            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' }),
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
             const recordData = parseDataArg(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
@@ -143,6 +232,14 @@ export function recordsCmd(wrap) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
             const record = await app.sdk.create(argv.table, recordData);
+            const sysID = getStringField(record, 'sys_id');
+            const mismatches = await verifyWriteBack(app, argv.table, sysID, recordData);
+            for (const m of mismatches) {
+              process.stderr.write(`⚠ field "${m.field}" was not persisted (sent: "${m.sent}", got: "${m.got}")\n`);
+            }
+            if (mismatches.length > 0 && argv.strict) {
+              throw new Error(`Strict mode: ${mismatches.length} field(s) not persisted after create`);
+            }
             app.ok(record, { summary: `Created record in ${argv.table}` });
           }),
         })
@@ -154,7 +251,8 @@ export function recordsCmd(wrap) {
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
-            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' }),
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
             const recordData = parseDataArg(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
@@ -162,6 +260,13 @@ export function recordsCmd(wrap) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
             const record = await app.sdk.update(argv.table, argv['sys-id'], recordData);
+            const mismatches = await verifyWriteBack(app, argv.table, argv['sys-id'], recordData);
+            for (const m of mismatches) {
+              process.stderr.write(`⚠ field "${m.field}" was not persisted (sent: "${m.sent}", got: "${m.got}")\n`);
+            }
+            if (mismatches.length > 0 && argv.strict) {
+              throw new Error(`Strict mode: ${mismatches.length} field(s) not persisted after update`);
+            }
             app.ok(record, { summary: `Updated record in ${argv.table}` });
           }),
         })
@@ -178,6 +283,163 @@ export function recordsCmd(wrap) {
             app.ok({ message: 'Record deleted', table: argv.table, sys_id: argv['sys-id'] }, { summary: `Deleted record from ${argv.table}` });
           }),
         })
+        .command({
+          command: 'attachments',
+          describe: 'Work with attachments on a record',
+          builder: (y) => y
+            .command({
+              command: 'list',
+              describe: 'List attachments on a record',
+              builder: (yy) => yy
+                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
+                .option('table', { type: 'string', describe: 'Parent table name (context only)' }),
+              handler: wrap(async (argv, app) => {
+                app.requireInstance();
+                const attachments = await app.sdk.listAttachments(argv['sys-id']);
+                app.ok({
+                  sys_id: argv['sys-id'],
+                  table: argv.table || '',
+                  count: attachments.length,
+                  attachments,
+                  context: { instance_url: app.getEffectiveInstance() },
+                }, { summary: `${attachments.length} attachment(s) on record ${argv['sys-id']}` });
+              }),
+            })
+            .command({
+              command: 'get <attachment-id>',
+              describe: 'Download an attachment to a local file',
+              builder: (yy) => yy
+                .positional('attachment-id', { describe: 'Attachment sys_id', type: 'string' })
+                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id (used to resolve the file name)' })
+                .option('out', { alias: 'o', type: 'string', describe: 'Output file path (default: attachment file name in cwd)' }),
+              handler: wrap(async (argv, app) => {
+                app.requireInstance();
+                const buf = await app.sdk.getAttachment(argv['attachment-id']);
+                let name = argv.out;
+                if (!name) {
+                  // Best-effort: derive the file name from the attachment row.
+                  let fileName = `${argv['attachment-id']}.bin`;
+                  try {
+                    const rows = await app.sdk.listAttachments(argv['sys-id']);
+                    const hit = (rows || []).find((a) => getStringField(a, 'sys_id') === argv['attachment-id']);
+                    const fn = getStringField(hit, 'file_name');
+                    if (fn) fileName = fn;
+                  } catch { /* keep default */ }
+                  name = fileName;
+                }
+                await fs.promises.writeFile(name, buf);
+                app.ok({ sys_id: argv['attachment-id'], out: name, bytes: buf.length }, { summary: `Wrote ${buf.length} bytes to ${name}` });
+              }),
+            })
+            .command({
+              command: 'add <file>',
+              describe: 'Upload a file as a new attachment on a record (mutation)',
+              builder: (yy) => yy
+                .positional('file', { describe: 'Local file path to upload', type: 'string' })
+                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
+                .option('table', { type: 'string', demandOption: true, describe: 'Parent table for the record (e.g. incident)' })
+                .option('name', { type: 'string', describe: 'Display file name (default: basename of --file)' })
+                .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+              handler: wrap(async (argv, app) => {
+                app.requireInstance();
+                await confirmDelete(app, argv, `Upload "${argv.file}" as an attachment on ${argv.table} ${argv['sys-id']}?`);
+                const content = await fs.promises.readFile(argv.file);
+                const fileName = argv.name || path.basename(argv.file);
+                const created = await app.sdk.addAttachment(argv.table, argv['sys-id'], content, fileName);
+                app.ok({ sys_id: created?.sys_id, file_name: fileName, table: argv.table, recordsys_id: argv['sys-id'] }, { summary: `Attached ${fileName}` });
+              }),
+            })
+            .demandCommand(1, 'Specify an attachment action: list, get, or add'),
+        })
+        .command({
+          command: 'bulk',
+          describe: 'Bulk-update records matching a query. Dry-run by default — pass --execute to commit',
+          builder: (y) => y
+            .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
+            .option('query', { type: 'string', demandOption: true, describe: 'Encoded query selecting the records to update (e.g. "priority=1^state=1")' })
+            .option('set', { type: 'string', demandOption: true, describe: 'JSON object of fields to set (e.g. \'{"state":"3"}\')' })
+            .option('dry-run', { type: 'boolean', default: true, describe: 'Preview the count + a sample without mutating (default)' })
+            .option('execute', { type: 'boolean', default: false, describe: 'Perform the update after confirmation' })
+            .option('limit', { type: 'number', default: 200, describe: 'Max records to update when executing' })
+            .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation (with --execute)' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            let set;
+            try {
+              set = JSON.parse(argv.set);
+            } catch (e) {
+              throw new Error(`Invalid --set JSON: ${e.message}`, { cause: e });
+            }
+            if (!set || typeof set !== 'object' || Array.isArray(set)) {
+              throw new Error('--set must be a JSON object of field=value pairs');
+            }
+            if (!argv['dry-run'] && !argv.execute) {
+              argv.execute = true; // explicit --no-dry-run implies execute intent
+            }
+            const dryRun = argv['dry-run'] && !argv.execute;
+            const count = await app.sdk.aggregateCount(argv.table, argv.query);
+
+            if (dryRun) {
+              const params = new URLSearchParams();
+              params.set('sysparm_query', argv.query);
+              params.set('sysparm_limit', '5');
+              params.set('sysparm_fields', 'sys_id,number,name');
+              let sample = [];
+              try { sample = await app.sdk.list(argv.table, params); } catch { /* non-fatal */ }
+              app.ok({
+                table: argv.table,
+                query: argv.query,
+                set,
+                count,
+                dry_run: true,
+                sample,
+                context: { instance_url: app.getEffectiveInstance() },
+              }, { summary: `Dry run: ${count} record(s) in ${argv.table} would be updated` });
+              return;
+            }
+
+            await confirmDelete(app, argv, `Bulk update ${count} record(s) in ${argv.table}?`);
+            const sysIDs = [];
+            const pageSize = Math.min(argv.limit, 1000);
+            const params = new URLSearchParams();
+            params.set('sysparm_query', argv.query);
+            params.set('sysparm_limit', String(pageSize));
+            params.set('sysparm_fields', 'sys_id');
+            let offset = 0;
+            while (sysIDs.length < argv.limit) {
+              params.set('sysparm_offset', String(offset));
+              let recs;
+              try { recs = await app.sdk.list(argv.table, params); } catch { break; }
+              if (!recs || recs.length === 0) break;
+              for (const r of recs) {
+                const id = getStringField(r, 'sys_id');
+                if (id) sysIDs.push(id);
+              }
+              if (recs.length < pageSize) break;
+              offset += recs.length;
+            }
+            const targets = sysIDs.slice(0, argv.limit);
+            let updated = 0;
+            const failures = [];
+            for (const id of targets) {
+              try {
+                await app.sdk.update(argv.table, id, set);
+                updated += 1;
+              } catch (e) {
+                failures.push({ sys_id: id, error: e.message || String(e) });
+              }
+            }
+            app.ok({
+              table: argv.table,
+              query: argv.query,
+              set,
+              matched: count,
+              updated,
+              failed: failures,
+              context: { instance_url: app.getEffectiveInstance() },
+            }, { summary: `Updated ${updated} of ${count} matching record(s) in ${argv.table}` });
+          }),
+        })
         .command({
           command: 'inspect <table> <identifier>',
           aliases: ['debug', 'diag'],
@@ -213,8 +475,8 @@ export function recordsCmd(wrap) {
       console.log('Query and manage records in any ServiceNow table.');
       console.log('');
       console.log('Available subcommands:');
-      console.log('  list                  List records from a table');
-      console.log('  get                   Get a single record by sys_id');
+      console.log('  list                  List records from a table (includes total by default)');
+      console.log('  get                   Get a single record by sys_id (--attachments to include files)');
       console.log('  create                Create a record');
       console.log('  update                Update a record');
       console.log('  delete                Delete a record');

package/src/commands/setup.js

@@ -1,6 +1,11 @@
 import { loginWizard, modifyProfile, removeProfile, pickProfile } from './auth.js';
 import { setActiveProfile } from '../config.js';
 import { errUsage } from '../errors.js';
+import { declareCapabilities } from '../capabilities.js';
+
+// Setup manages local profile config — runs without a configured instance.
+// (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() {

package/src/commands/skill.js

@@ -7,6 +7,9 @@ import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 
 import { globalConfigPath } from '../config.js';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('skill', { noInstance: true, skipDailyChecks: true });
 
 const SKILL_NAME = 'servicenow';
 const SKILL_REPO_PATH = path.join(

package/src/commands/snippets.js

@@ -0,0 +1,155 @@
+// jsn snippets — named query snippets stored locally in the config dir.
+// Save a table+query (with optional columns) under a name, then run it later
+// against the active profile. No instance contact for save/list/delete/show.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { globalConfigDir } from '../config.js';
+import { resolveFieldsParam } from '../helpers.js';
+
+function snippetsPath() {
+  const dir = globalConfigDir();
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, 'snippets.json');
+}
+
+function loadSnippets() {
+  try {
+    const raw = fs.readFileSync(snippetsPath(), 'utf-8');
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function saveSnippets(map) {
+  fs.writeFileSync(snippetsPath(), JSON.stringify(map, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function snippetsCmd(wrap) {
+  return {
+    command: 'snippets [subcommand]',
+    describe: 'Save and re-run named query snippets (stored locally, no instance contact except run)',
+    builder: (yargs) => {
+      return yargs
+        .command({
+          command: 'save <name>',
+          describe: 'Save a named query snippet',
+          builder: (y) => y
+            .positional('name', { describe: 'Snippet name', type: 'string' })
+            .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "priority=1^active=true")' })
+            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns' })
+            .option('limit', { type: 'number', describe: 'Max records (default: unlimited / SDK default)' }),
+          handler: wrap(async (argv, app) => {
+            const snippets = loadSnippets();
+            snippets[argv.name] = {
+              table: argv.table,
+              query: argv.query || '',
+              columns: argv.columns ? argv.columns.split(',') : undefined,
+              limit: argv.limit,
+              saved_at: new Date().toISOString(),
+            };
+            saveSnippets(snippets);
+            app.ok({ name: argv.name, ...snippets[argv.name] }, { summary: `Saved snippet "${argv.name}"` });
+          }),
+        })
+        .command({
+          command: 'run <name>',
+          describe: 'Run a saved query snippet against the active profile (read-only)',
+          builder: (y) => y
+            .positional('name', { describe: 'Snippet name', type: 'string' })
+            .option('query', { type: 'string', describe: 'Override the encoded query' })
+            .option('limit', { type: 'number', describe: 'Override max records' })
+            .option('json', { type: 'boolean', describe: 'Force JSON output' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const snippets = loadSnippets();
+            const snip = snippets[argv.name];
+            if (!snip) {
+              const err = new Error(`Snippet "${argv.name}" not found`);
+              err.code = 'not_found';
+              throw err;
+            }
+            const columns = snip.columns || [];
+            const query = argv.query || snip.query || '';
+            const limit = argv.limit || snip.limit || 20;
+            const params = new URLSearchParams();
+            params.set('sysparm_limit', String(limit));
+            params.set('sysparm_offset', '0');
+            params.set('sysparm_display_value', 'all');
+            const fields = columns.length ? resolveFieldsParam(columns) : undefined;
+            if (fields) params.set('sysparm_fields', fields);
+            if (query) params.set('sysparm_query', query);
+            const records = await app.sdk.list(snip.table, params);
+            app.ok({
+              table: snip.table,
+              query,
+              columns,
+              count: records.length,
+              records,
+              context: { instance_url: app.getEffectiveInstance() },
+            }, { summary: `${records.length} record(s) from ${snip.table} (snippet "${argv.name}")` });
+          }),
+        })
+        .command({
+          command: 'list',
+          describe: 'List saved snippets',
+          handler: wrap(async (argv, app) => {
+            const snippets = loadSnippets();
+            const entries = Object.entries(snippets).map(([name, s]) => ({
+              name,
+              table: s.table,
+              query: s.query || '',
+            }));
+            app.ok({ count: entries.length, snippets: entries }, { summary: `${entries.length} saved snippet(s)` });
+          }),
+        })
+        .command({
+          command: 'show <name>',
+          describe: 'Show a saved snippet definition',
+          handler: wrap(async (argv, app) => {
+            const snippets = loadSnippets();
+            const snip = snippets[argv.name];
+            if (!snip) {
+              const err = new Error(`Snippet "${argv.name}" not found`);
+              err.code = 'not_found';
+              throw err;
+            }
+            app.ok({ name: argv.name, ...snip }, { summary: `Snippet "${argv.name}"` });
+          }),
+        })
+        .command({
+          command: 'delete <name>',
+          describe: 'Delete a saved snippet',
+          builder: (y) => y.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+          handler: wrap(async (argv, app) => {
+            const { confirmDelete } = await import('../helpers.js');
+            await confirmDelete(app, argv, `Delete snippet "${argv.name}"?`);
+            const snippets = loadSnippets();
+            if (!(argv.name in snippets)) {
+              const err = new Error(`Snippet "${argv.name}" not found`);
+              err.code = 'not_found';
+              throw err;
+            }
+            delete snippets[argv.name];
+            saveSnippets(snippets);
+            app.ok({ name: argv.name, deleted: true }, { summary: `Deleted snippet "${argv.name}"` });
+          }),
+        });
+    },
+    handler: () => {
+      console.log('Named query snippets (stored locally).');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  save <name>       Save a table+query snippet');
+      console.log('  run <name>        Run a snippet against the active profile');
+      console.log('  list              List saved snippets');
+      console.log('  show <name>       Show a snippet definition');
+      console.log('  delete <name>     Delete a snippet');
+      console.log('');
+      console.log('Run "jsn snippets <command> --help" for details.');
+    },
+  };
+}

package/src/commands/tickets.js

@@ -1,4 +1,8 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam } from '../helpers.js';
+import { resolveRecord, resolveSysId } from '../resolve-record.js';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('tickets', { mutationSubcommands: ['create', 'update', 'delete'] });
 
 export function ticketsCmd(wrap) {
   return {
@@ -60,16 +64,8 @@ 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');
-            params.set('sysparm_display_value', 'all');
-            const records = await app.sdk.list('task', params);
-            if (records.length === 0) {
-              throw new Error(`Ticket not found: ${argv.number}`);
-            }
-            app.ok(records[0], { summary: `Ticket ${argv.number}` });
+            const record = await resolveRecord(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
+            app.ok(record, { summary: `Ticket ${argv.number}` });
           }),
         })
         .command({
@@ -88,15 +84,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');
-            const records = await app.sdk.list('task', findParams);
-            if (records.length === 0) {
-              throw new Error(`Ticket not found: ${argv.number}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
             const updated = await app.sdk.update('task', sysID, recordData);
             app.ok(updated, { summary: `Updated ticket ${argv.number}` });
           }),
@@ -105,15 +93,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');
-            const records = await app.sdk.list('task', findParams);
-            if (records.length === 0) {
-              throw new Error(`Ticket not found: ${argv.number}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
             await app.sdk.delete('task', sysID);
             app.ok({ number: argv.number, message: 'Ticket deleted' }, { summary: `Deleted ticket ${argv.number}` });
           }),