@jacebenson/jsn 4.3.7 → 4.3.8

package/src/commands/diff.js

@@ -0,0 +1,205 @@
+import { declareCapabilities } from '../capabilities.js';
+import { errUsage, errUsageHint } from '../errors.js';
+import { resolveSession } from '../session.js';
+import { resolveRecord } from '../resolve-record.js';
+
+declareCapabilities('diff', {});
+
+const DEFAULT_IGNORED_FIELDS = [
+  'sys_created_by',
+  'sys_created_on',
+  'sys_mod_count',
+  'sys_updated_by',
+  'sys_updated_on',
+];
+
+function profileTarget(app, name, label) {
+  const session = resolveSession({ profile: name }, app.config);
+  if (session.unknownProfile || !session.profileName) {
+    throw errUsageHint(`Unknown ${label} profile "${name}"`, 'Run "jsn auth status" to list configured profiles.');
+  }
+  if (!session.instance || !session.profile) {
+    throw errUsage(`Profile "${name}" has no configured instance URL`);
+  }
+  return {
+    name: session.profileName,
+    instance: session.instance,
+    profile: session.profile,
+    username: session.username || '',
+    domain: session.domain || '',
+  };
+}
+
+function sdkForProfile(app, target) {
+  return app.getSDKForProfile(target.instance, {
+    profile: target.profile,
+    profileName: target.name,
+    username: target.username,
+    authMethod: target.profile.auth_method,
+    domain: target.domain,
+  });
+}
+
+async function fetchRecord(app, target, table, identifier) {
+  try {
+    const record = await resolveRecord(sdkForProfile(app, target), {
+      table,
+      identifier,
+      matchField: 'sys_id',
+      resource: 'Record',
+    });
+    return { status: 'found', record };
+  } catch (error) {
+    if (error?.code === 'not_found') return { status: 'missing', record: null };
+    if (error?.code === 'forbidden') return { status: 'forbidden', record: null, error: error.code };
+    if (error?.code === 'auth_error') return { status: 'auth_error', record: null, error: error.code };
+    return { status: 'error', record: null, error: error?.code || 'error' };
+  }
+}
+
+function stableValue(value) {
+  if (value && typeof value === 'object' && Object.hasOwn(value, 'value')) return value.value;
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, stableValue(value[key])]));
+  }
+  return value;
+}
+
+function equalValue(a, b) {
+  return JSON.stringify(stableValue(a)) === JSON.stringify(stableValue(b));
+}
+
+function displayValue(value) {
+  if (value && typeof value === 'object' && value.display_value != null) return String(value.display_value);
+  if (value == null) return 'null';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+function fieldDifference(field, status, a, b) {
+  return {
+    field,
+    status,
+    ...(a !== undefined ? { a } : {}),
+    ...(b !== undefined ? { b } : {}),
+  };
+}
+
+export function compareRecords(recordA, recordB, ignoredFields = DEFAULT_IGNORED_FIELDS) {
+  const ignored = new Set(ignoredFields);
+  const fields = [...new Set([
+    ...Object.keys(recordA || {}),
+    ...Object.keys(recordB || {}),
+  ])].filter(field => !ignored.has(field)).sort();
+  const differences = [];
+  for (const field of fields) {
+    const hasA = Object.hasOwn(recordA || {}, field);
+    const hasB = Object.hasOwn(recordB || {}, field);
+    if (!hasA && hasB) differences.push(fieldDifference(field, 'added', undefined, recordB[field]));
+    else if (hasA && !hasB) differences.push(fieldDifference(field, 'missing', recordA[field], undefined));
+    else if (!equalValue(recordA[field], recordB[field])) differences.push(fieldDifference(field, 'changed', recordA[field], recordB[field]));
+  }
+  return differences;
+}
+
+export function formatRecordDiff(data) {
+  const lines = [
+    `Record diff: ${data.table} ${data.identifiers.a}`,
+    `A: ${data.profiles.a.name} (${data.existence.a})`,
+    `B: ${data.profiles.b.name} (${data.existence.b})`,
+    `Status: ${data.status}`,
+  ];
+  if (data.status === 'error' || data.status === 'forbidden' || data.status === 'auth_error' || data.status === 'missing' || data.status === 'both_missing') return `${lines.join('\n')}\n`;
+  lines.push(`Ignored: ${data.ignored_fields.join(', ') || '(none)'}`);
+  if (data.differences.length === 0) lines.push('No field differences');
+  for (const difference of data.differences) {
+    const left = difference.a === undefined ? '(missing)' : displayValue(difference.a);
+    const right = difference.b === undefined ? '(missing)' : displayValue(difference.b);
+    lines.push(`${difference.status.toUpperCase()} ${difference.field}: ${left} -> ${right}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function ignoredFields(argv) {
+  if (argv['no-ignore']) return [];
+  return [...new Set([...DEFAULT_IGNORED_FIELDS, ...(argv.ignore || [])])].sort();
+}
+
+export function diffCmd(wrap) {
+  return {
+    command: 'diff [subcommand]',
+    describe: 'Compare records across configured profiles (read-only)',
+    builder: (y) => y.command({
+      command: 'record',
+      describe: 'Compare one record across two profiles',
+      builder: (b) => b
+        .option('table', { type: 'string', demandOption: true, describe: 'ServiceNow table' })
+        .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id or exact identifier' })
+        .option('profile-a', { type: 'string', demandOption: true, describe: 'Profile for side A' })
+        .option('profile-b', { type: 'string', demandOption: true, describe: 'Profile for side B' })
+        .option('ignore', { type: 'string', array: true, default: [], describe: 'Additional field to ignore (repeatable)' })
+        .option('no-ignore', { type: 'boolean', default: false, describe: 'Do not ignore system noise fields' }),
+      handler: wrap(async (argv, app) => {
+        const table = String(argv.table || '').trim();
+        const identifier = String(argv['sys-id'] || '').trim();
+        if (!table || !identifier) throw errUsage('diff record requires --table and --sys-id');
+        if (argv['profile-a'] === argv['profile-b']) throw errUsage('Profile A and profile B must be different');
+        const targetA = profileTarget(app, argv['profile-a'], 'profile-a');
+        const targetB = profileTarget(app, argv['profile-b'], 'profile-b');
+        const [sideA, sideB] = await Promise.all([
+          fetchRecord(app, targetA, table, identifier),
+          fetchRecord(app, targetB, table, identifier),
+        ]);
+        const ignored = ignoredFields(argv);
+        let status = 'error';
+        let differences = [];
+        if (sideA.status === 'found' && sideB.status === 'found') {
+          differences = compareRecords(sideA.record, sideB.record, ignored);
+          status = differences.length ? 'different' : 'equal';
+        } else if (sideA.status === 'missing' && sideB.status === 'missing') {
+          status = 'both_missing';
+        } else if (sideA.status === 'missing' || sideB.status === 'missing') {
+          status = 'missing';
+        } else if (sideA.status === 'forbidden' || sideB.status === 'forbidden') {
+          status = 'forbidden';
+        } else if (sideA.status === 'auth_error' || sideB.status === 'auth_error') {
+          status = 'auth_error';
+        }
+        const data = {
+          table,
+          identifiers: { a: identifier, b: identifier },
+          profiles: {
+            a: { name: targetA.name, instance: targetA.instance },
+            b: { name: targetB.name, instance: targetB.instance },
+          },
+          existence: { a: sideA.status, b: sideB.status },
+          errors: { a: sideA.error || null, b: sideB.error || null },
+          ignored_fields: ignored,
+          status,
+          differences,
+          _formatted: formatRecordDiff({
+            table,
+            identifiers: { a: identifier },
+            profiles: dataProfiles(targetA, targetB),
+            existence: { a: sideA.status, b: sideB.status },
+            ignored_fields: ignored,
+            status,
+            differences,
+          }),
+        };
+        app.ok(data, { summary: `Record diff ${status}: ${table} ${identifier}` });
+      }),
+    }),
+    handler: wrap(async (_argv, app) => {
+      app.ok({ command: 'diff', subcommands: ['record'] }, { summary: 'Use `jsn diff record --help` for details.' });
+    }),
+  };
+}
+
+function dataProfiles(targetA, targetB) {
+  return {
+    a: { name: targetA.name, instance: targetA.instance },
+    b: { name: targetB.name, instance: targetB.instance },
+  };
+}

package/src/commands/docs/docs.js

@@ -15,6 +15,7 @@ import { searchDocs, getDocByIdOrPath } from './search.js';
 import { serveDocs } from './serve.js';
 import { syncCommunity, listCommunityDocs } from './community.js';
 import { declareCapabilities } from '../../capabilities.js';
+import { formatCommandList } from '../../helpers.js';
 
 declareCapabilities('docs', { noInstance: true, skipDailyChecks: true });
 
@@ -256,21 +257,22 @@ export function docsCmd(wrap) {
             .demandCommand(1, 'Specify an action: sync or list'),
         });
     },
-    handler: () => {
-      process.stdout.write('jsn docs — ServiceNow documentation search\n\n');
-      process.stdout.write('Available subcommands:\n');
-      process.stdout.write('  sync      Download docs and build a searchable index (handles updates too)\n');
-      process.stdout.write('  status    Show whether docs are downloaded, indexed, embedded, or served\n');
-      process.stdout.write('  search    Full-text + semantic search across the local docs index\n');
-      process.stdout.write('  show      Display a full documentation page by id or path\n');
-      process.stdout.write('  serve     Start a local web UI for browsing and searching docs\n');
-      process.stdout.write('  community Sync ServiceNow Community articles (hubs + linked posts) into the index\n');
-      process.stdout.write('\n');
-      process.stdout.write('Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.\n');
-      process.stdout.write('\n');
-      const dbPath = getDocsDbPath();
-      process.stdout.write(`Docs DB: ${dbPath} (run "jsn docs status" for details, or query directly with sqlite3)\n`);
-      process.stdout.write('\nRun "jsn docs <command> --help" for details.\n');
-    },
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'jsn docs — ServiceNow documentation search (sync, status, search, show, serve).';
+      app.ok({
+        command: 'docs',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: [
+            'Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.',
+            `Docs DB: ${getDocsDbPath()} (run "jsn docs status" for details, or query directly with sqlite3)`,
+            'Run "jsn docs <command> --help" for details.',
+          ].join('\n'),
+        }),
+      }, { summary });
+    }),
   };
 }

package/src/commands/flows.js

@@ -1,9 +1,30 @@
-import { formatRecordForDisplay, getStringField, interactiveList } from '../helpers.js';
+import fs from 'node:fs';
+import { formatRecordForDisplay, formatCommandList, getStringField, interactiveList } from '../helpers.js';
 import { discoverFlowContextFields, normalizeFlowContext, summarizeFlowContexts, formatFlowContextSummary, aggregateFlowContextMappings, mergeFlowContextStats, buildFlowContextQuery } from '../flow-context.js';
 import { declareCapabilities } from '../capabilities.js';
 import { inspectFlow } from '../flow-inspection.js';
-import { publishFlows, publishDoctor, flowStatus } from '../flow-publish.js';
+import { publishFlows, publishFlowLifecycle, publishDoctor, flowStatus } from '../flow-publish.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
+import { createFlowFromManifest, updateFlowFromManifest, readCurrentUpdateSet } from '../flow-create.js';
+import { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES } from '../flow-triggers.js';
+import { testFlow } from '../flow-test.js';
+import { errUsage } from '../errors.js';
+import { cancelled, pickDesignerRecord, guidedFlowCreate, guidedFlowEdit, guidedFlowTestRecord, hasDefinitionData, confirmDesignerMutation } from '../flow-designer-interactive.js';
+
+const pickFlow = (argv, app, query = '') => pickDesignerRecord(argv, app, argv.action ? 'sys_hub_action_type_definition' : 'sys_hub_flow', argv.action ? 'action' : 'flow', query);
+
+const FLOW_COMMANDS = [
+  { name: 'list', description: 'List flows' },
+  { name: 'executions', description: 'Show flow executions from sys_flow_context' },
+  { name: 'show [identifier]', description: 'Show a flow: structure, inputs, steps and conditions' },
+  { name: 'status [identifier]', description: 'Check whether a flow is actually able to run' },
+  { name: 'publish [identifier]', description: 'Publish (activate) a flow, or a custom action with --action' },
+  { name: 'test [identifier]', description: 'Execute a record-triggered flow against one record' },
+  { name: 'create', description: 'Create a draft flow: guided in a terminal, JSON manifest in scripts' },
+  { name: 'update [identifier]', description: 'Update a draft flow (alias: edit)' },
+  { name: 'doctor', description: 'Check whether this instance can publish flows at all' },
+  { name: 'delete [identifier]', description: 'Delete a flow (not implemented: use the Flow Designer UI)' },
+];
 
 function flowInspectionAdapter(app) {
   return {
@@ -12,7 +33,19 @@ function flowInspectionAdapter(app) {
   };
 }
 
-declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'delete', 'publish'] });
+// The picker is driven by the instance's own trigger definitions, but this CLI
+// can only create the families it has verified. State both plainly so a created
+// flow never surprises the operator with a trigger that was not really set.
+function triggerGuidance(trigger) {
+  return {
+    supported_families: [...SUPPORTED_TRIGGER_TYPES].sort(),
+    excluded_families: [...EXCLUDED_TRIGGER_TYPES.entries()].map(([type, reason]) => ({ type, reason })).sort((a, b) => a.type.localeCompare(b.type)),
+    created_trigger: trigger ? { id: trigger.id, type: trigger.type, name: trigger.name, triggerDefinitionId: trigger.triggerDefinitionId } : null,
+    note: 'The trigger picker lists only families this CLI can create and verify. Families the picker omits are reported in excluded_families.',
+  };
+}
+
+declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'edit', 'delete', 'publish', 'test'] });
 
 function renderChecks(checks) {
   return checks.map((c) => {
@@ -22,6 +55,8 @@ function renderChecks(checks) {
 }
 
 export function flowsCmd(wrap) {
+  const originalWrap = wrap;
+  wrap = handler => originalWrap((argv, app) => cancelled(() => handler(argv, app)));
   return {
     command: 'flows [subcommand]',
     aliases: ['flow'],
@@ -140,7 +175,7 @@ export function flowsCmd(wrap) {
           }),
         })
         .command({
-          command: 'show <identifier>',
+          command: 'show [identifier]',
           aliases: ['get'],
           describe: 'Show flow details by name or sys_id',
           builder: (y) => y
@@ -150,9 +185,11 @@ export function flowsCmd(wrap) {
               describe: 'Expand nested subflows to this depth (1 = subflow names only, 2 = one level, 3+ = deeper)',
             }),
           handler: wrap(async (argv, app) => {
+            const identifier = await pickFlow(argv, app);
+            if (identifier === undefined) return;
             const inspection = await inspectFlow({
               adapter: flowInspectionAdapter(app),
-              identifier: argv.identifier,
+              identifier,
               instanceURL: app.getEffectiveInstance(),
               depth: argv.depth,
             });
@@ -165,23 +202,32 @@ export function flowsCmd(wrap) {
           }),
         })
         .command({
-          command: 'publish <identifier>',
+          command: 'publish [identifier]',
           aliases: ['activate'],
           describe: 'Publish (activate) a flow so it can actually run',
           builder: (y) => y
-            .option('action', { type: 'boolean', default: false, describe: 'Treat the identifier as a custom action rather than a flow' }),
+            .option('action', { type: 'boolean', default: false, describe: 'Treat the identifier as a custom action rather than a flow' })
+            .option('force', { type: 'boolean', default: false, describe: 'Confirm publication and activation' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
+            const identifier = await pickFlow(argv, app);
+            if (identifier === undefined) return;
             const sysID = unwrapSysId(await resolveRecord(app.sdk, {
                 table: argv.action ? 'sys_hub_action_type_definition' : 'sys_hub_flow',
-                identifier: argv.identifier,
+                identifier,
                 matchField: 'name',
                 resource: argv.action ? 'Custom action' : 'Flow',
               }));
 
-            const result = argv.action
-              ? await publishFlows(app.sdk, [], [sysID])
-              : await publishFlows(app.sdk, [sysID], []);
+            await confirmDesignerMutation(argv, app, `Publish and activate ${argv.action ? 'action' : 'flow'} ${sysID}?`);
+            if (!argv.action) {
+              const lifecycle = await publishFlowLifecycle(app.sdk, app.getEffectiveInstance(), sysID);
+              return app.ok(lifecycle, {
+                summary: `Published ${sysID}; active=${lifecycle.active}; version=${lifecycle.version?.sys_id ?? lifecycle.version?.id ?? 'read back'}`,
+                breadcrumbs: [{ action: 'status', cmd: `jsn flows status ${sysID}`, description: 'Verify the flow will run' }],
+              });
+            }
+            const result = await publishFlows(app.sdk, [], [sysID]);
 
             const { summary, results, via } = result;
             const lines = results.map(r => `  ${r.status === 'success' ? '✅' : '❌'} ${r.flow_name ?? r.sys_id}: ${r.message ?? r.status}${r.errorMessage ? ` — ${r.errorMessage}` : ''}`);
@@ -193,12 +239,14 @@ export function flowsCmd(wrap) {
           }),
         })
         .command({
-          command: 'status <identifier>',
+          command: 'status [identifier]',
           describe: 'Check whether a flow is actually able to run',
           handler: wrap(async (argv, app) => {
             app.requireInstance();
+            const identifier = await pickFlow(argv, app);
+            if (identifier === undefined) return;
             const sysID = unwrapSysId(await resolveRecord(app.sdk, {
-              table: 'sys_hub_flow', identifier: argv.identifier, matchField: 'name', resource: 'Flow',
+              table: 'sys_hub_flow', identifier, matchField: 'name', resource: 'Flow',
             }));
             const status = await flowStatus(app.sdk, sysID);
 
@@ -208,6 +256,28 @@ export function flowsCmd(wrap) {
             });
           }),
         })
+        .command({
+          command: 'test [identifier]',
+          describe: 'Execute a record-triggered flow against one record (may cause side effects)',
+          builder: (y) => y
+            .option('record', { type: 'string', describe: 'Trigger record sys_id to test against' })
+            .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const identifier = await pickFlow(argv, app);
+            if (identifier === undefined) return;
+            argv = { ...argv, identifier };
+            const record = await guidedFlowTestRecord(argv, app);
+            if (record === undefined) return;
+            await confirmDesignerMutation(argv, app, `Execute flow test for ${identifier} against record ${record}; actions may cause side effects`);
+            const result = await testFlow(app.sdk, app.getEffectiveInstance(), identifier, record);
+            return app.ok(result, {
+              summary: result.status === 'completed'
+                ? `Flow test completed (${result.success ? 'success' : 'failed'})`
+                : 'Flow test accepted for execution',
+            });
+          }),
+        })
         .command({
           command: 'doctor',
           describe: 'Check whether this instance can publish flows at all',
@@ -224,52 +294,84 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          describe: 'Create a new flow (not yet implemented)',
+          describe: 'Create a draft flow: pick a trigger category then trigger in a terminal, or use a JSON manifest in scripts',
           builder: (y) => y
-            .option('data', { type: 'string', describe: 'JSON data for the flow' }),
-          handler: wrap(async (_argv, _app) => {
-            throw new Error('Flow creation requires the Flow Designer GraphQL API - not yet implemented.\n'
-              + 'Use the ServiceNow web UI to create flows, then use "jsn flows list" to view them.');
+            .option('data', { type: 'string', describe: 'Flow manifest as inline JSON' })
+            .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' })
+            .option('scope', { type: 'string', describe: 'Transaction scope sys_id or global for the guided picker' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const dataFile = argv.dataFile ?? argv['data-file'];
+            let manifest;
+            if (!hasDefinitionData(argv)) manifest = await guidedFlowCreate(argv, app);
+            else try {
+              const raw = dataFile ? fs.readFileSync(dataFile, 'utf8') : argv.data;
+              manifest = JSON.parse(raw.charCodeAt?.(0) === 0xFEFF ? raw.slice(1) : raw);
+            } catch (error) {
+              throw new Error(`Invalid flow manifest JSON: ${error.message}`, { cause: error });
+            }
+            const result = await createFlowFromManifest(app.sdk, app.getEffectiveInstance(), manifest, {
+              readUpdateSet: () => readCurrentUpdateSet(app.sdk),
+            });
+            app.ok({ ...result, trigger_guidance: triggerGuidance(result.trigger) }, {
+              summary: `Created draft flow "${result.flow.name}" (${result.flow.id}) with trigger ${result.trigger?.type ?? 'unknown'} (${result.trigger?.id ?? 'no trigger id'}) without activation`,
+              breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the draft flow' }],
+            });
           }),
         })
         .command({
-          command: 'update <identifier>',
-          describe: 'Update a flow (not yet implemented)',
+          command: 'update [identifier]',
+          aliases: ['edit'],
+          describe: 'Safely update supported fields of an existing inactive Draft flow',
           builder: (y) => y
-            .option('data', { type: 'string', describe: 'JSON data to update' }),
-          handler: wrap(async (_argv, _app) => {
-            throw new Error('Flow updates require the Flow Designer GraphQL API - not yet implemented.\n'
-              + 'Use the ServiceNow web UI to update flows, then use "jsn flows list" to view them.');
+            .option('data', { type: 'string', describe: 'Update manifest as inline JSON' })
+            .option('data-file', { type: 'string', describe: 'Read the update manifest from a JSON file' })
+            .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const dataFile = argv.dataFile ?? argv['data-file'];
+            const identifier = await pickFlow(argv, app, !hasDefinitionData(argv) ? 'active=false^status=draft' : '');
+            if (identifier === undefined) return;
+            argv = { ...argv, identifier };
+            let manifest;
+            if (!hasDefinitionData(argv)) manifest = await guidedFlowEdit(argv, app);
+            else try {
+              const raw = dataFile ? fs.readFileSync(dataFile, 'utf8') : argv.data;
+              manifest = JSON.parse(raw.charCodeAt?.(0) === 0xFEFF ? raw.slice(1) : raw);
+            } catch (error) {
+              throw new Error(`Invalid flow update manifest JSON: ${error.message}`, { cause: error });
+            }
+            await confirmDesignerMutation(argv, app, `Update draft flow ${identifier}; unspecified components and inputs are preserved`);
+            const result = await updateFlowFromManifest(app.sdk, app.getEffectiveInstance(), argv.identifier, manifest, {
+              readUpdateSet: () => readCurrentUpdateSet(app.sdk),
+            });
+            return app.ok(result, {
+              summary: `Updated draft flow "${result.flow.name}" (${result.flow.id}) without activation`,
+              breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the updated draft flow' }],
+            });
           }),
         })
         .command({
-          command: 'delete <identifier>',
+          command: 'delete [identifier]',
           describe: 'Delete a flow (not yet implemented)',
-          handler: wrap(async (_argv, _app) => {
-            throw new Error('Flow deletion requires the Flow Designer GraphQL API - not yet implemented.\n'
+          handler: wrap(async (argv, app) => {
+            const identifier = await pickFlow(argv, app);
+            if (identifier === undefined) return;
+            throw errUsage('Flow deletion requires the Flow Designer GraphQL API - not yet implemented.\n'
               + 'Use the ServiceNow web UI to delete flows.');
           }),
         });
     },
-    handler: () => {
-      console.log('Manage Flow Designer flows from the sys_hub_flow table.');
-      console.log('');
-      console.log('Available subcommands:');
-      console.log('  list                  List flows');
-      console.log('  executions            Show flow executions from sys_flow_context');
-      console.log('  show <identifier>     Show flow details by name or sys_id');
-      console.log('  status <identifier>   Check whether a flow is actually able to run');
-      console.log('  publish <identifier>  Publish (activate) a flow');
-      console.log('  doctor                Check whether this instance can publish flows');
-      console.log('  create                Create a new flow (not yet implemented)');
-      console.log('  update <identifier>   Update a flow (not yet implemented)');
-      console.log('  delete <identifier>   Delete a flow (not yet implemented)');
-      console.log('');
-      console.log('Run "jsn flows <command> --help" for details.');
-      console.log('');
-      console.log('Note: Flow structure comes from the ProcessFlow API (the Flow');
-      console.log('Designer UI source), so V1, V2, and subflow definitions all');
-      console.log('render with full action inputs and conditions.');
-    },
+    handler: wrap(async (_argv, app) => {
+      const summary = 'Manage Flow Designer flows from the sys_hub_flow table. Flow structure comes from the ProcessFlow API, so V1, V2 and subflow definitions all render in full.';
+      app.ok({
+        commands: FLOW_COMMANDS.map(command => command.name),
+        _formatted: formatCommandList({
+          title: summary,
+          commands: FLOW_COMMANDS,
+          footer: 'Run "jsn flows <command> --help" for details. In a terminal you can omit the target and pick one; scripts use explicit identifiers and manifests.',
+        }),
+      }, { summary });
+    }),
   };
 }

package/src/commands/graphql.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import { declareCapabilities } from '../capabilities.js';
+
+// GraphQL documents may contain mutations. Gate the whole command so normal
+// instance/auth and read-only protections apply without attempting AST parsing.
+declareCapabilities('graphql', { mutationSubcommands: [''] });
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+export async function resolveGraphQLInput(argv) {
+  const sources = [
+    argv.document !== undefined,
+    argv.query !== undefined,
+    argv.queryFile !== undefined,
+    argv.stdin === true,
+  ].filter(Boolean).length;
+  if (sources !== 1) {
+    throw new Error('Provide exactly one GraphQL document via positional document, --query, --query-file, or --stdin');
+  }
+
+  let query;
+  if (argv.document !== undefined) query = argv.document;
+  else if (argv.query !== undefined) query = argv.query;
+  else if (argv.queryFile !== undefined) query = fs.readFileSync(argv.queryFile, 'utf-8');
+  else query = await readStdin();
+
+  query = String(query || '').trim();
+  if (!query) throw new Error('GraphQL document must not be empty');
+  return query;
+}
+
+export function parseGraphQLVariables(value) {
+  if (value === undefined) return {};
+  let variables;
+  try {
+    variables = JSON.parse(value);
+  } catch {
+    throw new Error('--variables must be valid JSON');
+  }
+  if (!variables || typeof variables !== 'object' || Array.isArray(variables)) {
+    throw new Error('--variables must be a JSON object');
+  }
+  return variables;
+}
+
+export function graphqlCmd(wrap) {
+  return {
+    command: 'graphql [document]',
+    describe: 'Execute a GraphQL document against ServiceNow Now GraphQL',
+    builder: (yargs) => yargs
+      .positional('document', {
+        describe: 'GraphQL document string',
+        type: 'string',
+      })
+      .option('query', {
+        type: 'string',
+        describe: 'GraphQL document string (alternative to positional)',
+      })
+      .option('query-file', {
+        type: 'string',
+        describe: 'Read the GraphQL document from a file',
+      })
+      .option('variables', {
+        type: 'string',
+        describe: 'GraphQL variables as a JSON object',
+      })
+      .option('stdin', {
+        type: 'boolean',
+        describe: 'Read the GraphQL document from stdin',
+      }),
+    handler: wrap(async (argv, app) => {
+      const query = await resolveGraphQLInput(argv);
+      const variables = parseGraphQLVariables(argv.variables);
+      const endpoint = `${app.getEffectiveInstance()}/api/now/graphql`;
+      const result = await app.sdk.request(endpoint, {
+        method: 'POST',
+        body: JSON.stringify({ query, variables }),
+      });
+      const errorCount = Array.isArray(result?.errors) ? result.errors.length : 0;
+      app.ok(result, {
+        summary: errorCount
+          ? `GraphQL returned ${errorCount} error(s)`
+          : 'GraphQL request succeeded',
+      });
+    }),
+  };
+}