@aifabrix/builder 2.54.1 → 2.55.2

package/lib/search/search-run.js

@@ -0,0 +1,241 @@
+/**
+ * Orchestrate aifabrix search and aifabrix search skills.
+ *
+ * @fileoverview Search command run path (retrieve only)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const logger = require('../utils/logger');
+const { getWorkRoles, getWorkSkills, searchWork } = require('../api/work-search.api');
+const { resolveSearchDataplaneContext } = require('./dataplane-context');
+const { SearchCliError, authRequiredError } = require('./search-errors');
+const { buildSearchBody, roleRefFromOptions, resourceTypeFromOptions } = require('./search-args');
+const {
+  skillsEnvelope,
+  resourceTypesMap,
+  typeSpec,
+  isOperationRequired,
+  assertTypePublished,
+  assertOperationPublished
+} = require('./search-skills');
+const {
+  isInteractive,
+  missingFlagsError,
+  promptRoleAssistant,
+  promptResourceType,
+  promptOperation
+} = require('./search-prompts');
+const { emitSearchSuccess, emitSkillsSuccess } = require('./search-display');
+
+/**
+ * @param {Object} [overrides]
+ * @returns {Object}
+ */
+function defaultDeps(overrides = {}) {
+  return {
+    resolveContext: resolveSearchDataplaneContext,
+    getWorkRoles,
+    getWorkSkills,
+    searchWork,
+    prompt: (qs) => require('inquirer').prompt(qs),
+    logger,
+    isTty: () => Boolean(process.stdin && process.stdin.isTTY),
+    fsApi: fs,
+    ...overrides
+  };
+}
+
+/**
+ * @param {Object} options
+ * @param {Function} resolveContext
+ * @returns {Promise<Object>}
+ */
+async function resolveContextOrThrow(options, resolveContext) {
+  try {
+    return await resolveContext(options);
+  } catch (err) {
+    const message = err.message || String(err);
+    if (/login|auth|token|controller url/i.test(message)) {
+      throw authRequiredError(message);
+    }
+    throw new SearchCliError(message);
+  }
+}
+
+/**
+ * @param {Object} options
+ */
+function assertScriptSearchFlags(options) {
+  const missing = [];
+  if (!roleRefFromOptions(options)) missing.push('--role');
+  if (!resourceTypeFromOptions(options)) missing.push('--resource-type');
+  if (missing.length) {
+    throw missingFlagsError(missing);
+  }
+}
+
+/**
+ * @param {Object} res
+ * @param {string} fallback
+ * @returns {Object}
+ */
+function payloadOrThrow(res, fallback) {
+  if (res && Number(res.status) === 200) {
+    const payload = skillsEnvelope(res.payload);
+    return payload && typeof payload === 'object' ? payload : {};
+  }
+  const text = String((res && res.errorText) || '').trim() || fallback;
+  throw new SearchCliError(text);
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} ctx
+ * @param {Object} deps
+ * @returns {Promise<string>}
+ */
+async function resolveRoleRef(options, ctx, deps) {
+  const existing = roleRefFromOptions(options);
+  if (existing) {
+    return existing;
+  }
+  return promptRoleAssistant(ctx, deps);
+}
+
+/**
+ * @param {string} explicitType
+ * @param {string[]} typeKeys
+ * @param {Object} typeMap
+ * @param {boolean} interactive
+ * @param {Object} deps
+ * @returns {Promise<string>}
+ */
+async function resolveResourceType(explicitType, typeKeys, typeMap, interactive, deps) {
+  if (!typeKeys.length) {
+    throw new SearchCliError('No searchable resource types for this Role Assistant.');
+  }
+  if (explicitType) {
+    assertTypePublished(explicitType, typeMap);
+    return explicitType;
+  }
+  if (!interactive) {
+    throw missingFlagsError(['--resource-type']);
+  }
+  return promptResourceType(typeKeys, deps);
+}
+
+/**
+ * @param {string} explicitOp
+ * @param {Object} spec
+ * @param {boolean} interactive
+ * @param {Object} deps
+ * @returns {Promise<string>}
+ */
+async function resolveOperation(explicitOp, spec, interactive, deps) {
+  if (explicitOp) {
+    assertOperationPublished(explicitOp, spec);
+    return explicitOp;
+  }
+  if (isOperationRequired(spec) && !interactive) {
+    throw new SearchCliError(
+      'Operation is required for this resource type. Pass --operation.'
+    );
+  }
+  if (!interactive) {
+    return '';
+  }
+  return promptOperation(spec, deps);
+}
+
+/**
+ * @param {Object} body
+ * @param {Object} skillsPayload
+ * @param {Object} options
+ * @param {Object} deps
+ * @returns {Promise<Object>}
+ */
+async function fillTypeAndOperation(body, skillsPayload, options, deps) {
+  const typeMap = resourceTypesMap(skillsPayload);
+  const typeKeys = Object.keys(typeMap);
+  const interactive = isInteractive(options, deps.isTty);
+  const resourceType = await resolveResourceType(
+    body.resourceType || '',
+    typeKeys,
+    typeMap,
+    interactive,
+    deps
+  );
+  body.resourceType = resourceType;
+  const spec = typeSpec(typeMap, resourceType);
+  const operation = await resolveOperation(body.operation || '', spec, interactive, deps);
+  if (operation) {
+    body.operation = operation;
+  } else {
+    delete body.operation;
+  }
+  if (isOperationRequired(spec) && !body.operation) {
+    throw new SearchCliError(
+      'Operation is required for this resource type. Pass --operation.'
+    );
+  }
+  return body;
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} [depOverrides]
+ * @returns {Promise<number>}
+ */
+async function runSearch(options, depOverrides) {
+  const deps = defaultDeps(depOverrides);
+  const body = buildSearchBody(options, deps.fsApi);
+  const interactive = isInteractive(options, deps.isTty);
+  if (!interactive) {
+    assertScriptSearchFlags(options);
+  }
+  const ctx = await resolveContextOrThrow(options, deps.resolveContext);
+  if (!body.roleRef) {
+    body.roleRef = await resolveRoleRef(options, ctx, deps);
+  }
+  const skillsRes = await deps.getWorkSkills(ctx.dataplaneUrl, ctx.authConfig, body.roleRef);
+  const skillsPayload = payloadOrThrow(skillsRes, 'Unable to load search skills.');
+  await fillTypeAndOperation(body, skillsPayload, options, deps);
+  const searchRes = await deps.searchWork(ctx.dataplaneUrl, ctx.authConfig, body);
+  const payload = payloadOrThrow(searchRes, 'Search request failed.');
+  emitSearchSuccess(options, body, payload, deps.logger, deps.fsApi);
+  return 0;
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} [depOverrides]
+ * @returns {Promise<number>}
+ */
+async function runSearchSkills(options, depOverrides) {
+  const deps = defaultDeps(depOverrides);
+  const interactive = isInteractive(options, deps.isTty);
+  if (!interactive && !roleRefFromOptions(options)) {
+    throw missingFlagsError(['--role']);
+  }
+  const ctx = await resolveContextOrThrow(options, deps.resolveContext);
+  const roleRef = await resolveRoleRef(options, ctx, deps);
+  const skillsRes = await deps.getWorkSkills(ctx.dataplaneUrl, ctx.authConfig, roleRef);
+  const payload = payloadOrThrow(skillsRes, 'Unable to load search skills.');
+  if (!payload.roleRef) {
+    payload.roleRef = roleRef;
+  }
+  emitSkillsSuccess(options, payload, deps.logger, deps.fsApi);
+  return 0;
+}
+
+module.exports = {
+  defaultDeps,
+  runSearch,
+  runSearchSkills,
+  fillTypeAndOperation,
+  resolveRoleRef
+};

package/lib/search/search-skills.js

@@ -0,0 +1,198 @@
+/**
+ * YAML-free copies of work.skills helpers (do not import the test runner).
+ *
+ * @fileoverview Resource type / operation keys from a skills payload
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { SearchCliError } = require('./search-errors');
+
+/** Table retrieve keys stamped by the search grammar (list/search page, get one). */
+const RETRIEVE_TABLE_KEYS = new Set(['list', 'get', 'search']);
+
+/**
+ * @param {*} item
+ * @returns {string}
+ */
+function operationKeyFromItem(item) {
+  if (typeof item === 'string' && item.trim()) {
+    return item.trim();
+  }
+  if (item && typeof item === 'object') {
+    return String(item.key || '').trim();
+  }
+  return '';
+}
+
+/**
+ * @param {*} item
+ * @returns {boolean}
+ */
+function hasResultMode(item) {
+  return Boolean(item && typeof item === 'object' && String(item.resultMode || '').trim());
+}
+
+/**
+ * Retrieve/analyze only. Write-shaped keys stay off search.
+ * Keep table retrieve keys (list/get/search) and named views (source viewpoint).
+ *
+ * @param {*} item
+ * @param {boolean} grammarPresent
+ * @param {boolean} tableRetrievePresent
+ * @returns {boolean}
+ */
+function isRetrieveOperation(item, grammarPresent, tableRetrievePresent) {
+  const key = operationKeyFromItem(item);
+  if (!key) {
+    return false;
+  }
+  if (RETRIEVE_TABLE_KEYS.has(key)) {
+    return true;
+  }
+  if (typeof item === 'string') {
+    return !tableRetrievePresent;
+  }
+  const source = String((item && item.source) || '')
+    .trim()
+    .toLowerCase();
+  if (source === 'viewpoint') {
+    return true;
+  }
+  if (!source && !grammarPresent && !tableRetrievePresent) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {Object|null|undefined} spec
+ * @returns {*[]}
+ */
+function operationItems(spec) {
+  return Array.isArray(spec && spec.operations) ? spec.operations : [];
+}
+
+/**
+ * @param {Object|null|undefined} spec
+ * @returns {string[]}
+ */
+function operationKeys(spec) {
+  const raw = operationItems(spec);
+  const grammarPresent = raw.some(hasResultMode);
+  const tableRetrievePresent = raw.some((item) =>
+    RETRIEVE_TABLE_KEYS.has(operationKeyFromItem(item))
+  );
+  const keys = [];
+  for (const item of raw) {
+    if (!isRetrieveOperation(item, grammarPresent, tableRetrievePresent)) {
+      continue;
+    }
+    const key = operationKeyFromItem(item);
+    if (key) {
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * @param {Object|null|undefined} spec
+ * @returns {string[]}
+ */
+function allOperationKeys(spec) {
+  return operationItems(spec).map(operationKeyFromItem).filter(Boolean);
+}
+
+/**
+ * work.skills is an object. MCP execute may wrap it as a one-element array.
+ * @param {*} skillsPayload
+ * @returns {Object|null}
+ */
+function skillsEnvelope(skillsPayload) {
+  let cur = skillsPayload;
+  if (Array.isArray(cur) && cur.length === 1 && cur[0] && typeof cur[0] === 'object') {
+    cur = cur[0];
+  }
+  if (!cur || typeof cur !== 'object' || Array.isArray(cur)) {
+    return null;
+  }
+  if (cur.search && typeof cur.search === 'object') {
+    return cur;
+  }
+  if (cur.data && typeof cur.data === 'object' && !Array.isArray(cur.data) && cur.data.search) {
+    return cur.data;
+  }
+  return cur;
+}
+
+/**
+ * @param {Object|null|undefined} skillsPayload
+ * @returns {Object}
+ */
+function resourceTypesMap(skillsPayload) {
+  const root = skillsEnvelope(skillsPayload);
+  const rts = root && root.search && root.search.resourceTypes;
+  return rts && typeof rts === 'object' && !Array.isArray(rts) ? rts : {};
+}
+
+/**
+ * @param {Object} typeMap
+ * @param {string} resourceType
+ * @returns {Object}
+ */
+function typeSpec(typeMap, resourceType) {
+  const spec = typeMap && typeMap[resourceType];
+  return spec && typeof spec === 'object' ? spec : {};
+}
+
+/**
+ * @param {Object} spec
+ * @returns {boolean}
+ */
+function isOperationRequired(spec) {
+  return spec && spec.operationRequired === true;
+}
+
+/**
+ * @param {string} resourceType
+ * @param {Object} typeMap
+ */
+function assertTypePublished(resourceType, typeMap) {
+  if (!Object.prototype.hasOwnProperty.call(typeMap, resourceType)) {
+    throw new SearchCliError(
+      `Resource type "${resourceType}" is not published for this Role Assistant.`
+    );
+  }
+}
+
+/**
+ * @param {string} operation
+ * @param {Object} spec
+ */
+function assertOperationPublished(operation, spec) {
+  const keys = operationKeys(spec);
+  if (keys.includes(operation)) {
+    return;
+  }
+  if (allOperationKeys(spec).includes(operation)) {
+    throw new SearchCliError(
+      `Operation "${operation}" is not a retrieve operation for this resource type.`
+    );
+  }
+  throw new SearchCliError(
+    `Operation "${operation}" is not published for this resource type.`
+  );
+}
+
+module.exports = {
+  operationKeys,
+  skillsEnvelope,
+  resourceTypesMap,
+  typeSpec,
+  isOperationRequired,
+  assertTypePublished,
+  assertOperationPublished
+};

package/lib/utils/api-required-permissions.js

@@ -0,0 +1,271 @@
+/**
+ * Resolve required RBAC scopes for online API calls.
+ *
+ * Catalog is built from `@requiresPermission` plus the HTTP path in `lib/api/*.api.js`.
+ * Used when a 403 body does not list missing/required permissions.
+ *
+ * @fileoverview Fallback required-permission lookup for 403 errors
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fsRealSync = require('../internal/fs-real-sync');
+const path = require('path');
+
+const SCOPE_IN_TEXT_RE = /\b[a-z][a-z0-9_-]*:[a-z][a-z0-9_-]*(?::[a-z][a-z0-9_-]*)*\b/gi;
+const SKIP_SCOPE_SCHEMES = new Set(['http', 'https', 'mailto', 'ws', 'wss']);
+
+/** @type {Array<{ method: string, regex: RegExp, service: string, permissions: string[] }>|null} */
+let cachedCatalog = null;
+
+/**
+ * CLI command name (handleCommandError second arg) → required permission fallback.
+ * URL catalog is preferred; this is used when the 403 has no request URL.
+ */
+const COMMAND_REQUIRED_PERMISSIONS = Object.freeze({
+  deploy: { service: 'Controller', permissions: ['applications:deploy'] },
+  'env deploy': { service: 'Controller', permissions: ['controller:deploy'] },
+  upload: { service: 'Dataplane', permissions: ['external-system:publish'] },
+  download: { service: 'Dataplane', permissions: ['external-system:read'] },
+  delete: { service: 'Dataplane', permissions: ['external-system:delete'] },
+  wizard: { service: 'Dataplane', permissions: ['external-system:create'] },
+  'credential list': { service: 'Dataplane', permissions: ['credential:read'] },
+  'deployment list': { service: 'Controller', permissions: ['deployments:read'] },
+  'app register': { service: 'Controller', permissions: ['environments-applications:create'] },
+  'app list': { service: 'Controller', permissions: ['environments-applications:read'] }
+});
+
+/**
+ * @param {string} spec
+ * @returns {boolean}
+ */
+function looksLikeRbacSpec(spec) {
+  if (!spec || typeof spec !== 'string') return false;
+  const trimmed = spec.trim();
+  if (/^(none|public)\b/i.test(trimmed) && !trimmed.includes(':')) return false;
+  if (/authenticated\s*\(/i.test(trimmed)) return false;
+  if (/client credentials/i.test(trimmed) && !/[a-z0-9_-]+:[a-z0-9_-]+/i.test(trimmed)) return false;
+  return /[a-z0-9_-]+:[a-z0-9_-]+/i.test(trimmed);
+}
+
+/**
+ * @param {string} spec
+ * @returns {string[]}
+ */
+function permissionListFromSpec(spec) {
+  const main = String(spec).split('(')[0].trim();
+  if (!main) return [];
+  if (/\bor\b/i.test(main)) return [main];
+  return main.split(/\s*\+\s*/).map((part) => part.trim()).filter(Boolean);
+}
+
+/**
+ * @param {string} template
+ * @returns {RegExp}
+ */
+function pathTemplateToRegex(template) {
+  const parts = String(template).split('/');
+  const escaped = parts.map((seg) => {
+    if (/^\{[^}]+\}$/.test(seg)) return '[^/]+';
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }).join('/');
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * @param {string} block
+ * @returns {{ method: string, path: string, service: string, permissions: string[] }|null}
+ */
+function parsePermissionCommentBlock(block) {
+  const text = String(block).replace(/^\s*\*\s?/gm, '');
+  const methodPath = text.match(/\b(GET|POST|PUT|PATCH|DELETE)\s+(\/api\/[^\s*]+)/);
+  const perm = text.match(/@requiresPermission\s+\{([^}]+)\}\s+([^\n*]+)/);
+  if (!methodPath || !perm) return null;
+  const spec = String(perm[2] || '').trim();
+  if (!looksLikeRbacSpec(spec)) return null;
+  const permissions = permissionListFromSpec(spec);
+  if (permissions.length === 0) return null;
+  return {
+    method: methodPath[1].toUpperCase(),
+    path: methodPath[2].replace(/\/+$/, ''),
+    service: String(perm[1] || '').trim(),
+    permissions
+  };
+}
+
+/**
+ * @param {string} source
+ * @returns {Array<{ method: string, regex: RegExp, service: string, permissions: string[], pathLength: number }>}
+ */
+function parsePermissionEntriesFromSource(source) {
+  const entries = [];
+  const blocks = String(source).match(/\/\*\*[\s\S]*?\*\//g) || [];
+  for (const block of blocks) {
+    const parsed = parsePermissionCommentBlock(block);
+    if (!parsed) continue;
+    entries.push({
+      method: parsed.method,
+      regex: pathTemplateToRegex(parsed.path),
+      service: parsed.service,
+      permissions: parsed.permissions,
+      pathLength: parsed.path.length
+    });
+  }
+  return entries;
+}
+
+/**
+ * @returns {Array<{ method: string, regex: RegExp, service: string, permissions: string[], pathLength: number }>}
+ */
+function loadApiPermissionCatalog() {
+  if (cachedCatalog) return cachedCatalog;
+  const apiDir = path.join(__dirname, '..', 'api');
+  const entries = [];
+  let names = [];
+  try {
+    names = fsRealSync.readdirSync(apiDir);
+  } catch {
+    cachedCatalog = [];
+    return cachedCatalog;
+  }
+  for (const name of names) {
+    if (!name.endsWith('.api.js')) continue;
+    const source = fsRealSync.readFileSync(path.join(apiDir, name), 'utf8');
+    entries.push(...parsePermissionEntriesFromSource(source));
+  }
+  entries.sort((a, b) => b.pathLength - a.pathLength);
+  cachedCatalog = entries;
+  return cachedCatalog;
+}
+
+/**
+ * @param {string} [url]
+ * @returns {string}
+ */
+function apiPathFromUrl(url) {
+  const raw = String(url || '');
+  try {
+    const parsed = new URL(raw);
+    const idx = parsed.pathname.indexOf('/api/');
+    return idx >= 0 ? parsed.pathname.slice(idx).replace(/\/+$/, '') : parsed.pathname;
+  } catch {
+    const idx = raw.indexOf('/api/');
+    const pathOnly = idx >= 0 ? raw.slice(idx).split('?')[0] : raw.split('?')[0];
+    return pathOnly.replace(/\/+$/, '');
+  }
+}
+
+/**
+ * @param {string} [method]
+ * @param {string} [url]
+ * @returns {{ service: string, permissions: string[] }|null}
+ */
+function lookupRequiredPermission(method, url) {
+  const verb = String(method || '').toUpperCase();
+  const apiPath = apiPathFromUrl(url);
+  if (!verb || !apiPath.startsWith('/api/')) return null;
+  const catalog = loadApiPermissionCatalog();
+  for (const entry of catalog) {
+    if (entry.method === verb && entry.regex.test(apiPath)) {
+      return { service: entry.service, permissions: entry.permissions };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} [command]
+ * @returns {{ service: string, permissions: string[] }|null}
+ */
+function lookupCommandRequiredPermission(command) {
+  if (!command || typeof command !== 'string') return null;
+  return COMMAND_REQUIRED_PERMISSIONS[command] || null;
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractPermissionTokensFromText(text) {
+  if (!text || typeof text !== 'string') return [];
+  const found = text.match(SCOPE_IN_TEXT_RE) || [];
+  const unique = [];
+  for (const token of found) {
+    const scheme = token.split(':')[0].toLowerCase();
+    if (SKIP_SCOPE_SCHEMES.has(scheme)) continue;
+    if (!unique.includes(token)) unique.push(token);
+  }
+  return unique;
+}
+
+/**
+ * @param {Object} data
+ * @returns {boolean}
+ */
+function hasBodyPermissionLists(data) {
+  if (!data || typeof data !== 'object') return false;
+  const lists = [
+    data.missingPermissions,
+    data.requiredPermissions,
+    data.permissions,
+    data.missing && data.missing.permissions,
+    data.required && data.required.permissions,
+    data.data && data.data.missing && data.data.missing.permissions,
+    data.data && data.data.required && data.data.required.permissions
+  ];
+  return lists.some((list) => Array.isArray(list) && list.length > 0);
+}
+
+/**
+ * @param {*} errorData
+ * @returns {Object}
+ */
+function asErrorObject(errorData) {
+  if (errorData && typeof errorData === 'object' && !Array.isArray(errorData)) {
+    return { ...errorData };
+  }
+  const text = errorData === undefined || errorData === null ? 'Permission denied' : String(errorData);
+  return { detail: text, message: text };
+}
+
+/**
+ * When a 403 body has no permission list, fill requiredPermissions from the request catalog.
+ *
+ * @param {*} errorData
+ * @param {{ status?: number, method?: string, url?: string }} [ctx]
+ * @returns {*}
+ */
+function enrichForbiddenErrorData(errorData, ctx = {}) {
+  if (ctx.status !== 403) return errorData;
+  const data = asErrorObject(errorData);
+  if (ctx.method && !data.method) data.method = ctx.method;
+  if (ctx.url && !data.instance && !data.url) data.url = ctx.url;
+  if (hasBodyPermissionLists(data)) {
+    return data;
+  }
+  const fromText = extractPermissionTokensFromText(
+    [data.detail, data.message, data.error, data.title, data.errorDescription].filter(Boolean).join(' ')
+  );
+  if (fromText.length > 0) {
+    data.requiredPermissions = fromText;
+    return data;
+  }
+  const hit = lookupRequiredPermission(ctx.method, ctx.url);
+  if (!hit) return data;
+  data.cliPermissionService = hit.service;
+  data.requiredPermissions = hit.permissions;
+  return data;
+}
+
+module.exports = {
+  lookupRequiredPermission,
+  lookupCommandRequiredPermission,
+  enrichForbiddenErrorData,
+  extractPermissionTokensFromText,
+  parsePermissionEntriesFromSource,
+  parsePermissionCommentBlock,
+  apiPathFromUrl,
+  COMMAND_REQUIRED_PERMISSIONS
+};