obsidian-second-brain 0.1.0

package/dist/sync.js

@@ -0,0 +1,103 @@
+import { copyFile, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { hashRenderedBody } from "./changeset.js";
+import { cleanupEmptyDirectories, collectFiles, ensureDirectory, ensureWritableFilePath, removePathEntry } from "./filesystem.js";
+import { renderClaudeJsonlToMarkdown } from "./render-claude-jsonl.js";
+import { renderJsonlToMarkdown } from "./render-jsonl-markdown.js";
+export async function syncProviderTree(input) {
+    await ensureDirectory(input.destinationRoot);
+    const sourceFiles = await collectFiles(input.sourceRoot);
+    const expectedDestinationFiles = collectExpectedDestinationFiles(sourceFiles);
+    const renderedFiles = [];
+    let copiedFiles = 0;
+    let renderedMarkdownFiles = 0;
+    for (const sourceFile of sourceFiles) {
+        const destinationRelativePath = mapSourceToDestinationPath(sourceFile.relativePath);
+        const destinationPath = join(input.destinationRoot, destinationRelativePath);
+        await ensureDirectory(dirname(destinationPath));
+        await ensureWritableFilePath(destinationPath);
+        if (sourceFile.relativePath.endsWith(".jsonl")) {
+            const sourceContent = await readFile(sourceFile.absolutePath, "utf8");
+            const rendered = input.providerName === "claude"
+                ? renderClaudeJsonlToMarkdown({
+                    generatedAt: input.generatedAt,
+                    relativePath: sourceFile.relativePath,
+                    sourceContent
+                })
+                : renderJsonlToMarkdown({
+                    generatedAt: input.generatedAt,
+                    providerName: input.providerName,
+                    relativePath: sourceFile.relativePath,
+                    sourceContent
+                });
+            renderedFiles.push(toRenderedFile({
+                destinationPath,
+                markdown: rendered.markdown,
+                metadata: rendered.metadata,
+                providerName: input.providerName,
+                relativePath: sourceFile.relativePath,
+                sourcePath: sourceFile.absolutePath
+            }));
+            await writeFile(destinationPath, rendered.markdown);
+            renderedMarkdownFiles += 1;
+            continue;
+        }
+        await copyFile(sourceFile.absolutePath, destinationPath);
+        copiedFiles += 1;
+    }
+    const destinationFiles = await collectFiles(input.destinationRoot);
+    let deletedFiles = 0;
+    for (const destinationFile of destinationFiles) {
+        if (expectedDestinationFiles.has(destinationFile.relativePath)) {
+            continue;
+        }
+        await removePathEntry(destinationFile.absolutePath);
+        deletedFiles += 1;
+    }
+    await cleanupEmptyDirectories(input.destinationRoot);
+    return {
+        copiedFiles,
+        deletedFiles,
+        renderedFiles,
+        renderedMarkdownFiles
+    };
+}
+function toRenderedFile(input) {
+    // The relative path is the only per-file-unique identity: subagent
+    // transcripts carry the PARENT sessionId in their events (611 of 686 real
+    // files) and workflow journals all share the basename journal.jsonl, so
+    // neither field converges as a key. Transcripts are track-only (no
+    // synthesis), so a rename merely re-tracks the file at zero cost.
+    const sessionId = input.relativePath.replace(/\.jsonl$/u, "");
+    const segments = input.relativePath.split(/[\\/]/u);
+    const firstSegment = segments.length > 1 ? segments[0] : undefined;
+    const project = input.metadata.cwd
+        ? basename(input.metadata.cwd)
+        : firstSegment ?? "unknown";
+    return {
+        contentHash: hashRenderedBody(input.markdown),
+        destinationPath: input.destinationPath,
+        project,
+        providerName: input.providerName,
+        sessionId,
+        sessionStartedAt: input.metadata.sessionStartedAt,
+        sourcePath: input.sourcePath
+    };
+}
+function mapSourceToDestinationPath(relativePath) {
+    if (relativePath.endsWith(".jsonl")) {
+        return relativePath.replace(/\.jsonl$/u, ".md");
+    }
+    return relativePath;
+}
+function collectExpectedDestinationFiles(sourceFiles) {
+    const expectedDestinationFiles = new Set();
+    for (const sourceFile of sourceFiles) {
+        const destinationRelativePath = mapSourceToDestinationPath(sourceFile.relativePath);
+        if (expectedDestinationFiles.has(destinationRelativePath)) {
+            throw new Error(`Destination path collision: ${destinationRelativePath}`);
+        }
+        expectedDestinationFiles.add(destinationRelativePath);
+    }
+    return expectedDestinationFiles;
+}

package/dist/synthesis.js

@@ -0,0 +1,14 @@
+export const noopBackend = {
+    name: "noop",
+    synthesize: async () => ({ episodes: [] })
+};
+export function resolveBackend(name, backends = {}) {
+    if (name === "noop") {
+        return noopBackend;
+    }
+    const backend = backends[name];
+    if (backend !== undefined) {
+        return backend;
+    }
+    throw new Error(`Unknown synthesis backend: ${name} (available: noop, cli-claude, ollama)`);
+}

package/dist/uninstall.js

@@ -0,0 +1,80 @@
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { writeFileAtomic } from "./filesystem.js";
+import { HOURLY_LABEL, installManifestPath, WEEKLY_LABEL } from "./init.js";
+import { isUnchangedInstalledFile, loadInstallManifest } from "./install-manifest.js";
+import { hasManagedSection, removeManagedSection } from "./managed-section.js";
+import { removeLaunchdJob } from "./plist.js";
+export async function runUninstall(options, dependencies) {
+    const manifest = await loadInstallManifest(installManifestPath(dependencies.appDir));
+    const removed = [];
+    const warnings = [];
+    // 1. launchd jobs: bootout always; the plist files go through the same
+    // manifest-unchanged rule as every other generated file.
+    for (const label of [HOURLY_LABEL, WEEKLY_LABEL]) {
+        await removeLaunchdJob({
+            exec: dependencies.exec,
+            label,
+            launchAgentsDir: dependencies.launchAgentsDir,
+            removeFile: async (path) => {
+                await removeIfUnchanged(path, manifest, removed, warnings);
+            },
+            uid: dependencies.uid
+        });
+    }
+    // 2. Managed CLAUDE.md section (by markers — the rest of the file is the
+    // user's).
+    await removeSectionFromClaudeMd(join(options.claudeDir, "CLAUDE.md"), removed, warnings);
+    // 3. Every other manifest-listed generated file (wrap command, config).
+    for (const filePath of Object.keys(manifest.files)) {
+        if (removed.includes(filePath)) {
+            continue;
+        }
+        await removeIfUnchanged(filePath, manifest, removed, warnings);
+    }
+    // 4. The install manifest itself. Vault content (raw/, wiki/, .git) is
+    // deliberately retained — it is the user's data and audit trail.
+    await rm(installManifestPath(dependencies.appDir), { force: true });
+    for (const warning of warnings) {
+        dependencies.log(`warning: ${warning}`);
+    }
+    return { removed, warnings };
+}
+async function removeIfUnchanged(filePath, manifest, removed, warnings) {
+    if (manifest.files[filePath] === undefined) {
+        return;
+    }
+    if (await isUnchangedInstalledFile(manifest, filePath)) {
+        await rm(filePath, { force: true });
+        removed.push(filePath);
+        return;
+    }
+    try {
+        await readFile(filePath, "utf8");
+        warnings.push(`kept ${filePath} — modified since install`);
+    }
+    catch {
+        // Already gone; nothing to do.
+    }
+}
+async function removeSectionFromClaudeMd(claudeMdPath, removed, warnings) {
+    let existing;
+    try {
+        existing = await readFile(claudeMdPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (!hasManagedSection(existing)) {
+        return;
+    }
+    const next = removeManagedSection(existing);
+    if (next.length === 0) {
+        await rm(claudeMdPath, { force: true });
+        removed.push(claudeMdPath);
+        return;
+    }
+    await writeFileAtomic(claudeMdPath, next);
+    removed.push(`${claudeMdPath} (managed section)`);
+    warnings.push(`${claudeMdPath} kept — only the managed section was removed`);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "obsidian-second-brain",
+  "version": "0.1.0",
+  "description": "Turn an Obsidian vault into a self-maintaining second brain for AI coding sessions",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "templates",
+    "config/projects.example.json"
+  ],
+  "author": "Minh Nhat Hoang <hoangminhnhat08@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/minhnhat08/second-brain.git"
+  },
+  "homepage": "https://github.com/minhnhat08/second-brain#readme",
+  "bugs": {
+    "url": "https://github.com/minhnhat08/second-brain/issues"
+  },
+  "type": "module",
+  "bin": {
+    "second-brain": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "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"
+  },
+  "dependencies": {
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/claude-md-section.md

@@ -0,0 +1,12 @@
+<!-- BEGIN second-brain (managed by second-brain init — do not edit inside) -->
+At the end of any significant task, offer /wrap. /wrap writes
+{{VAULT}}/raw/artifacts/<project>/YYYY-MM-DD-<task>.<session_id>.{plan,output}.md
+with frontmatter (project, task, type, session_id, date).
+
+Second-brain retrieval: when the repository alone cannot answer — prior
+decisions and their rationale, how projects relate, "did a past session
+already solve this" — read {{VAULT}}/wiki/index.md and follow only the
+relevant links (entity pages in wiki/, recent activity in wiki/episodes/
+and wiki/reports/). The wiki records history; the repository is the source
+of truth for current implementation — when they disagree, trust the code.
+<!-- END second-brain -->

package/templates/launchd-weekly.plist.template

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.second-brain.weekly</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{NODE_PATH}}</string>
+    <string>{{BIN_PATH}}</string>
+    <string>sync</string>
+    <string>--all</string>
+    <string>--consolidate</string>
+    <string>--run</string>
+    <string>weekly</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>{{APP_DIR}}</string>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>0</integer>
+    <key>Hour</key>
+    <integer>9</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+  <key>RunAtLoad</key>
+  <false/>
+  <key>StandardOutPath</key>
+  <string>/tmp/second-brain-weekly.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/second-brain-weekly.stderr.log</string>
+</dict>
+</plist>

package/templates/launchd.plist.template

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.second-brain.hourly</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{NODE_PATH}}</string>
+    <string>{{BIN_PATH}}</string>
+    <string>sync</string>
+    <string>--all</string>
+    <string>--ingest</string>
+    <string>--run</string>
+    <string>hourly</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>{{APP_DIR}}</string>
+  <key>StartInterval</key>
+  <integer>3600</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/second-brain.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/second-brain.stderr.log</string>
+</dict>
+</plist>

package/templates/vault-agents.md

@@ -0,0 +1,124 @@
+# LLM Wiki Schema
+
+This is a personal knowledge base maintained by an LLM. The human curates sources and directs analysis. The LLM handles all writing, cross-referencing, and maintenance.
+
+## Directory Structure
+
+```
+raw/                      # Immutable source documents
+raw/projects/sessions/    # Mirrored AI session transcripts — machine-managed archive
+raw/artifacts/            # Curated task artifacts written by /wrap (plan + output per task)
+wiki/                     # LLM-generated and maintained markdown pages
+wiki/index.md             # Content catalog — entity/concept pages listed with summaries
+wiki/log.md               # Chronological record of all operations
+wiki/episodes/            # Quarantined episodic notes from the automated hourly ingest
+wiki/.ingest-state.json   # Ingest manifest (idempotency watermark) — pipeline-owned, never hand-edit
+```
+
+## Conventions
+
+- All wiki pages use `[[wikilinks]]` for cross-references (Obsidian style)
+- Page filenames: kebab-case, descriptive
+- Every wiki page has YAML frontmatter:
+
+```yaml
+---
+title: Page Title
+type: entity | concept | source-summary | synthesis | comparison | analysis
+tags: [relevant, tags]
+sources: [source-filename.md]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+### Page Types
+
+- **source-summary**: Summary of a single raw source. One per source file.
+- **entity**: A person, organization, tool, place, or other named thing.
+- **concept**: An idea, theory, methodology, or abstract topic.
+- **synthesis**: A page that draws together multiple sources/concepts into an argument or narrative.
+- **comparison**: Side-by-side analysis of two or more entities/concepts.
+- **analysis**: An answer to a specific question, filed for future reference.
+
+## Automated Ingest Rules
+
+These rules bind every ingest run — automated (hourly/weekly pipeline) or manual. They exist to prevent silent corruption of trusted pages.
+
+### Canonical-name resolution
+
+Before creating any entity or concept page, resolve the canonical name first:
+
+1. Search `wiki/index.md` and existing page frontmatter for the same real-world thing under alternative spellings, abbreviations, and aliases.
+2. If a page already exists under another name, update that page — never create a duplicate.
+3. New page names: kebab-case, the most specific commonly-used name. Record known aliases in frontmatter (`aliases: [...]`).
+
+### Additive edits only
+
+- Update pages by adding dated sections or appending to existing sections — never rewrite a page wholesale.
+- Never delete prior content. When new information supersedes old, add the correction, mark the old claim explicitly, and keep both.
+- Episodic notes from the hourly pass land only in `wiki/episodes/` — they never touch trusted entity/concept pages directly. Only the weekly consolidation pass may edit stable pages.
+
+### Index scope
+
+`wiki/index.md` indexes entity, concept, synthesis, comparison, and analysis pages only. Never index individual session transcripts — they are archive material, reachable from project pages via source links.
+
+### Write order (transactional)
+
+Every ingest run writes in this exact order:
+
+1. Wiki pages (entity/concept/episode pages)
+2. `wiki/index.md`
+3. `wiki/log.md`
+4. `wiki/.ingest-state.json` (manifest — last; advancing it commits the run)
+
+A crash before step 4 leaves the run fully replayable. Never hand-edit `.ingest-state.json`.
+
+## Workflows
+
+### Query
+
+When the user asks a question:
+
+1. Read `wiki/index.md` to identify relevant pages.
+2. Read the relevant pages.
+3. If needed, read raw sources for additional detail.
+4. Synthesize an answer with `[[wikilinks]]` to referenced pages.
+5. If the answer is substantial and reusable, offer to file it as an `analysis` or `synthesis` page.
+6. If filed, update `wiki/index.md` and append to `wiki/log.md`.
+
+### Lint
+
+When the user asks to health-check the wiki:
+
+1. Check for contradictions between pages.
+2. Find stale claims superseded by newer sources.
+3. Identify orphan pages (no inbound links).
+4. Flag concepts mentioned but lacking their own page.
+5. Suggest missing cross-references.
+6. Report findings and fix issues with user approval.
+7. Append a lint entry to `wiki/log.md`.
+
+## Index Format (wiki/index.md)
+
+Organized by page type. Each entry: `- [[page-name]] — one-line summary (N sources)`
+
+## Log Format (wiki/log.md)
+
+Each entry:
+
+```
+## [YYYY-MM-DD] operation | Subject
+Brief description of what was done.
+Pages created: [[page1]], [[page2]]
+Pages updated: [[page3]]
+```
+
+## Guidelines
+
+- Never modify files in `raw/`. They are immutable source material.
+- Always maintain bidirectional links — if A links to B, B should link back to A.
+- When new information contradicts existing wiki content, note the contradiction explicitly and cite both sources.
+- Prefer updating existing pages over creating new ones when the topic overlaps.
+- Keep summaries concise. Link to source for full detail.
+- Use Obsidian-compatible markdown (callouts, wikilinks, tags, footnotes).

package/templates/vault-claude-md.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/vault-gitignore

@@ -0,0 +1,12 @@
+# OS noise
+.DS_Store
+
+# Obsidian volatile state
+.obsidian/workspace*
+
+# Obsidian trash
+.trash/
+
+# Mirrored session transcripts: machine-managed, regenerable by re-running
+# sync, and rewritten with a fresh generated_at every hourly run.
+raw/projects/

package/templates/wiki-index.md

@@ -0,0 +1,7 @@
+# Wiki Index
+
+## Source Summaries
+
+## Entities
+
+## Concepts

package/templates/wiki-log.md

@@ -0,0 +1 @@
+# Ingest Log

package/templates/wrap-command.md

@@ -0,0 +1,99 @@
+---
+description: Capture the just-finished task into the second-brain vault as curated plan + output artifacts
+argument-hint: [short-task-slug]
+allowed-tools: Read, Write, Bash(git rev-parse:*), Bash(date:*), Bash(ls:*), Bash(test:*), Bash(mkdir:*), Bash(mv:*)
+---
+
+# /wrap — capture task artifacts into the vault
+
+You just finished a task in this session and still hold its full context. Distill it
+into two small, high-signal artifact files written directly into the Obsidian vault.
+These artifacts are the primary input for the vault's automated wiki ingest — write
+clean, intentional summaries, never a transcript dump.
+
+## Fixed install paths
+
+- Artifacts root: `{{VAULT}}/raw/artifacts`
+
+## Pre-computed context
+
+- Project root (git toplevel, falls back to cwd): !`git rev-parse --show-toplevel 2>/dev/null || pwd`
+- Today: !`date +%Y-%m-%d`
+- Session ID: ${CLAUDE_SESSION_ID}
+
+## Metadata rules
+
+1. `project` = basename of the project root above. If the session is not inside any
+   real project directory (home dir, /tmp, filesystem root), use the reserved
+   constant `_inbox` — a fixed literal, never derived from repo content. It bypasses
+   slugification and is the only segment allowed to start with `_`.
+2. `task` = $ARGUMENTS if non-empty, else a short slug derived from the task just
+   completed.
+3. `session_id` = the Session ID above. If it is empty, use the basename (minus
+   `.jsonl`) of the most recently modified transcript in
+   `~/.claude/projects/<slugified-cwd>/`.
+4. `date` = today (above).
+
+## Validation — mandatory before any write
+
+Slugify `project` and `task`: lowercase, replace whitespace and `_` with `-`, drop
+every character outside `[a-z0-9-]`, collapse repeated `-`, trim leading/trailing `-`.
+After slugification both MUST match `^[a-z0-9][a-z0-9-]*$`; if either is empty,
+abort and tell the user what failed. Never accept `.`, `..`, `/`, or `\` inside a
+segment — these rules guard against prompt-injected path escapes from repo content.
+Sole exception: the reserved fallback `_inbox` is used verbatim and skips the slug
+pipeline (it is a fixed constant, not agent-derived input).
+
+## Path containment — run immediately before each write
+
+1. `mkdir -p` the project directory `<artifacts-root>/<project>/` first.
+2. Canonicalize and compare: `root="$(realpath "<artifacts-root>")"` and
+   `dir="$(realpath "<artifacts-root>/<project>")"`. Require exactly
+   `dir == root + "/" + project`. If `realpath` fails or the prefix differs, abort.
+3. `test -L` every path component from the vault root down to the project directory
+   (vault, `raw`, `artifacts`, `<project>`) — refuse if ANY component is a symlink.
+4. Immediately before each Write: the exact `.tmp-` path and the final path must
+   both be absent and must not be symlinks (`test -e` / `test -L`). Re-run the
+   `test -L` check on the final path right before the `mv`.
+5. These prose checks cannot fully close TOCTOU races; the ingest pipeline
+   independently re-validates every path it reads — that is the backstop. On ANY
+   anomaly, refuse and report instead of working around it.
+
+## Files to write
+
+```
+<artifacts-root>/<project>/<date>-<task>.<session_id>.plan.md
+<artifacts-root>/<project>/<date>-<task>.<session_id>.output.md
+```
+
+Both with this frontmatter (English, no emojis):
+
+```yaml
+---
+project: <project>
+task: <one-line human-readable task description>
+type: plan        # or: output
+session_id: <session_id>
+date: <date>
+---
+```
+
+- `plan.md` — the intent: what was asked, the approach chosen, decisions made and
+  why, alternatives rejected, constraints discovered.
+- `output.md` — the result: what actually changed (files, commits, configs), how it
+  was verified, gotchas hit, follow-ups left open.
+
+Keep each file under ~120 lines. Write for a future reader with zero session
+context. Use `[[wikilinks]]` only for project-specific entities likely to have wiki
+pages; plain `[text](url)` links for well-known technologies.
+
+## Write procedure
+
+1. `mkdir -p` the project directory under the artifacts root.
+2. Write each file atomically: write to `<dir>/.tmp-<final-name>` with the Write
+   tool, then `mv` it to the final name.
+3. Never overwrite an existing artifact: if a final path already exists, append a
+   `-2` (then `-3`, ...) suffix to the task slug and retry.
+4. Touch nothing else in the vault — no `wiki/` edits, no other files. The ingest
+   pipeline owns the wiki.
+5. Report the two final paths to the user.