@m16khb/llm-wiki 0.1.0 → 0.1.2

package/internal/wiki/cleanup_test.go

@@ -0,0 +1,450 @@
+package wiki
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+	"unicode/utf8"
+)
+
+func TestCleanupRepositoryReferencesDryRunDoesNotModifyVault(t *testing.T) {
+	root := t.TempDir()
+	writeRepositoryReferenceFixture(t, root)
+	v := newTestVault(t, root)
+	v.Now = func() time.Time { return time.Date(2026, 5, 23, 12, 0, 0, 0, time.UTC) }
+
+	result, err := v.CleanupRepositoryReferences(RepositoryReferenceCleanupOptions{})
+	if err != nil {
+		t.Fatalf("CleanupRepositoryReferences() dry-run error = %v", err)
+	}
+	if result.Applied {
+		t.Fatalf("dry-run should not be applied: %+v", result)
+	}
+	if len(result.Bundles) != 1 {
+		t.Fatalf("expected one planned bundle, got %+v", result.Bundles)
+	}
+	bundle := result.Bundles[0]
+	if bundle.Repository != "sample-repo" || bundle.BundlePath != "20-wiki/concepts/repository-references/sample-repo/sample-repo-reference-bundle-2026-05-23.md" {
+		t.Fatalf("unexpected bundle plan: %+v", bundle)
+	}
+	if _, err := os.Stat(filepath.Join(root, filepath.FromSlash(bundle.BundlePath))); !os.IsNotExist(err) {
+		t.Fatalf("dry-run should not create bundle, stat err=%v", err)
+	}
+	if _, err := os.Stat(filepath.Join(root, "20-wiki/concepts/repository-references/sample-repo/sample-repo-go-rules-2026-05-22.md")); err != nil {
+		t.Fatalf("dry-run should leave fragment in place: %v", err)
+	}
+}
+
+func TestCleanupRepositoryReferencesApplyBundlesArchivesAndRewritesLinks(t *testing.T) {
+	root := t.TempDir()
+	writeRepositoryReferenceFixture(t, root)
+	v := newTestVault(t, root)
+	v.Now = func() time.Time { return time.Date(2026, 5, 23, 12, 0, 0, 0, time.UTC) }
+
+	result, err := v.CleanupRepositoryReferences(RepositoryReferenceCleanupOptions{Apply: true})
+	if err != nil {
+		t.Fatalf("CleanupRepositoryReferences() apply error = %v", err)
+	}
+	if !result.Applied {
+		t.Fatalf("expected apply result: %+v", result)
+	}
+	if len(result.Bundles) != 1 {
+		t.Fatalf("expected one bundle, got %+v", result.Bundles)
+	}
+	bundle := result.Bundles[0]
+	if len(bundle.FragmentPaths) != 2 || len(bundle.ArchivedPaths) != 2 {
+		t.Fatalf("expected two fragments archived, got %+v", bundle)
+	}
+
+	bundleData := readTestFile(t, root, bundle.BundlePath)
+	for _, want := range []string{
+		"title: \"Sample Repo Reference Bundle 2026-05-23\"",
+		"Consolidated on 2026-05-23 from 2 repository-reference fragments.",
+		"Go Rules",
+		"Swagger Rules",
+		"repo-source-card",
+		"_archive/repository-reference-fragments-2026-05-23/sample-repo/archived-sample-repo-go-rules-2026-05-22.md",
+	} {
+		if !strings.Contains(bundleData, want) {
+			t.Fatalf("bundle missing %q:\n%s", want, bundleData)
+		}
+	}
+	if strings.Contains(bundleData, "[[repo-source-card]]") {
+		t.Fatalf("bundle summary should sanitize wikilinks to plain text:\n%s", bundleData)
+	}
+
+	for _, oldPath := range bundle.FragmentPaths {
+		if _, err := os.Stat(filepath.Join(root, filepath.FromSlash(oldPath))); !os.IsNotExist(err) {
+			t.Fatalf("expected original fragment archived away %s, stat err=%v", oldPath, err)
+		}
+	}
+	archiveData := readTestFile(t, root, "_archive/repository-reference-fragments-2026-05-23/sample-repo/archived-sample-repo-go-rules-2026-05-22.md")
+	if !strings.Contains(archiveData, "status: archived") || !strings.Contains(archiveData, "[[sample-repo-reference-bundle-2026-05-23]]") {
+		t.Fatalf("archived fragment should point at bundle:\n%s", archiveData)
+	}
+
+	consumerData := readTestFile(t, root, "20-wiki/concepts/consumer.md")
+	if !strings.Contains(consumerData, "[[sample-repo-reference-bundle-2026-05-23]]") ||
+		!strings.Contains(consumerData, "[[sample-repo-reference-bundle-2026-05-23|swagger]]") ||
+		strings.Contains(consumerData, "sample-repo-go-rules-2026-05-22") {
+		t.Fatalf("consumer links were not rewritten:\n%s", consumerData)
+	}
+
+	indexData := readTestFile(t, root, "00-meta/index.md")
+	if !strings.Contains(indexData, "[[sample-repo-reference-bundle-2026-05-23]]") ||
+		strings.Contains(indexData, "sample-repo-swagger-rules-2026-05-22") {
+		t.Fatalf("index was not collapsed to bundle:\n%s", indexData)
+	}
+	if strings.Contains(indexData, "[[sample-repo-reference-bundle-2026-05-23]], [[sample-repo-reference-bundle-2026-05-23]]") {
+		t.Fatalf("index should dedupe repeated bundle-only bullets:\n%s", indexData)
+	}
+	if strings.Count(indexData, "- [[sample-repo-reference-bundle-2026-05-23]]") != 3 {
+		t.Fatalf("expected canonical, bold-tech, and data index entries only:\n%s", indexData)
+	}
+
+	sourceData := readTestFile(t, root, "10-sources/source-card.md")
+	if strings.Contains(sourceData, "sample-repo-reference-bundle") {
+		t.Fatalf("10-sources body must remain read-only, got:\n%s", sourceData)
+	}
+
+	lint, err := v.Lint()
+	if err != nil {
+		t.Fatalf("Lint() after cleanup error = %v", err)
+	}
+	if !lint.OK {
+		t.Fatalf("expected clean lint after cleanup, got %+v", lint)
+	}
+}
+
+func TestCleanupSummarySanitizesWikilinksAndTruncatesUTF8Safely(t *testing.T) {
+	summary := summarizeMarkdownBody(testFrontmatter("Korean", "reference") + `
+# Korean
+
+한글 문장을 충분히 길게 반복해서 byte 기준 절단이 UTF-8을 깨지 않게 만든다. [[old-fragment|표시명]] ` + strings.Repeat("가나다라마바사 ", 80) + `
+`)
+	if !utf8.ValidString(summary) {
+		t.Fatalf("summary should remain valid UTF-8: %q", summary)
+	}
+	if strings.Contains(summary, "[[") || strings.Contains(summary, "]]") || strings.Contains(summary, "old-fragment") {
+		t.Fatalf("summary should sanitize wikilinks to labels/plain text: %s", summary)
+	}
+	if !strings.Contains(summary, "표시명") {
+		t.Fatalf("summary should keep wikilink label: %s", summary)
+	}
+}
+
+func TestCleanupDuplicateSlugsDryRunDoesNotModifyVault(t *testing.T) {
+	root := t.TempDir()
+	writeDuplicateSlugFixture(t, root)
+	v := newTestVault(t, root)
+	v.Now = func() time.Time { return time.Date(2026, 5, 23, 12, 0, 0, 0, time.UTC) }
+
+	result, err := v.CleanupDuplicateSlugs(DuplicateSlugCleanupOptions{})
+	if err != nil {
+		t.Fatalf("CleanupDuplicateSlugs() dry-run error = %v", err)
+	}
+	if result.Applied {
+		t.Fatalf("dry-run should not be applied: %+v", result)
+	}
+	if len(result.Renames) != 2 {
+		t.Fatalf("expected two planned renames, got %+v", result.Renames)
+	}
+	if result.Renames[0].CanonicalPath != "00-meta/index.md" || result.Renames[0].FromPath != "index.md" || result.Renames[0].ToPath != "root-compatibility-index.md" {
+		t.Fatalf("unexpected first rename: %+v", result.Renames[0])
+	}
+	if _, err := os.Stat(filepath.Join(root, "index.md")); err != nil {
+		t.Fatalf("dry-run should leave root index in place: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(root, "root-compatibility-index.md")); !os.IsNotExist(err) {
+		t.Fatalf("dry-run should not create renamed file, stat err=%v", err)
+	}
+}
+
+func TestCleanupDuplicateSlugsApplyRenamesCompatibilityPagesAndClearsLintWarnings(t *testing.T) {
+	root := t.TempDir()
+	writeDuplicateSlugFixture(t, root)
+	v := newTestVault(t, root)
+	v.Now = func() time.Time { return time.Date(2026, 5, 23, 12, 0, 0, 0, time.UTC) }
+
+	result, err := v.CleanupDuplicateSlugs(DuplicateSlugCleanupOptions{Apply: true})
+	if err != nil {
+		t.Fatalf("CleanupDuplicateSlugs() apply error = %v", err)
+	}
+	if !result.Applied {
+		t.Fatalf("expected apply result: %+v", result)
+	}
+	if len(result.Renames) != 2 {
+		t.Fatalf("expected two renames, got %+v", result.Renames)
+	}
+	for _, oldPath := range []string{"index.md", "log.md"} {
+		if _, err := os.Stat(filepath.Join(root, oldPath)); !os.IsNotExist(err) {
+			t.Fatalf("expected duplicate root file renamed away %s, stat err=%v", oldPath, err)
+		}
+	}
+	renamedIndex := readTestFile(t, root, "root-compatibility-index.md")
+	if !strings.Contains(renamedIndex, "Renamed by duplicate-slug cleanup on 2026-05-23") ||
+		!strings.Contains(renamedIndex, "Canonical page: [[index]]") {
+		t.Fatalf("renamed index should preserve content with canonical notice:\n%s", renamedIndex)
+	}
+	if !strings.Contains(readTestFile(t, root, "root-compatibility-log.md"), "Canonical page: [[log]]") {
+		t.Fatalf("renamed log should point to canonical log")
+	}
+	if len(result.ReportPaths) != 1 {
+		t.Fatalf("expected report path, got %+v", result.ReportPaths)
+	}
+	report := readTestFile(t, root, result.ReportPaths[0])
+	if !strings.Contains(report, "`index.md` → `root-compatibility-index.md`") ||
+		!strings.Contains(report, "`log.md` → `root-compatibility-log.md`") {
+		t.Fatalf("report should list renames:\n%s", report)
+	}
+	lint, err := v.Lint()
+	if err != nil {
+		t.Fatalf("Lint() after duplicate cleanup error = %v", err)
+	}
+	if !lint.OK || len(lint.DuplicateSlugs) != 0 || len(lint.Warnings) != 0 {
+		t.Fatalf("expected clean lint after duplicate cleanup, got %+v", lint)
+	}
+}
+
+func TestAnalyzeCleanupRepositoryReferencesBuildsLLMReviewPack(t *testing.T) {
+	root := t.TempDir()
+	writeRepositoryReferenceFixture(t, root)
+	v := newTestVault(t, root)
+	v.Now = func() time.Time { return time.Date(2026, 5, 23, 12, 0, 0, 0, time.UTC) }
+
+	analysis, err := v.AnalyzeCleanup(CleanupAnalyzeOptions{Scope: "repository-references"})
+	if err != nil {
+		t.Fatalf("AnalyzeCleanup() error = %v", err)
+	}
+	if analysis.Scope != "repository-references" || analysis.Date != "2026-05-23" {
+		t.Fatalf("unexpected analysis header: %+v", analysis)
+	}
+	if len(analysis.Candidates) != 1 {
+		t.Fatalf("expected one cleanup candidate, got %+v", analysis.Candidates)
+	}
+	candidate := analysis.Candidates[0]
+	if candidate.ID != "repository-references:sample-repo" || candidate.Kind != "repository-reference-bundle" {
+		t.Fatalf("unexpected candidate: %+v", candidate)
+	}
+	if candidate.RecommendedAction.Type != "run_scope" || candidate.RecommendedAction.Scope != "repository-references" {
+		t.Fatalf("candidate should recommend a guarded scope action: %+v", candidate.RecommendedAction)
+	}
+	if len(candidate.Files) != 3 {
+		t.Fatalf("candidate should include bundle plus two fragments, got %+v", candidate.Files)
+	}
+	if len(analysis.LLMInstructions) == 0 || !strings.Contains(strings.Join(analysis.LLMInstructions, "\n"), "Do not edit 10-sources") {
+		t.Fatalf("analysis should include safety instructions: %+v", analysis.LLMInstructions)
+	}
+	if _, err := os.Stat(filepath.Join(root, "20-wiki/concepts/repository-references/sample-repo/sample-repo-reference-bundle-2026-05-23.md")); !os.IsNotExist(err) {
+		t.Fatalf("analysis should not write bundle, stat err=%v", err)
+	}
+}
+
+func TestApplyCleanupPlanRunScopeDryRunAndApply(t *testing.T) {
+	root := t.TempDir()
+	writeDuplicateSlugFixture(t, root)
+	v := newTestVault(t, root)
+	v.Now = func() time.Time { return time.Date(2026, 5, 23, 12, 0, 0, 0, time.UTC) }
+	plan := CleanupPlan{
+		Version: 1,
+		Scope:   "duplicate-slugs",
+		Summary: "LLM reviewed duplicate slug candidates and chose the deterministic guarded scope.",
+		Actions: []CleanupPlanAction{{
+			Type:   "run_scope",
+			Scope:  "duplicate-slugs",
+			Reason: "root compatibility pages duplicate canonical meta slugs",
+		}},
+	}
+
+	dryRun, err := v.ApplyCleanupPlan(CleanupPlanApplyOptions{Plan: plan})
+	if err != nil {
+		t.Fatalf("ApplyCleanupPlan() dry-run error = %v", err)
+	}
+	if dryRun.Applied || len(dryRun.Actions) != 1 || dryRun.Actions[0].PlannedChanges != 2 {
+		t.Fatalf("unexpected dry-run result: %+v", dryRun)
+	}
+	if _, err := os.Stat(filepath.Join(root, "root-compatibility-index.md")); !os.IsNotExist(err) {
+		t.Fatalf("dry-run should not create renamed file, stat err=%v", err)
+	}
+
+	applied, err := v.ApplyCleanupPlan(CleanupPlanApplyOptions{Plan: plan, Apply: true})
+	if err != nil {
+		t.Fatalf("ApplyCleanupPlan() apply error = %v", err)
+	}
+	if !applied.Applied || len(applied.Actions) != 1 || applied.Actions[0].PlannedChanges != 2 {
+		t.Fatalf("unexpected apply result: %+v", applied)
+	}
+	if _, err := os.Stat(filepath.Join(root, "root-compatibility-index.md")); err != nil {
+		t.Fatalf("apply should create renamed page: %v", err)
+	}
+	lint, err := v.Lint()
+	if err != nil {
+		t.Fatalf("Lint() after plan apply error = %v", err)
+	}
+	if !lint.OK || len(lint.DuplicateSlugs) != 0 {
+		t.Fatalf("expected clean lint after plan apply, got %+v", lint)
+	}
+}
+
+func TestApplyCleanupPlanRejectsUnsafeRename(t *testing.T) {
+	root := t.TempDir()
+	writeDuplicateSlugFixture(t, root)
+	v := newTestVault(t, root)
+
+	_, err := v.ApplyCleanupPlan(CleanupPlanApplyOptions{
+		Apply: true,
+		Plan: CleanupPlan{
+			Version: 1,
+			Scope:   "manual",
+			Actions: []CleanupPlanAction{{
+				Type:     "rename_page",
+				FromPath: "index.md",
+				ToPath:   "../escape.md",
+				Reason:   "bad LLM plan must be rejected by deterministic validation",
+			}},
+		},
+	})
+	if err == nil {
+		t.Fatalf("ApplyCleanupPlan() should reject path traversal target")
+	}
+	if _, statErr := os.Stat(filepath.Join(root, "index.md")); statErr != nil {
+		t.Fatalf("unsafe plan should leave source untouched: %v", statErr)
+	}
+
+	_, err = v.ApplyCleanupPlan(CleanupPlanApplyOptions{
+		Apply: true,
+		Plan: CleanupPlan{
+			Version: 1,
+			Scope:   "manual",
+			Actions: []CleanupPlanAction{{
+				Type:     "rename_page",
+				FromPath: "index.md",
+				ToPath:   "/tmp/escape.md",
+				Reason:   "absolute targets must be rejected",
+			}},
+		},
+	})
+	if err == nil {
+		t.Fatalf("ApplyCleanupPlan() should reject absolute target")
+	}
+
+	_, err = v.ApplyCleanupPlan(CleanupPlanApplyOptions{
+		Apply: true,
+		Plan: CleanupPlan{
+			Version: 1,
+			Scope:   "manual",
+			Actions: []CleanupPlanAction{{
+				Type:     "rename_page",
+				FromPath: "10-sources/source.md",
+				ToPath:   "20-wiki/concepts/source.md",
+				Reason:   "protected source paths must not be moved",
+			}},
+		},
+	})
+	if err == nil {
+		t.Fatalf("ApplyCleanupPlan() should reject protected 10-sources source")
+	}
+}
+
+func writeRepositoryReferenceFixture(t *testing.T, root string) {
+	t.Helper()
+	writeTestPage(t, root, "20-wiki/concepts/repository-references/sample-repo/sample-repo-go-rules-2026-05-22.md", testFrontmatter("Sample Repo Go Rules", "reference")+`
+# Go Rules
+
+Go services in sample-repo use explicit context deadlines and table-driven tests.
+Source grounding: [[repo-source-card]].
+`)
+	writeTestPage(t, root, "20-wiki/concepts/repository-references/sample-repo/sample-repo-swagger-rules-2026-05-22.md", testFrontmatter("Sample Repo Swagger Rules", "reference")+`
+# Swagger Rules
+
+Swagger annotations must document every exported HTTP handler response shape.
+`)
+	writeTestPage(t, root, "20-wiki/concepts/repository-references/sample-repo/sample-repo-reference-bundle-2026-05-22.md", testFrontmatter("Old Bundle", "reference")+`
+# Old Bundle
+
+Existing bundles are ignored as cleanup inputs.
+`)
+	writeTestPage(t, root, "20-wiki/concepts/consumer.md", testFrontmatter("Consumer", "concept")+`
+Use [[sample-repo-go-rules-2026-05-22]] and [[sample-repo-swagger-rules-2026-05-22|swagger]].
+`)
+	writeTestPage(t, root, "20-wiki/concepts/repo-source-card.md", testFrontmatter("Repo Source Card", "concept")+`
+# Repo Source Card
+`)
+	writeTestPage(t, root, "10-sources/source-card.md", testFrontmatter("Source Card", "source")+`
+This source mentions sample-repo-go-rules-2026-05-22 as plain text and must not be rewritten.
+`)
+	writeTestPage(t, root, "00-meta/index.md", testFrontmatter("Index", "index")+`
+# Index
+
+### Repository-specific technical references
+- [[sample-repo-go-rules-2026-05-22]]
+- [[sample-repo-swagger-rules-2026-05-22]]
+### Career / Resume
+- [[consumer]]
+
+**Repository-specific tech references**
+- [[sample-repo-go-rules-2026-05-22]], [[sample-repo-swagger-rules-2026-05-22]]
+- [[sample-repo-go-rules-2026-05-22]]
+
+### Data
+- [[sample-repo-go-rules-2026-05-22]], [[sample-repo-swagger-rules-2026-05-22]]
+- [[sample-repo-go-rules-2026-05-22]], [[sample-repo-swagger-rules-2026-05-22]]
+`)
+	writeTestPage(t, root, "00-meta/log.md", testFrontmatter("Log", "log")+`
+# Log
+`)
+}
+
+func writeDuplicateSlugFixture(t *testing.T, root string) {
+	t.Helper()
+	writeTestPage(t, root, "00-meta/index.md", testFrontmatter("Canonical Index", "index")+`
+# Canonical Index
+
+- [[canonical-page]]
+`)
+	writeTestPage(t, root, "00-meta/log.md", testFrontmatter("Canonical Log", "log")+`
+# Canonical Log
+`)
+	writeTestPage(t, root, "index.md", `---
+title: Root Compatibility Index
+type: index
+status: active
+created: 2026-05-23
+updated: 2026-05-23
+tags: [meta, index, compatibility]
+domain: meta
+---
+
+# Root Compatibility Index
+
+Canonical catalog: [00-meta/index.md](00-meta/index.md)
+`)
+	writeTestPage(t, root, "log.md", `---
+title: Root Compatibility Log
+type: log
+status: active
+created: 2026-05-23
+updated: 2026-05-23
+tags: [meta, log, compatibility]
+domain: meta
+---
+
+# Root Compatibility Log
+
+Canonical operation log: [00-meta/log.md](00-meta/log.md)
+`)
+	writeTestPage(t, root, "20-wiki/concepts/canonical-page.md", testFrontmatter("Canonical Page", "concept")+`
+# Canonical Page
+`)
+}
+
+func readTestFile(t *testing.T, root, rel string) string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(root, filepath.FromSlash(rel)))
+	if err != nil {
+		t.Fatalf("read %s: %v", rel, err)
+	}
+	return string(data)
+}

package/internal/wiki/init.go

@@ -0,0 +1,77 @@
+package wiki
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+var standardVaultDirs = []string{
+	"00-meta",
+	"00-meta/reports",
+	"10-sources",
+	"20-wiki",
+	"20-wiki/concepts",
+	"20-wiki/entities",
+	"20-wiki/summaries",
+	"30-sessions",
+}
+
+// InitResult reports the non-destructive folder bootstrap performed for a vault.
+type InitResult struct {
+	Root         string   `json:"root"`
+	CreatedRoot  bool     `json:"created_root"`
+	CreatedDirs  []string `json:"created_dirs,omitempty"`
+	ExistingDirs []string `json:"existing_dirs,omitempty"`
+}
+
+// StandardVaultDirs returns the fixed folder layout llm-wiki expects.
+func StandardVaultDirs() []string {
+	out := make([]string, len(standardVaultDirs))
+	copy(out, standardVaultDirs)
+	return out
+}
+
+// InitVault creates the standard llm-wiki vault folder structure. It is
+// intentionally non-destructive and idempotent: existing directories are left as
+// they are, files are never rewritten, and Obsidian configuration is not
+// created or modified.
+func InitVault(root string) (InitResult, error) {
+	if root == "" {
+		root = DefaultRoot()
+	}
+	abs, err := filepath.Abs(expandHome(root))
+	if err != nil {
+		return InitResult{}, err
+	}
+	result := InitResult{Root: abs}
+	if st, err := os.Stat(abs); err == nil {
+		if !st.IsDir() {
+			return InitResult{}, fmt.Errorf("vault root is not a directory: %s", abs)
+		}
+	} else if os.IsNotExist(err) {
+		if err := os.MkdirAll(abs, 0o755); err != nil {
+			return InitResult{}, fmt.Errorf("create vault root %s: %w", abs, err)
+		}
+		result.CreatedRoot = true
+	} else {
+		return InitResult{}, fmt.Errorf("stat vault root %s: %w", abs, err)
+	}
+	for _, rel := range standardVaultDirs {
+		path := filepath.Join(abs, filepath.FromSlash(rel))
+		if st, err := os.Stat(path); err == nil {
+			if !st.IsDir() {
+				return InitResult{}, fmt.Errorf("standard vault path is not a directory: %s", path)
+			}
+			result.ExistingDirs = append(result.ExistingDirs, rel)
+			continue
+		} else if !os.IsNotExist(err) {
+			return InitResult{}, fmt.Errorf("stat standard vault dir %s: %w", rel, err)
+		}
+		if err := os.MkdirAll(path, 0o755); err != nil {
+			return InitResult{}, fmt.Errorf("create standard vault dir %s: %w", rel, err)
+		}
+		result.CreatedDirs = append(result.CreatedDirs, rel)
+	}
+	return result, nil
+}

package/internal/wiki/vault_test.go

@@ -116,6 +116,47 @@ func TestSafeJoinRejectsUnsafePaths(t *testing.T) {
 	}
 }
 
+func TestInitVaultCreatesStandardFoldersAndIsIdempotent(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "missing", "llm-wiki")
+
+	result, err := InitVault(root)
+	if err != nil {
+		t.Fatalf("InitVault() error = %v", err)
+	}
+	if !result.CreatedRoot {
+		t.Fatalf("expected root to be created: %+v", result)
+	}
+	if result.Root != root {
+		t.Fatalf("unexpected root: got %q want %q", result.Root, root)
+	}
+	for _, rel := range StandardVaultDirs() {
+		if st, err := os.Stat(filepath.Join(root, filepath.FromSlash(rel))); err != nil || !st.IsDir() {
+			t.Fatalf("expected standard dir %s, stat=%v err=%v", rel, st, err)
+		}
+	}
+
+	again, err := InitVault(root)
+	if err != nil {
+		t.Fatalf("InitVault() second call error = %v", err)
+	}
+	if again.CreatedRoot || len(again.CreatedDirs) != 0 {
+		t.Fatalf("expected idempotent init without new dirs, got %+v", again)
+	}
+	if len(again.ExistingDirs) != len(StandardVaultDirs()) {
+		t.Fatalf("expected all dirs reported existing, got %+v", again)
+	}
+}
+
+func TestInitVaultRejectsFileRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "not-a-dir")
+	if err := os.WriteFile(root, []byte("x"), 0o644); err != nil {
+		t.Fatalf("write file root: %v", err)
+	}
+	if _, err := InitVault(root); err == nil {
+		t.Fatalf("expected InitVault to reject file root")
+	}
+}
+
 func TestCaptureWritesAllowedMarkdownAndRejectsProtectedFolders(t *testing.T) {
 	v := newTestVault(t, t.TempDir())
 	v.Now = func() time.Time { return time.Date(2026, 5, 23, 12, 0, 0, 0, time.UTC) }

package/npm/lib/runner.js

@@ -9,6 +9,9 @@ const SIGNAL_EXIT_CODES = {
   SIGTERM: 143,
 };
 
+const FINGERPRINT_INPUT_ENTRIES = ['go.mod', 'go.sum', 'package.json', 'cmd', 'internal'];
+const BINARY_INPUT_ENTRIES = ['go.mod', 'go.sum', 'cmd', 'internal'];
+
 function executableName(platform = process.platform) {
   return platform === 'win32' ? 'llm-wiki.exe' : 'llm-wiki';
 }
@@ -25,7 +28,9 @@ function isExecutable(file) {
 
 function findBundledBinary(packageRoot, platform = process.platform) {
   const candidate = path.join(packageRoot, 'bin', executableName(platform));
-  return isExecutable(candidate) ? candidate : '';
+  if (!isExecutable(candidate)) return '';
+  if (isBundledBinaryStale(packageRoot, candidate)) return '';
+  return candidate;
 }
 
 function readPackageVersion(packageRoot) {
@@ -38,7 +43,11 @@ function readPackageVersion(packageRoot) {
   }
 }
 
-function hashFile(hash, root, file) {
+function isBuildInput(file) {
+  return file.endsWith('.go') || ['go.mod', 'go.sum', 'package.json'].includes(path.basename(file));
+}
+
+function walkBuildInputs(root, file, visitor) {
   let stat;
   try {
     stat = fs.statSync(file);
@@ -49,14 +58,23 @@ function hashFile(hash, root, file) {
   if (stat.isDirectory()) {
     const entries = fs.readdirSync(file).sort();
     for (const entry of entries) {
-      hashFile(hash, root, path.join(file, entry));
+      walkBuildInputs(root, path.join(file, entry), visitor);
     }
     return;
   }
-  const isBuildInput = file.endsWith('.go') || ['go.mod', 'go.sum', 'package.json'].includes(path.basename(file));
-  if (!stat.isFile() || !isBuildInput) {
+  if (!stat.isFile() || !isBuildInput(file)) {
     return;
   }
+  visitor(file, stat);
+}
+
+function visitBuildInputs(packageRoot, entries, visitor) {
+  for (const entry of entries) {
+    walkBuildInputs(packageRoot, path.join(packageRoot, entry), visitor);
+  }
+}
+
+function hashFile(hash, root, file, stat) {
   hash.update(path.relative(root, file));
   hash.update('\0');
   hash.update(String(stat.size));
@@ -67,12 +85,30 @@ function hashFile(hash, root, file) {
 
 function sourceFingerprint(packageRoot) {
   const hash = crypto.createHash('sha256');
-  for (const entry of ['go.mod', 'go.sum', 'package.json', 'cmd', 'internal']) {
-    hashFile(hash, packageRoot, path.join(packageRoot, entry));
-  }
+  visitBuildInputs(packageRoot, FINGERPRINT_INPUT_ENTRIES, (file, stat) => hashFile(hash, packageRoot, file, stat));
   return hash.digest('hex').slice(0, 16);
 }
 
+function latestBuildInputMTime(packageRoot) {
+  let latest = 0;
+  visitBuildInputs(packageRoot, BINARY_INPUT_ENTRIES, (_file, stat) => {
+    if (stat.mtimeMs > latest) latest = stat.mtimeMs;
+  });
+  return latest;
+}
+
+function isBundledBinaryStale(packageRoot, binary) {
+  let binaryStat;
+  try {
+    binaryStat = fs.statSync(binary);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return true;
+    throw err;
+  }
+  const latestInput = latestBuildInputMTime(packageRoot);
+  return latestInput > binaryStat.mtimeMs;
+}
+
 function defaultCacheRoot(env = process.env) {
   if (env.LLM_WIKI_NPM_CACHE_DIR) return env.LLM_WIKI_NPM_CACHE_DIR;
   if (env.XDG_CACHE_HOME) return path.join(env.XDG_CACHE_HOME, 'llm-wiki', 'npm-wrapper');
@@ -110,8 +146,10 @@ function buildBinary(packageRoot, output, env = process.env) {
 function ensureBinary(options = {}) {
   const env = options.env || process.env;
   const packageRoot = options.packageRoot || env.LLM_WIKI_NPM_PACKAGE_ROOT || path.resolve(__dirname, '..', '..');
-  const bundled = findBundledBinary(packageRoot);
-  if (bundled) return bundled;
+  if (env.LLM_WIKI_NPM_REBUILD !== '1') {
+    const bundled = findBundledBinary(packageRoot);
+    if (bundled) return bundled;
+  }
 
   const cached = cacheBinaryPath(packageRoot, env);
   if (isExecutable(cached) && env.LLM_WIKI_NPM_REBUILD !== '1') return cached;
@@ -162,6 +200,8 @@ module.exports = {
   ensureBinary,
   executableName,
   findBundledBinary,
+  isBundledBinaryStale,
+  latestBuildInputMTime,
   run,
   sourceFingerprint,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m16khb/llm-wiki",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "npx wrapper for the llm-wiki Go MCP server and CLI",
   "bin": {
     "llm-wiki": "npm/bin/llm-wiki.js"