generated from eblume/project-template
Erich Blume
d36ed18590
Some checks failed
Build / validate (pull_request) Failing after 1m12s
The Neovim plugin now lives at eblume/hephaestus.nvim (plugin at the repo root). Remove heph.nvim/ from the monorepo and the build/test wiring that referenced it: - Dagger: drop the test_nvim function + the pinned-Neovim NVIM_VERSION - build.yaml: drop the `dagger call test-nvim` step - drop the mise run test-nvim task and .stylua.toml + the stylua prek hook (no Lua remains in the monorepo) - install-heph.md: install via a plain lazy.nvim spec pointing at the plugin repo over SSH (no more local-dir checkout hack) - README / AGENTS / heph-nvim.md: note the surface lives in its own repo The CLI/TUI -> nvim integration is unchanged (they shell out to `nvim` expecting the heph plugin installed). The v1-prototype tech-spec §14 build record and prior changelog fragments are left as frozen history. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
102 lines
8.9 KiB
Markdown
102 lines
8.9 KiB
Markdown
# hephaestus
|
|
|
|
A personal context management system — a single, self-hosted Rust application that fuses a wiki-style knowledge base (Zettelkasten) with task management. Notes and tasks are **first-class, cross-linkable entities** in one database, so a task like "Fix the roof leak" stays coupled to the home-repair log and contractor-call notes that give it context.
|
|
|
|
It is **offline-first**: fully useful on a laptop with no network, and (when the distributed layer lands) auto-syncing to a central instance hosted in blumeops. The primary surface will be a Neovim plugin (`heph.nvim`, an obsidian.nvim replacement); a CLI (`heph`) is the utility/scripting surface.
|
|
|
|
> **Why "what is next?" is the flagship.** heph is organized around concise, honest answers to recurring questions — above all *"what do I do right now?"* — built from ~10 years of the owner's lived prioritization discipline: projects-as-contexts; attention colors (white/orange/red/blue, where **red = a consequence exists if late**, not importance); **do-dates, not due-dates** (earliest-actionable, never a deadline alarm); and working-set tensions surfaced honestly (no "fake happy", no overwhelm).
|
|
|
|
See **[docs/explanation/design.md](docs/explanation/design.md)** for the vision and rationale, and **[docs/reference/v1-prototype-tech-spec.md](docs/reference/v1-prototype-tech-spec.md)** for the implementation-facing specification.
|
|
|
|
## Status
|
|
|
|
**Phase 1 (v1 prototype) — at Todoist feature-parity (2026-06-03)** on branch `feature/v1-prototype`. The Rust backend is feature-complete and **all three surfaces are installed daily-drivers**: the **`heph` CLI** (capture/scripting + the complete daemon API), **`heph-tui`** (the agenda/triage surface — attention-colored views, fzf move-to-project, undo/redo, an Inbox), and **`heph.nvim`** (the context/knowledge base — journals, wiki-links by id with conceal, a `[[` picker, YAML-frontmatter task editing). A global **⌘' quick-capture** popover (`heph-quickadd`) rounds out capture. Under the hood: **all three runtime modes work, replicas sync through a hub over HTTP, authenticated end-to-end with OIDC** (Authentik; JWKS/RS256, single-tenant), the offline-first config (`local` + `hub_url`) converges with a `yrs` text-CRDT, and the daemon runs as an OS service. CI is green, fully through Dagger; built test-first.
|
|
|
|
**heph now self-hosts its roadmap.** With parity reached, remaining and future work is tracked **in heph itself** — as tasks in the **`Hephaestus` project** (`heph view ondeck`, or the *On Deck* view in `heph-tui`) — rather than in a document. The [v1-prototype tech-spec](docs/reference/v1-prototype-tech-spec.md) is now the historical build record (its §14 tracker); the [design doc](docs/explanation/design.md) remains the living rationale.
|
|
|
|
| Area | State |
|
|
|---|---|
|
|
| Data model, markdown extraction, wiki-links, export | ✅ done |
|
|
| Tasks, links, "what is next?" ranking, recurrence, per-task logs | ✅ done |
|
|
| `hephd` daemon — **local mode** (file lock + JSON-RPC over a unix socket) | ✅ done |
|
|
| `heph` CLI; `list` / `health` / `journal` / full-text `search` (FTS5) | ✅ done |
|
|
| Sync engine — HLC, op-log, converging merge + conflict queue (no network yet) | ✅ done |
|
|
| yrs text-CRDT for body merge | ✅ done |
|
|
| `server` (hub) mode + spoke push/pull sync over HTTP (axum) | ✅ done |
|
|
| `client` mode + `RemoteStore` (online-only, no replica) | ✅ done |
|
|
| OIDC hub auth — bearer-token verification + owner gate | ✅ done |
|
|
| OIDC client — device-code login, keyring token cache | ✅ done |
|
|
| `heph.nvim` (primary surface) — RPC client, buffer-backed editing, wiki-link follow, journal (slice 11a) | ✅ done |
|
|
| `heph.nvim` — Tactical/Organizational task views, capture, attention, done/drop, log (slice 11b) | ✅ done |
|
|
| `heph.nvim` — context-item promotion + Dagger headless-nvim CI (slice 11c) | ✅ done |
|
|
| `heph.nvim` — managed daemon (plug-and-play, self-heal), follow-or-create, home/index, dailies picker, interactive views; installed + dev-isolated | ✅ done |
|
|
|
|
## Architecture
|
|
|
|
A Cargo workspace, layered so the same core runs from a laptop to a hub:
|
|
|
|
- **`crates/heph-core`** — the library: data model, the `Store` trait + SQLite store, markdown parsing/extraction, recurrence, the "what is next?" engine, and the sync engine (op-log, hybrid logical clocks, CRDT/LWW merge, conflict detection). Synchronous and clock-injected (no ambient wall-clock reads) so ranking and merge are deterministic.
|
|
- **`crates/hephd`** — the per-device daemon. One binary, three modes — **`local`** (own SQLite replica; a syncing spoke when given `--hub-url`), **`server`** (also the sync hub: an HTTP endpoint others sync against), **`client`** (thin, remote, no replica — proxies to a `--server-url`) — selected by configuration via a targetable `Store` backend. Surfaces connect to it over a unix socket; it owns the DB handle and background sync.
|
|
- **`crates/heph`** — the CLI: a thin client of the daemon (no direct DB access).
|
|
- **`hephaestus.nvim`** (its own forge repo, [eblume/hephaestus.nvim](ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.nvim.git)) — the Neovim editing/knowledge-base surface, a thin client of the daemon; see [docs/reference/heph-nvim.md](docs/reference/heph-nvim.md) and [docs/how-to/install-heph.md](docs/how-to/install-heph.md).
|
|
|
|
**Storage:** SQLite is the source of truth; a node's body is markdown; `export` materializes the whole store as a directory of `.md` files. **Sync:** each device holds a full replica + an append-only op-log; devices reconcile through a hub with automatic merge (text-CRDT bodies, last-writer-wins scalars, OR-set links) and a conflict queue for the ambiguous remainder. **Auth:** the hub verifies an OIDC bearer token (Authentik) on every op exchange — RS256/JWKS verification + a single-tenant owner gate — and clients obtain tokens via the OAuth 2.0 device-code flow (`heph auth login`), cached in the OS keyring. Local-only instances need no auth.
|
|
|
|
## Build & run
|
|
|
|
Requires a Rust toolchain (stable). The build is a standard Cargo workspace:
|
|
|
|
```bash
|
|
cargo build # build all crates
|
|
cargo test --all # run the full test suite
|
|
cargo clippy --all-targets -- -D warnings
|
|
```
|
|
|
|
Run the daemon in local mode, then drive it with the CLI:
|
|
|
|
```bash
|
|
# Terminal 1 — start the daemon (creates ~/.local/share/heph/heph.db and a socket)
|
|
cargo run -p hephd
|
|
|
|
# Terminal 2 — talk to it
|
|
cargo run -p heph -- task "Fix the roof leak" --attention red
|
|
cargo run -p heph -- next # the "what is next?" ranking
|
|
cargo run -p heph -- doc "Roof log" --body "Called the contractor."
|
|
cargo run -p heph -- search roof # full-text search
|
|
cargo run -p heph -- journal 2026-06-01 # open/create today's journal
|
|
cargo run -p heph -- export ./snapshot # write the store as a .md tree
|
|
```
|
|
|
|
The daemon takes an exclusive lock on its DB file; `--db` and `--socket` override the defaults.
|
|
|
|
## Development
|
|
|
|
- **Test-driven.** Every feature has tests at the appropriate layer(s) — unit, property tests, real-socket daemon integration, and CLI process tests. No feature is "done" without them.
|
|
- **Change process.** Changes are classified **C0 / C1 / C2** (quick fix / human-review PR / Mikado chain). The v1 prototype is a single long-lived **C1**. See [docs/how-to/agent-change-process.md](docs/how-to/agent-change-process.md).
|
|
- **Git hooks & tooling.** [prek](https://github.com/dustinblackman/prek) runs formatting, linting, and secret detection; [mise](https://mise.jdx.dev/) runs repo automation; CI (Forgejo) runs `prek` plus `cargo fmt`/`clippy`/`test` via `.forgejo/scripts/build`.
|
|
|
|
```bash
|
|
prek install && prek install --hook-type commit-msg # set up hooks
|
|
prek run --all-files # run all checks
|
|
mise tasks # list automation tasks
|
|
mise run ai-docs # docs AI agents read first
|
|
```
|
|
|
|
- **Documentation** is [Diataxis](https://diataxis.fr/)-structured and built with [Quartz](https://quartz.jzhao.xyz/); changelog fragments use [Towncrier](https://towncrier.readthedocs.io/) under `docs/changelog.d/`. Working agents should read **[AGENTS.md](AGENTS.md)** first.
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
./Cargo.toml # workspace manifest
|
|
./crates/heph-core/ # core library: model, store, extraction, recurrence, ranking, sync
|
|
./crates/hephd/ # daemon: local/server/client modes — unix-socket RPC + HTTP sync/rpc
|
|
./crates/heph/ # CLI: thin client of the daemon
|
|
./docs/ # Diataxis docs (design, v1-prototype-tech-spec, how-to), Quartz config
|
|
./.forgejo/ # CI build + release workflows and hooks
|
|
./.dagger/ # Dagger module backing docs builds/releases
|
|
./mise-tasks/ # repo automation via `mise run`
|
|
```
|
|
|
|
## License
|
|
|
|
All rights reserved. This is a personal, private project — not licensed for use, copying, modification, or distribution. Open-sourcing may be considered in the future. See [LICENSE](LICENSE).
|