stealthos-cli 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,44 @@
+# stealthos-cli
+
+Install and manage the [StealthOS](https://github.com/IgorKadu/stealthos) knowledge base in `~/.stealthos/`.
+
+```bash
+npm i -g stealthos-cli
+stealthos install
+stealthos status
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `stealthos install` | Copy the canonical `.ai/` tree into `~/.stealthos/` |
+| `stealthos status`  | Show install version, paths, tracked projects |
+| `stealthos version` | Print CLI version |
+| `stealthos help`    | Usage |
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--home <path>` | `~/.stealthos` | Target install dir |
+| `--source <path>` | auto-detect | Source `.ai/` tree (used for dev/CI) |
+| `--force` | off | Overwrite existing files |
+
+## Environment
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `STEALTHOS_HOME` | `~/.stealthos` | Same as `--home` |
+| `STEALTHOS_SOURCE` | auto-detect | Same as `--source` |
+| `STEALTHOS_DEBUG` | off | Set `=1` to print stack traces |
+
+## What gets installed
+
+`stealthos install` copies the canonical knowledge base (rules, workflows, server, hooks, blueprints, specs templates) into `~/.stealthos/`, **excluding** runtime outputs (`artifacts/`, `runtime/`, `snapshots/`, `context/`) and project-specific memory (those are initialized fresh per project).
+
+After install, set up your project with [`create-stealthos`](https://www.npmjs.com/package/create-stealthos).
+
+## License
+
+MIT — see root [LICENSE](../../LICENSE).

package/bin.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// stealthos — CLI entry point
+// Subcommands: install, status, version, help
+
+import { runCli } from "./src/cli.mjs";
+
+runCli(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`\n✖ stealthos failed: ${err.message}\n`);
+  if (process.env.STEALTHOS_DEBUG === "1") {
+    process.stderr.write(`${err.stack}\n`);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "stealthos-cli",
+  "version": "0.1.0-alpha.1",
+  "description": "StealthOS CLI — install/manage the StealthOS knowledge base in ~/.stealthos/. Subcommands: install, status, version.",
+  "type": "module",
+  "bin": {
+    "stealthos": "./bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "stealthos",
+    "mcp",
+    "ai",
+    "cli",
+    "claude-code"
+  ],
+  "author": "Igor Kadu (https://github.com/IgorKadu)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IgorKadu/stealthos.git",
+    "directory": "packages/stealthos-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/IgorKadu/stealthos/issues"
+  },
+  "homepage": "https://github.com/IgorKadu/stealthos/tree/main/packages/stealthos-cli#readme"
+}

package/src/cli.mjs

@@ -0,0 +1,79 @@
+// stealthos CLI router. Subcommand dispatcher.
+
+import { installCommand } from "./commands/install.mjs";
+import { statusCommand } from "./commands/status.mjs";
+
+const VERSION = "0.1.0-alpha.1";
+
+function usage() {
+  process.stdout.write(`
+stealthos v${VERSION}
+
+USAGE
+  stealthos <command> [options]
+
+COMMANDS
+  install     Install StealthOS knowledge base into ~/.stealthos/
+              Options:
+                --source <path>    Source .ai/ tree (default: auto-detect in monorepo)
+                --home <path>      Target home (default: ~/.stealthos)
+                --force            Overwrite existing files
+  status      Show ~/.stealthos/ install status (version, paths, project count)
+  version     Print stealthos CLI version
+  help        Show this message
+
+ENVIRONMENT
+  STEALTHOS_HOME          Override target home (default: ~/.stealthos)
+  STEALTHOS_SOURCE        Override source .ai/ path (default: auto-detect)
+  STEALTHOS_DEBUG=1       Print stack traces on errors
+
+EXAMPLES
+  stealthos install
+  stealthos install --home /opt/stealthos
+  stealthos status
+`);
+}
+
+export async function runCli(argv) {
+  const [cmd = "help", ...rest] = argv;
+  switch (cmd) {
+    case "install":
+      return installCommand(parseFlags(rest));
+    case "status":
+      return statusCommand(parseFlags(rest));
+    case "version":
+    case "-v":
+    case "--version":
+      process.stdout.write(`${VERSION}\n`);
+      return;
+    case "help":
+    case "-h":
+    case "--help":
+      usage();
+      return;
+    default:
+      process.stderr.write(`Unknown command: ${cmd}\n`);
+      usage();
+      process.exit(2);
+  }
+}
+
+function parseFlags(args) {
+  const out = { _positional: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        out[key] = next;
+        i++;
+      } else {
+        out[key] = true;
+      }
+    } else {
+      out._positional.push(a);
+    }
+  }
+  return out;
+}

package/src/commands/install.mjs

@@ -0,0 +1,136 @@
+// stealthos install — copies the canonical .ai/ tree into ~/.stealthos/
+// (or wherever --home / STEALTHOS_HOME points).
+// See ADR-0012 for the hybrid architecture.
+
+import { existsSync } from "node:fs";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveSource } from "../lib/resolve-source.mjs";
+import { copyTree } from "../lib/copy-tree.mjs";
+
+// Paths NOT to copy: runtime-generated outputs + project-specific history.
+// These get freshly initialized per project by the server.
+const DEFAULT_EXCLUDES = [
+  // Outputs
+  "artifacts",
+  "context",
+  "runtime",
+  "snapshots",
+  ".runtime",
+  // Project-specific memory (templates written below)
+  "memory/_detected-stack.json",
+  "memory/_summary.md",
+  "memory/decisions.md",
+  "memory/completed-tasks.md",
+  // Server runtime
+  "server/node_modules",
+  "server/.runtime",
+];
+
+// Memory templates (empty histories so the server can append to them)
+const MEMORY_TEMPLATES = {
+  "memory/decisions.md": `---
+version: 1.0.0
+updated: AUTO
+tier: conditional
+mutable: append_only
+triggers: arquitetura, decisão, adr
+---
+
+# Architecture Decision Records (ADRs)
+
+> Registro persistente de decisões arquiteturais. Cada ADR captura contexto, decisão, consequências e alternativas.
+
+## Entradas
+
+<!-- ADRs aparecem abaixo, mais recente primeiro -->
+`,
+  "memory/completed-tasks.md": `---
+version: 1.0.0
+updated: AUTO
+tier: conditional
+mutable: append_only
+---
+
+# Completed Tasks Log
+
+> Histórico append-only de tarefas concluídas com contexto suficiente para recuperar a memória do projeto.
+
+## Entradas
+
+<!-- Tarefas concluídas aparecem abaixo, mais recente primeiro -->
+`,
+};
+
+export async function installCommand(flags = {}) {
+  const home = flags.home ? String(flags.home) : (process.env.STEALTHOS_HOME || join(homedir(), ".stealthos"));
+  const source = resolveSource({ flagSource: flags.source });
+  const force = !!flags.force;
+
+  process.stdout.write(`\n╔══════════════════════════════════════════════╗\n`);
+  process.stdout.write(`║  stealthos install                             ║\n`);
+  process.stdout.write(`╚══════════════════════════════════════════════╝\n`);
+  process.stdout.write(`📂 Source: ${source}\n`);
+  process.stdout.write(`📦 Target: ${home}\n`);
+  process.stdout.write(`🔧 Force:  ${force ? "yes (overwrite)" : "no (skip existing)"}\n\n`);
+
+  if (existsSync(home) && !force) {
+    process.stdout.write(`⚠ ${home} já existe. Arquivos existentes serão preservados (use --force para sobrescrever).\n\n`);
+  }
+
+  await mkdir(home, { recursive: true });
+  await mkdir(join(home, "projects"), { recursive: true });
+
+  // Copy the canonical .ai/ tree
+  process.stdout.write(`📥 Copiando knowledge base...\n`);
+  const stats = await copyTree(source, home, {
+    excludes: DEFAULT_EXCLUDES,
+    force,
+  });
+
+  // Write empty memory templates if absent (or force)
+  let templatesWritten = 0;
+  for (const [rel, content] of Object.entries(MEMORY_TEMPLATES)) {
+    const dst = join(home, rel);
+    if (existsSync(dst) && !force) continue;
+    await mkdir(join(home, "memory"), { recursive: true });
+    const dated = content.replace(/AUTO/g, new Date().toISOString().slice(0, 10));
+    await writeFile(dst, dated, "utf8");
+    templatesWritten++;
+  }
+
+  // Write VERSION marker (records install timestamp + source manifest version)
+  let sourceVersion = "unknown";
+  try {
+    const m = JSON.parse(await readFile(join(source, "manifest.json"), "utf8"));
+    sourceVersion = m.version || "unknown";
+  } catch (_) {}
+  const versionMarker = {
+    installed_at: new Date().toISOString(),
+    installed_from: source,
+    source_version: sourceVersion,
+    cli_version: "0.1.0-alpha.1",
+  };
+  await writeFile(join(home, ".stealthos-version.json"), JSON.stringify(versionMarker, null, 2), "utf8");
+
+  process.stdout.write(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+  process.stdout.write(`✓ Instalação concluída\n`);
+  process.stdout.write(`  • Arquivos copiados:   ${stats.copied.length}\n`);
+  process.stdout.write(`  • Arquivos pulados:    ${stats.skipped.length} (já existiam, sem --force)\n`);
+  process.stdout.write(`  • Diretórios excluídos: ${stats.excluded.length} (outputs/state)\n`);
+  process.stdout.write(`  • Memory templates:    ${templatesWritten}\n`);
+  process.stdout.write(`  • Versão source:       ${sourceVersion}\n`);
+
+  // Check server/node_modules needs install
+  const serverPkgJson = join(home, "server", "package.json");
+  if (existsSync(serverPkgJson) && !existsSync(join(home, "server", "node_modules"))) {
+    process.stdout.write(`\n⚠ Próximo passo: instalar deps do server\n`);
+    process.stdout.write(`   cd "${join(home, "server")}" && npm install\n`);
+  }
+
+  process.stdout.write(`\nPara usar em modo hybrid:\n`);
+  process.stdout.write(`  export STEALTHOS_MODE=hybrid\n`);
+  process.stdout.write(`  export STEALTHOS_HOME="${home}"\n`);
+  process.stdout.write(`  node "${join(home, "server", "aios-server.mjs")}" --http\n`);
+}

package/src/commands/status.mjs

@@ -0,0 +1,66 @@
+// stealthos status — quick view of ~/.stealthos/ install state.
+
+import { existsSync } from "node:fs";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export async function statusCommand(flags = {}) {
+  const home = flags.home ? String(flags.home) : (process.env.STEALTHOS_HOME || join(homedir(), ".stealthos"));
+
+  process.stdout.write(`\n📦 StealthOS @ ${home}\n`);
+
+  if (!existsSync(home)) {
+    process.stdout.write(`  ✖ não instalado (rode 'stealthos install')\n`);
+    return;
+  }
+
+  // Version marker
+  const versionFile = join(home, ".stealthos-version.json");
+  if (existsSync(versionFile)) {
+    const v = JSON.parse(await readFile(versionFile, "utf8"));
+    process.stdout.write(`  • Instalado em:     ${v.installed_at}\n`);
+    process.stdout.write(`  • Source version:   ${v.source_version}\n`);
+    process.stdout.write(`  • CLI version:      ${v.cli_version}\n`);
+  } else {
+    process.stdout.write(`  ⚠ sem .stealthos-version.json (instalação manual ou parcial)\n`);
+  }
+
+  // Server presence
+  const serverFile = join(home, "server", "aios-server.mjs");
+  process.stdout.write(`  • Server present:   ${existsSync(serverFile) ? "yes" : "✖ NO"}\n`);
+  const nodeModules = join(home, "server", "node_modules");
+  process.stdout.write(`  • Server deps:      ${existsSync(nodeModules) ? "installed" : `⚠ missing (run: cd "${join(home, "server")}" && npm install)`}\n`);
+
+  // Knowledge base files
+  for (const f of ["INDEX.md", "CONTRACT.md", "ROUTER.md", "manifest.json"]) {
+    const p = join(home, f);
+    process.stdout.write(`  • ${f.padEnd(18)} ${existsSync(p) ? "✓" : "✖"}\n`);
+  }
+
+  // Workflows count
+  const wfDir = join(home, "workflows");
+  if (existsSync(wfDir)) {
+    const wfs = (await readdir(wfDir)).filter((n) => n.endsWith(".json") && !n.startsWith("_"));
+    process.stdout.write(`  • Workflows:        ${wfs.join(", ") || "(none)"}\n`);
+  }
+
+  // Projects count
+  const projDir = join(home, "projects");
+  if (existsSync(projDir)) {
+    const projects = (await readdir(projDir, { withFileTypes: true })).filter((d) => d.isDirectory());
+    process.stdout.write(`  • Projects tracked: ${projects.length}\n`);
+    for (const p of projects.slice(0, 5)) {
+      const sFile = join(projDir, p.name, "runtime", "state.json");
+      let name = "(no state)";
+      if (existsSync(sFile)) {
+        try {
+          const s = JSON.parse(await readFile(sFile, "utf8"));
+          name = s.identity?.project_name || "(no name)";
+        } catch (_) {}
+      }
+      process.stdout.write(`      - ${p.name}  → ${name}\n`);
+    }
+    if (projects.length > 5) process.stdout.write(`      ... +${projects.length - 5} more\n`);
+  }
+}

package/src/lib/copy-tree.mjs

@@ -0,0 +1,61 @@
+// Recursive tree copy with exclude patterns.
+// Pure node — no glob lib. Patterns are simple relative-path prefixes.
+
+import { readdir, mkdir, readFile, writeFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+// Normalize a path segment for matching (always forward slashes, lowercase first segment only)
+function normalizeRel(p) {
+  return p.split(sep).join("/");
+}
+
+function isExcluded(relPath, excludes) {
+  const norm = normalizeRel(relPath);
+  for (const ex of excludes) {
+    // Exact match OR prefix match (directory)
+    if (norm === ex) return true;
+    if (norm.startsWith(ex + "/")) return true;
+  }
+  return false;
+}
+
+export async function copyTree(srcRoot, dstRoot, {
+  excludes = [],
+  force = false,
+  log,
+} = {}) {
+  const stats = { copied: [], skipped: [], excluded: [] };
+  if (!existsSync(srcRoot)) {
+    throw new Error(`Source does not exist: ${srcRoot}`);
+  }
+
+  async function walk(srcDir, dstDir) {
+    await mkdir(dstDir, { recursive: true });
+    const entries = await readdir(srcDir, { withFileTypes: true });
+    for (const e of entries) {
+      const srcPath = join(srcDir, e.name);
+      const dstPath = join(dstDir, e.name);
+      const rel = relative(srcRoot, srcPath);
+      if (isExcluded(rel, excludes)) {
+        stats.excluded.push(rel);
+        if (log) log(`  - excluded: ${normalizeRel(rel)}`);
+        continue;
+      }
+      if (e.isDirectory()) {
+        await walk(srcPath, dstPath);
+      } else if (e.isFile()) {
+        if (existsSync(dstPath) && !force) {
+          stats.skipped.push(rel);
+          continue;
+        }
+        const buf = await readFile(srcPath);
+        await writeFile(dstPath, buf);
+        stats.copied.push(rel);
+      }
+    }
+  }
+
+  await walk(srcRoot, dstRoot);
+  return stats;
+}

package/src/lib/resolve-source.mjs

@@ -0,0 +1,43 @@
+// Locate the source .ai/ tree to install from.
+// Strategy:
+//   1. Explicit --source flag wins
+//   2. STEALTHOS_SOURCE env var
+//   3. Monorepo discovery: walk up from __dirname looking for sibling .ai/
+//   4. Fail loudly
+
+import { existsSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export function resolveSource({ flagSource } = {}) {
+  if (flagSource) {
+    const abs = resolve(flagSource);
+    if (!existsSync(join(abs, "manifest.json"))) {
+      throw new Error(`--source path does not contain manifest.json: ${abs}`);
+    }
+    return abs;
+  }
+  if (process.env.STEALTHOS_SOURCE) {
+    const abs = resolve(process.env.STEALTHOS_SOURCE);
+    if (!existsSync(join(abs, "manifest.json"))) {
+      throw new Error(`STEALTHOS_SOURCE does not contain manifest.json: ${abs}`);
+    }
+    return abs;
+  }
+  // Monorepo discovery: walk up from packages/stealthos-cli/src/lib/ to find sibling .ai/
+  let dir = __dirname;
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, ".ai");
+    if (existsSync(join(candidate, "manifest.json"))) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "Could not locate source .ai/ tree. Pass --source <path> or set STEALTHOS_SOURCE env var.",
+  );
+}