@calvin.magezi/agent-hq 0.3.0 → 0.6.4

package/README.md

@@ -2,76 +2,97 @@
 
 > Local-first AI agent hub — Claude, Gemini & Discord, all from one command.
 
-## Install
+## Quick Install
 
-### via bunx / npx (zero-install)
 ```bash
-bunx agent-hq
-# or
-npx agent-hq
+# Zero-install (auto-clones repo, installs Bun if needed)
+npx @calvin.magezi/agent-hq
+
+# Or with Bun (faster):
+bunx @calvin.magezi/agent-hq
 ```
 
-### via Homebrew
+This will:
+1. Install Bun if not present
+2. Clone the agent-hq repo to `~/agent-hq`
+3. Run `hq init` to set up everything
+
+## From Source
+
 ```bash
-brew tap calvinmagezi/agent-hq
-brew install hq
+git clone https://github.com/CalvinMagezi/agent-hq.git
+cd agent-hq
+bun install
+bun scripts/hq.ts init
 ```
 
-### Manual (inside the repo)
+## First-Time Setup
+
+After installation, run the guided walkthrough:
+
 ```bash
-hq install-cli   # symlinks scripts/hq.ts → ~/.local/bin/hq
+hq quickstart
 ```
 
-## First-time setup
+Or set up step by step:
 
 ```bash
-# Interactive (asks questions)
-hq init
+hq init                  # Full setup (vault, tools, services)
+hq env                   # Configure API keys interactively
+hq doctor                # Verify everything works
+```
 
-# Unattended — safe for agent/CI execution
-hq init --non-interactive
+### API Keys
 
-# Custom vault location
-hq init --vault /path/to/my/vault --non-interactive
-```
+You need at least one of these to use AI chat:
+
+| Key | Where to get it | Required? |
+|-----|-----------------|-----------|
+| `OPENROUTER_API_KEY` | [openrouter.ai/keys](https://openrouter.ai/keys) | Yes (or Gemini) |
+| `GEMINI_API_KEY` | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | Optional |
+| `DISCORD_BOT_TOKEN` | [discord.com/developers](https://discord.com/developers/applications) | Optional |
+
+Run `hq env` to set these interactively.
 
-## Commands
+## Essential Commands
 
 | Command | Description |
 |---------|-------------|
-| `hq` | Start interactive chat |
-| `hq init` | Full first-time setup |
-| `hq setup` | Scaffold vault only |
-| `hq status` | Service status |
-| `hq start [agent\|relay\|all]` | Start services |
-| `hq stop [agent\|relay\|all]` | Stop services |
-| `hq restart` | Restart everything |
-| `hq daemon start\|stop\|logs` | Background daemon |
-| `hq logs [target] [N]` | View logs |
-| `hq follow` | Live-tail logs |
+| `hq` | Start chatting (default) |
+| `hq quickstart` | Guided first-run walkthrough |
+| `hq doctor` | Diagnose common issues |
+| `hq env` | Set up API keys |
+| `hq status` | Check what's running |
+| `hq start all` | Start all services |
+| `hq stop all` | Stop all services |
+| `hq pwa` | Open the web dashboard |
+| `hq vault open` | Open vault in Obsidian |
 | `hq health` | Full health check |
-| `hq ps` | All managed processes |
-| `hq install` | Install launchd daemons |
-| `hq coo status` | COO orchestrator status |
+| `hq logs [target]` | View logs |
+| `hq help` | Essential commands |
+| `hq help --all` | All commands |
+| `hq help --agent` | Quick reference for AI agents |
 
-## Agent-installable
+## For AI Agents
 
-This CLI is designed to be fully installable by an AI agent:
+The CLI is fully automatable:
 
 ```bash
-# Prerequisites: bun, git
-bunx agent-hq init --non-interactive \
-  --vault ~/.agent-hq-vault
+OPENROUTER_API_KEY=sk-or-... \
+  npx @calvin.magezi/agent-hq init --non-interactive
 ```
 
-The init command will:
-1. Check prerequisites (bun, git)
-2. Install dependencies
-3. Scaffold the vault
-4. Create `.env.local` templates
-5. Install macOS launchd daemons
-6. Add `hq` to your PATH
+Run `hq help --agent` for the recommended command sequence.
+
+## What's Included
+
+- **Vault**: An Obsidian-compatible folder of markdown files — your AI's knowledge base
+- **HQ Agent**: Background worker that processes AI jobs
+- **Discord Relay**: Multi-bot system for chatting via Discord
+- **Web Dashboard**: PWA on localhost:4747 for monitoring
+- **Terminal Chat**: `hq` starts an interactive REPL
+- **Daemon**: Background workflows (memory consolidation, web digests, etc.)
 
 ## License
 
-MIT © Calvin Magezi
+MIT

package/bin/hq

@@ -1,26 +1,68 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 /**
  * agent-hq entry point
  *
- * When installed via `bunx agent-hq` or `npx agent-hq`:
- *   - If run from inside the monorepo, delegates to scripts/hq.ts
- *   - Otherwise, bootstraps the installation with `hq init`
+ * When installed via `npx @calvin.magezi/agent-hq` or `bunx @calvin.magezi/agent-hq`:
+ *   - If run from inside the monorepo, delegates to scripts/hq.ts via Bun
+ *   - Otherwise, bootstraps the installation (clone + hq init)
  *
- * Install globally:  bunx agent-hq install-cli
- * Homebrew:          brew install calvinmagezi/agent-hq/hq
+ * Works with Node.js (no Bun required) — auto-installs Bun if missing.
  */
 
-import * as fs from "fs";
-import * as path from "path";
-import { spawnSync } from "child_process";
+const fs = require("fs");
+const path = require("path");
+const { spawnSync, execSync } = require("child_process");
 
-// ── Locate the monorepo root ──────────────────────────────────────────────────
+// ── Helpers ─────────────────────────────────────────────────────────────────
 
-function findRepoRoot(start: string): string | null {
+function hasBun() {
+  try {
+    const r = spawnSync("bun", ["--version"], { stdio: "pipe" });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function installBun() {
+  console.log("\n  Bun is required but not installed. Installing Bun...\n");
+  const platform = process.platform;
+
+  if (platform === "win32") {
+    console.log("  Run this in PowerShell:");
+    console.log("    irm bun.sh/install.ps1 | iex\n");
+    console.log("  Then re-run: npx @calvin.magezi/agent-hq");
+    process.exit(1);
+  }
+
+  // macOS / Linux
+  const result = spawnSync("bash", ["-c", "curl -fsSL https://bun.sh/install | bash"], {
+    stdio: "inherit",
+  });
+
+  if (result.status !== 0) {
+    console.error("\n  Bun installation failed. Install manually: https://bun.sh\n");
+    process.exit(1);
+  }
+
+  // Source the new PATH (Bun installs to ~/.bun/bin)
+  const bunBin = path.join(process.env.HOME || "~", ".bun", "bin");
+  process.env.PATH = bunBin + ":" + process.env.PATH;
+
+  if (!hasBun()) {
+    console.log("\n  Bun installed but not found on PATH.");
+    console.log("  Restart your terminal, then re-run: npx @calvin.magezi/agent-hq\n");
+    process.exit(1);
+  }
+
+  console.log("\n  Bun installed successfully.\n");
+}
+
+// ── Locate the monorepo root ────────────────────────────────────────────────
+
+function findRepoRoot(start) {
   let dir = start;
   for (let i = 0; i < 8; i++) {
     const pkg = path.join(dir, "package.json");
-    const apps = path.join(dir, "apps/agent");
+    const apps = path.join(dir, "apps", "agent");
     if (fs.existsSync(pkg) && fs.existsSync(apps)) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) return null;
@@ -29,66 +71,78 @@ function findRepoRoot(start: string): string | null {
   return null;
 }
 
-// When installed via npm/bun globally, this file lives at:
-//   node_modules/.bin/hq  →  node_modules/agent-hq/bin/hq.ts
-// So walk up from __dirname to find the repo, or fall back to CWD.
-const repoFromPackage = findRepoRoot(path.resolve(import.meta.dir, "../../.."));
+const repoFromPackage = findRepoRoot(path.resolve(__dirname, "..", "..", ".."));
 const repoFromCwd = findRepoRoot(process.cwd());
-const REPO_ROOT = repoFromPackage ?? repoFromCwd;
+const REPO_ROOT = repoFromPackage || repoFromCwd;
 
-// ── Delegate or bootstrap ─────────────────────────────────────────────────────
+// ── Delegate or bootstrap ───────────────────────────────────────────────────
 
 if (REPO_ROOT) {
-  // We're inside (or near) the monorepo — exec the full CLI
-  const fullCli = path.join(REPO_ROOT, "scripts/hq.ts");
+  // Inside (or near) the monorepo — ensure Bun, then delegate to full CLI
+  if (!hasBun()) installBun();
+
+  const fullCli = path.join(REPO_ROOT, "scripts", "hq.ts");
   if (fs.existsSync(fullCli)) {
-    const result = spawnSync(process.execPath, [fullCli, ...process.argv.slice(2)], {
+    const result = spawnSync("bun", [fullCli, ...process.argv.slice(2)], {
       stdio: "inherit",
       env: process.env,
     });
-    process.exit(result.status ?? 0);
+    process.exit(result.status || 0);
   }
 }
 
-// ── Not in repo — run init to bootstrap ──────────────────────────────────────
+// ── Not in repo — run init to bootstrap ─────────────────────────────────────
 
 console.log(`
-  ┌─────────────────────────────────────────────────────┐
-  │  agent-hq — first run                               │
-  │                                                     │
-  │  No agent-hq repository found near this location.  │
-  │  Let's set everything up.                           │
-  └─────────────────────────────────────────────────────┘
+  +-------------------------------------------------+
+  |  agent-hq -- first run                          |
+  |                                                 |
+  |  No agent-hq repository found.                  |
+  |  Let's set everything up.                       |
+  +-------------------------------------------------+
 `);
 
+// Ensure Bun is available before cloning
+if (!hasBun()) installBun();
+
 const isNonInteractive =
   process.argv.includes("--non-interactive") ||
   process.argv.includes("-y") ||
   !process.stdout.isTTY;
 
 const installDir = path.join(
-  process.env.AGENT_HQ_DIR ?? (process.env.HOME ?? "~"),
+  process.env.AGENT_HQ_DIR || process.env.HOME || "~",
   "agent-hq"
 );
 
-console.log(`Cloning agent-hq to: ${installDir}`);
-const clone = spawnSync("git", [
-  "clone", "https://github.com/CalvinMagezi/agent-hq.git", installDir
-], { stdio: "inherit" });
+if (fs.existsSync(path.join(installDir, "package.json"))) {
+  console.log(`  Found existing repo at: ${installDir}`);
+  console.log(`  Running: cd ${installDir} && bun scripts/hq.ts init\n`);
+} else {
+  console.log(`  Cloning agent-hq to: ${installDir}\n`);
+  const clone = spawnSync("git", [
+    "clone", "https://github.com/CalvinMagezi/agent-hq.git", installDir
+  ], { stdio: "inherit" });
 
-if (clone.status !== 0) {
-  console.error("\nClone failed. Check your internet connection.");
-  process.exit(1);
+  if (clone.status !== 0) {
+    console.error("\n  Clone failed. Check your internet connection and that git is installed.");
+    process.exit(1);
+  }
 }
 
-const installArgs = [
-  path.join(installDir, "scripts/hq.ts"),
+const initArgs = isNonInteractive ? ["--non-interactive"] : [];
+const passedArgs = process.argv.slice(2).filter(a =>
+  a.startsWith("--vault") || a.startsWith("--repo-url") ||
+  a === "--non-interactive" || a === "-y" || a === "--reset"
+);
+
+const init = spawnSync("bun", [
+  path.join(installDir, "scripts", "hq.ts"),
   "init",
-  ...(isNonInteractive ? ["--non-interactive"] : []),
-];
-const init = spawnSync(process.execPath, installArgs, {
+  ...new Set([...initArgs, ...passedArgs]),
+], {
   cwd: installDir,
   stdio: "inherit",
   env: process.env,
 });
-process.exit(init.status ?? 0);
+process.exit(init.status || 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calvin.magezi/agent-hq",
-  "version": "0.3.0",
+  "version": "0.6.4",
   "description": "HQ CLI — local-first AI agent hub for Claude, Gemini & Discord",
   "homepage": "https://github.com/CalvinMagezi/agent-hq",
   "repository": {
@@ -27,7 +27,7 @@
     "README.md"
   ],
   "engines": {
-    "bun": ">=1.1.0"
+    "node": ">=18.0.0"
   },
   "scripts": {
     "prepublishOnly": "echo 'Publishing hq CLI...'"

package/src/initState.ts

@@ -16,7 +16,8 @@ export type InitStep =
   | "models"
   | "env"
   | "services"
-  | "cli";
+  | "cli"
+  | "mcp";
 
 export interface InitState {
   version: string;