@aifabrix/builder 2.54.1 → 2.55.2

package/lib/commands/role-assistant-copy.js

@@ -0,0 +1,155 @@
+/**
+ * aifabrix role-assistant copy — capture one Work Hub execution as YAML.
+ *
+ * @fileoverview Leaf command; Builder materializes the case from Work Hub reference
+ */
+
+'use strict';
+
+const { resolveLifecycleAuth } = require('./lifecycle-external');
+const { fetchWorkCopyReference, buildCopyCaseFromWorkReference } = require(
+  '../role-assistant/test-case-copy-from-work'
+);
+const { roleAssistantSystemKey } = require('../utils/role-assistant-paths');
+const { roleAssistantTestsDir } = require('../role-assistant/test-cases');
+const {
+  defaultCaseIdFromReference,
+  assertProcessExecutionId,
+  assertFolderToken,
+  copyTargetPath,
+  prepareCopyDocument,
+  yamlFromValidatedCase,
+  assertCopyTargetWritable,
+  persistCopyCaseYaml
+} = require('../role-assistant/test-case-copy');
+const { emitCopySuccess, emitCopyFailure } = require('./role-assistant-copy-output');
+
+function copyHelpAfter() {
+  return `
+Examples:
+  $ aifabrix role-assistant copy customer-support-bot --suite 001 --reference a9f09fb8-d9eb-477f-8bb4-59e670fc82a4
+  $ aifabrix role-assistant copy customer-support-bot --suite 001 --reference a9f09fb8-d9eb-477f-8bb4-59e670fc82a4 --case address-change
+  $ aifabrix role-assistant copy customer-support-bot --suite 001 --reference a9f09fb8-d9eb-477f-8bb4-59e670fc82a4 --dry-run
+  $ aifabrix role-assistant copy customer-support-bot --suite 001 --reference a9f09fb8-d9eb-477f-8bb4-59e670fc82a4 --json
+
+Notes:
+  - <roleKey> is bare; package folder is role-assistant/ra-<roleKey>/.
+  - --reference is the Work Hub execution id (the same id printed after a run).
+  - Writes tests/<suite>/<caseId>.yaml. Default caseId is copy-<first 8 hex of the execution id>.
+  - Existing files are not overwritten unless --force is set.
+  - --dry-run prints YAML and does not write.
+  - Builds local YAML from Work Hub execution status and result. Does not publish; use upload / deploy.
+`;
+}
+
+function normalizeCopyOptions(options) {
+  const opts = options && typeof options === 'object' ? options : {};
+  return {
+    env: opts.env || 'dev',
+    suite: opts.suite,
+    reference: opts.reference,
+    case: opts.case,
+    force: opts.force === true,
+    dryRun: opts.dryRun === true,
+    json: opts.json === true,
+    testsDir: opts.testsDir || null
+  };
+}
+
+function requireCopyFlags(opts) {
+  if (!opts.suite) {
+    throw new Error('--suite is required');
+  }
+  if (!opts.reference) {
+    throw new Error('--reference is required');
+  }
+}
+
+async function fetchCopyCase(systemKey, opts, peId, caseId) {
+  const auth = await resolveLifecycleAuth(systemKey, {
+    env: opts.env,
+    run: false,
+    noPublish: true
+  });
+  if (!auth || !auth.dataplaneUrl || !auth.authConfig) {
+    throw new Error('Not authenticated. Run aifabrix login, then retry.');
+  }
+  const reference = await fetchWorkCopyReference(
+    auth.dataplaneUrl,
+    auth.authConfig,
+    peId
+  );
+  return buildCopyCaseFromWorkReference({
+    systemKey,
+    caseId,
+    processExecutionId: peId,
+    status: reference.status,
+    result: reference.result
+  });
+}
+
+async function runRoleAssistantCopy(roleKey, options) {
+  const opts = normalizeCopyOptions(options);
+  requireCopyFlags(opts);
+  const peId = assertProcessExecutionId(opts.reference);
+  const suiteId = assertFolderToken(opts.suite, 'Suite id');
+  const caseId = assertFolderToken(
+    opts.case || defaultCaseIdFromReference(peId),
+    'Case id'
+  );
+  const systemKey = roleAssistantSystemKey(roleKey);
+  const testsDir = roleAssistantTestsDir(systemKey, { testsDir: opts.testsDir });
+  const targetPath = copyTargetPath(testsDir, suiteId, caseId);
+  if (!opts.dryRun) {
+    assertCopyTargetWritable(targetPath, opts.force);
+  }
+  const payload = await fetchCopyCase(systemKey, opts, peId, caseId);
+  const caseDoc = prepareCopyDocument(payload, caseId, peId);
+  const yamlText = yamlFromValidatedCase(caseDoc);
+  if (!opts.dryRun) {
+    persistCopyCaseYaml(targetPath, yamlText);
+  }
+  return {
+    success: true,
+    path: targetPath,
+    caseId,
+    suiteId,
+    processExecutionId: peId,
+    warnings: payload && payload.warnings,
+    yaml: yamlText,
+    dryRun: opts.dryRun
+  };
+}
+
+async function roleAssistantCopyHandler(roleKey, options) {
+  try {
+    const result = await runRoleAssistantCopy(roleKey, options);
+    emitCopySuccess(options, result);
+  } catch (error) {
+    emitCopyFailure(options, error);
+    process.exit(error && error.exitCode ? error.exitCode : 1);
+  }
+}
+
+function registerRoleAssistantCopyCommand(roleAssistant) {
+  roleAssistant
+    .command('copy <roleKey>')
+    .description('Capture one Work Hub execution as a local YAML test case')
+    .requiredOption('--suite <suiteId>', 'Suite folder under tests/ (for example 001)')
+    .requiredOption('--reference <executionId>', 'Work Hub execution id')
+    .option('--case <caseId>', 'Case id (default: copy-<first 8 hex of the execution id>)')
+    .option('--force', 'Overwrite an existing YAML file')
+    .option('--dry-run', 'Print YAML and do not write')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('--json', 'Machine-readable output envelope')
+    .addHelpText('after', copyHelpAfter())
+    .action((roleKey, options) => roleAssistantCopyHandler(roleKey, options));
+}
+
+module.exports = {
+  copyHelpAfter,
+  normalizeCopyOptions,
+  runRoleAssistantCopy,
+  roleAssistantCopyHandler,
+  registerRoleAssistantCopyCommand
+};

package/lib/commands/role-assistant-test-output.js

@@ -16,6 +16,7 @@ const {
   formatBlockingError,
   metadata
 } = require('../utils/cli-test-layout-chalk');
+const { formatCaseResultRows } = require('./role-assistant-test-result-rows');
 
 /**
  * Bucket a lifecycle step status into ok | failed | skipped | other.
@@ -157,15 +158,12 @@ function displayCaseResultSummary(caseResult) {
   }
   if (caseResult.passed) {
     logger.log(formatSuccessLine('Case assertions passed.'));
-    const warnings = Array.isArray(caseResult.warnings) ? caseResult.warnings : [];
-    for (const row of warnings) {
-      logger.log(formatWarningLine(row.message || String(row)));
-    }
-    return;
+  } else {
+    logger.log(formatBlockingError('Case assertions failed.'));
   }
-  logger.log(formatBlockingError('Case assertions failed.'));
-  for (const row of caseResult.failedAssertions) {
-    logger.log(formatWarningLine(row.message));
+  logger.log(metadata('Results:'));
+  for (const line of formatCaseResultRows(caseResult.assertions)) {
+    logger.log(line);
   }
 }
 
@@ -210,5 +208,6 @@ function displayRoleAssistantTestSummary(roleKey, verdict, portalUrl, result, ca
 module.exports = {
   formatStepsRunSummary,
   buildRoleAssistantTestEnvelope,
-  displayRoleAssistantTestSummary
+  displayRoleAssistantTestSummary,
+  formatCaseResultRows
 };

package/lib/commands/role-assistant-test-result-rows.js

@@ -0,0 +1,42 @@
+/**
+ * Human TTY lines for Role Assistant case assertion rows.
+ * @fileoverview Canonical glyphs for pass/fail/warn/notes/skip
+ */
+
+'use strict';
+
+const {
+  formatSuccessLine,
+  formatWarningLine,
+  formatBlockingError,
+  infoLine,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
+const { withKind } = require('../role-assistant/test-case-assertion-row');
+
+function formatCaseResultLine(assertion) {
+  const row = withKind(assertion || {});
+  const text = `${row.id || 'assertion'} — ${row.message || ''}`.trim();
+  if (row.kind === 'fail') {
+    return `  ${formatBlockingError(text)}`;
+  }
+  if (row.kind === 'warn') {
+    return `  ${formatWarningLine(text)}`;
+  }
+  if (row.kind === 'notes') {
+    return `  ${infoLine(`ℹ ${text}`)}`;
+  }
+  if (row.kind === 'skip') {
+    return `  ${metadata(`⏭ ${text}`)}`;
+  }
+  return `  ${formatSuccessLine(text)}`;
+}
+
+function formatCaseResultRows(assertions) {
+  return (Array.isArray(assertions) ? assertions : []).map(formatCaseResultLine);
+}
+
+module.exports = {
+  formatCaseResultLine,
+  formatCaseResultRows
+};

package/lib/commands/role-assistant.js

@@ -35,6 +35,11 @@ const {
   lifecycleVerdictFromCaseExecution
 } = require('../role-assistant/test-runner');
 const { assertRoleAssistantEvidencePreflight } = require('../role-assistant/test-cases-evidence');
+const { assertLocalCasesBeforeAuth } = require('../role-assistant/test-case-validate');
+const {
+  loadPublishedTestsIntoOptions,
+  patchCaseStatusAfterRun
+} = require('../role-assistant/test-pack-sync');
 const { collectString } = require('./governance');
 const {
   sectionTitle,
@@ -50,27 +55,33 @@ const {
   bareRoleKey,
   roleAssistantSystemKey
 } = require('../utils/role-assistant-paths');
+const { registerRoleAssistantCopyCommand } = require('./role-assistant-copy');
 
 function roleAssistantGroupHelpAfter() {
   return `
 Subcommands:
   test <roleKey>   Run lifecycle checks, optional YAML cases/suites, and print a portal deep link
+  copy <roleKey>   Capture one Work Hub execution as a local YAML test case
 
 Package workspace (top-level commands — same digital-worker package):
-  download / validate / upload / deploy <roleKey>   Manage role-assistant/ra-<roleKey>/
+  download / validate / upload ra-<roleKey>   Manage role-assistant/ra-<roleKey>/
+  upload publishes settings and sidecars; operator Make available is a separate action
 
 Examples:
   $ aifabrix role-assistant test customer-support-bot
   $ aifabrix role-assistant test customer-support-bot --suite 001
   $ aifabrix role-assistant test customer-support-bot --list-cases
   $ aifabrix role-assistant test customer-support-bot --env tst --json
-  $ aifabrix upload customer-support-bot --env dev
+  $ aifabrix role-assistant copy customer-support-bot --suite 001 --reference a9f09fb8-d9eb-477f-8bb4-59e670fc82a4
+  $ aifabrix upload ra-customer-support-bot --env dev
   $ aifabrix test ra-customer-support-bot
 
 Notes:
-  - Local packages live under role-assistant/ra-<roleKey>/ (bare <roleKey> in CLI args).
+  - role-assistant test/copy use bare <roleKey>; top-level package commands use ra-<roleKey>.
   - test uses the public/running worker by default; pass --publish (or upload) to refresh from local files.
+  - copy writes tests/<suite>/<caseId>.yaml from a Work Hub execution id; it does not publish.
   - See: aifabrix role-assistant test -h
+  - See: aifabrix role-assistant copy -h
 `;
 }
 
@@ -84,6 +95,7 @@ Examples:
   $ aifabrix role-assistant test customer-support-bot --suite 001
   $ aifabrix role-assistant test customer-support-bot --list-cases
   $ aifabrix role-assistant test customer-support-bot --suite 001 --fail-fast --json
+  $ aifabrix role-assistant test customer-support-bot --from-dataplane
   $ aifabrix test ra-customer-support-bot
 
 Notes:
@@ -93,6 +105,8 @@ Notes:
   - Runs lifecycle checks, then prints a portal deep link for full step-by-step status.
   - Case files with input.message/input.content execute Work Hub plan→accept (or work.start when executionPath: intent).
   - Cases with executionPath: search|skills (input.executionPath or case-root executionPath) run work.skills / work.search instead of Work Hub.
+  - After each case, current status is stored on the published test pack (passed, failed, or skipped).
+  - --from-dataplane loads published tests, then runs them (all suites unless --case / --suite is set).
   - Role Assistant packages do not need application.yaml; test uses device login and the published dataplane worker.
   - Cases with preflight.evidence.requiredKeys read live Evidence from the dataplane before start and hard-stop if those keys are missing or not active.
   - answers[] and approvals[] are matched to runtime wait payloads (questionKey/requestKey/waitReason).
@@ -138,6 +152,7 @@ function normalizeRoleAssistantTestOptions(options, cmd) {
     casesRoot: trimOptionalString(options.casesRoot),
     listCases: optionOrFlag(options, 'listCases', cmd, '--list-cases'),
     failFast: optionOrFlag(options, 'failFast', cmd, '--fail-fast'),
+    fromDataplane: optionOrFlag(options, 'fromDataplane', cmd, '--from-dataplane'),
     run: true
   };
 }
@@ -220,45 +235,91 @@ async function resolveSuiteCaseResults(systemKey, opts, result, verdict, portalU
   return outcomes;
 }
 
+async function maybeLoadFromDataplane(systemKey, opts) {
+  if (!opts.fromDataplane) {
+    return opts;
+  }
+  const auth = await resolveLifecycleAuth(systemKey, { ...opts, run: false, noPublish: true });
+  return loadPublishedTestsIntoOptions(systemKey, opts, auth);
+}
+
+async function resolveSelectedCaseResults(systemKey, opts, result, verdict, portalUrl) {
+  const runDiscovered = Boolean(opts.suite || (opts.fromDataplane && !opts.case));
+  if (runDiscovered) {
+    return resolveSuiteCaseResults(systemKey, opts, result, verdict, portalUrl);
+  }
+  return resolveRoleAssistantCaseResult(systemKey, opts, result, verdict, portalUrl);
+}
+
 async function runRoleAssistantTestAction(roleKey, options, cmd) {
-  const opts = normalizeRoleAssistantTestOptions(options, cmd);
+  let opts = normalizeRoleAssistantTestOptions(options, cmd);
   const systemKey = roleAssistantSystemKey(roleKey);
   const displayKey = bareRoleKey(roleKey);
+  opts = await maybeLoadFromDataplane(systemKey, opts);
 
   if (opts.listCases) {
     return listRoleAssistantCases(systemKey, opts);
   }
 
+  assertLocalCasesBeforeAuth(systemKey, opts);
+
   const result = await runLifecycleForExternalSystem(systemKey, opts);
   const verdict = lifecycleVerdictFromReport(result.report || {});
   const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, systemKey);
+  const caseResult = await resolveSelectedCaseResults(systemKey, opts, result, verdict, portalUrl);
 
-  let caseResult = null;
-  if (opts.suite) {
-    caseResult = await resolveSuiteCaseResults(systemKey, opts, result, verdict, portalUrl);
-  } else {
-    caseResult = await resolveRoleAssistantCaseResult(systemKey, opts, result, verdict, portalUrl);
-  }
+  const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
 
   if (opts.json) {
-    logger.log(
-      JSON.stringify(
-        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult),
-        null,
-        2
-      )
+    // Large piped stdout writes on Linux are non-blocking; exiting right
+    // after console.log() can truncate the JSON before the OS write
+    // completes. Wait for the write to flush before exiting non-zero.
+    const payload = JSON.stringify(
+      logger.sanitizeValue(
+        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult)
+      ),
+      null,
+      2
     );
-  } else {
-    displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
+    return new Promise((resolve) => {
+      process.stdout.write(`${payload}\n`, () => {
+        if (exitCode !== 0) {
+          process.exit(exitCode);
+        }
+        resolve(exitCode);
+      });
+    });
   }
 
-  const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
+  displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
   if (exitCode !== 0) {
     process.exit(exitCode);
   }
   return exitCode;
 }
 
+async function patchPublishedCaseStatus(roleKey, opts, roleCase, evaluation, authContext) {
+  const caseId = roleCase && roleCase.caseId;
+  if (!caseId) {
+    return evaluation;
+  }
+  let auth = authContext;
+  if (!auth || !auth.dataplaneUrl || !auth.authConfig) {
+    auth = await resolveLifecycleAuth(roleKey, { ...opts, run: false, noPublish: true });
+  }
+  if (!auth || !auth.dataplaneUrl || !auth.authConfig) {
+    return evaluation;
+  }
+  await patchCaseStatusAfterRun({
+    systemKey: roleAssistantSystemKey(roleKey),
+    caseId,
+    evaluation,
+    dataplaneUrl: auth.dataplaneUrl,
+    authConfig: auth.authConfig
+  });
+  return evaluation;
+}
+
 function attachCaseExecution(evaluation, executionResult, error) {
   const errMsg = error && (error.message || String(error));
   evaluation.execution = {
@@ -298,32 +359,35 @@ async function resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, po
   const roleCase = loadRoleAssistantTestCase(roleKey, opts.case, {
     testsDir: opts.testsDir || null
   });
+  let evaluation;
   if (!isExecutableRoleAssistantCase(roleCase)) {
-    return evaluateRoleAssistantTestCase(roleCase, result, verdict, portalUrl);
-  }
-  try {
-    return await resolveExecutableCaseResult(
-      roleKey,
-      roleCase,
-      opts,
-      result,
-      verdict,
-      portalUrl
-    );
-  } catch (error) {
-    const failedInput = mergeCaseExecutionIntoLifecycleResult(result, {
-      finalStatus: { status: 'failed' },
-      workResult: null,
-      workResultError: error.message || String(error),
-      interactions: []
-    });
-    failedInput.workResultError = error.message || String(error);
-    return attachCaseExecution(
-      evaluateRoleAssistantTestCase(roleCase, failedInput, verdict, portalUrl),
-      null,
-      error
-    );
+    evaluation = evaluateRoleAssistantTestCase(roleCase, result, verdict, portalUrl);
+  } else {
+    try {
+      evaluation = await resolveExecutableCaseResult(
+        roleKey,
+        roleCase,
+        opts,
+        result,
+        verdict,
+        portalUrl
+      );
+    } catch (error) {
+      const failedInput = mergeCaseExecutionIntoLifecycleResult(result, {
+        finalStatus: { status: 'failed' },
+        workResult: null,
+        workResultError: error.message || String(error),
+        interactions: []
+      });
+      failedInput.workResultError = error.message || String(error);
+      evaluation = attachCaseExecution(
+        evaluateRoleAssistantTestCase(roleCase, failedInput, verdict, portalUrl),
+        null,
+        error
+      );
+    }
   }
+  return patchPublishedCaseStatus(roleKey, opts, roleCase, evaluation);
 }
 
 async function roleAssistantTestHandler(roleKey, options, cmd) {
@@ -335,19 +399,8 @@ async function roleAssistantTestHandler(roleKey, options, cmd) {
   }
 }
 
-function setupRoleAssistantCommands(program) {
-  const roleAssistant = program
-    .command('role-assistant')
-    .description(
-      'Role Assistant packages: lifecycle checks, YAML cases/suites, and portal deep links'
-    )
-    .addHelpText('after', roleAssistantGroupHelpAfter());
-
-  roleAssistant
-    .command('test <roleKey>')
-    .description(
-      'Lifecycle checks + optional cases/suites; prints portal deep link (bare <roleKey>)'
-    )
+function addRoleAssistantTestRunOptions(cmd) {
+  return cmd
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('--case <caseIdOrPath>', 'Run and evaluate one role-assistant test case')
     .option('--tests-dir <dir>', 'Override role-assistant test case directory')
@@ -361,8 +414,16 @@ function setupRoleAssistantCommands(program) {
     )
     .option('--list-cases', 'List discoverable case files and exit')
     .option('--fail-fast', 'Stop suite run after the first failing case')
+    .option(
+      '--from-dataplane',
+      'Load published tests from the dataplane, then run them (all suites unless --case or --suite is set)'
+    )
     .option('-v, --verbose', 'Include full lifecycle report payload in --json output')
-    .option('-d, --debug', 'Write debug logs under role-assistant/<roleKey>/logs/')
+    .option('-d, --debug', 'Write debug logs under role-assistant/<roleKey>/logs/');
+}
+
+function addRoleAssistantTestPublishOptions(cmd) {
+  return cmd
     .option(
       '--publish',
       'Publish local Role Assistant package before checks (default: use public/running worker)'
@@ -385,9 +446,29 @@ function setupRoleAssistantCommands(program) {
       'Ignored for Role Assistant packages (Connected System governance generate does not run)',
       'bronze'
     )
-    .option('--json', 'Machine-readable output envelope')
+    .option('--json', 'Machine-readable output envelope');
+}
+
+function registerRoleAssistantTestCommand(roleAssistant) {
+  const cmd = roleAssistant
+    .command('test <roleKey>')
+    .description(
+      'Lifecycle checks + optional cases/suites; prints portal deep link (bare <roleKey>)'
+    );
+  addRoleAssistantTestPublishOptions(addRoleAssistantTestRunOptions(cmd))
     .addHelpText('after', roleAssistantHelpAfter())
-    .action((roleKey, options, cmd) => roleAssistantTestHandler(roleKey, options, cmd));
+    .action((roleKey, options, invoked) => roleAssistantTestHandler(roleKey, options, invoked));
+}
+
+function setupRoleAssistantCommands(program) {
+  const roleAssistant = program
+    .command('role-assistant')
+    .description(
+      'Role Assistant packages: lifecycle checks, YAML cases/suites, copy from Work Hub, and portal deep links'
+    )
+    .addHelpText('after', roleAssistantGroupHelpAfter());
+  registerRoleAssistantTestCommand(roleAssistant);
+  registerRoleAssistantCopyCommand(roleAssistant);
 }
 
 module.exports = {

package/lib/commands/search.js

@@ -0,0 +1,143 @@
+/**
+ * aifabrix search — retrieve governed Role Assistant information.
+ *
+ * @fileoverview Commander registration for search and search skills
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { runSearch, runSearchSkills } = require('../search/search-run');
+const { exitCodeForSearchError } = require('../search/search-errors');
+const { emitSearchError } = require('../search/search-display');
+
+const SEARCH_HELP = `
+
+Examples:
+  $ aifabrix search
+  $ aifabrix search --role ra-cfo --resource-type customer
+  $ aifabrix search --role ra-cfo --resource-type customer --operation list --json
+  $ aifabrix search --role ra-cfo --resource-type customer --output ./search.json
+  $ aifabrix search skills --role ra-cfo
+`;
+
+const SKILLS_HELP = `
+
+Examples:
+  $ aifabrix search skills
+  $ aifabrix search skills --role ra-cfo
+  $ aifabrix search skills --role ra-cfo --json
+  $ aifabrix search skills --role ra-cfo --output ./skills.json
+`;
+
+/**
+ * @param {*} value
+ * @param {string[]} previous
+ * @returns {string[]}
+ */
+function collectKnowledgeKey(value, previous) {
+  const next = Array.isArray(previous) ? previous : [];
+  next.push(value);
+  return next;
+}
+
+/**
+ * @param {import('commander').Command} cmd
+ */
+function addSharedSearchOptions(cmd) {
+  cmd
+    .option('--role <roleRef>', 'Role Assistant key (for example ra-cfo)')
+    .option('--role-ref <roleRef>', 'Alias for --role')
+    .option('-o, --output <file>', 'Write the JSON payload to this file')
+    .option('--no-interactive', 'Never prompt; missing required flags fail')
+    .option('-e, --env <environment>', 'Environment key')
+    .option('--json', 'Print the JSON payload on stdout (no prompts)')
+    .option('-v, --verbose', 'Include extra TTY detail when available');
+}
+
+/**
+ * @param {import('commander').Command} cmd
+ */
+function addSearchBodyOptions(cmd) {
+  cmd
+    .option('--resource-type <key>', 'Resource type published on that Role Assistant')
+    .option('--type <key>', 'Alias for --resource-type')
+    .option('--operation <key>', 'Named operation for that resource type')
+    .option('--filters <json>', 'JSON object of field filters')
+    .option('--filters-file <path>', 'JSON object of field filters from a file')
+    .option('--page <n>', 'Page number (integer ≥ 1)')
+    .option('--page-size <n>', 'Page size (integer 1–100)')
+    .option('--sort <spec>', 'Sort specification (pass-through)')
+    .option('--fields <csv>', 'Comma-separated field names')
+    .option('--graph', 'Include one-level related records')
+    .option('--query <text>', 'Semantic hop text when --graph is set')
+    .option('--knowledge-key <key>', 'Knowledge key (repeatable)', collectKnowledgeKey, [])
+    .option('--body <file>', 'JSON request body file (merged after flags)');
+}
+
+/**
+ * @param {Function} action
+ * @param {Object} options
+ * @returns {Promise<void>}
+ */
+async function dispatchSearchLeaf(action, options) {
+  try {
+    const code = await action(options);
+    if (code && code !== 0) {
+      process.exit(code);
+    }
+  } catch (err) {
+    const message = err.message || String(err);
+    emitSearchError(options, message, logger);
+    process.exit(exitCodeForSearchError(err));
+  }
+}
+
+/**
+ * @param {Object} options
+ * @param {import('commander').Command} command
+ * @returns {Object}
+ */
+function mergeCommandOptions(options, command) {
+  const parentOpts =
+    command && command.parent && typeof command.parent.opts === 'function'
+      ? command.parent.opts()
+      : {};
+  return { ...parentOpts, ...options };
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupSearchCommands(program) {
+  const search = program
+    .command('search')
+    .description('Search governed information for a Role Assistant assigned to you')
+    .addHelpText('after', SEARCH_HELP);
+  addSharedSearchOptions(search);
+  addSearchBodyOptions(search);
+
+  const searchRun = search
+    .command('run', { isDefault: true, hidden: true })
+    .description('Search governed information for a Role Assistant assigned to you')
+    .addHelpText('after', SEARCH_HELP);
+  searchRun.action(async(options, command) => {
+    await dispatchSearchLeaf(runSearch, mergeCommandOptions(options, command));
+  });
+
+  const skills = search
+    .command('skills')
+    .description('List searchable resource types and operations for a Role Assistant')
+    .addHelpText('after', SKILLS_HELP);
+  addSharedSearchOptions(skills);
+  skills.action(async(options, command) => {
+    await dispatchSearchLeaf(runSearchSkills, mergeCommandOptions(options, command));
+  });
+}
+
+module.exports = {
+  setupSearchCommands,
+  collectKnowledgeKey
+};