@jacebenson/jsn 4.3.8-dev.54 → 4.3.8-dev.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.8-dev.54",
+  "version": "4.3.8-dev.56",
   "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' },
@@ -103,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;
@@ -185,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' })

package/src/commands/updatesets.js

@@ -560,25 +560,16 @@ export function updateSetsCmd(wrap) {
               throw errUsage(`Cannot set "${name}" as current — update set is ${stateRaw === 'ignore' ? 'ignored' : 'complete'}.\nView it instead: jsn updatesets show "${name}"`);
             }
             const userSysID = await requireCurrentUserSysId(app.sdk);
-            await setCurrentUpdateSet(app.sdk, userSysID, sysID);
-
-            // Like the platform update set picker: switching the set also
-            // switches the application scope into the set's scope. The
-            // application field is a sys_scope reference, so its raw value
-            // IS the scope sys_id the apps.current_app preference stores.
+            // Scope selection can reset the session's capture set. Select the
+            // scope first, then the requested set, and verify both picker writes.
+            const scopeSysId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
             let scopeNote = '';
-            try {
-              const scopeSysId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
-              if (scopeSysId) {
-                await setCurrentApplication(app.sdk, userSysID, scopeSysId);
-                const scopeName = updateSetApp?.display_value || updateSetApp;
-                scopeNote = ` — scope switched to ${scopeName}`;
-              }
-            } catch {
-              // scope switch failed — fall back to a warning
-              const currentApp = await getCurrentApplication(app.sdk, userSysID).catch(() => null);
-              scopeNote = scopeMismatchWarning(updateSetApp, currentApp);
+            if (scopeSysId) {
+              await setCurrentApplication(app.sdk, userSysID, scopeSysId);
+              const scopeName = updateSetApp?.display_value || updateSetApp;
+              scopeNote = ` — scope switched to ${scopeName}`;
             }
+            await setCurrentUpdateSet(app.sdk, userSysID, sysID);
 
             app.ok({ update_set: name, sys_id: sysID }, { summary: `Current update set: ${name}${scopeNote}` });
           }),
@@ -631,15 +622,18 @@ export function updateSetsCmd(wrap) {
 
             // Auto-set as current update set
             const sysID = record?.sys_id?.value || record?.sys_id;
+            let selectionNote = '';
             try {
               const userSysID = await requireCurrentUserSysId(app.sdk);
               await setCurrentUpdateSet(app.sdk, userSysID, sysID);
-            } catch {
-              // Non-fatal — auto-set is a convenience, not mandatory
+            } catch (error) {
+              // Creation succeeded. Report partial success without hiding a
+              // failed selection or inviting a duplicate create on retry.
+              selectionNote = `; not selected as current: ${error.message}. Run jsn updatesets set "${argv.name}"`;
             }
 
             app.ok(record, {
-              summary: `Created update set: ${argv.name}`,
+              summary: `Created update set: ${argv.name}${selectionNote}`,
               breadcrumbs: [
                 {
                   action: 'set',

package/src/context.js

@@ -63,25 +63,16 @@ export async function getCurrentUpdateSet(sdk, userSysID) {
   return { name: val, sys_id: val };
 }
 
-/**
- * Find-or-create a sys_user_preference and set its value. Shared by the
- * scope/update-set "set" commands and create auto-set (was copy-pasted 3x).
- */
-async function setUserPreference(sdk, userSysID, name, value) {
-  const params = new URLSearchParams();
-  params.set('sysparm_query', `user=${userSysID}^name=${name}`);
-  params.set('sysparm_limit', '1');
-  params.set('sysparm_fields', 'sys_id');
-  const prefs = await sdk.list('sys_user_preference', params);
-  if (prefs.length > 0) {
-    await sdk.update('sys_user_preference', getStringField(prefs[0], 'sys_id'), { value });
-  } else {
-    await sdk.create('sys_user_preference', {
-      user: userSysID,
-      name,
-      value,
-      type: 'string',
-    });
+// Use the same selection contract as the platform picker. Table API writes to
+// sys_user_preference do not update an already-warmed session's capture context.
+async function selectContext(sdk, picker, data, expected) {
+  const endpoint = `${sdk.baseURL}/api/now/ui/concoursepicker/${picker}`;
+  await sdk.request(endpoint, { method: 'PUT', body: JSON.stringify(data) });
+  const response = await sdk.request(endpoint, { method: 'GET' });
+  const current = response?.result?.current;
+  const actual = picker === 'application' ? current : current?.sysId;
+  if (actual !== expected) {
+    throw new Error(`${picker === 'application' ? 'Application' : 'Update set'} selection was not applied. Expected ${expected}, received ${typeof actual === 'string' ? actual : 'an unreadable selection'}.`);
   }
 }
 
@@ -98,12 +89,12 @@ export async function requireCurrentUserSysId(sdk) {
   return getStringField(user[0], 'sys_id');
 }
 
-/** Set the current application scope via the apps.current_app preference. */
-export async function setCurrentApplication(sdk, userSysID, scopeSysID) {
-  await setUserPreference(sdk, userSysID, 'apps.current_app', scopeSysID);
+/** Select application scope in the authenticated session and verify it. */
+export async function setCurrentApplication(sdk, _userSysID, scopeSysID) {
+  await selectContext(sdk, 'application', { app_id: scopeSysID }, scopeSysID);
 }
 
-/** Set the current update set via the sys_update_set preference. */
-export async function setCurrentUpdateSet(sdk, userSysID, updateSetSysID) {
-  await setUserPreference(sdk, userSysID, 'sys_update_set', updateSetSysID);
+/** Select the capture update set in the authenticated session and verify it. */
+export async function setCurrentUpdateSet(sdk, _userSysID, updateSetSysID) {
+  await selectContext(sdk, 'updateset', { sysId: updateSetSysID }, updateSetSysID);
 }