@jacebenson/jsn 4.0.4 → 4.2.0

package/src/commands/codesearch.js

@@ -0,0 +1,103 @@
+// jsn codesearch — search across ServiceNow code artifacts (script includes,
+// business rules, client scripts, UI actions, ...) via the sn_codesearch
+// plugin REST API. Issue #180.
+
+import { errUsage } from '../errors.js';
+
+const DEFAULT_SEARCH_GROUP = 'sn_devstudio.Studio Search Group';
+
+// Flatten the API's nested shape into one row per record/field so the output
+// controller can render it as a table / CSV / JSON.
+//
+// API shape:
+//   result: [ { recordType, hits: [ { name, className, tableLabel,
+//     matches: [ { field, fieldLabel,
+//       lineMatches: [ { line, context, escaped } ] } ] } ] } ] }
+// NOTE: with ?table=<t> the API returns a single object, not an array.
+export function flattenHits(result) {
+  const groups = Array.isArray(result) ? result : (result ? [result] : []);
+  const rows = [];
+  for (const group of groups) {
+    for (const hit of group.hits || []) {
+      for (const match of hit.matches || []) {
+        const lines = (match.lineMatches || []).filter((lm) => lm.context);
+        rows.push({
+          table: hit.className || group.recordType,
+          name: hit.name,
+          field: match.field,
+          lines: lines.map((lm) => lm.line).join(','),
+          matches: lines.length,
+          context: lines[0]?.context?.trim() || '',
+          sys_id: hit.sys_id || hit.sysId || '',
+        });
+      }
+    }
+  }
+  return rows;
+}
+
+// Pre-rendered text view for styled/terminal output (output.js uses
+// data._formatted when present).
+function renderFormatted(rows, term) {
+  if (rows.length === 0) return `No code matches for "${term}".\n`;
+  const out = [];
+  for (const r of rows) {
+    out.push(`${r.table}  ${r.name}  .${r.field}  (lines ${r.lines})`);
+    if (r.context) out.push(`    ${r.context}`);
+  }
+  return out.join('\n') + '\n';
+}
+
+export function codesearchCmd(wrap) {
+  return {
+    command: 'codesearch [subcommand]',
+    aliases: ['codesearch'],
+    describe: 'Search code across ServiceNow artifacts (script includes, business rules, client scripts, ...)',
+    builder: (yargs) => yargs
+      .command({
+        command: 'search <term>',
+        describe: 'Search code for a term (e.g. "codesearch search GlideAjax")',
+        builder: (y) => y
+          .positional('term', { type: 'string', describe: 'Search term' })
+          .option('limit', { alias: 'l', type: 'number', default: 100, describe: 'Max results' })
+          .option('table', { alias: 't', type: 'string', describe: 'Restrict to one source table (e.g. sys_script_include)' })
+          .option('scope', { alias: 's', type: 'string', describe: 'Restrict to an app scope (e.g. x_my_app)' })
+          .option('search-group', { type: 'string', default: DEFAULT_SEARCH_GROUP, describe: 'Search group to use' })
+          .option('all-scopes', { type: 'boolean', default: true, describe: 'Search across all scopes (default true)' }),
+        handler: wrap(async (argv, app) => {
+          if (!argv.term || !argv.term.trim()) {
+            throw errUsage('A search term is required', 'Example: jsn codesearch search GlideAjax');
+          }
+
+          const params = new URLSearchParams();
+          params.set('term', argv.term);
+          params.set('limit', String(argv.limit));
+          params.set('search_group', argv.searchGroup);
+          params.set('search_all_scopes', String(argv.allScopes));
+          if (argv.table) params.set('table', argv.table);
+          if (argv.scope) params.set('scope', argv.scope);
+
+          const url = `${app.getEffectiveInstance()}/api/sn_codesearch/code_search/search?${params.toString()}`;
+          let payload;
+          try {
+            payload = await app.sdk.request(url);
+          } catch (err) {
+            if (err.code === 'api_error' && /404/.test(err.message)) {
+              err.message += '\n\nHint: the sn_codesearch plugin may not be active on this instance.';
+            }
+            throw err;
+          }
+
+          const result = payload?.result || [];
+          const rows = flattenHits(result);
+
+          app.ok(
+            { term: argv.term, count: rows.length, records: rows, _formatted: renderFormatted(rows, argv.term) },
+            { summary: `${rows.length} code match(es) for "${argv.term}"` },
+          );
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: search'),
+    handler: () => {},
+  };
+}

package/src/commands/dev/_generic.js

@@ -1,9 +1,10 @@
 // Generic dev subcommand builder for table-based CRUD
 
-import { formatRecordForDisplay, getStringField, isHexString, parseDataArg, confirmDelete, assertSafeExactMatch } from '../../helpers.js';
+import { formatRecordForDisplay, getStringField, parseDataArg, confirmDelete, interactiveList, canPrompt } from '../../helpers.js';
+import { resolveRecord, unwrapSysId } from '../../resolve-record.js';
 import { getCurrentUser, getCurrentApplication } from '../../context.js';
-import { paginatedSearch } from '../../paginated-search.js';
-import { isTTY, FormatAuto } from '../../output.js';
+import { FormatAuto } from '../../output.js';
+import { declareCapabilities } from '../../capabilities.js';
 
 function vowelArticle(word) {
   const first = word.charAt(0).toLowerCase();
@@ -75,10 +76,31 @@ async function resolveRecordScope(sdk, record) {
   }
 }
 
+/**
+ * Scope guard for update/delete on scoped tables: when scopeValidation is
+ * enabled and the record lives outside the current scope, refuse with a
+ * "switch scope first" error. Pass the resolved record straight through.
+ */
+async function guardScope(sdk, record) {
+  const recordScope = await resolveRecordScope(sdk, record);
+  const scopeErr = await checkScope(sdk, recordScope);
+  if (scopeErr) {
+    throw new Error(`record is in scope '${scopeErr.recordScope}', but your current scope is '${scopeErr.currentScope}'. Switch scope first: jsn scopes set ${scopeErr.recordScope}`);
+  }
+  return record;
+}
+
 export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {}) {
   const showFields = opts.showFields !== undefined ? opts.showFields : null;
   const singular = toSingular(name, opts.singular);
   const readOnly = opts.readOnly || false;
+  // Capability declaration: the readOnly flag drives the mutation registry.
+  // buildDevCmd commands are registered both at root and under `jsn dev`
+  // unless opts.devAlias says otherwise (root-only commands pass false).
+  declareCapabilities(name, {
+    mutationSubcommands: readOnly ? [] : ['create', 'update', 'delete'],
+    devAlias: opts.devAlias !== false,
+  });
   const scopeValidation = opts.scopeValidation || false;
   const extraQuery = opts.extraQuery || '';
   const showSummary = opts.showSummary || ((record, id) => `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${getStringField(record, 'name') || id}`);
@@ -111,66 +133,32 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           const limit = argv.limit;
 
           // Interactive picker with pagination
-          const interactive = isTTY(process.stdout) && isTTY(process.stdin);
-          if (interactive && app.output.getFormat() === FormatAuto && !query) {
-            // Get total count
-            let totalCount = 0;
-            try {
-              totalCount = await app.sdk.aggregateCount(table, extraQuery || '');
-            } catch { /* non-critical */ }
-
-            const source = async (term, offset, { signal: _signal } = {}) => {
-              const params = new URLSearchParams();
-              params.set('sysparm_limit', String(limit));
-              params.set('sysparm_display_value', 'all');
-              params.set('sysparm_fields', ['sys_id', 'name', 'sys_scope'].join(','));
-              if (term) {
-                params.set('sysparm_query', `nameLIKE${term}^ORDERBYDESCsys_updated_on`);
-              } else {
-                params.set('sysparm_query', (extraQuery ? extraQuery + '^' : '') + 'ORDERBYDESCsys_updated_on');
-                params.set('sysparm_offset', String(offset));
-              }
-              const records = await app.sdk.list(table, params);
-              return records.map(r => {
+          if (canPrompt() && app.output.getFormat() === FormatAuto && !query) {
+            const picked = await interactiveList({
+              app, table, singular, columns: ['name', 'sys_scope'], limit, query: extraQuery,
+              labelField: 'name',
+              message: `Select ${vowelArticle(singular)} ${singular}`,
+              formatLabel: (r) => {
                 const recordName = getStringField(r, 'name') || getStringField(r, 'sys_id');
                 const scope = getStringField(r, 'sys_scope') || '';
-                let label = recordName;
-                if (scope && scope !== 'global') label += ` [${scope}]`;
-                return { name: label, value: recordName };
-              });
-            };
-
-            const selectedName = await paginatedSearch({
-              message: `Select ${vowelArticle(singular)} ${singular}`,
-              pageSize: 10,
-              totalCount,
-              source,
+                return (scope && scope !== 'global') ? `${recordName} [${scope}]` : recordName;
+              },
             });
+            if (picked === undefined || picked === null) return; // cancelled, or table is empty
 
-            if (selectedName) {
-              const recordName = typeof selectedName === 'object' ? selectedName.value : selectedName;
-              assertSafeExactMatch(recordName);
-              const showParams = new URLSearchParams();
-              showParams.set('sysparm_query', `name=${recordName}`);
-              showParams.set('sysparm_display_value', 'all');
-              showParams.set('sysparm_limit', '1');
-              const showRecords = await app.sdk.list(table, showParams);
-              if (showRecords.length === 0) {
-                throw new Error(`${singular} not found: ${recordName}`);
-              }
-              const record = showRecords[0];
-              record._context = { instance_url: app.getEffectiveInstance(), table };
-              if (opts.onShow) {
-                await opts.onShow(record, app);
-              }
-              app.ok(record, {
-                summary: `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${recordName}`,
-                breadcrumbs: [
-                  ...(readOnly ? [] : [{ action: 'update', cmd: `jsn ${name} update ${recordName} --data '{...}'`, description: `Update this ${singular}` }]),
-                  { action: 'list', cmd: `jsn ${name} list`, description: `Back to all ${name}` },
-                ],
-              });
+            const record = picked;
+            const recordName = getStringField(record, 'name') || getStringField(record, 'sys_id');
+            record._context = { instance_url: app.getEffectiveInstance(), table };
+            if (opts.onShow) {
+              await opts.onShow(record, app);
             }
+            app.ok(record, {
+              summary: `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${recordName}`,
+              breadcrumbs: [
+                ...(readOnly ? [] : [{ action: 'update', cmd: `jsn ${name} update ${recordName} --data '{...}'`, description: `Update this ${singular}` }]),
+                { action: 'list', cmd: `jsn ${name} list`, description: `Back to all ${name}` },
+              ],
+            });
             return;
           }
 
@@ -201,34 +189,25 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         describe: `Show ${vowelArticle(singular)} ${singular} by name or sys_id`,
         handler: wrap(async (argv, app) => {
           const id = argv.identifier;
-          const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
-          assertSafeExactMatch(id);
-          const params = new URLSearchParams();
-          params.set('sysparm_query', `${queryField}=${id}`);
-          params.set('sysparm_limit', '1');
-          params.set('sysparm_display_value', 'all');
           // Only restrict sysparm_fields if showFields is explicitly set.
           // Go version fetches all fields for show unless explicitly restricted.
-          if (showFields && showFields.length > 0) {
-            params.set('sysparm_fields', [...new Set(['sys_id', ...showFields])].join(','));
-          }
-          const records = await app.sdk.list(table, params);
-          if (records.length === 0) {
-            throw new Error(`${singular} not found: ${id}`);
-          }
-          records[0]._context = {
+          const fields = (showFields && showFields.length > 0)
+            ? [...new Set(['sys_id', ...showFields])]
+            : undefined;
+          const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular, fields });
+          record._context = {
             instance_url: app.getEffectiveInstance(),
             table,
           };
 
           if (opts.onShow) {
-            await opts.onShow(records[0], app);
+            await opts.onShow(record, app);
           }
 
-          const summary = typeof showSummary === 'function' ? showSummary(records[0], id) : showSummary;
-          const breadcrumbs = typeof showBreadcrumbs === 'function' ? showBreadcrumbs(records[0], id) : showBreadcrumbs;
+          const summary = typeof showSummary === 'function' ? showSummary(record, id) : showSummary;
+          const breadcrumbs = typeof showBreadcrumbs === 'function' ? showBreadcrumbs(record, id) : showBreadcrumbs;
 
-          app.ok(records[0], { summary, breadcrumbs });
+          app.ok(record, { summary, breadcrumbs });
         }),
       });
 
@@ -259,26 +238,12 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
-            assertSafeExactMatch(id);
-            const findParams = new URLSearchParams();
-            findParams.set('sysparm_query', `${queryField}=${id}`);
-            findParams.set('sysparm_limit', '1');
-            findParams.set('sysparm_display_value', 'all');
-            const records = await app.sdk.list(table, findParams);
-            if (records.length === 0) {
-              throw new Error(`${singular} not found: ${id}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
-            const recordScope = await resolveRecordScope(app.sdk, records[0]);
-
+            const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular });
             if (scopeValidation) {
-              const scopeErr = await checkScope(app.sdk, recordScope);
-              if (scopeErr) {
-                throw new Error(`record is in scope '${scopeErr.recordScope}', but your current scope is '${scopeErr.currentScope}'. Switch scope first: jsn scopes set ${scopeErr.recordScope}`);
-              }
+              await guardScope(app.sdk, record);
             }
 
+            const sysID = unwrapSysId(record);
             const recordData = parseDataArg(argv);
             const updated = await app.sdk.update(table, sysID, recordData);
             app.ok(updated, { summary: `Updated ${singular} ${id}` });
@@ -290,27 +255,14 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           builder: (y) => y.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
-            assertSafeExactMatch(id);
-            const findParams = new URLSearchParams();
-            findParams.set('sysparm_query', `${queryField}=${id}`);
-            findParams.set('sysparm_limit', '1');
-            findParams.set('sysparm_display_value', 'all');
-            const records = await app.sdk.list(table, findParams);
-            if (records.length === 0) {
-              throw new Error(`${singular} not found: ${id}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
-            const recordName = getStringField(records[0], 'name') || id;
-            const recordScope = await resolveRecordScope(app.sdk, records[0]);
-
+            const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular });
             if (scopeValidation) {
-              const scopeErr = await checkScope(app.sdk, recordScope);
-              if (scopeErr) {
-                throw new Error(`record is in scope '${scopeErr.recordScope}', but your current scope is '${scopeErr.currentScope}'. Switch scope first: jsn scopes set ${scopeErr.recordScope}`);
-              }
+              await guardScope(app.sdk, record);
             }
 
+            const sysID = unwrapSysId(record);
+            const recordName = getStringField(record, 'name') || id;
+
             await confirmDelete(app, argv, `Delete ${singular} '${recordName}'`);
 
             await app.sdk.delete(table, sysID);

package/src/commands/dev/_simple.js

@@ -56,7 +56,12 @@ export const clientScriptsCmd = (wrap) => buildDevCmd('clientscripts', 'sys_scri
 
 export const uiActionsCmd = (wrap) => buildDevCmd('uiactions', 'sys_ui_action', ['uiaction', 'ua'], ['name', 'table', 'active', 'order', 'sys_scope'], wrap, { singular: 'UI action', scopeValidation: true });
 
-export const uiPoliciesCmd = (wrap) => buildDevCmd('uipolicies', 'sys_ui_policy', ['uipolicy', 'up'], ['short_description', 'table', 'active', 'order', 'sys_scope'], wrap, { singular: 'UI policy', scopeValidation: true });
+// NOTE: uipolicies has exactly ONE definition — the rich one in
+// ./uipolicies.js (re-exported below at the bottom of this file). A plain
+// buildDevCmd('uipolicies', ...) factory used to live here, but yargs keeps
+// the LAST registration of a duplicate command name, and cli.js registers
+// this module's uiPoliciesCmd before uipoliciesCmd — so the factory version
+// was dead code shadowing nothing. Deleted; the re-export is the behavior.
 
 export const tablesCmd = (wrap) => buildDevCmd('tables', 'sys_db_object', ['table', 't'], ['name', 'label', 'super_class', 'create_access_controls'], wrap, {
   singular: 'table',
@@ -98,28 +103,27 @@ export { aliasesCmd } from './aliases.js';
 export const catalogscriptsCmd = (wrap) => buildDevCmd('catalogscripts', 'catalog_script_client', ['catalogscript', 'cs'], ['name', 'table', 'active', 'sys_scope'], wrap, { singular: 'catalog script', scopeValidation: true });
 
 // ── Automation: Async ──
-export const scriptactionsCmd = (wrap) => buildDevCmd('scriptactions', 'sysevent_script_action', ['scriptaction'], ['name', 'active', 'sys_scope'], wrap, { singular: 'script action', scopeValidation: true });
-export const scheduledjobsCmd = (wrap) => buildDevCmd('scheduledjobs', 'sysauto_script', ['scheduledjob'], ['name', 'active', 'run_type', 'sys_scope'], wrap, { singular: 'scheduled job', scopeValidation: true });
-export const asyncrulesCmd = (wrap) => buildDevCmd('asyncrules', 'sys_script', ['asyncrule'], ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, { singular: 'async business rule', scopeValidation: true, extraQuery: 'when=async' });
-export const triggersCmd = (wrap) => buildDevCmd('triggers', 'sysevent_register', ['trigger'], ['name', 'event_name', 'active', 'sys_scope'], wrap, { singular: 'event trigger', scopeValidation: true });
+export const scriptactionsCmd = (wrap) => buildDevCmd('scriptactions', 'sysevent_script_action', ['scriptaction'], ['name', 'active', 'sys_scope'], wrap, { singular: 'script action', scopeValidation: true, devAlias: false });
+export const scheduledjobsCmd = (wrap) => buildDevCmd('scheduledjobs', 'sysauto_script', ['scheduledjob'], ['name', 'active', 'run_type', 'sys_scope'], wrap, { singular: 'scheduled job', scopeValidation: true, devAlias: false });
+export const asyncrulesCmd = (wrap) => buildDevCmd('asyncrules', 'sys_script', ['asyncrule'], ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, { singular: 'async business rule', scopeValidation: true, extraQuery: 'when=async', devAlias: false });
+export const triggersCmd = (wrap) => buildDevCmd('triggers', 'sysevent_register', ['trigger'], ['name', 'event_name', 'active', 'sys_scope'], wrap, { singular: 'event trigger', scopeValidation: true, devAlias: false });
 
 // ── Automation: In Memory ──
-export const decisiontablesCmd = (wrap) => buildDevCmd('decisiontables', 'sys_ws_definition', ['decisiontable'], ['name', 'active', 'sys_scope'], wrap, { singular: 'decision table', scopeValidation: true, readOnly: true });
-export const assignmentsCmd = (wrap) => buildDevCmd('assignments', 'sysrule_assignment', ['assignment'], ['name', 'active', 'sys_scope'], wrap, { singular: 'assignment rule', scopeValidation: true, readOnly: true });
+export const decisiontablesCmd = (wrap) => buildDevCmd('decisiontables', 'sys_ws_definition', ['decisiontable'], ['name', 'active', 'sys_scope'], wrap, { singular: 'decision table', scopeValidation: true, readOnly: true, devAlias: false });
+export const assignmentsCmd = (wrap) => buildDevCmd('assignments', 'sysrule_assignment', ['assignment'], ['name', 'active', 'sys_scope'], wrap, { singular: 'assignment rule', scopeValidation: true, readOnly: true, devAlias: false });
 
 // ── Automation: Inbound ──
-export const emailCmd = (wrap) => buildDevCmd('email', 'sysevent_in_email_action', ['emails'], ['name', 'active', 'type', 'sys_scope'], wrap, { singular: 'inbound email action', scopeValidation: true });
+export const emailCmd = (wrap) => buildDevCmd('email', 'sysevent_in_email_action', ['emails'], ['name', 'active', 'type', 'sys_scope'], wrap, { singular: 'inbound email action', scopeValidation: true, devAlias: false });
 
 // ── Automation: Outbound ──
 export { restmessageCmd } from './restmessage.js';
-export const restmethodsCmd = (wrap) => buildDevCmd('restmethods', 'sys_rest_message_fn', ['restmethod'], ['name', 'http_method', 'active', 'sys_scope'], wrap, { singular: 'REST method', scopeValidation: true });
 export { soapmessagesCmd } from './soapmessages.js';
 
 // ── UX: Core UI ──
-export const uimacrosCmd = (wrap) => buildDevCmd('uimacros', 'sys_ui_macro', ['uimacro'], ['name', 'active', 'sys_scope'], wrap, { singular: 'UI macro', scopeValidation: true });
+export const uimacrosCmd = (wrap) => buildDevCmd('uimacros', 'sys_ui_macro', ['uimacro'], ['name', 'active', 'sys_scope'], wrap, { singular: 'UI macro', scopeValidation: true, devAlias: false });
 
 // ── UX: Workspaces ──
-export const uxlistsCmd = (wrap) => buildDevCmd('uxlists', 'sys_ux_list', ['uxlist'], ['name', 'active', 'sys_scope'], wrap, { singular: 'workspace list', scopeValidation: true, readOnly: true });
-export const uxapplicabilityCmd = (wrap) => buildDevCmd('uxapplicability', 'sys_ux_applicability_m2m', ['uxapp'], ['name', 'active', 'sys_scope'], wrap, { singular: 'workspace applicability', scopeValidation: true, readOnly: true });
+export const uxlistsCmd = (wrap) => buildDevCmd('uxlists', 'sys_ux_list', ['uxlist'], ['name', 'active', 'sys_scope'], wrap, { singular: 'workspace list', scopeValidation: true, readOnly: true, devAlias: false });
+export const uxapplicabilityCmd = (wrap) => buildDevCmd('uxapplicability', 'sys_ux_applicability_m2m', ['uxapp'], ['name', 'active', 'sys_scope'], wrap, { singular: 'workspace applicability', scopeValidation: true, readOnly: true, devAlias: false });
 export { uipoliciesCmd } from './uipolicies.js';
 export const cataloguipoliciesCmd = (wrap) => buildDevCmd('cataloguipolicies', 'catalog_ui_policy', ['cataloguipolicy', 'cup'], ['short_description', 'catalog_item', 'variable_set', 'active', 'sys_scope'], wrap, { singular: 'catalog UI policy', scopeValidation: true });

package/src/commands/dev/b4rules.js

@@ -2,4 +2,4 @@ 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' });
+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', devAlias: false });

package/src/commands/dev/domains.js

@@ -11,6 +11,10 @@
 // to its own picker sessions.
 
 import { getStringField, interactiveList, assertSafeExactMatch } from '../../helpers.js';
+import { declareCapabilities } from '../../capabilities.js';
+
+// `domains set` writes the chosen domain into the profile config.
+declareCapabilities('domains', { mutationSubcommands: ['set'], devAlias: true });
 
 const DETAIL_FIELDS = 'sys_id,name,parent,sys_domain_path,description,active,sys_created_on,sys_updated_on';
 

package/src/commands/dev/eval.js

@@ -1,4 +1,10 @@
 import fs from 'node:fs';
+import { getCurrentUser, getCurrentApplication } from '../../context.js';
+import { declareCapabilities } from '../../capabilities.js';
+
+// The whole command is a mutation surface (runs arbitrary server-side JS) —
+// declared as `['']` so both `jsn eval` and `jsn dev eval` are gated.
+declareCapabilities('eval', { mutationSubcommands: [''], devAlias: true });
 
 export function evalCmd(wrap) {
   return {
@@ -6,27 +12,71 @@ export function evalCmd(wrap) {
     describe: 'Execute background scripts on the instance',
     builder: (yargs) => {
       return yargs
-        .option('script', { alias: 's', type: 'string', describe: "JavaScript code to execute (single-quote the script, double quotes inside: --script 'gs.log(\"Hello\")')" })
+        .option('script', { alias: 's', type: 'string', describe: 'JavaScript code to execute (single-quote the script, double quotes inside: --script \'gs.log("Hello")\')' })
         .option('file', { alias: 'f', type: 'string', describe: 'Read script from file (avoids shell quoting issues)' })
-        .option('scope', { alias: null, type: 'string', describe: 'Scope name or sys_id to run the script under (default: global)' });
+        .option('stdin', { type: 'boolean', describe: 'Read script from stdin (pipe-friendly, e.g. cat script.js | jsn eval --stdin)' })
+        .option('scope', { alias: null, type: 'string', describe: 'Scope name or sys_id to run the script under (default: active scope from banner)' })
+        // Script-mode flags (issue #177) — map to the Script Background form checkboxes
+        .option('rollback', { type: 'boolean', default: true, describe: 'Record rollback context (--no-rollback to skip)' })
+        .option('sandbox', { type: 'boolean', default: false, describe: 'Sandbox mode (KittyScript evaluator, single expression only — no DB writes)' })
+        .option('scriptlet', { type: 'boolean', default: false, describe: 'Run as scriptlet with global server-side objects' })
+        .option('quota-managed-transaction', { type: 'boolean', default: true, describe: 'Managed transaction limits (--no-quota-managed-transaction to skip)' });
     },
     handler: wrap(async (argv, app) => {
       let script;
       let scopeSysId = null;
 
-      if (argv.scope) {
-        scopeSysId = await app.sdk.resolveScope(argv.scope);
+      // Resolve execution scope: explicit --scope wins; otherwise use the
+      // active scope from apps.current_app (same source as the banner);
+      // fall back to global only when no active scope exists.
+      let scope = argv.scope || '';
+      if (!scope) {
+        try {
+          const user = await getCurrentUser(app.sdk);
+          if (user && user.sys_id) {
+            const currentApp = await getCurrentApplication(app.sdk, user.sys_id);
+            if (currentApp && currentApp.scope && currentApp.scope !== 'global') {
+              scope = currentApp.scope;
+            }
+          }
+        } catch {
+          // ignore — fall back to global
+        }
+      }
+
+      if (scope) {
+        scopeSysId = await app.sdk.resolveScope(scope);
         if (!scopeSysId) {
-          throw new Error(`Scope not found: ${argv.scope}`);
+          throw new Error(`Scope not found: ${scope}`);
         }
       }
 
       if (argv.file) {
         script = fs.readFileSync(argv.file, 'utf-8');
+      } else if (argv.stdin) {
+        script = await new Promise((resolve, reject) => {
+          let data = '';
+          process.stdin.setEncoding('utf-8');
+          process.stdin.on('data', (chunk) => { data += chunk; });
+          process.stdin.on('end', () => resolve(data));
+          process.stdin.on('error', reject);
+        });
       } else if (argv.script) {
         script = argv.script;
       } else {
-        throw new Error('--script or --file is required');
+        throw new Error('--script, --file, or --stdin is required');
+      }
+
+      // Sandbox mode uses the KittyScript evaluator, which only accepts a
+      // single expression — multi-statement scripts fail server-side. Warn
+      // early, on the user's raw script (before the $scopeSysId prepend).
+      if (argv.sandbox) {
+        const statements = script.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('//'));
+        const multiLine = statements.length > 1;
+        const hasTerminator = /;[\s\S]*\S/.test(script);
+        if (multiLine || hasTerminator) {
+          process.stderr.write('Warning: --sandbox runs a single expression (KittyScript). Multi-statement scripts will fail.\n\n');
+        }
       }
 
       if (scopeSysId) {
@@ -36,10 +86,18 @@ export function evalCmd(wrap) {
       const warning = scopeSysId
         ? ` ⚠️ Records without explicit sys_scope will land in global. Use $scopeSysId variable.`
         : '';
-      const output = await app.sdk.executeScript(script, argv.scope);
+      // Pass the resolved sys_id (not the name) — sys.scripts.do only
+      // honors selectable scope values, which are sys_ids.
+      const output = await app.sdk.executeScript(script, scopeSysId || '', {
+        rollback: argv.rollback,
+        quotaManagedTransaction: argv.quotaManagedTransaction,
+        sandbox: argv.sandbox,
+        scriptlet: argv.scriptlet,
+      });
       app.ok({
         script,
         output,
+        scope: scope || 'global',
         instance: app.getEffectiveInstance(),
       }, {
         summary: 'Script executed' + warning,

package/src/commands/dev/flows.js

@@ -1,4 +1,7 @@
 import { formatRecordForDisplay, getStringField, interactiveList } from '../../helpers.js';
+import { declareCapabilities } from '../../capabilities.js';
+
+declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'delete'], devAlias: true });
 
 export function flowsCmd(wrap) {
   return {