@jacebenson/jsn 4.3.7 → 4.3.8-dev.46

package/src/commands/auth.js

@@ -1,5 +1,6 @@
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile, setProfile } from '../config.js';
-import { errUsage } from '../errors.js';
+import { errUsage, errUsageHint } from '../errors.js';
+import { canUsePicker } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
 
@@ -128,14 +129,16 @@ export function validateLoginSelectors(argv = {}, targetProfile = null) {
 }
 
 /**
- * Pick a profile by name — interactive search picker when ambiguous,
- * auto-selects when there's exactly one, throws when none configured.
+ * Pick a profile by name — interactive search picker when ambiguous and a
+ * human is available, auto-selects when there's exactly one, throws when
+ * none configured. A non-interactive caller (agent, pipe, --json/--get)
+ * never opens a picker; it falls back to the single/default profile.
  */
 export async function pickProfile(app, message) {
   const { search } = await import('@inquirer/prompts');
   const profileNames = Object.keys(app.config.profiles || {});
   if (profileNames.length === 0) throw errUsage('No profiles configured. Run "jsn setup" first.');
-  if (profileNames.length === 1 || !app.isInteractive()) return profileNames[0];
+  if (profileNames.length === 1 || !canUsePicker(app, {})) return profileNames[0];
   const choices = profileNames.map(name => ({
     name: `${name} — ${app.config.profiles[name].instance_url}`,
     value: name,
@@ -281,10 +284,9 @@ export async function loginWizard(app, argv = {}) {
   app.config.activeProfile = profileName;
   app.config.defaultProfile = profileName;
 
-  // Present all connection-level options during setup. Gated on interactivity
-  // so a piped/scripted call never blocks on prompts.
-  const { canPrompt } = await import('../helpers.js');
-  if (canPrompt()) {
+  // Present all connection-level options during setup. Gated on
+  // interactivity so a piped/scripted call never blocks on prompts.
+  if (canUsePicker(app, argv)) {
     // @inquirer/prompts owns stdin while these confirmations run. Close the
     // older readline interface before handing stdin to Inquirer. This matters
     // on Windows Git Bash: leaving both readers attached can make the later
@@ -604,7 +606,7 @@ export function authCmd(wrap) {
               instanceURL = normalizeInstanceURL(namedProfile.instance_url);
             } else if (argv.instance) {
               instanceURL = resolveInstanceArg(argv.instance, app.config);
-            } else if (app.isInteractive()) {
+            } else if (canUsePicker(app, argv)) {
               // gh-faithful: interactive terminals always get a picker —
               // existing profiles plus "＋ Add a new instance". Zero profiles
               // goes straight to the setup wizard.
@@ -987,7 +989,9 @@ Examples:
               if (profileNames.length === 0) {
                 throw errUsage('No profiles configured. Run "jsn auth login" first.');
               }
-              if (profileNames.length > 1 && app.isInteractive()) {
+              if (profileNames.length === 1) {
+                name = profileNames[0];
+              } else if (canUsePicker(app, argv)) {
                 const { search } = await import('@inquirer/prompts');
                 const choices = profileNames.map(profileName => ({
                   name: `${profileName} — ${app.config.profiles[profileName].instance_url}`,
@@ -1002,7 +1006,13 @@ Examples:
                 });
                 name = selected;
               } else {
-                name = profileNames[0];
+                // Never silently switch the active profile for a
+                // non-interactive caller: picking one for them is a
+                // config write they did not ask for.
+                throw errUsageHint(
+                  `Which profile? ${profileNames.length} profiles are configured: ${profileNames.join(', ')}`,
+                  'Pass the profile name: jsn auth switch <name>'
+                );
               }
             }
             await setActiveProfile(app.config, name);

package/src/commands/cmdb.js

@@ -8,6 +8,7 @@
 import {
   assertSafeExactMatch,
   buildQuerySuffix,
+  formatCommandList,
   formatRecordForDisplay,
   getStringField,
   interactiveList,
@@ -351,6 +352,23 @@ export function cmdbCmd(wrap) {
   return {
     command: 'cmdb [subcommand]',
     describe: 'Query the Configuration Management Database (CMDB) — CIs and relationship traversal (read-only)',
+    // Parent discovery. Without a handler `jsn cmdb` exited 0 having printed
+    // nothing: a script reads that as success and a human as a hang. The child
+    // list comes from the registry (argv.subcommands), so it cannot drift from
+    // what is registered; the styled view is a side channel that JSON ignores.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Query the Configuration Management Database (CMDB): CI lookup and relationship traversal. Read-only.';
+      app.ok({
+        command: 'cmdb',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn cmdb <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (yargs) => {
       return yargs
         .command({

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 });
+    }),
   };
 }