@jacebenson/jsn 4.3.7-dev.37 → 4.3.7-dev.39

package/package.json

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

package/src/commands/actions.js

@@ -1,11 +1,22 @@
 import { buildDevCmd } from './_generic.js';
-import { parseDataArg } from '../helpers.js';
+import { formatCommandList, parseDataArg } from '../helpers.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.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 ACTION_COMMANDS = [
+  { name: 'list', description: 'List actions' },
+  { name: 'show [identifier]', description: 'Show an action by name or sys_id' },
+  { name: 'definition [identifier]', description: 'Read the full JSON definition including executable step_instances' },
+  { name: 'step-types', description: 'Read step schema templates for a target scope' },
+  { name: 'create', description: 'Create an action: guided in a terminal, full JSON definition in scripts' },
+  { name: 'update [identifier]', description: 'Save a full definition through Process Flow (alias: edit)' },
+  { name: 'test [identifier]', description: 'Execute an action and optionally wait for actual outputs' },
+  { name: 'delete [identifier]', description: 'Delete an action parent explicitly' },
+];
+
 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' })
@@ -131,9 +142,15 @@ 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 guide terminal users; automation uses full JSON definitions, not table fields.',
-      });
+      const summary = 'Manage Flow Designer actions from the sys_hub_action_type_definition table. Create and update guide terminal users; automation passes full JSON definitions, not table fields.';
+      app.ok({
+        commands: ACTION_COMMANDS.map(command => command.name),
+        _formatted: formatCommandList({
+          title: summary,
+          commands: ACTION_COMMANDS,
+          footer: 'Run "jsn actions <command> --help" for details. In a terminal you can omit the target and pick one.',
+        }),
+      }, { summary });
     }),
   };
 };

package/src/commands/flows.js

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { formatRecordForDisplay, getStringField, interactiveList } from '../helpers.js';
+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';
@@ -12,6 +12,19 @@ import { cancelled, pickDesignerRecord, guidedFlowCreate, guidedFlowEdit, guided
 
 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 {
     inspectFlow: app.sdk.inspectFlow.bind(app.sdk),
@@ -336,9 +349,15 @@ export function flowsCmd(wrap) {
         });
     },
     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.',
-      });
+      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/flow-create.js

@@ -230,14 +230,20 @@ export async function readActionDefinition(sdk, instance, actionTypeId, scope, {
   return { definition, schema };
 }
 
-function buildTypedInputs(action, schema) {
+export function buildTypedInputs(action, schema) {
   const supplied = action.inputs || {};
-  const allowed = new Set(schema.map(field => field.name));
+  const allowed = new Set(schema.map(field => field?.name).filter(Boolean));
   for (const key of Object.keys(supplied)) if (!allowed.has(key)) throw new Error(`Unsupported input "${key}" for action ${action.type}`);
   return schema.map(field => {
-    if (!field || typeof field !== 'object' || !field.id || !field.parameter || typeof field.parameter !== 'object') {
+    // The instance's own definition is the contract: identity is required,
+    // everything else (including an optional `parameter` block) is echoed back
+    // untouched. Demanding a key the provider omits breaks real actions.
+    if (!field || typeof field !== 'object' || !field.id || !field.name) {
       throw new Error(`Action ${action.type} returned an incomplete input schema; refusing to invent input metadata for "${field?.name || 'unknown'}"`);
     }
+    if (field.parameter !== undefined && (typeof field.parameter !== 'object' || field.parameter === null || Array.isArray(field.parameter))) {
+      throw new Error(`Action ${action.type} input "${field.name}" has a malformed parameter block; refusing to change it`);
+    }
     const suppliedValue = Object.prototype.hasOwnProperty.call(supplied, field.name) ? supplied[field.name] : field.default;
     if ((suppliedValue === undefined || suppliedValue === null) && (field.mandatory === true || field.required === true)) throw new Error(`Missing required input "${field.name}" for action ${action.type}`);
     const value = suppliedValue ?? null;

package/src/flow-designer-interactive.js

@@ -265,8 +265,8 @@ export async function guidedFlowCreate(argv, app) {
     const { schema } = await readActionDefinition(app.sdk, app.getEffectiveInstance(), id, manifest.scope, { requireTypes: true });
     const inputs = {};
     for (const field of schema) {
-      if (!field.id || !field.parameter || typeof field.parameter !== 'object' || Array.isArray(field.parameter)) {
-        throw errUsage(`Published action input ${field.name} lacks provider id/parameter metadata; no flow was allocated`);
+      if (!field.id || !field.name) {
+        throw errUsage(`Published action input ${field.name || 'unknown'} lacks the provider identity needed to bind a value; no flow was allocated`);
       }
       inputs[field.name] = await promptSchemaValue(app, field, field.default, 'Action input: ');
     }

package/src/helpers.js

@@ -32,6 +32,21 @@ export function canPrompt() {
   return isTTY(process.stdout) && isTTY(process.stdin);
 }
 
+/**
+ * Render a parent command's subcommand list for its default handler.
+ *
+ * Returned through the `_formatted` side channel so a terminal prints the list
+ * while `--json`/`--quiet` keep the structured envelope. A parent command that
+ * only sets a summary leaves terminal users with no way to discover children.
+ */
+export function formatCommandList({ title, commands, footer }) {
+  const width = Math.max(...commands.map(command => command.name.length));
+  const lines = [title, '', 'Available subcommands:'];
+  for (const command of commands) lines.push(`  ${command.name.padEnd(width)}  ${command.description}`);
+  if (footer) lines.push('', footer);
+  return `${lines.join('\n')}\n`;
+}
+
 /**
  * Confirm a destructive action before executing.
  *