e1ee18ca8a
sukr = suckless + Rust. Minimal static site compiler. - Update Cargo.toml name and description - Update main.rs USAGE and doc comments - Update AGENTS.md with new name, Tera architecture - Create README.md with quick start guide
141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# Project Agent Configuration
|
|
|
|
## Predicates
|
|
|
|
This project uses [predicate](https://github.com/nrdxp/predicate) for agent configuration.
|
|
|
|
**Installation Location:** `.agent/predicates/`
|
|
|
|
The agent MUST read and adhere to the global engineering ruleset and any active fragments:
|
|
|
|
```
|
|
.agent/
|
|
├── predicates/
|
|
│ ├── global.md # Base engineering ruleset (required)
|
|
│ └── fragments/ # Active extensions
|
|
│ └── rust.md # Rust conventions
|
|
└── workflows/
|
|
└── ... # Task-specific workflows
|
|
```
|
|
|
|
**Active Fragments:**
|
|
|
|
- Rust idioms (`.agent/predicates/fragments/rust.md`)
|
|
- DepMap MCP tools (`.agent/predicates/fragments/depmap.md`)
|
|
|
|
**Available Workflows:**
|
|
|
|
- `/ai-audit` — Audit code for AI-generated patterns
|
|
- `/core` — C.O.R.E. structured interaction protocol
|
|
- `/predicate` — Re-read global rules; combats context drift
|
|
- `/humanizer` — Remove AI writing patterns from text
|
|
|
|
---
|
|
|
|
## Project Overview
|
|
|
|
**sukr** is a minimal static site compiler written in Rust. Suckless, zero JS, transforms Markdown into high-performance static HTML.
|
|
|
|
### Philosophy
|
|
|
|
- **Suckless:** No bloated runtimes, no unnecessary JavaScript
|
|
- **Hermetic:** Single binary with all dependencies compiled in
|
|
- **Elegant:** Syntax highlighting via Tree-sitter, templates via Tera
|
|
|
|
### Architecture
|
|
|
|
The compiler implements an **Interceptor Pipeline**:
|
|
|
|
1. **Ingest:** Walk `content/`, parse TOML frontmatter
|
|
2. **Stream:** Feed Markdown to `pulldown-cmark` event parser
|
|
3. **Intercept:** Route code blocks to Tree-sitter, Mermaid, KaTeX
|
|
4. **Render:** Push modified events to HTML writer
|
|
5. **Layout:** Wrap in Tera templates (runtime, user-customizable)
|
|
6. **Write:** Output to `public/`
|
|
|
|
---
|
|
|
|
## Build & Commands
|
|
|
|
```bash
|
|
# Development
|
|
nix develop # Enter dev shell with Rust toolchain
|
|
cargo build # Build compiler
|
|
cargo run # Run compiler (builds site to public/)
|
|
|
|
# Production
|
|
nix build # Build hermetic release binary
|
|
./result/bin/sukr # Run release compiler
|
|
|
|
# CLI Usage
|
|
sukr # Build with ./site.toml
|
|
sukr -c sites/blog/site.toml # Build with custom config
|
|
sukr --help # Show usage
|
|
```
|
|
|
|
---
|
|
|
|
## Code Style
|
|
|
|
- Rust 2024 edition
|
|
- Follow `.agent/predicates/fragments/rust.md` conventions
|
|
- Prefer standard library over external crates
|
|
- No `unwrap()` in library code; use proper error handling
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
.
|
|
├── Cargo.toml # Rust manifest
|
|
├── flake.nix # Nix build environment
|
|
├── site.toml # Site configuration (or in sites/*)
|
|
├── src/
|
|
│ ├── main.rs # Pipeline orchestrator
|
|
│ ├── config.rs # TOML config loader
|
|
│ ├── content.rs # Content discovery, sections
|
|
│ ├── template_engine.rs # Tera template engine
|
|
│ ├── feed.rs # Atom feed generation
|
|
│ ├── highlight.rs # Tree-sitter highlighting
|
|
│ └── render.rs # Pulldown-cmark interception
|
|
├── templates/ # Tera templates (base, page, section/*)
|
|
├── content/ # Markdown + YAML frontmatter
|
|
├── static/ # CSS, images, _headers
|
|
└── public/ # Generated output
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
- Test runner: `cargo test`
|
|
- Naming: `test_<scenario>_<expected_outcome>`
|
|
- Focus on content transformation correctness
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
- No user input at runtime (build-time only)
|
|
- Validate frontmatter schema during parsing
|
|
- No secrets in content or templates
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Site configuration lives in `site.toml`:
|
|
|
|
```toml
|
|
title = "My Site"
|
|
author = "Author Name"
|
|
base_url = "https://example.com"
|
|
|
|
[paths] # All optional, defaults shown
|
|
content = "content"
|
|
output = "public"
|
|
static = "static"
|
|
templates = "templates"
|
|
```
|