@jacebenson/jsn 1.0.7 → 2.0.1

package/src/commands/catalog.js

@@ -0,0 +1,325 @@
+// Catalog item management commands
+// NOTE: This is an AI-friendly high-level command that wraps sc_cat_item + item_option_new
+
+import { resolveItemOptionType } from '../helpers.js';
+
+export function catalogCmd(wrap) {
+  return {
+    command: 'catalog <subcommand>',
+    aliases: ['cat'],
+    describe: 'Manage Service Catalog items and variables',
+    builder: (yargs) => {
+      return yargs
+        // ── create-item: Create a new catalog item definition ──
+        .command({
+          command: 'create-item',
+          describe: 'Create a catalog item (sc_cat_item) with variables',
+          builder: (y) => y
+            .option('name', { alias: 'n', type: 'string', demandOption: true, describe: 'Catalog item name' })
+            .option('short-description', { alias: 'd', type: 'string', describe: 'Short description' })
+            .option('description', { type: 'string', describe: 'Full description' })
+            .option('category', { alias: 'c', type: 'string', describe: 'Category name (created if missing)' })
+            .option('variable', { alias: 'v', type: 'array', describe: 'Variable definition in format "name:type:label" or "name:type" (e.g. "reason:multilinetext:Reason" or "start_date:date")' })
+            .option('variables', { type: 'string', describe: 'JSON object of variable values for submit_produce API (e.g. \'{"quantity":"100","reason":"Need more"}\')' })
+            .option('update-set', { type: 'string', describe: 'Update set sys_id or name to capture changes' }),
+          handler: wrap(async (argv, app) => {
+            // If --variables is provided, use submit_produce API (request against existing item)
+            if (argv.variables) {
+              let varsObj;
+              try {
+                varsObj = JSON.parse(argv.variables);
+              } catch {
+                throw new Error('--variables must be a valid JSON object, e.g. {"reason":"Need this"}');
+              }
+              // Resolve the catalog item sys_id from name if needed
+              let itemSysID = argv.name;
+              if (!itemSysID.match(/^[a-f0-9]{32}$/i)) {
+                const params = new URLSearchParams();
+                params.set('sysparm_query', `name=${itemSysID}`);
+                params.set('sysparm_limit', '1');
+                params.set('sysparm_fields', 'sys_id');
+                const items = await app.sdk.list('sc_cat_item', params);
+                if (items.length === 0) throw new Error(`Catalog item not found: ${itemSysID}`);
+                const item = items[0];
+                itemSysID = item.sys_id?.value || item.sys_id;
+              }
+              // Submit via submit_produce API
+              const endpoint = `${app.sdk.baseURL}/api/sn_sc/servicecatalog/items/${itemSysID}/submit_produce`;
+              const body = { variables: varsObj };
+              const result = await app.sdk.request(endpoint, {
+                method: 'POST',
+                body: JSON.stringify(body),
+              });
+              const reqID = result?.result?.sys_id || result?.result?.number || '';
+              app.ok({
+                requested_item: reqID,
+                item_id: itemSysID,
+                variables: varsObj,
+              }, {
+                summary: `Request created: ${result?.result?.number || reqID}`,
+                breadcrumbs: [
+                  { action: 'view', cmd: `jsn requests show ${reqID}`, description: 'View the request' },
+                ],
+              });
+              return;
+            }
+
+            // Original create-item flow: create a new catalog item definition
+            const name = argv.name;
+            const shortDesc = argv['short-description'] || '';
+            const description = argv.description || shortDesc;
+            let categoryID = '';
+
+            // Resolve or create category
+            if (argv.category) {
+              const catParams = new URLSearchParams();
+              catParams.set('sysparm_query', `title=${argv.category}`);
+              catParams.set('sysparm_limit', '1');
+              catParams.set('sysparm_fields', 'sys_id,title');
+              const cats = await app.sdk.list('sc_category', catParams);
+              if (cats.length > 0) {
+                categoryID = cats[0].sys_id?.value || cats[0].sys_id;
+              } else {
+                const newCat = await app.sdk.create('sc_category', {
+                  title: argv.category,
+                  description: `Category for ${argv.category}`,
+                });
+                categoryID = newCat.sys_id?.value || newCat.sys_id;
+              }
+            }
+
+            // Create the catalog item
+            const item = await app.sdk.create('sc_cat_item', {
+              name,
+              short_description: shortDesc,
+              description,
+              category: categoryID || undefined,
+              active: true,
+              type: 'item',
+              stage: 'requested',
+            });
+            const itemID = item.sys_id?.value || item.sys_id;
+
+            // Parse and create variables
+            const varDefs = [];
+            if (argv.variable) {
+              for (const v of argv.variable) {
+                const parts = String(v).split(':');
+                if (parts.length >= 2) {
+                  const typeName = parts.length >= 2 ? parts[parts.length - 2] : '';
+                  const label = parts.length >= 3 ? parts[parts.length - 1] : parts[0];
+                  const typeID = resolveItemOptionType(typeName);
+                  const sysName = parts[0].replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
+                  varDefs.push({
+                    name: sysName,
+                    question_text: label,
+                    type: typeID,
+                    order: varDefs.length * 100 + 100,
+                    cat_item: itemID,
+                    mandatory: true,
+                    active: true,
+                  });
+                }
+              }
+
+              for (const vd of varDefs) {
+                try {
+                  await app.sdk.create('item_option_new', vd);
+                } catch {
+                  // variable creation failure is non-fatal
+                }
+              }
+            }
+
+            app.ok({
+              sys_id: itemID,
+              name,
+              category: argv.category || null,
+              variables_created: varDefs.length,
+              update_set: argv['update-set'] || null,
+              instance_url: app.getEffectiveInstance(),
+            }, {
+              summary: `Created catalog item: ${name} (${varDefs.length} variable(s))`,
+              breadcrumbs: [
+                { action: 'view', cmd: `jsn records get --table sc_cat_item --sys-id ${itemID}`, description: 'View the catalog item' },
+                { action: 'edit', cmd: `jsn catalog update-item ${itemID} --name "${name}"`, description: 'Edit the catalog item' },
+              ],
+            });
+          }),
+        })
+        // ── items: List and show catalog items ──
+        .command({
+          command: 'items <subcommand>',
+          aliases: ['item'],
+          describe: 'Browse catalog items and inspect variables',
+          builder: (y) => y
+            .command({
+              command: 'list',
+              aliases: ['ls'],
+              describe: 'List catalog items',
+              builder: (y) => y
+                .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
+                .option('category', { type: 'string', describe: 'Filter by category' }),
+              handler: wrap(async (argv, app) => {
+                let query = 'ORDERBYname';
+                if (argv.category) query = `category.titleLIKE${argv.category}^${query}`;
+                const params = new URLSearchParams();
+                params.set('sysparm_query', query);
+                params.set('sysparm_limit', String(argv.limit));
+                params.set('sysparm_display_value', 'all');
+                params.set('sysparm_fields', 'sys_id,name,short_description,category,active');
+                const items = await app.sdk.list('sc_cat_item', params);
+                app.ok({
+                  table: 'sc_cat_item',
+                  count: items.length,
+                  columns: ['name', 'short_description', 'category', 'active'],
+                  records: items.map(r => ({
+                    sys_id: r.sys_id?.value || r.sys_id,
+                    name: r.name?.display_value || r.name,
+                    short_description: r.short_description?.display_value || r.short_description || '',
+                    category: r.category?.display_value || '',
+                    active: r.active?.display_value || r.active,
+                  })),
+                  context: { instance_url: app.getEffectiveInstance() },
+                }, { summary: `${items.length} catalog item(s)` });
+              }),
+            })
+            .command({
+              command: 'show <id>',
+              describe: 'Show a catalog item with variables and variable sets',
+              handler: wrap(async (argv, app) => {
+                let itemID = argv.id;
+                // Resolve name to sys_id
+                if (!itemID.match(/^[a-f0-9]{32}$/i)) {
+                  const params = new URLSearchParams();
+                  params.set('sysparm_query', `name=${itemID}`);
+                  params.set('sysparm_limit', '1');
+                  params.set('sysparm_fields', 'sys_id,name');
+                  const items = await app.sdk.list('sc_cat_item', params);
+                  if (items.length === 0) throw new Error(`Catalog item not found: ${itemID}`);
+                  itemID = items[0].sys_id?.value || items[0].sys_id;
+                }
+
+                // Get the catalog item
+                const item = await app.sdk.get('sc_cat_item', itemID);
+
+                // Get variables (item_option_new) for this catalog item
+                const varParams = new URLSearchParams();
+                varParams.set('sysparm_query', `cat_item=${itemID}^active=true`);
+                varParams.set('sysparm_limit', '100');
+                varParams.set('sysparm_display_value', 'all');
+                varParams.set('sysparm_fields', 'sys_id,name,question_text,type,order,mandatory,variable_set');
+                const variables = await app.sdk.list('item_option_new', varParams);
+
+                // Separate standalone vs variable-set variables
+                const standaloneVars = [];
+                const setVars = new Map(); // set_sys_id -> { name, label, variables: [] }
+                for (const v of variables) {
+                  const vs = v.variable_set?.value || v.variable_set;
+                  const entry = {
+                    sys_id: v.sys_id?.value || v.sys_id,
+                    name: v.name?.value || v.name || '',
+                    question_text: v.question_text?.display_value || v.question_text || '',
+                    type: v.type?.display_value || v.type,
+                    order: v.order?.display_value || v.order,
+                    mandatory: v.mandatory?.display_value || v.mandatory,
+                  };
+                  if (vs) {
+                    if (!setVars.has(vs)) {
+                      setVars.set(vs, { name: vs, label: vs, variables: [] });
+                    }
+                    setVars.get(vs).variables.push(entry);
+                  } else {
+                    standaloneVars.push(entry);
+                  }
+                }
+
+                // Try to resolve variable set names
+                for (const [sysID, setData] of setVars) {
+                  try {
+                    const vsRecord = await app.sdk.get('sc_cat_item_option_set', sysID);
+                    setData.name = vsRecord.name?.value || vsRecord.name || sysID;
+                    setData.label = vsRecord.label?.value || vsRecord.label || setData.name;
+                    setData.order = vsRecord.order?.display_value || vsRecord.order;
+                  } catch {
+                    // Can't resolve, keep sys_id as name
+                  }
+                }
+
+                app.ok({
+                  sys_id: itemID,
+                  name: item.name?.display_value || item.name,
+                  short_description: item.short_description?.display_value || item.short_description || '',
+                  description: item.description?.display_value || item.description || '',
+                  category: item.category?.display_value || '',
+                  active: item.active?.display_value || item.active,
+                  variables: {
+                    standalone: standaloneVars,
+                    variable_sets: Array.from(setVars.values()),
+                  },
+                  instance_url: app.getEffectiveInstance(),
+                }, {
+                  summary: `${item.name?.display_value || item.name} — ${standaloneVars.length + Array.from(setVars.values()).reduce((a, s) => a + s.variables.length, 0)} variable(s)`,
+                });
+              }),
+            })
+            .demandCommand(1, 'Specify a subcommand: list or show'),
+          handler: () => {},
+        })
+        // ── list-items: Legacy alias ──
+        .command({
+          command: 'list-items',
+          aliases: ['ls'],
+          describe: 'List catalog items (use "catalog items list" instead)',
+          builder: (y) => y
+            .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
+            .option('category', { type: 'string', describe: 'Filter by category' }),
+          handler: wrap(async (argv, app) => {
+            let query = 'ORDERBYname';
+            if (argv.category) query = `category.titleLIKE${argv.category}^${query}`;
+            const params = new URLSearchParams();
+            params.set('sysparm_query', query);
+            params.set('sysparm_limit', String(argv.limit));
+            params.set('sysparm_display_value', 'all');
+            params.set('sysparm_fields', 'sys_id,name,short_description,category,active');
+            const items = await app.sdk.list('sc_cat_item', params);
+            app.ok({
+              table: 'sc_cat_item',
+              count: items.length,
+              columns: ['name', 'short_description', 'category', 'active'],
+              records: items.map(r => ({
+                sys_id: r.sys_id?.value || r.sys_id,
+                name: r.name?.display_value || r.name,
+                short_description: r.short_description?.display_value || r.short_description || '',
+                category: r.category?.display_value || '',
+                active: r.active?.display_value || r.active,
+              })),
+              context: { instance_url: app.getEffectiveInstance() },
+            }, { summary: `${items.length} catalog item(s)` });
+          }),
+        });
+    },
+    handler: (argv) => {
+      if (!argv._[1]) {
+        console.log('Manage Service Catalog items.\n');
+        console.log('Commands:');
+        console.log('  create-item    Create a catalog item, or submit a request via submit_produce');
+        console.log('  items list     List catalog items');
+        console.log('  items show     Show catalog item details with variables');
+        console.log('\nExamples:');
+        console.log('  jsn catalog create-item "Request PTO" \\');
+        console.log('    --category "Time Off" \\');
+        console.log('    --short-description "Submit a PTO request" \\');
+        console.log('    --variable "start_date:date:Start Date" \\');
+        console.log('    --variable "type:select:Type" \\');
+        console.log('    --variable "reason:multilinetext:Reason/Notes"');
+        console.log('');
+        console.log('  # Submit a request via submit_produce:');
+        console.log('  jsn catalog create-item "Minecraft Coins" \\');
+        console.log('    --variables \'{"quantity":"100","reason":"Server upgrade"}\'');
+        console.log('\nVariable types: string, multilinetext, select, date, datetime, reference, checkbox, email');
+        console.log('\nRun "jsn catalog <command> --help" for details.');
+      }
+    },
+  };
+}

package/src/commands/changes.js

@@ -0,0 +1,7 @@
+import { buildTicketCommands } from './_ticket.js';
+
+const changeDefaultColumns = ['number', 'short_description', 'risk', 'state', 'assigned_to'];
+
+export function changesCmd(wrap) {
+  return buildTicketCommands('change_request', 'changes', 'chg', changeDefaultColumns, {}, null, wrap);
+}

package/src/commands/dev/_generic.js

@@ -0,0 +1,342 @@
+// Generic dev subcommand builder for table-based CRUD
+
+import { formatRecordForDisplay, getStringField, isHexString, parseDataArg } from '../../helpers.js';
+import { getCurrentUser, getCurrentApplication } from '../../context.js';
+import readline from 'node:readline';
+import search from '@inquirer/search';
+import { isTTY, FormatAuto } from '../../output.js';
+
+function vowelArticle(word) {
+  const first = word.charAt(0).toLowerCase();
+  return first === 'a' || first === 'e' || first === 'i' || first === 'o' || first === 'u' ? 'an' : 'a';
+}
+
+function buildHints(name, singular, readOnly) {
+  const crumbs = [];
+  if (!readOnly) {
+    crumbs.push({
+      action: 'create',
+      cmd: `jsn dev ${name} create --name ... --label "..."`,
+      description: `Create ${vowelArticle(singular)} ${singular}`,
+    });
+  }
+  crumbs.push({
+    action: 'show',
+    cmd: `jsn dev ${name} show <name_or_sys_id>`,
+    description: `Show ${singular} details`,
+  });
+  return crumbs;
+}
+
+function toSingular(name, explicitSingular) {
+  if (explicitSingular) return explicitSingular;
+  if (name.endsWith('ies')) return name.slice(0, -3) + 'y';
+  if (name.endsWith('es') && !name.endsWith('ses')) return name.slice(0, -2);
+  if (name.endsWith('s') && !name.endsWith('ss')) return name.slice(0, -1);
+  return name;
+}
+
+async function getCurrentScope(sdk) {
+  try {
+    const user = await getCurrentUser(sdk);
+    if (!user) return 'global';
+    const app = await getCurrentApplication(sdk, user.sys_id);
+    return app?.scope || 'global';
+  } catch {
+    return 'global';
+  }
+}
+
+async function checkScope(sdk, recordScope) {
+  const currentScope = await getCurrentScope(sdk);
+  if (currentScope === 'global') return null;
+  if (currentScope === recordScope) return null;
+  return { currentScope, recordScope };
+}
+
+export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {}) {
+  const showFields = opts.showFields !== undefined ? opts.showFields : null;
+  const singular = toSingular(name, opts.singular);
+  const readOnly = opts.readOnly || false;
+  const scopeValidation = opts.scopeValidation || false;
+  const showSummary = opts.showSummary || ((record, id) => `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${getStringField(record, 'name') || id}`);
+  const showBreadcrumbs = opts.showBreadcrumbs || ((record, id) => {
+    const crumbs = [
+      { action: 'list', cmd: `jsn dev ${name} list`, description: `Back to all ${name}` },
+    ];
+    if (!readOnly) {
+      crumbs.unshift(
+        { action: 'delete', cmd: `jsn dev ${name} delete ${id}`, description: `Delete this ${singular}` },
+        { action: 'update', cmd: `jsn dev ${name} update ${id} --data '{...}'`, description: `Update this ${singular}` }
+      );
+    }
+    return crumbs;
+  });
+
+  const builder = (yargs) => {
+    let y = yargs
+      .command({
+        command: 'list',
+        aliases: ['ls'],
+        describe: `List ${name}`,
+        builder: (y) => y
+          .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true^priority=1")' })
+          .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "name,label,super_class")' })
+          .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
+        handler: wrap(async (argv, app) => {
+          const query = argv.query || '';
+          const columns = argv.columns ? argv.columns.split(',') : defaultColumns;
+          const limit = argv.limit;
+
+          // Interactive picker in TTY with auto format and no explicit query
+          const interactive = isTTY(process.stdout) && isTTY(process.stdin);
+          if (interactive && app.output.getFormat() === FormatAuto && !query) {
+            const pickerColumns = ['sys_id', 'name', ...columns.filter(c => c !== 'name' && c !== 'sys_id')];
+            const pickerParams = new URLSearchParams();
+            pickerParams.set('sysparm_limit', String(limit));
+            pickerParams.set('sysparm_display_value', 'all');
+            pickerParams.set('sysparm_fields', pickerColumns.join(','));
+            pickerParams.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
+
+            const pickerRecords = await app.sdk.list(table, pickerParams);
+            if (pickerRecords.length === 0) {
+              app.ok({
+                table,
+                count: 0,
+                columns: pickerColumns,
+                records: [],
+                pagination: { limit, offset: 0 },
+                context: { instance_url: app.getEffectiveInstance() },
+              }, {
+                summary: `0 ${name}(s)`,
+                breadcrumbs: buildHints(name, singular, readOnly),
+              });
+              return;
+            }
+
+            const choices = pickerRecords.map(r => {
+              const recordName = getStringField(r, 'name') || getStringField(r, 'sys_id');
+              const scope = getStringField(r, 'sys_scope') || '';
+              let label = recordName;
+              if (scope && scope !== 'global') label += ` [${scope}]`;
+              return { name: label, value: recordName };
+            });
+
+            let selectedName;
+            try {
+              selectedName = await search({
+                message: `Select ${vowelArticle(singular)} ${singular}:`,
+                source: async (input) => {
+                  if (!input) return choices;
+                  const term = input.toLowerCase();
+                  return choices.filter(c => c.name.toLowerCase().includes(term));
+                },
+              });
+            } catch (err) {
+              if (err.name === 'ExitPromptError' || (err.message && err.message.includes('force closed'))) {
+                return;
+              }
+              throw err;
+            }
+
+            if (selectedName) {
+              const showParams = new URLSearchParams();
+              showParams.set('sysparm_query', `name=${selectedName}`);
+              showParams.set('sysparm_display_value', 'all');
+              showParams.set('sysparm_limit', '1');
+              const showRecords = await app.sdk.list(table, showParams);
+              if (showRecords.length === 0) {
+                throw new Error(`${singular} not found: ${selectedName}`);
+              }
+              const record = showRecords[0];
+              record._context = { instance_url: app.getEffectiveInstance(), table };
+              if (opts.onShow) {
+                await opts.onShow(record, app);
+              }
+              app.ok(record, {
+                summary: `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${selectedName}`,
+                breadcrumbs: [
+                  ...(readOnly ? [] : [{ action: 'update', cmd: `jsn dev ${name} update ${selectedName} --data '{...}'`, description: `Update this ${singular}` }]),
+                  { action: 'list', cmd: `jsn dev ${name} list`, description: `Back to all ${name}` },
+                ],
+              });
+            }
+            return;
+          }
+
+          // Non-interactive: text/table output
+          const params = new URLSearchParams();
+          params.set('sysparm_limit', String(limit));
+          params.set('sysparm_display_value', 'all');
+          params.set('sysparm_fields', ['sys_id', ...columns].join(','));
+          const q = query ? query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
+          params.set('sysparm_query', q);
+          const records = await app.sdk.list(table, params);
+          app.ok({
+            table,
+            count: records.length,
+            columns,
+            records: records.map(r => formatRecordForDisplay(r, columns)),
+            context: { instance_url: app.getEffectiveInstance() },
+          }, {
+            summary: `${records.length} ${name}(s)`,
+            breadcrumbs: buildHints(name, singular, readOnly),
+          });
+        }),
+      })
+      .command({
+        command: 'show <identifier>',
+        aliases: ['get'],
+        describe: `Show ${vowelArticle(singular)} ${singular} by name or sys_id`,
+        handler: wrap(async (argv, app) => {
+          const id = argv.identifier;
+          const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
+          const params = new URLSearchParams();
+          params.set('sysparm_query', `${queryField}=${id}`);
+          params.set('sysparm_limit', '1');
+          params.set('sysparm_display_value', 'all');
+          // Only restrict sysparm_fields if showFields is explicitly set.
+          // Go version fetches all fields for show unless explicitly restricted.
+          if (showFields && showFields.length > 0) {
+            params.set('sysparm_fields', [...new Set(['sys_id', ...showFields])].join(','));
+          }
+          const records = await app.sdk.list(table, params);
+          if (records.length === 0) {
+            throw new Error(`${singular} not found: ${id}`);
+          }
+          records[0]._context = {
+            instance_url: app.getEffectiveInstance(),
+            table,
+          };
+
+          if (opts.onShow) {
+            await opts.onShow(records[0], app);
+          }
+
+          const summary = typeof showSummary === 'function' ? showSummary(records[0], id) : showSummary;
+          const breadcrumbs = typeof showBreadcrumbs === 'function' ? showBreadcrumbs(records[0], id) : showBreadcrumbs;
+
+          app.ok(records[0], { summary, breadcrumbs });
+        }),
+      });
+
+    if (!readOnly) {
+      y = y
+        .command({
+          command: 'create',
+          describe: `Create a new ${singular}`,
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+          handler: wrap(async (argv, app) => {
+            const recordData = parseDataArg(argv);
+            const record = await app.sdk.create(table, recordData);
+            app.ok(record, {
+              summary: `Created ${singular}`,
+              breadcrumbs: [
+                { action: 'show', cmd: `jsn dev ${name} show ${getStringField(record, 'name') || getStringField(record, 'sys_id')}`, description: `View the new ${singular}` },
+              ],
+            });
+          }),
+        })
+        .command({
+          command: 'update <identifier>',
+          describe: `Update ${vowelArticle(singular)} ${singular}`,
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+          handler: wrap(async (argv, app) => {
+            const id = argv.identifier;
+            const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
+            const findParams = new URLSearchParams();
+            findParams.set('sysparm_query', `${queryField}=${id}`);
+            findParams.set('sysparm_limit', '1');
+            findParams.set('sysparm_display_value', 'all');
+            const records = await app.sdk.list(table, findParams);
+            if (records.length === 0) {
+              throw new Error(`${singular} not found: ${id}`);
+            }
+            const sysID = getStringField(records[0], 'sys_id');
+            const recordScope = getStringField(records[0], 'sys_scope');
+
+            if (scopeValidation) {
+              const scopeErr = await checkScope(app.sdk, recordScope);
+              if (scopeErr) {
+                throw new Error(`record is in scope '${scopeErr.recordScope}', but your current scope is '${scopeErr.currentScope}'. Switch scope first: jsn dev scopes set ${scopeErr.recordScope}`);
+              }
+            }
+
+            const recordData = parseDataArg(argv);
+            const updated = await app.sdk.update(table, sysID, recordData);
+            app.ok(updated, { summary: `Updated ${singular} ${id}` });
+          }),
+        })
+        .command({
+          command: 'delete <identifier>',
+          describe: `Delete ${vowelArticle(singular)} ${singular}`,
+          builder: (y) => y.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+          handler: wrap(async (argv, app) => {
+            const id = argv.identifier;
+            const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
+            const findParams = new URLSearchParams();
+            findParams.set('sysparm_query', `${queryField}=${id}`);
+            findParams.set('sysparm_limit', '1');
+            findParams.set('sysparm_display_value', 'all');
+            const records = await app.sdk.list(table, findParams);
+            if (records.length === 0) {
+              throw new Error(`${singular} not found: ${id}`);
+            }
+            const sysID = getStringField(records[0], 'sys_id');
+            const recordName = getStringField(records[0], 'name') || id;
+            const recordScope = getStringField(records[0], 'sys_scope');
+
+            if (scopeValidation) {
+              const scopeErr = await checkScope(app.sdk, recordScope);
+              if (scopeErr) {
+                throw new Error(`record is in scope '${scopeErr.recordScope}', but your current scope is '${scopeErr.currentScope}'. Switch scope first: jsn dev scopes set ${scopeErr.recordScope}`);
+              }
+            }
+
+            if (!argv.force && process.stdout.isTTY && process.stdin.isTTY) {
+              const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+              const answer = await new Promise((resolve) => {
+                rl.question(`Delete ${singular} '${recordName}'? (y/N): `, resolve);
+              });
+              rl.close();
+              const response = answer.trim().toLowerCase();
+              if (response !== 'y' && response !== 'yes') {
+                throw new Error('Deletion cancelled');
+              }
+            }
+
+            await app.sdk.delete(table, sysID);
+            app.ok({ name: recordName, sys_id: sysID, deleted: true }, { summary: `Deleted ${singular} '${recordName}'` });
+          }),
+        });
+    }
+
+    return y;
+  };
+
+  return {
+    command: `${name} [subcommand]`,
+    aliases: aliases || [],
+    describe: `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
+    builder,
+    handler: (_argv) => {
+      // This handler only runs when no subcommand is matched (the default case).
+      // Show help for the subcommands available.
+      console.log(`Manage ${name} from the ${table} table.`);
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list        List all records');
+      console.log('  show        Show record details');
+      if (!readOnly) {
+        console.log('  create      Create a new record');
+        console.log('  update      Update a record');
+        console.log('  delete      Delete a record');
+      }
+      console.log(`\nRun "jsn dev ${name} <command> --help" for details.`);
+    },
+  };
+}