From 22fd8186684b63c651e419c35719fb637286942d Mon Sep 17 00:00:00 2001 From: tolvitty Date: Thu, 12 Feb 2026 12:20:23 +0100 Subject: [PATCH] Release v1.0.0: README, version bump Add English README with badges, installation guide, usage examples, and architecture overview. Bump version to 1.0.0 in manifest and package. Co-Authored-By: Claude Opus 4.6 --- README.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++ manifest.json | 2 +- package.json | 2 +- 3 files changed, 203 insertions(+), 2 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..12066a6 --- /dev/null +++ b/README.md @@ -0,0 +1,201 @@ +
+ +# Logfire + +**Track everything. Query anything. Visualize it all.** + +An Obsidian plugin that logs all vault activity into a local SQLite database, +makes it queryable via SQL, and visualizes results with charts and dashboards. + +[![GitHub release](https://img.shields.io/github/v/release/tolvitty/obsidian-logfire?style=flat-square)](https://github.com/tolvitty/obsidian-logfire/releases) +[![License](https://img.shields.io/github/license/tolvitty/obsidian-logfire?style=flat-square)](LICENSE) +[![Obsidian](https://img.shields.io/badge/Obsidian-Desktop%20only-7C3AED?style=flat-square&logo=obsidian)](https://obsidian.md) +[![SQLite](https://img.shields.io/badge/Powered%20by-SQLite-003B57?style=flat-square&logo=sqlite)](https://sqlite.org) + +
+ +--- + +
+ +## Features + +
+ +### Event Tracking + +Logfire silently records vault activity in the background — file operations, content changes, navigation, editor keystrokes, and command executions. Events are buffered, debounced, and flushed to SQLite in batches for minimal performance impact. + +### SQL Query Engine + +Query your vault data with full SQL support. Use the interactive query editor with shorthand syntax (`events today`, `stats this-week group by file`) or write raw SQL. Includes autocomplete for table names, columns, functions, and event types. + +### Data Visualization + +- **10 SVG chart types** — bar, line, area, pie, donut, scatter, gauge, sparkline, stacked bar, horizontal bar +- **6 render formats** — table, timeline, summary, metric, list, heatmap +- **Multi-widget dashboards** with configurable grid layouts and auto-refresh +- **Vim-style keyboard navigation** (j/k/h/l, gg/G, /, y, Enter) for tables + +### Virtual Tables + +Query live vault metadata alongside event data: + +| Table | Contents | +|---|---| +| `_files` | path, name, extension, size, created, modified, folder | +| `_links` | from_path, to_path, display_text, link_type | +| `_tags` | path, tag | +| `_headings` | path, level, heading | + +### Projections & Reports + +Automatically generate Markdown reports from event data. Built-in presets for daily logs, session logs, and weekly digests — or create custom projection templates with scheduling. + +### Query Management + +- **History** — automatic tracking of all executed queries with metrics +- **Favorites** — save, categorize, and tag frequently used queries +- **Templates** — 9 built-in templates with parameter substitution, plus custom templates +- **Export** — CSV (Excel-compatible with BOM) and JSON export + +--- + +
+ +## Installation + +
+ +### Manual Installation + +1. Download `main.js`, `styles.css`, and `manifest.json` from the [latest release](https://github.com/tolvitty/obsidian-logfire/releases/latest) +2. Create a folder `/.obsidian/plugins/logfire/` +3. Copy the three files into that folder +4. Install the native SQLite dependency: + ```bash + cd /.obsidian/plugins/logfire/ + mkdir -p node_modules + npm install better-sqlite3 --prefix . + ``` +5. Rebuild `better-sqlite3` for your Obsidian's Electron version: + ```bash + # Find your Electron version (check Obsidian > Help > About) + npx @electron/rebuild -v -m . --only better-sqlite3 + ``` +6. Restart Obsidian and enable **Logfire** in Settings → Community Plugins + +### Build from Source + +```bash +git clone git@github.com:tolvitty/obsidian-logfire.git +cd obsidian-logfire +npm install +npm run build +``` + +Then copy `main.js`, `styles.css`, and `manifest.json` to your plugin folder and follow steps 4–6 above for the native module setup. + +> **Note:** Logfire is desktop-only. It requires `better-sqlite3`, a native Node.js module that must match your Obsidian's Electron ABI version. Mobile is not supported. + +--- + +
+ +## Usage + +
+ +### Code Blocks + +Embed live queries directly in your notes: + +````markdown +```logfire +range: today +group: file +format: table +``` +```` + +````markdown +```logfire-sql +SELECT source, COUNT(*) as events +FROM events +WHERE timestamp > (strftime('%s', 'now', 'start of day') * 1000) +GROUP BY source +ORDER BY events DESC +LIMIT 10 +``` +```` + +````markdown +```logfire-dashboard +name: My Dashboard +columns: 12 + +[widget:chart row:0 col:0 width:6 height:2] +-- title: Events by Type +-- chart: pie +SELECT type, COUNT(*) as count FROM events GROUP BY type + +[widget:stat row:0 col:6 width:3 height:1] +-- title: Total Events +SELECT COUNT(*) as value FROM events + +[widget:query row:0 col:9 width:3 height:2] +-- title: Recent Files +SELECT source, COUNT(*) as n FROM events GROUP BY source ORDER BY n DESC LIMIT 5 +``` +```` + +### Commands + +All commands are available via the command palette (`Ctrl/Cmd+P`): + +| Command | Description | +|---|---| +| Show event stream | Real-time event sidebar | +| Show dashboard | Open dashboard view | +| Open query editor | Interactive SQL editor | +| Show schema browser | Browse tables, columns, indexes | +| Show query templates | Pick from built-in and custom templates | +| Run projection | Execute a Markdown report template | +| Toggle tracking | Pause/resume event collection | +| Toggle Vim navigation | Enable j/k/h/l navigation in tables | + +--- + +
+ +## Architecture + +
+ +``` +src/ +├── main.ts Plugin entry, lifecycle, commands +├── types.ts Event types, settings, query interfaces +├── core/ +│ ├── database.ts SQLite via better-sqlite3 +│ ├── event-bus.ts Circular buffer, pub/sub, auto-flush +│ ├── session-manager.ts Session start/end, duration tracking +│ ├── content-analyzer.ts Snapshot cache, word/link/tag diffs +│ └── query-builder.ts QueryConfig → parameterized SQL +├── collectors/ File, content, nav, editor, system +├── query/ Code-block processors, modal, virtual tables, autocomplete +├── viz/ Table renderer, SVG charts, dashboards, Vim navigation +├── management/ History, favorites, templates +├── projection/ Report engine, formatters, presets +└── ui/ Settings, status bar, event stream, schema browser +``` + +--- + +
+ +## License + +MIT + +
diff --git a/manifest.json b/manifest.json index 67298cb..e0d8037 100644 --- a/manifest.json +++ b/manifest.json @@ -1,7 +1,7 @@ { "id": "logfire", "name": "Logfire", - "version": "0.1.0", + "version": "1.0.0", "minAppVersion": "1.5.0", "description": "Track all vault activity, query with SQL, visualize with charts and dashboards — all backed by SQLite.", "author": "tolvitty", diff --git a/package.json b/package.json index a1a84ab..0db625a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "logfire", - "version": "0.1.0", + "version": "1.0.0", "description": "Track all vault activity, query with SQL, visualize with charts and dashboards", "main": "main.js", "scripts": {