@jacebenson/jsn 4.3.7-dev.33 → 4.3.7-dev.35

package/README.md

@@ -31,6 +31,19 @@ npm install -g @jacebenson/jsn
 
 **Note:** git installs build `better-sqlite3` (docs search) from source, so the machine needs build tools (Python, make, a C++ compiler).
 
+## Direct MID installation
+
+```sh
+jsn midservers add --install-method direct --name worker1
+```
+
+Official x86-64 ZIPs for Linux and Windows, selected from the instance's
+`mid.version`. Credentials are prompted and validated before installation.
+Linux supports a user-owned background runtime. Windows currently prepares
+private files and offers a foreground console, not native service registration.
+See [direct MID installation](docs/mid-direct-install.md) for security boundaries,
+lifecycle commands and the untested Windows host phases. Docker remains available.
+
 ## Quick Start
 
 ```bash
@@ -97,8 +110,27 @@ jsn logs follow --level error --tail 10
 ### Flow Designer actions
 
 `actions` and `action` are the same command. `list`, `show`, and explicit
-`delete` remain available. Create and edit use full Process Flow JSON, not
-ordinary table-field updates.
+`delete` remain available. In a human terminal, omit the target to open a
+searchable picker. Create and edit guide you through provider schemas and save
+full Process Flow definitions, not ordinary table-field updates.
+
+```bash
+jsn actions create                 # Guided scope, name, schemas, inputs and script
+jsn actions edit                   # Pick an action, edit its saved definition
+jsn actions definition             # Pick and inspect a complete definition
+jsn actions test --wait            # Pick an action, supply saved-schema inputs, confirm
+jsn actions step-types             # Pick the exact transaction scope
+```
+
+Script inputs offer a file path or your `$VISUAL`/`$EDITOR`. New script steps can
+declare outputs and map them to action outputs. Variable declarations reuse
+provider schema templates and receive fresh UI identities. Unknown nested
+schema fields are retained. Unsupported input types stop with instructions to
+use `--data-file`; JSN does not silently omit them or invent schema defaults.
+Creation waits for an explicit final confirmation before allocating a parent.
+It saves a draft only and never publishes or runs it automatically.
+
+For automation, keep using explicit identifiers and full JSON:
 
 ```bash
 jsn actions step-types --scope <scope_sys_id> --get data > step-types.json
@@ -177,9 +209,43 @@ These internal endpoints and runtime-table permissions can vary by instance.
 
 ### Flow execution fields
 
+### Flow Designer terminal workflows
+
+```bash
+jsn flows create         # Guided record trigger and published action inputs
+jsn flows edit           # Pick an inactive Draft, edit condition or existing inputs
+jsn flows show           # Pick a flow to inspect
+jsn flows status         # Pick a flow to diagnose
+jsn flows test           # Pick flow and a record from its actual trigger table, confirm
+jsn flows publish        # Pick a flow, explicitly confirm activation
+# Automation must explicitly confirm publication too:
+jsn flows publish <flow_sys_id> --force --json
+```
+
+Wizards and omitted-target pickers require both a prompt-capable terminal and
+`auto` output. `--json`, explicit formats, `--get`, `--data`, `--data-file`,
+`--output-map`, pipes, `CI`, `NONINTERACTIVE` and `JSN_NO_PROMPTS=1` never open a
+wizard. In those modes provide identifiers and required scope/record/data
+explicitly. Tests, publish and deletion require `--force` or the profile's
+existing explicit skip-confirmations setting when prompting is unavailable.
+Read-only profiles still block mutations before authentication or prompting.
+Press Escape in record pickers or Ctrl+C in any wizard to cancel. Refusing a
+final confirmation leaves the instance untouched.
+
+Existing action/flow scopes come from saved raw identifiers. New scopes offer
+the active application preference if available, then a searchable scope picker.
+No scope name is guessed. Input pills are passed through unchanged.
+
+Flow edits are limited to the existing manifest contract. They do not rename
+flows, add/remove steps, implement Flow Logic, subflows, variables or error
+handling. Flow deletion remains unsupported. Action deletion retains its
+existing explicit parent-record cleanup and absence readback, not a new native
+builder deletion lifecycle. See [command coverage and local proof](docs/flow-designer-interactive.md).
+
 ### Flow creation manifest
 
-`jsn flows create` accepts `--data-file` or inline `--data`. The first slice
+`jsn flows create` accepts `--data-file` or inline `--data`, or guides human
+terminal users without those options. The supported slice
 supports one `record_create_or_update` trigger and published Action types whose
 input schemas are available from the instance. JSN resolves action metadata,
 defaults, and typed inputs from ServiceNow; callers do not provide GraphQL or

package/package.json

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

package/src/commands/_generic.js

@@ -181,11 +181,12 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         }),
       })
       .command({
-        command: 'show <identifier>',
+        command: opts.resolveIdentifier ? 'show [identifier]' : 'show <identifier>',
         aliases: ['get'],
         describe: `Show ${vowelArticle(singular)} ${singular} by name or sys_id`,
         handler: wrap(async (argv, app) => {
-          const id = argv.identifier;
+          const id = opts.resolveIdentifier ? await opts.resolveIdentifier(argv, app) : argv.identifier;
+          if (id === undefined) return;
           // Only restrict sysparm_fields if showFields is explicitly set.
           // Go version fetches all fields for show unless explicitly restricted.
           const fields = (showFields && showFields.length > 0)

package/src/commands/actions.js

@@ -1,15 +1,19 @@
 import { buildDevCmd } from './_generic.js';
-import { parseDataArg, confirmDelete } from '../helpers.js';
+import { parseDataArg } from '../helpers.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
-import { ACTION_TABLE, actionScope, validateScope } from '../processflow-actions.js';
+import { ACTION_TABLE, actionScope } from '../processflow-actions.js';
 import { errUsage } from '../errors.js';
+import { cancelled, pickDesignerRecord, designerScope, guidedActionCreate, guidedActionEdit, guidedActionTestInputs, interactiveDesigner, hasDefinitionData, confirmDesignerMutation } from '../flow-designer-interactive.js';
 
 const scopeOption = y => y.option('scope', { type: 'string', describe: 'Exact transaction scope sys_id; inferred from existing action when omitted' });
 const dataOptions = y => y
   .option('data-file', { type: 'string', describe: 'Full action definition JSON file, not table fields' })
   .option('data', { type: 'string', describe: 'Full action definition as JSON' });
 async function actionID(argv, app) {
+  const identifier = await pickDesignerRecord(argv, app, ACTION_TABLE, 'action');
+  if (identifier === undefined) return undefined;
+  argv = { ...argv, identifier };
   return unwrapSysId(await resolveRecord(app.sdk, { table: ACTION_TABLE, identifier: argv.identifier, matchField: 'name', resource: 'action' }));
 }
 
@@ -17,6 +21,7 @@ export const actionsCmd = wrap => {
   // Reuse the existing list/show picker and output contract only.
   const base = buildDevCmd('actions', ACTION_TABLE, ['action'], ['name', 'active', 'sys_scope', 'sys_updated_on'], wrap, {
     singular: 'action', readOnly: true,
+    resolveIdentifier: (argv, app) => cancelled(() => pickDesignerRecord(argv, app, ACTION_TABLE, 'action')),
     showBreadcrumbs: (_record, id) => [
       { action: 'definition', cmd: `jsn actions definition ${id}`, description: 'Read complete executable definition' },
       { action: 'list', cmd: 'jsn actions list', description: 'Back to actions' },
@@ -26,7 +31,7 @@ export const actionsCmd = wrap => {
   // Retain the common wrap and output controller; domain failures get a
   // structured error envelope and nonzero exit, never a success-shaped dispatch.
   const run = handler => wrap(async (argv, app) => {
-    try { await handler(argv, app); }
+    try { await cancelled(() => handler(argv, app)); }
     catch (error) {
       if (!error.code?.startsWith('action_')) throw error;
       if (error.details) error.hint = JSON.stringify(error.details);
@@ -40,37 +45,43 @@ export const actionsCmd = wrap => {
     builder: y => base.builder(y)
       .command({
         command: 'create', describe: 'Create parent and executable Process Flow action; verify persistence',
-        builder: yy => dataOptions(yy).option('scope', { type: 'string', demandOption: true, describe: 'Exact target scope sys_id, or global' }),
+        builder: yy => dataOptions(yy).option('scope', { type: 'string', describe: 'Exact target scope sys_id, or global' }),
         handler: run(async (argv, app) => {
-          const definition = parseDataArg(argv);
-          const result = await app.sdk.createProcessFlowAction(argv.scope, definition);
+          const guided = !hasDefinitionData(argv) ? await guidedActionCreate(argv, app) : undefined;
+          const definition = guided?.definition ?? parseDataArg(argv);
+          const scope = guided?.scope ?? await designerScope(argv, app);
+          const result = await app.sdk.createProcessFlowAction(scope, definition);
           app.ok(result, { summary: `Created and verified action ${result.sys_id}` });
         }),
       })
       .command({
-        command: 'definition <identifier>', describe: 'Read full JSON definition including executable step_instances',
+        command: 'definition [identifier]', describe: 'Read full JSON definition including executable step_instances',
         builder: scopeOption,
         handler: run(async (argv, app) => {
           const id = await actionID(argv, app);
+          if (id === undefined) return;
           const scope = await actionScope(app.sdk, id, argv.scope);
           app.ok(await app.sdk.getProcessFlowAction(id, scope), { summary: `Read action definition ${id}` });
         }),
       })
       .command({
-        command: 'update <identifier>', aliases: ['edit'], describe: 'Save a full definition through Process Flow PUT and verify readback',
+        command: 'update [identifier]', aliases: ['edit'], describe: 'Save a full definition through Process Flow PUT and verify readback',
         builder: yy => dataOptions(scopeOption(yy)),
         handler: run(async (argv, app) => {
-          const definition = parseDataArg(argv);
+          if (!hasDefinitionData(argv) && !interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for the full action definition in noninteractive mode');
           const id = await actionID(argv, app);
+          if (id === undefined) return;
+          const definition = hasDefinitionData(argv) ? parseDataArg(argv)
+            : await guidedActionEdit(argv, app, await app.sdk.getProcessFlowAction(id, await actionScope(app.sdk, id, argv.scope)));
           const result = await app.sdk.updateProcessFlowAction(id, argv.scope, definition);
           app.ok(result, { summary: `Saved and verified action ${id}` });
         }),
       })
       .command({
-        command: 'test <identifier>', describe: 'Execute saved or supplied definition; optionally wait for actual outputs',
+        command: 'test [identifier]', describe: 'Execute saved or supplied definition; optionally wait for actual outputs',
         builder: yy => dataOptions(scopeOption(yy))
           .option('force', { type: 'boolean', default: false, describe: 'Confirm execution of action scripts, which may have side effects' })
-          .option('output-map', { type: 'string', default: '{}', describe: 'JSON action input names to values; sent as outputMap' })
+          .option('output-map', { type: 'string', describe: 'JSON action input names to values; sent as outputMap' })
           .option('run-on-thread', { type: 'boolean', default: true, describe: 'Run test on a worker thread' })
           .option('tracing-enabled', { type: 'boolean', default: false, describe: 'Enable Flow Designer tracing' })
           .option('wait', { type: 'boolean', default: false, describe: 'Wait for COMPLETE context and actual runtime outputs' })
@@ -79,9 +90,14 @@ export const actionsCmd = wrap => {
           let outputMap;
           try { outputMap = JSON.parse(argv['output-map'] ?? '{}'); }
           catch { throw errUsage('--output-map must be valid JSON'); }
-          const definition = argv['data-file'] || argv.data ? parseDataArg(argv) : undefined;
+          let definition = hasDefinitionData(argv) ? parseDataArg(argv) : undefined;
           const id = await actionID(argv, app);
-          await confirmDelete(app, argv, `Execute action '${argv.identifier}' scripts, which may have side effects`);
+          if (id === undefined) return;
+          if (argv['output-map'] === undefined && interactiveDesigner(argv, app)) {
+            definition = await app.sdk.getProcessFlowAction(id, await actionScope(app.sdk, id, argv.scope));
+            outputMap = await guidedActionTestInputs(argv, app, definition);
+          }
+          await confirmDesignerMutation(argv, app, `Execute action '${id}' scripts, which may have side effects`);
           const result = await app.sdk.testProcessFlowAction(id, argv.scope, definition, outputMap, {
             wait: argv.wait, timeout: argv.timeout, runOnThread: argv['run-on-thread'], tracingEnabled: argv['tracing-enabled'],
           });
@@ -90,19 +106,20 @@ export const actionsCmd = wrap => {
       })
       .command({
         command: 'step-types', describe: 'Read step schema templates for a target scope',
-        builder: yy => yy.option('scope', { type: 'string', demandOption: true, describe: 'Exact transaction scope sys_id, or global' }),
+        builder: yy => yy.option('scope', { type: 'string', describe: 'Exact transaction scope sys_id, or global' }),
         handler: run(async (argv, app) => {
-          await validateScope(app.sdk, argv.scope);
-          app.ok(await app.sdk.getProcessFlowStepTypes(argv.scope), { summary: 'Process Flow step schemas' });
+          const scope = await designerScope(argv, app);
+          app.ok(await app.sdk.getProcessFlowStepTypes(scope), { summary: 'Process Flow step schemas' });
         }),
       })
       .command({
-        command: 'delete <identifier>', describe: 'Delete action parent explicitly',
+        command: 'delete [identifier]', describe: 'Delete action parent explicitly',
         builder: yy => scopeOption(yy).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
         handler: run(async (argv, app) => {
           const id = await actionID(argv, app);
+          if (id === undefined) return;
           await actionScope(app.sdk, id, argv.scope);
-          await confirmDelete(app, argv, `Delete action '${argv.identifier}'`);
+          await confirmDesignerMutation(argv, app, `Delete action '${id}'`);
           await app.sdk.delete(ACTION_TABLE, id);
           // Verify the exact target is absent. Do not interpret a 403 as deletion.
           const query = new URLSearchParams({ sysparm_query: `sys_id=${id}`, sysparm_limit: '1', sysparm_fields: 'sys_id', sysparm_display_value: 'false' });
@@ -115,7 +132,7 @@ export const actionsCmd = wrap => {
       }),
     handler: wrap(async (_argv, app) => {
       app.ok({ commands: ['list', 'show', 'definition', 'step-types', 'create', 'update', 'test', 'delete'] }, {
-        summary: 'Use jsn actions <command> --help. Create/update require full JSON definitions, not table fields.',
+        summary: 'Use jsn actions <command> --help. Create/update guide terminal users; automation uses full JSON definitions, not table fields.',
       });
     }),
   };

package/src/commands/flows.js

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { formatRecordForDisplay, getStringField, interactiveList, confirmDelete } from '../helpers.js';
+import { formatRecordForDisplay, 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';
@@ -7,6 +7,10 @@ import { publishFlows, publishFlowLifecycle, publishDoctor, flowStatus } from '.
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { createFlowFromManifest, updateFlowFromManifest, readCurrentUpdateSet } from '../flow-create.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);
 
 function flowInspectionAdapter(app) {
   return {
@@ -15,7 +19,7 @@ function flowInspectionAdapter(app) {
   };
 }
 
-declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'delete', 'publish', 'test'] });
+declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'edit', 'delete', 'publish', 'test'] });
 
 function renderChecks(checks) {
   return checks.map((c) => {
@@ -25,6 +29,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'],
@@ -143,7 +149,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
@@ -153,9 +159,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,
             });
@@ -168,20 +176,24 @@ 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',
               }));
 
+            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, {
@@ -201,12 +213,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);
 
@@ -217,15 +231,20 @@ export function flowsCmd(wrap) {
           }),
         })
         .command({
-          command: 'test <identifier>',
+          command: 'test [identifier]',
           describe: 'Execute a record-triggered flow against one record (may cause side effects)',
           builder: (y) => y
-            .option('record', { type: 'string', demandOption: true, describe: 'Trigger record sys_id to test against' })
+            .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();
-            await confirmDelete(app, argv, `Execute flow test for ${argv.identifier} against record ${argv.record}; actions may cause side effects`);
-            const result = await testFlow(app.sdk, app.getEffectiveInstance(), argv.identifier, argv.record);
+            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'})`
@@ -249,16 +268,16 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          describe: 'Create a draft flow from a schema-driven JSON manifest',
+          describe: 'Guide draft flow creation in a terminal, or use a schema-driven JSON manifest',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Flow manifest as inline JSON' })
             .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             const dataFile = argv.dataFile ?? argv['data-file'];
-            if (!dataFile && argv.data === undefined) throw new Error('Provide --data-file or --data for the flow manifest');
             let manifest;
-            try {
+            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) {
@@ -274,7 +293,8 @@ export function flowsCmd(wrap) {
           }),
         })
         .command({
-          command: 'update <identifier>',
+          command: 'update [identifier]',
+          aliases: ['edit'],
           describe: 'Safely update supported fields of an existing inactive Draft flow',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Update manifest as inline JSON' })
@@ -283,15 +303,18 @@ export function flowsCmd(wrap) {
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             const dataFile = argv.dataFile ?? argv['data-file'];
-            if (!dataFile && argv.data === undefined) throw new Error('Provide --data-file or --data for the flow update manifest');
+            const identifier = await pickFlow(argv, app, !hasDefinitionData(argv) ? 'active=false^status=draft' : '');
+            if (identifier === undefined) return;
+            argv = { ...argv, identifier };
             let manifest;
-            try {
+            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 confirmDelete(app, argv, `Update draft flow ${argv.identifier}; unspecified components and inputs are preserved`);
+            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),
             });
@@ -302,34 +325,20 @@ export function flowsCmd(wrap) {
           }),
         })
         .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('  test <identifier>    Execute a record-triggered flow against one record');
-      console.log('  doctor                Check whether this instance can publish flows');
-      console.log('  create                Create a draft flow from a JSON manifest');
-      console.log('  update <identifier>   Safely update supported fields of an existing Draft flow');
-      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) => {
+      app.ok({ commands: ['list', 'executions', 'show', 'status', 'publish', 'test', 'doctor', 'create', 'update', 'delete'] }, {
+        summary: 'Use jsn flows <command> --help. Human terminals can omit targets and guide create/edit; automation uses explicit identifiers and manifests.',
+      });
+    }),
   };
 }