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

package/src/commands/midservers.js

@@ -5,7 +5,8 @@ import { confirmDelete, formatRecordForDisplay, getStringField, interactiveList,
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
-import { detectDocker, defaultRun, installDockerMidServer, midInstallDirectory, validateMidCredentials } from '../midserver-install.js';
+import { detectDocker, defaultRun, installDockerMidServer, midInstallDirectory, normalizeMidName, validateMidCredentials } from '../midserver-install.js';
+import { detectDirectPlatform, installDirectMidServer, readDirectInstallation, removeDirectInstallation, runDirectInstallation } from '../midserver-direct.js';
 
 const AGENT_TABLE = 'ecc_agent';
 const QUEUE_TABLE = 'ecc_queue';
@@ -13,7 +14,7 @@ const LIST_FIELDS = ['sys_id', 'name', 'status', 'host_name', 'ip_address', 'ver
 const DEFAULT_TIMEOUT = 120000;
 const DEFAULT_INTERVAL = 2000;
 
-declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute'] });
+declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute', 'start', 'stop'] });
 
 function agentName(record) {
   const name = getStringField(record, 'name');
@@ -231,7 +232,7 @@ export function assertMidServerReady(record) {
   const name = getStringField(record, 'name') || getStringField(record, 'sys_id') || 'MID Server';
   const validated = queueValue(record.validated).toLowerCase();
   if (validated !== 'true') {
-    const error = new Error(`MID Server '${name}' is not validated yet (validation: ${validated || 'unknown'}). Wait for ServiceNow validation to complete before executing a command.`);
+    const error = new Error(`MID Server '${name}' is not validated yet (validation: ${validated || 'unknown'}). Use the manual Validate action in ServiceNow before executing a command.`);
     error.code = 'midserver_not_validated';
     throw error;
   }
@@ -273,7 +274,7 @@ export async function waitForMidServerUp(app, name, timeoutMs, intervalMs) {
       sysparm_query: `name=${fullName}`,
       sysparm_limit: '1',
       sysparm_display_value: 'all',
-      sysparm_fields: 'sys_id,name,status,host_name,version,last_heartbeat',
+      sysparm_fields: 'sys_id,name,status,validated,host_name,version,last_heartbeat',
     });
     const records = await app.sdk.list(AGENT_TABLE, params);
     if (records[0] && getStringField(records[0], 'status').toLowerCase() === 'up') return records[0];
@@ -282,11 +283,16 @@ export async function waitForMidServerUp(app, name, timeoutMs, intervalMs) {
   throw new Error(`MID Server '${fullName}' did not report Up within ${timeoutMs}ms`);
 }
 
-function removeLocalMidServer(instanceURL, name) {
-  const installDir = midInstallDirectory(instanceURL, name);
+function removeLocalMidServer(instanceURL, name, directory) {
+  const direct = readDirectInstallation(instanceURL, name, directory);
+  if (direct) { removeDirectInstallation(direct); return true; }
+  const installDir = directory || midInstallDirectory(instanceURL, name);
   const composePath = path.join(installDir, 'docker-compose.yaml');
   const envPath = path.join(installDir, '.env');
-  if (!fs.existsSync(composePath)) return false;
+  if (!fs.existsSync(composePath)) {
+    if (fs.existsSync(path.join(installDir, 'agent'))) throw new Error('Native MID directory exists without trustworthy ownership metadata; refusing removal');
+    return false;
+  }
   const composeArgs = ['compose', ...(fs.existsSync(envPath) ? ['--env-file', envPath] : []), '-f', composePath, 'down'];
   try {
     defaultRun('docker', composeArgs, { cwd: installDir });
@@ -303,7 +309,26 @@ function removeLocalMidServer(instanceURL, name) {
 }
 
 function showMidServerLogs(app, identifier, argv) {
-  const installDir = midInstallDirectory(app.getEffectiveInstance(), identifier);
+  const installDir = argv.directory || midInstallDirectory(app.getEffectiveInstance(), identifier);
+  const direct = readDirectInstallation(app.getEffectiveInstance(), identifier, argv.directory);
+  if (direct) {
+    if (!Number.isInteger(argv.tail) || argv.tail < 1 || argv.tail > 10000) throw new Error('Use --tail between 1 and 10000');
+    if (argv.follow) throw new Error('Direct log follow is not supported; read logs again or use the native host log viewer');
+    const logfile = path.join(installDir, 'agent', 'logs', 'agent0.log');
+    if (!fs.existsSync(logfile)) throw new Error('No MID agent log yet; the installation may only be prepared');
+    const stat = fs.lstatSync(logfile);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Untrusted MID log path');
+    const fd = fs.openSync(logfile, 'r');
+    let text;
+    try {
+      const length = Math.min(stat.size, 1024 * 1024);
+      const buffer = Buffer.alloc(length);
+      fs.readSync(fd, buffer, 0, length, stat.size - length);
+      text = buffer.toString('utf8').split('\n').slice(-argv.tail).join('\n');
+    } finally { fs.closeSync(fd); }
+    app.ok({ installation: 'direct', logfile, text, _formatted: `${text}\n` }, { summary: 'Local MID agent log (last 1 MiB maximum)' });
+    return;
+  }
   const composePath = path.join(installDir, 'docker-compose.yaml');
   const envPath = path.join(installDir, '.env');
   if (!fs.existsSync(composePath)) throw new Error(`No local Compose installation found for MID Server '${identifier}'`);
@@ -349,24 +374,48 @@ export function midserversCmd(wrap) {
       })
       .command({
         command: 'logs <identifier>',
-        describe: 'Show local Docker Compose logs for a MID Server',
+        describe: 'Show local native or Docker Compose MID logs',
         builder: (b) => b
           .option('tail', { type: 'number', default: 100, describe: 'Number of log lines' })
-          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' }),
+          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs (Compose only)' })
+          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
           showMidServerLogs(app, argv.identifier, argv);
         }),
       })
       .command({
         command: '<identifier> logs',
-        describe: 'Show local Docker Compose logs for a MID Server',
+        describe: 'Show local native or Docker Compose MID logs',
         builder: (b) => b
           .option('tail', { type: 'number', default: 100, describe: 'Number of log lines' })
-          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' }),
+          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs (Compose only)' })
+          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
           showMidServerLogs(app, argv.identifier, argv);
         }),
       })
+      .command({
+        command: 'start <identifier>',
+        describe: 'Start an owned direct MID (Windows: foreground console, no service)',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' }),
+        handler: wrap(async (argv, app) => {
+          const metadata = readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory);
+          if (!metadata) throw new Error('No owned direct MID installation found');
+          if (metadata.state !== 'prepared') throw new Error('MID is already started or has an uncertain runtime state; stop it first');
+          const result = runDirectInstallation(metadata, 'start');
+          app.ok(result, { summary: result.platform === 'windows' ? 'Windows MID console exited; no service was registered' : 'MID start command completed; registration and manual validation must be checked in ServiceNow' });
+        }),
+      })
+      .command({
+        command: 'stop <identifier>',
+        describe: 'Stop an owned Linux direct MID; Windows console uses Ctrl+C',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' }),
+        handler: wrap(async (argv, app) => {
+          const metadata = readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory);
+          if (!metadata) throw new Error('No owned direct MID installation found');
+          app.ok(runDirectInstallation(metadata, 'stop'), { summary: 'Owned native MID stop command completed' });
+        }),
+      })
       .command({
         command: 'add',
         describe: 'Install and verify a MID Server',
@@ -374,7 +423,7 @@ export function midserversCmd(wrap) {
           .option('name', { type: 'string', describe: 'MID Server name (prompted when omitted)' })
           .option('username', { type: 'string', describe: 'MID Server username (password is always prompted)' })
           .option('install-method', { type: 'string', choices: ['docker', 'direct'], describe: 'Installation method (prompted when omitted)' })
-          .option('directory', { type: 'string', describe: 'Docker installation directory' })
+          .option('directory', { type: 'string', describe: 'Installation directory (must not exist for direct ZIP)' })
           .option('wait-timeout', { type: 'number', default: 300000, describe: 'How long to wait for the MID Server to report Up' })
           .option('wait-interval', { type: 'number', default: 3000, describe: 'MID Server status polling interval in milliseconds' }),
         handler: wrap(async (argv, app) => {
@@ -395,20 +444,51 @@ export function midserversCmd(wrap) {
             choices: dockerAvailable
               ? [
                 { name: 'Docker (recommended)', value: 'docker' },
-                { name: 'Direct install (not available yet)', value: 'direct' },
+                { name: 'Direct ZIP install (native user-owned runtime)', value: 'direct' },
               ]
               : dockerStatus.installed && dockerStatus.compose
                 ? [
                   { name: 'Run with sudo', value: 'sudo' },
                   { name: 'Prepare files now, run Docker later', value: 'prepare' },
-                  { name: 'Direct install (not available yet)', value: 'direct' },
+                  { name: 'Direct ZIP install (native user-owned runtime)', value: 'direct' },
                 ]
               : [
                 { name: 'Prepare files now, run Docker later', value: 'prepare' },
-                { name: 'Direct install (not available yet)', value: 'direct' },
+                { name: 'Direct ZIP install (native user-owned runtime)', value: 'direct' },
               ],
           });
-          if (installMethod === 'direct') throw new Error('Direct MID Server installation is not implemented yet. Choose Docker.');
+          if (installMethod === 'direct') {
+            const native = detectDirectPlatform();
+            const decision = await select({
+              message: native === 'linux' ? 'No system service or elevation will be used. Choose runtime:' : 'Windows console runtime only; native service registration is not supported. Choose:',
+              choices: [
+                ...(native === 'linux' ? [{ name: 'Start user-owned background MID', value: 'start' }] : []),
+                { name: 'Prepare private files only (do not start)', value: 'prepare' },
+                { name: 'Cancel without downloading', value: 'cancel' },
+              ],
+            });
+            if (decision === 'cancel') return;
+            const shortName = normalizeMidName(name);
+            const existing = await app.sdk.list(AGENT_TABLE, new URLSearchParams({ sysparm_query: `name=${shortName}`, sysparm_fields: 'sys_id,name', sysparm_limit: '1' }));
+            if (existing.length) throw new Error(`MID '${shortName}' already exists in ServiceNow; choose a new name. Existing runtime and record were not changed.`);
+            const installation = await installDirectMidServer({
+              instanceURL: app.getEffectiveInstance(), ...credentials, name, directory: argv.directory, runNow: decision === 'start',
+            });
+            if (installation.state === 'prepared') {
+              app.ok(installation, { summary: `Prepared native MID '${installation.name}' in ${installation.installDir}; not started or registered. Start with jsn midservers start ${installation.name}${argv.directory ? ' --directory ' + JSON.stringify(installation.installDir) : ''}. Windows start runs in the foreground console; no service is installed.` });
+              return;
+            }
+            let record;
+            try { record = await waitForMidServerUp(app, installation.name, Math.max(1, argv['wait-timeout']), Math.max(500, argv['wait-interval'])); }
+            catch {
+              app.ok({ ...installation, registration: 'pending', validated: false }, { summary: `Native MID start command completed; registration is pending. Runtime retained for diagnostics at ${installation.installDir}; no forced teardown.` });
+              return;
+            }
+            const validated = queueValue(record.validated).toLowerCase() === 'true';
+            const url = new URL(`/ecc_agent.do?sys_id=${encodeURIComponent(unwrapSysId(record))}`, app.getEffectiveInstance()).href;
+            app.ok({ ...installation, registration: 'up', validated, record, url }, { summary: validated ? `MID '${installation.name}' is Up and manually validated` : `MID '${installation.name}' is Up but pending manual validation. Use Validate in ServiceNow: ${url}` });
+            return;
+          }
 
           const installation = await installDockerMidServer({
             instanceURL: app.getEffectiveInstance(),
@@ -448,7 +528,8 @@ export function midserversCmd(wrap) {
         command: 'remove [identifier]',
         aliases: ['delete'],
         describe: 'Remove a MID Server record (interactive when no identifier is given)',
-        builder: (b) => b.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+        builder: (b) => b.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' })
+          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
           let record;
           if (argv.identifier) {
@@ -456,8 +537,8 @@ export function midserversCmd(wrap) {
               record = await resolveMidServer(app.sdk, argv.identifier);
             } catch (error) {
               if (error.code !== 'not_found') throw error;
-              const localDir = midInstallDirectory(app.getEffectiveInstance(), argv.identifier);
-              if (!fs.existsSync(path.join(localDir, 'docker-compose.yaml'))) throw error;
+              const localDir = argv.directory || midInstallDirectory(app.getEffectiveInstance(), argv.identifier);
+              if (!readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory) && !fs.existsSync(path.join(localDir, 'docker-compose.yaml'))) throw error;
               record = null;
             }
           } else {
@@ -483,9 +564,10 @@ export function midserversCmd(wrap) {
           const sysId = record ? unwrapSysId(record) : null;
           const name = getStringField(record, 'name') || argv.identifier || sysId;
           await confirmDelete(app, argv, `Remove MID Server '${name}'`);
-          const localRemoved = removeLocalMidServer(app.getEffectiveInstance(), name);
+          const direct = readDirectInstallation(app.getEffectiveInstance(), name, argv.directory);
+          const localRemoved = removeLocalMidServer(app.getEffectiveInstance(), name, argv.directory);
           if (record) await app.sdk.delete(AGENT_TABLE, sysId);
-          app.ok({ name, sys_id: sysId, deleted: Boolean(record), local_compose_removed: localRemoved }, { summary: `Removed MID Server '${name}'${localRemoved ? ' and its local Compose stack' : ''}` });
+          app.ok({ name, sys_id: sysId, deleted: Boolean(record), local_compose_removed: localRemoved && !direct, local_installation_removed: localRemoved, local_installation_type: direct ? 'direct' : 'docker' }, { summary: `Removed MID Server '${name}'${localRemoved ? ' and its owned local runtime' : ''}` });
         }),
       })
       .command({
@@ -563,7 +645,7 @@ export function midserversCmd(wrap) {
       console.log('  issues [name_or_sys_id]       Show unresolved issues (--all includes resolved)');
       console.log('  events [name_or_sys_id]       Show lifecycle history');
       console.log('  show <name_or_sys_id>        Show a MID Server');
-      console.log('  add --name <name>             Create a MID Server record');
+      console.log('  add --name <name>             Install a MID Server (Docker or direct ZIP)');
       console.log('  remove <name_or_sys_id>       Remove a MID Server record');
       console.log('  execute <name_or_sys_id>      Execute a shell command');
       console.log('');

package/src/errors.js

@@ -204,6 +204,11 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
   // 'usage' is the legacy literal; CodeUsage ('usage_error') is the
   // exported constant. Both render as the usage class.
   if (code === CodeUsage || code === 'usage') {
+    // Interactive command families can opt into machine-readable fail-fast errors
+    // without changing the legacy stderr contract for other usage errors.
+    if (err.jsonEnvelope === true && resolveJsonMode(app, argv) && app) {
+      return { stream: 'stdout', text: null, exitCode: 2, appErr: true };
+    }
     return { stream: 'stderr', text: `Error (usage): ${err.message}\n`, exitCode: 2 };
   }
 

package/src/flow-create.js

@@ -91,7 +91,7 @@ function assertGraphQLSuccess(response, operation) {
   if (response?.result?.errorMessage) throw new Error(`${operation} failed: ${response.result.errorMessage}`);
 }
 
-function schemaEntries(definition) {
+function schemaEntries(definition, requireTypes = false) {
   const entries = [];
   const seen = new Set();
   walk(definition, object => {
@@ -102,6 +102,7 @@ function schemaEntries(definition) {
         const name = stringValue(field.name || field.key || field.element || field.parameter);
         if (!name || seen.has(name)) continue;
         seen.add(name);
+        if (requireTypes && !stringValue(field.type || field.inputType || field.valueType)) throw new Error(`Input ${name} has no provider type; refusing to invent a guided schema`);
         entries.push({
           ...field,
           name,
@@ -193,7 +194,7 @@ export function buildFlowUpdateMutation({ flowId, triggerUpdates = [], actionUpd
   return `mutation { global { snFlowDesigner { flow(${patch}) { triggerInstances { updates } actions { updates } } } } }`;
 }
 
-async function readProcessFlow(sdk, instance, flowId, scope) {
+export async function readProcessFlow(sdk, instance, flowId, scope) {
   if (!scope) throw new Error(`Flow ${flowId} has no transaction scope for ProcessFlow read`);
   const endpoint = `${instance}${FLOW_ENDPOINT}/${encodeURIComponent(flowId)}?sysparm_transaction_scope=${encodeURIComponent(scope)}`;
   const response = await sdk.request(endpoint, { method: 'GET' });
@@ -220,11 +221,11 @@ async function resolveActionType(sdk, actionType) {
   return { id: actionTypeId(record), record };
 }
 
-async function readActionDefinition(sdk, instance, actionTypeId, scope) {
+export async function readActionDefinition(sdk, instance, actionTypeId, scope, { requireTypes = false } = {}) {
   const endpoint = `${instance}/api/now/processflow/action/action_types/${encodeURIComponent(actionTypeId)}?sysparm_transaction_scope=${encodeURIComponent(scope)}`;
   const response = await sdk.request(endpoint, { method: 'GET' });
   const definition = response?.result ?? response?.data?.result ?? response?.data ?? response;
-  const schema = schemaEntries(definition);
+  const schema = schemaEntries(definition, requireTypes);
   if (schema.length === 0) throw new Error(`Action type ${actionTypeId} returned no input schema`);
   return { definition, schema };
 }
@@ -257,7 +258,7 @@ function parseSimpleCondition(condition) {
   return { field: match[1], operator: match[2], term: match[3] };
 }
 
-async function readTableDescriptor(sdk, instance, scope, table, override) {
+export async function readTableDescriptor(sdk, instance, scope, table, override) {
   if (override) return override(table);
   const endpoint = `${instance}${TABLE_DESCRIPTOR_ENDPOINT}?table=${encodeURIComponent(table)}&sysparm_transaction_scope=${encodeURIComponent(scope)}`;
   const response = await sdk.request(endpoint, { method: 'GET' });

package/src/flow-designer-interactive.js

@@ -0,0 +1,327 @@
+// Terminal orchestration only. Persistence and lifecycle remain in the SDK.
+import fs from 'node:fs';
+import { randomUUID, randomBytes } from 'node:crypto';
+import { input, select, confirm, editor } from '@inquirer/prompts';
+import { canPrompt, interactiveList, getStringField } from './helpers.js';
+import { FormatAuto } from './output.js';
+import { errUsage, errConfirmationRequired } from './errors.js';
+import { getCurrentUser, getCurrentApplication } from './context.js';
+import { validateDefinition, validateScope, ACTION_TABLE } from './processflow-actions.js';
+import { validateFlowManifest, validateFlowUpdateManifest, readProcessFlow, readActionDefinition, readTableDescriptor } from './flow-create.js';
+import { deriveRecordTrigger } from './flow-test.js';
+import { getActiveProfile } from './config.js';
+
+const CANCEL = Symbol('cancel');
+const clone = value => structuredClone(value);
+export const rawField = value => value && typeof value === 'object' && 'value' in value ? value.value : value;
+const prompts = app => app.flowDesignerPrompts || { input, select, confirm, editor };
+export function hasDefinitionData(argv) {
+  return argv.data !== undefined || argv['data-file'] !== undefined || argv.dataFile !== undefined;
+}
+export function interactiveDesigner(argv, app) {
+  return !hasDefinitionData(argv) && argv['output-map'] === undefined && !argv.get && app.output?.getFormat() === FormatAuto && canPrompt();
+}
+export async function cancelled(operation) {
+  try { return await operation(); }
+  catch (error) {
+    if (error === CANCEL || ['ExitPromptError', 'AbortPromptError'].includes(error.name)) return undefined;
+    // Keep direct handler errors throwable; opt into the shared JSON renderer at the CLI boundary.
+    if (error.code === 'usage_error') error.jsonEnvelope = true;
+    throw error;
+  }
+}
+export async function pickDesignerRecord(argv, app, table, singular, query = '', labelField = 'name') {
+  if (argv.identifier !== undefined) {
+    if (!String(argv.identifier).trim()) throw errUsage(`${singular} identifier must not be empty`);
+    return argv.identifier;
+  }
+  if (!interactiveDesigner(argv, app)) throw errUsage(`Provide an explicit ${singular} identifier in noninteractive mode`);
+  const picked = await interactiveList({ app, table, singular, query, labelField,
+    columns: [labelField], promptFn: app.promptFn });
+  if (picked === null) throw errUsage(`No readable ${singular} records are available for selection`);
+  if (picked === undefined) return undefined;
+  const id = rawField(picked.sys_id);
+  if (!id) throw errUsage(`Selected ${singular} has no raw sys_id`);
+  return id;
+}
+export async function designerScope(argv, app) {
+  if (argv.scope !== undefined) return validateScope(app.sdk, argv.scope);
+  if (!interactiveDesigner(argv, app)) throw errUsage('Provide --scope <exact sys_id or global> in noninteractive mode');
+  const user = await getCurrentUser(app.sdk);
+  const current = user ? await getCurrentApplication(app.sdk, user.sys_id) : null;
+  if (current?.appSysId && await prompts(app).confirm({ message: `Use current application scope ${current.appSysId}?`, default: true })) {
+    return validateScope(app.sdk, current.appSysId);
+  }
+  const scope = await pickDesignerRecord(argv, app, 'sys_scope', 'scope');
+  if (scope === undefined) throw CANCEL;
+  return validateScope(app.sdk, scope);
+}
+export async function confirmDesignerSave(app, message) {
+  if (!await prompts(app).confirm({ message, default: false })) throw CANCEL;
+}
+// Explicit JSON/data, pipes and disabled prompts never enter a TTY confirmation.
+export async function confirmDesignerMutation(argv, app, message) {
+  if (argv.force) return;
+  if (interactiveDesigner(argv, app)) return confirmDesignerSave(app, message);
+  if (getActiveProfile(app.config)?.skip_confirmations === true) return;
+  throw errConfirmationRequired(message, ['jsn', ...(argv._ || [])].join(' '));
+}
+function required(value) { return String(value).trim() ? true : 'A value is required'; }
+function scalarDefault(value) { return value == null ? '' : typeof value === 'string' ? value : JSON.stringify(value); }
+function schemaObjectValue(field, value) {
+  return ['object', 'complex'].includes(field.type) && value && typeof value === 'object'
+    && !('schemaless' in value) && field.children?.some(child => Object.hasOwn(value, child.name));
+}
+
+// Preserve schema objects. Change only a requested value, never regenerate metadata.
+export async function promptSchemaValue(app, field, existing, prefix = '') {
+  if (!field?.name || !field.type) throw errUsage('Provider returned an incomplete named, typed input schema');
+  const p = prompts(app);
+  const message = `${prefix}${field.label || field.name} [${field.type}]`;
+  const supplied = existing ?? field.defaultValue ?? field.default;
+  const value = schemaObjectValue(field, supplied) ? supplied : rawField(supplied);
+  if (field.type === 'script') {
+    const method = await p.select({ message: `${message}: script source`, choices: [
+      { name: 'Script file', value: 'file' }, { name: 'Open $VISUAL/$EDITOR', value: 'editor' },
+    ] });
+    const script = method === 'file'
+      ? fs.readFileSync(await p.input({ message: 'Script file path', validate: required }), 'utf8')
+      : await p.editor({ message, default: scalarDefault(value), waitForUse: true });
+    if ((field.mandatory === true || field.required === true) && !script.trim()) throw errUsage(`Script ${field.name} is required; nothing was saved`);
+    return script;
+  }
+  if (typeof value === 'string' && value.startsWith('{{')) {
+    return p.input({ message: `${message} (raw pill)`, default: value, validate: required });
+  }
+  if (field.children?.length && ['object', 'complex'].includes(field.type)) {
+    const result = value && typeof value === 'object' && !Array.isArray(value) ? clone(value) : {};
+    for (const child of field.children) result[child.name] = await promptSchemaValue(app, child, result[child.name], `${message}.`);
+    return result;
+  }
+  if (['boolean', 'bool'].includes(field.type)) {
+    return p.confirm({ message, default: value === true || value === 'true' });
+  }
+  if (field.type === 'choice' && Array.isArray(field.choices) && field.choices.length) {
+    if (field.choices.some(choice => typeof choice !== 'string' && (!choice || !Object.hasOwn(choice, 'value')))) {
+      throw errUsage(`Choice input ${field.name} has incomplete provider choices; nothing was saved`);
+    }
+    return p.select({ message, default: value, choices: field.choices.map(choice => ({
+      name: typeof choice === 'string' ? choice : String(choice.label ?? choice.display_value ?? choice.value),
+      value: typeof choice === 'string' ? choice : choice.value,
+    })) });
+  }
+  const textual = ['string', 'reference', 'table_name', 'field_name', 'conditions', 'condition', 'html', 'url', 'email', 'choice', 'document_id'];
+  const numeric = ['integer', 'number', 'decimal', 'float'];
+  if (![...textual, ...numeric].includes(field.type)) {
+    throw errUsage(`Guided input ${field.name} has unsupported type ${field.type}; use --data-file to preserve its complete schema and value`);
+  }
+  const answer = await p.input({ message: `${message} (raw pills accepted)`, default: scalarDefault(value), validate: answer => {
+    if ((field.mandatory === true || field.required === true) && answer === '') return 'A value is required';
+    if (numeric.includes(field.type) && answer !== '' && !answer.startsWith('{{') && (!Number.isFinite(Number(answer)) || field.type === 'integer' && !Number.isInteger(Number(answer)))) return 'Enter a valid number or raw pill';
+    return true;
+  } });
+  // Pills are opaque provider expressions, not numbers to be coerced.
+  return numeric.includes(field.type) && answer !== '' && !answer.startsWith('{{') ? Number(answer) : answer;
+}
+async function editVariables(app, variables, message, valueKey = 'value') {
+  for (const field of variables.filter(field => !field.name.startsWith('__'))) {
+    if (await prompts(app).confirm({ message: `${message}: change ${field.name}?`, default: false })) {
+      const value = await promptSchemaValue(app, field, field[valueKey], `${message}: `);
+      const wrapped = field[valueKey] && typeof field[valueKey] === 'object' && 'value' in field[valueKey] && !schemaObjectValue(field, field[valueKey]);
+      field[valueKey] = wrapped ? { ...field[valueKey], value } : value;
+      if (valueKey === 'defaultValue') field.mandatory = await prompts(app).confirm({ message: `${field.name}: required?`, default: field.mandatory === true });
+    }
+  }
+}
+function schemaTemplates(types) {
+  const templates = [];
+  const visit = fields => {
+    if (fields !== undefined && !Array.isArray(fields)) throw errUsage('Provider variable schema must be an array; no parent was allocated');
+    for (const field of fields || []) {
+      if (!field || typeof field !== 'object') throw errUsage('Provider variable schema requires objects; no parent was allocated');
+      if (field.name && field.type && !field.name.startsWith('__')) templates.push(field);
+      visit(field.children);
+    }
+  };
+  for (const type of types) { visit(type.inputs); visit(type.outputs); visit(type.extended_inputs); visit(type.extended_outputs); }
+  return templates;
+}
+function freshVariable(template) {
+  const field = clone(template);
+  const renew = variable => {
+    variable.id = randomBytes(16).toString('hex');
+    if (variable.attributes?.uiUniqueId) variable.attributes.uiUniqueId = randomUUID();
+    for (const child of variable.children || []) renew(child);
+  };
+  renew(field);
+  return field;
+}
+async function newVariable(app, templates, message) {
+  const candidates = templates.filter(field => ['string', 'integer', 'boolean', 'reference', 'object'].includes(field.type));
+  if (!candidates.length) throw errUsage('Step schemas contain no supported variable templates; use --data-file');
+  const template = await prompts(app).select({ message: `${message}: select provider schema template`, choices: candidates.map(field => ({ name: `${field.name} [${field.type}]`, value: field })) });
+  const field = freshVariable(template);
+  field.name = await prompts(app).input({ message: `${message}: variable name`, validate: value => /^[A-Za-z_][A-Za-z0-9_]*$/.test(value) || 'Use a JavaScript variable name' });
+  field.label = field.name;
+  field.mandatory = await prompts(app).confirm({ message: `${field.name}: required?`, default: false });
+  delete field.value;
+  delete field.display_value;
+  return field;
+}
+export function stepTypeSchemas(response) {
+  const types = Array.isArray(response) ? response : response?.step_types ?? response?.stepTypes;
+  if (!Array.isArray(types) || !types.length) throw errUsage('Provider returned no supported step_types schema array; no parent was allocated');
+  return types;
+}
+export async function guidedActionCreate(argv, app) {
+  if (!interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for a full action definition in noninteractive mode');
+  const scope = await designerScope(argv, app);
+  const types = stepTypeSchemas(await app.sdk.getProcessFlowStepTypes(scope));
+  const definition = { scope, name: await prompts(app).input({ message: 'Action name', validate: required }),
+    description: await prompts(app).input({ message: 'Description' }), inputs: [], outputs: [], steps: [] };
+  const templates = schemaTemplates(types);
+  while (await prompts(app).confirm({ message: 'Add an action input?', default: false })) {
+    definition.inputs.push(await newVariable(app, templates, 'Action input'));
+  }
+  do {
+    const schema = await prompts(app).select({ message: 'Select executable step schema', choices: types.map(type => ({ name: type.name || type.step_type_name || type.type || type.step_type, value: type })) });
+    if (!(schema.type || schema.step_type) || !(schema.id || schema.step_type_id) || !Array.isArray(schema.inputs) || !Array.isArray(schema.outputs)) {
+      throw errUsage('Selected provider step schema is incomplete; no parent was allocated');
+    }
+    const step = { ...clone(schema), cid: randomUUID(), step_type: schema.step_type || schema.type,
+      step_type_id: schema.step_type_id || schema.id, order: definition.steps.length + 1,
+      inputs: clone(schema.inputs), outputs: clone(schema.outputs),
+      extended_inputs: clone(schema.extended_inputs || []), extended_outputs: clone(schema.extended_outputs || []) };
+    delete step.id;
+    delete step.step_id;
+    delete step.action;
+    for (const field of step.inputs) field.value = await promptSchemaValue(app, field, field.value);
+    if (step.step_type === 'SCRIPT') {
+      for (const field of definition.inputs) step.extended_inputs.push({ ...freshVariable(field), extended: true, value: `{{inputs.${field.name}}}` });
+      while (await prompts(app).confirm({ message: 'Declare a script step output?', default: false })) {
+        step.extended_outputs.push({ ...await newVariable(app, templates, 'Script output'), extended: true });
+      }
+    }
+    definition.steps.push(step);
+  } while (await prompts(app).confirm({ message: 'Add another step?', default: false }));
+  const outputs = definition.steps.flatMap(step => [...step.outputs, ...step.extended_outputs]
+    .filter(field => !field.name.startsWith('__')).map(field => ({ step, field })));
+  while (await prompts(app).confirm({ message: 'Map a step output to an action output?', default: false })) {
+    if (!outputs.length) throw errUsage('No provider-declared step outputs available');
+    const { step, field } = await prompts(app).select({ message: 'Select output', choices: outputs.map(candidate => ({ name: `Step ${candidate.step.order}: ${candidate.field.name}`, value: candidate })) });
+    const output = { ...freshVariable(field), extended: false };
+    output.name = await prompts(app).input({ message: 'Action output name', default: field.name, validate: required });
+    output.value = `{{step[${step.cid}].${field.name}}}`;
+    definition.outputs.push(output);
+  }
+  validateDefinition(definition, undefined, scope);
+  await confirmDesignerSave(app, `Create inactive draft action '${definition.name}' with ${definition.steps.length} step(s)? No publish or execution.`);
+  return { scope, definition };
+}
+export async function guidedActionEdit(argv, app, definition) {
+  if (!interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for the full action definition in noninteractive mode');
+  validateDefinition(definition, definition.id, definition.scope);
+  const edited = clone(definition);
+  const fields = await prompts(app).select({ message: 'Edit action', choices: [
+    { name: 'Name and description', value: 'metadata' }, { name: 'Action inputs', value: 'inputs' },
+    { name: 'Action output mappings', value: 'outputs' }, { name: 'Step inputs, scripts and mappings', value: 'steps' },
+  ] });
+  if (fields === 'metadata') {
+    edited.name = await prompts(app).input({ message: 'Action name', default: edited.name, validate: required });
+    if (Object.hasOwn(edited, 'displayName')) edited.displayName = edited.name;
+    edited.description = await prompts(app).input({ message: 'Description', default: edited.description || '' });
+  } else if (fields === 'steps') {
+    const step = await prompts(app).select({ message: 'Select saved step', choices: edited.steps.map(step => ({ name: `${step.order}: ${step.step_type}`, value: step })) });
+    await editVariables(app, step.inputs, 'Step input');
+    await editVariables(app, step.extended_inputs, 'Step input mapping');
+    await editVariables(app, step.extended_outputs, 'Step output');
+  } else await editVariables(app, edited[fields], fields, fields === 'inputs' ? 'defaultValue' : 'value');
+  validateDefinition(edited, definition.id, definition.scope);
+  await confirmDesignerSave(app, `Save action '${edited.name}'? Unspecified schema and lifecycle identities are preserved. No publish or execution.`);
+  return edited;
+}
+export async function guidedActionTestInputs(argv, app, definition) {
+  const values = {};
+  for (const field of definition.inputs) values[field.name] = await promptSchemaValue(app, field, field.defaultValue, 'Test input: ');
+  return values;
+}
+async function tableName(argv, app) {
+  const id = await pickDesignerRecord(argv, app, 'sys_db_object', 'trigger table');
+  if (id === undefined) throw CANCEL;
+  const table = await app.sdk.get('sys_db_object', id);
+  const name = rawField(table?.name);
+  if (!name) throw errUsage('Selected trigger table has no raw name');
+  return name;
+}
+export async function guidedFlowCreate(argv, app) {
+  if (!interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for the flow manifest in noninteractive mode');
+  const manifest = { name: await prompts(app).input({ message: 'Flow name', validate: required }),
+    description: await prompts(app).input({ message: 'Description' }), scope: await designerScope(argv, app),
+    trigger: { type: 'record_create_or_update', table: await tableName(argv, app),
+      condition: await prompts(app).input({ message: 'Trigger condition (single supported encoded predicate, or empty)' }) }, actions: [] };
+  while (await prompts(app).confirm({ message: 'Add a published action?', default: true })) {
+    const id = await pickDesignerRecord(argv, app, ACTION_TABLE, 'published action', 'active=true^published=true');
+    if (id === undefined) throw CANCEL;
+    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`);
+      }
+      inputs[field.name] = await promptSchemaValue(app, field, field.default, 'Action input: ');
+    }
+    manifest.actions.push({ type: id, inputs });
+  }
+  validateFlowManifest(manifest);
+  await confirmDesignerSave(app, `Create inactive draft flow '${manifest.name}' with ${manifest.actions.length} action(s)? No publish or execution.`);
+  return manifest;
+}
+export async function savedFlowDefinition(app, identifier) {
+  const { resolveRecord, unwrapSysId } = await import('./resolve-record.js');
+  const record = await resolveRecord(app.sdk, { table: 'sys_hub_flow', identifier, matchField: 'name', resource: 'flow' });
+  const id = unwrapSysId(record);
+  const scope = rawField(record.scope);
+  if (!scope) throw errUsage('Saved flow has no raw transaction scope');
+  return { record, definition: await readProcessFlow(app.sdk, app.getEffectiveInstance(), id, scope) };
+}
+export async function guidedFlowEdit(argv, app) {
+  if (!interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for the flow update manifest in noninteractive mode');
+  const { record, definition } = await savedFlowDefinition(app, argv.identifier);
+  if (rawField(record.active) === true || rawField(record.active) === 'true' || rawField(record.status) !== 'draft') throw errUsage('Guided flow edit requires an inactive Draft');
+  const manifest = {};
+  const choice = await prompts(app).select({ message: 'Edit supported draft flow fields', choices: [
+    { name: 'Record trigger condition', value: 'trigger' }, { name: 'Existing action input values', value: 'actions' },
+  ] });
+  if (choice === 'trigger') {
+    const trigger = deriveRecordTrigger(definition).trigger;
+    const condition = (trigger.inputs || []).find(field => field.name === 'condition');
+    manifest.trigger = { condition: await prompts(app).input({ message: 'Trigger condition (single supported encoded predicate, or empty)', default: rawField(condition?.value) || '' }) };
+  } else {
+    const actions = definition.actionInstances || definition.actions || [];
+    if (!actions.length) throw errUsage('Saved flow contains no supported action instances');
+    const action = await prompts(app).select({ message: 'Select saved action instance', choices: actions.map(action => ({ name: `${action.order}: ${getStringField(action, 'name') || action.actionTypeSysId}`, value: action })) });
+    const fields = action.inputs || action.inputValues || [];
+    if (!fields.length) throw errUsage('Saved action instance contains no input schema');
+    const field = await prompts(app).select({ message: 'Select input to change', choices: fields.map(field => ({ name: `${field.name} [${field.type || field.parameter?.type || 'unknown'}]`, value: field })) });
+    const actionType = rawField(action.actionTypeSysId || action.action_type_sys_id || action.actionType?.sys_id || action.actionType?.sysId);
+    let inputSchema = { ...field, type: field.type || field.parameter?.type };
+    if (!inputSchema.type) {
+      const { schema } = await readActionDefinition(app.sdk, app.getEffectiveInstance(), actionType, rawField(record.scope), { requireTypes: true });
+      inputSchema = schema.find(candidate => candidate.name === field.name);
+      if (!inputSchema) throw errUsage(`Saved action input ${field.name} is absent from its provider schema`);
+    }
+    const value = await promptSchemaValue(app, inputSchema, rawField(field.value));
+    manifest.actions = [{ order: Number(action.order), type: actionType, inputs: { [field.name]: value } }];
+  }
+  validateFlowUpdateManifest(manifest);
+  return manifest;
+}
+export async function guidedFlowTestRecord(argv, app) {
+  if (argv.record !== undefined) return argv.record;
+  if (!interactiveDesigner(argv, app)) throw errUsage('Provide --record <sys_id> in noninteractive mode');
+  const { record, definition } = await savedFlowDefinition(app, argv.identifier);
+  const { table } = deriveRecordTrigger(definition);
+  const descriptor = await readTableDescriptor(app.sdk, app.getEffectiveInstance(), rawField(record.scope), table);
+  const { identifier: _identifier, ...pickerArgs } = argv;
+  return pickDesignerRecord(pickerArgs, app, table, `test record in ${table}`, '', descriptor.displayField);
+}