@dahch/muninn 0.0.0-stage → 0.1.0

package/dist/commands/memory.js

@@ -0,0 +1,325 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { MemoryService } from "../service/memory-service.js";
+import { startMcpServer } from "../mcp/server.js";
+import { indexFilesIntoMuninn } from "../indexer/ast-indexer.js";
+import { sanitizeTerminalText } from "../util/text.js";
+const IGNORED_INDEX_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".harness",
+    ".huginn",
+    "dist",
+    "build",
+    ".cache",
+]);
+const SOURCE_FILE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+]);
+export function findSourceFiles(dir) {
+    const results = [];
+    function walk(current) {
+        if (!fs.existsSync(current))
+            return;
+        try {
+            const entries = fs.readdirSync(current, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    if (!IGNORED_INDEX_DIRS.has(entry.name)) {
+                        walk(path.join(current, entry.name));
+                    }
+                }
+                else if (entry.isFile()) {
+                    const ext = path.extname(entry.name).toLowerCase();
+                    if (SOURCE_FILE_EXTENSIONS.has(ext)) {
+                        results.push(path.join(current, entry.name));
+                    }
+                }
+            }
+        }
+        catch {
+            // ignore read error
+        }
+    }
+    walk(dir);
+    return results;
+}
+export function printMemoryUsage() {
+    console.log(`muninn memory — Persistent codebase memory across spec-build cycles
+
+Usage:
+  muninn memory init [--db <path>] [--project <path>]
+  muninn memory search <query> [--category <cat>] [--limit <n>] [--project <path>]
+  muninn memory sync [--import] [--file <path>] [--project <path>]
+  muninn memory index [files...] [--project <path>] [--db <path>]
+
+Subcommands:
+  init     Initialize SQLite database and verify schema
+  search   Search observations with BM25 relevance ranking
+  sync     Export observations to disk (.jsonl) or import with --import
+  index    Index AST symbols and dependencies into Muninn memory
+`);
+}
+export function printMcpUsage() {
+    console.log(`muninn mcp — Model Context Protocol server for Muninn memory
+
+Usage:
+  muninn mcp run [--db <path>] [--project <path>]
+
+Subcommands:
+  run     Start the stdio MCP server for agent memory integration
+`);
+}
+export async function handleMemoryCommand(subcommand, args, positionals) {
+    const dbPath = typeof args["--db"] === "string" ? args["--db"] : undefined;
+    const projectRoot = typeof args["--project"] === "string"
+        ? args["--project"]
+        : typeof args["--root"] === "string"
+            ? args["--root"]
+            : undefined;
+    if (!subcommand ||
+        args["--help"] ||
+        args["-h"] ||
+        subcommand === "help" ||
+        subcommand === "--help" ||
+        subcommand === "-h") {
+        printMemoryUsage();
+        return;
+    }
+    if (subcommand === "init") {
+        const service = new MemoryService({ dbPath, projectRoot });
+        try {
+            const project = service.currentProject;
+            console.log(chalk.green("✔ Muninn memory database initialized"));
+            console.log(`  Database: ${service.db.name}`);
+            console.log(`  Project:  ${project.name} (${project.root_path})`);
+            console.log(`  Status:   Tables ready`);
+        }
+        finally {
+            service.close?.();
+        }
+        return;
+    }
+    if (subcommand === "search") {
+        const queryPositional = positionals?.[0] ??
+            (typeof args._positional === "string" && args._positional !== "search"
+                ? args._positional
+                : undefined);
+        const query = typeof args["--query"] === "string" ? args["--query"] : queryPositional;
+        if (!query || query.trim() === "") {
+            console.error(chalk.red("Error: Search query is required."));
+            process.exitCode = 1;
+            return;
+        }
+        const category = typeof args["--category"] === "string" ? args["--category"] : undefined;
+        const parsedLimit = typeof args["--limit"] === "string"
+            ? Math.floor(Number(args["--limit"]))
+            : undefined;
+        const limit = parsedLimit && parsedLimit > 0 ? parsedLimit : 10;
+        const service = new MemoryService({ dbPath, projectRoot });
+        try {
+            const results = service.search({
+                query: query.trim(),
+                category,
+                limit,
+            });
+            if (results.length === 0) {
+                console.log(`No observations found matching "${query.trim()}".`);
+                return;
+            }
+            console.log(chalk.bold(`Found ${results.length} result(s) for "${query.trim()}" (BM25 ranked):`));
+            for (const obs of results) {
+                const categoryTag = chalk.cyan(`[${obs.category.toUpperCase()}]`);
+                const rankScore = chalk.gray(`(score: ${obs.rank.toFixed(3)})`);
+                console.log(`\n${categoryTag} ${chalk.bold(obs.title)} ${rankScore}`);
+                if (obs.topic_key) {
+                    console.log(`  ${chalk.dim("Topic:")} ${obs.topic_key}`);
+                }
+                const preview = obs.content.length > 150
+                    ? `${obs.content.slice(0, 147)}...`
+                    : obs.content;
+                console.log(`  ${chalk.white(preview.replace(/\n/g, " "))}`);
+                if (obs.entities && obs.entities.length > 0) {
+                    const symbols = obs.entities.map((e) => e.identifier).join(", ");
+                    console.log(`  ${chalk.dim("Symbols:")} ${chalk.yellow(symbols)}`);
+                }
+            }
+        }
+        finally {
+            service.close?.();
+        }
+        return;
+    }
+    if (subcommand === "sync") {
+        const syncPositional = positionals?.[0] ??
+            (typeof args._positional === "string" && args._positional !== "sync"
+                ? args._positional
+                : undefined);
+        const filePath = typeof args["--file"] === "string" ? args["--file"] : syncPositional;
+        const isImport = Boolean(args["--import"]);
+        const service = new MemoryService({ dbPath, projectRoot });
+        try {
+            if (isImport) {
+                const result = service.importFromDisk(filePath);
+                console.log(`Imported ${result.imported} memories (skipped ${result.skipped} duplicates) from ${filePath ?? path.join(service.currentProject.root_path || process.cwd(), ".huginn", "memories.jsonl")}.`);
+            }
+            else {
+                const result = service.syncToDisk(filePath);
+                console.log(`Synced ${result.count} memories to ${result.path}.`);
+            }
+        }
+        finally {
+            service.close?.();
+        }
+        return;
+    }
+    if (subcommand === "index") {
+        const rawFiles = positionals && positionals.length > 0
+            ? positionals
+            : typeof args._positional === "string" && args._positional !== "index"
+                ? [args._positional]
+                : [];
+        const service = new MemoryService({ dbPath, projectRoot });
+        try {
+            const root = service.currentProject.root_path || process.cwd();
+            const targetFiles = rawFiles.length > 0 ? rawFiles : findSourceFiles(root);
+            const result = indexFilesIntoMuninn(service, targetFiles, {
+                projectRoot: root,
+            });
+            console.log(chalk.green(`✔ Indexed ${result.indexedFiles} file(s) (${result.indexedSymbols} symbol(s), ${result.indexedDependencies} dependency link(s)) into Muninn memory.`));
+        }
+        finally {
+            service.close?.();
+        }
+        return;
+    }
+    console.error(chalk.red(`Unknown subcommand: ${subcommand}`));
+    printMemoryUsage();
+    process.exitCode = 1;
+}
+/**
+ * Logs to stderr without ever risking a second crash (ADR-30.3): once the
+ * parent pipe is gone, even the diagnostic write can fail with EPIPE.
+ */
+function logToStderr(line) {
+    try {
+        process.stderr.write(line.endsWith("\n") ? line : `${line}\n`);
+    }
+    catch {
+        /* stderr is gone too — the process is exiting anyway */
+    }
+}
+/**
+ * Installs the stdio guards that keep `muninn mcp run` from crashing or hanging
+ * when its parent goes away (REQ-30 / AC-30.3):
+ *
+ * - an `'error'` handler on `process.stdout` so an EPIPE from a closed parent
+ *   pipe is logged and turned into a clean shutdown instead of an unhandled
+ *   exception that kills the server mid-response;
+ * - a no-op `'error'` handler on `process.stderr` for the same reason (a dead
+ *   parent usually breaks both ends);
+ * - `'end'`/`'close'` on `process.stdin` — the SDK transport only observes
+ *   `'data'`/`'error'`, so without this bridge a parent disconnect is invisible
+ *   and the server would keep running forever.
+ */
+function installStdioGuards(onStdoutFailure) {
+    const onStdoutError = (err) => {
+        logToStderr(`[muninn] mcp run: stdout write failed (${sanitizeTerminalText(err.message)}); shutting down.`);
+        onStdoutFailure();
+    };
+    const onStderrError = () => {
+        /* a broken stderr must never crash the JSON-RPC server */
+    };
+    process.stdout.on("error", onStdoutError);
+    process.stderr.on("error", onStderrError);
+    return {
+        dispose() {
+            process.stdout.off("error", onStdoutError);
+            process.stderr.off("error", onStderrError);
+        },
+    };
+}
+export async function handleMcpCommand(subcommand, args) {
+    const dbPath = typeof args["--db"] === "string" ? args["--db"] : undefined;
+    const projectRoot = typeof args["--project"] === "string"
+        ? args["--project"]
+        : typeof args["--root"] === "string"
+            ? args["--root"]
+            : undefined;
+    if (!subcommand ||
+        args["--help"] ||
+        args["-h"] ||
+        subcommand === "help" ||
+        subcommand === "--help" ||
+        subcommand === "-h") {
+        printMcpUsage();
+        return;
+    }
+    if (subcommand === "run") {
+        const { server, transport, service } = await startMcpServer({
+            dbPath,
+            projectRoot,
+        });
+        try {
+            // Protocol failures were previously discarded (AC-30.3): surface them on
+            // stderr (never stdout — that stream carries JSON-RPC) without aborting.
+            if (server) {
+                server.onerror = (err) => {
+                    logToStderr(`[muninn] mcp run: protocol error: ${sanitizeTerminalText(err.message)}`);
+                };
+            }
+            // Keep process alive while stdio transport is connected:
+            await new Promise((resolve) => {
+                let finished = false;
+                const onStdinClosed = () => {
+                    if ((process.env.MUNINN_DEBUG || process.env.HUGINN_DEBUG)) {
+                        logToStderr("[muninn] mcp run: stdin closed by the client; shutting down.");
+                    }
+                    done();
+                };
+                const guards = installStdioGuards(() => done());
+                const done = () => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    process.removeListener("SIGINT", done);
+                    process.removeListener("SIGTERM", done);
+                    process.stdin.removeListener("end", onStdinClosed);
+                    process.stdin.removeListener("close", onStdinClosed);
+                    guards.dispose();
+                    resolve();
+                };
+                if (transport) {
+                    transport.onclose = () => done();
+                }
+                else {
+                    done();
+                    return;
+                }
+                // The parent disappearing is a lifecycle event, not a hang: bridge EOF
+                // (and an abruptly closed pipe) to the same shutdown path as onclose.
+                process.stdin.on("end", onStdinClosed);
+                process.stdin.on("close", onStdinClosed);
+                process.on("SIGINT", done);
+                process.on("SIGTERM", done);
+            });
+        }
+        finally {
+            service?.close?.();
+            await server?.close?.();
+        }
+        return;
+    }
+    console.error(chalk.red(`Unknown subcommand: ${subcommand}`));
+    printMcpUsage();
+    process.exitCode = 1;
+}
+//# sourceMappingURL=memory.js.map

package/dist/commands/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/commands/memory.ts"],"names":[],"mappings":"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"}

package/dist/contracts/compiler.d.ts

@@ -0,0 +1,71 @@
+import ts from "typescript";
+export type DiagnosticCategoryName = "error" | "warning" | "message" | "suggestion";
+export interface FormattedDiagnostic {
+    filePath: string;
+    line: number;
+    character: number;
+    code: string;
+    category: DiagnosticCategoryName;
+    message: string;
+    snippet?: string;
+}
+export interface ContractVerificationResult {
+    valid: boolean;
+    errorsCount: number;
+    diagnostics: FormattedDiagnostic[];
+}
+/**
+ * Safe default TypeScript compiler options used when tsconfig.json is absent or invalid.
+ */
+export declare const DEFAULT_COMPILER_OPTIONS: ts.CompilerOptions;
+/**
+ * Creates a formatted visual snippet of the line of code containing the error,
+ * with a caret pointer underlining the exact error span.
+ * Clamps input positions, line lengths, and span lengths to bounded limits (SEC-006, REV-008).
+ */
+export declare function createVisualSnippet(sourceFile: ts.SourceFile, start: number, length?: number): string;
+/**
+ * Formats a raw TypeScript compiler diagnostic into a structured FormattedDiagnostic.
+ */
+export declare function formatDiagnostic(diagnostic: ts.Diagnostic, projectRoot: string): FormattedDiagnostic;
+/**
+ * Loads tsconfig.json strictly from projectRoot without walking up parent directories (REV-005, SEC-007).
+ */
+export declare function loadProjectConfig(projectRoot: string): {
+    configPath: string | undefined;
+    options: ts.CompilerOptions;
+    fileNames: string[];
+    errors: ts.Diagnostic[];
+};
+export declare const TS_JS_EXTENSIONS: Set<string>;
+/**
+ * Recursively discovers TypeScript/JavaScript source files within a directory.
+ */
+export declare function findSourceFilesInDir(dir: string): string[];
+export type ResolveTargetFilesResult = {
+    success: true;
+    targetFiles?: string[];
+} | {
+    success: false;
+    failure: ContractVerificationResult;
+};
+/**
+ * Validates requested file paths against path traversal and file existence (SEC-001, REV-003).
+ */
+export declare function resolveTargetFiles(projectRoot: string, filePaths?: string[]): ResolveTargetFilesResult;
+/**
+ * Verifies TypeScript compilation contracts for the given project and files.
+ * Returns structured pre-emit diagnostics with line/character locations and visual code snippets.
+ */
+export declare function verifyTypeScriptContracts(projectRoot: string, filePaths?: string[]): ContractVerificationResult;
+/**
+ * Formats a ContractVerificationResult into a markdown report suitable for
+ * gate evaluation and thinker fix prompts.
+ */
+export declare function formatDiagnosticsReport(result: ContractVerificationResult): string;
+export declare const TypeValidator: {
+    check: typeof verifyTypeScriptContracts;
+    formatReport: typeof formatDiagnosticsReport;
+    DEFAULT_COMPILER_OPTIONS: ts.CompilerOptions;
+};
+//# sourceMappingURL=compiler.d.ts.map

package/dist/contracts/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/contracts/compiler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,MAAM,sBAAsB,GAC9B,OAAO,GACP,SAAS,GACT,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,EAAE,CAAC,eASzC,CAAC;AAkBF;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAU,GACjB,MAAM,CA+BR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,WAAW,EAAE,MAAM,GAClB,mBAAmB,CAwCrB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC;CACzB,CAuCA;AAED,eAAO,MAAM,gBAAgB,aAS3B,CAAC;AAEH;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAsB1D;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACzC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,0BAA0B,CAAA;CAAE,CAAC;AAE5D;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,wBAAwB,CAyD1B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,0BAA0B,CAwI5B;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,0BAA0B,GACjC,MAAM,CAyBR;AAED,eAAO,MAAM,aAAa;;;;CAIzB,CAAC"}