136 lines
3.7 KiB
Markdown
136 lines
3.7 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 operates on directories by default:
|
|
|
|
```bash
|
|
ork info . # Aggregate info for all .org files
|
|
ork sections --todos-only # List TODOs across files
|
|
ork query "tag:work" -R # Recursive search
|
|
ork get "section-id" -j # JSON output
|
|
ork toggle "task-id" -n # Dry run
|
|
ork add "New Task" file.org --todo TODO
|
|
```
|
|
|
|
Use `-j/--json` for machine-readable output. Use `-n/--dry-run` for mutations.
|
|
|
|
## 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. **Property/tag write commands** — stubs only, not implemented
|
|
3. **Timestamp text** — displays "set" placeholder, not actual date
|
|
4. **No incremental parsing** — full reparse on every call
|
|
|
|
## 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
|
|
./target/release/ork check .
|
|
./target/release/ork info test.org -j
|
|
```
|
|
|
|
## Questions?
|
|
|
|
Check VISION.md for project goals and design principles.
|