@aifabrix/builder 2.53.1 → 2.55.0

package/lib/commands/agent-kit.js

@@ -0,0 +1,346 @@
+/**
+ * `aifabrix agent-kit` command group.
+ * @fileoverview Install, init, status, update, validate, remote create
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { formatSuccessLine, formatBlockingError, formatWarningLine } = require('../utils/cli-layout-chalk');
+const { runInstall, runUpdate } = require('../agent-kit/run');
+const path = require('path');
+const { runInit, runRemoteCreate } = require('../agent-kit/init');
+const { enrichInitHostOptions, enrichInitRemoteOptions, enrichRemoteOptions, enrichApproveAllOptions } = require('../agent-kit/remote-prompts');
+const { hostLabel } = require('../agent-kit/hosts');
+const { runStatus } = require('../agent-kit/status');
+const { runValidate } = require('../agent-kit/validate-kit');
+const { formatHumanStatus } = require('../agent-kit/report');
+const { KIT_STATE } = require('../agent-kit/constants');
+const { loadState } = require('../agent-kit/state-file');
+const { resolveGitRoot } = require('../agent-kit/repo-guard');
+const {
+  GROUP_HELP,
+  INSTALL_HELP,
+  STATUS_HELP,
+  UPDATE_HELP,
+  VALIDATE_HELP,
+  INIT_HELP,
+  REMOTE_HELP
+} = require('./agent-kit-help');
+
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  logger.log(formatHumanStatus(json));
+  if (json.conflicts && json.conflicts.length) {
+    logger.log(formatWarningLine(`Conflicts: ${json.conflicts.join(', ')}`));
+  }
+}
+
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitInitReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  logger.log('AI Fabrix workspace init');
+  logger.log(`Path       ${json.path}`);
+  logger.log(`Name       ${json.name}`);
+  logger.log(`SCM        ${json.scm}`);
+  if (json.hosts && json.hosts.length) {
+    logger.log(`Hosts      ${json.hosts.map((h) => hostLabel(h)).join(', ')}`);
+  }
+  if (json.kit) {
+    logger.log(`Agent Kit  ${json.kit.kitVersion} (${json.kit.state})`);
+  }
+  if (json.remote && !json.remote.skipped) {
+    logger.log(`Remote     ${json.remote.provider}:${json.remote.fullName} (${json.remote.visibility})`);
+  } else {
+    logger.log('Remote     skipped (use: aifabrix agent-kit remote create)');
+  }
+  logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Done'));
+}
+
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitRemoteReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  if (json.remote && json.remote.skipped) {
+    logger.log(formatWarningLine(`Remote skipped: ${json.remote.reason || 'already configured'}`));
+  } else if (json.remote) {
+    logger.log(`Remote     ${json.remote.provider}:${json.remote.fullName} (${json.remote.visibility})`);
+  }
+  logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Done'));
+}
+
+/**
+ * @param {Function} runner
+ * @param {object} options
+ * @param {boolean} [failOnConflict]
+ * @returns {Promise<void>}
+ */
+async function runLeaf(runner, options, failOnConflict) {
+  const json = runner(options);
+  emitReport(json, Boolean(options.json));
+  if (failOnConflict && json.conflicts && json.conflicts.length) {
+    logger.error(formatBlockingError('Managed files were modified locally. Re-run with --force to replace kit-owned content only.'));
+    process.exitCode = 1;
+    return;
+  }
+  if (!options.json && json.state && json.state !== KIT_STATE.NOT_INSTALLED) {
+    logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Done'));
+  }
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupAgentKitCommands(program) {
+  const group = program
+    .command('agent-kit')
+    .description('Install, init, and update the AI Fabrix Agent Kit in a customer workspace')
+    .addHelpText('after', GROUP_HELP);
+
+  addInitCommand(group);
+  addInstallCommand(group);
+  addStatusCommand(group);
+  addUpdateCommand(group);
+  addValidateCommand(group);
+  addRemoteCommand(group);
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addInitCommand(group) {
+  group
+    .command('init [nameOrPath]')
+    .description('Create a customer workspace skeleton, git repo, and Agent Kit')
+    .option('--host <target>', 'all, cursor, codex, or claude (omit on TTY to choose)', 'all')
+    .option('--scm <kind>', 'git or none', 'git')
+    .option('--remote', 'Create private hosting remote and push (requires auth)')
+    .option('--no-remote', 'Force local-only (skip remote prompt on TTY)')
+    .option('--org <owner>', 'Hosting org or user (required with --remote when non-TTY)')
+    .option('--visibility <mode>', 'private or public', 'private')
+    .option('--license <kind>', 'mit or none', 'none')
+    .option('--force', 'Allow non-empty target directory')
+    .option('--yes', 'Silent: skip TTY confirm (pair with --host and --org); also auto-approves host permissions')
+    .option('--approve-all', 'Write Claude Code and Codex auto-approve configs')
+    .option('--skip-approve-all', 'Do not write Claude Code or Codex auto-approve configs')
+    .option('--dry-run', 'Plan writes without changing files')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', INIT_HELP)
+    .action(async(nameOrPath, options) => {
+      try {
+        const interactive = Boolean(process.stdout.isTTY) && !options.json;
+        const withHost = await enrichInitHostOptions(
+          { ...options, nameOrPath },
+          { interactive }
+        );
+        const withApprove = await enrichApproveAllOptions(withHost, { interactive });
+        const merged = await enrichInitRemoteOptions(withApprove, {
+          interactive,
+          workspaceName: path.basename(String(nameOrPath || 'workspace'))
+        });
+        if (merged.cancelled) {
+          logger.log('Cancelled.');
+          return;
+        }
+        const json = runInit(merged);
+        emitInitReport(json, Boolean(options.json));
+      } catch (error) {
+        handleCommandError(error, 'agent-kit init');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addRemoteCommand(group) {
+  const remote = group.command('remote').description('Hosting remotes for an Agent Kit workspace');
+  remote
+    .command('create')
+    .description('Create a private GitHub remote and push the current workspace')
+    .option('--org <owner>', 'Hosting org or user (required when non-TTY)')
+    .option('--name <repo>', 'Remote repository name (default: directory basename)')
+    .option('--visibility <mode>', 'private or public', 'private')
+    .option('--yes', 'Silent: skip TTY confirmation (pair with --org)')
+    .option('--dry-run', 'Plan without creating the remote')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', REMOTE_HELP)
+    .action(async(options) => {
+      try {
+        const interactive = Boolean(process.stdout.isTTY) && !options.json;
+        const merged = await enrichRemoteOptions(options, {
+          interactive,
+          name: options.name || path.basename(process.cwd())
+        });
+        if (merged.cancelled) {
+          logger.log('Cancelled.');
+          return;
+        }
+        const json = runRemoteCreate(merged);
+        emitRemoteReport(json, Boolean(options.json));
+      } catch (error) {
+        handleCommandError(error, 'agent-kit remote create');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addInstallCommand(group) {
+  group
+    .command('install')
+    .description('Install the Agent Kit into the current git repository')
+    .option('--host <target>', 'all, cursor, codex, or claude', 'all')
+    .option('--approve-all', 'Write Claude Code and Codex auto-approve configs')
+    .option('--skip-approve-all', 'Do not write Claude Code or Codex auto-approve configs')
+    .option('--yes', 'Silent: auto-approve host permission configs without asking')
+    .option('--dry-run', 'Plan writes without changing files')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', INSTALL_HELP)
+    .action(async(options) => {
+      try {
+        const interactive = Boolean(process.stdout.isTTY) && !options.json;
+        const merged = await enrichApproveAllOptions(options, { interactive });
+        await runLeaf(runInstall, merged, true);
+      } catch (error) {
+        handleCommandError(error, 'agent-kit install');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addStatusCommand(group) {
+  group
+    .command('status')
+    .description('Show installed Agent Kit version and file state')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', STATUS_HELP)
+    .action(async(options) => {
+      try {
+        await runLeaf(runStatus, options, false);
+      } catch (error) {
+        handleCommandError(error, 'agent-kit status');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * Recorded --host from a previous install (update omits --host to keep this).
+ * @returns {string[]|undefined}
+ */
+function readRecordedHosts() {
+  try {
+    const state = loadState(resolveGitRoot(process.cwd()));
+    if (state && Array.isArray(state.hosts) && state.hosts.length) {
+      return state.hosts;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Update does not prompt or auto-write host configs unless flags are set.
+ * @param {object} options
+ * @returns {Promise<object>}
+ */
+async function mergeUpdateApproveOptions(options) {
+  const interactive = Boolean(process.stdout.isTTY) && !options.json;
+  const host = options.host || readRecordedHosts();
+  return enrichApproveAllOptions({ ...options, host }, { interactive, ask: false });
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addUpdateCommand(group) {
+  group
+    .command('update')
+    .description('Update managed Agent Kit files from this Builder release')
+    .option('--host <target>', 'all, cursor, codex, or claude (omit to keep recorded hosts)')
+    .option('--approve-all', 'Write Claude Code and Codex auto-approve configs')
+    .option('--skip-approve-all', 'Do not write Claude Code or Codex auto-approve configs')
+    .option('--yes', 'Silent: auto-approve host permission configs without asking')
+    .option('--dry-run', 'Plan writes without changing files')
+    .option('--force', 'Replace modified kit-owned files and managed sections')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', UPDATE_HELP)
+    .action(async(options) => {
+      try {
+        const merged = await mergeUpdateApproveOptions(options);
+        await runLeaf(runUpdate, merged, !options.force);
+      } catch (error) {
+        handleCommandError(error, 'agent-kit update');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addValidateCommand(group) {
+  group
+    .command('validate')
+    .description('Validate the bundled Agent Kit and the current repository install')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', VALIDATE_HELP)
+    .action(async(options) => {
+      try {
+        await runValidateLeaf(options);
+      } catch (error) {
+        handleCommandError(error, 'agent-kit validate');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * @param {object} options
+ * @returns {Promise<void>}
+ */
+async function runValidateLeaf(options) {
+  const json = runValidate(options);
+  if (options.json) {
+    logger.log(JSON.stringify(json, null, 2));
+  } else if (json.success) {
+    logger.log(formatSuccessLine(`Agent Kit ${json.kitVersion} is valid`));
+  } else {
+    logger.error(formatBlockingError(json.errors.join('; ')));
+  }
+  if (!json.success) {
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { setupAgentKitCommands };