atlas-hq 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# atlas-hq
+
+CLI launcher for [Atlas HQ](https://github.com/nord-initiatives/atlas_hq) — task management for AI agent teams.
+
+## Quick Start
+
+```bash
+npx atlas-hq start
+```
+
+That's it. Atlas HQ will be running at [http://localhost:3500](http://localhost:3500).
+
+## Requirements
+
+- [Docker Desktop](https://docs.docker.com/get-docker/) (with Docker Compose V2)
+- Node.js ≥ 18
+
+## Commands
+
+| Command           | Description                          |
+| ----------------- | ------------------------------------ |
+| `atlas-hq start`  | Pull images and start the stack      |
+| `atlas-hq stop`   | Stop the stack                       |
+| `atlas-hq status` | Show running container status        |
+| `atlas-hq open`   | Open the UI in your browser          |
+| `atlas-hq help`   | Show help                            |
+
+## Options
+
+| Flag              | Description                          | Default |
+| ----------------- | ------------------------------------ | ------- |
+| `--port-api`      | Host port for the API                | 3501    |
+| `--port-ui`       | Host port for the UI                 | 3500    |
+
+Environment variables `ATLAS_HQ_API_PORT` and `ATLAS_HQ_UI_PORT` also work.
+
+## Examples
+
+```bash
+# Start with custom ports
+npx atlas-hq start --port-ui 8080 --port-api 8081
+
+# Check status
+npx atlas-hq status
+
+# Stop
+npx atlas-hq stop
+```
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../lib/index.mjs';
+
+run(process.argv.slice(2));

package/docker-compose.yml

@@ -0,0 +1,85 @@
+###############################################################################
+# docker-compose.yml — Atlas HQ full-stack one-command local install
+#
+# Spins up:
+#   atlas-hq-api   Atlas HQ API      → http://localhost:3501
+#   atlas-hq-ui    Atlas HQ UI       → http://localhost:3500
+#
+# Named volume:
+#   atlas-hq-data  SQLite database persistence (/data inside the API container)
+#
+# ── Quick start ───────────────────────────────────────────────────────────────
+#   docker compose up          # build images and start everything (foreground)
+#   docker compose up -d       # same, detached
+#   docker compose down        # stop and remove containers (data volume kept)
+#   docker compose down -v     # ⚠️  also removes the data volume (wipes DB)
+#
+# ── Local overrides ───────────────────────────────────────────────────────────
+#   Copy docker-compose.override.yml.example to docker-compose.override.yml
+#   and edit it. Docker Compose merges it automatically — no extra flags needed.
+#
+# ── Environment variables ─────────────────────────────────────────────────────
+#   ATLAS_HQ_API_PORT            Host port for the API     (default: 3501)
+#   ATLAS_HQ_UI_PORT             Host port for the UI      (default: 3500)
+#   NEXT_PUBLIC_API_URL          API URL baked into the UI build
+#                                (default: http://localhost:3501)
+###############################################################################
+
+name: atlas-hq
+
+# ── Named volume for SQLite persistence ───────────────────────────────────────
+volumes:
+  atlas-hq-data:
+    driver: local
+
+# ── Services ──────────────────────────────────────────────────────────────────
+services:
+
+  # ── API ─────────────────────────────────────────────────────────────────────
+  atlas-hq-api:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile.api
+    image: atlas-hq-api:local
+    container_name: atlas-hq-api
+    restart: unless-stopped
+    ports:
+      - "${ATLAS_HQ_API_PORT:-3501}:3501"
+    volumes:
+      - atlas-hq-data:/data
+    environment:
+      NODE_ENV: production
+      PORT: "3501"
+      ATLAS_HQ_DB_PATH: /data/atlas.db
+      ATLAS_HQ_DATA_DIR: /data
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3501/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 15s
+
+  # ── UI ──────────────────────────────────────────────────────────────────────
+  atlas-hq-ui:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile.ui
+      args:
+        NEXT_PUBLIC_API_URL: "${NEXT_PUBLIC_API_URL:-http://localhost:3501}"
+    image: atlas-hq-ui:local
+    container_name: atlas-hq-ui
+    restart: unless-stopped
+    ports:
+      - "${ATLAS_HQ_UI_PORT:-3500}:3500"
+    environment:
+      NODE_ENV: production
+      PORT: "3500"
+    depends_on:
+      atlas-hq-api:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3500"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 20s

package/lib/index.mjs

@@ -0,0 +1,211 @@
+import { execSync, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const COMPOSE_SOURCE = join(__dirname, '..', 'docker-compose.yml');
+
+// Data directory where we keep the compose file and any local config
+const DATA_DIR = join(homedir(), '.atlas-hq');
+
+const HELP = `
+atlas-hq — CLI launcher for Atlas HQ
+
+Usage:
+  atlas-hq <command> [options]
+
+Commands:
+  start     Pull images and start the Atlas HQ stack
+  stop      Stop the Atlas HQ stack
+  status    Show running container status
+  open      Open the Atlas HQ UI in a browser
+  help      Show this help message
+
+Options:
+  --port-api <port>   Host port for the API  (default: 3501, env: ATLAS_HQ_API_PORT)
+  --port-ui  <port>   Host port for the UI   (default: 3500, env: ATLAS_HQ_UI_PORT)
+
+Examples:
+  npx atlas-hq start
+  npx atlas-hq start --port-ui 8080
+  npx atlas-hq stop
+`.trim();
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function die(msg) {
+  console.error(`\x1b[31m✗\x1b[0m ${msg}`);
+  process.exit(1);
+}
+
+function info(msg) {
+  console.log(`\x1b[36mℹ\x1b[0m ${msg}`);
+}
+
+function success(msg) {
+  console.log(`\x1b[32m✓\x1b[0m ${msg}`);
+}
+
+function checkDocker() {
+  try {
+    execFileSync('docker', ['--version'], { stdio: 'pipe' });
+  } catch {
+    die(
+      'Docker is not installed or not in PATH.\n' +
+      '  Install Docker Desktop: https://docs.docker.com/get-docker/\n' +
+      '  Then run this command again.'
+    );
+  }
+
+  // Check Docker daemon is running
+  try {
+    execFileSync('docker', ['info'], { stdio: 'pipe' });
+  } catch {
+    die(
+      'Docker daemon is not running.\n' +
+      '  Start Docker Desktop and try again.'
+    );
+  }
+
+  // Check docker compose is available
+  try {
+    execFileSync('docker', ['compose', 'version'], { stdio: 'pipe' });
+  } catch {
+    die(
+      'Docker Compose (V2) is not available.\n' +
+      '  Update Docker Desktop or install the compose plugin:\n' +
+      '  https://docs.docker.com/compose/install/'
+    );
+  }
+}
+
+function ensureDataDir() {
+  if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR, { recursive: true });
+  }
+  // Copy compose file into data dir so Docker Compose has a stable project dir
+  const dest = join(DATA_DIR, 'docker-compose.yml');
+  writeFileSync(dest, readFileSync(COMPOSE_SOURCE));
+  return DATA_DIR;
+}
+
+function compose(args, opts = {}) {
+  const cwd = ensureDataDir();
+  const cmd = ['docker', 'compose', ...args].join(' ');
+  try {
+    execSync(cmd, { cwd, stdio: 'inherit', ...opts });
+  } catch (e) {
+    if (!opts.ignoreError) {
+      die(`Command failed: ${cmd}`);
+    }
+  }
+}
+
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--port-api' && argv[i + 1]) {
+      flags.apiPort = argv[++i];
+    } else if (argv[i] === '--port-ui' && argv[i + 1]) {
+      flags.uiPort = argv[++i];
+    }
+  }
+  return flags;
+}
+
+function setPortEnv(flags) {
+  if (flags.apiPort) process.env.ATLAS_HQ_API_PORT = flags.apiPort;
+  if (flags.uiPort) process.env.ATLAS_HQ_UI_PORT = flags.uiPort;
+}
+
+function getUiPort() {
+  return process.env.ATLAS_HQ_UI_PORT || '3500';
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  try {
+    if (platform === 'darwin') {
+      execFileSync('open', [url], { stdio: 'pipe' });
+    } else if (platform === 'win32') {
+      execFileSync('cmd', ['/c', 'start', url], { stdio: 'pipe' });
+    } else {
+      execFileSync('xdg-open', [url], { stdio: 'pipe' });
+    }
+  } catch {
+    info(`Could not open browser automatically. Visit: ${url}`);
+  }
+}
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+
+function cmdStart(flags) {
+  checkDocker();
+  setPortEnv(flags);
+  const uiPort = getUiPort();
+  const apiPort = process.env.ATLAS_HQ_API_PORT || '3501';
+
+  info('Pulling latest Atlas HQ images…');
+  compose(['pull']);
+
+  info('Starting Atlas HQ…');
+  compose(['up', '-d', '--remove-orphans']);
+
+  success(`Atlas HQ is starting!`);
+  console.log(`  UI:  http://localhost:${uiPort}`);
+  console.log(`  API: http://localhost:${apiPort}`);
+  console.log(`\n  Run \x1b[1matlas-hq open\x1b[0m to open the UI in your browser.`);
+}
+
+function cmdStop() {
+  checkDocker();
+  info('Stopping Atlas HQ…');
+  compose(['down']);
+  success('Atlas HQ stopped.');
+}
+
+function cmdStatus() {
+  checkDocker();
+  ensureDataDir();
+  compose(['ps'], { ignoreError: true });
+}
+
+function cmdOpen(flags) {
+  setPortEnv(flags);
+  const uiPort = getUiPort();
+  const url = `http://localhost:${uiPort}`;
+  info(`Opening ${url}…`);
+  openBrowser(url);
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+export function run(argv) {
+  const command = argv[0];
+  const flags = parseFlags(argv.slice(1));
+
+  switch (command) {
+    case 'start':
+      cmdStart(flags);
+      break;
+    case 'stop':
+      cmdStop();
+      break;
+    case 'status':
+      cmdStatus();
+      break;
+    case 'open':
+      cmdOpen(flags);
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(HELP);
+      break;
+    default:
+      die(`Unknown command: ${command}\n\nRun \x1b[1matlas-hq help\x1b[0m for usage.`);
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "atlas-hq",
+  "version": "0.1.0",
+  "description": "CLI launcher for Atlas HQ — task management for AI agent teams",
+  "license": "MIT",
+  "bin": {
+    "atlas-hq": "./bin/cli.mjs"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "docker-compose.yml",
+    "README.md"
+  ],
+  "keywords": [
+    "atlas-hq",
+    "task-management",
+    "ai-agents",
+    "docker",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nord-initiatives/atlas_hq"
+  }
+}