@sonisoft/now-sdk-ext-cli 2.0.1 → 2.1.0

package/oclif.manifest.json

@@ -1678,123 +1678,6 @@
         "update.js"
       ]
     },
-    "exec": {
-      "aliases": [],
-      "args": {
-        "scope": {
-          "description": "Scope to execute script in. Use \"global\" for global scope.",
-          "name": "scope",
-          "required": true
-        },
-        "file": {
-          "description": "File to execute in scripts background. If omitted, starts REPL mode.",
-          "name": "file",
-          "required": false
-        }
-      },
-      "description": "Execute JavaScript on a ServiceNow instance remotely using Scripts - Background.\n\nThis command allows you to run JavaScript either from files or interactively via REPL mode. It mimics the functionality of the Scripts - Background interface in ServiceNow, providing a way to execute scripts programmatically without manual interaction. The output is returned in real-time and can be piped to other commands or saved to files.\n\nModes:\n  • File Mode: Provide a file path to execute scripts from a file\n  • REPL Mode: Omit the file path to start an interactive session\n\nFeatures:\n  • Execute local JavaScript files remotely\n  • Interactive REPL for ad-hoc script execution\n  • Script parameterization with {placeholder} replacement\n  • Multi-line script support in REPL\n  • Scope-aware execution (global or custom scope)\n  • Real-time console output capture\n  • Pipe-able output for command chaining\n  • Debug logging support\n  • Useful for data migration, testing, and administrative tasks\n\nScript Parameterization:\n  Use {paramName} placeholders in your script files, then provide values via --params:\n  • Supports any JSON-serializable values (strings, numbers, booleans)\n  • Multiple parameters supported\n  • All occurrences of each placeholder are replaced\n  • Example: {token}, {username}, {environment}\n\nREPL Controls:\n  • Press Enter to add a new line\n  • Type .exec or press Ctrl+D to execute the script\n  • Type .clear to clear the current input\n  • Type .exit or press Ctrl+C twice to exit REPL\n\n⚠️  IMPORTANT SECURITY WARNING:\nThis command executes scripts with the same permissions and risks as using Scripts - Background directly\nin ServiceNow. Always:\n  • Review scripts before execution\n  • Test in non-production environments first\n  • Use appropriate scoping to limit access\n  • Be aware of data modification risks\n  • Follow your organization's security policies\n  • Never execute untrusted scripts\n\nScript Capabilities:\n  Scripts run with full GlideSystem API access and can:\n  • Query and modify database records\n  • Create, update, and delete data\n  • Execute business rules and workflows\n  • Access all APIs available in Scripts - Background\n  • Use gs, GlideRecord, GlideAggregate, and other server-side APIs",
-      "examples": [
-        {
-          "description": "Start REPL in global scope",
-          "command": "<%= config.bin %> <%= command.id %> global --auth dev-instance"
-        },
-        {
-          "description": "Start REPL in custom application scope",
-          "command": "<%= config.bin %> <%= command.id %> x_my_custom_app --auth dev-instance"
-        },
-        {
-          "description": "Execute a script file in global scope",
-          "command": "<%= config.bin %> <%= command.id %> global ./scripts/cleanup.js --auth dev-instance"
-        },
-        {
-          "description": "Execute a script file in a custom application scope",
-          "command": "<%= config.bin %> <%= command.id %> x_my_custom_app ./scripts/app-config.js --auth dev-instance"
-        },
-        {
-          "description": "Execute a parameterized script with single parameter",
-          "command": "<%= config.bin %> <%= command.id %> global ./scripts/query-user.js --auth dev-instance --params '{\"username\":\"admin\"}'"
-        },
-        {
-          "description": "Execute a parameterized script with multiple parameters",
-          "command": "<%= config.bin %> <%= command.id %> global ./scripts/update-record.js --auth dev-instance --params '{\"table\":\"incident\",\"field\":\"priority\",\"value\":\"1\"}'"
-        },
-        {
-          "description": "Execute and save output to a file",
-          "command": "<%= config.bin %> <%= command.id %> global ./scripts/report.js --auth dev-instance > report.txt"
-        },
-        {
-          "description": "Execute and pipe output to grep for filtering",
-          "command": "<%= config.bin %> <%= command.id %> global ./scripts/list-users.js --auth dev-instance | grep \"admin\""
-        },
-        {
-          "description": "Execute with debug logging to troubleshoot issues",
-          "command": "<%= config.bin %> <%= command.id %> global ./script.js --auth dev-instance --log-level debug"
-        },
-        {
-          "description": "Execute with parameters for template replacement",
-          "command": "<%= config.bin %> <%= command.id %> global ./script.js --auth dev-instance --params '{\"token\":\"abc123\",\"env\":\"dev\"}'"
-        }
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "auth": {
-          "char": "a",
-          "description": "Auth alias to use.",
-          "name": "auth",
-          "required": false,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "log-level": {
-          "helpGroup": "GLOBAL",
-          "name": "log-level",
-          "summary": "Specify level for logging.",
-          "default": "info",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "debug",
-            "warn",
-            "error",
-            "info",
-            "trace"
-          ],
-          "type": "option"
-        },
-        "params": {
-          "char": "p",
-          "description": "JSON object of parameters to replace in script file. Use {paramName} syntax in your script.",
-          "name": "params",
-          "required": false,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "exec",
-      "pluginAlias": "@sonisoft/now-sdk-ext-cli",
-      "pluginName": "@sonisoft/now-sdk-ext-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "autocomplete": {},
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "exec",
-        "index.js"
-      ]
-    },
     "flow:action": {
       "aliases": [],
       "args": {},
@@ -2257,7 +2140,7 @@
     "flow:run": {
       "aliases": [],
       "args": {},
-      "description": "Execute a Flow Designer flow by scoped name.\n\nRuns a flow using the sn_fd.FlowAPI ScriptableFlowRunner. Supports foreground (synchronous) and background (asynchronous) execution modes.\n\nFeatures:\n  • Execute flows by scoped name (e.g. global.my_flow)\n  • Pass input values as JSON\n  • Foreground or background execution mode\n  • Quick mode to skip execution detail records\n  • Returns context ID, outputs, and debug information",
+      "description": "Execute a published Flow Designer flow by scoped name.\n\nRuns a flow using the sn_fd.FlowAPI ScriptableFlowRunner. Supports foreground (synchronous) and background (asynchronous) execution modes.\n\nNote: This command requires the flow to be published. For testing flows that are not yet published (draft/saved state), use `flow test` instead.\n\nFeatures:\n  • Execute flows by scoped name (e.g. global.my_flow)\n  • Pass input values as JSON\n  • Foreground or background execution mode\n  • Quick mode to skip execution detail records\n  • Returns context ID, outputs, and debug information",
       "examples": [
         {
           "description": "Run a flow in foreground mode",
@@ -2451,7 +2334,7 @@
     "flow:subflow": {
       "aliases": [],
       "args": {},
-      "description": "Execute a Flow Designer subflow by scoped name.\n\nRuns a subflow using the sn_fd.FlowAPI ScriptableFlowRunner.\n\nFeatures:\n  • Execute subflows by scoped name\n  • Pass input values as JSON\n  • Foreground or background execution mode\n  • Returns context ID, outputs, and debug information",
+      "description": "Execute a published Flow Designer subflow by scoped name.\n\nRuns a subflow using the sn_fd.FlowAPI ScriptableFlowRunner.\n\nNote: This command requires the subflow to be published. For testing flows that are not yet published (draft/saved state), use `flow test` instead.\n\nFeatures:\n  • Execute subflows by scoped name\n  • Pass input values as JSON\n  • Foreground or background execution mode\n  • Returns context ID, outputs, and debug information",
       "examples": [
         {
           "description": "Run a subflow",
@@ -2560,6 +2443,225 @@
         "subflow.js"
       ]
     },
+    "flow:test": {
+      "aliases": [],
+      "args": {},
+      "description": "Test a Flow Designer flow without requiring it to be published.\n\nInvokes the same API as the \"Test\" button in Flow Designer, running the flow in its current saved (draft) state. Unlike `flow run` which requires a published flow and uses sn_fd.FlowAPI, `flow test` works on unpublished drafts via the ProcessFlow REST API.\n\nFeatures:\n  • Test flows by sys_id or scoped name\n  • Pass trigger output values as JSON via --output-map\n  • Auto-resolves scope from flow definition if not provided\n  • Synchronous or asynchronous execution",
+      "examples": [
+        {
+          "description": "Test a flow by sys_id",
+          "command": "<%= config.bin %> <%= command.id %> --flow-id 887dda5583237210fdb8f7b6feaad32c --output-map '{\"current\":\"0ecd7552db252200a6a2b31be0b8f5e6\",\"table_name\":\"change_request\"}' --auth dev"
+        },
+        {
+          "description": "Test a flow by scoped name with explicit scope",
+          "command": "<%= config.bin %> <%= command.id %> -f x_myapp.my_flow -o '{\"current\":\"abc123\",\"table_name\":\"incident\"}' --scope x_myapp --auth dev"
+        },
+        {
+          "description": "Test with JSON output",
+          "command": "<%= config.bin %> <%= command.id %> -f 887dda5583237210fdb8f7b6feaad32c -o '{\"current\":\"abc123\"}' --json --auth dev"
+        }
+      ],
+      "flags": {
+        "json": {
+          "char": "j",
+          "description": "Output results as JSON",
+          "name": "json",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "auth": {
+          "char": "a",
+          "description": "Auth alias to use.",
+          "name": "auth",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "log-level": {
+          "helpGroup": "GLOBAL",
+          "name": "log-level",
+          "summary": "Specify level for logging.",
+          "default": "info",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "debug",
+            "warn",
+            "error",
+            "info",
+            "trace"
+          ],
+          "type": "option"
+        },
+        "flow-id": {
+          "char": "f",
+          "description": "Flow sys_id or scoped name (e.g. x_myapp.my_flow)",
+          "name": "flow-id",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "output-map": {
+          "char": "o",
+          "description": "JSON mapping of trigger output variable names to test values (e.g. '{\"current\":\"<sys_id>\",\"table_name\":\"change_request\"}')",
+          "name": "output-map",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope": {
+          "description": "Scope sys_id for transaction scope (auto-resolved from flow definition if omitted)",
+          "name": "scope",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "synchronous": {
+          "description": "Run test synchronously (default: true)",
+          "name": "synchronous",
+          "required": false,
+          "allowNo": true,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "flow:test",
+      "pluginAlias": "@sonisoft/now-sdk-ext-cli",
+      "pluginName": "@sonisoft/now-sdk-ext-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "flow",
+        "test.js"
+      ]
+    },
+    "exec": {
+      "aliases": [],
+      "args": {
+        "scope": {
+          "description": "Scope to execute script in. Use \"global\" for global scope.",
+          "name": "scope",
+          "required": true
+        },
+        "file": {
+          "description": "File to execute in scripts background. If omitted, starts REPL mode.",
+          "name": "file",
+          "required": false
+        }
+      },
+      "description": "Execute JavaScript on a ServiceNow instance remotely using Scripts - Background.\n\nThis command allows you to run JavaScript either from files or interactively via REPL mode. It mimics the functionality of the Scripts - Background interface in ServiceNow, providing a way to execute scripts programmatically without manual interaction. The output is returned in real-time and can be piped to other commands or saved to files.\n\nModes:\n  • File Mode: Provide a file path to execute scripts from a file\n  • REPL Mode: Omit the file path to start an interactive session\n\nFeatures:\n  • Execute local JavaScript files remotely\n  • Interactive REPL for ad-hoc script execution\n  • Script parameterization with {placeholder} replacement\n  • Multi-line script support in REPL\n  • Scope-aware execution (global or custom scope)\n  • Real-time console output capture\n  • Pipe-able output for command chaining\n  • Debug logging support\n  • Useful for data migration, testing, and administrative tasks\n\nScript Parameterization:\n  Use {paramName} placeholders in your script files, then provide values via --params:\n  • Supports any JSON-serializable values (strings, numbers, booleans)\n  • Multiple parameters supported\n  • All occurrences of each placeholder are replaced\n  • Example: {token}, {username}, {environment}\n\nREPL Controls:\n  • Press Enter to add a new line\n  • Type .exec or press Ctrl+D to execute the script\n  • Type .clear to clear the current input\n  • Type .exit or press Ctrl+C twice to exit REPL\n\n⚠️  IMPORTANT SECURITY WARNING:\nThis command executes scripts with the same permissions and risks as using Scripts - Background directly\nin ServiceNow. Always:\n  • Review scripts before execution\n  • Test in non-production environments first\n  • Use appropriate scoping to limit access\n  • Be aware of data modification risks\n  • Follow your organization's security policies\n  • Never execute untrusted scripts\n\nScript Capabilities:\n  Scripts run with full GlideSystem API access and can:\n  • Query and modify database records\n  • Create, update, and delete data\n  • Execute business rules and workflows\n  • Access all APIs available in Scripts - Background\n  • Use gs, GlideRecord, GlideAggregate, and other server-side APIs",
+      "examples": [
+        {
+          "description": "Start REPL in global scope",
+          "command": "<%= config.bin %> <%= command.id %> global --auth dev-instance"
+        },
+        {
+          "description": "Start REPL in custom application scope",
+          "command": "<%= config.bin %> <%= command.id %> x_my_custom_app --auth dev-instance"
+        },
+        {
+          "description": "Execute a script file in global scope",
+          "command": "<%= config.bin %> <%= command.id %> global ./scripts/cleanup.js --auth dev-instance"
+        },
+        {
+          "description": "Execute a script file in a custom application scope",
+          "command": "<%= config.bin %> <%= command.id %> x_my_custom_app ./scripts/app-config.js --auth dev-instance"
+        },
+        {
+          "description": "Execute a parameterized script with single parameter",
+          "command": "<%= config.bin %> <%= command.id %> global ./scripts/query-user.js --auth dev-instance --params '{\"username\":\"admin\"}'"
+        },
+        {
+          "description": "Execute a parameterized script with multiple parameters",
+          "command": "<%= config.bin %> <%= command.id %> global ./scripts/update-record.js --auth dev-instance --params '{\"table\":\"incident\",\"field\":\"priority\",\"value\":\"1\"}'"
+        },
+        {
+          "description": "Execute and save output to a file",
+          "command": "<%= config.bin %> <%= command.id %> global ./scripts/report.js --auth dev-instance > report.txt"
+        },
+        {
+          "description": "Execute and pipe output to grep for filtering",
+          "command": "<%= config.bin %> <%= command.id %> global ./scripts/list-users.js --auth dev-instance | grep \"admin\""
+        },
+        {
+          "description": "Execute with debug logging to troubleshoot issues",
+          "command": "<%= config.bin %> <%= command.id %> global ./script.js --auth dev-instance --log-level debug"
+        },
+        {
+          "description": "Execute with parameters for template replacement",
+          "command": "<%= config.bin %> <%= command.id %> global ./script.js --auth dev-instance --params '{\"token\":\"abc123\",\"env\":\"dev\"}'"
+        }
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "auth": {
+          "char": "a",
+          "description": "Auth alias to use.",
+          "name": "auth",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "log-level": {
+          "helpGroup": "GLOBAL",
+          "name": "log-level",
+          "summary": "Specify level for logging.",
+          "default": "info",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "debug",
+            "warn",
+            "error",
+            "info",
+            "trace"
+          ],
+          "type": "option"
+        },
+        "params": {
+          "char": "p",
+          "description": "JSON object of parameters to replace in script file. Use {paramName} syntax in your script.",
+          "name": "params",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "exec",
+      "pluginAlias": "@sonisoft/now-sdk-ext-cli",
+      "pluginName": "@sonisoft/now-sdk-ext-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "autocomplete": {},
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "exec",
+        "index.js"
+      ]
+    },
     "health:check": {
       "aliases": [],
       "args": {},
@@ -6024,5 +6126,5 @@
       ]
     }
   },
-  "version": "2.0.1"
+  "version": "2.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonisoft/now-sdk-ext-cli",
   "description": "A CLI extending the functionality of the ServiceNow SDK.",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "author": "Chris Nanda",
   "bin": {
     "nex": "./bin/run.js"
@@ -17,7 +17,7 @@
     "@servicenow/sdk-cli": "4.3.0",
     "@servicenow/sdk-cli-core": "3.0.3",
     "@servicenow/sdk-core": "4.3.0",
-    "@sonisoft/now-sdk-ext-core": "^3.4.0",
+    "@sonisoft/now-sdk-ext-core": "^3.6.0",
     "@ts-morph/common": "^0.24.0",
     "chalk": "^4.1.2",
     "cometd": "^8.0.4",