@bizone-ai/cli 0.1.0

package/README.md

@@ -0,0 +1,289 @@
+# Bizone CLI
+
+An assistant CLI for running the **Bizone orchestrator platform** locally using Docker.
+
+The CLI starts, configures, and stops the platform containers — a bundled
+`mysql` database, `resource-manager`, `orchestrator`, `state-store`, and `ui` —
+plus the one-shot resources initialization job (`bizone-resources`).
+Optionally runs `cloud-tools` as well if required.
+Works on **macOS** and **Windows**.
+
+---
+
+## Installation
+
+Requires **Node.js >= 18** and a running **Docker** engine.
+
+```bash
+cd cli
+npm install        # no runtime dependencies, but sets up the bin link
+npm link           # makes `bizone` available globally (optional)
+```
+
+Or run directly without linking:
+
+```bash
+node cli/bin/bizone.js <category> <command> [args]
+```
+
+All examples below assume the `bizone` command is on your PATH.
+
+---
+
+## Command structure
+
+```
+bizone <category> <command> [args] [--no-colors]
+```
+
+| Category        | Aliases     | Purpose                                         |
+|-----------------|-------------|-------------------------------------------------|
+| `start`         | —           | Start the platform                              |
+| `stop`          | —           | Stop the platform                               |
+| `configuration` | `config`,`c`| General CLI configuration                       |
+| `images`        | `img`       | Override container image URLs                   |
+| `environment`   | `env`       | Set environment variables per container         |
+| `resources`     | `res`, `r`  | Resources imported into the resource-manager    |
+| `database`      | `db`        | Manage the bundled MySQL database               |
+
+Global flags:
+
+- `--no-colors` — disable ANSI colors (also disabled when `NO_COLOR` is set or output is not a TTY)
+- `--help`, `-h` — show usage
+- `--version`, `-v` — show version
+
+---
+
+## Configuration file
+
+All settings are stored in a single JSON file in your home directory:
+
+- **macOS / Linux:** `~/.bizone/config.json`
+- **Windows:** `%USERPROFILE%\.bizone\config.json`
+
+Running container ids are tracked alongside it in `containers.json`.
+
+File shape:
+
+```json
+{
+  "config":    { "key": "value" },
+  "images":    { "type": "image-url" },
+  "env":       { "type": { "NAME": "value" } },
+  "resources": { "namespace": "path" }
+}
+```
+
+---
+
+## `configuration` — general settings
+
+```bash
+bizone config get                 # show current configuration (with defaults)
+bizone config set {key} {value}   # set a config key
+bizone config remove {key}        # reset a key back to its default
+```
+
+Stored at `$.config.{key}`.
+
+### Available keys
+
+| Key                     | Default        | Description                                                                                        |
+|-------------------------|----------------|----------------------------------------------------------------------------------------------------|
+| `forward_aws_env`       | `true`         | Forward `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` into the orchestrator container |
+| `network_name`          | `bizone-local` | Shared docker network all containers join                                                          |
+| `mysql_port`            | `33306`        | Host port for the bundled MySQL database                                                           |
+| `orchestrator_port`     | `8001`         | Host port for the orchestrator                                                                     |
+| `resource_manager_port` | `7070`         | Host port for the resource-manager                                                                 |
+| `state_store_port`      | `8088`         | Host port for the state-store                                                                      |
+| `state_store_enable`    | `true`         | Run `state-store` as part of the sequence                                                          |
+| `cloud_tools_port`      | `8086`         | Host port for cloud-tools                                                                          |
+| `cloud_tools_enable`    | `false`        | Run `cloud-tools` as part of the sequence                                                          |
+| `ui_port`               | `7006`         | Host port for the UI                                                                               |
+| `timeout_sec`           | `300`          | Readiness wait timeout per service (seconds)                                                       |
+
+Example:
+
+```bash
+bizone config set ui_port 9006
+bizone config set cloud_tools_enable true
+```
+
+---
+
+## `images` — override container images
+
+```bash
+bizone images get                 # list image URLs (override or default)
+bizone images set {type} {url}    # override an image
+bizone images remove {type}       # reset to default
+```
+
+Stored at `$.images.{type}`. Valid types:
+
+`mysql`, `orchestrator`, `state-store`, `resource-manager`, `cloud-tools`, `ui`, `resources`
+
+Example:
+
+```bash
+bizone images set state-store bizone-local/state-store:1.0.0
+```
+
+---
+
+## `environment` — per-container environment variables
+
+```bash
+bizone env get {type}                 # show env vars (secrets masked)
+bizone env set {type} {name} {value}  # set an env var
+bizone env remove {type} {name}       # remove an env var
+```
+
+Stored at `$.env.{type}.{name}`. `{type}` is one of the image types above.
+
+Each container type also has built-in **default** environment variables that
+are applied at run time unless you override the same key with `env set` (your
+value wins). `env get` shows the effective set, tagging each entry as
+`(default)` or `(override)`. For example, the MySQL client defaults
+(`storage.type=mysql`, `mysql.storage`, `mysql.storage.user`,
+`mysql.storage.password.secret`, `secret.mysql.password`) are applied to every
+container except `ui`, and the `mysql` container gets `MYSQL_ROOT_PASSWORD=root`.
+
+Secret values are masked on `get` (showing only the first 4 and last 4
+characters). Keys are treated as secrets when they match a predefined list
+(e.g. `AWS_SECRET_ACCESS_KEY`, `mysql.storage.password.secret`) or contain
+`password` / `secret` / `token` / `apikey`.
+
+Example:
+
+```bash
+bizone env set state-store db_url "mysql://user:pass@host:3306/db"
+bizone env get state-store
+#   db_url = mysq*******...****/db
+```
+
+These env vars are passed to the container at run time via `-e NAME=value`.
+
+---
+
+## `resources` — startup resource import
+
+Define resources to import into the resource-manager on startup, grouped by
+namespace.
+
+```bash
+bizone resources get                       # list configured sources
+bizone resources set {namespace} {path}    # set a file or folder source
+bizone resources remove {namespace}        # remove a namespace source
+```
+
+Stored at `$.resources.{namespace}`. `{path}` may be:
+
+- a **folder** — every `.json` file found recursively becomes one item
+- a **single file with an `items` array** — that array is used as the items
+- a **single file otherwise** — the whole file becomes the only item
+
+Relative paths resolve against the `.bizone` config directory.
+
+Example:
+
+```bash
+bizone resources set my_namespace ./my_namespace.json
+```
+
+### Import procedure
+
+On startup, for each namespace, the CLI sends:
+
+```
+POST http://localhost:{resource_manager_port}/admin/{namespace}/status
+
+{ "user": "bizone-cli", "message": "resource initialization", "items": [ ... ] }
+```
+
+---
+
+## `start` — start the platform
+
+```bash
+bizone start
+```
+
+Non-blocking: once everything is ready it prints **"Platform is running"** and
+returns control to the shell. Container ids are saved to
+`~/.bizone/containers.json` keyed by container name.
+
+### Startup sequence
+
+1. Create the shared docker network `bizone-local` (skipped if it exists).
+2. Start `mysql` **only if it is not already running** (an existing DB container
+   is reused), then wait until it accepts connections (`mysqladmin ping`).
+   The resource-manager is configured to store into this database, whose data
+   lives in the persistent docker volume `bizone-mysql-data`.
+3. Start `resource-manager`; wait until `GET /.system/status` returns `{ "status": "OK" }`.
+4. Run the `bizone-resources` initialization job (blocking).
+5. Import any configured `resources` namespaces (see above).
+6. Start `orchestrator`, `ui`, and any enabled optional services in parallel
+   (state-store / cloud-tools run only when `*_enable=true`).
+   - The orchestrator receives the AWS env vars when `forward_aws_env=true`.
+7. Wait for all of them to become ready:
+   - `ui` — `GET /actuator/health/readiness` returns `{"status":{"code":"UP"}}`
+   - all others — `GET /.system/status` returns `{ "status": "OK" }`
+   - each wait times out after `timeout_sec` seconds.
+
+Each container is started with:
+
+```
+docker run -d \
+  --name bizone-{type} -h bizone-{type} \
+  --network bizone-local --network-alias bizone-{type} \
+  -p {host_port}:{container_port} \
+  [-e NAME=value ...] \
+  {image}
+```
+
+---
+
+## `stop` — stop the platform
+
+```bash
+bizone stop
+```
+
+Reads `containers.json`, validates each id against `docker ps`, stops &
+removes the running containers, and updates the local file.
+
+The **database is intentionally left running** so its data persists and the
+next `bizone start` reuses it. To remove the database, use `bizone db destroy`.
+
+---
+
+## `database` — manage the MySQL database
+
+```bash
+bizone database destroy   # remove the DB container and its data volume
+```
+
+The bundled `mysql` container stores its data in the persistent docker volume
+`bizone-mysql-data`, so it survives `bizone stop` and container restarts.
+
+`destroy` permanently removes both the `bizone-mysql` container and the
+`bizone-mysql-data` volume (all data is lost). It refuses to run while any other
+platform container (`bizone-*`) is still running — run `bizone stop` first.
+
+---
+
+## Troubleshooting
+
+- **"Docker does not appear to be running"** — start Docker Desktop / the Docker daemon.
+- **Startup timed out** — increase `timeout_sec`, or check the container logs with `docker logs bizone-{type}`.
+- **Port already in use** — change the relevant `*_port` config value.
+- **Stale containers blocking a re-run** — `bizone start` force-removes existing
+  `bizone-*` containers by name before starting; you can also run `bizone stop`.
+- **`pull access denied` from AWS ECR** — when an image lives in an
+  `{account}.dkr.ecr.{region}.amazonaws.com` registry and the pull is
+  unauthorized, `bizone start` automatically authenticates by running
+  `aws ecr get-login-password --region {region}` and piping it into
+  `docker login --username AWS --password-stdin {registry}`, then retries.
+  This requires the **AWS CLI** to be installed and configured with valid
+  credentials for that account.

package/bin/bizone.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code || 0))
+  .catch((err) => {
+    console.error(err && err.message ? err.message : err);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@bizone-ai/cli",
+  "version": "0.1.0",
+  "description": "Assistant CLI for running the Bizone orchestrator platform locally with Docker",
+  "type": "module",
+  "bin": {
+    "bizone": "bin/bizone.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/bizone.js",
+    "test": "echo No tests"
+  },
+  "license": "UNLICENSED"
+}

package/src/cli.js

@@ -0,0 +1,103 @@
+// Argument parsing and command dispatch.
+
+import { initColors, color, log } from './colors.js';
+import { configuration } from './commands/configuration.js';
+import { images } from './commands/images.js';
+import { environment } from './commands/environment.js';
+import { resources } from './commands/resources.js';
+import { database } from './commands/database.js';
+import { start } from './commands/start.js';
+import { stop } from './commands/stop.js';
+import { CONFIG_PATH } from './config.js';
+
+const VERSION = '1.0.0';
+
+// category -> { aliases, handler }
+const CATEGORIES = {
+  configuration: { aliases: ['config', 'c'], handler: configuration },
+  images: { aliases: ['img'], handler: images },
+  environment: { aliases: ['env'], handler: environment },
+  resources: { aliases: ['res', 'r'], handler: resources },
+  database: { aliases: ['db'], handler: database },
+};
+
+function resolveCategory(name) {
+  if (CATEGORIES[name]) return CATEGORIES[name];
+  for (const cat of Object.values(CATEGORIES)) {
+    if (cat.aliases.includes(name)) return cat;
+  }
+  return null;
+}
+
+function printHelp() {
+  const b = color.bold;
+  const c = color.cyan;
+  log.plain(b('bizone') + ' - run the Bizone orchestrator platform locally with Docker');
+  log.plain('');
+  log.plain(b('Usage:') + ' bizone <category> <command> [args]  [--no-colors]');
+  log.plain('');
+  log.plain(b('Lifecycle:'));
+  log.plain(`  ${c('bizone start')}                     Start the platform (startup sequence)`);
+  log.plain(`  ${c('bizone stop')}                      Stop running platform containers`);
+  log.plain('');
+  log.plain(b('Configuration:') + color.dim('  (config, c)'));
+  log.plain(`  ${c('bizone config get')}                Show current configuration`);
+  log.plain(`  ${c('bizone config set {key} {value}')}  Set a config value`);
+  log.plain(`  ${c('bizone config remove {key}')}       Remove a config value`);
+  log.plain('');
+  log.plain(b('Images:') + color.dim('  (img)'));
+  log.plain(`  ${c('bizone images get')}                List image URLs (override or default)`);
+  log.plain(`  ${c('bizone images set {type} {url}')}   Override an image`);
+  log.plain(`  ${c('bizone images remove {type}')}      Reset image to default`);
+  log.plain('');
+  log.plain(b('Environment:') + color.dim('  (env)'));
+  log.plain(`  ${c('bizone env get {type}')}            Show env vars (secrets masked)`);
+  log.plain(`  ${c('bizone env set {type} {name} {value}')}  Set an env var`);
+  log.plain(`  ${c('bizone env remove {type} {name}')}  Remove an env var`);
+  log.plain('');
+  log.plain(b('Resources:') + color.dim('  (res, r)'));
+  log.plain(`  ${c('bizone resources get')}             List resource sources`);
+  log.plain(`  ${c('bizone resources set {namespace} {path}')}  Set a resource source`);
+  log.plain(`  ${c('bizone resources remove {namespace}')}  Remove a resource source`);
+  log.plain('');
+  log.plain(b('Database:') + color.dim('  (db)'));
+  log.plain(`  ${c('bizone database destroy')}          Remove the DB container and its data volume`);
+  log.plain('');
+  log.plain(b('Global flags:'));
+  log.plain(`  ${c('--no-colors')}   Disable ANSI colors`);
+  log.plain(`  ${c('--help, -h')}    Show this help`);
+  log.plain(`  ${c('--version, -v')} Show version`);
+  log.plain('');
+  log.plain(color.dim(`Config file: ${CONFIG_PATH}`));
+}
+
+export async function main(argv) {
+  // Extract global flags anywhere in argv.
+  const noColors = argv.includes('--no-colors');
+  initColors({ noColors });
+  const args = argv.filter((a) => a !== '--no-colors');
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    printHelp();
+    return 0;
+  }
+  if (args[0] === '--version' || args[0] === '-v' || args[0] === 'version') {
+    log.plain(VERSION);
+    return 0;
+  }
+
+  const [category, ...rest] = args;
+
+  // Lifecycle commands act as bare categories.
+  if (category === 'start') return await start();
+  if (category === 'stop') return stop();
+
+  const resolved = resolveCategory(category);
+  if (!resolved) {
+    log.err(`Unknown command: ${color.cyan(category)}`);
+    log.plain(`Run ${color.cyan('bizone --help')} for usage.`);
+    return 1;
+  }
+
+  return await resolved.handler(rest);
+}

package/src/colors.js

@@ -0,0 +1,46 @@
+// Minimal ANSI color helpers. Colors are disabled when `--no-colors` is passed
+// or when stdout is not a TTY / NO_COLOR env is set.
+
+let enabled = true;
+
+export function setColorsEnabled(value) {
+  enabled = value;
+}
+
+export function initColors({ noColors }) {
+  if (noColors) {
+    enabled = false;
+    return;
+  }
+  if (process.env.NO_COLOR) {
+    enabled = false;
+    return;
+  }
+  enabled = Boolean(process.stdout.isTTY);
+}
+
+function wrap(open, close) {
+  return (text) => (enabled ? `[${open}m${text}[${close}m` : String(text));
+}
+
+export const color = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  magenta: wrap(35, 39),
+  cyan: wrap(36, 39),
+  gray: wrap(90, 39),
+};
+
+// Common log helpers.
+export const log = {
+  info: (msg) => console.log(msg),
+  step: (msg) => console.log(`${color.cyan('•')} ${msg}`),
+  ok: (msg) => console.log(`${color.green('✓')} ${msg}`),
+  warn: (msg) => console.log(`${color.yellow('!')} ${msg}`),
+  err: (msg) => console.error(`${color.red('✗')} ${msg}`),
+  plain: (msg) => console.log(msg),
+};

package/src/commands/configuration.js

@@ -0,0 +1,69 @@
+// `bizone configuration|config|c get|set|remove`
+
+import { loadConfig, saveConfig, getConfigValue } from '../config.js';
+import { CONFIG_KEYS, DEFAULT_CONFIG } from '../defaults.js';
+import { color, log } from '../colors.js';
+
+function printKnownKeys() {
+  log.plain(color.bold('Known configuration keys (with defaults):'));
+  for (const k of CONFIG_KEYS) {
+    log.plain(`  ${color.cyan(k)} = ${color.dim(DEFAULT_CONFIG[k])}`);
+  }
+}
+
+export function configuration(args) {
+  const [sub, key, ...rest] = args;
+  const cfg = loadConfig();
+
+  switch (sub) {
+    case 'get': {
+      log.plain(color.bold('Configuration:'));
+      for (const k of CONFIG_KEYS) {
+        const isSet = Object.prototype.hasOwnProperty.call(cfg.config, k);
+        const val = getConfigValue(cfg, k);
+        const tag = isSet ? '' : color.dim(' (default)');
+        log.plain(`  ${color.cyan(k)} = ${val}${tag}`);
+      }
+      // Any non-standard custom keys the user added.
+      for (const k of Object.keys(cfg.config)) {
+        if (!CONFIG_KEYS.includes(k)) {
+          log.plain(`  ${color.cyan(k)} = ${cfg.config[k]}${color.yellow(' (custom)')}`);
+        }
+      }
+      return 0;
+    }
+    case 'set': {
+      if (!key || rest.length === 0) {
+        log.err('Usage: bizone config set {key} {value}');
+        printKnownKeys();
+        return 1;
+      }
+      const value = rest.join(' ');
+      if (!CONFIG_KEYS.includes(key)) {
+        log.warn(`"${key}" is not a known config key; storing it anyway.`);
+      }
+      cfg.config[key] = value;
+      saveConfig(cfg);
+      log.ok(`Set ${color.cyan(key)} = ${value}`);
+      return 0;
+    }
+    case 'remove': {
+      if (!key) {
+        log.err('Usage: bizone config remove {key}');
+        return 1;
+      }
+      if (Object.prototype.hasOwnProperty.call(cfg.config, key)) {
+        delete cfg.config[key];
+        saveConfig(cfg);
+        log.ok(`Removed ${color.cyan(key)}`);
+      } else {
+        log.warn(`Key ${color.cyan(key)} was not set.`);
+      }
+      return 0;
+    }
+    default:
+      log.err('Usage: bizone config <get|set|remove> ...');
+      printKnownKeys();
+      return 1;
+  }
+}

package/src/commands/database.js

@@ -0,0 +1,68 @@
+// `bizone database|db destroy` — remove the database container and its volume.
+// Only permitted when no other platform containers are running.
+
+import { loadContainers, saveContainers } from '../config.js';
+import { CONTAINERS } from '../defaults.js';
+import {
+  dockerAvailable,
+  runningContainerNames,
+  stopContainer,
+  removeVolume,
+} from '../docker.js';
+import { color, log } from '../colors.js';
+
+const mysql = CONTAINERS.mysql;
+
+export function database(args) {
+  const [sub] = args;
+  switch (sub) {
+    case 'destroy':
+      return destroy();
+    default:
+      log.err('Usage: bizone database destroy');
+      return 1;
+  }
+}
+
+function destroy() {
+  if (!dockerAvailable()) {
+    log.err('Docker does not appear to be running or installed.');
+    return 1;
+  }
+
+  // Refuse while any other platform container is still running.
+  const running = runningContainerNames();
+  const others = [...running].filter(
+    (n) => n.startsWith('bizone-') && n !== mysql.containerName,
+  );
+  if (others.length > 0) {
+    log.err(`Cannot destroy the database while platform containers are running: ${others.join(', ')}`);
+    log.plain(`Run ${color.cyan('bizone stop')} first, then ${color.cyan('bizone db destroy')}.`);
+    return 1;
+  }
+
+  log.warn(`This will permanently delete the database container and ALL its data (volume ${mysql.volume.name}).`);
+
+  // Stop + remove the container (no-op if already gone).
+  log.step(`Removing container ${mysql.containerName}...`);
+  stopContainer(mysql.containerName);
+
+  // Remove the data volume.
+  log.step(`Removing volume ${mysql.volume.name}...`);
+  if (removeVolume(mysql.volume.name)) {
+    log.ok(`Removed volume ${mysql.volume.name}`);
+  } else {
+    log.warn(`Volume ${mysql.volume.name} not found or already removed`);
+  }
+
+  // Drop from the local record.
+  const containers = loadContainers();
+  if (containers[mysql.containerName]) {
+    delete containers[mysql.containerName];
+    saveContainers(containers);
+  }
+
+  log.plain('');
+  log.plain(color.green(color.bold('✓ Database destroyed')));
+  return 0;
+}