@aifabrix/builder 2.54.1 → 2.55.2

package/lib/agent-kit/start.js

@@ -0,0 +1,310 @@
+/**
+ * Start Claude Code or Codex in a named tmux session.
+ * @fileoverview Does not install Agent Kit skills
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+const logger = require('../utils/logger');
+const { resolveGitRoot } = require('./repo-guard');
+const { writeApproveAllFiles } = require('./host-approve');
+
+const START_APPS = {
+  claude: { bin: 'claude' },
+  codex: { bin: 'codex' }
+};
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normalizeStartApp(value) {
+  const app = String(value || '').trim();
+  if (!START_APPS[app]) {
+    throw new Error('Invalid app. Use claude or codex.');
+  }
+  return app;
+}
+
+/**
+ * Session names may not contain colons or periods.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function sanitizeSessionName(value) {
+  const name = String(value || '')
+    .trim()
+    .replace(/[.:\s]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (!name) {
+    throw new Error(
+      'Invalid --name. Use the last folder of this git workspace, for example aifabrix-docs.'
+    );
+  }
+  return name;
+}
+
+/**
+ * Default display name is the last folder of the git workspace.
+ * @param {unknown} explicit
+ * @param {string} cwd
+ * @returns {string}
+ */
+function resolveSessionName(explicit, cwd) {
+  const raw = explicit === undefined || explicit === null || explicit === ''
+    ? path.basename(cwd)
+    : explicit;
+  return sanitizeSessionName(raw);
+}
+
+/**
+ * @param {object} options
+ * @returns {string}
+ */
+function currentUsername(options) {
+  if (options && options.username) {
+    return String(options.username);
+  }
+  try {
+    return os.userInfo().username;
+  } catch {
+    return process.env.USER || process.env.LOGNAME || 'user';
+  }
+}
+
+/**
+ * Hostname + login, e.g. builder01-dev03.
+ * @param {object} [options]
+ * @returns {string}
+ */
+function hostUserPrefix(options) {
+  const hostRaw = options && options.hostname ? options.hostname : os.hostname();
+  const host = String(hostRaw).split('.')[0];
+  return sanitizeSessionName(`${host}-${currentUsername(options || {})}`);
+}
+
+/**
+ * Remote Control session: builder01-dev03-aifabrix-docs.
+ * @param {string} prefix
+ * @param {string} session
+ * @returns {string}
+ */
+function resolveRemoteControlName(prefix, session) {
+  return sanitizeSessionName(`${prefix}-${session}`);
+}
+
+/**
+ * @param {string} bin
+ * @param {Function} exec
+ * @returns {boolean}
+ */
+function hasOnPath(bin, exec) {
+  try {
+    exec('which', [bin], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {object} options
+ * @returns {void}
+ */
+function validateStartOptions(options) {
+  const app = String(options.app || '').trim();
+  if (options.remoteControl && app !== 'claude') {
+    throw new Error('--remote-control is only valid with claude.');
+  }
+}
+
+/**
+ * Claude argv after the binary (Remote Control names, not Claude --tmux).
+ * @param {object} p
+ * @returns {string[]}
+ */
+function claudeInnerArgs(p) {
+  const args = ['--name', p.session];
+  if (!p.remoteControl) {
+    return args;
+  }
+  return args.concat([
+    '--remote-control',
+    p.remoteControlName,
+    '--remote-control-session-name-prefix',
+    p.remoteControlPrefix
+  ]);
+}
+
+/**
+ * @param {object} p
+ * @returns {object}
+ */
+function buildTmuxSpec(p) {
+  const spec = START_APPS[p.app];
+  const extra = p.app === 'claude' ? claudeInnerArgs(p) : [];
+  const mode = p.detach
+    ? ['new-session', '-d', '-s', p.session, '-c', p.cwd]
+    : ['new-session', '-A', '-s', p.session, '-c', p.cwd];
+  const remote = p.app === 'claude' && p.remoteControl;
+  return {
+    bin: 'tmux',
+    args: [...mode, spec.bin, ...extra],
+    session: p.session,
+    appBin: spec.bin,
+    needTmux: true,
+    remoteControlName: remote ? p.remoteControlName : undefined,
+    remoteControlPrefix: remote ? p.remoteControlPrefix : undefined
+  };
+}
+
+/**
+ * @param {object} p
+ * @returns {object}
+ */
+function buildLaunchSpec(p) {
+  return buildTmuxSpec(p);
+}
+
+/**
+ * @param {{ appBin: string, needTmux?: boolean }} spec
+ * @param {Function} exec
+ * @returns {void}
+ */
+function requireBinaries(spec, exec) {
+  if (spec.needTmux && !hasOnPath('tmux', exec)) {
+    throw new Error('tmux is not on PATH. Install tmux, then retry.');
+  }
+  if (hasOnPath(spec.appBin, exec)) {
+    return;
+  }
+  if (spec.appBin === 'claude') {
+    throw new Error(
+      'claude is not on PATH. Install with: curl -fsSL https://claude.ai/install.sh | bash'
+    );
+  }
+  throw new Error('codex is not on PATH. Install with: npm install -g @openai/codex');
+}
+
+/**
+ * @param {object} options
+ * @returns {boolean}
+ */
+function shouldExecute(options) {
+  if (options.dryRun || options.json) {
+    return false;
+  }
+  if (options.detach) {
+    return true;
+  }
+  if (!process.stdout.isTTY) {
+    throw new Error('agent-kit start needs a TTY to attach. Pass --detach or --dry-run.');
+  }
+  return true;
+}
+
+/**
+ * @param {object} options
+ * @param {{ bin: string, args: string[], cwd: string }} spec
+ * @returns {unknown}
+ */
+function spawnLaunch(options, spec) {
+  const spawn = options.spawnSync || spawnSync;
+  const result = spawn(spec.bin, spec.args, { stdio: 'inherit', cwd: spec.cwd });
+  const status = result && typeof result.status === 'number' ? result.status : 0;
+  if (status !== 0) {
+    throw new Error(`${spec.bin} exited with status ${status}`);
+  }
+  return status;
+}
+
+/**
+ * @param {object} spec
+ * @param {object} extra
+ * @returns {object}
+ */
+function toStartResult(spec, extra) {
+  const launch = [spec.bin, ...spec.args];
+  return {
+    command: 'start',
+    app: extra.app,
+    session: spec.session,
+    remoteControlName: spec.remoteControlName,
+    remoteControlPrefix: spec.remoteControlPrefix,
+    path: extra.cwd,
+    launch,
+    tmux: spec.needTmux ? launch : undefined,
+    approvals: extra.approvals,
+    dryRun: extra.dryRun,
+    detach: extra.detach,
+    executed: extra.executed
+  };
+}
+
+/**
+ * @param {object} options
+ * @returns {object}
+ */
+function runStart(options) {
+  validateStartOptions(options);
+  const app = normalizeStartApp(options.app);
+  const cwd = resolveGitRoot(options.cwd || process.cwd());
+  const session = resolveSessionName(options.name, cwd);
+  const remoteControlPrefix = hostUserPrefix(options);
+  const remoteControlName = resolveRemoteControlName(remoteControlPrefix, session);
+  const exec = options.execFileSync || execFileSync;
+  const spec = buildLaunchSpec({
+    app,
+    cwd,
+    session,
+    remoteControlPrefix,
+    remoteControlName,
+    detach: Boolean(options.detach),
+    remoteControl: Boolean(options.remoteControl)
+  });
+  spec.cwd = cwd;
+  const approveAll = !options.skipApproveAll && Boolean(options.approveAll || options.yes);
+  const approvals = writeApproveAllFiles({
+    repoRoot: cwd,
+    hosts: [app],
+    approveAll,
+    dryRun: Boolean(options.dryRun)
+  });
+  if (!options.dryRun) {
+    requireBinaries(spec, exec);
+  }
+  const execute = shouldExecute(options);
+  if (execute && !options.json) {
+    logger.log(`Starting ${app} session ${spec.session}`);
+  }
+  if (execute) {
+    spawnLaunch(options, spec);
+  }
+  return toStartResult(spec, {
+    app,
+    cwd,
+    approvals,
+    dryRun: Boolean(options.dryRun),
+    detach: Boolean(options.detach),
+    executed: execute
+  });
+}
+
+module.exports = {
+  START_APPS,
+  normalizeStartApp,
+  sanitizeSessionName,
+  resolveSessionName,
+  hostUserPrefix,
+  resolveRemoteControlName,
+  claudeInnerArgs,
+  buildTmuxSpec,
+  runStart
+};

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 };