@aifabrix/builder 2.53.1 → 2.55.0

package/lib/agent-kit/hosts.js

@@ -0,0 +1,71 @@
+/**
+ * Normalize Agent Kit --host values.
+ * @fileoverview Host selection for install reporting and adapters
+ */
+
+'use strict';
+
+const ALL_HOSTS = ['cursor', 'codex', 'claude'];
+const HOST_LABELS = {
+  cursor: 'Cursor',
+  codex: 'Codex',
+  claude: 'Claude Code'
+};
+
+/**
+ * @param {string|string[]} [value]
+ * @returns {string[]}
+ */
+function normalizeHosts(value) {
+  if (Array.isArray(value)) {
+    const unique = [...new Set(value.map((h) => String(h || '').trim()).filter(Boolean))];
+    if (!unique.length) {
+      throw new Error('Invalid --host. Use all, cursor, codex, or claude.');
+    }
+    if (unique.some((h) => !ALL_HOSTS.includes(h) && h !== 'all')) {
+      throw new Error('Invalid --host. Use all, cursor, codex, or claude.');
+    }
+    if (unique.includes('all') || unique.length === ALL_HOSTS.length) {
+      return ALL_HOSTS.slice();
+    }
+    return unique.filter((h) => ALL_HOSTS.includes(h));
+  }
+  const host = value || 'all';
+  if (host === 'all') {
+    return ALL_HOSTS.slice();
+  }
+  if (host.includes(',')) {
+    return normalizeHosts(host.split(',').map((part) => part.trim()));
+  }
+  if (ALL_HOSTS.includes(host)) {
+    return [host];
+  }
+  throw new Error('Invalid --host. Use all, cursor, codex, or claude.');
+}
+
+/**
+ * @param {string} host
+ * @returns {string}
+ */
+function hostLabel(host) {
+  return HOST_LABELS[host] || host;
+}
+
+/**
+ * Install uses --host (default all). Update keeps recorded hosts unless --host is set.
+ * @param {object} [options]
+ * @param {object|null} [state]
+ * @param {'install'|'update'} [mode]
+ * @returns {string[]}
+ */
+function resolveManagedHosts(options, state, mode) {
+  if (options && options.host) {
+    return normalizeHosts(options.host);
+  }
+  if (mode === 'update' && state && Array.isArray(state.hosts) && state.hosts.length) {
+    return normalizeHosts(state.hosts);
+  }
+  return normalizeHosts('all');
+}
+
+module.exports = { ALL_HOSTS, HOST_LABELS, normalizeHosts, hostLabel, resolveManagedHosts };

package/lib/agent-kit/init.js

@@ -0,0 +1,319 @@
+/**
+ * Agent Kit workspace init and remote-create runners.
+ * @fileoverview Skeleton + git + install + optional GitHub remote
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { isUnsafeRoot } = require('./repo-guard');
+const { resolveWorkspaceTarget } = require('./workspace-name');
+const { writeWorkspaceSkeleton, isNonEmptyDirectory } = require('./workspace-skeleton');
+const { ensureGitRepository, ensureInitialCommit, hasOriginRemote, isGitRepository } = require('./scm/git');
+const { getGithubAuthStatus, createGithubRemote } = require('./hosting/github');
+const { runInstall } = require('./run');
+const { loadKitPackage } = require('./package-load');
+const { getCliVersion } = require('../utils/installation-log-core');
+
+/**
+ * @param {string} scm
+ * @returns {string}
+ */
+function normalizeScm(scm) {
+  const value = scm || 'git';
+  if (value !== 'git' && value !== 'none') {
+    throw new Error('Invalid --scm. Use git or none.');
+  }
+  return value;
+}
+
+/**
+ * @param {string} visibility
+ * @returns {string}
+ */
+function normalizeVisibility(visibility) {
+  const value = visibility || 'private';
+  if (value !== 'private' && value !== 'public') {
+    throw new Error('Invalid --visibility. Use private or public.');
+  }
+  return value;
+}
+
+/**
+ * @param {object} options
+ * @returns {boolean}
+ */
+function wantsRemote(options) {
+  if (options.noRemote) {
+    return false;
+  }
+  return Boolean(options.remote);
+}
+
+/**
+ * @param {string} targetAbs
+ * @param {boolean} force
+ */
+function assertSafeTarget(targetAbs, force) {
+  if (isUnsafeRoot(targetAbs)) {
+    throw new Error('Refusing to init the Agent Kit into a filesystem root or home directory.');
+  }
+  if (isNonEmptyDirectory(targetAbs) && !force) {
+    throw new Error(
+      `Target is not empty: ${targetAbs}. Use --force to continue, or choose another path.`
+    );
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {boolean} interactive
+ */
+function assertRemoteFlags(options, interactive) {
+  if (!wantsRemote(options)) {
+    return;
+  }
+  if (!interactive && !options.org) {
+    throw new Error('Non-interactive --remote requires --org <owner>.');
+  }
+}
+
+/**
+ * @param {object} options
+ * @returns {object}
+ */
+function checkRemoteAuth(options) {
+  const auth = getGithubAuthStatus({ execFileSync: options.execFileSync });
+  if (!auth.authenticated) {
+    throw new Error(
+      'GitHub authentication required for --remote. Run: gh auth login\n' +
+        'Then retry, or omit --remote and later run: aifabrix agent-kit remote create'
+    );
+  }
+  return auth;
+}
+
+/**
+ * @param {object} ctx
+ * @returns {object|null}
+ */
+function maybeCreateRemote(ctx) {
+  const { options, targetAbs, workspaceName, dryRun } = ctx;
+  if (!wantsRemote(options)) {
+    return null;
+  }
+  checkRemoteAuth(options);
+  return createGithubRemote({
+    name: workspaceName,
+    org: options.org,
+    visibility: normalizeVisibility(options.visibility),
+    cwd: targetAbs,
+    dryRun,
+    execFileSync: options.execFileSync
+  });
+}
+
+/**
+ * @param {object} options
+ * @returns {object}
+ */
+function runInit(options) {
+  const cwd = options.cwd || process.cwd();
+  const dryRun = Boolean(options.dryRun);
+  const scm = normalizeScm(options.scm);
+  const interactive =
+    typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
+  const { targetAbs, workspaceName } = resolveWorkspaceTarget(options.nameOrPath, cwd);
+  assertSafeTarget(targetAbs, Boolean(options.force));
+  assertRemoteFlags(options, interactive);
+
+  const phases = [];
+  if (!dryRun) {
+    fs.mkdirSync(targetAbs, { recursive: true });
+  }
+  const skeletonFiles = writeWorkspaceSkeleton(targetAbs, {
+    workspaceName,
+    license: options.license === 'mit' ? 'mit' : 'none',
+    dryRun
+  });
+  phases.push({ phase: 'skeleton', files: skeletonFiles });
+
+  let gitResult = { initialized: false, skipped: true };
+  if (scm === 'git') {
+    gitResult = ensureGitRepository(targetAbs, { dryRun, execFileSync: options.execFileSync });
+    phases.push({ phase: 'scm', provider: 'git', ...gitResult });
+  } else {
+    phases.push({ phase: 'scm', provider: 'none' });
+  }
+
+  const kit = installKitPhase({
+    scm,
+    dryRun,
+    targetAbs,
+    host: options.host || 'all',
+    approveAll: Boolean(options.approveAll),
+    force: Boolean(options.force),
+    gitResult,
+    phases
+  });
+
+  const remote = remotePhase({ options, targetAbs, workspaceName, dryRun, phases });
+
+  return buildInitReport({
+    dryRun,
+    targetAbs,
+    workspaceName,
+    scm,
+    kit,
+    remote,
+    phases
+  });
+}
+
+/**
+ * @param {object} p
+ * @returns {object|null}
+ */
+function installKitPhase(p) {
+  if (p.scm !== 'git') {
+    return null;
+  }
+  if (p.dryRun) {
+    const kitPkg = loadKitPackage();
+    const skills = (kitPkg.manifest.skills || []).length;
+    p.phases.push({ phase: 'agent-kit', planned: true });
+    return {
+      state: 'CURRENT',
+      kitVersion: kitPkg.manifest.kitVersion,
+      skills: { expected: skills, installed: 0 }
+    };
+  }
+  if (!isGitRepository(p.targetAbs) && !p.gitResult.initialized) {
+    return null;
+  }
+  const kit = runInstall({
+    cwd: p.targetAbs,
+    host: p.host,
+    approveAll: Boolean(p.approveAll),
+    force: Boolean(p.force)
+  });
+  p.phases.push({ phase: 'agent-kit', state: kit.state });
+  return kit;
+}
+
+/**
+ * @param {object} p
+ * @returns {object|null}
+ */
+function remotePhase(p) {
+  if (!wantsRemote(p.options)) {
+    p.phases.push({
+      phase: 'remote',
+      skipped: true,
+      hint: 'aifabrix agent-kit remote create'
+    });
+    return null;
+  }
+  const commit = ensureInitialCommit(p.targetAbs, {
+    dryRun: p.dryRun,
+    execFileSync: p.options.execFileSync
+  });
+  p.phases.push({ phase: 'commit', ...commit });
+  const remote = maybeCreateRemote(p);
+  p.phases.push({ phase: 'remote', ...remote });
+  return remote;
+}
+
+/**
+ * @param {object} p
+ * @returns {object}
+ */
+function buildInitReport(p) {
+  return {
+    success: true,
+    command: 'init',
+    dryRun: p.dryRun,
+    path: p.targetAbs,
+    name: p.workspaceName,
+    scm: p.scm,
+    hosts: p.kit && p.kit.hosts ? p.kit.hosts : undefined,
+    remote: p.remote,
+    builderVersion: getCliVersion(),
+    kit: p.kit
+      ? {
+        state: p.kit.state,
+        kitVersion: p.kit.kitVersion,
+        skills: p.kit.skills
+      }
+      : null,
+    phases: p.phases
+  };
+}
+
+/**
+ * @param {object} options
+ * @returns {object}
+ */
+function runRemoteCreate(options) {
+  const cwd = options.cwd || process.cwd();
+  const dryRun = Boolean(options.dryRun);
+  const interactive =
+    typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
+  const targetAbs = path.resolve(cwd);
+  if (isUnsafeRoot(targetAbs)) {
+    throw new Error(
+      'Run remote create from inside the workspace (for example: cd ~/cust-demo && aifabrix agent-kit remote create).'
+    );
+  }
+  if (!isGitRepository(targetAbs)) {
+    throw new Error(
+      'remote create requires a git repository. cd into the workspace, then run: aifabrix agent-kit remote create'
+    );
+  }
+  if (hasOriginRemote(targetAbs, { execFileSync: options.execFileSync })) {
+    return {
+      success: true,
+      command: 'remote-create',
+      dryRun,
+      path: targetAbs,
+      remote: { provider: 'github', skipped: true, reason: 'origin-exists' },
+      builderVersion: getCliVersion()
+    };
+  }
+  if (!interactive && !options.org) {
+    throw new Error('Non-interactive remote create requires --org <owner>.');
+  }
+  checkRemoteAuth(options);
+  const commit = ensureInitialCommit(targetAbs, {
+    dryRun,
+    execFileSync: options.execFileSync
+  });
+  const name = options.name || path.basename(targetAbs);
+  const remote = createGithubRemote({
+    name,
+    org: options.org,
+    visibility: normalizeVisibility(options.visibility),
+    cwd: targetAbs,
+    dryRun,
+    execFileSync: options.execFileSync
+  });
+  return {
+    success: true,
+    command: 'remote-create',
+    dryRun,
+    path: targetAbs,
+    name,
+    commit,
+    remote,
+    builderVersion: getCliVersion()
+  };
+}
+
+module.exports = {
+  runInit,
+  runRemoteCreate,
+  normalizeScm,
+  normalizeVisibility,
+  wantsRemote
+};

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

@@ -0,0 +1,17 @@
+/**
+ * Resolve the bundled Agent Kit template root.
+ * @fileoverview Path to templates/agent-kit
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * @returns {string}
+ */
+function getKitRoot() {
+  return path.join(__dirname, '..', '..', 'templates', 'agent-kit');
+}
+
+module.exports = { getKitRoot };

package/lib/agent-kit/managed-section.js

@@ -0,0 +1,79 @@
+/**
+ * Managed-section markers for kit-owned markdown (AGENTS.md, CLAUDE.md).
+ * @fileoverview Extract, append, and replace kit-owned sections
+ */
+
+'use strict';
+
+const { BEGIN_MARKER, END_MARKER } = require('./constants');
+
+/**
+ * @param {string} body
+ * @returns {string}
+ */
+function wrapSection(body) {
+  const trimmed = String(body || '').replace(/^\n+|\n+$/g, '');
+  return `${BEGIN_MARKER}\n${trimmed}\n${END_MARKER}\n`;
+}
+
+/**
+ * @param {string} text
+ * @returns {string|null}
+ */
+function extractSection(text) {
+  const start = text.indexOf(BEGIN_MARKER);
+  const end = text.indexOf(END_MARKER);
+  if (start < 0 || end < 0 || end <= start) {
+    return null;
+  }
+  return text.slice(start + BEGIN_MARKER.length, end).replace(/^\n+|\n+$/g, '');
+}
+
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+function hasManagedSection(text) {
+  return extractSection(text) !== null;
+}
+
+/**
+ * Append a managed section; leave existing bytes unchanged.
+ * @param {string} text
+ * @param {string} body
+ * @returns {string}
+ */
+function appendManagedSection(text, body) {
+  const wrapped = wrapSection(body);
+  if (!text) {
+    return wrapped;
+  }
+  const prefix = text.endsWith('\n') ? text : `${text}\n`;
+  return `${prefix}\n${wrapped}`;
+}
+
+/**
+ * Replace only the marked section. Unmarked prose stays byte-identical.
+ * @param {string} text
+ * @param {string} body
+ * @returns {string}
+ */
+function replaceManagedSection(text, body) {
+  if (!hasManagedSection(text)) {
+    return appendManagedSection(text, body);
+  }
+  const start = text.indexOf(BEGIN_MARKER);
+  const end = text.indexOf(END_MARKER) + END_MARKER.length;
+  const after = text.slice(end);
+  const wrapped = wrapSection(body).replace(/\n$/, '');
+  const suffix = after.startsWith('\n') || after.length === 0 ? after : `\n${after}`;
+  return `${text.slice(0, start)}${wrapped}${suffix}`;
+}
+
+module.exports = {
+  wrapSection,
+  extractSection,
+  hasManagedSection,
+  appendManagedSection,
+  replaceManagedSection
+};

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

@@ -0,0 +1,45 @@
+/**
+ * Load bundled Agent Kit package manifest and inventory.
+ * @fileoverview Read templates/agent-kit YAML contracts
+ */
+
+'use strict';
+
+const path = require('path');
+const yaml = require('js-yaml');
+const fs = require('../internal/fs-real-sync');
+const { getKitRoot } = require('./kit-root');
+
+/**
+ * @param {string} relativeName
+ * @returns {object}
+ */
+function loadYamlFromKit(relativeName) {
+  const filePath = path.join(getKitRoot(), relativeName);
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const parsed = yaml.load(raw);
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`Invalid Agent Kit file: ${relativeName} (${typeof raw})`);
+  }
+  return parsed;
+}
+
+/**
+ * @returns {object}
+ */
+function loadKitPackage() {
+  const manifest = loadYamlFromKit('agent-kit.yaml');
+  if (manifest.schemaVersion !== '1' || !manifest.kitVersion) {
+    throw new Error('agent-kit.yaml must declare schemaVersion 1 and kitVersion.');
+  }
+  if (!Array.isArray(manifest.skills) || manifest.skills.length !== 4) {
+    throw new Error('agent-kit.yaml must list exactly four skills.');
+  }
+  return {
+    root: getKitRoot(),
+    manifest,
+    inventory: loadYamlFromKit('parity-inventory.yaml')
+  };
+}
+
+module.exports = { loadKitPackage, loadYamlFromKit };

package/lib/agent-kit/plan-ops.js

@@ -0,0 +1,69 @@
+/**
+ * Map file classification to install/update actions.
+ * @fileoverview Agent Kit action planner
+ */
+
+'use strict';
+
+const { ACTION, FILE_STATE } = require('./constants');
+
+/**
+ * @param {object} item
+ * @param {boolean} force
+ * @returns {string}
+ */
+function actionForInstall(item, force) {
+  if (item.mode === 'if-missing') {
+    return item.fileState === FILE_STATE.MISSING ? ACTION.CREATE : ACTION.SKIP;
+  }
+  if (item.replaceOnInstall) {
+    return ACTION.REPLACE;
+  }
+  const fileState = item.fileState;
+  if (fileState === FILE_STATE.MISSING) {
+    return ACTION.CREATE;
+  }
+  if (fileState === FILE_STATE.UNCHANGED_MANAGED) {
+    return ACTION.SKIP;
+  }
+  if (fileState === FILE_STATE.USER_FILE_NO_MANAGED_SECTION) {
+    return ACTION.APPEND_SECTION;
+  }
+  if (fileState === FILE_STATE.MODIFIED_MANAGED) {
+    return force ? ACTION.REPLACE : ACTION.CONFLICT;
+  }
+  if (fileState === FILE_STATE.OBSOLETE_UNCHANGED_MANAGED) {
+    return ACTION.DELETE;
+  }
+  if (fileState === FILE_STATE.OBSOLETE_MODIFIED_MANAGED) {
+    return ACTION.RETAIN;
+  }
+  return ACTION.SKIP;
+}
+
+/**
+ * @param {object} item
+ * @param {boolean} force
+ * @returns {string}
+ */
+function actionForUpdate(item, force) {
+  if (item.mode === 'if-missing') {
+    return item.fileState === FILE_STATE.MISSING ? ACTION.CREATE : ACTION.SKIP;
+  }
+  if (item.fileState === FILE_STATE.UNCHANGED_MANAGED) {
+    return ACTION.REPLACE;
+  }
+  return actionForInstall({ ...item, replaceOnInstall: item.replaceOnInstall }, force);
+}
+
+/**
+ * @param {object[]} items
+ * @param {(item: object, force: boolean) => string} picker
+ * @param {boolean} force
+ * @returns {object[]}
+ */
+function assignActions(items, picker, force) {
+  return items.map((item) => ({ ...item, action: picker(item, force) }));
+}
+
+module.exports = { actionForInstall, actionForUpdate, assignActions };