143 lines
3.9 KiB
Markdown
143 lines
3.9 KiB
Markdown
# Agent Guidelines
|
|
|
|
Instructions for AI agents working on orkmode.
|
|
|
|
## Project Context
|
|
|
|
Orkmode is a native org-mode implementation: Rust parser/core + Qt/QML UI.
|
|
|
|
Current state: **v0.3** — parser, CLI, 9P server, and a read-only Qt6/QML GUI.
|
|
|
|
## Codebase Structure
|
|
|
|
```
|
|
crates/
|
|
├── org-ast/ # AST types (Document, Section, Element, etc.)
|
|
├── org-parser/ # Tree-sitter parser, AST conversion
|
|
├── ork-server/ # 9P server exposing org files (bin: ork-server)
|
|
└── ork-cli/ # CLI tool, a 9P client (bin name: ork)
|
|
ui/ # Qt6/QML GUI, a 9P client (bin: orkmode)
|
|
├── src/ # p9client, orkclient, documentmodel, main
|
|
└── qml/ # Main.qml, OutlineView.qml
|
|
```
|
|
|
|
## Working with the Code
|
|
|
|
### Build
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
Requires: Rust 1.70+, C compiler (for tree-sitter grammar).
|
|
|
|
### Test
|
|
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
### CLI
|
|
|
|
The `ork` CLI is a 9P client that talks to `ork-server`. Start a server first, then:
|
|
|
|
```bash
|
|
export ORK_ADDR=unix:///tmp/ork.sock
|
|
|
|
ork docs # List documents
|
|
ork tree work # Outline of work.org
|
|
ork todos # All TODOs
|
|
ork get work my-task # Section fields
|
|
ork set work my-task keyword DONE
|
|
ork add work "* TODO New task :work:"
|
|
```
|
|
|
|
Base 9P operations are available as `ork ls`, `ork read`, `ork write`, `ork rdwr`.
|
|
|
|
## Architecture Decisions
|
|
|
|
### Parser
|
|
|
|
- Uses [tree-sitter-org](https://github.com/nvim-orgmode/tree-sitter-org) grammar (git submodule)
|
|
- Pinned to tree-sitter 0.22 (0.23+ requires rustc 1.90+)
|
|
- Conversion in `org-parser/src/convert.rs` maps tree-sitter nodes to AST
|
|
|
|
### AST
|
|
|
|
- Follows [org-element spec](https://orgmode.org/worg/dev/org-syntax.html)
|
|
- All nodes have `Span` for source locations
|
|
- `Document` → `Section`* → `Element`* / `Section`*
|
|
- Inline objects (bold, links) are partially implemented
|
|
|
|
### 9P server
|
|
|
|
- `ork-server` exposes org files as a 9P namespace (docs, sections, fields, agenda, query)
|
|
- Structural ops via the `ctl` file: rm, move, promote, demote, refile, archive, lint
|
|
- `ork` is a pure 9P client; all org logic lives in the server
|
|
|
|
## Conventions
|
|
|
|
### Rust
|
|
|
|
- Edition 2021
|
|
- Use `thiserror` for error types
|
|
- Use `serde` for serialization
|
|
- Prefer `&str` over `String` in function signatures
|
|
- Match existing code style
|
|
|
|
### Commits
|
|
|
|
- Imperative mood: "Add feature" not "Added feature"
|
|
- Reference issue/context in body if relevant
|
|
|
|
### CLI
|
|
|
|
- Commands operate on paths (file or directory)
|
|
- Default to current directory
|
|
- `-R` for recursive
|
|
- `-j` for JSON output
|
|
- `-n` for dry run
|
|
|
|
## Current Limitations
|
|
|
|
1. **Inline objects incomplete** — tree-sitter-org doesn't fully parse bold/italic/links
|
|
2. **No incremental parsing** — full reparse on every write
|
|
3. **Section ID instability** — slug-derived IDs change when titles change (UUID IDs via `:ID:` are stable)
|
|
|
|
## Next Steps (v0.4)
|
|
|
|
The read-only GUI is in place (Qt6/QML, 9P client in `ui/`). Next: in-place
|
|
editing per the VISION "document is the control surface" model.
|
|
|
|
Tasks:
|
|
1. Section body view: read `/<doc>/<id>/body`, render structured
|
|
2. Per-section drop-to-raw-text edit; reparse-on-commit (one 9P write per edit)
|
|
3. Direct-manipulation structural edits mapped to `/ctl` verbs
|
|
(move/promote/demote/refile) — drag/click, no menu trees
|
|
4. TODO cycling, tag, and priority edits via the existing field files
|
|
5. Agenda view backed by `/agenda/{today,week,todos}`
|
|
|
|
GUI verification: `orkmode --selftest -a <addr>` dumps the outline via the
|
|
model without a display (used to test the 9P client + model in CI).
|
|
|
|
## Testing Changes
|
|
|
|
Before committing:
|
|
|
|
```bash
|
|
cargo build --release
|
|
cargo test
|
|
|
|
# Integration test (start server, run CLI, stop server)
|
|
ork-server -a unix:///tmp/ork-test.sock -d /tmp/test-org &
|
|
SERVER_PID=$!
|
|
export ORK_ADDR=unix:///tmp/ork-test.sock
|
|
ork docs
|
|
ork lint
|
|
kill $SERVER_PID
|
|
```
|
|
|
|
## Questions?
|
|
|
|
Check VISION.md for project goals and design principles.
|