@hexabot-ai/cli 3.0.0-alpha.3

package/src/core/config.ts

@@ -0,0 +1,127 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import chalk from 'chalk';
+
+import type { PackageManager } from './package-manager.js';
+
+export interface DockerConfig {
+  composeFile: string;
+  defaultServices: string[];
+}
+
+export interface EnvConfig {
+  local: string;
+  localExample: string;
+  docker: string;
+  dockerExample: string;
+}
+
+export interface HexabotConfig {
+  devScript: string;
+  startScript: string;
+  packageManager?: PackageManager;
+  docker: DockerConfig;
+  env: EnvConfig;
+}
+
+const CONFIG_FILE_NAME = 'hexabot.config.json';
+const DEFAULT_CONFIG: HexabotConfig = {
+  devScript: 'dev',
+  startScript: 'start',
+  docker: {
+    composeFile: 'docker/docker-compose.yml',
+    defaultServices: [],
+  },
+  env: {
+    local: '.env',
+    localExample: '.env.example',
+    docker: '.env.docker',
+    dockerExample: '.env.docker.example',
+  },
+};
+
+export const resolveConfigPath = (projectRoot = process.cwd()) => {
+  return path.join(projectRoot, CONFIG_FILE_NAME);
+};
+
+export const loadProjectConfig = (projectRoot = process.cwd()) => {
+  const configPath = resolveConfigPath(projectRoot);
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<HexabotConfig>;
+
+    return mergeConfig(DEFAULT_CONFIG, parsed);
+  } catch (error) {
+    console.warn(chalk.yellow('Invalid hexabot.config.json. Using defaults.'));
+    console.warn(chalk.yellow((error as Error).message));
+
+    return { ...DEFAULT_CONFIG };
+  }
+};
+
+export const ensureProjectConfig = (
+  projectRoot = process.cwd(),
+  overrides: Partial<HexabotConfig> = {},
+) => {
+  const configPath = resolveConfigPath(projectRoot);
+  if (!fs.existsSync(configPath)) {
+    const config = mergeConfig(DEFAULT_CONFIG, overrides);
+    writeProjectConfig(config, projectRoot);
+
+    return config;
+  }
+
+  if (Object.keys(overrides).length > 0) {
+    return updateProjectConfig(projectRoot, overrides);
+  }
+
+  return loadProjectConfig(projectRoot);
+};
+
+export const writeProjectConfig = (
+  config: HexabotConfig,
+  projectRoot = process.cwd(),
+) => {
+  const configPath = resolveConfigPath(projectRoot);
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+};
+
+export const updateProjectConfig = (
+  projectRoot: string,
+  overrides: Partial<HexabotConfig>,
+) => {
+  const existing = loadProjectConfig(projectRoot);
+  const next = mergeConfig(existing, overrides);
+  writeProjectConfig(next, projectRoot);
+
+  return next;
+};
+
+const mergeConfig = (
+  base: HexabotConfig,
+  overrides: Partial<HexabotConfig>,
+): HexabotConfig => {
+  return {
+    ...base,
+    ...overrides,
+    docker: {
+      ...base.docker,
+      ...(overrides.docker || {}),
+    },
+    env: {
+      ...base.env,
+      ...(overrides.env || {}),
+    },
+  };
+};

package/src/core/docker.ts

@@ -0,0 +1,91 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import chalk from 'chalk';
+
+export type ComposeMode = 'dev' | 'prod';
+
+export const resolveComposeFile = (projectRoot: string, filePath: string) => {
+  return path.isAbsolute(filePath)
+    ? filePath
+    : path.join(projectRoot, filePath);
+};
+
+export const generateComposeFiles = (
+  baseComposeFile: string,
+  services: string[],
+  mode?: ComposeMode,
+) => {
+  if (!fs.existsSync(baseComposeFile)) {
+    console.error(
+      chalk.red(
+        `Docker compose file not found at ${baseComposeFile}. Update hexabot.config.json.`,
+      ),
+    );
+    process.exit(1);
+  }
+
+  const composeDir = path.dirname(baseComposeFile);
+  const files = [`-f ${baseComposeFile}`];
+
+  services.forEach((service) => {
+    const serviceFile = path.join(composeDir, `docker-compose.${service}.yml`);
+    if (fs.existsSync(serviceFile)) {
+      files.push(`-f ${serviceFile}`);
+    }
+    if (mode) {
+      const serviceModeFile = path.join(
+        composeDir,
+        `docker-compose.${service}.${mode}.yml`,
+      );
+      if (fs.existsSync(serviceModeFile)) {
+        files.push(`-f ${serviceModeFile}`);
+      }
+    }
+  });
+
+  if (mode) {
+    const modeFile = path.join(composeDir, `docker-compose.${mode}.yml`);
+    if (fs.existsSync(modeFile)) {
+      files.push(`-f ${modeFile}`);
+    }
+  }
+
+  return files.join(' ');
+};
+
+export const dockerCompose = (args: string) => {
+  try {
+    const cmd = `docker compose ${args}`;
+    console.log(chalk.yellow(cmd));
+    execSync(cmd, { stdio: 'inherit' });
+  } catch (_error) {
+    console.error(chalk.red('Error executing Docker Compose command.'));
+    process.exit(1);
+  }
+};
+
+export const dockerExec = (
+  container: string,
+  command: string,
+  options?: string,
+) => {
+  try {
+    const optionalArgs = options ? `${options} ` : '';
+    const cmd = `docker exec -it ${optionalArgs}${container} ${command}`;
+    console.log(chalk.bgYellow(cmd));
+    execSync(cmd, {
+      stdio: 'inherit',
+    });
+  } catch (_error) {
+    console.error(chalk.red('Error executing Docker Exec command.'));
+    process.exit(1);
+  }
+};

package/src/core/env.ts

@@ -0,0 +1,90 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import chalk from 'chalk';
+
+import type { HexabotConfig } from './config.js';
+
+export interface EnvBootstrapOptions {
+  force?: boolean;
+  quiet?: boolean;
+}
+
+export const bootstrapEnvFile = (
+  projectRoot: string,
+  exampleFile: string,
+  targetFile: string,
+  options: EnvBootstrapOptions = {},
+) => {
+  const examplePath = path.join(projectRoot, exampleFile);
+  const targetPath = path.join(projectRoot, targetFile);
+
+  if (!fs.existsSync(examplePath)) {
+    console.log(
+      chalk.yellow(
+        `Example env file "${exampleFile}" is missing. Skipping bootstrap.`,
+      ),
+    );
+
+    return false;
+  }
+
+  if (!options.force && fs.existsSync(targetPath)) {
+    if (!options.quiet) {
+      console.log(
+        chalk.gray(
+          `Env file "${targetFile}" already exists. Use --force to overwrite.`,
+        ),
+      );
+    }
+
+    return false;
+  }
+
+  fs.copyFileSync(examplePath, targetPath);
+  if (!options.quiet) {
+    console.log(
+      chalk.green(`Generated ${targetFile} from ${exampleFile}. Customize it!`),
+    );
+  }
+
+  return true;
+};
+
+export const listEnvStatus = (projectRoot: string, config: HexabotConfig) => {
+  const entries = [
+    config.env.localExample,
+    config.env.local,
+    config.env.dockerExample,
+    config.env.docker,
+  ];
+
+  return entries.map((file) => ({
+    file,
+    path: path.join(projectRoot, file),
+    exists: fs.existsSync(path.join(projectRoot, file)),
+  }));
+};
+
+export const resolveEnvExample = (
+  projectRoot: string,
+  envFile: string | undefined,
+  defaultExample: string,
+) => {
+  if (!envFile) {
+    return defaultExample;
+  }
+
+  const candidate = `${envFile}.example`;
+  if (fs.existsSync(path.join(projectRoot, candidate))) {
+    return candidate;
+  }
+
+  return defaultExample;
+};

package/src/core/package-manager.ts

@@ -0,0 +1,126 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import chalk from 'chalk';
+
+import { readPackageJson } from './project.js';
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+
+const PACKAGE_MANAGER_LOCKFILES: Record<PackageManager, string> = {
+  npm: 'package-lock.json',
+  pnpm: 'pnpm-lock.yaml',
+  yarn: 'yarn.lock',
+  bun: 'bun.lockb',
+};
+
+export const normalizePackageManager = (value?: string) => {
+  if (!value) {
+    return undefined;
+  }
+
+  const normalized = value.toLowerCase() as PackageManager;
+  if (!Object.keys(PACKAGE_MANAGER_LOCKFILES).includes(normalized)) {
+    console.error(
+      chalk.red(
+        `Unsupported package manager "${value}". Use npm, pnpm, yarn, or bun.`,
+      ),
+    );
+    process.exit(1);
+  }
+
+  return normalized;
+};
+
+export const detectPackageManager = (projectRoot = process.cwd()) => {
+  const entries = Object.entries(PACKAGE_MANAGER_LOCKFILES) as [
+    PackageManager,
+    string,
+  ][];
+
+  for (const [pm, lockfile] of entries) {
+    if (fs.existsSync(path.join(projectRoot, lockfile))) {
+      return pm;
+    }
+  }
+
+  return 'npm';
+};
+
+export const installDependencies = (
+  pm: PackageManager,
+  projectRoot = process.cwd(),
+) => {
+  const command = getInstallCommand(pm);
+  runCommand(command, projectRoot);
+};
+
+export const runPackageScript = (
+  pm: PackageManager,
+  script: string,
+  projectRoot = process.cwd(),
+  scriptArgs: string[] = [],
+) => {
+  ensureScriptExists(script, projectRoot);
+  const command = getRunScriptCommand(pm, script, scriptArgs);
+  runCommand(command, projectRoot);
+};
+
+const ensureScriptExists = (script: string, projectRoot: string) => {
+  const packageJson = readPackageJson(projectRoot);
+  if (!packageJson?.scripts?.[script]) {
+    console.error(
+      chalk.red(
+        `Cannot find script "${script}" in package.json. Update hexabot.config.json or package.json scripts.`,
+      ),
+    );
+    process.exit(1);
+  }
+};
+const getInstallCommand = (pm: PackageManager) => {
+  switch (pm) {
+    case 'pnpm':
+      return 'pnpm install';
+    case 'yarn':
+      return 'yarn install';
+    case 'bun':
+      return 'bun install';
+    default:
+      return 'npm install';
+  }
+};
+const getRunScriptCommand = (
+  pm: PackageManager,
+  script: string,
+  args: string[],
+) => {
+  const joinedArgs = args.join(' ');
+
+  switch (pm) {
+    case 'pnpm':
+      return joinedArgs
+        ? `pnpm run ${script} -- ${joinedArgs}`
+        : `pnpm run ${script}`;
+    case 'yarn':
+      return joinedArgs ? `yarn ${script} ${joinedArgs}` : `yarn ${script}`;
+    case 'bun':
+      return joinedArgs
+        ? `bun run ${script} ${joinedArgs}`
+        : `bun run ${script}`;
+    default:
+      return joinedArgs
+        ? `npm run ${script} -- ${joinedArgs}`
+        : `npm run ${script}`;
+  }
+};
+const runCommand = (command: string, projectRoot: string) => {
+  console.log(chalk.cyan(command));
+  execSync(command, { cwd: projectRoot, stdio: 'inherit' });
+};

package/src/core/prerequisites.ts

@@ -0,0 +1,117 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { execSync } from 'child_process';
+
+import chalk from 'chalk';
+
+const REQUIRED_NODE_VERSION = '20.18.1';
+
+export interface PrerequisiteOptions {
+  docker?: boolean;
+  silent?: boolean;
+  fatal?: boolean;
+}
+
+export interface PrerequisiteCheckResult {
+  ok: boolean;
+  message: string;
+  details?: string;
+}
+
+export const checkPrerequisites = (options: PrerequisiteOptions = {}) => {
+  checkNodeVersion(options);
+  if (options.docker) {
+    checkDocker(options);
+  }
+};
+
+export const checkNodeVersion = (
+  options: PrerequisiteOptions = {},
+): PrerequisiteCheckResult => {
+  try {
+    const nodeVersion = execSync('node --version', {
+      encoding: 'utf-8',
+    }).trim();
+    const currentNodeVersion = normalizeVersion(nodeVersion);
+
+    if (compareVersions(currentNodeVersion, REQUIRED_NODE_VERSION) >= 0) {
+      const message = `Node.js ${nodeVersion} ✓`;
+      logSuccess(message, options);
+
+      return { ok: true, message };
+    }
+
+    const message = `Node.js version must be at least ${REQUIRED_NODE_VERSION}. Current version: ${nodeVersion}.`;
+    handleFailure(message, options);
+
+    return { ok: false, message };
+  } catch (error) {
+    const message =
+      "Node.js is not accessible or installed correctly. Install Node.js v20.18.1+ and ensure it's in your PATH.";
+
+    handleFailure(message, options, error);
+
+    return { ok: false, message, details: (error as Error).message };
+  }
+};
+
+export const checkDocker = (
+  options: PrerequisiteOptions = {},
+): PrerequisiteCheckResult => {
+  try {
+    const dockerVersion = execSync('docker --version', {
+      encoding: 'utf-8',
+    }).trim();
+    const message = `Docker is installed: ${dockerVersion}`;
+    logSuccess(message, options);
+
+    return { ok: true, message };
+  } catch (error) {
+    const message =
+      'Docker is required for this command. Please install Docker.';
+    handleFailure(message, options, error);
+
+    return { ok: false, message, details: (error as Error).message };
+  }
+};
+
+const normalizeVersion = (version: string) => {
+  return version.startsWith('v') ? version.slice(1) : version;
+};
+const compareVersions = (current: string, required: string) => {
+  const currentParts = current.split('.').map(Number);
+  const requiredParts = required.split('.').map(Number);
+
+  for (let i = 0; i < requiredParts.length; i++) {
+    if ((currentParts[i] || 0) > (requiredParts[i] || 0)) {
+      return 1;
+    } else if ((currentParts[i] || 0) < (requiredParts[i] || 0)) {
+      return -1;
+    }
+  }
+
+  return 0;
+};
+const logSuccess = (message: string, options: PrerequisiteOptions) => {
+  if (!options.silent) {
+    console.log(chalk.green(message));
+  }
+};
+const handleFailure = (
+  message: string,
+  options: PrerequisiteOptions,
+  error?: unknown,
+) => {
+  console.error(chalk.red(message));
+
+  if (options.fatal !== false) {
+    if (error && options.silent) {
+      console.error(chalk.red((error as Error).message));
+    }
+    process.exit(1);
+  }
+};

package/src/core/project.ts

@@ -0,0 +1,97 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import chalk from 'chalk';
+
+const DOCKER_FOLDER_NAME = 'docker';
+const HEXABOT_PACKAGE = '@hexabot-ai/api';
+
+export interface PackageJson {
+  name?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+export const resolveProjectRoot = (cwd = process.cwd()) => {
+  return path.resolve(cwd);
+};
+
+export const readPackageJson = (
+  projectRoot = process.cwd(),
+): PackageJson | null => {
+  try {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+      return null;
+    }
+
+    return JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8')) as PackageJson;
+  } catch (_error) {
+    return null;
+  }
+};
+
+export const isHexabotProject = (projectRoot = process.cwd()) => {
+  const packageJson = readPackageJson(projectRoot);
+  if (!packageJson) {
+    return false;
+  }
+
+  return hasHexabotDependency(packageJson);
+};
+
+export const assertHexabotProject = (projectRoot = process.cwd()) => {
+  if (!isHexabotProject(projectRoot)) {
+    console.error(
+      chalk.red(
+        'This command must be executed inside a Hexabot project (missing @hexabot-ai/api in package.json).',
+      ),
+    );
+    console.log(
+      chalk.yellow(
+        'Run `hexabot create <project>` or navigate to your project.',
+      ),
+    );
+    process.exit(1);
+  }
+};
+
+export const resolveDockerFolder = (projectRoot = process.cwd()) => {
+  return path.resolve(projectRoot, `./${DOCKER_FOLDER_NAME}`);
+};
+
+export const ensureDockerFolder = (projectRoot = process.cwd()) => {
+  const folder = resolveDockerFolder(projectRoot);
+
+  if (!fs.existsSync(folder)) {
+    console.error(
+      chalk.red(
+        `The '${DOCKER_FOLDER_NAME}' folder is missing. Docker commands require the Hexabot project's docker/ directory.`,
+      ),
+    );
+    console.log(
+      chalk.yellow(
+        `Ensure you're at the project root (e.g. cd path/to/my-bot) before running Docker commands.`,
+      ),
+    );
+    process.exit(1);
+  }
+
+  return folder;
+};
+
+const hasHexabotDependency = (packageJson: PackageJson) => {
+  const allDeps = {
+    ...(packageJson.dependencies || {}),
+    ...(packageJson.devDependencies || {}),
+  };
+
+  return Boolean(allDeps[HEXABOT_PACKAGE]);
+};

package/src/index.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { createCliProgram } from './cli.js';
+import { checkPrerequisites } from './core/prerequisites.js';
+import { printBanner } from './ui/banner.js';
+
+printBanner();
+checkPrerequisites({ silent: true });
+
+const program = createCliProgram();
+
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/src/services/templates.ts

@@ -0,0 +1,33 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import axios from 'axios';
+import decompress from 'decompress';
+
+export const downloadAndExtractTemplate = async (
+  templateUrl: string,
+  destination: string,
+) => {
+  try {
+    const response = await axios({
+      url: templateUrl,
+      method: 'GET',
+      responseType: 'arraybuffer',
+    });
+    const zipFilePath = path.join(destination, 'template.zip');
+    fs.writeFileSync(zipFilePath, response.data);
+
+    await decompress(zipFilePath, destination, {
+      strip: 1,
+    });
+    fs.unlinkSync(zipFilePath);
+  } catch (_error) {
+    throw new Error(`Failed to download template from GitHub`);
+  }
+};