@hexabot-ai/cli 3.0.0-alpha.3

package/eslint.config.cjs

@@ -0,0 +1,104 @@
+const path = require('node:path');
+const { FlatCompat } = require('@eslint/eslintrc');
+const globals = require('globals');
+const tsParser = require('@typescript-eslint/parser');
+const tsPlugin = require('@typescript-eslint/eslint-plugin');
+const importPlugin = require('eslint-plugin-import');
+const headerPlugin = require('eslint-plugin-header');
+
+if (!headerPlugin.rules.header.meta.schema) {
+  headerPlugin.rules.header.meta.schema = {
+    type: 'array',
+  };
+}
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  resolvePluginsRelativeTo: __dirname,
+});
+
+const createConfig = ({ headerYear = '2025' } = {}) => {
+  const headerLines = [
+    '',
+    ' * Hexabot — Fair Core License (FCL-1.0-ALv2)',
+    {
+      pattern: '^ \\* Copyright \\(c\\) 20\\d{2} Hexastack\\.$',
+      template: ` * Copyright (c) ${headerYear} Hexastack.`,
+    },
+    ' * Full terms: see LICENSE.md.',
+    ' ',
+  ];
+
+  return [
+    {
+      ignores: ['dist', 'eslint.config.cjs', 'eslint.config-staged.cjs'],
+    },
+    ...compat.extends('plugin:@typescript-eslint/recommended', 'plugin:prettier/recommended'),
+    {
+      files: ['**/*.ts'],
+      languageOptions: {
+        parser: tsParser,
+        parserOptions: {
+          project: path.join(__dirname, 'tsconfig.json'),
+          tsconfigRootDir: __dirname,
+          sourceType: 'module',
+        },
+        globals: {
+          ...globals.node,
+          fetch: 'readonly',
+        },
+      },
+      plugins: {
+        '@typescript-eslint': tsPlugin,
+        import: importPlugin,
+        header: headerPlugin,
+      },
+      rules: {
+        '@typescript-eslint/explicit-function-return-type': 'off',
+        '@typescript-eslint/explicit-module-boundary-types': 'off',
+        '@typescript-eslint/no-explicit-any': 'off',
+        '@typescript-eslint/no-this-alias': 'off',
+        '@typescript-eslint/no-empty-object-type': 'off',
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          {
+            argsIgnorePattern: '^_',
+            varsIgnorePattern: '^_',
+            caughtErrorsIgnorePattern: '^_',
+          },
+        ],
+        '@typescript-eslint/no-namespace': 'off',
+        'padding-line-between-statements': [
+          2,
+          { blankLine: 'always', prev: '*', next: 'export' },
+          { blankLine: 'always', prev: '*', next: 'function' },
+          { blankLine: 'always', prev: '*', next: 'return' },
+          { blankLine: 'never', prev: 'const', next: 'const' },
+        ],
+        'lines-between-class-members': ['warn', 'always'],
+        'no-console': 'off',
+        'no-duplicate-imports': 2,
+        'object-shorthand': 1,
+        'import/order': [
+          'error',
+          {
+            groups: ['builtin', 'external', 'unknown', 'parent', 'sibling', 'index', 'internal'],
+            'newlines-between': 'always',
+            alphabetize: {
+              order: 'asc',
+              caseInsensitive: true,
+            },
+          },
+        ],
+        'header/header': [2, 'block', headerLines, 2],
+        'no-multiple-empty-lines': ['error', { max: 1 }],
+      },
+    },
+  ];
+};
+
+const config = createConfig();
+
+config.createConfig = createConfig;
+
+module.exports = config;

package/jest.config.ts

@@ -0,0 +1,24 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
+  transform: {
+    '^.+\\.(ts|tsx)$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/tsconfig.json',
+        useESM: true,
+      },
+    ],
+  },
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^chalk$': '<rootDir>/test/__mocks__/chalk.ts',
+  },
+  testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/index.ts'],
+};
+
+export default config;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@hexabot-ai/cli",
+  "version": "3.0.0-alpha.3",
+  "description": "Official Hexabot CLI for creating and managing AI chatbot/agent projects built with Hexabot.",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "hexabot": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
+    "prepare": "npm run build",
+    "release:patch": "npm version patch && git push origin main --tags",
+    "release:minor": "npm version minor && git push origin main --tags",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix"
+  },
+  "keywords": [],
+  "author": "Hexastack",
+  "license": "AGPL-3.0-only",
+  "lint-staged": {
+    "*.{ts}": "eslint --fix --config eslint.config-staged.cjs"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "decompress": "^4.2.1",
+    "degit": "^2.8.4",
+    "dotenv": "^16.4.5",
+    "figlet": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/chalk": "^2.2.0",
+    "@types/commander": "^2.12.2",
+    "@types/decompress": "^4.2.7",
+    "@types/degit": "^2.8.6",
+    "@types/figlet": "^1.5.8",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.7.4",
+    "@typescript-eslint/eslint-plugin": "^8.46.0",
+    "@typescript-eslint/parser": "^8.46.0",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.37.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-header": "^3.1.1",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^30.2.0",
+    "lint-staged": "^15.3.0",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.4.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,37 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Command } from 'commander';
+
+import { registerCheckCommand } from './commands/check.js';
+import { registerConfigCommand } from './commands/config.js';
+import { registerCreateCommand } from './commands/create.js';
+import { registerDevCommand } from './commands/dev.js';
+import { registerDockerCommand } from './commands/docker.js';
+import { registerEnvCommand } from './commands/env.js';
+import { registerMigrateCommand } from './commands/migrate.js';
+import { registerStartCommand } from './commands/start.js';
+import { getCliVersion } from './utils/version.js';
+
+export const createCliProgram = () => {
+  const program = new Command();
+
+  program
+    .name('Hexabot')
+    .description('A CLI to manage your Hexabot project instance')
+    .version(getCliVersion());
+
+  registerCheckCommand(program);
+  registerCreateCommand(program);
+  registerConfigCommand(program);
+  registerDevCommand(program);
+  registerDockerCommand(program);
+  registerEnvCommand(program);
+  registerStartCommand(program);
+  registerMigrateCommand(program);
+
+  return program;
+};

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

@@ -0,0 +1,116 @@
+/*
+ * 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 listEnvStatus = jest.fn();
+const checkDocker = jest.fn();
+const checkNodeVersion = jest.fn();
+const isHexabotProject = jest.fn();
+
+jest.unstable_mockModule('../../core/config.js', () => ({
+  loadProjectConfig,
+}));
+
+jest.unstable_mockModule('../../core/env.js', () => ({
+  listEnvStatus,
+}));
+
+jest.unstable_mockModule('../../core/prerequisites.js', () => ({
+  checkDocker,
+  checkNodeVersion,
+}));
+
+jest.unstable_mockModule('../../core/project.js', () => ({
+  isHexabotProject,
+}));
+
+let registerCheckCommand: (program: Command) => void;
+
+beforeAll(async () => {
+  ({ registerCheckCommand } = await import('../check.js'));
+});
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  process.exitCode = undefined;
+});
+
+describe('registerCheckCommand', () => {
+  it('runs full diagnostics by default', async () => {
+    checkNodeVersion.mockReturnValue({ ok: true, message: 'Node OK' });
+    isHexabotProject.mockReturnValue(true);
+    loadProjectConfig.mockReturnValue({
+      env: {
+        local: '.env',
+      },
+    });
+    listEnvStatus.mockReturnValue([
+      { file: '.env', exists: true },
+      { file: '.env.docker', exists: true },
+    ]);
+    checkDocker.mockReturnValue({ ok: true, message: 'Docker OK' });
+    const logs: string[] = [];
+    jest.spyOn(console, 'log').mockImplementation((message?: string) => {
+      logs.push(String(message));
+    });
+
+    const program = new Command();
+    registerCheckCommand(program);
+    await program.parseAsync(['node', 'test', 'check']);
+
+    expect(logs.join('\n')).toContain('Node.js version');
+    expect(logs.join('\n')).toContain('Hexabot project');
+    expect(logs.join('\n')).toContain('Env file .env');
+    expect(logs.join('\n')).toContain('Docker');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('supports docker-only and no-docker modes', async () => {
+    checkDocker.mockReturnValue({ ok: true, message: 'Docker OK' });
+    checkNodeVersion.mockReturnValue({ ok: true, message: 'Node OK' });
+
+    const dockerOnlyProgram = new Command();
+    registerCheckCommand(dockerOnlyProgram);
+    await dockerOnlyProgram.parseAsync([
+      'node',
+      'test',
+      'check',
+      '--docker-only',
+    ]);
+
+    expect(checkNodeVersion).not.toHaveBeenCalled();
+    expect(isHexabotProject).not.toHaveBeenCalled();
+    expect(checkDocker).toHaveBeenCalled();
+
+    jest.clearAllMocks();
+    checkDocker.mockReturnValue({ ok: true, message: 'Docker OK' });
+    checkNodeVersion.mockReturnValue({ ok: true, message: 'Node OK' });
+    const noDockerProgram = new Command();
+    registerCheckCommand(noDockerProgram);
+    await noDockerProgram.parseAsync(['node', 'test', 'check', '--no-docker']);
+    expect(checkDocker).not.toHaveBeenCalled();
+  });
+
+  it('sets process exit code when checks fail', async () => {
+    checkNodeVersion.mockReturnValue({ ok: true, message: 'Node OK' });
+    isHexabotProject.mockReturnValue(false);
+    checkDocker.mockReturnValue({ ok: false, message: 'Docker missing' });
+    const logs: string[] = [];
+    jest.spyOn(console, 'log').mockImplementation((message?: string) => {
+      logs.push(String(message));
+    });
+
+    const program = new Command();
+    registerCheckCommand(program);
+    await program.parseAsync(['node', 'test', 'check', '--no-docker']);
+
+    expect(logs.join('\n')).toContain('Hexabot project');
+    expect(process.exitCode).toBe(1);
+  });
+});

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

@@ -0,0 +1,97 @@
+/*
+ * 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 updateProjectConfig = jest.fn();
+const normalizePackageManager = jest.fn();
+const assertHexabotProject = jest.fn();
+
+jest.unstable_mockModule('../../core/config.js', () => ({
+  loadProjectConfig,
+  updateProjectConfig,
+}));
+
+jest.unstable_mockModule('../../core/package-manager.js', () => ({
+  normalizePackageManager,
+}));
+
+jest.unstable_mockModule('../../core/project.js', () => ({
+  assertHexabotProject,
+}));
+
+let registerConfigCommand: (program: Command) => void;
+
+beforeAll(async () => {
+  ({ registerConfigCommand } = await import('../config.js'));
+});
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  loadProjectConfig.mockReturnValue({ packageManager: 'npm' });
+  normalizePackageManager.mockImplementation((value: unknown) =>
+    typeof value === 'string' ? value.toLowerCase() : undefined,
+  );
+});
+
+describe('registerConfigCommand', () => {
+  it('prints the current project config', async () => {
+    const logs: string[] = [];
+    jest.spyOn(console, 'log').mockImplementation((message?: string) => {
+      logs.push(String(message));
+    });
+    const program = new Command();
+    registerConfigCommand(program);
+
+    await program.parseAsync(['node', 'test', 'config', 'show']);
+
+    expect(logs.some((line) => line.includes('"packageManager"'))).toBe(true);
+  });
+
+  it('updates configuration values with automatic parsing', async () => {
+    const program = new Command();
+    registerConfigCommand(program);
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'config',
+      'set',
+      'packageManager',
+      'PNPM',
+    ]);
+    expect(normalizePackageManager).toHaveBeenCalledWith('PNPM');
+    expect(updateProjectConfig).toHaveBeenCalledWith(expect.any(String), {
+      packageManager: 'pnpm',
+    });
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'config',
+      'set',
+      'docker.defaultServices',
+      'api, postgres',
+    ]);
+    expect(updateProjectConfig).toHaveBeenCalledWith(expect.any(String), {
+      docker: { defaultServices: ['api', 'postgres'] },
+    });
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'config',
+      'set',
+      'limits.rate',
+      '50',
+    ]);
+    expect(updateProjectConfig).toHaveBeenCalledWith(expect.any(String), {
+      limits: { rate: 50 },
+    });
+  });
+});

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

@@ -0,0 +1,151 @@
+/*
+ * 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 runDev: (options?: any) => Promise<void>;
+
+beforeAll(async () => {
+  ({ runDev } = await import('../dev.js'));
+});
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  normalizePackageManager.mockImplementation((value: unknown) =>
+    typeof value === 'string' ? value.toLowerCase() : undefined,
+  );
+  resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
+  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
+});
+
+const baseConfig = {
+  devScript: 'dev',
+  startScript: 'start',
+  packageManager: 'pnpm',
+  docker: {
+    composeFile: 'docker/docker-compose.yml',
+    defaultServices: ['api'],
+  },
+  env: {
+    local: '.env',
+    localExample: '.env.example',
+    docker: '.env.docker',
+    dockerExample: '.env.docker.example',
+  },
+};
+
+describe('runDev', () => {
+  it('runs the dev script locally with env bootstrapping', async () => {
+    loadProjectConfig.mockReturnValue(baseConfig);
+    resolveEnvExample.mockReturnValue('.env.custom');
+
+    await runDev({ env: '.env.local' });
+
+    expect(assertHexabotProject).toHaveBeenCalled();
+    expect(resolveEnvExample).toHaveBeenCalledWith(
+      expect.any(String),
+      '.env.local',
+      baseConfig.env.localExample,
+    );
+    expect(bootstrapEnvFile).toHaveBeenCalledWith(
+      expect.any(String),
+      '.env.custom',
+      '.env.local',
+    );
+    expect(runPackageScript).toHaveBeenCalledWith(
+      'pnpm',
+      'dev',
+      expect.any(String),
+    );
+    expect(dockerCompose).not.toHaveBeenCalled();
+  });
+
+  it('updates the stored package manager when overridden', async () => {
+    loadProjectConfig.mockReturnValue({
+      ...baseConfig,
+      packageManager: 'npm',
+    });
+
+    await runDev({ pm: 'yarn', envBootstrap: false });
+
+    expect(updateProjectConfig).toHaveBeenCalledWith(expect.any(String), {
+      packageManager: 'yarn',
+    });
+    expect(bootstrapEnvFile).not.toHaveBeenCalled();
+  });
+
+  it('runs docker compose when the docker flag is provided', async () => {
+    loadProjectConfig.mockReturnValue(baseConfig);
+
+    await runDev({ docker: true, services: 'api,postgres', detach: true });
+
+    expect(bootstrapEnvFile).toHaveBeenCalledWith(
+      expect.any(String),
+      baseConfig.env.dockerExample,
+      baseConfig.env.docker,
+    );
+    expect(checkDocker).toHaveBeenCalled();
+    expect(ensureDockerFolder).toHaveBeenCalled();
+    expect(generateComposeFiles).toHaveBeenCalledWith(
+      '/tmp/docker/docker-compose.yml',
+      ['api', 'postgres'],
+      'dev',
+    );
+    expect(dockerCompose).toHaveBeenCalledWith(
+      expect.stringContaining('up --build -d'),
+    );
+    expect(runPackageScript).not.toHaveBeenCalled();
+  });
+});