obsidian-second-brain 0.1.0 → 0.2.0

package/dist/managed-section.js

@@ -1,30 +1,51 @@
-const BEGIN_MARKER = "<!-- BEGIN second-brain (managed by second-brain init — do not edit inside) -->";
-const END_MARKER = "<!-- END second-brain -->";
-export function hasManagedSection(content) {
-    return content.includes(BEGIN_MARKER) && content.includes(END_MARKER);
+// Historical strings — existing vaults already contain them; never reword.
+export const INIT_MARKERS = {
+    begin: "<!-- BEGIN second-brain (managed by second-brain init — do not edit inside) -->",
+    end: "<!-- END second-brain -->"
+};
+export const CODE_MAPS_MARKERS = {
+    begin: "<!-- BEGIN second-brain code-maps (managed by second-brain — do not edit inside) -->",
+    end: "<!-- END second-brain code-maps -->"
+};
+export function hasManagedBlock(content, markers) {
+    return content.includes(markers.begin) && content.includes(markers.end);
 }
 // Idempotent: re-applying replaces the block in place, never duplicates
-// (design 7.3). The block argument must already contain the markers.
+// (design 7.3). `body` must NOT contain the markers — they are added here.
+export function applyManagedBlock(existing, markers, body) {
+    const block = [markers.begin, body.trim(), markers.end].join("\n");
+    return applyBlockString(existing, markers, block);
+}
+export function removeManagedBlock(content, markers) {
+    if (!hasManagedBlock(content, markers)) {
+        return content;
+    }
+    const beginIndex = content.indexOf(markers.begin);
+    const endIndex = content.indexOf(markers.end) + markers.end.length;
+    const before = content.slice(0, beginIndex).replace(/\n+$/u, "");
+    const after = content.slice(endIndex).replace(/^\n+/u, "");
+    const joined = [before, after].filter((part) => part.length > 0).join("\n");
+    return joined.length > 0 ? `${joined}\n` : "";
+}
+// Legacy init API — the block argument already contains the INIT markers.
+export function hasManagedSection(content) {
+    return hasManagedBlock(content, INIT_MARKERS);
+}
 export function applyManagedSection(existing, block) {
+    return applyBlockString(existing, INIT_MARKERS, block);
+}
+export function removeManagedSection(content) {
+    return removeManagedBlock(content, INIT_MARKERS);
+}
+function applyBlockString(existing, markers, block) {
     const trimmedBlock = block.trim();
     if (existing === undefined || existing.trim().length === 0) {
         return `${trimmedBlock}\n`;
     }
-    if (hasManagedSection(existing)) {
-        const beginIndex = existing.indexOf(BEGIN_MARKER);
-        const endIndex = existing.indexOf(END_MARKER) + END_MARKER.length;
+    if (hasManagedBlock(existing, markers)) {
+        const beginIndex = existing.indexOf(markers.begin);
+        const endIndex = existing.indexOf(markers.end) + markers.end.length;
         return `${existing.slice(0, beginIndex)}${trimmedBlock}${existing.slice(endIndex)}`;
     }
     return `${existing.replace(/\n+$/u, "")}\n\n${trimmedBlock}\n`;
 }
-export function removeManagedSection(content) {
-    if (!hasManagedSection(content)) {
-        return content;
-    }
-    const beginIndex = content.indexOf(BEGIN_MARKER);
-    const endIndex = content.indexOf(END_MARKER) + END_MARKER.length;
-    const before = content.slice(0, beginIndex).replace(/\n+$/u, "");
-    const after = content.slice(endIndex).replace(/^\n+/u, "");
-    const joined = [before, after].filter((part) => part.length > 0).join("\n");
-    return joined.length > 0 ? `${joined}\n` : "";
-}

package/dist/map-command.js

@@ -0,0 +1,191 @@
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { captureRepo, defaultCaptureDependencies } from "./code-capture.js";
+import { stripCodeManifestEntries } from "./code-classify.js";
+import { runCodeMapIngest } from "./code-ingest.js";
+import { createCliClaudeCodeMapBackend, resolveCodeMapBackend } from "./code-map-backend.js";
+import { DEFAULT_MAX_MODULES } from "./code-map-config.js";
+import { loadConfig } from "./config.js";
+import { writeFileAtomic } from "./filesystem.js";
+import { acquireLock } from "./lock.js";
+import { loadManifest, saveManifest } from "./manifest.js";
+import { createReportWriter } from "./report.js";
+import { isSlug, slugify } from "./slug.js";
+import { resolveVaultPaths } from "./vault-paths.js";
+const USAGE = "Usage: second-brain map <repoPath> [--project <name>] [--path <subdir>] [--max-modules N] [--force]";
+export function parseMapArgs(argv) {
+    let configPath;
+    let force = false;
+    let maxModules;
+    let project;
+    let repoPath;
+    let scope;
+    for (let index = 0; index < argv.length; index += 1) {
+        const currentArg = argv[index];
+        if (currentArg === "--force") {
+            force = true;
+            continue;
+        }
+        if (currentArg === "--config" ||
+            currentArg === "--max-modules" ||
+            currentArg === "--path" ||
+            currentArg === "--project") {
+            const nextArg = argv[index + 1];
+            if (!nextArg) {
+                throw new Error(`Missing value for ${currentArg}`);
+            }
+            if (currentArg === "--config") {
+                configPath = nextArg;
+            }
+            else if (currentArg === "--project") {
+                project = nextArg;
+            }
+            else if (currentArg === "--path") {
+                scope = nextArg.replace(/\/+$/u, "");
+            }
+            else {
+                const parsed = Number(nextArg);
+                if (!Number.isInteger(parsed) || parsed < 1 || parsed > 64) {
+                    throw new Error(`Invalid --max-modules: ${nextArg}`);
+                }
+                maxModules = parsed;
+            }
+            index += 1;
+            continue;
+        }
+        if (currentArg.startsWith("--")) {
+            throw new Error(`Unknown argument: ${currentArg}`);
+        }
+        if (repoPath !== undefined) {
+            throw new Error(`Unexpected argument: ${currentArg}`);
+        }
+        repoPath = currentArg;
+    }
+    if (repoPath === undefined) {
+        throw new Error(USAGE);
+    }
+    return {
+        ...(configPath === undefined ? {} : { configPath }),
+        force,
+        ...(maxModules === undefined ? {} : { maxModules }),
+        ...(project === undefined ? {} : { project }),
+        repoPath,
+        ...(scope === undefined ? {} : { scope })
+    };
+}
+export async function runMapCommand(argv, dependencies) {
+    const flags = parseMapArgs(argv);
+    const configPath = resolve(flags.configPath ?? dependencies.defaultConfigPath);
+    const config = await loadConfig(configPath);
+    const repoPath = resolve(flags.repoPath);
+    const project = flags.project ?? slugify(basename(repoPath));
+    if (!isSlug(project)) {
+        throw new Error(`Project name does not slugify cleanly: ${flags.project ?? basename(repoPath)} — pass --project`);
+    }
+    const flagScope = flags.scope === undefined ? "" : flags.scope;
+    const byProject = config.codeMap?.repos.find((repo) => repo.project === project);
+    const byTarget = config.codeMap?.repos.find((repo) => repo.path === repoPath && (repo.scope ?? "") === flagScope);
+    if (byProject !== undefined && (byProject.path !== repoPath || (byProject.scope ?? "") !== flagScope)) {
+        throw new Error(`Project ${project} is already registered for ${byProject.path} — pass a different --project`);
+    }
+    if (byTarget !== undefined && byTarget.project !== project) {
+        throw new Error(`Repo is already registered as project ${byTarget.project}`);
+    }
+    const registered = byProject ?? byTarget;
+    const repo = {
+        ...(flags.maxModules !== undefined
+            ? { maxModules: flags.maxModules }
+            : registered?.maxModules === undefined
+                ? {}
+                : { maxModules: registered.maxModules }),
+        ...(registered?.modules === undefined ? {} : { modules: registered.modules }),
+        path: repoPath,
+        project,
+        ...(flags.scope !== undefined
+            ? { scope: flags.scope }
+            : registered?.scope === undefined
+                ? {}
+                : { scope: registered.scope })
+    };
+    const vaultPaths = resolveVaultPaths(config.vaultRoot);
+    // Same lock as the hourly job — map must never interleave with it.
+    const lock = await acquireLock(vaultPaths.lockPath);
+    try {
+        // 1. Capture. Read-before-write: a git failure aborts before any write,
+        // so a typo'd path leaves the vault byte-identical (design 6.1).
+        const captureSummary = await captureRepo({
+            date: dependencies.now().toISOString().slice(0, 10),
+            globalMaxModules: config.codeMap?.maxModules ?? DEFAULT_MAX_MODULES,
+            rawCodeRoot: vaultPaths.rawCodeRoot,
+            repo
+        }, defaultCaptureDependencies(repoPath));
+        dependencies.log(`captured ${repo.project}: written=${captureSummary.evidenceWritten}, unchanged=${captureSummary.evidenceUnchanged}, modules=${captureSummary.moduleCount}`);
+        // 2. Registration after a successful capture (design 7).
+        if (registered === undefined) {
+            await registerRepo(configPath, {
+                ...(flags.maxModules === undefined ? {} : { maxModules: flags.maxModules }),
+                path: repoPath,
+                project,
+                ...(flags.scope === undefined ? {} : { scope: flags.scope })
+            });
+            dependencies.log(`registered ${project} in ${configPath}`);
+        }
+        // 3. --force: clear this project's code:* manifest entries so every page
+        // re-renders (decoded-segment matching, design 7).
+        if (flags.force) {
+            const manifest = await loadManifest(vaultPaths.manifestPath);
+            await saveManifest(vaultPaths.manifestPath, stripCodeManifestEntries(manifest, project));
+            dependencies.log(`cleared code manifest entries for ${project}`);
+        }
+        // 4. Immediate ingest so pages exist right away.
+        const models = config.codeMap?.models ?? { pages: "haiku", structure: "sonnet" };
+        const backend = resolveCodeMapBackend(config.synthesis.backend, () => createCliClaudeCodeMapBackend({
+            ...(config.synthesis.claudeBin === undefined
+                ? {}
+                : { claudeBin: config.synthesis.claudeBin }),
+            logsRoot: config.logsRoot,
+            models
+        }));
+        if (backend === undefined) {
+            dependencies.log("synthesis backend is noop — evidence captured; pages will render once a backend is configured");
+            return;
+        }
+        const reportWriter = createReportWriter({
+            now: dependencies.now,
+            reportsRoot: vaultPaths.reportsRoot,
+            runKind: "manual",
+            vaultRoot: vaultPaths.vaultDir
+        });
+        const summary = await runCodeMapIngest({
+            backend,
+            evidenceCaptured: captureSummary.evidenceWritten,
+            indexPath: vaultPaths.indexPath,
+            logPath: vaultPaths.wikiLogPath,
+            manifestPath: vaultPaths.manifestPath,
+            now: dependencies.now,
+            rawCodeRoot: vaultPaths.rawCodeRoot,
+            reportWriter,
+            wikiCodeRoot: vaultPaths.wikiCodeRoot
+        });
+        dependencies.log(`pages rendered: ${summary.pagesRendered.length}, pruned: ${summary.pagesPruned.length}, failures: ${summary.failures.length}`);
+        for (const failure of summary.failures) {
+            dependencies.log(`failed: ${failure.project} — ${failure.reason}`);
+        }
+        if (summary.failures.length > 0) {
+            process.exitCode = 1;
+        }
+    }
+    finally {
+        await lock.release();
+    }
+}
+// Registration edits the RAW config file (not the resolved view) so user
+// formatting conventions like relative provider paths survive untouched.
+async function registerRepo(configPath, entry) {
+    const raw = JSON.parse(await readFile(configPath, "utf8"));
+    const codeMap = typeof raw.codeMap === "object" && raw.codeMap !== null
+        ? raw.codeMap
+        : {};
+    const repos = Array.isArray(codeMap.repos) ? codeMap.repos : [];
+    await writeFileAtomic(configPath, `${JSON.stringify({ ...raw, codeMap: { ...codeMap, repos: [...repos, entry] } }, null, 2)}\n`);
+}

package/dist/report.js

@@ -21,6 +21,7 @@ export function createReportWriter(input) {
             state.reportPath ??
                 (await claimReportPath(input.reportsRoot, createdAt, input.runKind));
         const content = await buildReportContent({
+            codeMap: state.codeMap,
             consolidation: state.consolidation,
             createdAt,
             ingest: state.ingest,
@@ -42,6 +43,10 @@ export function createReportWriter(input) {
         };
     };
     return {
+        addCodeMap: async (data) => {
+            state.codeMap = data;
+            return write();
+        },
         addConsolidation: async (data) => {
             state.consolidation = data;
             return write();
@@ -58,6 +63,9 @@ async function buildReportContent(input) {
     if (input.ingest) {
         lines.push(`transcripts_added: ${input.ingest.transcriptsAdded.length}`, `transcripts_changed: ${input.ingest.transcriptsChanged.length}`, `artifacts_ingested: ${input.ingest.artifacts.length}`, `episodes_created: ${input.ingest.episodes.length}`, `ingest_failures: ${input.ingest.failures.length}`, `artifacts_quarantined: ${input.ingest.quarantined.length}`);
     }
+    if (input.codeMap) {
+        lines.push(`code_evidence_captured: ${input.codeMap.evidenceCaptured}`, `code_pages_rendered: ${input.codeMap.pagesRendered.length}`, `code_pages_pruned: ${input.codeMap.pagesPruned.length}`, `code_failures: ${input.codeMap.failures.length}`);
+    }
     if (input.consolidation) {
         lines.push(`pages_created: ${input.consolidation.pagesCreated.length}`, `pages_updated: ${input.consolidation.pagesUpdated.length}`, `episodes_consolidated: ${input.consolidation.episodesConsolidated}`, `consolidation_failures: ${input.consolidation.failures.length}`, `episodes_quarantined: ${input.consolidation.quarantined.length}`);
     }
@@ -66,6 +74,9 @@ async function buildReportContent(input) {
     if (input.ingest) {
         lines.push("", ...(await buildIngestSection(input.ingest, input.vaultRoot)));
     }
+    if (input.codeMap) {
+        lines.push("", ...buildCodeMapSection(input.codeMap));
+    }
     if (input.consolidation) {
         lines.push("", ...buildConsolidationSection(input.consolidation));
     }
@@ -121,6 +132,29 @@ async function buildIngestSection(data, vaultRoot) {
     }
     return lines;
 }
+function buildCodeMapSection(data) {
+    const lines = ["## Code map", ""];
+    lines.push(`Evidence files captured: ${data.evidenceCaptured}`);
+    if (data.pagesRendered.length > 0) {
+        lines.push(`Pages rendered: ${data.pagesRendered.map((page) => `[[code/${page}]]`).join(", ")}`);
+    }
+    if (data.pagesPruned.length > 0) {
+        lines.push(`Pages pruned: ${data.pagesPruned.map((page) => `\`code/${page}\``).join(", ")}`);
+    }
+    if (data.failures.length > 0) {
+        lines.push("", "### Failures", "");
+        for (const failure of data.failures) {
+            lines.push(`- ${failure.project} — ${failure.reason}`);
+        }
+    }
+    if (data.quarantined.length > 0) {
+        lines.push("", "### Quarantined evidence", "");
+        for (const entry of data.quarantined) {
+            lines.push(`- \`${entry.path}\` — ${entry.reason}`);
+        }
+    }
+    return lines;
+}
 function buildConsolidationSection(data) {
     const lines = ["## Consolidation", ""];
     if (data.pagesCreated.length > 0) {

package/dist/shell.js

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 export async function runCommand(command, args, cwd, env) {
@@ -40,6 +40,60 @@ export async function runCommandAllowFailure(command, args, cwd) {
         };
     }
 }
+// execFile cannot feed stdin; the code-map backend pipes prompts that exceed
+// OS argv limits, so this spawn-based variant exists alongside it.
+export async function runCommandWithInput(command, args, cwd, input) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(command, [...args], { cwd });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const settle = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (result instanceof Error) {
+                rejectPromise(result);
+            }
+            else {
+                resolvePromise(result);
+            }
+        };
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            settle(new Error(buildCommandError(command, args, {
+                code: error.code,
+                message: error.message,
+                stderr,
+                stdout
+            })));
+        });
+        child.on("close", (code, signal) => {
+            if (code === 0) {
+                settle({ stderr, stdout });
+                return;
+            }
+            settle(new Error(buildCommandError(command, args, {
+                ...(code === null ? {} : { code }),
+                ...(signal === null ? {} : { signal }),
+                stderr,
+                stdout
+            })));
+        });
+        // A child that exits before draining stdin raises EPIPE here; the close
+        // handler already carries the real outcome.
+        child.stdin.on("error", () => undefined);
+        child.stdin.end(input);
+    });
+}
 // Long prompts are passed as argv: echoing them whole made failure reasons
 // unreadable, while the actual diagnostic (exit code, spawn error, stream
 // tails) was missing entirely.

package/dist/vault-paths.js

@@ -0,0 +1,23 @@
+import { join, resolve, sep } from "node:path";
+export function resolveVaultPaths(vaultRoot) {
+    // Defense-in-depth (design 7.6): the prune scope must stay confined to
+    // raw/projects, so a hand-edited config cannot point ingest at a stray tree.
+    const normalized = resolve(vaultRoot);
+    if (!normalized.endsWith(join(`${sep}raw`, "projects"))) {
+        throw new Error(`vaultRoot must end in raw/projects to run ingest, got: ${vaultRoot}`);
+    }
+    const vault = resolve(normalized, "..", "..");
+    return {
+        artifactsRoot: join(vault, "raw", "artifacts"),
+        episodesRoot: join(vault, "wiki", "episodes"),
+        indexPath: join(vault, "wiki", "index.md"),
+        lockPath: join(vault, "wiki", ".ingest.lock"),
+        manifestPath: join(vault, "wiki", ".ingest-state.json"),
+        rawCodeRoot: join(vault, "raw", "code"),
+        reportsRoot: join(vault, "wiki", "reports"),
+        vaultDir: vault,
+        wikiCodeRoot: join(vault, "wiki", "code"),
+        wikiLogPath: join(vault, "wiki", "log.md"),
+        wikiRoot: join(vault, "wiki")
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-second-brain",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Turn an Obsidian vault into a self-maintaining second brain for AI coding sessions",
   "license": "MIT",
   "files": [
@@ -28,7 +28,7 @@
     "sync": "tsx src/cli.ts",
     "test": "tsx --test tests/**/*.test.ts",
     "coverage": "tsx --test --experimental-test-coverage tests/**/*.test.ts",
-    "e2e": "npm run build && tsx --test tests/e2e/cli.e2e.ts tests/e2e/lifecycle.e2e.ts tests/e2e/claude-smoke.e2e.ts"
+    "e2e": "npm run build && tsx --test tests/e2e/cli.e2e.ts tests/e2e/lifecycle.e2e.ts tests/e2e/code-map.e2e.ts tests/e2e/claude-smoke.e2e.ts"
   },
   "dependencies": {
     "zod": "^4.1.12"