@hexabot-ai/cli 3.0.0-alpha.3

package/src/commands/create.ts

@@ -0,0 +1,201 @@
+/*
+ * 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 { Command } from 'commander';
+
+import { ensureProjectConfig, loadProjectConfig } from '../core/config.js';
+import { bootstrapEnvFile } from '../core/env.js';
+import {
+  detectPackageManager,
+  installDependencies,
+  normalizePackageManager,
+} from '../core/package-manager.js';
+import { downloadAndExtractTemplate } from '../services/templates.js';
+import { validateProjectName } from '../utils/validation.js';
+
+import { runDev } from './dev.js';
+
+const DEFAULT_TEMPLATE_REPO = 'hexastack/hexabot-template-starter';
+
+interface CreateCommandOptions {
+  template?: string;
+  pm?: string;
+  noInstall?: boolean;
+  dev?: boolean;
+  docker?: boolean;
+  force?: boolean;
+}
+
+export const registerCreateCommand = (program: Command) => {
+  program
+    .command('create <projectName>')
+    .description('Create a new Hexabot project from the starter')
+    .option(
+      '-t, --template <name>',
+      'Project template to use (default: starter)',
+    )
+    .option('--pm <npm|pnpm|yarn|bun>', 'Preferred package manager')
+    .option('--no-install', 'Skip installing dependencies')
+    .option('--dev', 'Run hexabot dev after creation')
+    .option('--docker', 'Bootstrap Docker env files during creation')
+    .option('--force', 'Allow scaffolding into a non-empty directory')
+    .action(async (projectName: string, options: CreateCommandOptions) => {
+      await createProject(projectName, options);
+    });
+};
+
+const createProject = async (
+  projectName: string,
+  options: CreateCommandOptions,
+) => {
+  if (!validateProjectName(projectName)) {
+    console.error(
+      chalk.red(
+        'Invalid project name. Use lowercase letters, numbers, and dashes.',
+      ),
+    );
+    process.exit(1);
+  }
+
+  const projectPath = path.join(process.cwd(), projectName);
+  ensureTargetDirectory(projectPath, options.force);
+
+  const templateRepo = resolveTemplateRepo(options.template);
+  console.log(chalk.blue(`Using template ${templateRepo}`));
+
+  try {
+    const latestTag = await fetchLatestReleaseTag(templateRepo);
+    const templateUrl = `https://github.com/${templateRepo}/archive/refs/tags/${latestTag}.zip`;
+    await downloadAndExtractTemplate(templateUrl, projectPath);
+
+    const pmPreference = normalizePackageManager(options.pm);
+    const detectedPm = detectPackageManager(projectPath);
+    const packageManager = pmPreference || detectedPm;
+    const configOverrides: Partial<ReturnType<typeof loadProjectConfig>> = {
+      packageManager,
+    };
+
+    ensureProjectConfig(projectPath, configOverrides);
+    const config = loadProjectConfig(projectPath);
+
+    bootstrapEnvFile(projectPath, config.env.localExample, config.env.local, {
+      quiet: true,
+    });
+    if (options.docker) {
+      bootstrapEnvFile(
+        projectPath,
+        config.env.dockerExample,
+        config.env.docker,
+        { quiet: true },
+      );
+    }
+
+    if (options.noInstall) {
+      console.log(
+        chalk.yellow('Skipping dependency installation (--no-install).'),
+      );
+    } else {
+      console.log(
+        chalk.blue(`Installing dependencies with ${packageManager}...`),
+      );
+      installDependencies(packageManager, projectPath);
+    }
+
+    logSuccessMessage(projectName, { docker: options.docker });
+
+    if (options.dev) {
+      if (options.noInstall) {
+        console.log(
+          chalk.yellow(
+            'Dependencies were not installed. Run `npm install` before `--dev`.',
+          ),
+        );
+      } else {
+        console.log(chalk.blue('Starting dev server...'));
+        await runDev({
+          cwd: projectPath,
+          docker: options.docker,
+        });
+      }
+    }
+  } catch (error) {
+    console.error(chalk.red('Error creating project.'), error);
+    process.exit(1);
+  }
+};
+const resolveTemplateRepo = (template?: string) => {
+  if (!template) {
+    return DEFAULT_TEMPLATE_REPO;
+  }
+
+  if (template.includes('/')) {
+    return template;
+  }
+
+  return `hexastack/hexabot-template-${template}`;
+};
+const ensureTargetDirectory = (projectPath: string, force?: boolean) => {
+  if (fs.existsSync(projectPath)) {
+    const isEmpty = fs.readdirSync(projectPath).length === 0;
+    if (!isEmpty && !force) {
+      console.error(
+        chalk.red(
+          `Directory ${projectPath} is not empty. Use --force to scaffold anyway.`,
+        ),
+      );
+      process.exit(1);
+    }
+  } else {
+    fs.mkdirSync(projectPath, { recursive: true });
+  }
+};
+const fetchLatestReleaseTag = async (templateRepo: string) => {
+  const response = await fetch(
+    `https://api.github.com/repos/${templateRepo}/releases/latest`,
+  );
+  const data = await response.json();
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch the latest release information: ${data.message}`,
+    );
+  }
+
+  return data.tag_name;
+};
+const logSuccessMessage = (
+  projectName: string,
+  options: { docker?: boolean },
+) => {
+  console.log('\n');
+  console.log(chalk.green(`🎉 Project ${projectName} created successfully.`));
+  console.log('\n');
+  console.log(chalk.bgYellow.black(`Next steps:`));
+  console.log(chalk.gray(`1. Navigate to the project folder:`));
+  console.log(chalk.yellow(`   cd ${projectName}`));
+  if (options.docker) {
+    console.log(
+      chalk.gray(
+        `2. Run dev mode with Docker (or omit --docker for local sqlite):`,
+      ),
+    );
+    console.log(chalk.yellow(`   hexabot dev --docker`));
+  } else {
+    console.log(chalk.gray(`2. Start local dev server (SQLite by default):`));
+    console.log(chalk.yellow(`   hexabot dev`));
+  }
+  console.log(chalk.gray(`3. Explore docker helpers if needed:`));
+  console.log(chalk.yellow(`   hexabot docker up --services postgres`));
+  console.log(
+    chalk.gray(
+      `Need env files? Run ${chalk.white('hexabot env init --docker')}`,
+    ),
+  );
+  console.log('\n');
+};

package/src/commands/dev.ts

@@ -0,0 +1,122 @@
+/*
+ * 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 DevOptions {
+  docker?: boolean;
+  services?: string;
+  detach?: boolean;
+  env?: string;
+  envBootstrap?: boolean;
+  pm?: string;
+  cwd?: string;
+}
+
+export const registerDevCommand = (program: Command) => {
+  program
+    .command('dev')
+    .description('Run the current Hexabot project in development mode')
+    .option('--docker', 'Run using Docker')
+    .option(
+      '--services <list>',
+      'Comma-separated services or profiles to enable',
+    )
+    .option('-d, --detach', 'Detach Docker containers (Docker mode only)')
+    .option('--env <file>', 'Env file to use for local dev (default: .env)')
+    .option('--no-env-bootstrap', 'Skip env bootstrapping')
+    .option('--pm <npm|pnpm|yarn|bun>', 'Override package manager')
+    .action(async (options: DevOptions) => {
+      await runDev(options);
+    });
+};
+
+export const runDev = async (options: DevOptions = {}) => {
+  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 = options.envBootstrap !== false;
+  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 runDockerDev(projectRoot, options, config);
+  } else {
+    runPackageScript(pm, config.devScript, projectRoot);
+  }
+};
+
+const runDockerDev = async (
+  projectRoot: string,
+  options: DevOptions,
+  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, 'dev');
+  const upArgs = ['up', '--build'];
+  if (options.detach) {
+    upArgs.push('-d');
+  }
+
+  const composeCommand = `${composeArgs} ${upArgs.join(' ')}`.trim();
+  console.log(
+    chalk.blue(
+      `Starting Docker services${services.length ? ` (${services.join(', ')})` : ''}`,
+    ),
+  );
+  dockerCompose(composeCommand);
+};

package/src/commands/docker.ts

@@ -0,0 +1,190 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import * as path from 'path';
+
+import { Command } from 'commander';
+
+import { loadProjectConfig } from '../core/config.js';
+import {
+  dockerCompose,
+  generateComposeFiles,
+  resolveComposeFile,
+} from '../core/docker.js';
+import { bootstrapEnvFile } from '../core/env.js';
+import { checkDocker } from '../core/prerequisites.js';
+import { assertHexabotProject, ensureDockerFolder } from '../core/project.js';
+import { parseServices } from '../utils/services.js';
+
+import { runStart } from './start.js';
+
+export const registerDockerCommand = (program: Command) => {
+  const dockerCommand = program.command('docker').description('Docker helpers');
+
+  dockerCommand
+    .command('up')
+    .description('Start Docker services')
+    .option('--services <list>', 'Comma-separated services/profiles')
+    .option('-d, --detach', 'Run containers in the background')
+    .option('--build', 'Build images before starting')
+    .action(
+      (options: { services?: string; detach?: boolean; build?: boolean }) =>
+        runDockerCommand('up', options),
+    );
+
+  dockerCommand
+    .command('down')
+    .description('Stop Docker services')
+    .option('--services <list>', 'Comma-separated services/profiles')
+    .option('--volumes', 'Remove volumes')
+    .action((options: { services?: string; volumes?: boolean }) =>
+      runDockerCommand('down', options),
+    );
+
+  dockerCommand
+    .command('logs [service]')
+    .description('View Docker logs')
+    .option('-f, --follow', 'Follow logs')
+    .option('--since <time>', 'Only show logs since time (e.g. 1h)')
+    .action(
+      (
+        service: string | undefined,
+        options: { follow?: boolean; since?: string },
+      ) => runDockerLogs(service, options),
+    );
+
+  dockerCommand
+    .command('ps')
+    .description('List running services')
+    .action(() => runDockerPs());
+
+  dockerCommand
+    .command('start')
+    .description('Start Docker services in production mode')
+    .option('--services <list>', 'Comma-separated services/profiles')
+    .option('-d, --detach', 'Run containers in the background')
+    .option('--build', 'Build images before starting')
+    .option('--env-bootstrap', 'Generate env files from *.example if missing')
+    .action(
+      async (options: {
+        services?: string;
+        detach?: boolean;
+        build?: boolean;
+        envBootstrap?: boolean;
+      }) => {
+        await runStart({
+          docker: true,
+          services: options.services,
+          detach: options.detach,
+          build: options.build,
+          envBootstrap: options.envBootstrap,
+        });
+      },
+    );
+};
+
+const runDockerCommand = (
+  lifecycle: 'up' | 'down',
+  options: {
+    services?: string;
+    detach?: boolean;
+    build?: boolean;
+    volumes?: boolean;
+  },
+) => {
+  const projectRoot = path.resolve(process.cwd());
+  assertHexabotProject(projectRoot);
+  checkDocker({ silent: true });
+  const config = loadProjectConfig(projectRoot);
+  ensureDockerFolder(projectRoot);
+  const services = resolveServices(options.services, config);
+  const composeFile = resolveComposeFile(
+    projectRoot,
+    config.docker.composeFile,
+  );
+  const composeArgs = generateComposeFiles(
+    composeFile,
+    services,
+    lifecycle === 'up' ? 'dev' : undefined,
+  );
+
+  if (lifecycle === 'up') {
+    bootstrapEnvFile(projectRoot, config.env.dockerExample, config.env.docker, {
+      quiet: true,
+    });
+    const commandArgs = ['up'];
+    if (options.build) {
+      commandArgs.push('--build');
+    }
+    if (options.detach) {
+      commandArgs.push('-d');
+    }
+    dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim());
+  } else {
+    const commandArgs = ['down'];
+    if (options.volumes) {
+      commandArgs.push('-v');
+    }
+    dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim());
+  }
+};
+const runDockerLogs = (
+  service: string | undefined,
+  options: { follow?: boolean; since?: string },
+) => {
+  const projectRoot = path.resolve(process.cwd());
+  assertHexabotProject(projectRoot);
+  checkDocker({ silent: true });
+  const config = loadProjectConfig(projectRoot);
+  ensureDockerFolder(projectRoot);
+  const composeFile = resolveComposeFile(
+    projectRoot,
+    config.docker.composeFile,
+  );
+  const composeArgs = generateComposeFiles(
+    composeFile,
+    config.docker.defaultServices,
+    'dev',
+  );
+  const args = ['logs'];
+  if (options.follow) {
+    args.push('-f');
+  }
+  if (options.since) {
+    args.push(`--since ${options.since}`);
+  }
+  if (service) {
+    args.push(service);
+  }
+
+  dockerCompose(`${composeArgs} ${args.join(' ')}`.trim());
+};
+const runDockerPs = () => {
+  const projectRoot = path.resolve(process.cwd());
+  assertHexabotProject(projectRoot);
+  checkDocker({ silent: true });
+  const config = loadProjectConfig(projectRoot);
+  ensureDockerFolder(projectRoot);
+  const composeFile = resolveComposeFile(
+    projectRoot,
+    config.docker.composeFile,
+  );
+  const composeArgs = generateComposeFiles(
+    composeFile,
+    config.docker.defaultServices,
+    'dev',
+  );
+
+  dockerCompose(`${composeArgs} ps`);
+};
+const resolveServices = (
+  servicesInput: string | undefined,
+  config: ReturnType<typeof loadProjectConfig>,
+) => {
+  const provided = parseServices(servicesInput || '');
+
+  return provided.length ? provided : config.docker.defaultServices;
+};

package/src/commands/env.ts

@@ -0,0 +1,62 @@
+/*
+ * 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 } from '../core/config.js';
+import { bootstrapEnvFile, listEnvStatus } from '../core/env.js';
+import { assertHexabotProject } from '../core/project.js';
+
+export const registerEnvCommand = (program: Command) => {
+  const envCommand = program.command('env').description('Manage env files');
+
+  envCommand
+    .command('init')
+    .description('Copy *.example env files')
+    .option('--docker', 'Initialize Docker env file')
+    .option('--force', 'Overwrite existing env files')
+    .action((options: { docker?: boolean; force?: boolean }) => {
+      const projectRoot = path.resolve(process.cwd());
+      assertHexabotProject(projectRoot);
+      const config = loadProjectConfig(projectRoot);
+
+      if (options.docker) {
+        bootstrapEnvFile(
+          projectRoot,
+          config.env.dockerExample,
+          config.env.docker,
+          { force: options.force },
+        );
+      } else {
+        bootstrapEnvFile(
+          projectRoot,
+          config.env.localExample,
+          config.env.local,
+          {
+            force: options.force,
+          },
+        );
+      }
+    });
+
+  envCommand
+    .command('list')
+    .description('Show env file status')
+    .action(() => {
+      const projectRoot = path.resolve(process.cwd());
+      assertHexabotProject(projectRoot);
+      const config = loadProjectConfig(projectRoot);
+      const statuses = listEnvStatus(projectRoot, config);
+
+      statuses.forEach((status) => {
+        const symbol = status.exists ? chalk.green('✓') : chalk.red('✗');
+        console.log(`${symbol} ${status.file}`);
+      });
+    });
+};

package/src/commands/migrate.ts

@@ -0,0 +1,27 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Command } from 'commander';
+
+import { dockerExec } from '../core/docker.js';
+import { checkDocker } from '../core/prerequisites.js';
+import { ensureDockerFolder } from '../core/project.js';
+
+export const registerMigrateCommand = (program: Command) => {
+  program
+    .command('migrate [args...]')
+    .description('Run database migrations')
+    .action((args: string[] = []) => {
+      checkDocker({ silent: true });
+      ensureDockerFolder();
+      const migrateArgs = args.join(' ').trim();
+      const command = migrateArgs
+        ? `npm run migrate ${migrateArgs}`
+        : 'npm run migrate';
+
+      dockerExec('api', command, '--user $(id -u):$(id -g)');
+    });
+};