@hexabot-ai/cli 3.0.0-alpha.3

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

@@ -0,0 +1,168 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { jest } from '@jest/globals';
+import { Command } from 'commander';
+
+const loadProjectConfig = jest.fn();
+const dockerCompose = jest.fn();
+const generateComposeFiles = jest.fn();
+const resolveComposeFile = jest.fn();
+const bootstrapEnvFile = jest.fn();
+const checkDocker = jest.fn();
+const assertHexabotProject = jest.fn();
+const ensureDockerFolder = jest.fn();
+const parseServices = jest.fn();
+const runStart = jest.fn();
+
+jest.unstable_mockModule('../../core/config.js', () => ({
+  loadProjectConfig,
+}));
+
+jest.unstable_mockModule('../../core/docker.js', () => ({
+  dockerCompose,
+  generateComposeFiles,
+  resolveComposeFile,
+}));
+
+jest.unstable_mockModule('../../core/env.js', () => ({
+  bootstrapEnvFile,
+}));
+
+jest.unstable_mockModule('../../core/prerequisites.js', () => ({
+  checkDocker,
+}));
+
+jest.unstable_mockModule('../../core/project.js', () => ({
+  assertHexabotProject,
+  ensureDockerFolder,
+}));
+
+jest.unstable_mockModule('../../utils/services.js', () => ({
+  parseServices,
+}));
+
+jest.unstable_mockModule('../start.js', () => ({
+  runStart,
+}));
+
+let registerDockerCommand: (program: Command) => void;
+
+beforeAll(async () => {
+  ({ registerDockerCommand } = await import('../docker.js'));
+});
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  parseServices.mockImplementation((value: unknown) =>
+    (typeof value === 'string' ? value : '')
+      .split(',')
+      .filter((entry) => entry),
+  );
+  resolveComposeFile.mockReturnValue('/project/docker/docker-compose.yml');
+  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
+  loadProjectConfig.mockReturnValue({
+    docker: {
+      composeFile: 'docker/docker-compose.yml',
+      defaultServices: ['api'],
+    },
+    env: {
+      docker: '.env.docker',
+      dockerExample: '.env.docker.example',
+    },
+  });
+});
+
+const createProgram = () => {
+  const program = new Command();
+  registerDockerCommand(program);
+
+  return program;
+};
+
+describe('registerDockerCommand', () => {
+  it('runs docker compose up with extra flags and services', async () => {
+    const program = createProgram();
+    await program.parseAsync([
+      'node',
+      'test',
+      'docker',
+      'up',
+      '--services',
+      'api,postgres',
+      '--build',
+      '--detach',
+    ]);
+
+    expect(bootstrapEnvFile).toHaveBeenCalled();
+    expect(generateComposeFiles).toHaveBeenCalledWith(
+      '/project/docker/docker-compose.yml',
+      ['api', 'postgres'],
+      'dev',
+    );
+    expect(dockerCompose).toHaveBeenCalledWith(
+      expect.stringContaining('up --build -d'),
+    );
+  });
+
+  it('runs docker compose down with optional volume removal', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'docker', 'down', '--volumes']);
+
+    expect(dockerCompose).toHaveBeenCalledWith(
+      expect.stringContaining('down -v'),
+    );
+    expect(bootstrapEnvFile).not.toHaveBeenCalled();
+  });
+
+  it('tails docker logs with filters', async () => {
+    const program = createProgram();
+    await program.parseAsync([
+      'node',
+      'test',
+      'docker',
+      'logs',
+      'api',
+      '--follow',
+      '--since',
+      '1h',
+    ]);
+
+    expect(dockerCompose).toHaveBeenCalledWith(
+      expect.stringContaining('logs -f --since 1h api'),
+    );
+  });
+
+  it('lists running services with docker ps', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'docker', 'ps']);
+
+    expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('ps'));
+  });
+
+  it('delegates to start command for docker start', async () => {
+    const program = createProgram();
+    await program.parseAsync([
+      'node',
+      'test',
+      'docker',
+      'start',
+      '--services',
+      'api',
+      '--build',
+      '--detach',
+      '--env-bootstrap',
+    ]);
+
+    expect(runStart).toHaveBeenCalledWith({
+      docker: true,
+      services: 'api',
+      build: true,
+      detach: true,
+      envBootstrap: true,
+    });
+  });
+});

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

@@ -0,0 +1,95 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { jest } from '@jest/globals';
+import { Command } from 'commander';
+
+const loadProjectConfig = jest.fn();
+const bootstrapEnvFile = jest.fn();
+const listEnvStatus = jest.fn();
+const assertHexabotProject = jest.fn();
+
+jest.unstable_mockModule('../../core/config.js', () => ({
+  loadProjectConfig,
+}));
+
+jest.unstable_mockModule('../../core/env.js', () => ({
+  bootstrapEnvFile,
+  listEnvStatus,
+}));
+
+jest.unstable_mockModule('../../core/project.js', () => ({
+  assertHexabotProject,
+}));
+
+let registerEnvCommand: (program: Command) => void;
+
+beforeAll(async () => {
+  ({ registerEnvCommand } = await import('../env.js'));
+});
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  loadProjectConfig.mockReturnValue({
+    env: {
+      local: '.env',
+      localExample: '.env.example',
+      docker: '.env.docker',
+      dockerExample: '.env.docker.example',
+    },
+  });
+});
+
+describe('registerEnvCommand', () => {
+  it('bootstraps env files for docker or local targets', async () => {
+    const dockerProgram = new Command();
+    registerEnvCommand(dockerProgram);
+    await dockerProgram.parseAsync([
+      'node',
+      'test',
+      'env',
+      'init',
+      '--docker',
+      '--force',
+    ]);
+    expect(bootstrapEnvFile).toHaveBeenCalledWith(
+      expect.any(String),
+      '.env.docker.example',
+      '.env.docker',
+      { force: true },
+    );
+
+    jest.clearAllMocks();
+    const localProgram = new Command();
+    registerEnvCommand(localProgram);
+    await localProgram.parseAsync(['node', 'test', 'env', 'init']);
+    expect(bootstrapEnvFile).toHaveBeenCalledWith(
+      expect.any(String),
+      '.env.example',
+      '.env',
+      { force: undefined },
+    );
+  });
+
+  it('lists env statuses with formatted output', async () => {
+    const statuses = [
+      { file: '.env', exists: true },
+      { file: '.env.docker', exists: false },
+    ];
+    listEnvStatus.mockReturnValue(statuses);
+    const logs: string[] = [];
+    jest.spyOn(console, 'log').mockImplementation((message?: string) => {
+      logs.push(String(message));
+    });
+
+    const program = new Command();
+    registerEnvCommand(program);
+    await program.parseAsync(['node', 'test', 'env', 'list']);
+
+    expect(logs.join('\n')).toContain('.env');
+    expect(logs.join('\n')).toContain('.env.docker');
+  });
+});

package/src/commands/__tests__/migrate.test.ts

@@ -0,0 +1,64 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { jest } from '@jest/globals';
+import { Command } from 'commander';
+
+const dockerExec = jest.fn();
+const ensureDockerFolder = jest.fn();
+const checkDocker = jest.fn();
+
+jest.unstable_mockModule('../../core/docker.js', () => ({
+  dockerExec,
+}));
+
+jest.unstable_mockModule('../../core/project.js', () => ({
+  ensureDockerFolder,
+}));
+
+jest.unstable_mockModule('../../core/prerequisites.js', () => ({
+  checkDocker,
+}));
+
+let registerMigrateCommand: (program: Command) => void;
+
+beforeAll(async () => {
+  ({ registerMigrateCommand } = await import('../migrate.js'));
+});
+
+describe('registerMigrateCommand', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    ensureDockerFolder.mockReturnValue('/workspace/docker');
+  });
+
+  it('runs migrations with additional arguments', async () => {
+    const program = new Command();
+    registerMigrateCommand(program);
+
+    await program.parseAsync(['node', 'test', 'migrate', 'seed', '20241128']);
+
+    expect(ensureDockerFolder).toHaveBeenCalled();
+    expect(dockerExec).toHaveBeenCalledWith(
+      'api',
+      'npm run migrate seed 20241128',
+      '--user $(id -u):$(id -g)',
+    );
+  });
+
+  it('runs migrations without extra arguments', async () => {
+    const program = new Command();
+    registerMigrateCommand(program);
+
+    await program.parseAsync(['node', 'test', 'migrate']);
+
+    expect(dockerExec).toHaveBeenCalledWith(
+      'api',
+      'npm run migrate',
+      '--user $(id -u):$(id -g)',
+    );
+  });
+});

package/src/commands/__tests__/start.test.ts

@@ -0,0 +1,166 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { jest } from '@jest/globals';
+
+const loadProjectConfig = jest.fn();
+const updateProjectConfig = jest.fn();
+const dockerCompose = jest.fn();
+const generateComposeFiles = jest.fn();
+const resolveComposeFile = jest.fn();
+const bootstrapEnvFile = jest.fn();
+const resolveEnvExample = jest.fn();
+const detectPackageManager = jest.fn();
+const normalizePackageManager = jest.fn();
+const runPackageScript = jest.fn();
+const checkDocker = jest.fn();
+const assertHexabotProject = jest.fn();
+const ensureDockerFolder = jest.fn();
+
+jest.unstable_mockModule('../../core/config.js', () => ({
+  loadProjectConfig,
+  updateProjectConfig,
+}));
+
+jest.unstable_mockModule('../../core/docker.js', () => ({
+  dockerCompose,
+  generateComposeFiles,
+  resolveComposeFile,
+}));
+
+jest.unstable_mockModule('../../core/env.js', () => ({
+  bootstrapEnvFile,
+  resolveEnvExample,
+}));
+
+jest.unstable_mockModule('../../core/package-manager.js', () => ({
+  detectPackageManager,
+  normalizePackageManager,
+  runPackageScript,
+}));
+
+jest.unstable_mockModule('../../core/prerequisites.js', () => ({
+  checkDocker,
+}));
+
+jest.unstable_mockModule('../../core/project.js', () => ({
+  assertHexabotProject,
+  ensureDockerFolder,
+}));
+
+jest.unstable_mockModule('../../utils/services.js', () => ({
+  parseServices: (value: string) => value.split(',').filter(Boolean),
+}));
+
+let runStart: (options?: any) => Promise<void>;
+
+beforeAll(async () => {
+  ({ runStart } = await import('../start.js'));
+});
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  normalizePackageManager.mockImplementation(
+    (value: unknown) => value as string | undefined,
+  );
+});
+
+describe('runStart', () => {
+  const baseConfig = {
+    startScript: 'start',
+    packageManager: 'npm',
+    docker: {
+      composeFile: 'docker/docker-compose.yml',
+      defaultServices: [],
+    },
+    env: {
+      local: '.env',
+      localExample: '.env.example',
+      docker: '.env.docker',
+      dockerExample: '.env.docker.example',
+    },
+  };
+
+  it('runs the npm start script when not using Docker', async () => {
+    loadProjectConfig.mockReturnValue(baseConfig);
+
+    await runStart();
+
+    expect(assertHexabotProject).toHaveBeenCalled();
+    expect(runPackageScript).toHaveBeenCalledWith(
+      'npm',
+      'start',
+      expect.any(String),
+    );
+    expect(detectPackageManager).not.toHaveBeenCalled();
+    expect(updateProjectConfig).not.toHaveBeenCalled();
+    expect(dockerCompose).not.toHaveBeenCalled();
+  });
+
+  it('runs docker compose in prod mode with env bootstrap', async () => {
+    const config = {
+      ...baseConfig,
+      packageManager: undefined,
+      docker: {
+        composeFile: 'docker/docker-compose.yml',
+        defaultServices: ['api'],
+      },
+    };
+    loadProjectConfig.mockReturnValue(config);
+    detectPackageManager.mockReturnValue('pnpm');
+    resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
+    generateComposeFiles.mockReturnValue('-f docker-compose.yml');
+
+    await runStart({
+      docker: true,
+      services: 'api,postgres',
+      envBootstrap: true,
+      build: true,
+      detach: true,
+    });
+
+    expect(detectPackageManager).toHaveBeenCalled();
+    expect(updateProjectConfig).toHaveBeenCalledWith(expect.any(String), {
+      packageManager: 'pnpm',
+    });
+    expect(bootstrapEnvFile).toHaveBeenCalledWith(
+      expect.any(String),
+      config.env.dockerExample,
+      config.env.docker,
+    );
+    expect(resolveEnvExample).not.toHaveBeenCalled();
+    expect(checkDocker).toHaveBeenCalled();
+    expect(ensureDockerFolder).toHaveBeenCalled();
+    expect(generateComposeFiles).toHaveBeenCalledWith(
+      '/tmp/docker/docker-compose.yml',
+      ['api', 'postgres'],
+      'prod',
+    );
+    expect(dockerCompose).toHaveBeenCalledWith(
+      expect.stringContaining('up --build -d'),
+    );
+    expect(runPackageScript).not.toHaveBeenCalled();
+  });
+
+  it('bootstraps envs for local start when requested', async () => {
+    loadProjectConfig.mockReturnValue(baseConfig);
+    resolveEnvExample.mockReturnValue('.env.local.example');
+
+    await runStart({ envBootstrap: true, env: '.env.local' });
+
+    expect(resolveEnvExample).toHaveBeenCalledWith(
+      expect.any(String),
+      '.env.local',
+      baseConfig.env.localExample,
+    );
+    expect(bootstrapEnvFile).toHaveBeenCalledWith(
+      expect.any(String),
+      '.env.local.example',
+      '.env.local',
+    );
+    expect(runPackageScript).toHaveBeenCalled();
+  });
+});

package/src/commands/check.ts

@@ -0,0 +1,102 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import chalk from 'chalk';
+import { Command } from 'commander';
+
+import { loadProjectConfig } from '../core/config.js';
+import { listEnvStatus } from '../core/env.js';
+import { checkDocker, checkNodeVersion } from '../core/prerequisites.js';
+import { isHexabotProject } from '../core/project.js';
+
+interface CheckCommandOptions {
+  dockerOnly?: boolean;
+  docker?: boolean;
+  noDocker?: boolean;
+}
+
+export const registerCheckCommand = (program: Command) => {
+  program
+    .command('check')
+    .description('Run diagnostic checks')
+    .option('--docker-only', 'Only run Docker checks')
+    .option('--no-docker', 'Skip Docker checks')
+    .action((options: CheckCommandOptions) => {
+      runDiagnostics({
+        dockerOnly: options.dockerOnly,
+        noDocker: options.noDocker ?? options.docker === false,
+      });
+    });
+};
+
+const runDiagnostics = (options: {
+  dockerOnly?: boolean;
+  noDocker?: boolean;
+}) => {
+  const projectRoot = process.cwd();
+  const onlyDocker = options.dockerOnly;
+  const skipDocker = options.noDocker;
+  const results: DiagnosticResult[] = [];
+
+  if (!onlyDocker) {
+    const nodeResult = checkNodeVersion({ fatal: false, silent: true });
+    results.push({
+      label: 'Node.js version',
+      ok: nodeResult.ok,
+      message: nodeResult.message,
+    });
+
+    const projectResult = isHexabotProject(projectRoot);
+    results.push({
+      label: 'Hexabot project',
+      ok: projectResult,
+      message: projectResult
+        ? 'Found @hexabot-ai/api in package.json'
+        : 'Run inside a Hexabot project directory',
+    });
+
+    if (projectResult) {
+      const config = loadProjectConfig(projectRoot);
+      const envStatuses = listEnvStatus(projectRoot, config);
+      envStatuses.forEach((status) => {
+        results.push({
+          label: `Env file ${status.file}`,
+          ok: status.exists,
+          message: status.exists ? 'Found' : 'Missing',
+        });
+      });
+    }
+  }
+
+  if (!skipDocker) {
+    const dockerResult = checkDocker({ fatal: false, silent: true });
+    results.push({
+      label: 'Docker',
+      ok: dockerResult.ok,
+      message: dockerResult.message,
+    });
+  }
+
+  const hasErrors = results.some((result) => !result.ok);
+  results.forEach((result) => printResult(result));
+
+  if (hasErrors) {
+    process.exitCode = 1;
+  }
+};
+
+interface DiagnosticResult {
+  label: string;
+  ok: boolean;
+  message?: string;
+}
+
+const printResult = (result: DiagnosticResult) => {
+  const status = result.ok ? chalk.green('PASS') : chalk.red('FAIL');
+  console.log(
+    `${status} ${result.label}${result.message ? ` — ${result.message}` : ''}`,
+  );
+};

package/src/commands/config.ts

@@ -0,0 +1,90 @@
+/*
+ * 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 { normalizePackageManager } from '../core/package-manager.js';
+import { assertHexabotProject } from '../core/project.js';
+
+export const registerConfigCommand = (program: Command) => {
+  const configCommand = program.command('config').description('Project config');
+
+  configCommand
+    .command('show')
+    .description('Print effective Hexabot configuration')
+    .action(() => {
+      const projectRoot = path.resolve(process.cwd());
+      assertHexabotProject(projectRoot);
+      const config = loadProjectConfig(projectRoot);
+      console.log(JSON.stringify(config, null, 2));
+    });
+
+  configCommand
+    .command('set <key> <value>')
+    .description('Update a configuration value (dot notation)')
+    .action((key: string, value: string) => {
+      const projectRoot = path.resolve(process.cwd());
+      assertHexabotProject(projectRoot);
+      const normalizedValue = parseValue(key, value);
+      const override = buildOverride(key.split('.'), normalizedValue);
+      const updated = updateProjectConfig(projectRoot, override);
+      console.log(chalk.green('Updated hexabot.config.json'));
+      console.log(JSON.stringify(updated, null, 2));
+    });
+};
+
+const parseValue = (key: string, value: string) => {
+  if (key === 'packageManager') {
+    return normalizePackageManager(value);
+  }
+
+  const trimmed = value.trim();
+  if (trimmed === 'true') {
+    return true;
+  }
+  if (trimmed === 'false') {
+    return false;
+  }
+  if (!Number.isNaN(Number(trimmed)) && trimmed !== '') {
+    return Number(trimmed);
+  }
+  if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+    try {
+      return JSON.parse(trimmed);
+    } catch (_error) {
+      // fallback to string
+    }
+  }
+  if (trimmed.includes(',') && key.endsWith('Services')) {
+    return trimmed
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+
+  return trimmed;
+};
+const buildOverride = (
+  parts: string[],
+  value: unknown,
+): Record<string, unknown> => {
+  if (!parts.length) {
+    return {};
+  }
+
+  const [head, ...rest] = parts;
+  if (!head) {
+    return buildOverride(rest, value);
+  }
+
+  return {
+    [head]: rest.length ? buildOverride(rest, value) : value,
+  };
+};