@hexabot-ai/cli 3.0.0-alpha.3

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "importOrderSeparation": true
+}

package/AGENTS.md

@@ -0,0 +1,64 @@
+# Hexabot CLI
+
+This file is the authoritative cheat-sheet for the Hexabot CLI. It summarizes the runtime bootstrap, core helpers, and per-command responsibilities so we can confidently extend or coordinate agent work without re-reading the entire codebase.
+
+## Runtime & Bootstrap
+
+- **Entry point**: `src/index.ts` prints the banner (`printBanner()`) and calls `checkPrerequisites({ silent: true })` before instantiating the Commander program. That pre-flight verifies Node.js (see below) so user-facing commands can assume a supported runtime.
+- **CLI factory**: `createCliProgram()` (`src/cli.ts`) builds the `Command` instance, configures name/description/version (`getCliVersion()`), and registers `check`, `create`, `config`, `dev`, `docker`, `env`, `start`, and `migrate` commands.
+- **Prerequisite gate**: `checkPrerequisites()` / `checkNodeVersion()` / `checkDocker()` (`src/core/prerequisites.ts`) centralize system checks. The top-level bootstrap validates Node (>= 20.18.1) while Docker checks are performed by commands that actually need Docker.
+- **Project guard**: `assertHexabotProject()` / `isHexabotProject()` (`src/core/project.ts`) enforce that commands run inside a workspace whose `package.json` depends on `@hexabot-ai/api`. Docker-aware commands also call `ensureDockerFolder()` which ensures `<projectRoot>/docker/` exists before touching compose files.
+- **Service parsing**: `parseServices()` (`src/utils/services.ts`) normalizes the shared `--services` flag to a de-duped string array so Docker helpers can safely compose per-service overlays.
+
+## Configuration & Environment Model
+
+- **Config file**: `hexabot.config.json` lives at the project root and is managed by `src/core/config.ts`. `loadProjectConfig()` merges user overrides with defaults (`devScript`, `startScript`, compose path `docker/docker-compose.yml`, env filenames, and optional `packageManager`). `ensureProjectConfig()` writes the file when scaffolding and `updateProjectConfig()` persists dot-notation updates from the CLI.
+- **Env helpers**: `bootstrapEnvFile()`, `listEnvStatus()`, and `resolveEnvExample()` (`src/core/env.ts`) copy `*.example` files when needed and report which env files exist. Commands never manipulate env paths directly—they rely on the config struct.
+- **Package managers**: `normalizePackageManager()`, `detectPackageManager()`, `runPackageScript()`, and `installDependencies()` (`src/core/package-manager.ts`) keep npm/pnpm/yarn/bun handling consistent. `runPackageScript()` verifies the requested script exists in `package.json` before executing it.
+
+## Docker Compose helpers
+
+- **Compose resolution**: `resolveComposeFile()` ensures config paths are absolute, while `generateComposeFiles()` (`src/core/docker.ts`) builds the `-f` flag chain. It always starts with the base file, then per-service overlays (`docker-compose.<service>.yml`), optional service/mode overlays (`docker-compose.<service>.<dev|prod>.yml`), and finally the global `docker-compose.<mode>.yml` when it exists.
+- **Execution wrappers**: `dockerCompose()` and `dockerExec()` (same module) print highlighted commands, run them via `execSync`, and exit with code `1` on Docker failures.
+
+## Subcommand Catalog
+
+| Command | Responsibilities | Options & IO | Implementation Notes |
+| --- | --- | --- | --- |
+| `check [--docker-only] [--no-docker]` | Run diagnostics for local Node version, Hexabot project detection, env files, and optionally Docker. | Flags narrow which checks run; outputs PASS/FAIL rows and sets exit code 1 if any check fails. | `src/commands/check.ts` calls `checkNodeVersion()`, `isHexabotProject()`, `loadProjectConfig()`, `listEnvStatus()`, and `checkDocker()` in sequence and prints results with chalk. |
+| `create <projectName>` | Scaffold a project from a GitHub template, configure package manager, bootstrap env files, install deps, and optionally start dev mode. | `--template`, `--pm`, `--no-install`, `--dev`, `--docker`, `--force`. Writes `hexabot.config.json` and new env files, installs deps (unless skipped), and can immediately run `hexabot dev`. | `src/commands/create.ts` validates the slug, downloads the latest release zip of `hexastack/hexabot-template-*` via `downloadAndExtractTemplate()`, ensures config/env files exist, installs dependencies via `installDependencies()`, and optionally calls `runDev()` for the new project. |
+| `config show` | Print the effective `hexabot.config.json` after merging defaults. | No flags; emits pretty-printed JSON. | `src/commands/config.ts` resolves the project root, asserts the workspace, and calls `loadProjectConfig()`. |
+| `config set <key> <value>` | Update nested config values via dot notation with type-aware parsing. | Supports booleans, numbers, JSON literals, comma lists (for `*Services` keys), and package-manager normalization. | Uses `parseValue()` + `buildOverride()` to construct overrides, writes via `updateProjectConfig()`, and echoes the new config. |
+| `dev [--docker] [--services] [-d] [--env] [--no-env-bootstrap] [--pm]` | Run the project in development mode using either the package script or Docker compose stack. | When not using Docker it runs the configured dev script (`dev` default) after optional env bootstrapping. Docker mode bootstraps the docker env file, resolves compose overlays, and runs `docker compose ... up --build [-d]`. | `src/commands/dev.ts` auto-detects the package manager, persists it into the config, handles env bootstrapping (local or docker), then either calls `runPackageScript()` or `runDockerDev()` (which uses `generateComposeFiles()` with mode `dev`). |
+| `start [--docker] [--services] [-d] [--build] [--env] [--env-bootstrap] [--pm]` | Production entry point mirroring `dev` but defaulting to the configured start script and prod compose overlays. | Local mode optionally bootstraps env files when `--env-bootstrap` is passed; Docker mode layers prod compose files, supports `--build`/`--detach`, and logs which services start. | `src/commands/start.ts` shares the package-manager persistence logic with `dev`. `runDockerStart()` enforces Docker availability, resolves compose overlays with mode `prod`, and shells out via `dockerCompose()`. |
+| ``docker up`` / ``docker down`` | Low-level Docker helpers for dev-mode compose stacks. | `up` supports `--services`, `--build`, `--detach`; `down` supports `--services` and `--volumes`. | `src/commands/docker.ts` ensures config + docker folder, resolves services (`parseServices()` with fallbacks to `config.docker.defaultServices`), bootstraps docker env files, and executes `docker compose ... up|down`. |
+| ``docker logs [service]`` / ``docker ps`` | Introspection helpers for the dev stack. | Logs accept `--follow`/`--since`. | Reuse `generateComposeFiles(..., 'dev')` plus targeted docker compose commands. |
+| ``docker start`` | Production-mode convenience wrapper for `hexabot start --docker`. | `--services`, `--detach`, `--build`, `--env-bootstrap`. | This subcommand simply calls `runStart({ docker: true, ... })` so behavior stays aligned with the main `start` command. |
+| `env init [--docker] [--force]` | Copy the configured `.env*` files from their `.example` counterparts. | By default bootstraps the local env; `--docker` switches to docker env paths; `--force` overwrites. | `src/commands/env.ts` calls `bootstrapEnvFile()` with the paths from the loaded config. |
+| `env list` | Show which env files exist. | None; prints ✓/✗ markers. | Uses `listEnvStatus()` results and chalk formatting. |
+| `migrate [args...]` | Execute database migrations inside the `api` container. | Arbitrary args are appended to `npm run migrate`. Requires a dockerized project root. | `src/commands/migrate.ts` checks Docker, ensures `docker/` exists, and runs `dockerExec('api', 'npm run migrate …', '--user $(id -u):$(id -g)')` so generated files share the host UID/GID. |
+
+## Shared Utilities & Services
+
+- **Template download**: `downloadAndExtractTemplate()` (`src/services/templates.ts`) fetches the release archive with `fetch`, saves it as `template.zip`, extracts using `decompress` (`strip: 1`), and then deletes the zip. `create` is the only consumer.
+- **Project metadata**: `readPackageJson()` (`src/core/project.ts`) powers package-manager validation and Hexabot project detection.
+- **Versioning**: `getCliVersion()` (`src/utils/version.ts`) reads `packages/cli/package.json` and defaults to `3.0.0` on failure.
+
+## Typical Workflow
+
+1. `hexabot create my-bot --docker` — scaffold a workspace, persist the preferred package manager into `hexabot.config.json`, bootstrap both local and docker env files, and install dependencies.
+2. `cd my-bot`
+3. `hexabot check` — confirm Node/Docker availability, project structure, and env files before running heavier commands.
+4. `hexabot env init` — re-run if you need to refresh `.env` files (use `--docker` to target docker envs).
+5. `hexabot dev --docker --services postgres,ollama` — spin up the dev stack with the requested services and `docker-compose.<service>.dev.yml` overlays.
+6. `hexabot start` or `hexabot start --docker --services api` — run production scripts locally or via Docker.
+7. `hexabot docker down --volumes` / `hexabot migrate` / `hexabot env list` as needed for lifecycle management.
+
+## Extending the CLI
+
+- Follow the established pattern under `src/commands/` by implementing `registerFooCommand(program: Command)` modules and wiring them up inside `createCliProgram()` so help/version wiring stays centralized.
+- Always gate project-specific commands with `assertHexabotProject()`, and guard docker-aware flows with both `checkDocker()` and `ensureDockerFolder()`.
+- Use `loadProjectConfig()` / `updateProjectConfig()` instead of hard-coding script names, env files, or compose paths. That keeps future overrides working automatically.
+- Share env initialization via `bootstrapEnvFile()` / `listEnvStatus()` and `--force` semantics rather than reimplementing file copies.
+- When adding compose-aware commands, rely on `parseServices()` and `generateComposeFiles()` so service overlays, dev/prod modes, and future compose conventions stay consistent.
+- Keep this AGENTS.md file updated whenever commands, defaults, or orchestrating helpers change so downstream automation never acts on stale assumptions.

package/README.md

@@ -0,0 +1,192 @@
+# Hexabot CLI
+
+Hexabot CLI is a powerful command-line tool to help manage your Hexabot project instance. With it, you can create new projects, initialize environments, start services in various modes, run database migrations, and more. The CLI aims to make managing your chatbot seamless and intuitive.
+
+
+Not yet familiar with [Hexabot](https://hexabot.ai/)? It's a open-source chatbot / agent solution that allows users to create and manage AI-powered, multi-channel, and multilingual chatbots with ease. If you would like to learn more, please visit the [official github repo](https://github.com/Hexastack/Hexabot/).
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 20.18.1
+- One package manager (`npm`, `pnpm`, `yarn`, or `bun`)
+- Docker Desktop/Engine (only required when you pass `--docker` or use `hexabot docker ...`)
+
+### Installation
+
+Install Hexabot CLI globally to have easy access to its commands:
+
+```sh
+npm install -g @hexabot-ai/cli
+```
+
+### Usage
+
+Once installed, you can use the `hexabot` command anywhere. The CLI focuses on a “zero to bot” flow: create a project, `cd` into it, and run `hexabot dev`. Docker is optional and available via `--docker` or the `hexabot docker ...` helpers.
+
+### Commands
+
+#### `create <project-name>`
+
+Scaffold a new Hexabot project from the official NestJS starter template.
+
+```sh
+hexabot create support-bot
+```
+
+Common options:
+
+- `-t, --template <name>` – template repository. Use `org/repo` or shorthand `starter`.
+- `--pm <npm|pnpm|yarn|bun>` – force a package manager (auto-detected otherwise).
+- `--no-install` – skip running the package manager after scaffolding.
+- `--dev` – immediately run `hexabot dev` once creation is complete.
+- `--docker` – bootstrap the Docker env file and hint about Docker-first commands.
+- `--force` – allow scaffolding into a non-empty directory.
+
+The command downloads the latest template release, installs dependencies (unless `--no-install`), and bootstraps `.env` (and `.env.docker` when `--docker` is passed).
+
+#### `dev`
+
+Run the current project in development mode. Defaults to local (SQLite) development by running the configured package script (defaults to `npm run dev`).
+
+```sh
+# Local dev
+hexabot dev
+
+# Docker dev with Postgres profile
+hexabot dev --docker --services postgres
+```
+
+Options:
+
+- `--docker` – run Docker Compose instead of the package script.
+- `--services <list>` – comma-separated Compose overlays/profiles to enable.
+- `-d, --detach` – detach Docker Compose.
+- `--env <file>` – custom env file for local dev (defaults to `.env`).
+- `--no-env-bootstrap` – skip copying `.env.example` files automatically.
+- `--pm <npm|pnpm|yarn|bun>` – temporarily override the package manager.
+
+#### `env`
+
+Helper commands to manage `.env` files.
+
+- `hexabot env init` – copy `.env.example` ➜ `.env`.
+- `hexabot env init --docker` – copy `.env.docker.example` ➜ `.env.docker`.
+- `hexabot env list` – show which env files exist or are missing.
+
+Flags: `--force` overwrites existing files when running `env init`.
+
+#### `docker`
+
+Quality-of-life wrappers around `docker compose` using the project’s `docker/` folder.
+
+- `hexabot docker up [--services <list>] [--build] [-d]`
+- `hexabot docker down [--services <list>] [--volumes]`
+- `hexabot docker logs [service] [-f | --since <1h>]`
+- `hexabot docker ps`
+- `hexabot docker start [--services <list>] [--build] [-d]` – convenience alias for `hexabot start --docker`
+
+The CLI automatically stitches together `docker-compose.yml` + `docker-compose.<service>.yml` overlays and can copy `.env.docker.example` on first run.
+
+#### `start`
+
+Production-oriented variant of `dev`.
+
+```sh
+hexabot start
+hexabot start --docker --services api,postgres --build
+```
+
+- Local mode runs the configured `start` script (defaults to `npm run start`).
+- Docker mode uses the “prod” compose overlays (e.g. `docker-compose.<service>.prod.yml`) so no dev-specific files are chained.
+- Pass `--env-bootstrap` if you still want the CLI to copy env examples automatically.
+
+#### `check`
+
+Run diagnostics for the current environment.
+
+```sh
+hexabot check
+hexabot check --docker-only
+```
+
+Outputs PASS/FAIL entries for Node.js version, project detection, env files, and optionally Docker.
+
+#### `config`
+
+Inspect or tweak `hexabot.config.json` without editing it manually.
+
+- `hexabot config show`
+- `hexabot config set <key> <value>` (supports dot notation, e.g. `docker.defaultServices "postgres,redis"`)
+
+#### `migrate [args...]`
+
+Run database migrations inside the Docker `api` container. Any extra args are forwarded to `npm run migrate`.
+
+## Example Workflow
+
+1. **Create a new project** (installs dependencies automatically unless `--no-install`):
+
+   ```sh
+   npx @hexabot-ai/cli create support-bot
+   ```
+
+2. **Enter the project and start local dev (SQLite, no Docker required)**:
+
+   ```sh
+   cd support-bot
+   hexabot dev
+   ```
+
+3. **Need infrastructure like Postgres or Redis? Opt in with Docker**:
+
+   ```sh
+   hexabot dev --docker --services postgres,redis
+   # or manage Docker services directly
+   hexabot docker up --services postgres
+   ```
+
+That’s it—`create → cd → dev` is the happy path, while Docker and env helpers remain available on demand.
+
+## Documentation
+
+For detailed information on how to get started, as well as in-depth user and developer guides, please refer to our full documentation available in the docs folder or visit the [Documentation](https://docs.hexabot.ai).
+
+You can also find specific documentation for different components of the project in the following locations:
+
+- [API Documentation](api/README.md)
+- [UI Documentation](frontend/README.md)
+- [Live Chat Widget Documentation](widget/README.md)
+- [NLU Engine Documentation](nlu/README.md)
+
+## Contributing
+
+We welcome contributions from the community! Whether you want to report a bug, suggest new features, or submit a pull request, your input is valuable to us.
+
+Please refer to our contribution policy first : [How to contribute to Hexabot](./CONTRIBUTING.md)
+
+
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](./CODE_OF_CONDUCT.md)
+
+Feel free to join us on [Discord](https://discord.gg/rNb9t2MFkG)
+
+## License
+
+Copyright (c) 2025 Hexastack.
+
+This project is licensed under the **Fair Core License, Version 1.0**, with **Apache License 2.0** as the future license (abbrev. **FCL-1.0-ALv2**).
+
+**Change date.** For each version of the software, the Fair Core License converts to Apache-2.0 on the **second anniversary** of the date that version is made available.
+
+**Commercial features & license keys.** Certain features of Hexabot are protected by license-key checks. You **must not** remove, modify, disable, or circumvent those checks, nor enable access to protected functionality without a valid license key.
+
+**Competing uses (non-compete).** Use that competes with Hexastack’s business—for example, offering Hexabot (or a substantially similar service) as a hosted or commercial product—is not permitted until the conversion to Apache-2.0 for the applicable version.
+
+**Redistribution.** If you distribute copies, modifications, or derivatives, you must include this license and not remove copyright or proprietary notices.
+
+**Patents.** A limited patent license is granted for permitted uses and terminates on patent aggression.
+
+**Trademarks.** “Hexabot” and “Hexastack” are trademarks. Except to identify Hexastack as the origin of the software, no trademark rights are granted.
+
+**Disclaimer.** The software is provided “AS IS,” without warranties or conditions of any kind, and Hexastack will not be liable for any damages arising from its use.

package/dist/cli.js

@@ -0,0 +1,31 @@
+/*
+ * 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/dist/commands/__tests__/check.test.js

@@ -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 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;
+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 = [];
+        jest.spyOn(console, 'log').mockImplementation((message) => {
+            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 = [];
+        jest.spyOn(console, 'log').mockImplementation((message) => {
+            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/dist/commands/__tests__/config.test.js

@@ -0,0 +1,80 @@
+/*
+ * 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;
+beforeAll(async () => {
+    ({ registerConfigCommand } = await import('../config.js'));
+});
+beforeEach(() => {
+    jest.resetAllMocks();
+    loadProjectConfig.mockReturnValue({ packageManager: 'npm' });
+    normalizePackageManager.mockImplementation((value) => typeof value === 'string' ? value.toLowerCase() : undefined);
+});
+describe('registerConfigCommand', () => {
+    it('prints the current project config', async () => {
+        const logs = [];
+        jest.spyOn(console, 'log').mockImplementation((message) => {
+            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/dist/commands/__tests__/dev.test.js

@@ -0,0 +1,105 @@
+/*
+ * 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) => value.split(',').filter(Boolean),
+}));
+let runDev;
+beforeAll(async () => {
+    ({ runDev } = await import('../dev.js'));
+});
+beforeEach(() => {
+    jest.resetAllMocks();
+    normalizePackageManager.mockImplementation((value) => 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();
+    });
+});