128 lines
3.0 KiB
Markdown
128 lines
3.0 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.1** — parser and CLI complete, no UI yet.
|
|
|
|
## Codebase Structure
|
|
|
|
```
|
|
crates/
|
|
├── org-ast/ # AST types (Document, Section, Element, etc.)
|
|
├── org-parser/ # Tree-sitter parser, AST conversion
|
|
├── orkmode-core/ # High-level API, C FFI
|
|
└── ork-cli/ # CLI tool (bin name: ork)
|
|
```
|
|
|
|
## 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
|
|
|
|
### FFI
|
|
|
|
- C-compatible FFI in `orkmode-core/src/ffi.rs`
|
|
- Functions prefixed `ork_*`
|
|
- Caller owns returned strings (free with `ork_string_free`)
|
|
|
|
## 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.2)
|
|
|
|
Priority: Qt/QML read-only document viewer.
|
|
|
|
Tasks:
|
|
1. Set up Qt6/QML project in `ui/`
|
|
2. Link orkmode-core via C FFI
|
|
3. Implement document model (QAbstractItemModel)
|
|
4. Basic headline rendering with folding
|
|
5. Syntax highlighting
|
|
|
|
## 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.
|