@jacebenson/jsn 4.3.13-dev.91.1 → 4.3.13-dev.93.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.91.1",
+  "version": "4.3.13-dev.93.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -19,6 +19,7 @@ import { discoverCmd } from './commands/discover.js';
 import { setupCmd } from './commands/setup.js';
 import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
+import { attachmentsCmd } from './commands/attachments.js';
 import { cmdbCmd } from './commands/cmdb.js';
 import { snippetsCmd } from './commands/snippets.js';
 import { catalogCmd } from './commands/catalog.js';
@@ -409,6 +410,7 @@ export function buildCLI() {
     // DATA
     .command(cmdbCmd(wrap))
     .command(recordsCmd(wrap))
+    .command(attachmentsCmd(wrap))
     .command(transactionsCmd(wrap))
 
     .command(platformCmd(wrap))
@@ -486,7 +488,7 @@ export function buildCLI() {
     })
     .onParentDiscovery((argv, { path, subcommands }) => {
       // Reached only for a parent command that declares no default handler of
-      // its own (records attachments, docs community, and any future parent) —
+      // its own (attachments, docs community, and any future parent) —
       // the adapter used to fall through and exit 0 having printed nothing.
       // Children come from the registry, description included, so this list
       // cannot drift from the registrations the way a hand-written one did.

package/src/commands/attachments.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { confirmDelete, getStringField } from '../helpers.js';
+import { errUsage } from '../errors.js';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('attachments', { mutationSubcommands: ['upload', 'add'] });
+const identifier = value => {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value)) throw errUsage('Supply a safe record or attachment sys_id.');
+  return value;
+};
+
+// A server-provided filename may never choose directories or platform devices.
+export function attachmentFilename(value, id) {
+  const name = path.posix.basename(String(value || '').replaceAll('\\', '/'))
+    .replace(/[<>:"|?*\p{Cc}]/gu, '_').replace(/[. ]+$/g, '');
+  return !name || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name) ? `${id}.bin` : name;
+}
+
+export const attachmentsCmd = wrap => ({
+  command: 'attachments [subcommand]',
+  aliases: ['attachment'],
+  describe: 'List, download and upload files attached to any record',
+  builder: y => y
+    .epilogue([
+      'List files: jsn attachments list --sys-id <record-id>',
+      'Download by attachment ID: jsn attachments download <attachment-id> --out ./file.bin',
+      'Upload: jsn attachments upload ./file.txt --table incident --sys-id <record-id>',
+      'download/get and upload/add are aliases. The former records attachments subtree has moved here.',
+      'Downloads use a safe basename and refuse to overwrite existing local files unless --overwrite is supplied.',
+    ].join('\n'))
+    .command({
+      command: 'list',
+      describe: 'List attachment metadata for a parent record',
+      builder: y => y
+        .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
+        .option('table', { type: 'string', describe: 'Parent table (output context only)' }),
+      handler: wrap(async (argv, app) => {
+        const id = identifier(argv['sys-id']);
+        app.requireInstance();
+        const attachments = await app.sdk.listAttachments(id);
+        app.ok({ sys_id: id, table: argv.table || '', count: attachments.length, attachments,
+          context: { instance_url: app.getEffectiveInstance() } }, { summary: `${attachments.length} attachment(s) on record ${id}` });
+      }),
+    })
+    .command({
+      command: 'download <attachment-id>',
+      aliases: ['get'],
+      describe: 'Download file bytes by attachment ID; no parent record ID needed',
+      builder: y => y
+        .positional('attachment-id', { type: 'string', describe: 'Attachment sys_id' })
+        .option('out', { alias: 'o', type: 'string', describe: 'Local output path (default: safe attachment filename in cwd)' })
+        .option('overwrite', { type: 'boolean', default: false, describe: 'Replace an existing local file' }),
+      handler: wrap(async (argv, app) => {
+        const id = identifier(argv.attachmentId ?? argv['attachment-id']);
+        app.requireInstance();
+        let out = argv.out;
+        if (!out) {
+          const metadata = await app.sdk.request(`${app.sdk.baseURL}/api/now/attachment/${id}`, { method: 'GET' });
+          out = attachmentFilename(getStringField(metadata?.result, 'file_name'), id);
+        }
+        const bytes = await app.sdk.getAttachment(id);
+        await fs.writeFile(out, bytes, { flag: argv.overwrite ? 'w' : 'wx' });
+        app.ok({ sys_id: id, out, bytes: bytes.length }, { summary: `Wrote ${bytes.length} bytes to ${out}` });
+      }),
+    })
+    .command({
+      command: 'upload <file>',
+      aliases: ['add'],
+      describe: 'Upload a local file to a record (requires confirmation)',
+      builder: y => y
+        .positional('file', { type: 'string', describe: 'Local file to upload' })
+        .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
+        .option('table', { type: 'string', demandOption: true, describe: 'Parent table, for example incident' })
+        .option('name', { type: 'string', describe: 'Attachment filename (default: local basename)' })
+        .option('force', { type: 'boolean', default: false, describe: 'Skip upload confirmation after approval' }),
+      handler: wrap(async (argv, app) => {
+        const id = identifier(argv['sys-id']);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(argv.table)) throw errUsage('Supply a valid parent table name.');
+        app.requireInstance();
+        await confirmDelete(app, argv, `Upload "${argv.file}" as an attachment on ${argv.table} ${id}?`);
+        const content = await fs.readFile(argv.file);
+        const fileName = argv.name || path.basename(argv.file);
+        const created = await app.sdk.addAttachment(argv.table, id, content, fileName);
+        app.ok({ sys_id: getStringField(created, 'sys_id'), file_name: fileName, table: argv.table, recordsys_id: id }, { summary: `Attached ${fileName}` });
+      }),
+    }),
+});

package/src/commands/records.js

@@ -1,5 +1,3 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, verifyWriteBack } from '../helpers.js';
 import { listRecords, recordListParams, getRecord, createRecord, updateRecord, deleteRecord } from '../records-engine.js';
 import { unwrapSysId } from '../resolve-record.js';
@@ -7,7 +5,7 @@ import { errUsage } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
-  mutationSubcommands: ['create', 'update', 'delete', 'bulk', 'attachments add'],
+  mutationSubcommands: ['create', 'update', 'delete', 'bulk'],
 });
 
 const tableDefaultColumns = {
@@ -304,74 +302,6 @@ export function recordsCmd(wrap) {
             app.ok({ message: 'Record deleted', table: argv.table, sys_id: sysID }, { 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: 'aggregate',
           describe: 'Run ServiceNow Stats API aggregation with optional grouping',

package/src/mutations.js

@@ -33,7 +33,7 @@ function currentPaths(paths) {
  * Prefix match: a command whose argv._ path begins with a mutation pattern
  * IS that mutation (trailing positionals like a sys_id or file path don't
  * change the intent). This lets positional mutation subcommands (e.g.
- * `records attachments <id> add <file>`) be gated on read-only profiles.
+ * `attachments upload <file>`) be gated on read-only profiles.
  *
  * @param {object} argv — yargs parsed argv with `_` array
  * @param {Array<string[]>} [paths] — mutation path patterns; defaults to