@hexabot-ai/cli 3.4.0 → 3.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -5,7 +5,7 @@ This file is the authoritative cheat-sheet for the Hexabot CLI. It summarizes th
5
5
  ## Runtime & Bootstrap
6
6
 
7
7
  - **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.
8
- - **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.
8
+ - **CLI factory**: `createCliProgram()` (`src/cli.ts`) builds the `Command` instance, configures name/description/version (`getCliVersion()`), and registers `check`, `create`, `config`, `dev`, `env`, `start`, `stop`, and `migrate` commands.
9
9
  - **Prerequisite gate**: `checkPrerequisites()` / `checkNodeVersion()` / `checkDocker()` (`src/core/prerequisites.ts`) centralize system checks. The top-level bootstrap validates Node (>= 24.17.0) while Docker checks are performed by commands that actually need Docker.
10
10
  - **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.
11
11
  - **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.
@@ -29,11 +29,9 @@ This file is the authoritative cheat-sheet for the Hexabot CLI. It summarizes th
29
29
  | `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`, bootstraps local and Docker env files, persists initial admin seed credentials, sets `COMPOSE_PROJECT_NAME` in `.env.docker`, installs deps (unless skipped), and can immediately run `hexabot dev`. Post-create output should clearly present `hexabot dev` as local SQLite mode and `hexabot dev --docker --services postgres` as Docker plus Postgres mode. | `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. |
30
30
  | `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()`. |
31
31
  | `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. |
32
- | `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 --env-file .env.docker ... up --build [-d]` when the Docker env exists. | `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`). |
33
- | `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`, passes `.env.docker` to Compose when present, 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()`. |
34
- | ``docker up`` / ``docker down`` | Low-level Docker helpers for dev-mode compose stacks. | `up` supports `--services`, `--build`, `--detach`; `down` supports `--services` and `--volumes`. Both pass `.env.docker` to Compose when present. | `src/commands/docker.ts` ensures config + docker folder, resolves services (`parseServices()` with fallbacks to `config.docker.defaultServices`), bootstraps docker env files for `up`, and executes `docker compose ... up|down`. |
35
- | ``docker logs [service]`` / ``docker ps`` | Introspection helpers for the dev stack. | Logs accept `--follow`/`--since`. | Reuse `generateComposeFiles(..., 'dev')` plus targeted docker compose commands. |
36
- | ``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. |
32
+ | `dev [--docker] [--services <list>] [-d] [--env <file>] [--no-env-bootstrap] [--pm <manager>]` | 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 --env-file .env.docker ... up --build [-d]` when the Docker env exists. | `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`). |
33
+ | `start [--docker] [--services <list>] [-d] [--build] [--env <file>] [--env-bootstrap] [--pm <manager>]` | 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, never pulls Hexabot application images, supports local builds with `--build`, passes `.env.docker` to Compose when present, 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()`. |
34
+ | `stop --docker [--services <list>] [-v] [--remove-orphans]` | Tear down the Docker stack started by `dev --docker` / `start --docker`. | `--docker` is mandatory: without it the command errors out (local `dev`/`start` are foreground processes stopped with Ctrl+C). `--volumes` and `--remove-orphans` map to the matching `docker compose down` flags. | `src/commands/stop.ts` resolves services from `--services` or `docker.defaultServices`, builds the `-f` chain with `generateComposeFiles()` **without** a mode overlay, and runs `docker compose --env-file .env.docker ... down` via `dockerCompose()` so the compose project name matches the started stack. |
37
35
  | `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. |
38
36
  | `env list` | Show which env files exist. | None; prints ✓/✗ markers. | Uses `listEnvStatus()` results and chalk formatting. |
39
37
  | `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. |
@@ -53,7 +51,8 @@ This file is the authoritative cheat-sheet for the Hexabot CLI. It summarizes th
53
51
  5. `hexabot dev` — run local dev with SQLite.
54
52
  6. `hexabot dev --docker --services postgres` — run dev with Docker and Postgres when needed.
55
53
  7. `hexabot start` or `hexabot start --docker --services api` — run production scripts locally or via Docker.
56
- 8. `hexabot docker down --volumes` / `hexabot migrate` / `hexabot env list` as needed for lifecycle management.
54
+ 8. `hexabot stop --docker` — tear down the Docker stack (add `-v` to drop volumes).
55
+ 9. `hexabot migrate` / `hexabot env list` as needed for lifecycle management.
57
56
 
58
57
  ## Extending the CLI
59
58
 
package/README.md CHANGED
@@ -10,7 +10,7 @@ Not yet familiar with [Hexabot](https://hexabot.ai/)? Hexabot v3 is an agentic A
10
10
 
11
11
  - Node.js >= 24.17.0
12
12
  - One package manager (`npm`, `pnpm`, `yarn`, or `bun`)
13
- - Docker Desktop/Engine (only required when you pass `--docker` or use `hexabot docker ...`)
13
+ - Docker Desktop/Engine (only required when you pass `--docker`)
14
14
 
15
15
  ### Installation
16
16
 
@@ -22,7 +22,7 @@ npm install -g @hexabot-ai/cli
22
22
 
23
23
  ### Usage
24
24
 
25
- Once installed, you can use the `hexabot` command anywhere. The CLI focuses on a “zero to running workflow automation” path: create a project, `cd` into it, and run `hexabot dev`. Docker is optional and available via `--docker` or the `hexabot docker ...` helpers.
25
+ Once installed, you can use the `hexabot` command anywhere. The CLI focuses on a “zero to running workflow automation” path: create a project, `cd` into it, and run `hexabot dev`. Docker is optional and available through the `--docker` option on `dev`, `start`, and `stop`.
26
26
 
27
27
  ### Commands
28
28
 
@@ -76,18 +76,6 @@ Helper commands to manage `.env` files.
76
76
 
77
77
  Flags: `--force` overwrites existing files when running `env init`.
78
78
 
79
- #### `docker`
80
-
81
- Quality-of-life wrappers around `docker compose` using the project’s `docker/` folder.
82
-
83
- - `hexabot docker up [--services <list>] [--build] [-d]`
84
- - `hexabot docker down [--services <list>] [--volumes]`
85
- - `hexabot docker logs [service] [-f | --since <1h>]`
86
- - `hexabot docker ps`
87
- - `hexabot docker start [--services <list>] [--build] [-d]` – convenience alias for `hexabot start --docker`
88
-
89
- The CLI automatically stitches together `docker-compose.yml` + `docker-compose.<service>.yml` overlays, can copy `.env.docker.example` on first run, and passes `.env.docker` to Docker Compose with `--env-file` when it exists.
90
-
91
79
  #### `start`
92
80
 
93
81
  Production-oriented variant of `dev`.
@@ -99,8 +87,26 @@ hexabot start --docker --services api,postgres --build
99
87
 
100
88
  - Local mode runs the configured `start` script (defaults to `npm run start`).
101
89
  - Docker mode uses the “prod” compose overlays (e.g. `docker-compose.<service>.prod.yml`) so no dev-specific files are chained.
90
+ - Docker mode never pulls the Hexabot application images. It uses locally available production images; pass `--build` to build or rebuild them locally.
91
+ - Docker mode automatically stitches together the base Compose file and service overlays, and passes `.env.docker` through `--env-file` when it exists.
102
92
  - Pass `--env-bootstrap` if you still want the CLI to copy env examples automatically.
103
93
 
94
+ #### `stop`
95
+
96
+ Stop the Docker stack previously started with `dev --docker` or `start --docker`.
97
+
98
+ ```sh
99
+ hexabot start --docker -d
100
+ hexabot stop --docker
101
+ ```
102
+
103
+ - `--docker` – required; the CLI only manages the Docker stack. Local `dev`/`start` run in the foreground, so stop them with Ctrl+C.
104
+ - `--services <list>` – comma-separated Compose overlays/profiles to chain (defaults to `docker.defaultServices`).
105
+ - `-v, --volumes` – also remove the named volumes declared by the stack (destroys database data).
106
+ - `--remove-orphans` – remove containers that are no longer defined by the chained Compose files.
107
+
108
+ The command runs `docker compose ... down` with the base Compose file plus service overlays (no dev/prod overlay), and passes `.env.docker` through `--env-file` when it exists so `COMPOSE_PROJECT_NAME` resolves to the same project that was started.
109
+
104
110
  #### `check`
105
111
 
106
112
  Run diagnostics for the current environment.
@@ -144,11 +150,17 @@ Run database migrations inside the Docker `api` container. Any extra args are fo
144
150
  hexabot dev --docker --services postgres
145
151
  ```
146
152
 
153
+ 4. **Tear the Docker stack down when you are done**:
154
+
155
+ ```sh
156
+ hexabot stop --docker
157
+ ```
158
+
147
159
  That’s it—`create → cd → dev` is the happy path for a new Hexabot v3 automation project, while Docker and env helpers remain available on demand.
148
160
 
149
161
  ## Documentation
150
162
 
151
- 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).
163
+ For detailed information on how to get started, see the repository README files below or visit the [Documentation](https://docs.hexabot.ai).
152
164
 
153
165
  You can also find specific documentation for different components of the project in the following locations:
154
166
 
package/dist/cli.js CHANGED
@@ -8,10 +8,10 @@ import { registerCheckCommand } from './commands/check.js';
8
8
  import { registerConfigCommand } from './commands/config.js';
9
9
  import { registerCreateCommand } from './commands/create.js';
10
10
  import { registerDevCommand } from './commands/dev.js';
11
- import { registerDockerCommand } from './commands/docker.js';
12
11
  import { registerEnvCommand } from './commands/env.js';
13
12
  import { registerMigrateCommand } from './commands/migrate.js';
14
13
  import { registerStartCommand } from './commands/start.js';
14
+ import { registerStopCommand } from './commands/stop.js';
15
15
  import { getCliVersion } from './utils/version.js';
16
16
  export const createCliProgram = () => {
17
17
  const program = new Command();
@@ -23,9 +23,9 @@ export const createCliProgram = () => {
23
23
  registerCreateCommand(program);
24
24
  registerConfigCommand(program);
25
25
  registerDevCommand(program);
26
- registerDockerCommand(program);
27
26
  registerEnvCommand(program);
28
27
  registerStartCommand(program);
28
+ registerStopCommand(program);
29
29
  registerMigrateCommand(program);
30
30
  return program;
31
31
  };
@@ -0,0 +1,56 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+ import * as path from 'path';
7
+ import chalk from 'chalk';
8
+ import { loadProjectConfig } from '../core/config.js';
9
+ import { dockerCompose, generateComposeFiles, resolveComposeEnvFile, resolveComposeFile, } from '../core/docker.js';
10
+ import { checkDocker } from '../core/prerequisites.js';
11
+ import { assertHexabotProject, ensureDockerFolder } from '../core/project.js';
12
+ import { parseServices } from '../utils/services.js';
13
+ export const registerStopCommand = (program) => {
14
+ program
15
+ .command('stop')
16
+ .description('Stop the Docker stack started with `dev`/`start`')
17
+ .option('--docker', 'Stop the Docker services (required)')
18
+ .option('--services <list>', 'Comma-separated services/profiles to stop')
19
+ .option('-v, --volumes', 'Remove named volumes declared by the stack')
20
+ .option('--remove-orphans', 'Remove containers not defined in the stack')
21
+ .action(async (options) => {
22
+ await runStop(options);
23
+ });
24
+ };
25
+ export const runStop = async (options = {}) => {
26
+ const projectRoot = path.resolve(options.cwd || process.cwd());
27
+ assertHexabotProject(projectRoot);
28
+ if (!options.docker) {
29
+ console.error(chalk.red('`hexabot stop` only manages the Docker stack.'));
30
+ console.log(chalk.yellow('Run `hexabot stop --docker`. Local `dev`/`start` runs in the foreground—press Ctrl+C to stop it.'));
31
+ process.exit(1);
32
+ }
33
+ const config = loadProjectConfig(projectRoot);
34
+ await runDockerStop(projectRoot, options, config);
35
+ };
36
+ const runDockerStop = async (projectRoot, options, config) => {
37
+ checkDocker({ silent: true });
38
+ ensureDockerFolder(projectRoot);
39
+ const servicesInput = parseServices(options.services || '');
40
+ const services = servicesInput.length
41
+ ? servicesInput
42
+ : config.docker.defaultServices;
43
+ const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
44
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
45
+ const composeArgs = generateComposeFiles(composeFile, services);
46
+ const downArgs = ['down'];
47
+ if (options.volumes) {
48
+ downArgs.push('--volumes');
49
+ }
50
+ if (options.removeOrphans) {
51
+ downArgs.push('--remove-orphans');
52
+ }
53
+ const composeCommand = `${composeArgs} ${downArgs.join(' ')}`.trim();
54
+ console.log(chalk.blue(`Stopping Docker services${services.length ? ` (${services.join(', ')})` : ''}`));
55
+ dockerCompose(composeCommand, { envFile });
56
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hexabot-ai/cli",
3
- "version": "3.4.0",
3
+ "version": "3.4.3",
4
4
  "description": "Official Hexabot CLI for creating and managing AI chatbot/agent projects built with Hexabot.",
5
5
  "main": "dist/index.js",
6
6
  "type": "module",
@@ -22,16 +22,13 @@
22
22
  "axios": "^1.18.1",
23
23
  "chalk": "^5.3.0",
24
24
  "commander": "^12.1.0",
25
- "degit": "^2.8.4",
26
- "dotenv": "^16.4.5",
27
25
  "figlet": "^1.7.0"
28
26
  },
29
27
  "devDependencies": {
30
28
  "@jest/globals": "^30.4.1",
31
- "@types/degit": "^2.8.6",
32
29
  "@types/figlet": "^1.5.8",
33
30
  "@types/jest": "^30.0.0",
34
- "@types/node": "^22.7.4",
31
+ "@types/node": "^24.1.0",
35
32
  "@typescript-eslint/eslint-plugin": "^8.46.0",
36
33
  "@typescript-eslint/parser": "^8.46.0",
37
34
  "cross-env": "^10.1.0",
package/src/cli.ts CHANGED
@@ -10,10 +10,10 @@ import { registerCheckCommand } from './commands/check.js';
10
10
  import { registerConfigCommand } from './commands/config.js';
11
11
  import { registerCreateCommand } from './commands/create.js';
12
12
  import { registerDevCommand } from './commands/dev.js';
13
- import { registerDockerCommand } from './commands/docker.js';
14
13
  import { registerEnvCommand } from './commands/env.js';
15
14
  import { registerMigrateCommand } from './commands/migrate.js';
16
15
  import { registerStartCommand } from './commands/start.js';
16
+ import { registerStopCommand } from './commands/stop.js';
17
17
  import { getCliVersion } from './utils/version.js';
18
18
 
19
19
  export const createCliProgram = () => {
@@ -28,9 +28,9 @@ export const createCliProgram = () => {
28
28
  registerCreateCommand(program);
29
29
  registerConfigCommand(program);
30
30
  registerDevCommand(program);
31
- registerDockerCommand(program);
32
31
  registerEnvCommand(program);
33
32
  registerStartCommand(program);
33
+ registerStopCommand(program);
34
34
  registerMigrateCommand(program);
35
35
 
36
36
  return program;
@@ -0,0 +1,130 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import { jest } from '@jest/globals';
8
+
9
+ const loadProjectConfig = jest.fn();
10
+ const dockerCompose = jest.fn();
11
+ const generateComposeFiles = jest.fn();
12
+ const resolveComposeEnvFile = jest.fn();
13
+ const resolveComposeFile = jest.fn();
14
+ const checkDocker = jest.fn();
15
+ const assertHexabotProject = jest.fn();
16
+ const ensureDockerFolder = jest.fn();
17
+
18
+ jest.unstable_mockModule('../../core/config.js', () => ({
19
+ loadProjectConfig,
20
+ }));
21
+
22
+ jest.unstable_mockModule('../../core/docker.js', () => ({
23
+ dockerCompose,
24
+ generateComposeFiles,
25
+ resolveComposeEnvFile,
26
+ resolveComposeFile,
27
+ }));
28
+
29
+ jest.unstable_mockModule('../../core/prerequisites.js', () => ({
30
+ checkDocker,
31
+ }));
32
+
33
+ jest.unstable_mockModule('../../core/project.js', () => ({
34
+ assertHexabotProject,
35
+ ensureDockerFolder,
36
+ }));
37
+
38
+ jest.unstable_mockModule('../../utils/services.js', () => ({
39
+ parseServices: (value: string) => value.split(',').filter(Boolean),
40
+ }));
41
+
42
+ let runStop: (options?: any) => Promise<void>;
43
+
44
+ beforeAll(async () => {
45
+ ({ runStop } = await import('../stop.js'));
46
+ });
47
+
48
+ beforeEach(() => {
49
+ jest.resetAllMocks();
50
+ });
51
+
52
+ describe('runStop', () => {
53
+ const baseConfig = {
54
+ docker: {
55
+ composeFile: 'docker/docker-compose.yml',
56
+ defaultServices: ['api'],
57
+ },
58
+ env: {
59
+ docker: '.env.docker',
60
+ dockerExample: '.env.docker.example',
61
+ },
62
+ };
63
+
64
+ it('runs docker compose down for the configured services', async () => {
65
+ loadProjectConfig.mockReturnValue(baseConfig);
66
+ resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
67
+ resolveComposeEnvFile.mockReturnValue('/tmp/.env.docker');
68
+ generateComposeFiles.mockReturnValue('-f docker-compose.yml');
69
+
70
+ await runStop({ docker: true });
71
+
72
+ expect(assertHexabotProject).toHaveBeenCalled();
73
+ expect(checkDocker).toHaveBeenCalled();
74
+ expect(ensureDockerFolder).toHaveBeenCalled();
75
+ expect(generateComposeFiles).toHaveBeenCalledWith(
76
+ '/tmp/docker/docker-compose.yml',
77
+ ['api'],
78
+ );
79
+ expect(resolveComposeEnvFile).toHaveBeenCalledWith(
80
+ expect.any(String),
81
+ baseConfig.env.docker,
82
+ );
83
+ expect(dockerCompose).toHaveBeenCalledWith('-f docker-compose.yml down', {
84
+ envFile: '/tmp/.env.docker',
85
+ });
86
+ });
87
+
88
+ it('forwards the requested services, volumes and orphan cleanup', async () => {
89
+ loadProjectConfig.mockReturnValue(baseConfig);
90
+ resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
91
+ resolveComposeEnvFile.mockReturnValue(undefined);
92
+ generateComposeFiles.mockReturnValue('-f docker-compose.yml');
93
+
94
+ await runStop({
95
+ docker: true,
96
+ services: 'api,postgres',
97
+ volumes: true,
98
+ removeOrphans: true,
99
+ });
100
+
101
+ expect(generateComposeFiles).toHaveBeenCalledWith(
102
+ '/tmp/docker/docker-compose.yml',
103
+ ['api', 'postgres'],
104
+ );
105
+ expect(dockerCompose).toHaveBeenCalledWith(
106
+ '-f docker-compose.yml down --volumes --remove-orphans',
107
+ { envFile: undefined },
108
+ );
109
+ });
110
+
111
+ it('exits when --docker is missing', async () => {
112
+ const exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => {
113
+ throw new Error('exit:1');
114
+ }) as () => never);
115
+ const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
116
+ const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
117
+ loadProjectConfig.mockReturnValue(baseConfig);
118
+
119
+ await expect(runStop()).rejects.toThrow('exit:1');
120
+
121
+ expect(exitSpy).toHaveBeenCalledWith(1);
122
+ expect(errorSpy).toHaveBeenCalled();
123
+ expect(checkDocker).not.toHaveBeenCalled();
124
+ expect(dockerCompose).not.toHaveBeenCalled();
125
+
126
+ exitSpy.mockRestore();
127
+ errorSpy.mockRestore();
128
+ logSpy.mockRestore();
129
+ });
130
+ });
@@ -0,0 +1,96 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import * as path from 'path';
8
+
9
+ import chalk from 'chalk';
10
+ import { Command } from 'commander';
11
+
12
+ import { loadProjectConfig } from '../core/config.js';
13
+ import {
14
+ dockerCompose,
15
+ generateComposeFiles,
16
+ resolveComposeEnvFile,
17
+ resolveComposeFile,
18
+ } from '../core/docker.js';
19
+ import { checkDocker } from '../core/prerequisites.js';
20
+ import { assertHexabotProject, ensureDockerFolder } from '../core/project.js';
21
+ import { parseServices } from '../utils/services.js';
22
+
23
+ export interface StopOptions {
24
+ docker?: boolean;
25
+ services?: string;
26
+ volumes?: boolean;
27
+ removeOrphans?: boolean;
28
+ cwd?: string;
29
+ }
30
+
31
+ export const registerStopCommand = (program: Command) => {
32
+ program
33
+ .command('stop')
34
+ .description('Stop the Docker stack started with `dev`/`start`')
35
+ .option('--docker', 'Stop the Docker services (required)')
36
+ .option('--services <list>', 'Comma-separated services/profiles to stop')
37
+ .option('-v, --volumes', 'Remove named volumes declared by the stack')
38
+ .option('--remove-orphans', 'Remove containers not defined in the stack')
39
+ .action(async (options: StopOptions) => {
40
+ await runStop(options);
41
+ });
42
+ };
43
+
44
+ export const runStop = async (options: StopOptions = {}) => {
45
+ const projectRoot = path.resolve(options.cwd || process.cwd());
46
+ assertHexabotProject(projectRoot);
47
+
48
+ if (!options.docker) {
49
+ console.error(chalk.red('`hexabot stop` only manages the Docker stack.'));
50
+ console.log(
51
+ chalk.yellow(
52
+ 'Run `hexabot stop --docker`. Local `dev`/`start` runs in the foreground—press Ctrl+C to stop it.',
53
+ ),
54
+ );
55
+ process.exit(1);
56
+ }
57
+
58
+ const config = loadProjectConfig(projectRoot);
59
+ await runDockerStop(projectRoot, options, config);
60
+ };
61
+
62
+ const runDockerStop = async (
63
+ projectRoot: string,
64
+ options: StopOptions,
65
+ config: ReturnType<typeof loadProjectConfig>,
66
+ ) => {
67
+ checkDocker({ silent: true });
68
+ ensureDockerFolder(projectRoot);
69
+ const servicesInput = parseServices(options.services || '');
70
+ const services = servicesInput.length
71
+ ? servicesInput
72
+ : config.docker.defaultServices;
73
+ const composeFile = resolveComposeFile(
74
+ projectRoot,
75
+ config.docker.composeFile,
76
+ );
77
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
78
+ const composeArgs = generateComposeFiles(composeFile, services);
79
+ const downArgs = ['down'];
80
+ if (options.volumes) {
81
+ downArgs.push('--volumes');
82
+ }
83
+ if (options.removeOrphans) {
84
+ downArgs.push('--remove-orphans');
85
+ }
86
+
87
+ const composeCommand = `${composeArgs} ${downArgs.join(' ')}`.trim();
88
+ console.log(
89
+ chalk.blue(
90
+ `Stopping Docker services${
91
+ services.length ? ` (${services.join(', ')})` : ''
92
+ }`,
93
+ ),
94
+ );
95
+ dockerCompose(composeCommand, { envFile });
96
+ };
@@ -1,127 +0,0 @@
1
- /*
2
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
- * Copyright (c) 2025 Hexastack.
4
- * Full terms: see LICENSE.md.
5
- */
6
- import * as path from 'path';
7
- import { loadProjectConfig } from '../core/config.js';
8
- import { dockerCompose, generateComposeFiles, resolveComposeEnvFile, resolveComposeFile, } from '../core/docker.js';
9
- import { bootstrapEnvFile } from '../core/env.js';
10
- import { checkDocker } from '../core/prerequisites.js';
11
- import { assertHexabotProject, ensureDockerFolder } from '../core/project.js';
12
- import { parseServices } from '../utils/services.js';
13
- import { runStart } from './start.js';
14
- export const registerDockerCommand = (program) => {
15
- const dockerCommand = program.command('docker').description('Docker helpers');
16
- dockerCommand
17
- .command('up')
18
- .description('Start Docker services')
19
- .option('--services <list>', 'Comma-separated services/profiles')
20
- .option('-d, --detach', 'Run containers in the background')
21
- .option('--build', 'Build images before starting')
22
- .action((options) => runDockerCommand('up', options));
23
- dockerCommand
24
- .command('down')
25
- .description('Stop Docker services')
26
- .option('--services <list>', 'Comma-separated services/profiles')
27
- .option('--volumes', 'Remove volumes')
28
- .action((options) => runDockerCommand('down', options));
29
- dockerCommand
30
- .command('logs [service]')
31
- .description('View Docker logs')
32
- .option('-f, --follow', 'Follow logs')
33
- .option('--since <time>', 'Only show logs since time (e.g. 1h)')
34
- .action((service, options) => runDockerLogs(service, options));
35
- dockerCommand
36
- .command('ps')
37
- .description('List running services')
38
- .action(() => runDockerPs());
39
- dockerCommand
40
- .command('start')
41
- .description('Start Docker services in production mode')
42
- .option('--services <list>', 'Comma-separated services/profiles')
43
- .option('-d, --detach', 'Run containers in the background')
44
- .option('--build', 'Build images before starting')
45
- .option('--env-bootstrap', 'Generate env files from *.example if missing')
46
- .action(async (options) => {
47
- await runStart({
48
- docker: true,
49
- services: options.services,
50
- detach: options.detach,
51
- build: options.build,
52
- envBootstrap: options.envBootstrap,
53
- });
54
- });
55
- };
56
- const runDockerCommand = (lifecycle, options) => {
57
- const projectRoot = path.resolve(process.cwd());
58
- assertHexabotProject(projectRoot);
59
- checkDocker({ silent: true });
60
- const config = loadProjectConfig(projectRoot);
61
- ensureDockerFolder(projectRoot);
62
- const services = resolveServices(options.services, config);
63
- const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
64
- const composeArgs = generateComposeFiles(composeFile, services, lifecycle === 'up' ? 'dev' : undefined);
65
- if (lifecycle === 'up') {
66
- bootstrapEnvFile(projectRoot, config.env.dockerExample, config.env.docker, {
67
- quiet: true,
68
- });
69
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
70
- const commandArgs = ['up'];
71
- if (options.build) {
72
- commandArgs.push('--build');
73
- }
74
- if (options.detach) {
75
- commandArgs.push('-d');
76
- }
77
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
78
- envFile,
79
- });
80
- }
81
- else {
82
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
83
- const commandArgs = ['down'];
84
- if (options.volumes) {
85
- commandArgs.push('-v');
86
- }
87
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
88
- envFile,
89
- });
90
- }
91
- };
92
- const runDockerLogs = (service, options) => {
93
- const projectRoot = path.resolve(process.cwd());
94
- assertHexabotProject(projectRoot);
95
- checkDocker({ silent: true });
96
- const config = loadProjectConfig(projectRoot);
97
- ensureDockerFolder(projectRoot);
98
- const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
99
- const composeArgs = generateComposeFiles(composeFile, config.docker.defaultServices, 'dev');
100
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
101
- const args = ['logs'];
102
- if (options.follow) {
103
- args.push('-f');
104
- }
105
- if (options.since) {
106
- args.push(`--since ${options.since}`);
107
- }
108
- if (service) {
109
- args.push(service);
110
- }
111
- dockerCompose(`${composeArgs} ${args.join(' ')}`.trim(), { envFile });
112
- };
113
- const runDockerPs = () => {
114
- const projectRoot = path.resolve(process.cwd());
115
- assertHexabotProject(projectRoot);
116
- checkDocker({ silent: true });
117
- const config = loadProjectConfig(projectRoot);
118
- ensureDockerFolder(projectRoot);
119
- const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
120
- const composeArgs = generateComposeFiles(composeFile, config.docker.defaultServices, 'dev');
121
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
122
- dockerCompose(`${composeArgs} ps`, { envFile });
123
- };
124
- const resolveServices = (servicesInput, config) => {
125
- const provided = parseServices(servicesInput || '');
126
- return provided.length ? provided : config.docker.defaultServices;
127
- };
@@ -1,180 +0,0 @@
1
- /*
2
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
- * Copyright (c) 2025 Hexastack.
4
- * Full terms: see LICENSE.md.
5
- */
6
-
7
- import { jest } from '@jest/globals';
8
- import { Command } from 'commander';
9
-
10
- const loadProjectConfig = jest.fn();
11
- const dockerCompose = jest.fn();
12
- const generateComposeFiles = jest.fn();
13
- const resolveComposeEnvFile = jest.fn();
14
- const resolveComposeFile = jest.fn();
15
- const bootstrapEnvFile = jest.fn();
16
- const checkDocker = jest.fn();
17
- const assertHexabotProject = jest.fn();
18
- const ensureDockerFolder = jest.fn();
19
- const parseServices = jest.fn();
20
- const runStart = jest.fn();
21
-
22
- jest.unstable_mockModule('../../core/config.js', () => ({
23
- loadProjectConfig,
24
- }));
25
-
26
- jest.unstable_mockModule('../../core/docker.js', () => ({
27
- dockerCompose,
28
- generateComposeFiles,
29
- resolveComposeEnvFile,
30
- resolveComposeFile,
31
- }));
32
-
33
- jest.unstable_mockModule('../../core/env.js', () => ({
34
- bootstrapEnvFile,
35
- }));
36
-
37
- jest.unstable_mockModule('../../core/prerequisites.js', () => ({
38
- checkDocker,
39
- }));
40
-
41
- jest.unstable_mockModule('../../core/project.js', () => ({
42
- assertHexabotProject,
43
- ensureDockerFolder,
44
- }));
45
-
46
- jest.unstable_mockModule('../../utils/services.js', () => ({
47
- parseServices,
48
- }));
49
-
50
- jest.unstable_mockModule('../start.js', () => ({
51
- runStart,
52
- }));
53
-
54
- let registerDockerCommand: (program: Command) => void;
55
-
56
- beforeAll(async () => {
57
- ({ registerDockerCommand } = await import('../docker.js'));
58
- });
59
-
60
- beforeEach(() => {
61
- jest.resetAllMocks();
62
- parseServices.mockImplementation((value: unknown) =>
63
- (typeof value === 'string' ? value : '')
64
- .split(',')
65
- .filter((entry) => entry),
66
- );
67
- resolveComposeFile.mockReturnValue('/project/docker/docker-compose.yml');
68
- resolveComposeEnvFile.mockReturnValue('/project/.env.docker');
69
- generateComposeFiles.mockReturnValue('-f docker-compose.yml');
70
- loadProjectConfig.mockReturnValue({
71
- docker: {
72
- composeFile: 'docker/docker-compose.yml',
73
- defaultServices: ['api'],
74
- },
75
- env: {
76
- docker: '.env.docker',
77
- dockerExample: '.env.docker.example',
78
- },
79
- });
80
- });
81
-
82
- const createProgram = () => {
83
- const program = new Command();
84
- registerDockerCommand(program);
85
-
86
- return program;
87
- };
88
-
89
- describe('registerDockerCommand', () => {
90
- it('runs docker compose up with extra flags and services', async () => {
91
- const program = createProgram();
92
- await program.parseAsync([
93
- 'node',
94
- 'test',
95
- 'docker',
96
- 'up',
97
- '--services',
98
- 'api,postgres',
99
- '--build',
100
- '--detach',
101
- ]);
102
-
103
- expect(bootstrapEnvFile).toHaveBeenCalled();
104
- expect(generateComposeFiles).toHaveBeenCalledWith(
105
- '/project/docker/docker-compose.yml',
106
- ['api', 'postgres'],
107
- 'dev',
108
- );
109
- expect(resolveComposeEnvFile).toHaveBeenCalledWith(
110
- expect.any(String),
111
- '.env.docker',
112
- );
113
- expect(dockerCompose).toHaveBeenCalledWith(
114
- expect.stringContaining('up --build -d'),
115
- { envFile: '/project/.env.docker' },
116
- );
117
- });
118
-
119
- it('runs docker compose down with optional volume removal', async () => {
120
- const program = createProgram();
121
- await program.parseAsync(['node', 'test', 'docker', 'down', '--volumes']);
122
-
123
- expect(dockerCompose).toHaveBeenCalledWith(
124
- expect.stringContaining('down -v'),
125
- { envFile: '/project/.env.docker' },
126
- );
127
- expect(bootstrapEnvFile).not.toHaveBeenCalled();
128
- });
129
-
130
- it('tails docker logs with filters', async () => {
131
- const program = createProgram();
132
- await program.parseAsync([
133
- 'node',
134
- 'test',
135
- 'docker',
136
- 'logs',
137
- 'api',
138
- '--follow',
139
- '--since',
140
- '1h',
141
- ]);
142
-
143
- expect(dockerCompose).toHaveBeenCalledWith(
144
- expect.stringContaining('logs -f --since 1h api'),
145
- { envFile: '/project/.env.docker' },
146
- );
147
- });
148
-
149
- it('lists running services with docker ps', async () => {
150
- const program = createProgram();
151
- await program.parseAsync(['node', 'test', 'docker', 'ps']);
152
-
153
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('ps'), {
154
- envFile: '/project/.env.docker',
155
- });
156
- });
157
-
158
- it('delegates to start command for docker start', async () => {
159
- const program = createProgram();
160
- await program.parseAsync([
161
- 'node',
162
- 'test',
163
- 'docker',
164
- 'start',
165
- '--services',
166
- 'api',
167
- '--build',
168
- '--detach',
169
- '--env-bootstrap',
170
- ]);
171
-
172
- expect(runStart).toHaveBeenCalledWith({
173
- docker: true,
174
- services: 'api',
175
- build: true,
176
- detach: true,
177
- envBootstrap: true,
178
- });
179
- });
180
- });
@@ -1,199 +0,0 @@
1
- /*
2
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
- * Copyright (c) 2025 Hexastack.
4
- * Full terms: see LICENSE.md.
5
- */
6
-
7
- import * as path from 'path';
8
-
9
- import { Command } from 'commander';
10
-
11
- import { loadProjectConfig } from '../core/config.js';
12
- import {
13
- dockerCompose,
14
- generateComposeFiles,
15
- resolveComposeEnvFile,
16
- resolveComposeFile,
17
- } from '../core/docker.js';
18
- import { bootstrapEnvFile } from '../core/env.js';
19
- import { checkDocker } from '../core/prerequisites.js';
20
- import { assertHexabotProject, ensureDockerFolder } from '../core/project.js';
21
- import { parseServices } from '../utils/services.js';
22
-
23
- import { runStart } from './start.js';
24
-
25
- export const registerDockerCommand = (program: Command) => {
26
- const dockerCommand = program.command('docker').description('Docker helpers');
27
-
28
- dockerCommand
29
- .command('up')
30
- .description('Start Docker services')
31
- .option('--services <list>', 'Comma-separated services/profiles')
32
- .option('-d, --detach', 'Run containers in the background')
33
- .option('--build', 'Build images before starting')
34
- .action(
35
- (options: { services?: string; detach?: boolean; build?: boolean }) =>
36
- runDockerCommand('up', options),
37
- );
38
-
39
- dockerCommand
40
- .command('down')
41
- .description('Stop Docker services')
42
- .option('--services <list>', 'Comma-separated services/profiles')
43
- .option('--volumes', 'Remove volumes')
44
- .action((options: { services?: string; volumes?: boolean }) =>
45
- runDockerCommand('down', options),
46
- );
47
-
48
- dockerCommand
49
- .command('logs [service]')
50
- .description('View Docker logs')
51
- .option('-f, --follow', 'Follow logs')
52
- .option('--since <time>', 'Only show logs since time (e.g. 1h)')
53
- .action(
54
- (
55
- service: string | undefined,
56
- options: { follow?: boolean; since?: string },
57
- ) => runDockerLogs(service, options),
58
- );
59
-
60
- dockerCommand
61
- .command('ps')
62
- .description('List running services')
63
- .action(() => runDockerPs());
64
-
65
- dockerCommand
66
- .command('start')
67
- .description('Start Docker services in production mode')
68
- .option('--services <list>', 'Comma-separated services/profiles')
69
- .option('-d, --detach', 'Run containers in the background')
70
- .option('--build', 'Build images before starting')
71
- .option('--env-bootstrap', 'Generate env files from *.example if missing')
72
- .action(
73
- async (options: {
74
- services?: string;
75
- detach?: boolean;
76
- build?: boolean;
77
- envBootstrap?: boolean;
78
- }) => {
79
- await runStart({
80
- docker: true,
81
- services: options.services,
82
- detach: options.detach,
83
- build: options.build,
84
- envBootstrap: options.envBootstrap,
85
- });
86
- },
87
- );
88
- };
89
-
90
- const runDockerCommand = (
91
- lifecycle: 'up' | 'down',
92
- options: {
93
- services?: string;
94
- detach?: boolean;
95
- build?: boolean;
96
- volumes?: boolean;
97
- },
98
- ) => {
99
- const projectRoot = path.resolve(process.cwd());
100
- assertHexabotProject(projectRoot);
101
- checkDocker({ silent: true });
102
- const config = loadProjectConfig(projectRoot);
103
- ensureDockerFolder(projectRoot);
104
- const services = resolveServices(options.services, config);
105
- const composeFile = resolveComposeFile(
106
- projectRoot,
107
- config.docker.composeFile,
108
- );
109
- const composeArgs = generateComposeFiles(
110
- composeFile,
111
- services,
112
- lifecycle === 'up' ? 'dev' : undefined,
113
- );
114
-
115
- if (lifecycle === 'up') {
116
- bootstrapEnvFile(projectRoot, config.env.dockerExample, config.env.docker, {
117
- quiet: true,
118
- });
119
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
120
- const commandArgs = ['up'];
121
- if (options.build) {
122
- commandArgs.push('--build');
123
- }
124
- if (options.detach) {
125
- commandArgs.push('-d');
126
- }
127
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
128
- envFile,
129
- });
130
- } else {
131
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
132
- const commandArgs = ['down'];
133
- if (options.volumes) {
134
- commandArgs.push('-v');
135
- }
136
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
137
- envFile,
138
- });
139
- }
140
- };
141
- const runDockerLogs = (
142
- service: string | undefined,
143
- options: { follow?: boolean; since?: string },
144
- ) => {
145
- const projectRoot = path.resolve(process.cwd());
146
- assertHexabotProject(projectRoot);
147
- checkDocker({ silent: true });
148
- const config = loadProjectConfig(projectRoot);
149
- ensureDockerFolder(projectRoot);
150
- const composeFile = resolveComposeFile(
151
- projectRoot,
152
- config.docker.composeFile,
153
- );
154
- const composeArgs = generateComposeFiles(
155
- composeFile,
156
- config.docker.defaultServices,
157
- 'dev',
158
- );
159
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
160
- const args = ['logs'];
161
- if (options.follow) {
162
- args.push('-f');
163
- }
164
- if (options.since) {
165
- args.push(`--since ${options.since}`);
166
- }
167
- if (service) {
168
- args.push(service);
169
- }
170
-
171
- dockerCompose(`${composeArgs} ${args.join(' ')}`.trim(), { envFile });
172
- };
173
- const runDockerPs = () => {
174
- const projectRoot = path.resolve(process.cwd());
175
- assertHexabotProject(projectRoot);
176
- checkDocker({ silent: true });
177
- const config = loadProjectConfig(projectRoot);
178
- ensureDockerFolder(projectRoot);
179
- const composeFile = resolveComposeFile(
180
- projectRoot,
181
- config.docker.composeFile,
182
- );
183
- const composeArgs = generateComposeFiles(
184
- composeFile,
185
- config.docker.defaultServices,
186
- 'dev',
187
- );
188
- const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
189
-
190
- dockerCompose(`${composeArgs} ps`, { envFile });
191
- };
192
- const resolveServices = (
193
- servicesInput: string | undefined,
194
- config: ReturnType<typeof loadProjectConfig>,
195
- ) => {
196
- const provided = parseServices(servicesInput || '');
197
-
198
- return provided.length ? provided : config.docker.defaultServices;
199
- };