stealthos-cli 0.1.0-alpha.3 → 0.1.0-alpha.4

package/ai/server/src/packager/context-builder.ts

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ContextPackage, ProjectState } from "../types.js";
+import { analyzeProject } from "../analyzer/index.js";
+import { extractKeywords, injectMemory } from "./memory-injector.js";
+import { renderModuleYaml, summarizeModule } from "./module-summarizer.js";
+import { estimateTokens, checkHeadroom } from "./token-estimator.js";
+
+export interface BuildOptions {
+  intent?: string;
+  maxModules?: number;
+  state?: ProjectState;
+  write?: boolean;
+  windowTokens?: number;
+}
+
+export async function buildContextPackage(
+  projectRoot: string,
+  options: BuildOptions = {},
+): Promise<ContextPackage> {
+  const intent = (options.intent ?? "").trim();
+  const state = options.state ?? (await analyzeProject(projectRoot, { write: false }));
+  const keywords = extractKeywords(intent);
+  const maxModules = options.maxModules ?? 12;
+
+  const rankedModules = state.modules
+    .map((m) => ({ m, s: scoreModule(m.id, m.exports, m.imports, keywords) }))
+    .sort((a, b) => b.s - a.s);
+
+  const chosen =
+    keywords.length === 0
+      ? topByInbound(state, maxModules)
+      : rankedModules
+          .filter((x) => x.s > 0)
+          .slice(0, maxModules)
+          .map((x) => x.m);
+
+  if (chosen.length === 0 && state.modules.length > 0) {
+    chosen.push(...topByInbound(state, Math.min(5, state.modules.length)));
+  }
+
+  const memory = await injectMemory(projectRoot, keywords, 6);
+
+  const sections: string[] = [];
+
+  sections.push(renderHeader(intent, state));
+  sections.push(renderStackBlock(state));
+
+  if (memory.rules_summary) {
+    sections.push("## Critical rules (from .ai/rules/dont.md)\n\n" + memory.rules_summary);
+  }
+
+  if (chosen.length) {
+    const moduleBlocks = chosen.map((m) => {
+      const sum = summarizeModule(m, state.graph, state.smells);
+      return "```yaml\n" + renderModuleYaml(sum) + "\n```";
+    });
+    sections.push("## Modules in scope (" + chosen.length + ")\n\n" + moduleBlocks.join("\n\n"));
+  } else if (state.modules.length === 0) {
+    sections.push(
+      "## Modules in scope\n\n_(no code modules detected yet — project is in `.ai/` setup phase)_",
+    );
+  }
+
+  if (memory.decisions.length) {
+    sections.push(
+      "## Relevant decisions (from memory)\n\n" +
+        memory.decisions.map((d) => `### ${d.title}\n\n${truncate(d.body, 600)}`).join("\n\n"),
+    );
+  }
+  if (memory.errors.length) {
+    sections.push(
+      "## Past errors & solutions\n\n" +
+        memory.errors.map((d) => `### ${d.title}\n\n${truncate(d.body, 500)}`).join("\n\n"),
+    );
+  }
+  if (memory.issues.length) {
+    sections.push(
+      "## Known issues\n\n" +
+        memory.issues.map((d) => `### ${d.title}\n\n${truncate(d.body, 400)}`).join("\n\n"),
+    );
+  }
+
+  if (state.smells.length) {
+    const top = state.smells.slice(0, 8);
+    sections.push(
+      "## Top smells\n\n" +
+        top
+          .map(
+            (s) =>
+              `- **${s.kind}** [${s.severity}] \`${s.location.file}${
+                s.location.line ? ":" + s.location.line : ""
+              }\` — ${s.message}`,
+          )
+          .join("\n"),
+    );
+  }
+
+  const markdown = sections.join("\n\n").trim() + "\n";
+  const tokens = estimateTokens(markdown);
+  const sourceHash = sha256OfStateRef(state);
+
+  const pkg: ContextPackage = {
+    intent: intent || "(no intent — general project overview)",
+    generated_at: new Date().toISOString(),
+    estimated_tokens: tokens,
+    source_state_hash: sourceHash,
+    modules_included: chosen.map((m) => m.id),
+    markdown,
+  };
+
+  if (options.write !== false) {
+    const ctxDir = join(projectRoot, ".ai", "context", "packages");
+    await mkdir(ctxDir, { recursive: true });
+    const slug = slugify(intent) || "overview";
+    const mdPath = join(ctxDir, `${slug}.md`);
+    const jsonPath = join(ctxDir, `${slug}.json`);
+    await writeFile(mdPath, markdown, "utf8");
+    await writeFile(
+      jsonPath,
+      JSON.stringify(
+        {
+          intent: pkg.intent,
+          generated_at: pkg.generated_at,
+          estimated_tokens: pkg.estimated_tokens,
+          source_state_hash: pkg.source_state_hash,
+          modules_included: pkg.modules_included,
+          headroom: checkHeadroom(markdown, options.windowTokens),
+          file: `${slug}.md`,
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+  }
+
+  return pkg;
+}
+
+function scoreModule(
+  id: string,
+  exportsList: string[],
+  imports: string[],
+  keywords: string[],
+): number {
+  if (keywords.length === 0) return 0;
+  let s = 0;
+  const lowerId = id.toLowerCase();
+  for (const k of keywords) {
+    if (k.length < 3) continue;
+    if (lowerId.includes(k)) s += 5;
+    for (const e of exportsList) if (e.toLowerCase().includes(k)) s += 3;
+    for (const i of imports) if (i.toLowerCase().includes(k)) s += 1;
+  }
+  return s;
+}
+
+function topByInbound(state: ProjectState, limit: number) {
+  const inbound = new Map<string, number>();
+  for (const e of state.graph.edges) {
+    inbound.set(e.to, (inbound.get(e.to) ?? 0) + 1);
+  }
+  return [...state.modules]
+    .sort((a, b) => (inbound.get(b.id) ?? 0) - (inbound.get(a.id) ?? 0))
+    .slice(0, limit);
+}
+
+function renderHeader(intent: string, state: ProjectState): string {
+  return [
+    "# Context Package",
+    "",
+    `**Intent:** ${intent || "_(general project overview)_"}`,
+    `**Generated:** ${new Date().toISOString()}`,
+    `**Runtime:** v${state.version}`,
+    `**Source:** \`.ai/context/project-state.json\` (${state.modules.length} modules, ${state.smells.length} smells)`,
+  ].join("\n");
+}
+
+function renderStackBlock(state: ProjectState): string {
+  const s = state.stack;
+  const lines = [
+    "## Stack",
+    "",
+    `- Languages: ${s.languages.join(", ") || "(none detected)"}`,
+    `- Frameworks: ${s.frameworks.join(", ") || "(none)"}`,
+  ];
+  if (s.package_manager) lines.push(`- Package manager: ${s.package_manager}`);
+  if (s.databases?.length) lines.push(`- Databases: ${s.databases.join(", ")}`);
+  if (s.test_frameworks?.length) lines.push(`- Test frameworks: ${s.test_frameworks.join(", ")}`);
+  return lines.join("\n");
+}
+
+function truncate(text: string, n: number): string {
+  const t = text.trim();
+  return t.length <= n ? t : t.slice(0, n - 1) + "…";
+}
+
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .slice(0, 50);
+}
+
+function sha256OfStateRef(state: ProjectState): string {
+  const h = createHash("sha256");
+  h.update(state.generated_at);
+  h.update(String(state.modules.length));
+  h.update(String(state.graph.edges.length));
+  return h.digest("hex").slice(0, 16);
+}

package/ai/server/src/packager/index.ts

@@ -0,0 +1,3 @@
+export { buildContextPackage } from "./context-builder.js";
+export { estimateTokens, checkHeadroom } from "./token-estimator.js";
+export { extractKeywords } from "./memory-injector.js";

package/ai/server/src/packager/memory-injector.ts

@@ -0,0 +1,128 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export interface MemoryEntry {
+  source: string;
+  title: string;
+  body: string;
+}
+
+export interface InjectedMemory {
+  decisions: MemoryEntry[];
+  errors: MemoryEntry[];
+  issues: MemoryEntry[];
+  rules_summary: string;
+}
+
+export async function injectMemory(
+  projectRoot: string,
+  keywords: string[],
+  limit = 6,
+): Promise<InjectedMemory> {
+  const memDir = join(projectRoot, ".ai", "memory");
+  const rulesDir = join(projectRoot, ".ai", "rules");
+
+  const decisions = await loadEntries(join(memDir, "decisions.md"), "decisions.md");
+  const errors = await loadEntries(join(memDir, "errors-and-solutions.md"), "errors-and-solutions.md");
+  const issues = await loadEntries(join(memDir, "known-issues.md"), "known-issues.md");
+
+  const rank = (e: MemoryEntry) => score(e.title + " " + e.body, keywords);
+
+  return {
+    decisions: pickTop(decisions, rank, limit),
+    errors: pickTop(errors, rank, limit),
+    issues: pickTop(issues, rank, limit),
+    rules_summary: await summarizeRules(rulesDir),
+  };
+}
+
+async function loadEntries(filePath: string, source: string): Promise<MemoryEntry[]> {
+  if (!existsSync(filePath)) return [];
+  const txt = await readFile(filePath, "utf8").catch(() => "");
+  if (!txt) return [];
+  const sections = txt.split(/\n(?=##\s+)/);
+  const entries: MemoryEntry[] = [];
+  for (const sec of sections) {
+    const trimmed = sec.trim();
+    if (!trimmed.startsWith("##")) continue;
+    const firstLineEnd = trimmed.indexOf("\n");
+    const title = (firstLineEnd > 0 ? trimmed.slice(0, firstLineEnd) : trimmed)
+      .replace(/^#+\s*/, "")
+      .trim();
+    const body = firstLineEnd > 0 ? trimmed.slice(firstLineEnd + 1).trim() : "";
+    if (title.toLowerCase().includes("template") || title.toLowerCase().includes("exemplo")) continue;
+    entries.push({ source, title, body });
+  }
+  return entries;
+}
+
+function score(text: string, keywords: string[]): number {
+  if (keywords.length === 0) return 0;
+  const lower = text.toLowerCase();
+  let s = 0;
+  for (const k of keywords) {
+    if (k.length < 3) continue;
+    const occurrences = lower.split(k).length - 1;
+    s += occurrences;
+  }
+  return s;
+}
+
+function pickTop<T>(items: T[], rank: (item: T) => number, limit: number): T[] {
+  return [...items]
+    .map((item) => ({ item, s: rank(item) }))
+    .filter((x) => x.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, limit)
+    .map((x) => x.item);
+}
+
+async function summarizeRules(rulesDir: string): Promise<string> {
+  if (!existsSync(rulesDir)) return "";
+  const dont = await readFile(join(rulesDir, "dont.md"), "utf8").catch(() => "");
+  if (!dont) return "";
+  const lines = dont.split("\n").filter((l) => /^\s*-\s+/.test(l) || /^##\s+/.test(l));
+  return lines.slice(0, 25).join("\n");
+}
+
+export function extractKeywords(intent: string): string[] {
+  const stop = new Set([
+    "para",
+    "como",
+    "uma",
+    "que",
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "this",
+    "that",
+    "into",
+    "your",
+    "vai",
+    "com",
+    "ser",
+    "dos",
+    "das",
+    "por",
+    "ele",
+    "ela",
+    "isto",
+    "isso",
+    "pelo",
+    "pela",
+    "sobre",
+    "novo",
+    "nova",
+    "novos",
+    "novas",
+  ]);
+  return intent
+    .toLowerCase()
+    .replace(/[^\w\sáéíóúâêîôûãõàèìòùç-]/g, " ")
+    .split(/\s+/)
+    .map((w) => w.trim())
+    .filter((w) => w.length >= 3 && !stop.has(w));
+}

package/ai/server/src/packager/module-summarizer.ts

@@ -0,0 +1,60 @@
+import type { DependencyGraph, ModuleInfo, Smell } from "../types.js";
+
+export interface ModuleSummary {
+  module: string;
+  language: string;
+  size_lines: number;
+  exports: string[];
+  depends_on: string[];
+  inbound: string[];
+  smells: string[];
+}
+
+export function summarizeModule(
+  m: ModuleInfo,
+  graph: DependencyGraph,
+  smells: Smell[],
+): ModuleSummary {
+  const internalDeps = graph.edges
+    .filter((e) => e.from === m.id)
+    .map((e) => e.to);
+  const externalDeps = m.imports.filter((i) => !i.startsWith("."));
+  const inbound = graph.edges.filter((e) => e.to === m.id).map((e) => e.from);
+  const moduleSmells = smells
+    .filter((s) => s.location.file === m.path)
+    .map((s) => `${s.kind}${s.location.line ? `:L${s.location.line}` : ""} — ${s.message}`);
+
+  return {
+    module: m.id,
+    language: m.language,
+    size_lines: m.size_lines,
+    exports: m.exports.slice(0, 10),
+    depends_on: [...internalDeps, ...externalDeps].slice(0, 12),
+    inbound: inbound.slice(0, 10),
+    smells: moduleSmells.slice(0, 5),
+  };
+}
+
+export function renderModuleYaml(s: ModuleSummary): string {
+  const lines: string[] = [];
+  lines.push(`module: ${s.module}`);
+  lines.push(`language: ${s.language}`);
+  lines.push(`size_lines: ${s.size_lines}`);
+  if (s.exports.length) {
+    lines.push("exports:");
+    for (const e of s.exports) lines.push(`  - ${e}`);
+  }
+  if (s.depends_on.length) {
+    lines.push("depends_on:");
+    for (const d of s.depends_on) lines.push(`  - ${d}`);
+  }
+  if (s.inbound.length) {
+    lines.push("inbound:");
+    for (const i of s.inbound) lines.push(`  - ${i}`);
+  }
+  if (s.smells.length) {
+    lines.push("smells:");
+    for (const sm of s.smells) lines.push(`  - "${sm.replace(/"/g, '\\"')}"`);
+  }
+  return lines.join("\n");
+}

package/ai/server/src/packager/token-estimator.ts

@@ -0,0 +1,26 @@
+const CHARS_PER_TOKEN = 3.8;
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+export interface HeadroomCheck {
+  estimated: number;
+  budget: number;
+  fits: boolean;
+  utilization_pct: number;
+}
+
+const DEFAULT_WINDOW = 200_000;
+const HEADROOM_RATIO = 0.4;
+
+export function checkHeadroom(text: string, windowTokens: number = DEFAULT_WINDOW): HeadroomCheck {
+  const estimated = estimateTokens(text);
+  const budget = Math.floor(windowTokens * HEADROOM_RATIO);
+  return {
+    estimated,
+    budget,
+    fits: estimated <= budget,
+    utilization_pct: Math.round((estimated / windowTokens) * 1000) / 10,
+  };
+}

package/ai/server/src/snapshot/index.ts

@@ -0,0 +1,3 @@
+export { createSnapshot } from "./snapshot-creator.js";
+export { listSnapshots, diffSnapshots } from "./snapshot-diff.js";
+export { restoreSnapshot } from "./snapshot-restore.js";

package/ai/server/src/snapshot/snapshot-creator.ts

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { ProjectState, SnapshotManifest } from "../types.js";
+import { analyzeProject } from "../analyzer/index.js";
+
+const TRACKED_ROOTS = [".ai", ".claude", "CLAUDE.md", "GEMINI.md", "GPT.md"];
+const HASH_IGNORED_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".runtime",
+  "archive",
+  ".turbo",
+  ".vercel",
+  ".next",
+]);
+
+export interface CreateOptions {
+  label: string;
+  state?: ProjectState;
+}
+
+export async function createSnapshot(
+  projectRoot: string,
+  options: CreateOptions,
+): Promise<SnapshotManifest> {
+  const label = sanitizeLabel(options.label);
+  const id = `${timestamp()}-${label}`;
+  const snapDir = join(projectRoot, ".ai", "snapshots", id);
+  await mkdir(snapDir, { recursive: true });
+
+  const state = options.state ?? (await analyzeProject(projectRoot, { write: false }));
+  const fileHashes = await hashTrackedFiles(projectRoot);
+
+  const stateFile = "state.json";
+  const summaryFile = "summary.md";
+
+  const manifest: SnapshotManifest = {
+    id,
+    label,
+    created_at: new Date().toISOString(),
+    project_root: projectRoot,
+    state_file: stateFile,
+    summary_file: summaryFile,
+    file_hashes: fileHashes,
+    stats: {
+      total_files_hashed: Object.keys(fileHashes).length,
+      modules: state.modules.length,
+      smells: state.smells.length,
+    },
+  };
+
+  await writeFile(join(snapDir, stateFile), JSON.stringify(state, null, 2), "utf8");
+  await writeFile(
+    join(snapDir, summaryFile),
+    renderSummary(manifest, state, await readMemorySnapshot(projectRoot)),
+    "utf8",
+  );
+  await writeFile(join(snapDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+
+  return manifest;
+}
+
+function timestamp(): string {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+function sanitizeLabel(label: string): string {
+  return label.replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "snap";
+}
+
+async function hashTrackedFiles(projectRoot: string): Promise<Record<string, string>> {
+  const hashes: Record<string, string> = {};
+  for (const root of TRACKED_ROOTS) {
+    const abs = join(projectRoot, root);
+    if (!existsSync(abs)) continue;
+    await walkAndHash(abs, projectRoot, hashes);
+  }
+  return hashes;
+}
+
+async function walkAndHash(
+  dir: string,
+  projectRoot: string,
+  out: Record<string, string>,
+): Promise<void> {
+  let stats;
+  try {
+    stats = await readdir(dir, { withFileTypes: true });
+  } catch {
+    // single-file root (CLAUDE.md etc.)
+    try {
+      const content = await readFile(dir);
+      const rel = relative(projectRoot, dir).replace(/\\/g, "/");
+      out[rel] = sha256(content);
+    } catch {
+      // ignore
+    }
+    return;
+  }
+  for (const e of stats) {
+    if (HASH_IGNORED_DIRS.has(e.name)) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      await walkAndHash(p, projectRoot, out);
+    } else if (e.isFile()) {
+      try {
+        const content = await readFile(p);
+        const rel = relative(projectRoot, p).replace(/\\/g, "/");
+        out[rel] = sha256(content);
+      } catch {
+        // ignore unreadable
+      }
+    }
+  }
+}
+
+function sha256(buf: Buffer): string {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+interface MemorySnapshot {
+  decisions_count: number;
+  pending_tasks_count: number;
+  known_issues_count: number;
+  last_decision?: string;
+}
+
+async function readMemorySnapshot(projectRoot: string): Promise<MemorySnapshot> {
+  const memDir = join(projectRoot, ".ai", "memory");
+  const snap: MemorySnapshot = {
+    decisions_count: 0,
+    pending_tasks_count: 0,
+    known_issues_count: 0,
+  };
+  const read = async (name: string) =>
+    readFile(join(memDir, name), "utf8").catch(() => "");
+
+  const decisions = await read("decisions.md");
+  const pending = await read("pending-tasks.md");
+  const issues = await read("known-issues.md");
+
+  snap.decisions_count = countMatches(decisions, /^##?\s+ADR-/gm) || countMatches(decisions, /^##\s+/gm);
+  snap.pending_tasks_count = countMatches(pending, /^\s*-\s+\[\s?\]/gm);
+  snap.known_issues_count = countMatches(issues, /^##\s+/gm);
+
+  const lastDecision = decisions.split(/\n##\s+/).slice(-1)[0]?.split("\n")[0];
+  if (lastDecision && lastDecision.trim().length > 0 && !lastDecision.includes("#")) {
+    snap.last_decision = lastDecision.trim().slice(0, 120);
+  }
+  return snap;
+}
+
+function countMatches(text: string, re: RegExp): number {
+  const m = text.match(re);
+  return m ? m.length : 0;
+}
+
+function renderSummary(
+  manifest: SnapshotManifest,
+  state: ProjectState,
+  mem: MemorySnapshot,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Snapshot ${manifest.id}`, "");
+  lines.push(`**Label:** ${manifest.label}`);
+  lines.push(`**Created:** ${manifest.created_at}`);
+  lines.push(`**Root:** \`${manifest.project_root}\``, "");
+
+  lines.push("## Project state at capture", "");
+  lines.push(`- Languages: ${state.stack.languages.join(", ") || "(none)"}`);
+  lines.push(`- Modules: ${state.modules.length}`);
+  lines.push(`- Smells: ${state.smells.length}`);
+  lines.push(`- Circular deps: ${state.graph.cycles.length}`);
+  lines.push(`- Total files (repo): ${state.stats.total_files}`);
+  lines.push("");
+
+  lines.push("## Files hashed", "");
+  lines.push(`- Count: ${manifest.stats.total_files_hashed}`);
+  lines.push("");
+
+  lines.push("## Memory at capture", "");
+  lines.push(`- Decisions logged: ${mem.decisions_count}`);
+  lines.push(`- Pending tasks: ${mem.pending_tasks_count}`);
+  lines.push(`- Known issues: ${mem.known_issues_count}`);
+  if (mem.last_decision) {
+    lines.push(`- Last decision: _${mem.last_decision}_`);
+  }
+  lines.push("");
+
+  if (state.smells.length) {
+    lines.push("## Top smells", "");
+    for (const s of state.smells.slice(0, 10)) {
+      const loc = `${s.location.file}${s.location.line ? ":" + s.location.line : ""}`;
+      lines.push(`- **${s.kind}** [${s.severity}] \`${loc}\` — ${s.message}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}