hivemind-context-governance 1.3.0

package/src/cli.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * HiveMind CLI — One-command initialization and management.
+ *
+ * Usage:
+ *   npx hivemind-context-governance          — Initialize (default)
+ *   npx hivemind-context-governance init      — Same as above
+ *   npx hivemind-context-governance status    — Show current brain state
+ *
+ * CRITICAL: NO console.log in library code. CLI is the ONLY
+ * place where console output is allowed (it IS the user interface).
+ */
+
+import { argv } from "node:process"
+import { initProject } from "./cli/init.js"
+import { createStateManager, loadConfig } from "./lib/persistence.js"
+import { listArchives } from "./lib/planning-fs.js"
+
+const COMMANDS = ["init", "status", "compact", "dashboard", "help"] as const
+type Command = (typeof COMMANDS)[number]
+
+function printHelp(): void {
+  const help = `
+HiveMind Context Governance — CLI
+
+Usage:
+  npx hivemind-context-governance [command] [options]
+
+Commands:
+  (default)     Initialize HiveMind in current project
+  init          Same as default — initialize project
+  status        Show current session and governance state
+  compact       Archive current session and reset
+  dashboard     Launch dashboard server
+  help          Show this help message
+
+Options:
+  --lang <en|vi>           Language (default: en)
+  --mode <permissive|assisted|strict>  Governance mode (default: assisted)
+  --expert <beginner|intermediate|advanced|expert>  Expert level (default: intermediate)
+  --style <explanatory|outline|skeptical|architecture|minimal>  Output style (default: explanatory)
+  --code-review            Require code review before accepting
+  --tdd                    Enforce test-driven development
+
+Examples:
+  npx hivemind-context-governance
+  npx hivemind-context-governance --mode strict --lang vi
+  npx hivemind-context-governance status
+`
+  // CLI is the user interface — console output is allowed here
+  // eslint-disable-next-line no-console
+  console.log(help)
+}
+
+async function showStatus(directory: string): Promise<void> {
+  const stateManager = createStateManager(directory)
+  const config = await loadConfig(directory)
+  const state = await stateManager.load()
+
+  if (!state) {
+    // eslint-disable-next-line no-console
+    console.log("No active session. Run 'npx hivemind-context-governance' first.")
+    return
+  }
+
+  const archives = await listArchives(directory)
+
+  const status = `
+┌─ HiveMind Status ────────────────────────┐
+│ Session: ${state.session.id.padEnd(30)}│
+│ Status:  ${state.session.governance_status.padEnd(30)}│
+│ Mode:    ${state.session.mode.padEnd(30)}│
+│ Govern:  ${config.governance_mode.padEnd(30)}│
+├─ Hierarchy ──────────────────────────────┤
+│ Trajectory: ${(state.hierarchy.trajectory || "(none)").padEnd(27)}│
+│ Tactic:     ${(state.hierarchy.tactic || "(none)").padEnd(27)}│
+│ Action:     ${(state.hierarchy.action || "(none)").padEnd(27)}│
+├─ Metrics ────────────────────────────────┤
+│ Turns:   ${String(state.metrics.turn_count).padEnd(30)}│
+│ Drift:   ${(state.metrics.drift_score + "/100").padEnd(30)}│
+│ Files:   ${String(state.metrics.files_touched.length).padEnd(30)}│
+│ Updates: ${String(state.metrics.context_updates).padEnd(30)}│
+│ Archive: ${(archives.length + " sessions").padEnd(30)}│
+└──────────────────────────────────────────┘
+`
+  // eslint-disable-next-line no-console
+  console.log(status)
+}
+
+async function main(): Promise<void> {
+  const args = argv.slice(2)
+
+  // Parse flags from all args
+  const flags: Record<string, string> = {}
+  const positionalArgs: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--") && args[i + 1] && !args[i + 1].startsWith("--")) {
+      flags[args[i].slice(2)] = args[i + 1]
+      i++
+    } else if (args[i].startsWith("--")) {
+      flags[args[i].slice(2)] = ""
+    } else {
+      positionalArgs.push(args[i])
+    }
+  }
+
+  // Default to "init" when no command given (npx hivemind-context-governance)
+  const command = (positionalArgs[0] ?? "init") as Command
+  const directory = process.cwd()
+
+  switch (command) {
+    case "init":
+      await initProject(directory, {
+        language: (flags["lang"] as "en" | "vi") ?? undefined,
+        governanceMode:
+          (flags["mode"] as "permissive" | "assisted" | "strict") ?? undefined,
+        expertLevel: (flags["expert"] as "beginner" | "intermediate" | "advanced" | "expert") ?? undefined,
+        outputStyle: (flags["style"] as "explanatory" | "outline" | "skeptical" | "architecture" | "minimal") ?? undefined,
+        requireCodeReview: "code-review" in flags,
+        enforceTdd: "tdd" in flags,
+      })
+      break
+
+    case "status":
+      await showStatus(directory)
+      break
+
+    case "compact":
+      // eslint-disable-next-line no-console
+      console.log("Manual compaction: use compact_session tool within OpenCode.")
+      break
+
+    case "dashboard": {
+      // Lazy-load dashboard to avoid pulling heavy deps on init/status
+      const { createDashboardServer } = await import("./dashboard/server.js")
+      const port = flags["port"] ? parseInt(flags["port"], 10) : undefined
+      const server = createDashboardServer(directory, { port })
+      try {
+        await server.start()
+        // eslint-disable-next-line no-console
+        console.log(`HiveMind Dashboard running at ${server.url}`)
+        // eslint-disable-next-line no-console
+        console.log(`\nPress Ctrl+C to stop`)
+
+        // Keep running until interrupted
+        await new Promise(() => {
+          process.on("SIGINT", async () => {
+            // eslint-disable-next-line no-console
+            console.log("\nShutting down...")
+            await server.stop()
+            process.exit(0)
+          })
+        })
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error("Failed to start dashboard:", err)
+        process.exit(1)
+      }
+      break
+    }
+
+    case "help":
+      printHelp()
+      break
+
+    default:
+      // eslint-disable-next-line no-console
+      console.log(`Unknown command: ${command}`)
+      printHelp()
+      break
+  }
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error("Error:", err)
+  process.exit(1)
+})

package/src/dashboard/i18n/en.ts

@@ -0,0 +1,43 @@
+/**
+ * English i18n strings — HiveMind Dashboard
+ */
+
+export const en = {
+  dashboard: {
+    title: "HiveMind Context Governance",
+    hierarchy: {
+      trajectory: "TRAJECTORY",
+      tactic: "TACTIC",
+      action: "ACTION",
+      status: {
+        pending: "PENDING",
+        active: "ACTIVE",
+        complete: "COMPLETE",
+        blocked: "BLOCKED",
+      },
+    },
+    agentLog: {
+      title: "AGENT ACTIONS",
+      empty: "No actions yet...",
+      timestamp: "Time",
+    },
+    metrics: {
+      title: "METRICS",
+      turns: "Turns",
+      drift: "Drift",
+      files: "Files",
+      status: "Status",
+    },
+    planning: {
+      title: "PLANNING FILES",
+      index: "index.md",
+      active: "active.md",
+      archive: "Archive",
+    },
+    governance: {
+      locked: "LOCKED",
+      open: "OPEN",
+      warning: "Declare intent to unlock",
+    },
+  },
+}

package/src/dashboard/i18n/index.ts

@@ -0,0 +1,20 @@
+/**
+ * i18n barrel — translation loader
+ */
+
+import { en } from "./en.js"
+import { vi } from "./vi.js"
+
+export type I18nStrings = typeof en
+export type SupportedLanguage = "en" | "vi"
+
+const translations: Record<SupportedLanguage, I18nStrings> = {
+  en,
+  vi,
+}
+
+export function getTranslations(lang: SupportedLanguage = "en"): I18nStrings {
+  return translations[lang] ?? translations.en
+}
+
+export { en, vi }

package/src/dashboard/i18n/vi.ts

@@ -0,0 +1,43 @@
+/**
+ * Vietnamese i18n strings — HiveMind Dashboard
+ */
+
+export const vi = {
+  dashboard: {
+    title: "HiveMind Quản Trị Ngữ Cảnh",
+    hierarchy: {
+      trajectory: "MỤC TIÊU",
+      tactic: "CHIẾN THUẬT",
+      action: "HÀNH ĐỘNG",
+      status: {
+        pending: "CHỜ",
+        active: "ĐANG LÀM",
+        complete: "XONG",
+        blocked: "BỊ CHẶN",
+      },
+    },
+    agentLog: {
+      title: "HÀNH ĐỘNG AGENT",
+      empty: "Chưa có hành động...",
+      timestamp: "Thời gian",
+    },
+    metrics: {
+      title: "SỐ LIỆU",
+      turns: "Lượt",
+      drift: "Độ lệch",
+      files: "File",
+      status: "Trạng thái",
+    },
+    planning: {
+      title: "FILE KẾ HOẠCH",
+      index: "index.md",
+      active: "active.md",
+      archive: "Lưu trữ",
+    },
+    governance: {
+      locked: "KHÓA",
+      open: "MỞ",
+      warning: "Khai báo ý định để mở khóa",
+    },
+  },
+}

package/src/dashboard/server.ts

@@ -0,0 +1,372 @@
+/**
+ * HiveMind Dashboard Backend
+ *
+ * Provides HTTP API for dashboard data:
+ * - GET /api/state — Current brain state
+ * - GET /api/active — Active session content
+ * - GET /api/index — Project trajectory
+ * - GET /api/archives — List of archived sessions
+ * - GET /api/archives/:id — Specific archive content
+ * - GET /api/metrics — Session metrics
+ *
+ * Serves static dashboard files in production.
+ */
+
+import { createServer, IncomingMessage, ServerResponse } from "http"
+import { readFile } from "fs/promises"
+import { existsSync } from "fs"
+import { join, basename } from "path"
+import { createStateManager } from "../lib/persistence.js"
+import { readActiveMd, listArchives, getPlanningPaths } from "../lib/planning-fs.js"
+import { createLogger } from "../lib/logging.js"
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+interface DashboardConfig {
+  projectRoot: string
+  port: number
+  host: string
+}
+
+interface ApiResponse {
+  success: boolean
+  data?: unknown
+  error?: string
+}
+
+// ─── CORS Headers ────────────────────────────────────────────────────
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+  "Content-Type": "application/json",
+}
+
+// ─── Response Helpers ────────────────────────────────────────────────
+
+function sendJson(res: ServerResponse, status: number, data: ApiResponse): void {
+  res.writeHead(status, CORS_HEADERS)
+  res.end(JSON.stringify(data))
+}
+
+function sendError(res: ServerResponse, status: number, message: string): void {
+  sendJson(res, status, { success: false, error: message })
+}
+
+// ─── Route Handlers ──────────────────────────────────────────────────
+
+async function handleGetState(
+  config: DashboardConfig,
+  res: ServerResponse
+): Promise<void> {
+  try {
+    const stateManager = createStateManager(config.projectRoot)
+    const state = await stateManager.load()
+
+    if (!state) {
+      sendJson(res, 200, { success: true, data: null })
+      return
+    }
+
+    sendJson(res, 200, { success: true, data: state })
+  } catch (err) {
+    sendError(res, 500, `Failed to load state: ${err}`)
+  }
+}
+
+async function handleGetActive(
+  config: DashboardConfig,
+  res: ServerResponse
+): Promise<void> {
+  try {
+    const activeMd = await readActiveMd(config.projectRoot)
+    sendJson(res, 200, { success: true, data: activeMd })
+  } catch (err) {
+    sendError(res, 500, `Failed to load active.md: ${err}`)
+  }
+}
+
+async function handleGetIndex(
+  config: DashboardConfig,
+  res: ServerResponse
+): Promise<void> {
+  try {
+    const paths = getPlanningPaths(config.projectRoot)
+    const content = await readFile(paths.indexPath, "utf-8")
+    sendJson(res, 200, { success: true, data: { content } })
+  } catch (err) {
+    sendError(res, 500, `Failed to load index.md: ${err}`)
+  }
+}
+
+async function handleGetArchives(
+  config: DashboardConfig,
+  res: ServerResponse
+): Promise<void> {
+  try {
+    const archives = await listArchives(config.projectRoot)
+    sendJson(res, 200, {
+      success: true,
+      data: archives.map((path) => ({
+        id: basename(path, ".md"),
+        path,
+      })),
+    })
+  } catch (err) {
+    sendError(res, 500, `Failed to list archives: ${err}`)
+  }
+}
+
+async function handleGetArchive(
+  config: DashboardConfig,
+  archiveId: string,
+  res: ServerResponse
+): Promise<void> {
+  try {
+    const paths = getPlanningPaths(config.projectRoot)
+    const archivePath = join(paths.archiveDir, `${archiveId}.md`)
+
+    // Security: ensure path is within archive directory
+    if (!archivePath.startsWith(paths.archiveDir)) {
+      sendError(res, 403, "Invalid archive ID")
+      return
+    }
+
+    if (!existsSync(archivePath)) {
+      sendError(res, 404, "Archive not found")
+      return
+    }
+
+    const content = await readFile(archivePath, "utf-8")
+    sendJson(res, 200, { success: true, data: { id: archiveId, content } })
+  } catch (err) {
+    sendError(res, 500, `Failed to load archive: ${err}`)
+  }
+}
+
+async function handleGetMetrics(
+  config: DashboardConfig,
+  res: ServerResponse
+): Promise<void> {
+  try {
+    const stateManager = createStateManager(config.projectRoot)
+    const state = await stateManager.load()
+    const archives = await listArchives(config.projectRoot)
+
+    if (!state) {
+      sendJson(res, 200, {
+        success: true,
+        data: {
+          hasSession: false,
+          totalArchives: archives.length,
+        },
+      })
+      return
+    }
+
+    sendJson(res, 200, {
+      success: true,
+      data: {
+        hasSession: true,
+        session: {
+          id: state.session.id,
+          mode: state.session.mode,
+          status: state.session.governance_status,
+          startTime: state.session.start_time,
+        },
+        hierarchy: state.hierarchy,
+        metrics: state.metrics,
+        totalArchives: archives.length,
+      },
+    })
+  } catch (err) {
+    sendError(res, 500, `Failed to load metrics: ${err}`)
+  }
+}
+
+// ─── Router ──────────────────────────────────────────────────────────
+
+function route(
+  config: DashboardConfig,
+  req: IncomingMessage,
+  res: ServerResponse
+): void {
+  const url = req.url ?? "/"
+  const method = req.method ?? "GET"
+
+  // CORS preflight
+  if (method === "OPTIONS") {
+    res.writeHead(204, CORS_HEADERS)
+    res.end()
+    return
+  }
+
+  // Only accept GET requests for API
+  if (method !== "GET") {
+    sendError(res, 405, "Method not allowed")
+    return
+  }
+
+  // API routes
+  if (url === "/api/state") {
+    handleGetState(config, res)
+    return
+  }
+
+  if (url === "/api/active") {
+    handleGetActive(config, res)
+    return
+  }
+
+  if (url === "/api/index") {
+    handleGetIndex(config, res)
+    return
+  }
+
+  if (url === "/api/archives") {
+    handleGetArchives(config, res)
+    return
+  }
+
+  if (url.startsWith("/api/archives/")) {
+    const archiveId = url.slice("/api/archives/".length)
+    handleGetArchive(config, archiveId, res)
+    return
+  }
+
+  if (url === "/api/metrics") {
+    handleGetMetrics(config, res)
+    return
+  }
+
+  if (url === "/api/health") {
+    sendJson(res, 200, { success: true, data: { status: "ok" } })
+    return
+  }
+
+  // 404 for unknown routes
+  sendError(res, 404, "Not found")
+}
+
+// ─── Server Factory ──────────────────────────────────────────────────
+
+export interface DashboardServer {
+  start(): Promise<void>
+  stop(): Promise<void>
+  url: string
+}
+
+export function createDashboardServer(
+  projectRoot: string,
+  options: { port?: number; host?: string } = {}
+): DashboardServer {
+  const config: DashboardConfig = {
+    projectRoot,
+    port: options.port ?? 0, // 0 = random available port
+    host: options.host ?? "127.0.0.1",
+  }
+
+  let server: ReturnType<typeof createServer> | null = null
+  let serverUrl = ""
+
+  return {
+    get url() {
+      return serverUrl
+    },
+
+    async start(): Promise<void> {
+      // Ensure planning directory exists
+      const paths = getPlanningPaths(projectRoot)
+      if (!existsSync(paths.planningDir)) {
+        throw new Error(
+          `HiveMind not initialized. Run 'hivemind init' first.`
+        )
+      }
+
+      // Setup logging
+      const log = await createLogger(
+        join(paths.planningDir, "logs"),
+        "dashboard"
+      )
+
+      return new Promise((resolve, reject) => {
+        server = createServer((req, res) => {
+          route(config, req, res)
+        })
+
+        server.listen(config.port, config.host, () => {
+          const address = server?.address()
+          if (address && typeof address === "object") {
+            serverUrl = `http://${config.host}:${address.port}`
+            log.info(`Dashboard server started at ${serverUrl}`)
+            resolve()
+          } else {
+            reject(new Error("Failed to get server address"))
+          }
+        })
+
+        server.on("error", (err) => {
+          reject(err)
+        })
+      })
+    },
+
+    async stop(): Promise<void> {
+      return new Promise((resolve) => {
+        if (server) {
+          server.close(() => resolve())
+          server = null
+        } else {
+          resolve()
+        }
+      })
+    },
+  }
+}
+
+// ─── CLI Entry Point ─────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const projectRoot = process.cwd()
+  const port = process.env.HIVEMIND_PORT
+    ? parseInt(process.env.HIVEMIND_PORT, 10)
+    : undefined
+
+  const server = createDashboardServer(projectRoot, { port })
+
+  try {
+    await server.start()
+    // eslint-disable-next-line no-console
+    console.log(`HiveMind Dashboard running at ${server.url}`)
+    // eslint-disable-next-line no-console
+    console.log(`API endpoints:`)
+    // eslint-disable-next-line no-console
+    console.log(`  ${server.url}/api/state`)
+    // eslint-disable-next-line no-console
+    console.log(`  ${server.url}/api/metrics`)
+    // eslint-disable-next-line no-console
+    console.log(`  ${server.url}/api/active`)
+    // eslint-disable-next-line no-console
+    console.log(`  ${server.url}/api/archives`)
+    // eslint-disable-next-line no-console
+    console.log(`\nPress Ctrl+C to stop`)
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error("Failed to start dashboard:", err)
+    process.exit(1)
+  }
+
+  // Graceful shutdown
+  process.on("SIGINT", async () => {
+    // eslint-disable-next-line no-console
+    console.log("\nShutting down...")
+    await server.stop()
+    process.exit(0)
+  })
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main()
+}