@aifabrix/builder 2.54.1 → 2.55.0

package/lib/agent-kit/state-file.js

@@ -0,0 +1,83 @@
+/**
+ * Installed Agent Kit state file.
+ * @fileoverview Read/write .aifabrix/agent-kit.yaml
+ */
+
+'use strict';
+
+const path = require('path');
+const yaml = require('js-yaml');
+const fs = require('../internal/fs-real-sync');
+const { STATE_RELATIVE, SECTION_ID } = require('./constants');
+
+/**
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function statePath(repoRoot) {
+  return path.join(repoRoot, STATE_RELATIVE);
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {object|null}
+ */
+function loadState(repoRoot) {
+  const filePath = statePath(repoRoot);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  const parsed = yaml.load(fs.readFileSync(filePath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+  return parsed;
+}
+
+/**
+ * @param {object} kit
+ * @param {string[]} hosts
+ * @param {object[]} ops
+ * @param {string} builderVersion
+ * @returns {object}
+ */
+function buildStateDocument(kit, hosts, ops, builderVersion) {
+  const managedFiles = [];
+  for (const op of ops) {
+    if (op.action === 'delete' || op.action === 'retain' || op.action === 'conflict') {
+      continue;
+    }
+    if (op.action === 'skip' && op.fileState === 'MISSING') {
+      continue;
+    }
+    if (!op.targetRel || op.mode === 'obsolete' || op.mode === 'if-missing') {
+      continue;
+    }
+    const row = { path: op.targetRel, sha256: op.sourceHash };
+    if (op.mode === 'managed-section') {
+      row.section = SECTION_ID;
+    }
+    managedFiles.push(row);
+  }
+  return {
+    schemaVersion: '1',
+    kitVersion: kit.manifest.kitVersion,
+    builderVersion,
+    installedAt: new Date().toISOString(),
+    hosts,
+    managedFiles
+  };
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {object} doc
+ * @returns {void}
+ */
+function writeState(repoRoot, doc) {
+  const filePath = statePath(repoRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, yaml.dump(doc, { lineWidth: 120, noRefs: true, sortKeys: false }), 'utf8');
+}
+
+module.exports = { statePath, loadState, buildStateDocument, writeState };

package/lib/agent-kit/status.js

@@ -0,0 +1,50 @@
+/**
+ * Agent Kit status.
+ * @fileoverview Classify installed files without writing
+ */
+
+'use strict';
+
+const { getCliVersion } = require('../utils/installation-log-core');
+const { resolveGitRoot } = require('./repo-guard');
+const { loadKitPackage } = require('./package-load');
+const { listManagedTargets } = require('./file-list');
+const { classifyItems } = require('./classify');
+const { detectV1, listObsoleteV1Items } = require('./v1-detect');
+const { loadState } = require('./state-file');
+const { ACTION } = require('./constants');
+const { kitStateName, buildJsonReport } = require('./report');
+const { ALL_HOSTS } = require('./hosts');
+
+/**
+ * @param {object} options
+ * @returns {object}
+ */
+function runStatus(options) {
+  const repoRoot = resolveGitRoot(options.cwd || process.cwd());
+  const kit = loadKitPackage();
+  const state = loadState(repoRoot);
+  const includeShims = detectV1(repoRoot);
+  const hosts = (state && state.hosts) || ALL_HOSTS.slice();
+  const includeClaude = hosts.includes('claude');
+  const items = listManagedTargets(kit, repoRoot, {
+    includeShims: includeShims && hosts.includes('cursor'),
+    includeClaude
+  });
+  classifyItems(items, state, hosts);
+  items.push(...listObsoleteV1Items(kit, repoRoot, new Set(items.map((item) => item.targetRel))));
+  const ops = items.map((item) => ({ ...item, action: ACTION.SKIP }));
+  const kitState = kitStateName(state, kit, ops);
+  return buildJsonReport({
+    command: 'status',
+    kit,
+    state,
+    hosts,
+    ops,
+    dryRun: true,
+    builderVersion: getCliVersion(),
+    kitState
+  });
+}
+
+module.exports = { runStatus };

package/lib/agent-kit/v1-detect.js

@@ -0,0 +1,81 @@
+/**
+ * Detect v1 Agent Kit files in a customer repository.
+ * @fileoverview Name + hash detection for migration
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { V1_MARKERS, FILE_STATE } = require('./constants');
+const { sha256File } = require('./checksums');
+
+/**
+ * @param {string} repoRoot
+ * @returns {boolean}
+ */
+function detectV1(repoRoot) {
+  return V1_MARKERS.some((rel) => fs.existsSync(path.join(repoRoot, rel)));
+}
+
+/**
+ * @param {object} kit
+ * @param {string} repoRoot
+ * @param {Set<string>} managedRels
+ * @returns {object[]}
+ */
+function listObsoleteV1Items(kit, repoRoot, managedRels) {
+  const rows = (kit.inventory && kit.inventory.v1Files) || [];
+  const items = [];
+  for (const row of rows) {
+    if (row.disposition === 'shim' || !row.installedPath) {
+      continue;
+    }
+    if (managedRels.has(row.installedPath)) {
+      continue;
+    }
+    const targetAbs = path.join(repoRoot, row.installedPath);
+    if (!fs.existsSync(targetAbs)) {
+      continue;
+    }
+    const hash = sha256File(targetAbs);
+    const unchanged = hash === row.sha256;
+    items.push({
+      sourceAbs: null,
+      targetRel: row.installedPath,
+      targetAbs,
+      mode: 'obsolete',
+      sourceHash: row.sha256,
+      currentHash: hash,
+      fileState: unchanged
+        ? FILE_STATE.OBSOLETE_UNCHANGED_MANAGED
+        : FILE_STATE.OBSOLETE_MODIFIED_MANAGED,
+      v1Owner: row.owner
+    });
+  }
+  return items;
+}
+
+/**
+ * Replace unmodified v1 command files with thin shims on install.
+ * @param {object[]} items
+ * @param {object} kit
+ * @returns {void}
+ */
+function markV1ShimReplacements(items, kit) {
+  const byPath = new Map();
+  for (const row of (kit.inventory && kit.inventory.v1Files) || []) {
+    byPath.set(row.installedPath, row);
+  }
+  for (const item of items) {
+    if (!item.optional || !item.currentHash) {
+      continue;
+    }
+    const row = byPath.get(item.targetRel);
+    if (row && row.disposition === 'shim' && item.currentHash === row.sha256) {
+      item.replaceOnInstall = true;
+    }
+  }
+}
+
+module.exports = { detectV1, listObsoleteV1Items, markV1ShimReplacements };

package/lib/agent-kit/validate-kit.js

@@ -0,0 +1,87 @@
+/**
+ * Validate bundled Agent Kit package and optional install.
+ * @fileoverview Schema, paths, skill names, installed conflicts
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { loadKitPackage } = require('./package-load');
+const { listTreeFiles } = require('./file-list');
+const { runStatus } = require('./status');
+const { KIT_STATE } = require('./constants');
+
+const FORBIDDEN_RE = /@[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}|kv:\/\/[^\s]+\/[A-Za-z0-9+/]{12,}|\/home\/[a-z0-9]+\/(?!dev)/i;
+
+/**
+ * @param {object} kit
+ * @returns {string[]}
+ */
+function collectPackageErrors(kit) {
+  const errors = [];
+  const names = kit.manifest.skills || [];
+  if (new Set(names).size !== names.length) {
+    errors.push('Duplicate skill name in agent-kit.yaml.');
+  }
+  for (const name of names) {
+    const skillMd = path.join(kit.root, 'skills', name, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) {
+      errors.push(`Missing SKILL.md for ${name}.`);
+    }
+  }
+  for (const spec of [...(kit.manifest.managed || []), ...(kit.manifest.optional || [])]) {
+    const sourceAbs = path.join(kit.root, spec.source);
+    if (!fs.existsSync(sourceAbs)) {
+      errors.push(`Managed source missing: ${spec.source}`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * @param {object} kit
+ * @returns {string[]}
+ */
+function collectContentErrors(kit) {
+  const errors = [];
+  for (const file of listTreeFiles(kit.root, '')) {
+    if (file.rel === 'parity-inventory.yaml') {
+      continue;
+    }
+    const text = fs.readFileSync(file.abs, 'utf8');
+    if (FORBIDDEN_RE.test(text)) {
+      errors.push(`Forbidden customer/secret pattern in ${file.rel}`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * @param {object} [options]
+ * @returns {object}
+ */
+function runValidate(options = {}) {
+  const kit = loadKitPackage();
+  const errors = [...collectPackageErrors(kit), ...collectContentErrors(kit)];
+  let install = null;
+  try {
+    install = runStatus(options);
+  } catch (error) {
+    if (!String(error.message || '').includes('git repository')) {
+      throw error;
+    }
+  }
+  if (install && install.state === KIT_STATE.CONFLICTS) {
+    errors.push(`Install conflicts: ${install.conflicts.join(', ')}`);
+  }
+  return {
+    success: errors.length === 0,
+    command: 'validate',
+    kitVersion: kit.manifest.kitVersion,
+    errors,
+    install
+  };
+}
+
+module.exports = { runValidate, collectPackageErrors, collectContentErrors };

package/lib/agent-kit/workspace-name.js

@@ -0,0 +1,40 @@
+/**
+ * Resolve workspace directory name for agent-kit init.
+ * @fileoverview Name authority — never rewrite cust-* to aif-*
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * @param {string|undefined} nameOrPath
+ * @param {string} cwd
+ * @returns {{ targetAbs: string, workspaceName: string }}
+ */
+function resolveWorkspaceTarget(nameOrPath, cwd) {
+  const base = path.resolve(cwd || process.cwd());
+  if (!nameOrPath || !String(nameOrPath).trim()) {
+    throw new Error('Workspace name or path is required. Example: aifabrix agent-kit init cust-demo');
+  }
+  const raw = String(nameOrPath).trim();
+  const looksLikePath =
+    path.isAbsolute(raw) || raw.includes('/') || raw.includes('\\') || raw === '.' || raw.startsWith('.');
+  const targetAbs = looksLikePath ? path.resolve(base, raw) : path.join(base, raw);
+  const workspaceName = path.basename(targetAbs);
+  if (!workspaceName || workspaceName === '.' || workspaceName === '..') {
+    throw new Error('Could not derive a workspace name from the path.');
+  }
+  return { targetAbs, workspaceName };
+}
+
+/**
+ * Preserve user-supplied names; never rewrite cust-* prefixes.
+ * @param {string} name
+ * @returns {string}
+ */
+function assertNameUnchanged(name) {
+  return name;
+}
+
+module.exports = { resolveWorkspaceTarget, assertNameUnchanged };

package/lib/agent-kit/workspace-skeleton.js

@@ -0,0 +1,103 @@
+/**
+ * Copy product-neutral workspace skeleton for agent-kit init.
+ * @fileoverview templates/agent-kit/workspace → target
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { getKitRoot } = require('./kit-root');
+
+/**
+ * @returns {string}
+ */
+function getWorkspaceTemplateRoot() {
+  return path.join(getKitRoot(), 'workspace');
+}
+
+/**
+ * @param {string} text
+ * @param {{ workspaceName: string, year?: number, copyrightHolder?: string }} vars
+ * @returns {string}
+ */
+function applyPlaceholders(text, vars) {
+  return String(text)
+    .replace(/\{\{workspaceName\}\}/g, vars.workspaceName)
+    .replace(/\{\{year\}\}/g, String(vars.year || new Date().getFullYear()))
+    .replace(/\{\{copyrightHolder\}\}/g, vars.copyrightHolder || 'Copyright Holder');
+}
+
+/**
+ * @param {string} absDir
+ * @param {string} relPrefix
+ * @returns {{ rel: string, abs: string }[]}
+ */
+function listTemplateFiles(absDir, relPrefix) {
+  if (!fs.existsSync(absDir)) {
+    return [];
+  }
+  const out = [];
+  for (const ent of fs.readdirSync(absDir, { withFileTypes: true })) {
+    const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+    const abs = path.join(absDir, ent.name);
+    if (ent.isDirectory()) {
+      out.push(...listTemplateFiles(abs, rel));
+    } else if (ent.name !== 'LICENSE.mit') {
+      out.push({ rel, abs });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} targetAbs
+ * @param {{ workspaceName: string, license?: string, dryRun?: boolean }} options
+ * @returns {string[]} written relative paths
+ */
+function writeWorkspaceSkeleton(targetAbs, options) {
+  const written = [];
+  const vars = { workspaceName: options.workspaceName };
+  const root = getWorkspaceTemplateRoot();
+  for (const file of listTemplateFiles(root, '')) {
+    const dest = path.join(targetAbs, file.rel);
+    if (!options.dryRun) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const body = applyPlaceholders(fs.readFileSync(file.abs, 'utf8'), vars);
+      fs.writeFileSync(dest, body, 'utf8');
+    }
+    written.push(file.rel);
+  }
+  if (options.license === 'mit') {
+    const src = path.join(root, 'LICENSE.mit');
+    const dest = path.join(targetAbs, 'LICENSE');
+    if (!options.dryRun && fs.existsSync(src)) {
+      fs.writeFileSync(dest, applyPlaceholders(fs.readFileSync(src, 'utf8'), vars), 'utf8');
+    }
+    written.push('LICENSE');
+  }
+  if (!options.dryRun) {
+    fs.mkdirSync(path.join(targetAbs, 'integration'), { recursive: true });
+    fs.mkdirSync(path.join(targetAbs, 'role-assistant'), { recursive: true });
+  }
+  return written;
+}
+
+/**
+ * @param {string} targetAbs
+ * @returns {boolean}
+ */
+function isNonEmptyDirectory(targetAbs) {
+  if (!fs.existsSync(targetAbs)) {
+    return false;
+  }
+  const entries = fs.readdirSync(targetAbs).filter((name) => name !== '.git');
+  return entries.length > 0;
+}
+
+module.exports = {
+  getWorkspaceTemplateRoot,
+  applyPlaceholders,
+  writeWorkspaceSkeleton,
+  isNonEmptyDirectory
+};

package/lib/api/role-assistant-test-pack.api.js

@@ -0,0 +1,86 @@
+/**
+ * Dataplane Role Assistant test pack CRUD + case status.
+ *
+ * @fileoverview PUT/GET pack and PATCH case status
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { throwIfApiFailed } = require('./api-response-errors');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+function packEndpoint(dataplaneUrl, systemIdOrKey, suffix) {
+  const base = String(dataplaneUrl || '').replace(/\/$/, '');
+  const key = encodeURIComponent(systemIdOrKey);
+  return `${base}/api/v1/external/systems/${key}/role-assistant-tests${suffix || ''}`;
+}
+
+function packPath(systemIdOrKey, suffix) {
+  const key = encodeURIComponent(systemIdOrKey);
+  return `/api/v1/external/systems/${key}/role-assistant-tests${suffix || ''}`;
+}
+
+function isMissingPackResponse(res) {
+  return Boolean(res && res.success === false && Number(res.status) === 404);
+}
+
+/**
+ * PUT /api/v1/external/systems/{systemIdOrKey}/role-assistant-tests
+ * @requiresPermission {Dataplane} external-system:update
+ * @async
+ */
+async function upsertRoleAssistantTestPack(dataplaneUrl, authConfig, systemIdOrKey, pack) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.put(packPath(systemIdOrKey), { body: { pack } });
+  throwIfApiFailed(res, {
+    endpointUrl: packEndpoint(dataplaneUrl, systemIdOrKey, '')
+  });
+  return unwrapApiData(res);
+}
+
+/**
+ * GET /api/v1/external/systems/{systemIdOrKey}/role-assistant-tests
+ * @requiresPermission {Dataplane} external-system:read
+ * @async
+ */
+async function getRoleAssistantTestPack(dataplaneUrl, authConfig, systemIdOrKey, options = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(packPath(systemIdOrKey));
+  if (options.allowMissing === true && isMissingPackResponse(res)) {
+    return null;
+  }
+  throwIfApiFailed(res, {
+    endpointUrl: packEndpoint(dataplaneUrl, systemIdOrKey, '')
+  });
+  return unwrapApiData(res);
+}
+
+/**
+ * PATCH /api/v1/external/systems/{systemIdOrKey}/role-assistant-tests/cases/{caseId}/status
+ * @requiresPermission {Dataplane} external-system:update
+ * @async
+ */
+async function patchRoleAssistantTestCaseStatus(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  caseId,
+  body
+) {
+  const suffix = `/cases/${encodeURIComponent(caseId)}/status`;
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.patch(packPath(systemIdOrKey, suffix), { body });
+  throwIfApiFailed(res, {
+    endpointUrl: packEndpoint(dataplaneUrl, systemIdOrKey, suffix)
+  });
+  return unwrapApiData(res);
+}
+
+module.exports = {
+  upsertRoleAssistantTestPack,
+  getRoleAssistantTestPack,
+  patchRoleAssistantTestCaseStatus
+};

package/lib/api/work-search.api.js

@@ -14,6 +14,7 @@ const { unwrapApiData } = require('../utils/external-system-readiness-core');
 const SEARCH_TIMEOUT_MS = 120000;
 const LAYER_B_SYSTEM_KEY = process.env.RUNTIME_ORCHESTRATION_SYSTEM_KEY || 'runtime-orchestration';
 const LAYER_B_TOOLS = Object.freeze({
+  roles: { resourceType: 'work-roles', toolName: 'work_roles.list' },
   skills: { resourceType: 'work-skills', toolName: 'work_skills.get' },
   search: { resourceType: 'work-search', toolName: 'work_search.create' }
 });
@@ -45,19 +46,31 @@ function extractErrorText(res) {
   return parts.join(' ');
 }
 
+/**
+ * MCP execute sometimes wraps a single JSON object as a one-element array.
+ * @param {*} value
+ * @returns {*}
+ */
+function unwrapSingletonObject(value) {
+  if (Array.isArray(value) && value.length === 1 && value[0] && typeof value[0] === 'object') {
+    return value[0];
+  }
+  return value;
+}
+
 function unwrapExecutePayload(res) {
-  const body = unwrapApiData(res);
+  const body = unwrapSingletonObject(unwrapApiData(res));
   if (!body || typeof body !== 'object') {
     return body;
   }
   if (body.result && typeof body.result === 'object') {
-    return body.result;
+    return unwrapSingletonObject(body.result);
   }
   if (body.json && typeof body.json === 'object') {
-    return body.json;
+    return unwrapSingletonObject(body.json);
   }
   if (body.root && typeof body.root === 'object') {
-    return body.root;
+    return unwrapSingletonObject(body.root);
   }
   return body;
 }
@@ -94,6 +107,18 @@ async function executeLayerBTool(dataplaneUrl, authConfig, tool, args = {}) {
   return normalizeLayerBResult(res);
 }
 
+/**
+ * GET-equivalent work.roles for the current caller.
+ * @requiresPermission {Dataplane} Authenticated (oauth2: [])
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @returns {Promise<{ status: number, payload: Object|null, errorText: string, raw: Object }>}
+ */
+async function getWorkRoles(dataplaneUrl, authConfig) {
+  return executeLayerBTool(dataplaneUrl, authConfig, LAYER_B_TOOLS.roles, {});
+}
+
 /**
  * GET-equivalent work.skills for one roleRef.
  * Requests detail=full so search.resourceTypes (executable grammar) is present.
@@ -128,9 +153,11 @@ module.exports = {
   SEARCH_TIMEOUT_MS,
   buildLayerBExecutePath,
   extractErrorText,
+  unwrapSingletonObject,
   unwrapExecutePayload,
   normalizeLayerBResult,
   executeLayerBTool,
+  getWorkRoles,
   getWorkSkills,
   searchWork
 };