@jacebenson/jsn 4.3.8-dev.53 → 4.3.8-dev.55

package/package.json

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

package/src/commands/actions.js

@@ -12,6 +12,7 @@ const ACTION_COMMANDS = [
   { 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: 'action-type-schema', description: 'Read provider metadata for an exact action type ID and 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' },
@@ -29,6 +30,53 @@ async function actionID(argv, app) {
   return unwrapSysId(await resolveRecord(app.sdk, { table: ACTION_TABLE, identifier: argv.identifier, matchField: 'name', resource: 'action' }));
 }
 
+const refID = value => typeof value === 'string' ? value : value?.value ?? value?.sys_id ?? value?.sysId ?? value?.id;
+const asBoolean = value => value === true || value === 1 || (typeof value === 'string' && value.toLowerCase() === 'true');
+const EXAMPLE_TYPES = new Set(['approval_rules', 'conditions', 'schedule_date_time']);
+function collectActionExamples(node, snapshotId, allowedInputs, examples, flowName) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const item of node) collectActionExamples(item, snapshotId, allowedInputs, examples, flowName); return; }
+  const typeId = refID(node.actionTypeSysId || node.action_type_sys_id || node.actionType || node.action_type);
+  if (typeId === snapshotId && Array.isArray(node.inputs)) {
+    const values = Object.fromEntries(node.inputs.filter(input => input?.name && allowedInputs.has(input.name) && input.value !== undefined && input.value !== null)
+      .map(input => [input.name, refID(input.value) ?? input.value]));
+    if (Object.keys(values).length) examples.push({ flow: flowName, inputs: values });
+  }
+  for (const [key, value] of Object.entries(node)) if (key !== 'inputs') collectActionExamples(value, snapshotId, allowedInputs, examples, flowName);
+}
+async function findActionExamples(sdk, definition, inputDefinitions) {
+  const snapshotId = refID(definition.latest_snapshot);
+  if (!/^[a-f0-9]{32}$/i.test(snapshotId || '')) return { examples: [], status: 'unavailable' };
+  const allowedInputs = new Set(inputDefinitions.filter(input => EXAMPLE_TYPES.has(input.type)
+    && !/(password|secret|token|credential|authorization|cookie|api[_-]?key)/i.test(input.name)).map(input => input.name));
+  if (!allowedInputs.size) return { examples: [], status: 'not_applicable' };
+  const query = new URLSearchParams({
+    sysparm_query: `action_type=${snapshotId}^ORDERBYsys_id`,
+    sysparm_fields: 'sys_id,flow,action_type',
+    sysparm_limit: '20',
+    sysparm_display_value: 'false',
+  });
+  const rows = await sdk.listStrict('sys_hub_action_instance', query);
+  if (!rows.length) return { examples: [], status: 'none' };
+  const flowIds = [...new Set(rows.map(row => refID(row.flow)).filter(value => /^[a-f0-9]{32}$/i.test(value || '')))];
+  if (!flowIds.length) return { examples: [], status: 'unavailable' };
+  const examples = [];
+  let unreadable = false;
+  for (const flowId of flowIds.slice(0, 10)) {
+    try {
+      const result = await sdk.inspectFlow(flowId);
+      const payloadActions = result?.payload?.actionInstances;
+      if (!Array.isArray(payloadActions) || !payloadActions.some(item => item && typeof item === 'object' && !Array.isArray(item))) {
+        unreadable = true;
+        continue;
+      }
+      collectActionExamples(result.payload, snapshotId, allowedInputs, examples, result?.flow?.name || flowId);
+    } catch { unreadable = true; }
+    if (examples.length >= 3) break;
+  }
+  return { examples: examples.slice(0, 3), status: examples.length ? 'found' : unreadable ? 'unavailable' : 'none' };
+}
+
 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, {
@@ -56,7 +104,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. --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":[]}]}`,
+        command: 'create', describe: 'Create a Process Flow action. Use `jsn actions step-types --scope <sys_id>` for live provider schemas. The required definition structure is code-owned; step-specific fields are provider-defined.',
         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;
@@ -77,12 +125,13 @@ export const actionsCmd = wrap => {
           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,
+            mandatory: asBoolean(input.mandatory ?? input.required ?? input.parameter?.mandatory ?? input.parameter?.required),
             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.' },
+          const exampleResult = await findActionExamples(app.sdk, definition, inputs);
+          app.ok({ action: { id, name: definition.name, scope }, inputs, examples: exampleResult.examples,
+            examples_status: exampleResult.status },
           { summary: `Input help for action ${definition.name || id}` });
         }),
       })
@@ -137,13 +186,30 @@ export const actionsCmd = wrap => {
         }),
       })
       .command({
-        command: 'step-types', describe: 'Read step schema templates for a target scope',
+        command: 'step-types', describe: 'Read full live step schemas for a target scope',
         builder: yy => yy.option('scope', { type: 'string', describe: 'Exact transaction scope sys_id, or global' }),
         handler: run(async (argv, app) => {
           const scope = await designerScope(argv, app);
           app.ok(await app.sdk.getProcessFlowStepTypes(scope), { summary: 'Process Flow step schemas' });
         }),
       })
+      .command({
+        command: 'action-type-schema', describe: 'Read live provider input/output metadata for an exact action type ID and scope',
+        builder: yy => yy.option('id', { type: 'string', demandOption: true, describe: 'Exact 32-character action type sys_id' }).option('scope', { type: 'string', demandOption: true, describe: 'Exact transaction scope sys_id, or global' }),
+        handler: run(async (argv, app) => {
+          if (!/^[a-f\d]{32}$/i.test(argv.id)) throw errUsage('--id must be an exact 32-character action type sys_id');
+          if (!/^(?:[a-fA-F0-9]{32}|global)$/.test(argv.scope)) throw errUsage('--scope must be an exact scope sys_id or global');
+          app.requireInstance();
+          const url = `${app.sdk.baseURL}/api/now/processflow/action/action_types/${encodeURIComponent(argv.id)}?${new URLSearchParams({ sysparm_transaction_scope: argv.scope })}`;
+          const response = await app.sdk.request(url, { method: 'GET' });
+          const result = response?.result;
+          if (response?.error || result?.error || (result?.errorCode !== undefined && result.errorCode !== 0 && result.errorCode !== '0')) {
+            throw new Error(result?.errorMessage || response?.error?.message || 'Provider rejected the action type schema request');
+          }
+          if (!result || typeof result !== 'object') throw new Error('Provider returned no action type metadata');
+          app.ok(result, { summary: `Provider action type schema ${argv.id}` });
+        }),
+      })
       .command({
         command: 'delete [identifier]', describe: 'Delete action parent explicitly',
         builder: yy => scopeOption(yy).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),

package/src/commands/flows.js

@@ -6,7 +6,7 @@ import { inspectFlow } from '../flow-inspection.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 { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES, readTriggerCatalog, readTriggerInputDefinitions } 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';
@@ -63,6 +63,25 @@ export function flowsCmd(wrap) {
     describe: 'Manage Flow Designer flows',
     builder: (yargs) => {
       return yargs
+        .command({
+          command: 'schemas',
+          describe: 'Read live trigger catalog and declared inputs; supported marks verified CLI creation families',
+          handler: wrap(async (_argv, app) => {
+            app.requireInstance();
+            const catalog = await readTriggerCatalog(app.sdk);
+            for (const category of catalog.categories) {
+              for (const trigger of category.triggers) {
+                if (trigger.supported) trigger.inputs = await readTriggerInputDefinitions(app.sdk, trigger.sysId);
+              }
+            }
+            for (const trigger of catalog.ungrouped) {
+              if (trigger.supported) trigger.inputs = await readTriggerInputDefinitions(app.sdk, trigger.sysId);
+            }
+            const data = { ...catalog, structural_contract: 'Manifest keys and persistence shape are code-owned; trigger definitions and input metadata are instance-derived.' };
+            data._formatted = [...catalog.categories.flatMap(c => c.triggers.map(t => `${c.name}: ${t.name} [${t.type}] ${t.supported ? 'supported' : 'not supported'}; inputs: ${(t.inputs || []).map(i => i.name + ':' + i.type).join(', ')}`)), ...catalog.ungrouped.map(t => `${t.name} [${t.type}] ungrouped${t.supported ? '; supported' : '; not supported'}; inputs: ${(t.inputs || []).map(i => i.name + ':' + i.type).join(', ')}`)].join('\n');
+            app.ok(data, { summary: 'Live Flow trigger schemas' });
+          }),
+        })
         .command({
           command: 'list',
           aliases: ['ls'],
@@ -294,7 +313,7 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          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"}}]}`,
+          describe: 'Create a draft flow from a JSON manifest or guided prompts. Use `jsn flows schemas` for instance-derived trigger and input schemas, and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for provider action inputs. Manifest structure remains code-owned.',
           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 +341,7 @@ export function flowsCmd(wrap) {
         .command({
           command: 'update [identifier]',
           aliases: ['edit'],
-          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"}}]}`,
+          describe: 'Safely update an inactive Draft flow from a partial JSON manifest. Use `jsn flows schemas` for live trigger inputs and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for provider action inputs. Manifest structure remains code-owned; omitted values are preserved.',
           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' })