@zeyue0329/xiaoma-cli 1.13.0 → 1.15.1

package/tools/installer/cli-utils.js

@@ -0,0 +1,57 @@
+const path = require('node:path');
+const prompts = require('./prompts');
+
+const CLIUtils = {
+  /**
+   * Get version from the repo's package.json (tools/installer/ -> repo root is ../../)
+   */
+  getVersion() {
+    try {
+      const packageJson = require(path.join(__dirname, '..', '..', 'package.json'));
+      return packageJson.version || 'Unknown';
+    } catch {
+      return 'Unknown';
+    }
+  },
+
+  /**
+   * Display XiaoMa logo and version using @clack intro + box
+   */
+  async displayLogo() {
+    const version = this.getVersion();
+    const color = await prompts.getColor();
+
+    // XIAOMA block-letter ASCII art (yellow)
+    const logo = [
+      '  ██╗  ██╗██╗ █████╗  ██████╗ ███╗   ███╗ █████╗',
+      '  ╚██╗██╔╝██║██╔══██╗██╔═══██╗████╗ ████║██╔══██╗',
+      '   ╚███╔╝ ██║███████║██║   ██║██╔████╔██║███████║',
+      '   ██╔██╗ ██║██╔══██║██║   ██║██║╚██╔╝██║██╔══██║',
+      '  ██╔╝ ██╗██║██║  ██║╚██████╔╝██║ ╚═╝ ██║██║  ██║',
+      '  ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝',
+    ]
+      .map((line) => color.yellow(line))
+      .join('\n');
+
+    const tagline = '      AI-Driven Agile Development';
+
+    await prompts.box(`${logo}\n${tagline}`, `v${version}`, {
+      contentAlign: 'center',
+      rounded: true,
+      formatBorder: color.blue,
+    });
+  },
+
+  /**
+   * Display module configuration header
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from module.yaml
+   * @param {string} subheader - Custom subheader from module.yaml
+   */
+  async displayModuleConfigHeader(moduleName, header = null, subheader = null) {
+    const title = header || `Configuring ${moduleName.toUpperCase()} Module`;
+    await prompts.note(subheader || '', title);
+  },
+};
+
+module.exports = { CLIUtils };

package/tools/installer/commands/install.js

@@ -0,0 +1,146 @@
+const path = require('node:path');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
+const { UI } = require('../ui');
+
+const installer = new Installer();
+const ui = new UI();
+
+module.exports = {
+  command: 'install',
+  description: 'Install XiaoMa Core agents and tools',
+  options: [
+    ['-d, --debug', 'Enable debug output for manifest generation'],
+    ['--directory <path>', 'Installation directory (default: current directory)'],
+    ['--modules <modules>', 'Comma-separated list of module IDs to install (e.g., "xmc,xpm")'],
+    [
+      '--tools <tools>',
+      'Comma-separated list of tool/IDE IDs to configure (e.g., "claude-code,cursor"). Required for fresh non-interactive (--yes) installs. Run with --list-tools to see all valid IDs.',
+    ],
+    ['--list-tools', 'Print all supported tool/IDE IDs (with target directories) and exit.'],
+    [
+      '--set <spec>',
+      'Set a module config option non-interactively. Spec format: <module>.<key>=<value> (e.g. xmc.project_knowledge=research). Repeatable. Run --list-options to see available keys.',
+      (value, prev) => [...(prev || []), value],
+      [],
+    ],
+    [
+      '--list-options [module]',
+      'List available --set keys for all locally-known official modules, or for a single module by code, then exit.',
+    ],
+    ['--action <type>', 'Action type for existing installations: install, update, or quick-update'],
+    ['--user-name <name>', 'Name for agents to use (default: system username)'],
+    ['--communication-language <lang>', 'Language for agent communication (default: English)'],
+    ['--document-output-language <lang>', 'Language for document output (default: English)'],
+    ['--output-folder <path>', 'Output folder path relative to project root (default: _xiaoma-output)'],
+    ['--custom-source <sources>', 'Comma-separated Git URLs or local paths to install custom modules from'],
+    ['-y, --yes', 'Accept all defaults and skip prompts where possible'],
+    [
+      '--channel <channel>',
+      'Apply channel (stable|next) to all external modules being installed. --all-stable and --all-next are aliases.',
+    ],
+    ['--all-stable', 'Alias for --channel=stable. Resolves externals to the highest stable release tag.'],
+    ['--all-next', 'Alias for --channel=next. Resolves externals to main HEAD.'],
+    ['--next <code>', 'Install module <code> from main HEAD (next channel). Repeatable.', (value, prev) => [...(prev || []), value], []],
+    [
+      '--pin <spec>',
+      'Pin an external/custom module to a specific tag: --pin CODE=TAG (e.g. --pin my-module=v1.0.0). Repeatable.',
+      (value, prev) => [...(prev || []), value],
+      [],
+    ],
+  ],
+  action: async (options) => {
+    try {
+      if (options.listTools) {
+        const { formatPlatformList } = require('../ide/platform-codes');
+        process.stdout.write((await formatPlatformList()) + '\n');
+        process.exit(0);
+      }
+
+      if (options.listOptions !== undefined) {
+        const { formatOptionsList } = require('../list-options');
+        const moduleArg = options.listOptions === true ? null : options.listOptions;
+        const { text, ok } = await formatOptionsList(moduleArg);
+        const stream = ok ? process.stdout : process.stderr;
+        // process.exit() forces immediate termination and can truncate the
+        // buffered write when stdout/stderr is piped or captured by CI. Wait
+        // for the write to flush, then set process.exitCode and return so the
+        // event loop drains naturally. Non-zero exit when a single-module
+        // lookup misses so a CI typo like `--list-options bmn` doesn't look
+        // successful in scripts.
+        await new Promise((resolve, reject) => {
+          stream.write(text + '\n', (error) => (error ? reject(error) : resolve()));
+        });
+        process.exitCode = ok ? 0 : 1;
+        return;
+      }
+
+      // Set debug flag as environment variable for all components
+      if (options.debug) {
+        process.env.XiaoMa_DEBUG_MANIFEST = 'true';
+        await prompts.log.info('Debug mode enabled');
+      }
+
+      // Validate --set syntax up-front so malformed entries fail fast,
+      // before we touch the network or filesystem. Parsed entries are
+      // re-derived inside ui.js where overrides are seeded.
+      if (options.set && options.set.length > 0) {
+        const { parseSetEntries } = require('../set-overrides');
+        try {
+          parseSetEntries(options.set);
+        } catch (error) {
+          await prompts.log.error(error.message);
+          process.exit(1);
+        }
+      }
+
+      const config = await ui.promptInstall(options);
+
+      // Handle cancel
+      if (config.actionType === 'cancel') {
+        await prompts.log.warn('Installation cancelled.');
+        process.exit(0);
+      }
+
+      // Handle quick update separately. --set is a post-install TOML patch so
+      // it works the same way for quick-update as for a regular install — the
+      // installer runs, then `applySetOverrides` patches the central config
+      // files. Pass the parsed overrides through.
+      if (config.actionType === 'quick-update') {
+        const { parseSetEntries } = require('../set-overrides');
+        config.setOverrides = parseSetEntries(options.set || []);
+        const result = await installer.quickUpdate(config);
+        await prompts.log.success('Quick update complete!');
+        await prompts.log.info(`Updated ${result.moduleCount} modules with preserved settings (${result.modules.join(', ')})`);
+        process.exit(0);
+      }
+
+      // Regular install/update flow
+      const result = await installer.install(config);
+
+      // Check if installation was cancelled
+      if (result && result.cancelled) {
+        process.exit(0);
+      }
+
+      // Check if installation succeeded
+      if (result && result.success) {
+        process.exit(0);
+      }
+    } catch (error) {
+      try {
+        if (error.fullMessage) {
+          await prompts.log.error(error.fullMessage);
+        } else {
+          await prompts.log.error(`Installation failed: ${error.message}`);
+        }
+        if (error.stack && !error.expected) {
+          await prompts.log.message(error.stack);
+        }
+      } catch {
+        console.error(error.fullMessage || error.message || error);
+      }
+      process.exit(1);
+    }
+  },
+};

package/tools/{cli → installer}/commands/status.js

@@ -1,8 +1,8 @@
 const path = require('node:path');
-const prompts = require('../lib/prompts');
-const { Installer } = require('../installers/lib/core/installer');
-const { Manifest } = require('../installers/lib/core/manifest');
-const { UI } = require('../lib/ui');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
+const { Manifest } = require('../core/manifest');
+const { UI } = require('../ui');
 
 const installer = new Installer();
 const manifest = new Manifest();
@@ -11,15 +11,23 @@ const ui = new UI();
 module.exports = {
   command: 'status',
   description: 'Display XiaoMa installation status and module versions',
-  options: [],
+  options: [['--directory <path>', 'Project directory (default: current directory)']],
   action: async (options) => {
     try {
+      const fs = require('../fs-native');
+
+      // Resolve the target project directory (--directory takes precedence over CWD)
+      const projectDir = options.directory ? path.resolve(options.directory) : process.cwd();
+      if (!(await fs.pathExists(projectDir))) {
+        await prompts.log.error(`Directory does not exist: ${projectDir}`);
+        process.exit(1);
+        return;
+      }
+
       // Find the xiaoma directory
-      const projectDir = process.cwd();
       const { xiaomaDir } = await installer.findXiaomaDir(projectDir);
 
       // Check if xiaoma directory exists
-      const fs = require('fs-extra');
       if (!(await fs.pathExists(xiaomaDir))) {
         await prompts.log.warn('No XiaoMa installation found in the current directory.');
         await prompts.log.message(`Expected location: ${xiaomaDir}`);

package/tools/{cli → installer}/commands/uninstall.js

@@ -1,7 +1,7 @@
 const path = require('node:path');
-const fs = require('fs-extra');
-const prompts = require('../lib/prompts');
-const { Installer } = require('../installers/lib/core/installer');
+const fs = require('../fs-native');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
 
 const installer = new Installer();
 
@@ -62,9 +62,9 @@ module.exports = {
       }
 
       const existingInstall = await installer.getStatus(projectDir);
-      const version = existingInstall.version || 'unknown';
-      const modules = (existingInstall.modules || []).map((m) => m.id || m.name).join(', ');
-      const ides = (existingInstall.ides || []).join(', ');
+      const version = existingInstall.installed ? existingInstall.version : 'unknown';
+      const modules = existingInstall.moduleIds.join(', ');
+      const ides = existingInstall.ides.join(', ');
 
       const outputFolder = await installer.getOutputFolder(projectDir);
 
@@ -148,7 +148,7 @@ module.exports = {
       if (!removeOutputFolder) summary.push(`User artifacts preserved in ${outputFolder}/`);
 
       await prompts.note(summary.join('\n'), 'Summary');
-      await prompts.outro('To reinstall, run: npx xiaoma-cli install');
+      await prompts.outro('To reinstall, run: npx @zeyue0329/xiaoma-cli install');
 
       process.exit(0);
     } catch (error) {

package/tools/installer/core/config.js

@@ -0,0 +1,73 @@
+/**
+ * Clean install configuration built from user input.
+ * User input comes from either UI answers or headless CLI flags.
+ */
+class Config {
+  constructor({
+    directory,
+    modules,
+    ides,
+    skipPrompts,
+    verbose,
+    actionType,
+    coreConfig,
+    moduleConfigs,
+    quickUpdate,
+    channelOptions,
+    setOverrides,
+  }) {
+    this.directory = directory;
+    this.modules = Object.freeze([...modules]);
+    this.ides = Object.freeze([...ides]);
+    this.skipPrompts = skipPrompts;
+    this.verbose = verbose;
+    this.actionType = actionType;
+    this.coreConfig = coreConfig;
+    this.moduleConfigs = moduleConfigs;
+    this._quickUpdate = quickUpdate;
+    // channelOptions carry a Map + Set; don't deep-freeze.
+    this.channelOptions = channelOptions || null;
+    // Parsed `--set <module>.<key>=<value>` overrides, applied as a TOML
+    // patch AFTER the install finishes. Shape: { moduleCode: { key: value } }.
+    // Intentionally NOT integrated with the prompt/template/schema flow; see
+    // `tools/installer/set-overrides.js` for the rationale and tradeoffs.
+    this.setOverrides = setOverrides || {};
+    Object.freeze(this);
+  }
+
+  /**
+   * Build a clean install config from raw user input.
+   * @param {Object} userInput - UI answers or CLI flags
+   * @returns {Config}
+   */
+  static build(userInput) {
+    const modules = [...(userInput.modules || [])];
+    if (userInput.installCore && !modules.includes('core')) {
+      modules.unshift('core');
+    }
+
+    return new Config({
+      directory: userInput.directory,
+      modules,
+      ides: userInput.skipIde ? [] : [...(userInput.ides || [])],
+      skipPrompts: userInput.skipPrompts || false,
+      verbose: userInput.verbose || false,
+      actionType: userInput.actionType,
+      coreConfig: userInput.coreConfig || {},
+      moduleConfigs: userInput.moduleConfigs || null,
+      quickUpdate: userInput._quickUpdate || false,
+      channelOptions: userInput.channelOptions || null,
+      setOverrides: userInput.setOverrides || {},
+    });
+  }
+
+  hasCoreConfig() {
+    return this.coreConfig && Object.keys(this.coreConfig).length > 0;
+  }
+
+  isQuickUpdate() {
+    return this._quickUpdate;
+  }
+}
+
+module.exports = { Config };

package/tools/installer/core/existing-install.js

@@ -0,0 +1,121 @@
+const path = require('node:path');
+const fs = require('../fs-native');
+const yaml = require('yaml');
+const { Manifest } = require('./manifest');
+
+/**
+ * Immutable snapshot of an existing XiaoMa installation.
+ * Pure query object — no filesystem operations after construction.
+ */
+class ExistingInstall {
+  #version;
+
+  constructor({ installed, version, hasCore, modules, ides }) {
+    this.installed = installed;
+    this.#version = version;
+    this.hasCore = hasCore;
+    this.modules = Object.freeze(modules.map((m) => Object.freeze({ ...m })));
+    this.moduleIds = Object.freeze(this.modules.map((m) => m.id));
+    this.ides = Object.freeze([...ides]);
+    Object.freeze(this);
+  }
+
+  get version() {
+    if (!this.installed) {
+      throw new Error('version is not available when nothing is installed');
+    }
+    return this.#version;
+  }
+
+  static empty() {
+    return new ExistingInstall({
+      installed: false,
+      version: null,
+      hasCore: false,
+      modules: [],
+      ides: [],
+    });
+  }
+
+  /**
+   * Scan a xiaoma directory and return an immutable snapshot of what's installed.
+   * @param {string} xiaomaDir - Path to xiaoma directory
+   * @returns {Promise<ExistingInstall>}
+   */
+  static async detect(xiaomaDir) {
+    if (!(await fs.pathExists(xiaomaDir))) {
+      return ExistingInstall.empty();
+    }
+
+    let version = null;
+    let hasCore = false;
+    const modules = [];
+    let ides = [];
+
+    const manifest = new Manifest();
+    const manifestData = await manifest.read(xiaomaDir);
+    if (manifestData) {
+      version = manifestData.version;
+      if (manifestData.ides) {
+        ides = manifestData.ides.filter((ide) => ide && typeof ide === 'string');
+      }
+    }
+
+    const corePath = path.join(xiaomaDir, 'core');
+    if (await fs.pathExists(corePath)) {
+      hasCore = true;
+
+      if (!version) {
+        const coreConfigPath = path.join(corePath, 'config.yaml');
+        if (await fs.pathExists(coreConfigPath)) {
+          try {
+            const configContent = await fs.readFile(coreConfigPath, 'utf8');
+            const config = yaml.parse(configContent);
+            if (config.version) {
+              version = config.version;
+            }
+          } catch {
+            // Ignore config read errors
+          }
+        }
+      }
+    }
+
+    if (manifestData && manifestData.modules && manifestData.modules.length > 0) {
+      for (const moduleId of manifestData.modules) {
+        const modulePath = path.join(xiaomaDir, moduleId);
+        const moduleConfigPath = path.join(modulePath, 'config.yaml');
+
+        const moduleInfo = {
+          id: moduleId,
+          path: modulePath,
+          version: 'unknown',
+        };
+
+        if (await fs.pathExists(moduleConfigPath)) {
+          try {
+            const configContent = await fs.readFile(moduleConfigPath, 'utf8');
+            const config = yaml.parse(configContent);
+            moduleInfo.version = config.version || 'unknown';
+            moduleInfo.name = config.name || moduleId;
+            moduleInfo.description = config.description;
+          } catch {
+            // Ignore config read errors
+          }
+        }
+
+        modules.push(moduleInfo);
+      }
+    }
+
+    const installed = hasCore || modules.length > 0 || !!manifestData;
+
+    if (!installed) {
+      return ExistingInstall.empty();
+    }
+
+    return new ExistingInstall({ installed, version, hasCore, modules, ides });
+  }
+}
+
+module.exports = { ExistingInstall };

package/tools/installer/core/install-paths.js

@@ -0,0 +1,132 @@
+const path = require('node:path');
+const fs = require('../fs-native');
+const { getProjectRoot } = require('../project-root');
+const { XiaoMa_FOLDER_NAME } = require('../ide/shared/path-utils');
+
+class InstallPaths {
+  static async create(config) {
+    const srcDir = getProjectRoot();
+    await assertReadableDir(srcDir, 'XiaoMa source root');
+
+    const pkgPath = path.join(srcDir, 'package.json');
+    await assertReadableFile(pkgPath, 'package.json');
+    const version = require(pkgPath).version;
+
+    const projectRoot = path.resolve(config.directory);
+    await ensureWritableDir(projectRoot, 'project root');
+
+    const xiaomaDir = path.join(projectRoot, XiaoMa_FOLDER_NAME);
+    const isUpdate = await fs.pathExists(xiaomaDir);
+
+    const configDir = path.join(xiaomaDir, '_config');
+    const coreDir = path.join(xiaomaDir, 'core');
+    const scriptsDir = path.join(xiaomaDir, 'scripts');
+    const customDir = path.join(xiaomaDir, 'custom');
+
+    for (const [dir, label] of [
+      [xiaomaDir, 'xiaoma directory'],
+      [configDir, 'config directory'],
+      [coreDir, 'core module directory'],
+      [scriptsDir, 'shared scripts directory'],
+      [customDir, 'customizations directory'],
+    ]) {
+      await ensureWritableDir(dir, label);
+    }
+
+    return new InstallPaths({
+      srcDir,
+      version,
+      projectRoot,
+      xiaomaDir,
+      configDir,
+      coreDir,
+      scriptsDir,
+      customDir,
+      isUpdate,
+    });
+  }
+
+  constructor(props) {
+    Object.assign(this, props);
+    Object.freeze(this);
+  }
+
+  manifestFile() {
+    return path.join(this.configDir, 'manifest.yaml');
+  }
+  centralConfig() {
+    return path.join(this.xiaomaDir, 'config.toml');
+  }
+  centralUserConfig() {
+    return path.join(this.xiaomaDir, 'config.user.toml');
+  }
+  filesManifest() {
+    return path.join(this.configDir, 'files-manifest.csv');
+  }
+  helpCatalog() {
+    return path.join(this.configDir, 'xiaoma-help.csv');
+  }
+  moduleDir(name) {
+    return path.join(this.xiaomaDir, name);
+  }
+  moduleConfig(name) {
+    return path.join(this.xiaomaDir, name, 'config.yaml');
+  }
+}
+
+async function assertReadableDir(dirPath, label) {
+  const stat = await fs.stat(dirPath).catch(() => null);
+  if (!stat) {
+    throw new Error(`${label} does not exist: ${dirPath}`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`${label} is not a directory: ${dirPath}`);
+  }
+  try {
+    await fs.access(dirPath, fs.constants.R_OK);
+  } catch {
+    throw new Error(`${label} is not readable: ${dirPath}`);
+  }
+}
+
+async function assertReadableFile(filePath, label) {
+  const stat = await fs.stat(filePath).catch(() => null);
+  if (!stat) {
+    throw new Error(`${label} does not exist: ${filePath}`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`${label} is not a file: ${filePath}`);
+  }
+  try {
+    await fs.access(filePath, fs.constants.R_OK);
+  } catch {
+    throw new Error(`${label} is not readable: ${filePath}`);
+  }
+}
+
+async function ensureWritableDir(dirPath, label) {
+  const stat = await fs.stat(dirPath).catch(() => null);
+  if (stat && !stat.isDirectory()) {
+    throw new Error(`${label} exists but is not a directory: ${dirPath}`);
+  }
+
+  try {
+    await fs.ensureDir(dirPath);
+  } catch (error) {
+    if (error.code === 'EACCES') {
+      throw new Error(`${label}: permission denied creating directory: ${dirPath}`);
+    }
+    if (error.code === 'ENOSPC') {
+      throw new Error(`${label}: no space left on device: ${dirPath}`);
+    }
+    throw new Error(`${label}: cannot create directory: ${dirPath} (${error.message})`);
+  }
+
+  try {
+    await fs.access(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+  } catch {
+    throw new Error(`${label} is not writable: ${dirPath}`);
+  }
+}
+
+module.exports = { InstallPaths };