@bitefoundry/obsidian 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,142 +1,149 @@
1
- <div align="center">
2
-
3
- # `@bitefoundry/obsidian`
4
-
5
- **Obsidian-native terminal workspace, interactive knowledge graph & AI agent toolkit — Zero-Auth Local Vaults, Backlinks, Braille Graph View, CLI · TUI · HTTP API · MCP.**
6
-
7
- [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fobsidian?style=flat-square&color=7C3AED)](https://www.npmjs.com/package/@bitefoundry/obsidian)
8
- [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
- [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](Cargo.toml)
10
- [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](package.json)
11
-
12
- <br />
13
-
14
- ![Obsidian TUI Demo](assets/demo.gif)
15
-
16
- </div>
17
-
18
- ---
19
-
20
- ## Highlights
21
-
22
- | Pillar | Capabilities |
23
- | :--- | :--- |
24
- | **Zero-Auth Native Vault Discovery** | Automatically discovers every local Obsidian vault from `%APPDATA%\obsidian\obsidian.json` (Windows), `~/Library/Application Support/obsidian/obsidian.json` (macOS), or `~/.config/obsidian/obsidian.json` (Linux) — 100% local-first Markdown files on disk, zero API keys or cloud auth required. |
25
- | **Obsidian-Native 3-Pane TUI** | Signature Obsidian purple (`#a78bfa` / `#7c3aed`) Minimal-Chrome workspace (`obsidian` / `obs`): collapsible **5-Tab Left Sidebar (`[`)** (`1 Files · 2 Tags · 3 Bookmarks · 4 Outline · 5 Tasks`), **Live Note Canvas** with YAML Frontmatter pills, `#tag` chips, semantic Callout cards, interactive `- [ ]` checkboxes (`Space`/`x` updates the `.md` file atomically), clickable `[[wikilinks]]`, inline HD `![[image.png]]` previews (`v`), **Right Backlinks & Outgoing Inspector (`B`)**, **Quick Switcher (`Ctrl+O`)**, **Daily Notes (`D`)**, and **5 curated palettes** (`Obsidian Dark`, `Catppuccin Mocha`, `Tokyo Night`, `Nord`, `Warm Paper`). |
26
- | **Interactive Knowledge Graph (`G`)** | Force-directed & radial **Braille Canvas Knowledge Graph** rendered right inside the terminal: purple focal edges, 1-hop / 2-hop / unresolved ghost nodes, Local vs Global scope (`l`), hop depth (`+/-`), node cycling (`j`/`k`/`Tab`), and `Enter` jump-to-note. |
27
- | **SQLite WAL + FTS5 + 4-in-1 Agent Interface** | Incremental `mtime_ms` + `size_bytes` filesystem scanner powering SQLite WAL + FTS5 search (with automatic `<3`-char Korean/CJK `LIKE` fallback), background watcher IPC daemon (`obsidian daemon`), scriptable `--json` CLI, local **HTTP JSON API** (`obsidian serve`, `:8792`), and **stdio MCP server** (`obsidian mcp`, **18 typed tools** with `confirm: true` `.trash/` safety guard). |
28
-
29
- ---
30
-
31
- ## Quick Start
32
-
33
- ```bash
34
- # 1. Install globally (links `obsidian` and `obs` native Rust binaries)
35
- npm i -g @bitefoundry/obsidian
36
-
37
- # 2. Launch directly — auto-discovers your existing local Obsidian vaults!
38
- obsidian # alias: obs
39
-
40
- # Or scaffold a starter local vault anywhere:
41
- obsidian init ~/Documents/SecondBrain
42
- obsidian vaults list
43
- ```
44
-
45
- ---
46
-
47
- ## Keybindings Cheat Sheet
48
-
49
- | Key | Action | Context |
50
- | :--- | :--- | :--- |
51
- | `Ctrl+O` / `Ctrl+K` / `Ctrl+P` | **Quick Switcher** & Command Palette (fuzzy notes + `>commands`) | Global |
52
- | `G` | Toggle **Interactive Knowledge Graph View** (Braille force-directed canvas) | Global |
53
- | `l` / `+` `-` / `j` `k` / `Enter` | Toggle Local/Global scope · Depth · Cycle nodes · Open node | Graph View |
54
- | `D` | Open or create **Today's Daily Note** (reads `.obsidian/daily-notes.json`) | Global |
55
- | `[` / `Ctrl+B` | Toggle collapsible Left Sidebar | Global |
56
- | `1` `2` `3` `4` `5` | Switch Sidebar tabs: **Files · Tags · Bookmarks · Outline · Tasks** | Global |
57
- | `B` | Toggle Right Inspector (**Linked Mentions / Backlinks** & Outgoing Links) | Global |
58
- | `Space` / `x` | Toggle live `- [ ]` / `- [x]` checkbox surgically in the `.md` file | Canvas / Tasks |
59
- | `Enter` / `Backspace` / `Alt+←` | Follow `[[wikilink]]` / Navigate back in note history stack | Canvas |
60
- | `a` / `n` / `e` / `b` | Quick Append · New Note · Open in `$EDITOR` (auto-reindexes) · Bookmark | Global |
61
- | `u` / `h` / `v` / `y` | Link Extractor · Toggle Inline Hrefs · HD Image Preview · Copy Code/Note | Global |
62
- | `Ctrl+V` / `Ctrl+F` | Paste clipboard PNG into `Attachments/` · File Picker (`z` zoxide jump) | Global |
63
- | `Ctrl+S` / `Ctrl+,` / `.` / `?` | Vault Switcher · Settings (5 Palettes) · Context Menu · Keybinding Help | Global |
64
-
65
- ---
66
-
67
- ## CLI, HTTP API & MCP
68
-
69
- ### CLI (`--json` & `--vault` ready)
70
-
71
- ```bash
72
- # Discover, register, scaffold & reindex local vaults
73
- obsidian vaults list --json
74
- obsidian vaults add ~/Vaults/Work --name work
75
- obsidian vaults use work
76
- obsidian init ~/Vaults/Starter
77
- obsidian reindex
78
-
79
- # Search, read, author, daily notes & surgical checkbox toggles
80
- obsidian search "Architecture" --json
81
- obsidian notes list --folder Projects --json
82
- obsidian notes read "Q4 Architecture RFC"
83
- obsidian notes create "Sprint Retro" --folder Notes --tags "retro,q4"
84
- obsidian notes append "Q4 Architecture RFC" "- [ ] Ship v0.1.0"
85
- obsidian daily --append "- [ ] Review PRs"
86
- obsidian tasks --open --json
87
- obsidian toggle-task "Q4 Architecture RFC" 14
88
-
89
- # Knowledge Graph & Link Intelligence
90
- obsidian backlinks "Q4 Architecture RFC" --json
91
- obsidian links "Q4 Architecture RFC" --json
92
- obsidian graph "Q4 Architecture RFC" --depth 2 --json
93
- obsidian orphans --json
94
- obsidian tags architecture --json
95
-
96
- # Background watcher daemon & diagnostics
97
- obsidian daemon start
98
- obsidian doctor --json
99
- ```
100
-
101
- ### Local HTTP JSON API (`obsidian serve`)
102
-
103
- ```bash
104
- obsidian serve --bind 127.0.0.1 --port 8792 --token "$API_TOKEN"
105
- curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8792/api/v1/search?q=Architecture"
106
- curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8792/api/v1/graph?note=Q4%20Architecture%20RFC&depth=2"
107
- ```
108
-
109
- Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
110
-
111
- ### MCP Server (`obsidian mcp` — 18 Tools)
112
-
113
- ```json
114
- {
115
- "mcpServers": {
116
- "obsidian": {
117
- "command": "obsidian",
118
- "args": ["mcp"]
119
- }
120
- }
121
- }
122
- ```
123
-
124
- Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
125
-
126
- ---
127
-
128
- ## `@bitefoundry` Enterprise Terminal Suite
129
-
130
- | Package | Commands | Workspace | Interfaces |
131
- | :--- | :--- | :--- | :--- |
132
- | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
133
- | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook`, `ol` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
134
- | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote`, `on` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
135
- | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `sp` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
136
- | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `jira`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
137
- | [`@bitefoundry/notion`](https://www.npmjs.com/package/@bitefoundry/notion) | `notion`, `nt` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
138
- | **`@bitefoundry/obsidian`** | `obsidian`, `obs` | Obsidian (Local Vaults, Backlinks & Interactive Knowledge Graph) | TUI · CLI · HTTP · MCP |
139
-
140
- ---
141
-
142
- > **Disclaimer:** Unofficial terminal client for Obsidian vaults. Not affiliated with, endorsed by, or sponsored by Dynalist Inc. (Obsidian).
1
+ <div align="center">
2
+
3
+ # `@bitefoundry/obsidian`
4
+
5
+ **Obsidian-native terminal workspace, interactive knowledge graph & AI agent toolkit — Zero-Auth Local Vaults, Backlinks, Braille Graph View, CLI · TUI · HTTP API · MCP.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fobsidian?style=flat-square&color=7C3AED)](https://www.npmjs.com/package/@bitefoundry/obsidian)
8
+ [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
+ [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](https://github.com/BiteFoundry/obsidian/blob/master/Cargo.toml)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](package.json)
11
+
12
+ <br />
13
+
14
+ ![Obsidian TUI Demo](https://raw.githubusercontent.com/BiteFoundry/obsidian/master/assets/demo.gif)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## Highlights
21
+
22
+ | Pillar | Capabilities |
23
+ | :--- | :--- |
24
+ | **Zero-Auth Native Vault Discovery** | Automatically discovers every local Obsidian vault from `%APPDATA%\obsidian\obsidian.json` (Windows), `~/Library/Application Support/obsidian/obsidian.json` (macOS), or `~/.config/obsidian/obsidian.json` (Linux) — 100% local-first Markdown files on disk, zero API keys or cloud auth required. |
25
+ | **Obsidian-Native 3-Pane TUI** | Signature Obsidian purple (`#a78bfa` / `#7c3aed`) Minimal-Chrome workspace (`obsidian` / `obs`): collapsible **5-Tab Left Sidebar (`[`)** (`1 Files · 2 Tags · 3 Bookmarks · 4 Outline · 5 Tasks`), **Live Note Canvas** with YAML Frontmatter pills, `#tag` chips, semantic Callout cards, interactive `- [ ]` checkboxes (`Space`/`x` updates the `.md` file atomically), clickable `[[wikilinks]]`, inline HD `![[image.png]]` previews (`v`), **Right Backlinks & Outgoing Inspector (`B`)**, **Quick Switcher (`Ctrl+O`)**, **Daily Notes (`D`)**, and **5 curated palettes** (`Obsidian Dark`, `Catppuccin Mocha`, `Tokyo Night`, `Nord`, `Warm Paper`). |
26
+ | **Interactive Knowledge Graph (`G`)** | Force-directed & radial **Braille Canvas Knowledge Graph** rendered right inside the terminal: purple focal edges, 1-hop / 2-hop / unresolved ghost nodes, Local vs Global scope (`l`), hop depth (`+/-`), node cycling (`j`/`k`/`Tab`), and `Enter` jump-to-note. |
27
+ | **SQLite WAL + FTS5 + 4-in-1 Agent Interface** | Incremental `mtime_ms` + `size_bytes` filesystem scanner powering SQLite WAL + FTS5 search (with automatic `<3`-char Korean/CJK `LIKE` fallback), background watcher IPC daemon (`obsidian daemon`), scriptable `--json` CLI, local **HTTP JSON API** (`obsidian serve`, `:8792`), and **stdio MCP server** (`obsidian mcp`, **19 typed tools** with `confirm: true` `.trash/` safety guard). |
28
+
29
+ ---
30
+
31
+ ## Quick Start
32
+
33
+ ```bash
34
+ # 1. Install globally (links `obsidian` and `obs` native Rust binaries)
35
+ npm i -g @bitefoundry/obsidian
36
+
37
+ # 2. Launch directly — auto-discovers your existing local Obsidian vaults!
38
+ obsidian # alias: obs
39
+
40
+ # Or scaffold a starter local vault anywhere:
41
+ obsidian init ~/Documents/SecondBrain
42
+ obsidian vaults list
43
+ ```
44
+
45
+ ---
46
+
47
+ ## Keybindings Cheat Sheet
48
+
49
+ | Key | Action | Context |
50
+ | :--- | :--- | :--- |
51
+ | `Ctrl+O` / `Ctrl+K` / `Ctrl+P` | **Quick Switcher** & Command Palette (fuzzy notes + `>commands`) | Global |
52
+ | `G` | Toggle **Interactive Knowledge Graph View** (Braille force-directed canvas) | Global |
53
+ | `l` / `+` `-` / `j` `k` / `Enter` | Toggle Local/Global scope · Depth · Cycle nodes · Open node | Graph View |
54
+ | `D` | Open or create **Today's Daily Note** (reads `.obsidian/daily-notes.json`) | Global |
55
+ | `[` / `Ctrl+B` | Toggle collapsible Left Sidebar | Global |
56
+ | `1` `2` `3` `4` `5` | Switch Sidebar tabs: **Files · Tags · Bookmarks · Outline · Tasks** | Global |
57
+ | `B` | Toggle Right Inspector (**Linked Mentions / Backlinks** & Outgoing Links) | Global |
58
+ | `Space` / `x` | Toggle live `- [ ]` / `- [x]` checkbox surgically in the `.md` file | Canvas / Tasks |
59
+ | `Enter` / `Backspace` / `Alt+←` | Follow `[[wikilink]]` / Navigate back in note history stack | Canvas |
60
+ | `a` / `n` / `b` | Quick Append · New Note · Bookmark | Global |
61
+ | `e` / `Ctrl+E` | Edit inline · Open in `$VISUAL` or `$EDITOR` and reindex on success | Note |
62
+ | `u` / `h` / `v` / `y` | Link Extractor · Toggle Inline Hrefs · HD Image Preview · Copy Code/Note | Global |
63
+ | `Ctrl+V` / `Ctrl+F` | Paste clipboard PNG into `Attachments/` · File Picker (`z` zoxide jump) | Global |
64
+ | `Ctrl+S` / `Ctrl+,` / `.` / `?` | Vault Switcher · Settings (5 Palettes) · Context Menu · Keybinding Help | Global |
65
+
66
+ ---
67
+
68
+ ## CLI, HTTP API & MCP
69
+
70
+ ### CLI (`--json` & `--vault` ready)
71
+
72
+ ```bash
73
+ # Discover, register, scaffold & reindex local vaults
74
+ obsidian vaults list --json
75
+ obsidian vaults add ~/Vaults/Work --name work
76
+ obsidian vaults use work
77
+ obsidian init ~/Vaults/Starter
78
+ obsidian reindex
79
+
80
+ # Search, read, author, daily notes & surgical checkbox toggles
81
+ obsidian search "Architecture" --json
82
+ obsidian notes list --folder Projects --json
83
+ obsidian notes read "Q4 Architecture RFC"
84
+ obsidian notes read "Q4 Architecture RFC" --json --compact
85
+ obsidian notes create "Sprint Retro" --folder Notes --tags "retro,q4"
86
+ obsidian notes append "Q4 Architecture RFC" -- "- [ ] Ship v0.1.0"
87
+ obs notes move "Q4 Architecture RFC" "Archive/Q4 Architecture RFC" --json
88
+ obsidian daily "--append=- [ ] Review PRs"
89
+ obsidian tasks --open --json
90
+ obsidian toggle-task "Q4 Architecture RFC" 14
91
+
92
+ # Knowledge Graph & Link Intelligence
93
+ obsidian backlinks "Q4 Architecture RFC" --json
94
+ obsidian links "Q4 Architecture RFC" --json
95
+ obsidian graph "Q4 Architecture RFC" --depth 2 --json
96
+ obsidian orphans --json
97
+ obsidian tags architecture --json
98
+
99
+ # Background watcher daemon & diagnostics
100
+ obsidian daemon start
101
+ obsidian doctor --json
102
+ ```
103
+
104
+ `notes read` prints raw Markdown. With `--json --compact`, it returns `rel_path`, `title`, and `raw_markdown`. Use `notes edit <NOTE>` for arbitrary body edits in your editor. The npm package provides `obsidian` and `obs` for the same CLI and MCP commands. Use `obs` when the desktop application's CLI is also registered on your PATH. [Obsidian CLI setup](https://obsidian.md/help/cli)
105
+
106
+ ### Local HTTP JSON API (`obsidian serve`)
107
+
108
+ ```bash
109
+ obsidian serve --bind 127.0.0.1 --port 8792 --token "$API_TOKEN"
110
+ curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8792/api/v1/search?q=Architecture"
111
+ curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8792/api/v1/graph?note=Q4%20Architecture%20RFC&depth=2"
112
+ ```
113
+
114
+ Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
115
+
116
+ ### MCP Server (`obsidian mcp` / `obs mcp` — 19 Tools)
117
+
118
+ ```json
119
+ {
120
+ "mcpServers": {
121
+ "obsidian": {
122
+ "command": "obsidian",
123
+ "args": ["mcp"]
124
+ }
125
+ }
126
+ }
127
+ ```
128
+
129
+ Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
130
+
131
+ `move_note` renames or moves a note within a vault and updates incoming wikilinks that need a new target. Use `append_note`, `toggle_task`, and `update_frontmatter` for edits to Markdown, checkboxes, and properties. [Editing surfaces and move examples](docs/MCP.md#read-and-edit-notes)
132
+
133
+ ---
134
+
135
+ ## `@bitefoundry` Enterprise Terminal Suite
136
+
137
+ | Package | Commands | Workspace | Interfaces |
138
+ | :--- | :--- | :--- | :--- |
139
+ | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
140
+ | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
141
+ | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote`, `note` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
142
+ | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `sp`, `onedrive`, `od` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
143
+ | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `jira`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
144
+ | [`@bitefoundry/notion`](https://www.npmjs.com/package/@bitefoundry/notion) | `notion`, `nt` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
145
+ | **`@bitefoundry/obsidian`** | `obsidian`, `obs` | Obsidian (Local Vaults, Backlinks & Interactive Knowledge Graph) | TUI · CLI · HTTP · MCP |
146
+
147
+ ---
148
+
149
+ > **Disclaimer:** Unofficial terminal client for Obsidian vaults. Not affiliated with, endorsed by, or sponsored by Dynalist Inc. (Obsidian).
package/docs/API.md ADDED
@@ -0,0 +1,32 @@
1
+ # `@bitefoundry/obsidian` Local HTTP JSON API
2
+
3
+ Start the local HTTP JSON server (default `127.0.0.1:8792`):
4
+
5
+ ```bash
6
+ obsidian serve --bind 127.0.0.1 --port 8792
7
+ # Optional Bearer authentication:
8
+ obsidian serve --port 8792 --token "my-local-secret"
9
+ ```
10
+
11
+ When `--token` is provided, include `Authorization: Bearer <token>` on all `/api/v1/*` requests.
12
+
13
+ ## Endpoints
14
+
15
+ | Method | Path | Description |
16
+ | :--- | :--- | :--- |
17
+ | `GET` | `/health` | Service health, version, active vault, and indexed note count |
18
+ | `GET` | `/api/v1/vaults` | List all auto-discovered and registered Obsidian vaults |
19
+ | `GET` | `/api/v1/search?q=...&limit=25&vault=...` | Full-text FTS5 search (+ automatic `<3`-char Korean/CJK `LIKE` fallback) |
20
+ | `GET` | `/api/v1/notes?folder=...&vault=...` | List notes in the vault, optionally filtered by folder prefix |
21
+ | `GET` | `/api/v1/notes/{*path}?vault=...` | Read full note Markdown, frontmatter, headings, tasks, backlinks & outgoing links |
22
+ | `POST` | `/api/v1/notes` | Create a new Markdown note atomically (`{ title, folder?, content?, tags?, vault? }`) |
23
+ | `POST` | `/api/v1/notes/append` | Append Markdown text to an existing note (`{ note, text, vault? }`) |
24
+ | `POST` | `/api/v1/daily` | Open or create today's Daily Note and optionally append (`{ date?, append?, vault? }`) |
25
+ | `GET` | `/api/v1/backlinks?note=...&vault=...` | Incoming linked mentions (backlinks) with surrounding context snippets |
26
+ | `GET` | `/api/v1/graph?note=...&depth=2&vault=...` | Local BFS knowledge graph (or global vault graph when `note` is omitted) |
27
+ | `GET` | `/api/v1/tags?tag=...&vault=...` | List all tags with counts, or list notes matching `tag` |
28
+ | `GET` | `/api/v1/tasks?status=open\|done\|all&note=...` | List Markdown checklist tasks across vault or within one note |
29
+ | `POST` | `/api/v1/tasks/toggle` | Surgically toggle `- [ ]` <-> `- [x]` at 1-based line (`{ note, line, vault? }`) |
30
+ | `POST` | `/api/v1/reindex` | Trigger immediate incremental filesystem scan & SQLite index refresh |
31
+
32
+ See **[openapi.yaml](openapi.yaml)** for the full OpenAPI 3.1 specification.
package/docs/MCP.md ADDED
@@ -0,0 +1,65 @@
1
+ # `@bitefoundry/obsidian` MCP Server (`obsidian mcp`)
2
+
3
+ `@bitefoundry/obsidian` ships a native stdio JSON-RPC 2.0 Model Context Protocol (MCP) server with **19 typed tools** operating directly on local vaults. Both npm commands, `obsidian mcp` and `obs mcp`, start this server. Use `obs` if your PATH also contains the desktop application's command. [Obsidian CLI setup](https://obsidian.md/help/cli)
4
+
5
+ ## Configuration
6
+
7
+ Add to Claude Desktop, Cursor, Windsurf, or any MCP-compatible host:
8
+
9
+ ```json
10
+ {
11
+ "mcpServers": {
12
+ "obsidian": {
13
+ "command": "obsidian",
14
+ "args": ["mcp"]
15
+ }
16
+ }
17
+ }
18
+ ```
19
+
20
+ Optionally pin a specific vault via `"args": ["--vault", "My Vault", "mcp"]` or `"env": { "OBSIDIAN_VAULT": "My Vault" }`.
21
+
22
+ ## Tool Catalog (19 Tools)
23
+
24
+ | # | Tool | Arguments | Purpose |
25
+ | :-: | :--- | :--- | :--- |
26
+ | 1 | `list_vaults` | *(none)* | List auto-discovered & registered Obsidian vaults with note counts |
27
+ | 2 | `search_notes` | `query`, `limit?`, `vault?` | SQLite FTS5 search with `<3`-char Korean/CJK `LIKE` fallback |
28
+ | 3 | `read_note` | `note`, `compact?`, `vault?` | Read raw Markdown, frontmatter, tags, headings, tasks, backlinks & outgoing links |
29
+ | 4 | `list_notes` | `folder?`, `vault?` | List notes in the vault, optionally filtered by folder prefix |
30
+ | 5 | `create_note` | `title`, `folder?`, `content?`, `tags?`, `vault?` | Create a new `.md` note atomically with YAML frontmatter |
31
+ | 6 | `append_note` | `note`, `text`, `vault?` | Append Markdown text, tasks, or callouts atomically |
32
+ | 7 | `update_frontmatter` | `note`, `properties`, `vault?` | Set or delete (`null`) top-level YAML properties |
33
+ | 8 | `delete_note` | `note`, `confirm` (`true`), `vault?` | Safely move a note into `<vault>/.trash/` (requires `confirm: true`) |
34
+ | 9 | `daily_note` | `date?`, `append?`, `vault?` | Open or create today's Daily Note and optionally append text |
35
+ | 10 | `get_backlinks` | `note`, `vault?` | Return incoming linked mentions (backlinks) with snippet context |
36
+ | 11 | `get_outgoing_links` | `note`, `vault?` | Return outgoing wikilinks and embeds (resolved & unresolved) |
37
+ | 12 | `get_local_graph` | `note?`, `depth?`, `vault?` | Return local BFS neighborhood (or global vault graph when `note` omitted) |
38
+ | 13 | `list_tags` | `vault?` | List all inline and frontmatter `#tags` with note counts |
39
+ | 14 | `find_by_tag` | `tag`, `vault?` | Find all notes matching a tag (including nested subtags) |
40
+ | 15 | `list_tasks` | `status?`, `note?`, `vault?` | List Markdown checklist tasks (`all`, `open`, or `done`) |
41
+ | 16 | `toggle_task` | `note`, `line`, `expected_text?`, `expected_checked?`, `expected_mtime_ms?`, `vault?` | Toggle a Markdown checkbox at an exact 1-based line number, with optional conflict checks |
42
+ | 17 | `find_orphans` | `vault?` | Find orphan notes with 0 backlinks and 0 outgoing links |
43
+ | 18 | `reindex_vault` | `vault?` | Trigger immediate incremental scan & SQLite FTS5/graph reindex |
44
+ | 19 | `move_note` | `src`, `dst`, `vault?` | Move or rename a note within its vault and update incoming wikilinks that need a new target |
45
+
46
+ ## Read and edit notes
47
+
48
+ Call `read_note` with `{"note":"Projects/Review.md","compact":true}` to get `rel_path`, `title`, and `raw_markdown`. Omit `compact` for metadata and links.
49
+
50
+ - For arbitrary Markdown edits, use `obs notes edit <NOTE>`, TUI `e` for inline editing, or TUI `Ctrl+E` for an external editor.
51
+ - Use MCP `append_note` to add Markdown with its indentation and trailing spaces intact. The CLI form is `obs notes append <NOTE> -- <TEXT>`.
52
+ - Use MCP `toggle_task` or `obs toggle-task <NOTE> <LINE>` for a checkbox. To change YAML properties, call MCP `update_frontmatter` with a properties object such as `{"status":"ready","obsolete":null}`. This sets `status` and removes `obsolete`.
53
+ - For HTTP edit routes, see the append and task toggle entries in the [HTTP API catalog](API.md).
54
+
55
+ ### Move or rename a note
56
+
57
+ Call `move_note` with these arguments, or run `obs notes move "Release Review" "Archive/Release Review" --json`.
58
+
59
+ ```json
60
+ {"src":"Release Review","dst":"Archive/Release Review","vault":"work"}
61
+ ```
62
+
63
+ `src` accepts a vault-relative path, note title, or frontmatter alias. `dst` gives the new path and filename within the selected vault. The command adds `.md` when omitted, creates missing parent directories, and rejects an existing destination.
64
+
65
+ Both surfaces report `moved`, `from`, `to`, `updated_links_in_notes`, and `bookmark_preserved`. The link count is the number of files rewritten. Matching wikilinks keep heading and block fragments, display text, and the embed marker. Wikilinks in inline and fenced code stay literal. To adjust Markdown-style `[label](path)` destinations, edit their source notes. [Obsidian internal link formats](https://obsidian.md/help/links)
package/docs/NPM.md CHANGED
@@ -1,29 +1,47 @@
1
- # npm Cross-Platform Packaging (`@bitefoundry/obsidian`)
2
-
3
- `@bitefoundry/obsidian` distributes prebuilt native Rust binaries across 6 OS/CPU targets via npm `optionalDependencies` and a zero-Node-process `postinstall` linker.
4
-
5
- ## Published Packages
6
-
7
- | Package | OS | Arch | Rust Target |
8
- | :--- | :--- | :--- | :--- |
9
- | `@bitefoundry/obsidian` | All | All | Root CLI wrapper (`obsidian`, `obs`) |
10
- | `@bitefoundry/obsidian-win32-x64` | Windows | x64 | `x86_64-pc-windows-msvc` |
11
- | `@bitefoundry/obsidian-win32-arm64` | Windows | arm64 | `aarch64-pc-windows-msvc` |
12
- | `@bitefoundry/obsidian-darwin-x64` | macOS (`>= 11.0`) | x64 | `x86_64-apple-darwin` |
13
- | `@bitefoundry/obsidian-darwin-arm64` | macOS (`>= 11.0`) | arm64 | `aarch64-apple-darwin` |
14
- | `@bitefoundry/obsidian-linux-x64` | Linux (`GLIBC >= 2.28`) | x64 | `x86_64-unknown-linux-gnu` |
15
- | `@bitefoundry/obsidian-linux-arm64` | Linux (`GLIBC >= 2.28`) | arm64 | `aarch64-unknown-linux-gnu` |
16
-
17
- ## Compatibility Guarantees
18
-
19
- - **Linux**: Built with `cargo-zigbuild` targeting `GLIBC 2.28` and verified in CI via `node scripts/verify-glibc.mjs --max 2.28` + AlmaLinux 8 container smoke test.
20
- - **macOS**: Built with `MACOSX_DEPLOYMENT_TARGET=11.0` (Big Sur and newer).
21
- - **Zero-Auth, Zero-Native-Keyring**: 100% pure Rust + bundled SQLite — no `libsecret` or system DBus runtime dependencies.
22
-
23
- ## Maintenance Scripts
24
-
25
- ```bash
26
- node scripts/sync-version.mjs --check # Verify Cargo.toml + all 7 package.json versions match
27
- node scripts/verify-glibc.mjs --self-test # Run ELF GLIBC parser self-tests
28
- node scripts/build-npm.mjs --all # Stage release binaries into npm/obsidian-*/bin
29
- ```
1
+ # npm Cross-Platform Packaging (`@bitefoundry/obsidian`)
2
+
3
+ `@bitefoundry/obsidian` distributes prebuilt native Rust binaries across 6 OS/CPU targets via npm `optionalDependencies` and a zero-Node-process `postinstall` linker.
4
+
5
+ ## Published Packages
6
+
7
+ | Package | OS | Arch | Rust Target |
8
+ | :--- | :--- | :--- | :--- |
9
+ | `@bitefoundry/obsidian` | All | All | Root CLI wrapper (`obsidian`, `obs`) |
10
+ | `@bitefoundry/obsidian-win32-x64` | Windows | x64 | `x86_64-pc-windows-msvc` |
11
+ | `@bitefoundry/obsidian-win32-arm64` | Windows | arm64 | `aarch64-pc-windows-msvc` |
12
+ | `@bitefoundry/obsidian-darwin-x64` | macOS (`>= 11.0`) | x64 | `x86_64-apple-darwin` |
13
+ | `@bitefoundry/obsidian-darwin-arm64` | macOS (`>= 11.0`) | arm64 | `aarch64-apple-darwin` |
14
+ | `@bitefoundry/obsidian-linux-x64` | Linux (`GLIBC >= 2.28`) | x64 | `x86_64-unknown-linux-gnu` |
15
+ | `@bitefoundry/obsidian-linux-arm64` | Linux (`GLIBC >= 2.28`) | arm64 | `aarch64-unknown-linux-gnu` |
16
+
17
+ ## Compatibility Guarantees
18
+
19
+ - **Linux**: Built with `cargo-zigbuild` targeting `GLIBC 2.28` and verified in CI via `node scripts/verify-glibc.mjs --max 2.28` + AlmaLinux 8 container smoke test.
20
+ - **macOS**: Built with `MACOSX_DEPLOYMENT_TARGET=11.0` (Big Sur and newer).
21
+ - **Local vault access**: SQLite and the YAML parser are bundled with the binary. Local vaults require no cloud sign-in, `libsecret`, or system DBus.
22
+
23
+ ## Maintenance Scripts
24
+
25
+ ```bash
26
+ node scripts/sync-version.mjs --check # Verify Cargo.toml + all 7 package.json versions match
27
+ node scripts/verify-glibc.mjs --self-test # Run ELF GLIBC parser self-tests
28
+ node scripts/build-npm.mjs --all # Stage release binaries into npm/obsidian-*/bin
29
+ ```
30
+
31
+ ## Checklist smoke test
32
+
33
+ Run the unpacked package's launcher against a temporary vault. Both commands should exit successfully and write the checklist text to the corresponding Markdown file.
34
+
35
+ ```bash
36
+ scratch="$(mktemp -d)"
37
+ export OBSIDIAN_CONFIG_DIR="$scratch/config"
38
+ export OBSIDIAN_DATA_DIR="$scratch/data"
39
+ export OBSIDIAN_APP_CONFIG_PATH="$scratch/obsidian.json"
40
+ export OBSIDIAN_AUTO_DAEMON=0
41
+ printf '%s\n' '{"vaults":{}}' > "$OBSIDIAN_APP_CONFIG_PATH"
42
+ vault="$scratch/vault"
43
+ obsidian init "$vault"
44
+ obsidian --vault "$vault" notes create "Release Review"
45
+ obsidian --vault "$vault" notes append "Release Review" -- "- [ ] Ship v0.1.0"
46
+ obsidian --vault "$vault" daily "--append=- [ ] Review PRs"
47
+ ```
@@ -0,0 +1,137 @@
1
+ openapi: 3.1.0
2
+ info:
3
+ title: "@bitefoundry/obsidian Local HTTP API"
4
+ version: "0.1.0"
5
+ description: Local HTTP JSON API for Obsidian vaults, FTS5 search, backlinks, knowledge graph, tasks, and daily notes (`obsidian serve`, default `:8792`).
6
+ servers:
7
+ - url: http://127.0.0.1:8792
8
+ paths:
9
+ /health:
10
+ get:
11
+ summary: Service health and active vault status
12
+ responses:
13
+ "200":
14
+ description: Healthy service metadata
15
+ /api/v1/vaults:
16
+ get:
17
+ summary: List auto-discovered and registered Obsidian vaults
18
+ responses:
19
+ "200":
20
+ description: Vault summaries
21
+ /api/v1/search:
22
+ get:
23
+ summary: Full-text FTS5 search with Korean/CJK LIKE fallback
24
+ parameters:
25
+ - name: q
26
+ in: query
27
+ required: true
28
+ schema: { type: string }
29
+ - name: limit
30
+ in: query
31
+ schema: { type: integer, default: 25 }
32
+ - name: vault
33
+ in: query
34
+ schema: { type: string }
35
+ responses:
36
+ "200":
37
+ description: Matching notes with snippets
38
+ /api/v1/notes:
39
+ get:
40
+ summary: List notes in the vault
41
+ parameters:
42
+ - name: folder
43
+ in: query
44
+ schema: { type: string }
45
+ - name: vault
46
+ in: query
47
+ schema: { type: string }
48
+ responses:
49
+ "200":
50
+ description: Note summaries
51
+ post:
52
+ summary: Create a new Markdown note atomically
53
+ responses:
54
+ "201":
55
+ description: Created note
56
+ /api/v1/notes/{path}:
57
+ get:
58
+ summary: Read note Markdown, frontmatter, headings, tasks, backlinks & outgoing links
59
+ parameters:
60
+ - name: path
61
+ in: path
62
+ required: true
63
+ schema: { type: string }
64
+ responses:
65
+ "200":
66
+ description: Note detail
67
+ /api/v1/notes/append:
68
+ post:
69
+ summary: Append Markdown text to an existing note
70
+ responses:
71
+ "200":
72
+ description: Appended successfully
73
+ /api/v1/daily:
74
+ post:
75
+ summary: Open or create today's Daily Note and optionally append text
76
+ responses:
77
+ "200":
78
+ description: Daily note payload
79
+ /api/v1/backlinks:
80
+ get:
81
+ summary: Incoming linked mentions (backlinks) to a note
82
+ parameters:
83
+ - name: note
84
+ in: query
85
+ required: true
86
+ schema: { type: string }
87
+ responses:
88
+ "200":
89
+ description: Backlink entries with context snippets
90
+ /api/v1/graph:
91
+ get:
92
+ summary: Local BFS or global vault knowledge graph
93
+ parameters:
94
+ - name: note
95
+ in: query
96
+ schema: { type: string }
97
+ - name: depth
98
+ in: query
99
+ schema: { type: integer, default: 2 }
100
+ responses:
101
+ "200":
102
+ description: Graph nodes and edges
103
+ /api/v1/tags:
104
+ get:
105
+ summary: List tags with counts or find notes by tag
106
+ parameters:
107
+ - name: tag
108
+ in: query
109
+ schema: { type: string }
110
+ responses:
111
+ "200":
112
+ description: Tag counts or tagged notes
113
+ /api/v1/tasks:
114
+ get:
115
+ summary: List Markdown checklist tasks
116
+ parameters:
117
+ - name: status
118
+ in: query
119
+ schema: { type: string, enum: [all, open, done] }
120
+ - name: note
121
+ in: query
122
+ schema: { type: string }
123
+ responses:
124
+ "200":
125
+ description: Task entries
126
+ /api/v1/tasks/toggle:
127
+ post:
128
+ summary: Toggle a Markdown checkbox at a 1-based line number
129
+ responses:
130
+ "200":
131
+ description: Updated checkbox state
132
+ /api/v1/reindex:
133
+ post:
134
+ summary: Trigger incremental filesystem scan & SQLite FTS5 reindex
135
+ responses:
136
+ "200":
137
+ description: Index statistics
package/package.json CHANGED
@@ -1,52 +1,55 @@
1
- {
2
- "name": "@bitefoundry/obsidian",
3
- "version": "0.1.2",
4
- "description": "Obsidian-native terminal workspace, interactive knowledge graph & AI agent toolkit — Local Vaults, Backlinks, Graph View, CLI, TUI, HTTP API & MCP",
5
- "repository": {
6
- "type": "git",
7
- "url": "git+https://github.com/BiteFoundry/obsidian.git"
8
- },
9
- "license": "MIT",
10
- "bin": {
11
- "obsidian": "bin/obsidian.js",
12
- "obs": "bin/obs.js"
13
- },
14
- "files": [
15
- "bin/obsidian.js",
16
- "bin/obs.js",
17
- "scripts/postinstall.mjs",
18
- "docs/NPM.md",
19
- "README.md"
20
- ],
21
- "engines": {
22
- "node": ">=18"
23
- },
24
- "keywords": [
25
- "obsidian",
26
- "obsidian-cli",
27
- "obsidian-tui",
28
- "obs",
29
- "knowledge-graph",
30
- "second-brain",
31
- "pkm",
32
- "markdown",
33
- "wikilinks",
34
- "backlinks",
35
- "cli",
36
- "tui",
37
- "mcp"
38
- ],
39
- "scripts": {
40
- "postinstall": "node scripts/postinstall.mjs",
41
- "sync-version": "node scripts/sync-version.mjs",
42
- "build:npm": "node scripts/build-npm.mjs"
43
- },
44
- "optionalDependencies": {
45
- "@bitefoundry/obsidian-win32-x64": "0.1.2",
46
- "@bitefoundry/obsidian-win32-arm64": "0.1.2",
47
- "@bitefoundry/obsidian-darwin-x64": "0.1.2",
48
- "@bitefoundry/obsidian-darwin-arm64": "0.1.2",
49
- "@bitefoundry/obsidian-linux-x64": "0.1.2",
50
- "@bitefoundry/obsidian-linux-arm64": "0.1.2"
51
- }
52
- }
1
+ {
2
+ "name": "@bitefoundry/obsidian",
3
+ "version": "0.1.4",
4
+ "description": "Obsidian-native terminal workspace, interactive knowledge graph & AI agent toolkit — Local Vaults, Backlinks, Graph View, CLI, TUI, HTTP API & MCP",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/BiteFoundry/obsidian.git"
8
+ },
9
+ "license": "MIT",
10
+ "bin": {
11
+ "obsidian": "bin/obsidian.js",
12
+ "obs": "bin/obs.js"
13
+ },
14
+ "files": [
15
+ "bin/obsidian.js",
16
+ "bin/obs.js",
17
+ "scripts/postinstall.mjs",
18
+ "docs/NPM.md",
19
+ "docs/API.md",
20
+ "docs/MCP.md",
21
+ "docs/openapi.yaml",
22
+ "README.md"
23
+ ],
24
+ "engines": {
25
+ "node": ">=18"
26
+ },
27
+ "keywords": [
28
+ "obsidian",
29
+ "obsidian-cli",
30
+ "obsidian-tui",
31
+ "obs",
32
+ "knowledge-graph",
33
+ "second-brain",
34
+ "pkm",
35
+ "markdown",
36
+ "wikilinks",
37
+ "backlinks",
38
+ "cli",
39
+ "tui",
40
+ "mcp"
41
+ ],
42
+ "scripts": {
43
+ "postinstall": "node scripts/postinstall.mjs",
44
+ "sync-version": "node scripts/sync-version.mjs",
45
+ "build:npm": "node scripts/build-npm.mjs"
46
+ },
47
+ "optionalDependencies": {
48
+ "@bitefoundry/obsidian-win32-x64": "0.1.4",
49
+ "@bitefoundry/obsidian-win32-arm64": "0.1.4",
50
+ "@bitefoundry/obsidian-darwin-x64": "0.1.4",
51
+ "@bitefoundry/obsidian-darwin-arm64": "0.1.4",
52
+ "@bitefoundry/obsidian-linux-x64": "0.1.4",
53
+ "@bitefoundry/obsidian-linux-arm64": "0.1.4"
54
+ }
55
+ }
@@ -1,259 +1,259 @@
1
- #!/usr/bin/env node
2
- // Zero-Node-Process npm native binary linker.
3
- //
4
- // On Unix (linux/darwin): replaces installed `bin/obsidian.js` and `bin/obs.js` with
5
- // hardlinks/symlinks directly to `@bitefoundry/obsidian-<platform>-<arch>/bin/obsidian` so npm's
6
- // bin symlink execve's the native Rust binary directly (0ms Node startup, 0MB Node RSS).
7
- //
8
- // On Windows (win32): creates NTFS hardlinks (fallback copy) `bin/obsidian.exe` & `bin/obs.exe`
9
- // and rewrites npm's `.bin/{obsidian,obs}[.cmd|.ps1]` shims when present to invoke
10
- // the native executable directly without spawning `node.exe`.
11
-
12
- import fs from 'node:fs';
13
- import path from 'node:path';
14
- import { createRequire } from 'node:module';
15
- import { fileURLToPath } from 'node:url';
16
-
17
- const BIN_NAMES = ['obsidian', 'obs'];
18
- const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
19
-
20
- function linkOrCopyFile(source, destination) {
21
- const tmp = `${destination}.tmp-${process.pid}`;
22
- try {
23
- fs.rmSync(tmp, { force: true });
24
- } catch {
25
- // Ignore cleanup errors on nonexistent temp paths.
26
- }
27
- try {
28
- fs.linkSync(source, tmp);
29
- } catch {
30
- fs.copyFileSync(source, tmp);
31
- }
32
- try {
33
- fs.renameSync(tmp, destination);
34
- } catch {
35
- try {
36
- fs.rmSync(destination, { force: true });
37
- } catch {
38
- // Ignore; renameSync below will surface or fail safely.
39
- }
40
- fs.renameSync(tmp, destination);
41
- }
42
- }
43
-
44
- function replaceJsWithNativeLinkUnix(binaryPath, destinationJs) {
45
- const tmp = `${destinationJs}.tmp-${process.pid}`;
46
- try {
47
- fs.rmSync(tmp, { force: true });
48
- } catch {
49
- // Ignore cleanup errors.
50
- }
51
- try {
52
- fs.linkSync(binaryPath, tmp);
53
- } catch {
54
- try {
55
- fs.rmSync(tmp, { force: true });
56
- } catch {
57
- // Ignore cleanup errors.
58
- }
59
- fs.symlinkSync(binaryPath, tmp);
60
- }
61
- try {
62
- fs.renameSync(tmp, destinationJs);
63
- } catch (err) {
64
- try {
65
- fs.rmSync(tmp, { force: true });
66
- } catch {
67
- // Ignore cleanup errors.
68
- }
69
- throw err;
70
- }
71
- }
72
-
73
- function collectWindowsShimDirs(pkgRoot, env = process.env) {
74
- const dirs = [];
75
- const parentScope = path.dirname(pkgRoot);
76
- const nodeModulesDir = path.dirname(parentScope);
77
- if (
78
- path.basename(parentScope) === '@bitefoundry' &&
79
- path.basename(nodeModulesDir) === 'node_modules'
80
- ) {
81
- dirs.push(path.join(nodeModulesDir, '.bin'));
82
- dirs.push(path.dirname(nodeModulesDir));
83
- }
84
-
85
- if (env.npm_config_global === 'true' && env.npm_config_prefix) {
86
- const prefix = path.resolve(env.npm_config_prefix);
87
- dirs.push(prefix);
88
- dirs.push(path.join(prefix, 'bin'));
89
- }
90
-
91
- return [...new Set(dirs)];
92
- }
93
-
94
- function shimReferencesLauncher(content, name) {
95
- const normalized = content.replace(/\\/g, '/').toLowerCase();
96
- return (
97
- normalized.includes('@bitefoundry/obsidian') &&
98
- normalized.includes(`bin/${name}.js`)
99
- );
100
- }
101
-
102
- function rewriteWindowsShims(shimDir, pkgRoot) {
103
- if (!fs.existsSync(shimDir)) return 0;
104
- let rewritten = 0;
105
-
106
- for (const name of BIN_NAMES) {
107
- const exePath = path.join(pkgRoot, 'bin', `${name}.exe`);
108
- if (!fs.existsSync(exePath)) continue;
109
-
110
- const relWin = path.relative(shimDir, exePath).replace(/\//g, '\\');
111
- const relPosix = path.relative(shimDir, exePath).replace(/\\/g, '/');
112
-
113
- const cmdPath = path.join(shimDir, `${name}.cmd`);
114
- try {
115
- if (fs.existsSync(cmdPath)) {
116
- const content = fs.readFileSync(cmdPath, 'utf8');
117
- if (shimReferencesLauncher(content, name)) {
118
- fs.writeFileSync(cmdPath, `@ECHO off\r\n"%~dp0${relWin}" %*\r\n`, 'utf8');
119
- rewritten += 1;
120
- }
121
- }
122
- } catch {
123
- // Fall back cleanly.
124
- }
125
-
126
- const ps1Path = path.join(shimDir, `${name}.ps1`);
127
- try {
128
- if (fs.existsSync(ps1Path)) {
129
- const content = fs.readFileSync(ps1Path, 'utf8');
130
- if (shimReferencesLauncher(content, name)) {
131
- const ps1Body = [
132
- '#!/usr/bin/env pwsh',
133
- '$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent',
134
- `$exePath = Join-Path $basedir '${relWin.replace(/'/g, "''")}'`,
135
- 'if ($MyInvocation.ExpectingInput) {',
136
- ' $input | & $exePath @args',
137
- '} else {',
138
- ' & $exePath @args',
139
- '}',
140
- 'exit $LASTEXITCODE',
141
- '',
142
- ].join('\n');
143
- fs.writeFileSync(ps1Path, ps1Body, 'utf8');
144
- rewritten += 1;
145
- }
146
- }
147
- } catch {
148
- // Fall back cleanly.
149
- }
150
-
151
- const shPath = path.join(shimDir, name);
152
- try {
153
- if (fs.existsSync(shPath)) {
154
- const content = fs.readFileSync(shPath, 'utf8');
155
- if (shimReferencesLauncher(content, name)) {
156
- const shBody = [
157
- '#!/bin/sh',
158
- 'basedir=$(dirname "$(echo "$0" | sed -e \'s,\\\\,/,g\')")',
159
- `exec "$basedir/${relPosix}" "$@"`,
160
- '',
161
- ].join('\n');
162
- fs.writeFileSync(shPath, shBody, 'utf8');
163
- rewritten += 1;
164
- }
165
- }
166
- } catch {
167
- // Fall back cleanly.
168
- }
169
- }
170
-
171
- return rewritten;
172
- }
173
-
174
- export function runPostinstall(options = {}) {
175
- const pkgRoot = path.resolve(options.pkgRoot || PKG_ROOT);
176
- const platform = options.platform || process.platform;
177
- const arch = options.arch || process.arch;
178
- const env = options.env || process.env;
179
-
180
- if (
181
- fs.existsSync(path.join(pkgRoot, 'Cargo.toml')) ||
182
- fs.existsSync(path.join(pkgRoot, '.git'))
183
- ) {
184
- return { skipped: true, reason: 'dev_repo' };
185
- }
186
-
187
- const platformKey = `${platform}-${arch}`;
188
- const packageName = `@bitefoundry/obsidian-${platformKey}`;
189
- const binaryName = platform === 'win32' ? 'obsidian.exe' : 'obsidian';
190
-
191
- let packageDir = null;
192
- try {
193
- const requireFromPkg = createRequire(path.join(pkgRoot, 'package.json'));
194
- packageDir = path.dirname(requireFromPkg.resolve(`${packageName}/package.json`));
195
- } catch {
196
- packageDir = null;
197
- }
198
-
199
- const binaryPath = packageDir ? path.join(packageDir, 'bin', binaryName) : null;
200
- if (!binaryPath || !fs.existsSync(binaryPath)) {
201
- return { skipped: true, reason: 'missing_platform_binary' };
202
- }
203
-
204
- const binDir = path.join(pkgRoot, 'bin');
205
- if (!fs.existsSync(binDir)) {
206
- return { skipped: true, reason: 'missing_bin_dir' };
207
- }
208
-
209
- if (platform === 'win32') {
210
- let linked = 0;
211
- for (const name of BIN_NAMES) {
212
- const destExe = path.join(binDir, `${name}.exe`);
213
- try {
214
- linkOrCopyFile(binaryPath, destExe);
215
- linked += 1;
216
- } catch {
217
- // Leave fallback JS launcher untouched.
218
- }
219
- }
220
-
221
- let shimsRewritten = 0;
222
- for (const shimDir of collectWindowsShimDirs(pkgRoot, env)) {
223
- try {
224
- shimsRewritten += rewriteWindowsShims(shimDir, pkgRoot);
225
- } catch {
226
- // Never fail npm install on read-only or custom shims.
227
- }
228
- }
229
- return { skipped: false, platform, linked, shimsRewritten };
230
- }
231
-
232
- try {
233
- fs.chmodSync(binaryPath, 0o755);
234
- } catch {
235
- // Ignore on read-only stores.
236
- }
237
-
238
- let linked = 0;
239
- for (const name of BIN_NAMES) {
240
- const destJs = path.join(binDir, `${name}.js`);
241
- try {
242
- replaceJsWithNativeLinkUnix(binaryPath, destJs);
243
- linked += 1;
244
- } catch {
245
- // Leave fallback JS launcher intact.
246
- }
247
- }
248
-
249
- return { skipped: false, platform, linked };
250
- }
251
-
252
- if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
253
- try {
254
- runPostinstall();
255
- } catch {
256
- // Postinstall optimization must never fail npm install.
257
- }
258
- process.exit(0);
259
- }
1
+ #!/usr/bin/env node
2
+ // Zero-Node-Process npm native binary linker.
3
+ //
4
+ // On Unix (linux/darwin): replaces installed `bin/obsidian.js` and `bin/obs.js` with
5
+ // hardlinks/symlinks directly to `@bitefoundry/obsidian-<platform>-<arch>/bin/obsidian` so npm's
6
+ // bin symlink execve's the native Rust binary directly (0ms Node startup, 0MB Node RSS).
7
+ //
8
+ // On Windows (win32): creates NTFS hardlinks (fallback copy) `bin/obsidian.exe` & `bin/obs.exe`
9
+ // and rewrites npm's `.bin/{obsidian,obs}[.cmd|.ps1]` shims when present to invoke
10
+ // the native executable directly without spawning `node.exe`.
11
+
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+ import { createRequire } from 'node:module';
15
+ import { fileURLToPath } from 'node:url';
16
+
17
+ const BIN_NAMES = ['obsidian', 'obs'];
18
+ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
19
+
20
+ function linkOrCopyFile(source, destination) {
21
+ const tmp = `${destination}.tmp-${process.pid}`;
22
+ try {
23
+ fs.rmSync(tmp, { force: true });
24
+ } catch {
25
+ // Ignore cleanup errors on nonexistent temp paths.
26
+ }
27
+ try {
28
+ fs.linkSync(source, tmp);
29
+ } catch {
30
+ fs.copyFileSync(source, tmp);
31
+ }
32
+ try {
33
+ fs.renameSync(tmp, destination);
34
+ } catch {
35
+ try {
36
+ fs.rmSync(destination, { force: true });
37
+ } catch {
38
+ // Ignore; renameSync below will surface or fail safely.
39
+ }
40
+ fs.renameSync(tmp, destination);
41
+ }
42
+ }
43
+
44
+ function replaceJsWithNativeLinkUnix(binaryPath, destinationJs) {
45
+ const tmp = `${destinationJs}.tmp-${process.pid}`;
46
+ try {
47
+ fs.rmSync(tmp, { force: true });
48
+ } catch {
49
+ // Ignore cleanup errors.
50
+ }
51
+ try {
52
+ fs.linkSync(binaryPath, tmp);
53
+ } catch {
54
+ try {
55
+ fs.rmSync(tmp, { force: true });
56
+ } catch {
57
+ // Ignore cleanup errors.
58
+ }
59
+ fs.symlinkSync(binaryPath, tmp);
60
+ }
61
+ try {
62
+ fs.renameSync(tmp, destinationJs);
63
+ } catch (err) {
64
+ try {
65
+ fs.rmSync(tmp, { force: true });
66
+ } catch {
67
+ // Ignore cleanup errors.
68
+ }
69
+ throw err;
70
+ }
71
+ }
72
+
73
+ function collectWindowsShimDirs(pkgRoot, env = process.env) {
74
+ const dirs = [];
75
+ const parentScope = path.dirname(pkgRoot);
76
+ const nodeModulesDir = path.dirname(parentScope);
77
+ if (
78
+ path.basename(parentScope) === '@bitefoundry' &&
79
+ path.basename(nodeModulesDir) === 'node_modules'
80
+ ) {
81
+ dirs.push(path.join(nodeModulesDir, '.bin'));
82
+ dirs.push(path.dirname(nodeModulesDir));
83
+ }
84
+
85
+ if (env.npm_config_global === 'true' && env.npm_config_prefix) {
86
+ const prefix = path.resolve(env.npm_config_prefix);
87
+ dirs.push(prefix);
88
+ dirs.push(path.join(prefix, 'bin'));
89
+ }
90
+
91
+ return [...new Set(dirs)];
92
+ }
93
+
94
+ function shimReferencesLauncher(content, name) {
95
+ const normalized = content.replace(/\\/g, '/').toLowerCase();
96
+ return (
97
+ normalized.includes('@bitefoundry/obsidian') &&
98
+ normalized.includes(`bin/${name}.js`)
99
+ );
100
+ }
101
+
102
+ function rewriteWindowsShims(shimDir, pkgRoot) {
103
+ if (!fs.existsSync(shimDir)) return 0;
104
+ let rewritten = 0;
105
+
106
+ for (const name of BIN_NAMES) {
107
+ const exePath = path.join(pkgRoot, 'bin', `${name}.exe`);
108
+ if (!fs.existsSync(exePath)) continue;
109
+
110
+ const relWin = path.relative(shimDir, exePath).replace(/\//g, '\\');
111
+ const relPosix = path.relative(shimDir, exePath).replace(/\\/g, '/');
112
+
113
+ const cmdPath = path.join(shimDir, `${name}.cmd`);
114
+ try {
115
+ if (fs.existsSync(cmdPath)) {
116
+ const content = fs.readFileSync(cmdPath, 'utf8');
117
+ if (shimReferencesLauncher(content, name)) {
118
+ fs.writeFileSync(cmdPath, `@ECHO off\r\n"%~dp0${relWin}" %*\r\n`, 'utf8');
119
+ rewritten += 1;
120
+ }
121
+ }
122
+ } catch {
123
+ // Fall back cleanly.
124
+ }
125
+
126
+ const ps1Path = path.join(shimDir, `${name}.ps1`);
127
+ try {
128
+ if (fs.existsSync(ps1Path)) {
129
+ const content = fs.readFileSync(ps1Path, 'utf8');
130
+ if (shimReferencesLauncher(content, name)) {
131
+ const ps1Body = [
132
+ '#!/usr/bin/env pwsh',
133
+ '$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent',
134
+ `$exePath = Join-Path $basedir '${relWin.replace(/'/g, "''")}'`,
135
+ 'if ($MyInvocation.ExpectingInput) {',
136
+ ' $input | & $exePath @args',
137
+ '} else {',
138
+ ' & $exePath @args',
139
+ '}',
140
+ 'exit $LASTEXITCODE',
141
+ '',
142
+ ].join('\n');
143
+ fs.writeFileSync(ps1Path, ps1Body, 'utf8');
144
+ rewritten += 1;
145
+ }
146
+ }
147
+ } catch {
148
+ // Fall back cleanly.
149
+ }
150
+
151
+ const shPath = path.join(shimDir, name);
152
+ try {
153
+ if (fs.existsSync(shPath)) {
154
+ const content = fs.readFileSync(shPath, 'utf8');
155
+ if (shimReferencesLauncher(content, name)) {
156
+ const shBody = [
157
+ '#!/bin/sh',
158
+ 'basedir=$(dirname "$(echo "$0" | sed -e \'s,\\\\,/,g\')")',
159
+ `exec "$basedir/${relPosix}" "$@"`,
160
+ '',
161
+ ].join('\n');
162
+ fs.writeFileSync(shPath, shBody, 'utf8');
163
+ rewritten += 1;
164
+ }
165
+ }
166
+ } catch {
167
+ // Fall back cleanly.
168
+ }
169
+ }
170
+
171
+ return rewritten;
172
+ }
173
+
174
+ export function runPostinstall(options = {}) {
175
+ const pkgRoot = path.resolve(options.pkgRoot || PKG_ROOT);
176
+ const platform = options.platform || process.platform;
177
+ const arch = options.arch || process.arch;
178
+ const env = options.env || process.env;
179
+
180
+ if (
181
+ fs.existsSync(path.join(pkgRoot, 'Cargo.toml')) ||
182
+ fs.existsSync(path.join(pkgRoot, '.git'))
183
+ ) {
184
+ return { skipped: true, reason: 'dev_repo' };
185
+ }
186
+
187
+ const platformKey = `${platform}-${arch}`;
188
+ const packageName = `@bitefoundry/obsidian-${platformKey}`;
189
+ const binaryName = platform === 'win32' ? 'obsidian.exe' : 'obsidian';
190
+
191
+ let packageDir = null;
192
+ try {
193
+ const requireFromPkg = createRequire(path.join(pkgRoot, 'package.json'));
194
+ packageDir = path.dirname(requireFromPkg.resolve(`${packageName}/package.json`));
195
+ } catch {
196
+ packageDir = null;
197
+ }
198
+
199
+ const binaryPath = packageDir ? path.join(packageDir, 'bin', binaryName) : null;
200
+ if (!binaryPath || !fs.existsSync(binaryPath)) {
201
+ return { skipped: true, reason: 'missing_platform_binary' };
202
+ }
203
+
204
+ const binDir = path.join(pkgRoot, 'bin');
205
+ if (!fs.existsSync(binDir)) {
206
+ return { skipped: true, reason: 'missing_bin_dir' };
207
+ }
208
+
209
+ if (platform === 'win32') {
210
+ let linked = 0;
211
+ for (const name of BIN_NAMES) {
212
+ const destExe = path.join(binDir, `${name}.exe`);
213
+ try {
214
+ linkOrCopyFile(binaryPath, destExe);
215
+ linked += 1;
216
+ } catch {
217
+ // Leave fallback JS launcher untouched.
218
+ }
219
+ }
220
+
221
+ let shimsRewritten = 0;
222
+ for (const shimDir of collectWindowsShimDirs(pkgRoot, env)) {
223
+ try {
224
+ shimsRewritten += rewriteWindowsShims(shimDir, pkgRoot);
225
+ } catch {
226
+ // Never fail npm install on read-only or custom shims.
227
+ }
228
+ }
229
+ return { skipped: false, platform, linked, shimsRewritten };
230
+ }
231
+
232
+ try {
233
+ fs.chmodSync(binaryPath, 0o755);
234
+ } catch {
235
+ // Ignore on read-only stores.
236
+ }
237
+
238
+ let linked = 0;
239
+ for (const name of BIN_NAMES) {
240
+ const destJs = path.join(binDir, `${name}.js`);
241
+ try {
242
+ replaceJsWithNativeLinkUnix(binaryPath, destJs);
243
+ linked += 1;
244
+ } catch {
245
+ // Leave fallback JS launcher intact.
246
+ }
247
+ }
248
+
249
+ return { skipped: false, platform, linked };
250
+ }
251
+
252
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
253
+ try {
254
+ runPostinstall();
255
+ } catch {
256
+ // Postinstall optimization must never fail npm install.
257
+ }
258
+ process.exit(0);
259
+ }