@jacebenson/jsn 4.3.8-dev.50 → 4.3.8-dev.52

package/package.json

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

package/src/commands/actions.js

@@ -9,6 +9,7 @@ import { cancelled, pickDesignerRecord, designerScope, guidedActionCreate, guide
 const ACTION_COMMANDS = [
   { name: 'list', description: 'List actions' },
   { name: 'show [identifier]', description: 'Show an action by name or sys_id' },
+  { name: 'help [identifier]', description: 'Show action input requirements and live usage examples' },
   { 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' },
@@ -55,7 +56,7 @@ export const actionsCmd = wrap => {
     describe: 'Flow Designer actions: create, edit full definitions, and test with outputs',
     builder: y => base.builder(y)
       .command({
-        command: 'create', describe: 'Create parent and executable Process Flow action; verify persistence',
+        command: 'create', describe: `Create parent and executable Process Flow action; verify persistence. --data/--data-file requires a full definition with inputs, outputs, and steps arrays. Variables have name and type; each step requires cid, step_type, and inputs, outputs, extended_inputs, extended_outputs arrays. Use step_types for valid step_type schema. Example (structure only):\n{"name":"Example action","inputs":[{"name":"record_id","type":"string"}],"outputs":[],"steps":[{"cid":"step-1","step_type":"<stepTypeFromSchema>","inputs":[],"outputs":[],"extended_inputs":[],"extended_outputs":[]}]}`,
         builder: yy => dataOptions(yy).option('scope', { type: 'string', describe: 'Exact target scope sys_id, or global' }),
         handler: run(async (argv, app) => {
           const guided = !hasDefinitionData(argv) ? await guidedActionCreate(argv, app) : undefined;
@@ -65,6 +66,26 @@ export const actionsCmd = wrap => {
           app.ok(result, { summary: `Created and verified action ${result.sys_id}` });
         }),
       })
+      .command({
+        command: 'help [identifier]', describe: 'Show action input requirements and examples from flows on this instance',
+        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);
+          const definition = await app.sdk.getProcessFlowAction(id, scope);
+          const inputs = (definition.inputs || []).map(input => ({
+            name: input.name,
+            type: input.type || input.parameter?.type || input.parameter?.inputType || input.valueType || 'unknown',
+            mandatory: input.mandatory ?? input.required ?? input.parameter?.mandatory ?? input.parameter?.required ?? false,
+            default: input.defaultValue ?? input.default ?? input.parameter?.defaultValue ?? '',
+            description: input.description || input.label || input.parameter?.label || '',
+          }));
+          app.ok({ action: { id, name: definition.name, scope }, inputs, examples: [], examples_status: 'unverified',
+            examples_note: 'Live examples are not shown yet because this instance’s action-instance to snapshot relationship has not been verified.' },
+          { summary: `Input help for action ${definition.name || id}` });
+        }),
+      })
       .command({
         command: 'definition [identifier]', describe: 'Read full JSON definition including executable step_instances',
         builder: scopeOption,

package/src/commands/flows.js

@@ -294,7 +294,7 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          describe: 'Create a draft flow: pick a trigger category then trigger in a terminal, or use a JSON manifest in scripts',
+          describe: `Create a draft flow. JSON manifest fields: name (required), scope (required), optional description, trigger { type (required), optional table, condition, inputs }, actions (required array of { type, optional inputs }). Trigger type must be supported; trigger inputs and action inputs are objects. Flow Logic, subflows, variables, and errorHandling are unsupported. Example:\n{"name":"Approval flow","scope":"global","trigger":{"type":"record_create_or_update","table":"incident"},"actions":[{"type":"<actionTypeSysId>","inputs":{"message":"Created"}}]}`,
           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' })
@@ -322,7 +322,7 @@ export function flowsCmd(wrap) {
         .command({
           command: 'update [identifier]',
           aliases: ['edit'],
-          describe: 'Safely update supported fields of an existing inactive Draft flow',
+          describe: `Safely update an inactive Draft flow. JSON may contain scope, trigger { optional type: "record_create_or_update", table and/or condition }, and/or actions [{ order (positive integer), type, inputs (non-empty object of changed values) }]. Only existing trigger and action inputs are updated; omitted values are preserved. Example:\n{"trigger":{"table":"incident","condition":"active=true"},"actions":[{"order":1,"type":"<existingActionTypeSysId>","inputs":{"message":"Updated"}}]}`,
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Update manifest as inline JSON' })
             .option('data-file', { type: 'string', describe: 'Read the update manifest from a JSON file' })