@jacebenson/jsn 4.3.7-dev.36 → 4.3.7-dev.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.7-dev.36",
+  "version": "4.3.7-dev.38",
   "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/commands/midservers.js

@@ -7,7 +7,7 @@ import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { detectDocker, defaultRun, installDockerMidServer, midInstallDirectory, normalizeMidName, validateMidCredentials } from '../midserver-install.js';
-import { detectDirectPlatform, installDirectMidServer, readDirectInstallation, removeDirectInstallation, runDirectInstallation } from '../midserver-direct.js';
+import { detectDirectPlatform, followDirectLog, installDirectMidServer, readDirectInstallation, removeDirectInstallation, resolveDirectLogFile, runDirectInstallation } from '../midserver-direct.js';
 
 const AGENT_TABLE = 'ecc_agent';
 const QUEUE_TABLE = 'ecc_queue';
@@ -344,14 +344,13 @@ function removeLocalMidServer(instanceURL, name, directory) {
   return true;
 }
 
-function showMidServerLogs(app, identifier, argv) {
+async function showMidServerLogs(app, identifier, argv) {
   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 logfile = resolveDirectLogFile(installDir);
+    if (!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');
@@ -360,8 +359,15 @@ function showMidServerLogs(app, identifier, argv) {
       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');
+      const all = buffer.toString('utf8').split('\n');
+      if (all.length && all[all.length - 1] === '') all.pop();
+      text = all.slice(-argv.tail).join('\n');
     } finally { fs.closeSync(fd); }
+    if (argv.follow) {
+      // Following streams new lines directly; the JSON envelope would be unreachable.
+      process.stdout.write(`Tailing ${logfile} (Ctrl+C to stop)\n${text}\n`);
+      return followDirectLog(installDir);
+    }
     app.ok({ installation: 'direct', logfile, text, _formatted: `${text}\n` }, { summary: 'Local MID agent log (last 1 MiB maximum)' });
     return;
   }
@@ -413,10 +419,10 @@ export function midserversCmd(wrap) {
         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 (Compose only)' })
+          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' })
           .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
-          showMidServerLogs(app, argv.identifier, argv);
+          await showMidServerLogs(app, argv.identifier, argv);
         }),
       })
       .command({
@@ -424,10 +430,10 @@ export function midserversCmd(wrap) {
         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 (Compose only)' })
+          .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' })
           .option('directory', { type: 'string', describe: 'Local installation directory override' }),
         handler: wrap(async (argv, app) => {
-          showMidServerLogs(app, argv.identifier, argv);
+          await showMidServerLogs(app, argv.identifier, argv);
         }),
       })
       .command({

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.
  *

package/src/midserver-direct.js

@@ -153,6 +153,55 @@ export function readDirectInstallation(instanceURL, name, directory) {
   return metadata;
 }
 
+// The vendor rotates agent0.log to agent0.log.0 (and upward), so the plain
+// name may not exist on a healthy install. Newest real file wins; links and
+// non-files are never followed.
+export function resolveDirectLogFile(installDir) {
+  const directory = path.join(installDir, 'agent', 'logs');
+  let names;
+  try { names = fs.readdirSync(directory); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  const candidates = [];
+  for (const name of names) {
+    const agent = /^agent0\.log(\.\d+)?$/.test(name);
+    if (!agent && name !== 'wrapper.log') continue;
+    const full = path.join(directory, name);
+    const stat = fs.lstatSync(full);
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    candidates.push({ full, agent, mtime: stat.mtimeMs });
+  }
+  candidates.sort((a, b) => (b.agent - a.agent) || (b.mtime - a.mtime));
+  return candidates.length ? candidates[0].full : null;
+}
+
+/**
+ * Tail a direct install's agent log, following rotation.
+ *
+ * The vendor rotates by creating a new file, so the followed path can change
+ * between polls; a shrinking file is treated as truncation and re-read from
+ * the start. Each appended chunk is handed to `writer` unchanged.
+ */
+export async function followDirectLog(installDir, { writer = chunk => process.stdout.write(chunk), intervalMs = 1000, iterations = Infinity, sleep } = {}) {
+  const pause = sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+  let file = resolveDirectLogFile(installDir);
+  if (!file) throw new Error('No MID agent log yet; the installation may only be prepared');
+  let offset = fs.statSync(file).size;
+  for (let seen = 0; seen < iterations; seen++) {
+    await pause(intervalMs);
+    const next = resolveDirectLogFile(installDir) || file;
+    if (next !== file) { file = next; offset = 0; }
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) return;
+    if (stat.size < offset) offset = 0;
+    if (stat.size === offset) continue;
+    const length = stat.size - offset;
+    const buffer = Buffer.alloc(length);
+    const fd = fs.openSync(file, 'r');
+    try { fs.readSync(fd, buffer, 0, length, offset); } finally { fs.closeSync(fd); }
+    offset = stat.size;
+    writer(buffer.toString('utf8'));
+  }
+}
+
 function uncertainState(metadata) {
   return `MID '${metadata.name}' runtime state is uncertain after an interrupted lifecycle command. Confirm no vendor MID process from ${metadata.installDir} is running, then rerun; installed files are kept.`;
 }