@hexabot-ai/cli 3.0.0-alpha.3

package/src/commands/start.ts

@@ -0,0 +1,126 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import * as path from 'path';
+
+import chalk from 'chalk';
+import { Command } from 'commander';
+
+import { loadProjectConfig, updateProjectConfig } from '../core/config.js';
+import {
+  dockerCompose,
+  generateComposeFiles,
+  resolveComposeFile,
+} from '../core/docker.js';
+import { bootstrapEnvFile, resolveEnvExample } from '../core/env.js';
+import {
+  detectPackageManager,
+  normalizePackageManager,
+  runPackageScript,
+} from '../core/package-manager.js';
+import { checkDocker } from '../core/prerequisites.js';
+import { assertHexabotProject, ensureDockerFolder } from '../core/project.js';
+import { parseServices } from '../utils/services.js';
+
+export interface StartOptions {
+  docker?: boolean;
+  services?: string;
+  detach?: boolean;
+  build?: boolean;
+  env?: string;
+  envBootstrap?: boolean;
+  pm?: string;
+  cwd?: string;
+}
+
+export const registerStartCommand = (program: Command) => {
+  program
+    .command('start')
+    .description('Run the project in production mode')
+    .option('--docker', 'Run using Docker (production stack)')
+    .option('--services <list>', 'Comma-separated services/profiles to enable')
+    .option('-d, --detach', 'Detach Docker containers')
+    .option('--build', 'Build Docker images before starting')
+    .option('--env <file>', 'Env file to use (default: .env)')
+    .option('--env-bootstrap', 'Generate env files from *.example if missing')
+    .option('--pm <npm|pnpm|yarn|bun>', 'Override package manager')
+    .action(async (options: StartOptions) => {
+      await runStart(options);
+    });
+};
+
+export const runStart = async (options: StartOptions = {}) => {
+  const projectRoot = path.resolve(options.cwd || process.cwd());
+  assertHexabotProject(projectRoot);
+  const config = loadProjectConfig(projectRoot);
+  const normalizedPm = normalizePackageManager(options.pm);
+  const pm =
+    normalizedPm || config.packageManager || detectPackageManager(projectRoot);
+
+  if (config.packageManager !== pm) {
+    updateProjectConfig(projectRoot, { packageManager: pm });
+  }
+
+  const shouldBootstrap = Boolean(options.envBootstrap);
+  if (shouldBootstrap) {
+    if (options.docker) {
+      bootstrapEnvFile(
+        projectRoot,
+        config.env.dockerExample,
+        config.env.docker,
+      );
+    } else {
+      const envFile = options.env || config.env.local;
+      const envExample = resolveEnvExample(
+        projectRoot,
+        envFile,
+        config.env.localExample,
+      );
+      bootstrapEnvFile(projectRoot, envExample, envFile);
+    }
+  }
+
+  if (options.docker) {
+    await runDockerStart(projectRoot, options, config);
+  } else {
+    runPackageScript(pm, config.startScript, projectRoot);
+  }
+};
+
+const runDockerStart = async (
+  projectRoot: string,
+  options: StartOptions,
+  config: ReturnType<typeof loadProjectConfig>,
+) => {
+  checkDocker({ silent: true });
+  ensureDockerFolder(projectRoot);
+  const servicesInput = parseServices(options.services || '');
+  const services = servicesInput.length
+    ? servicesInput
+    : config.docker.defaultServices;
+  const composeFile = resolveComposeFile(
+    projectRoot,
+    config.docker.composeFile,
+  );
+  const composeArgs = generateComposeFiles(composeFile, services, 'prod');
+  const upArgs = ['up'];
+  if (options.build) {
+    upArgs.push('--build');
+  }
+  if (options.detach) {
+    upArgs.push('-d');
+  }
+
+  const composeCommand = `${composeArgs} ${upArgs.join(' ')}`.trim();
+  console.log(
+    chalk.blue(
+      `Starting Docker services in production mode${
+        services.length ? ` (${services.join(', ')})` : ''
+      }`,
+    ),
+  );
+  dockerCompose(composeCommand);
+};

package/src/core/__tests__/config.test.ts

@@ -0,0 +1,114 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import {
+  ensureProjectConfig,
+  HexabotConfig,
+  loadProjectConfig,
+  resolveConfigPath,
+  updateProjectConfig,
+} from '../config.js';
+
+describe('project config helpers', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hexabot-config-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('loads default values when the config file is missing', () => {
+    const config = loadProjectConfig(tempDir);
+
+    expect(config).toMatchObject({
+      devScript: 'dev',
+      startScript: 'start',
+      docker: {
+        composeFile: 'docker/docker-compose.yml',
+        defaultServices: [],
+      },
+      env: {
+        local: '.env',
+        localExample: '.env.example',
+        docker: '.env.docker',
+        dockerExample: '.env.docker.example',
+      },
+    });
+  });
+
+  it('merges overrides from the config file', () => {
+    const override: Partial<HexabotConfig> = {
+      devScript: 'custom-dev',
+      docker: {
+        composeFile: 'docker/compose.override.yml',
+        defaultServices: ['api', 'postgres'],
+      },
+      env: {
+        local: '.env.dev',
+        localExample: '.env.example',
+        docker: '.env.docker',
+        dockerExample: '.env.docker.example',
+      },
+    };
+    fs.writeFileSync(resolveConfigPath(tempDir), JSON.stringify(override));
+
+    const config = loadProjectConfig(tempDir);
+
+    expect(config.devScript).toBe('custom-dev');
+    expect(config.docker).toMatchObject({
+      composeFile: 'docker/compose.override.yml',
+      defaultServices: ['api', 'postgres'],
+    });
+    expect(config.env.local).toBe('.env.dev');
+    expect(config.env.localExample).toBe('.env.example');
+  });
+
+  it('creates a config file when ensuring one with overrides', () => {
+    const overrides: Partial<HexabotConfig> = {
+      packageManager: 'pnpm',
+      env: {
+        local: '.env.dev',
+        localExample: '.env.example',
+        docker: '.env.docker',
+        dockerExample: '.env.docker.example',
+      },
+    };
+    const config = ensureProjectConfig(tempDir, overrides);
+
+    expect(config.packageManager).toBe('pnpm');
+    expect(
+      JSON.parse(fs.readFileSync(resolveConfigPath(tempDir), 'utf-8')),
+    ).toMatchObject({
+      packageManager: 'pnpm',
+      env: expect.objectContaining({ local: '.env.dev' }),
+    });
+  });
+
+  it('updates existing config files by merging overrides', () => {
+    fs.writeFileSync(
+      resolveConfigPath(tempDir),
+      JSON.stringify({ startScript: 'serve' }),
+    );
+
+    const updated = updateProjectConfig(tempDir, {
+      docker: {
+        composeFile: 'docker/docker-compose.yml',
+        defaultServices: ['api'],
+      },
+    });
+
+    expect(updated.startScript).toBe('serve');
+    expect(updated.docker.defaultServices).toEqual(['api']);
+    expect(updated.env.local).toBe('.env');
+  });
+});

package/src/core/__tests__/docker.test.ts

@@ -0,0 +1,59 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { jest } from '@jest/globals';
+
+import { generateComposeFiles } from '../docker.js';
+
+describe('generateComposeFiles', () => {
+  let tempDir: string;
+  let composeFile: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hexabot-docker-'));
+    composeFile = path.join(tempDir, 'docker-compose.yml');
+    fs.writeFileSync(composeFile, '');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('builds the compose file list for provided services', () => {
+    const apiFile = path.join(tempDir, 'docker-compose.api.yml');
+    const dbFile = path.join(tempDir, 'docker-compose.db.yml');
+    fs.writeFileSync(apiFile, '');
+    fs.writeFileSync(dbFile, '');
+
+    const result = generateComposeFiles(composeFile, ['api', 'db']);
+
+    expect(result).toBe(
+      `-f ${composeFile} ` + `-f ${apiFile} ` + `-f ${dbFile}`,
+    );
+  });
+
+  it('includes mode specific service and main files when they exist', () => {
+    const apiFile = path.join(tempDir, 'docker-compose.api.yml');
+    const serviceModeFile = path.join(tempDir, 'docker-compose.api.dev.yml');
+    const mainModeFile = path.join(tempDir, 'docker-compose.dev.yml');
+    fs.writeFileSync(apiFile, '');
+    fs.writeFileSync(serviceModeFile, '');
+    fs.writeFileSync(mainModeFile, '');
+
+    const result = generateComposeFiles(composeFile, ['api'], 'dev');
+
+    expect(result).toBe(
+      `-f ${composeFile} ` +
+        `-f ${apiFile} ` +
+        `-f ${serviceModeFile} -f ${mainModeFile}`,
+    );
+  });
+});

package/src/core/__tests__/env.test.ts

@@ -0,0 +1,97 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { jest } from '@jest/globals';
+
+import { bootstrapEnvFile, listEnvStatus, resolveEnvExample } from '../env.js';
+
+describe('env helpers', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hexabot-env-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    jest.restoreAllMocks();
+  });
+
+  it('copies the example env file when the target is missing', () => {
+    const example = '.env.example';
+    const target = '.env';
+    fs.writeFileSync(path.join(tempDir, example), 'KEY=value');
+
+    const result = bootstrapEnvFile(tempDir, example, target);
+
+    expect(result).toBe(true);
+    expect(fs.readFileSync(path.join(tempDir, target), 'utf-8')).toBe(
+      'KEY=value',
+    );
+  });
+
+  it('skips copying when the target exists unless forced', () => {
+    const example = '.env.example';
+    const target = '.env';
+    fs.writeFileSync(path.join(tempDir, example), 'NEW=value');
+    fs.writeFileSync(path.join(tempDir, target), 'OLD=value');
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+    const skipped = bootstrapEnvFile(tempDir, example, target, {
+      quiet: false,
+    });
+    expect(skipped).toBe(false);
+    expect(fs.readFileSync(path.join(tempDir, target), 'utf-8')).toBe(
+      'OLD=value',
+    );
+    expect(logSpy).toHaveBeenCalled();
+
+    const forced = bootstrapEnvFile(tempDir, example, target, { force: true });
+    expect(forced).toBe(true);
+    expect(fs.readFileSync(path.join(tempDir, target), 'utf-8')).toBe(
+      'NEW=value',
+    );
+  });
+
+  it('lists env file statuses using the provided config', () => {
+    const config = {
+      env: {
+        local: '.env',
+        localExample: '.env.example',
+        docker: '.env.docker',
+        dockerExample: '.env.docker.example',
+      },
+    } as const;
+    fs.writeFileSync(path.join(tempDir, '.env.example'), '');
+    fs.writeFileSync(path.join(tempDir, '.env'), '');
+
+    const statuses = listEnvStatus(tempDir, config as any);
+
+    expect(statuses).toEqual([
+      expect.objectContaining({ file: '.env.example', exists: true }),
+      expect.objectContaining({ file: '.env', exists: true }),
+      expect.objectContaining({ file: '.env.docker.example', exists: false }),
+      expect.objectContaining({ file: '.env.docker', exists: false }),
+    ]);
+  });
+
+  it('resolves env example files relative to the project root', () => {
+    const envFile = '.env.local';
+    const defaultExample = '.env.example';
+    const examplePath = path.join(tempDir, `${envFile}.example`);
+    fs.writeFileSync(examplePath, '');
+
+    expect(resolveEnvExample(tempDir, envFile, defaultExample)).toBe(
+      `${envFile}.example`,
+    );
+    expect(resolveEnvExample(tempDir, '.missing', defaultExample)).toBe(
+      defaultExample,
+    );
+  });
+});

package/src/core/__tests__/package-manager.test.ts

@@ -0,0 +1,121 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { jest } from '@jest/globals';
+
+const readPackageJson = jest.fn();
+const execSync = jest.fn();
+
+jest.unstable_mockModule('../project.js', () => ({
+  readPackageJson,
+}));
+
+jest.unstable_mockModule('child_process', () => ({
+  execSync,
+}));
+
+type PackageManagerModule = typeof import('../package-manager.js');
+let normalizePackageManager: PackageManagerModule['normalizePackageManager'];
+let detectPackageManager: PackageManagerModule['detectPackageManager'];
+let runPackageScript: PackageManagerModule['runPackageScript'];
+let installDependencies: PackageManagerModule['installDependencies'];
+
+beforeAll(async () => {
+  ({
+    normalizePackageManager,
+    detectPackageManager,
+    runPackageScript,
+    installDependencies,
+  } = await import('../package-manager.js'));
+});
+
+afterEach(() => {
+  jest.resetAllMocks();
+});
+
+describe('normalizePackageManager', () => {
+  it('returns normalized package manager names', () => {
+    expect(normalizePackageManager('PNPM')).toBe('pnpm');
+    expect(normalizePackageManager(undefined)).toBeUndefined();
+  });
+
+  it('exits when the package manager is unsupported', () => {
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('exit:1');
+    }) as () => never);
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => normalizePackageManager('foo')).toThrow('exit:1');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('detectPackageManager', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hexabot-pm-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('detects the package manager based on lockfiles', () => {
+    fs.writeFileSync(path.join(tempDir, 'pnpm-lock.yaml'), '');
+
+    expect(detectPackageManager(tempDir)).toBe('pnpm');
+  });
+
+  it('falls back to npm when no lockfiles are found', () => {
+    expect(detectPackageManager(tempDir)).toBe('npm');
+  });
+});
+
+describe('installDependencies & runPackageScript', () => {
+  const projectRoot = '/tmp/project';
+
+  beforeEach(() => {
+    readPackageJson.mockReturnValue({
+      scripts: {
+        build: 'tsc',
+      },
+    });
+  });
+
+  it('runs installation commands for the chosen package manager', () => {
+    installDependencies('yarn', projectRoot);
+
+    expect(execSync).toHaveBeenCalledWith('yarn install', {
+      cwd: projectRoot,
+      stdio: 'inherit',
+    });
+  });
+
+  it('runs package scripts after ensuring the script exists', () => {
+    runPackageScript('pnpm', 'build', projectRoot, ['--watch']);
+
+    expect(execSync).toHaveBeenCalledWith('pnpm run build -- --watch', {
+      cwd: projectRoot,
+      stdio: 'inherit',
+    });
+  });
+
+  it('exits when the script is missing from package.json', () => {
+    readPackageJson.mockReturnValue({ scripts: {} });
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('exit:1');
+    }) as () => never);
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => runPackageScript('npm', 'dev', projectRoot)).toThrow('exit:1');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});

package/src/core/__tests__/project.test.ts

@@ -0,0 +1,68 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { jest } from '@jest/globals';
+
+import { ensureDockerFolder, resolveDockerFolder } from '../project.js';
+
+describe('project helpers', () => {
+  let tempDirs: string[] = [];
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    tempDirs.forEach((dir) =>
+      fs.rmSync(dir, {
+        recursive: true,
+        force: true,
+      }),
+    );
+    tempDirs = [];
+  });
+
+  const createTempDir = (withDockerFolder: boolean) => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hexabot-project-'));
+    tempDirs.push(dir);
+    if (withDockerFolder) {
+      fs.mkdirSync(path.join(dir, 'docker'));
+    }
+
+    return dir;
+  };
+
+  it('resolves the docker folder relative to the working directory', () => {
+    jest.spyOn(process, 'cwd').mockReturnValue('/workspace/hexabot');
+
+    expect(resolveDockerFolder()).toBe(
+      path.resolve('/workspace/hexabot', './docker'),
+    );
+  });
+
+  it('returns the folder path when it exists', () => {
+    const cwd = createTempDir(true);
+    jest.spyOn(process, 'cwd').mockReturnValue(cwd);
+
+    expect(ensureDockerFolder()).toBe(path.resolve(cwd, './docker'));
+  });
+
+  it('exits the process when the docker folder is missing', () => {
+    const cwd = createTempDir(false);
+    jest.spyOn(process, 'cwd').mockReturnValue(cwd);
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(((
+      code?: string | number | null | undefined,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as (code?: string | number | null | undefined) => never);
+
+    expect(() => ensureDockerFolder()).toThrow('exit:1');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});