@m16khb/llm-wiki 0.1.0

package/README.md

@@ -0,0 +1,170 @@
+# llm-wiki
+
+`llm-wiki`는 Claude Code와 Codex가 같은 Obsidian-backed LLM Wiki vault를 안전하게 공유하도록 하는 Go 기반 MCP 서버/CLI다.
+
+현재 기본 구조는 **단일 daemon process + streamable HTTP MCP + SQLite WAL queue + in-memory metadata cache**다. 여러 Claude Code/Codex 세션은 각자 파일을 직접 쓰지 않고 같은 daemon의 MCP endpoint에 붙는다.
+
+## 핵심 원칙
+
+- Single writer: `llm-wiki serve` daemon 하나가 write를 직렬화한다.
+- SQLite WAL queue: write job은 durable queue/audit DB에 먼저 기록된다.
+- Local-first: Markdown vault가 canonical source다. SQLite는 queue/index/cache/audit state이며 rebuild 가능해야 한다.
+- Read-safe: `.obsidian/`, hidden/runtime directory, path traversal은 차단한다.
+- Write-minimal: 기본 write는 `wiki_capture`의 additive Markdown 생성뿐이다.
+- Source 보호: `10-sources/` body 수정/삭제 도구는 제공하지 않는다.
+
+## 빠른 시작
+
+```bash
+# repo root
+./scripts/install-local.sh
+
+# singleton daemon 시작
+./bin/llm-wiki serve --vault ~/workspace/knowledge-base/llm-wiki
+
+# 별도 shell에서 health check
+curl http://127.0.0.1:39233/healthz
+
+# read-only CLI smoke
+./bin/llm-wiki info --vault ~/workspace/knowledge-base/llm-wiki --json
+./bin/llm-wiki search --vault ~/workspace/knowledge-base/llm-wiki --limit 5 karpathy
+./bin/llm-wiki lint --vault ~/workspace/knowledge-base/llm-wiki --json
+
+# queue audit 확인
+./bin/llm-wiki jobs --limit 20
+```
+
+`--vault`를 생략하면 `LLM_WIKI_ROOT`, `LLM_WIKI_VAULT`, `~/workspace/knowledge-base/llm-wiki`, `~/Workspace/knowledge-base/llm-wiki` 순서로 찾는다.
+
+`--db`를 생략하면 `LLM_WIKI_DB` 또는 OS user config directory 아래 `llm-wiki/llm-wiki.db`를 사용한다.
+
+## CLI commands
+
+| Command | Purpose |
+|---|---|
+| `llm-wiki serve` | singleton daemon + streamable HTTP MCP endpoint 시작 |
+| `llm-wiki mcp` | legacy stdio MCP server; daemon HTTP가 기본 권장 경로 |
+| `llm-wiki info` | vault root/count 요약 |
+| `llm-wiki search QUERY` | Markdown lexical search |
+| `llm-wiki read PAGE_OR_PATH` | slug 또는 vault-relative path로 page 읽기 |
+| `llm-wiki lint` | frontmatter/wikilink/slug 구조 점검 |
+| `llm-wiki capture` | SQLite queue를 통해 allowed folder에 curated note 생성 |
+| `llm-wiki jobs` | SQLite queue 최근 job audit 출력 |
+
+## MCP tools
+
+| Tool | Type | Purpose |
+|---|---|---|
+| `wiki_info` | read-only | vault count/root 확인 |
+| `wiki_search` | read-only | keyword search |
+| `wiki_read` | read-only | page content 읽기 |
+| `wiki_lint` | read-only | structural lint |
+| `wiki_capture` | queued additive write | `20-wiki/`, `30-sessions/`, `00-meta/reports/` 하위에 note 생성 |
+
+## Claude Code 설정
+
+먼저 daemon을 실행한다.
+
+```bash
+/Users/m16khb/Workspace/llm-wiki/bin/llm-wiki serve \
+  --vault /Users/m16khb/Workspace/knowledge-base/llm-wiki
+```
+
+그 다음 `config/claude-code.mcp.json`을 target project의 `.mcp.json`에 복사한다.
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "type": "http",
+      "url": "http://127.0.0.1:39233/mcp"
+    }
+  }
+}
+```
+
+Claude Code는 local stdio뿐 아니라 HTTP MCP server 설정도 지원한다. 공식 문서는 `claude mcp add`와 `.mcp.json` scope를 설명한다: https://code.claude.com/docs/en/mcp
+
+### npx / stdio compatibility 설정
+
+HTTP daemon을 공유하는 구성이 기본 권장 경로지만, stdio MCP만 허용되는 환경에서는 npm wrapper로 `llm-wiki mcp`를 실행할 수 있다.
+
+로컬 repo를 바로 쓰는 `.mcp.json` 예시:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "/Users/m16khb/Workspace/llm-wiki",
+        "llm-wiki",
+        "mcp",
+        "--vault",
+        "/Users/m16khb/Workspace/knowledge-base/llm-wiki"
+      ]
+    }
+  }
+}
+```
+
+npm registry에 publish한 뒤에는 package path 대신 package name을 쓴다.
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@m16khb/llm-wiki",
+        "llm-wiki",
+        "mcp",
+        "--vault",
+        "/Users/m16khb/Workspace/knowledge-base/llm-wiki"
+      ]
+    }
+  }
+}
+```
+
+wrapper는 기존 `bin/llm-wiki`가 있으면 그대로 실행하고, 없으면 Go toolchain으로 CLI를 cache에 빌드한 뒤 실행한다. MCP stdio 안전을 위해 wrapper 자체는 stdout에 진단을 쓰지 않는다.
+
+## Codex 설정
+
+먼저 daemon을 실행한다. 그 다음 `config/codex.config.toml` 내용을 `~/.codex/config.toml`에 병합한다.
+
+```toml
+[mcp_servers.llm-wiki]
+url = "http://127.0.0.1:39233/mcp"
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+Codex config는 MCP streamable HTTP server endpoint를 `mcp_servers.<id>.url`로 설정한다: https://developers.openai.com/codex/config-reference
+
+## 개발 문서
+
+작업 전 `AGENTS.md`와 `agent_docs/CONSTITUTION.md`를 읽는다.
+
+- `agent_docs/ARCHITECTURE.md` — daemon/queue/MCP 구조와 계층 책임
+- `agent_docs/CONVENTIONS.md` — 구현 컨벤션
+- `agent_docs/GO_GUIDE.md` — Go 작성 가이드
+- `agent_docs/TESTING.md` — 검증 기준
+- `agent_docs/CAUTIONS.md` — 반복 주의사항
+- `agent_docs/TECH_STACK.md` — 버전/명령/설정
+- `agent_docs/ADR.md` — 유지할 결정 기록
+
+## 검증
+
+```bash
+gofmt -w cmd internal
+npm run test:npm
+go test ./... -count=1
+go build ./...
+```
+
+실제 사용자 vault를 대상으로 destructive test를 하지 않는다. `capture`/write 동작은 temp vault test나 명시적인 test vault에서 검증한다.

package/cmd/llm-wiki/main.go

@@ -0,0 +1,272 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/m16khb/llm-wiki/internal/daemon"
+	"github.com/m16khb/llm-wiki/internal/mcpserver"
+	"github.com/m16khb/llm-wiki/internal/service"
+	"github.com/m16khb/llm-wiki/internal/store"
+	"github.com/m16khb/llm-wiki/internal/wiki"
+)
+
+func main() {
+	log.SetOutput(os.Stderr)
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(2)
+	}
+	cmd := os.Args[1]
+	switch cmd {
+	case "mcp":
+		runMCP(os.Args[2:])
+	case "serve", "daemon":
+		runServe(os.Args[2:])
+	case "jobs", "queue":
+		runJobs(os.Args[2:])
+	case "info":
+		runInfo(os.Args[2:])
+	case "search":
+		runSearch(os.Args[2:])
+	case "read":
+		runRead(os.Args[2:])
+	case "lint":
+		runLint(os.Args[2:])
+	case "capture":
+		runCapture(os.Args[2:])
+	case "version", "--version", "-v":
+		fmt.Println(mcpserver.Version)
+	case "help", "--help", "-h":
+		usage()
+	default:
+		fmt.Fprintf(os.Stderr, "unknown command: %s\n\n", cmd)
+		usage()
+		os.Exit(2)
+	}
+}
+
+func usage() {
+	fmt.Fprintf(os.Stderr, `llm-wiki %s
+
+Usage:
+  llm-wiki serve [--vault PATH] [--db PATH] [--addr 127.0.0.1:39233]
+  llm-wiki mcp [--vault PATH] [--db PATH]
+  llm-wiki info [--vault PATH] [--json]
+  llm-wiki search [--vault PATH] [--limit N] [--root FOLDER] QUERY
+  llm-wiki read [--vault PATH] [--max-bytes N] PAGE_OR_PATH
+  llm-wiki lint [--vault PATH] [--json]
+  llm-wiki capture [--vault PATH] [--db PATH] --title TITLE --body BODY [--type concept] [--tags a,b]
+  llm-wiki jobs [--db PATH] [--limit N]
+
+Environment:
+  LLM_WIKI_ROOT or LLM_WIKI_VAULT can provide the default vault path.
+  LLM_WIKI_DB can provide the default SQLite WAL queue path.
+
+`, mcpserver.Version)
+}
+
+func vaultFlag(fs *flag.FlagSet) *string {
+	return fs.String("vault", "", "Obsidian LLM Wiki vault root")
+}
+
+func dbFlag(fs *flag.FlagSet) *string {
+	return fs.String("db", "", "SQLite queue/cache database path")
+}
+
+func runMCP(args []string) {
+	fs := flag.NewFlagSet("mcp", flag.ExitOnError)
+	vaultRoot := vaultFlag(fs)
+	dbPath := dbFlag(fs)
+	_ = fs.Parse(args)
+	server, err := mcpserver.New(mcpserver.Config{VaultRoot: *vaultRoot, DBPath: *dbPath})
+	if err != nil {
+		log.Fatalf("llm-wiki mcp: %v", err)
+	}
+	if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
+		log.Fatalf("llm-wiki mcp: %v", err)
+	}
+}
+
+func runServe(args []string) {
+	fs := flag.NewFlagSet("serve", flag.ExitOnError)
+	vaultRoot := vaultFlag(fs)
+	dbPath := dbFlag(fs)
+	addr := fs.String("addr", "127.0.0.1:39233", "HTTP listen address for streamable MCP")
+	_ = fs.Parse(args)
+	srv, err := daemon.New(daemon.Config{VaultRoot: *vaultRoot, DBPath: *dbPath, Addr: *addr})
+	if err != nil {
+		log.Fatalf("llm-wiki serve: %v", err)
+	}
+	defer srv.Close()
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	if err := srv.Serve(ctx); err != nil && err != context.Canceled {
+		log.Fatalf("llm-wiki serve: %v", err)
+	}
+}
+
+func runInfo(args []string) {
+	fs := flag.NewFlagSet("info", flag.ExitOnError)
+	vaultRoot := vaultFlag(fs)
+	jsonOut := fs.Bool("json", false, "print JSON")
+	_ = fs.Parse(args)
+	v := mustVault(*vaultRoot)
+	info, err := v.Info()
+	must(err)
+	if *jsonOut {
+		printJSON(info)
+		return
+	}
+	fmt.Printf("root: %s\nmarkdown: %d\nsources: %d\nconcepts: %d\nentities: %d\nsessions: %d\n", info.Root, info.MarkdownFiles, info.Sources, info.Concepts, info.Entities, info.Sessions)
+}
+
+func runSearch(args []string) {
+	fs := flag.NewFlagSet("search", flag.ExitOnError)
+	vaultRoot := vaultFlag(fs)
+	limit := fs.Int("limit", 10, "max results")
+	root := fs.String("root", "", "optional vault-relative folder filter")
+	jsonOut := fs.Bool("json", false, "print JSON")
+	_ = fs.Parse(args)
+	query := strings.Join(fs.Args(), " ")
+	v := mustVault(*vaultRoot)
+	var roots []string
+	if strings.TrimSpace(*root) != "" {
+		roots = append(roots, *root)
+	}
+	results, err := v.Search(wiki.SearchOptions{Query: query, Limit: *limit, Roots: roots})
+	must(err)
+	if *jsonOut {
+		printJSON(results)
+		return
+	}
+	for _, r := range results {
+		fmt.Printf("[[%s]] %s score=%d\n  %s\n", r.Slug, r.Path, r.Score, r.Snippet)
+	}
+}
+
+func runRead(args []string) {
+	fs := flag.NewFlagSet("read", flag.ExitOnError)
+	vaultRoot := vaultFlag(fs)
+	maxBytes := fs.Int("max-bytes", 0, "max bytes")
+	jsonOut := fs.Bool("json", false, "print JSON")
+	_ = fs.Parse(args)
+	if fs.NArg() != 1 {
+		fmt.Fprintln(os.Stderr, "read requires PAGE_OR_PATH")
+		os.Exit(2)
+	}
+	v := mustVault(*vaultRoot)
+	page, content, err := v.ReadPage(fs.Arg(0), *maxBytes)
+	must(err)
+	if *jsonOut {
+		printJSON(map[string]any{"page": page, "content": content})
+		return
+	}
+	fmt.Print(content)
+}
+
+func runLint(args []string) {
+	fs := flag.NewFlagSet("lint", flag.ExitOnError)
+	vaultRoot := vaultFlag(fs)
+	jsonOut := fs.Bool("json", false, "print JSON")
+	_ = fs.Parse(args)
+	v := mustVault(*vaultRoot)
+	result, err := v.Lint()
+	must(err)
+	if *jsonOut {
+		printJSON(result)
+	} else if result.OK {
+		fmt.Printf("PASS markdown=%d\n", result.MarkdownFiles)
+	} else {
+		fmt.Printf("FAIL markdown=%d missing_frontmatter=%d broken_wikilinks=%d duplicate_slugs=%d\n", result.MarkdownFiles, len(result.MissingFrontmatter), len(result.BrokenWikilinks), len(result.DuplicateSlugs))
+	}
+	if !result.OK {
+		os.Exit(1)
+	}
+}
+
+func runCapture(args []string) {
+	fs := flag.NewFlagSet("capture", flag.ExitOnError)
+	vaultRoot := vaultFlag(fs)
+	dbPath := dbFlag(fs)
+	title := fs.String("title", "", "page title")
+	body := fs.String("body", "", "markdown body")
+	bodyFile := fs.String("body-file", "", "read markdown body from file")
+	typ := fs.String("type", "concept", "page type")
+	status := fs.String("status", "draft", "page status")
+	domain := fs.String("domain", "dev-fundamentals", "domain")
+	tags := fs.String("tags", "", "comma-separated tags")
+	folder := fs.String("folder", "", "target folder")
+	slug := fs.String("slug", "", "page slug")
+	overwrite := fs.Bool("overwrite", false, "overwrite existing page")
+	jsonOut := fs.Bool("json", false, "print JSON")
+	_ = fs.Parse(args)
+	bodyText := *body
+	if *bodyFile != "" {
+		data, err := os.ReadFile(*bodyFile)
+		must(err)
+		bodyText = string(data)
+	}
+	svc, err := service.New(service.Config{VaultRoot: *vaultRoot, DBPath: *dbPath})
+	must(err)
+	defer svc.Close()
+	result, err := svc.Capture(wiki.CaptureInput{Title: *title, Body: bodyText, Type: *typ, Status: *status, Domain: *domain, Tags: splitComma(*tags), Folder: *folder, Slug: *slug, Overwrite: *overwrite})
+	must(err)
+	if *jsonOut {
+		printJSON(result)
+		return
+	}
+	fmt.Printf("wrote %s\n", result.Path)
+}
+
+func runJobs(args []string) {
+	fs := flag.NewFlagSet("jobs", flag.ExitOnError)
+	dbPath := dbFlag(fs)
+	limit := fs.Int("limit", 20, "max jobs")
+	_ = fs.Parse(args)
+	st, err := store.Open(*dbPath)
+	must(err)
+	defer st.Close()
+	jobs, err := st.RecentJobs(context.Background(), *limit)
+	must(err)
+	printJSON(jobs)
+}
+
+func mustVault(root string) *wiki.Vault {
+	v, err := wiki.New(root)
+	must(err)
+	return v
+}
+
+func must(err error) {
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "llm-wiki:", err)
+		os.Exit(1)
+	}
+}
+
+func printJSON(v any) {
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	must(enc.Encode(v))
+}
+
+func splitComma(s string) []string {
+	var out []string
+	for _, part := range strings.Split(s, ",") {
+		part = strings.TrimSpace(part)
+		if part != "" {
+			out = append(out, part)
+		}
+	}
+	return out
+}

package/go.mod

@@ -0,0 +1,23 @@
+module github.com/m16khb/llm-wiki
+
+go 1.25.5
+
+require github.com/modelcontextprotocol/go-sdk v1.6.0
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/jsonschema-go v0.4.3 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
+	golang.org/x/oauth2 v0.35.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	modernc.org/libc v1.72.3 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	modernc.org/sqlite v1.50.1 // indirect
+)

package/go.sum

@@ -0,0 +1,41 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/modelcontextprotocol/go-sdk v1.6.0 h1:PPLS3kn7WtOEnR+Af4X5H96SG0qSab8R/ZQT/HkhPkY=
+github.com/modelcontextprotocol/go-sdk v1.6.0/go.mod h1:kzm3kzFL1/+AziGOE0nUs3gvPoNxMCvkxokMkuFapXQ=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
+modernc.org/libc v1.72.3 h1:ZnDF4tXn4NBXFutMMQC4vtbTFSXhhKzR73fv0beZEAU=
+modernc.org/libc v1.72.3/go.mod h1:dn0dZNnnn1clLyvRxLxYExxiKRZIRENOfqQ8XEeg4Qs=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/sqlite v1.50.1 h1:l+cQvn0sd0zJJtfygGHuQJ5AjlrwXmWPw4KP3ZMwr9w=
+modernc.org/sqlite v1.50.1/go.mod h1:tcNzv5p84E0skkmJn038y+hWJbLQXQqEnQfeh5r2JLM=

package/internal/daemon/lock.go

@@ -0,0 +1,50 @@
+package daemon
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+// Lock is an advisory cross-process singleton guard for a daemon instance.
+type Lock struct {
+	path string
+	file *os.File
+}
+
+// AcquireLock obtains a non-blocking exclusive advisory lock.
+func AcquireLock(path string) (*Lock, error) {
+	if path == "" {
+		return nil, fmt.Errorf("lock path is required")
+	}
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return nil, err
+	}
+	if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+		return nil, err
+	}
+	file, err := os.OpenFile(abs, os.O_CREATE|os.O_RDWR, 0o644)
+	if err != nil {
+		return nil, err
+	}
+	if err := syscall.Flock(int(file.Fd()), syscall.LOCK_EX|syscall.LOCK_NB); err != nil {
+		file.Close()
+		return nil, fmt.Errorf("another llm-wiki daemon is already using %s: %w", abs, err)
+	}
+	_ = file.Truncate(0)
+	_, _ = fmt.Fprintf(file, "pid=%d\n", os.Getpid())
+	return &Lock{path: abs, file: file}, nil
+}
+
+func (l *Lock) Close() error {
+	if l == nil || l.file == nil {
+		return nil
+	}
+	_ = syscall.Flock(int(l.file.Fd()), syscall.LOCK_UN)
+	err := l.file.Close()
+	_ = os.Remove(l.path)
+	l.file = nil
+	return err
+}

package/internal/daemon/lock_test.go

@@ -0,0 +1,19 @@
+package daemon
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestAcquireLockPreventsSecondDaemon(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "daemon.lock")
+	first, err := AcquireLock(path)
+	if err != nil {
+		t.Fatalf("AcquireLock first error = %v", err)
+	}
+	defer first.Close()
+	if second, err := AcquireLock(path); err == nil {
+		second.Close()
+		t.Fatalf("second AcquireLock unexpectedly succeeded")
+	}
+}