@jacebenson/jsn 4.3.13-dev.87.1 → 4.3.13-dev.88.1

package/package.json

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

package/src/commands/_generic.js

@@ -1,3 +1,4 @@
+import { constrainQuery, constrainedQueryHelp } from '../constrained-query.js';
 import { enrichRelatedLists, relatedListOptions } from '../related-lists.js';
 // Generic table-based CRUD command builder
 
@@ -122,19 +123,24 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         command: 'list',
         aliases: ['ls'],
         describe: `List ${name}`,
-        builder: (y) => recordOptions(y)
-          .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true^priority=1")' })
-          .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "name,label,super_class")' })
-          .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
+        builder: (y) => {
+          const command = recordOptions(y)
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true^priority=1")' })
+            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "name,label,super_class")' })
+            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' });
+          const help = [opts.help, extraQuery ? constrainedQueryHelp(extraQuery) : ''].filter(Boolean).join('\n');
+          return help ? command.epilogue(help) : command;
+        },
         handler: wrap(async (argv, app) => {
           const query = argv.query || '';
+          const constrainedQuery = constrainQuery(query, extraQuery);
           const columns = argv.columns ? argv.columns.split(',') : defaultColumns;
           const limit = argv.limit;
 
           // Interactive picker with pagination
           if (canPrompt() && app.output.getFormat() === FormatAuto && !query) {
             const picked = await interactiveList({
-              app, table, singular, columns: ['name', 'sys_scope'], limit, query: extraQuery,
+              app, table, singular, columns: ['name', 'sys_scope'], limit, query: constrainedQuery,
               labelField: 'name',
               message: `Select ${vowelArticle(singular)} ${singular}`,
               formatLabel: (r) => {
@@ -162,8 +168,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           }
 
           // Non-interactive: text/table output
-          const baseQ = extraQuery ? extraQuery + '^' : '';
-          const q = query ? query + '^ORDERBYDESCsys_updated_on' : (baseQ + 'ORDERBYDESCsys_updated_on');
+          const q = `${constrainedQuery}${constrainedQuery ? '^' : ''}ORDERBYDESCsys_updated_on`;
           const params = recordListParams({ limit, fields: ['sys_id', ...columns], query: q });
           const records = await listRecords(app.sdk, { table, params, displayValues: argv.displayValues ?? opts.referenceMode });
           app.ok({
@@ -277,13 +282,14 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         });
     }
 
-    return y;
+    const help = [opts.help, extraQuery ? constrainedQueryHelp(extraQuery) : ''].filter(Boolean).join('\n');
+    return help ? y.epilogue(help) : y;
   };
 
   return {
     command: `${name} [subcommand]`,
     aliases: aliases || [],
-    describe: `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
+    describe: opts.describe || `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
     discovery: {
       table,
       defaultColumns,

package/src/commands/b4rules.js

@@ -1,5 +1,10 @@
 import { buildDevCmd } from './_generic.js';
 
-// Before-query business rules — applies filters to GlideRecord queries before they execute.
-// These are sys_script records with order < 100.
-export const b4rulesCmd = (wrap) => buildDevCmd('b4rules', 'sys_script', ['b4rule'], ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, { singular: 'before-query business rule', scopeValidation: true, extraQuery: 'when=before' });
+// Query rules are explicitly marked; their order is not a classification rule.
+export const b4rulesCmd = wrap => buildDevCmd('b4rules', 'sys_script', ['b4rule'],
+  ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, {
+    singular: 'before-query business rule', scopeValidation: true,
+    extraQuery: 'when=before^action_query=true',
+    describe: 'Inspect before-query business rules that can filter record reads',
+    help: 'Before-query business rules use when=before and the Boolean action_query=true. Filter collection and active status for the affected table. For field behavior, see jsn columns --help; do not bypass server rules or ACLs.',
+  });

package/src/commands/columns.js

@@ -1,9 +1,10 @@
+import { fieldBehaviorHelp } from '../field-behavior.js';
 import { buildDevCmd } from './_generic.js';
 
 export const columnsCmd = (wrap) => {
   const base = buildDevCmd('columns', 'sys_dictionary', ['column', 'col'],
     ['element', 'column_label', 'internal_type', 'mandatory', 'max_length', 'active'],
-    wrap, { singular: 'column', scopeValidation: true });
+    wrap, { singular: 'column', scopeValidation: true, help: fieldBehaviorHelp });
 
   // Add --table filter
   const origBuilder = base.builder;

package/src/constrained-query.js

@@ -0,0 +1,20 @@
+import { errUsageHint } from './errors.js';
+
+/** Constrained table views accept literal AND filters. Encoded queries have no
+ * portable parenthesization; OR/NQ/dynamic clauses must not escape fixed filters. */
+export function constrainQuery(query = '', constraint = '') {
+  if (!constraint) return query;
+  const clauses = String(query).split('^').filter((clause, index, values) => clause !== 'EQ' || index !== values.length - 1);
+  if (!query) return constraint;
+  const literal = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*(?:(?:!=|>=|<=|=|>|<|NOT LIKE|STARTSWITH|ENDSWITH|LIKE|NOT IN|IN)[^^]*|ISEMPTY|ISNOTEMPTY)$/;
+  const ordering = /^ORDERBY(?:DESC)?[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*$/;
+  const allowed = clause => ordering.test(clause) || (literal.test(clause)
+    && (!/^(?:NQ|OR)/i.test(clause) || /^order(?:!=|>=|<=|=|>|<|NOT LIKE|STARTSWITH|ENDSWITH|LIKE|NOT IN|IN|ISEMPTY|ISNOTEMPTY)/.test(clause)));
+  if (/javascript\s*:/i.test(query) || clauses.some(clause => !allowed(clause))) {
+    throw errUsageHint('This constrained command accepts literal AND filters and ORDERBY only; OR, NQ and dynamic query clauses are unsupported.',
+      `The fixed filter is ${constraint}. Use literal AND clauses, or explicitly use records list for advanced queries and retain the intended constraints in every branch.`);
+  }
+  return clauses.length ? `${constraint}^${clauses.join('^')}` : constraint;
+}
+
+export const constrainedQueryHelp = constraint => `Always includes: ${constraint}. Additional --query filters use literal AND clauses (plus ORDERBY). OR, NQ and dynamic query clauses are rejected before requests so they cannot bypass this view's fixed filter.`;

package/src/field-behavior.js

@@ -0,0 +1,15 @@
+// Schema-backed investigation paths; no universal priority order is assumed.
+export const fieldBehaviorHelp = [
+  'Investigate the observed symptom; there is no fixed priority order for every field problem.',
+  'Query filtering: jsn b4rules list --query "collection=incident^active=true" --json',
+  'Before-query rules use sys_script.when=before and the Boolean action_query=true.',
+  'Dictionary entry: jsn records list --table sys_dictionary --query "name=incident^element=caller_id" --json',
+  'Inherited dictionary overrides: jsn records list --table sys_dictionary_override --query "name=incident^element=caller_id" --json',
+  'Inspect base_table and inherited tables as needed; the dictionary entry is separate from its overrides.',
+  'Access controls: jsn acls list --query "nameINincident,incident.*,incident.caller_id,*.caller_id,*,*.*" --json',
+  'Also inspect inherited-table and wildcard ACLs. Exact name=incident alone omits field/wildcard rules.',
+  'ACL rows are evidence, not proof of effective access: operation, roles, conditions and scripts matter.',
+  'Form behavior: jsn clientscripts list --query "table=incident^active=true" --json',
+  'Form policies: jsn uipolicies list --query "table=incident^active=true" --json',
+  'Use the command help and show output to inspect the relevant records. Never bypass a business rule, ACL or other protection to make a symptom disappear.',
+].join('\n');

package/src/record-command-profiles.js

@@ -18,7 +18,7 @@ export default {
   appmenu: { table: 'sys_app_application', aliases: ['app-menu', 'menu'], columns: ['name', 'active', 'sys_scope'],
     options: { singular: 'application menu', scopeValidation: true } },
   acls: { table: 'sys_security_acl', aliases: ['acl'], columns: ['name', 'operation', 'type', 'active', 'sys_scope'],
-    options: { singular: 'ACL', scopeValidation: true } },
+    options: { singular: 'ACL', scopeValidation: true, help: 'Investigate table, field, wildcard and inherited ACL names for the relevant operation. Exact name=incident alone does not cover incident.caller_id, incident.*, *.caller_id or inherited-table ACLs. Roles, conditions and scripts affect effective access; rows alone do not prove access. See jsn columns --help for field investigation paths.' } },
   roles: { table: 'sys_user_role', aliases: ['role', 'r'], columns: ['name', 'description', 'elevated_privilege', 'sys_scope'],
     options: { singular: 'role', scopeValidation: true } },
   properties: { table: 'sys_properties', aliases: ['property', 'prop'], columns: ['name', 'value', 'description', 'sys_scope'],