Skip to content

agents.md

Latest commit

 

History

History
78 lines (60 loc) · 3.77 KB

agents.md

File metadata and controls

78 lines (60 loc) · 3.77 KB
Raw

Agents Guide (Muonium Native)

This repo is used both as a product workspace and as an automation target for coding agents.

Prime directive

  • Prefer minimal, surgical edits.
  • Keep changes consistent with existing conventions.
  • Avoid reformatting or renaming unless necessary.

Repo structure (high level)

  • vendor/ contains external dependencies; when possible, track them as git submodules.
  • muonium-kotlin/ is the Kotlin Multiplatform implementation area.
  • investor/ contains pitch/docs and should not be modified unless explicitly requested.

Submodules

  • Use git submodule status to verify state.
  • When updating a submodule, commit:
    • .gitmodules (only if changed)
    • the submodule gitlink (the submodule directory entry)
  • Do not edit vendored submodule contents directly unless the intent is to fork.

Kotlin Multiplatform porting guidelines

When porting vendor/pygments-swift into Kotlin Multiplatform:

Goals

  • Preserve behavior and token output fidelity first, then optimize.
  • Keep a stable, small public API to support rendering/consumers.
  • Ensure deterministic output across JVM/Android and Kotlin/Native.

Non-goals (unless asked)

  • Do not implement a full IDE/editor.
  • Do not introduce heavy dependencies (e.g., full parser frameworks) unless required.

Suggested deliverables

  • A KMP library that exposes:
    • a tokenizer/lexer API
    • token types + scopes
    • theme mapping primitives (optional)
  • A test corpus that compares Kotlin output to the Swift reference for a set of fixtures.

Performance notes

  • Tokenization is hot-path: avoid per-character allocations.
  • Prefer streaming APIs (append to mutable lists / emit callbacks).
  • Benchmark with representative file sizes and languages.

Working agreement

  • If uncertain about an API surface, create a small RFC doc first.
  • Always add or update tests when implementing core lexing behavior.

CLI exports (HTML/PNG/PDF)

The Kotlin CLI supports exporting highlighted output:

  • Entry point: muonium-kotlin/cli (run via muonium-kotlin/tools/gradle.sh or repo make run)
  • Formats:
    • --format tokens (default) or --format text (alias): prints token stream to stdout
    • --format html|png|pdf: writes to --out <file>
  • Common flags: --language <name>, --theme light|dark, --font-size <n>

Quick smoke (from repo root):

  • cd muonium-kotlin && ./tools/gradle.sh :cli:run --args="../vendor/pygments-swift/sample-code/fibonacci.json --format html --out /tmp/muonium.html"
  • cd muonium-kotlin && ./tools/gradle.sh :cli:run --args="../vendor/pygments-swift/sample-code/fibonacci.json --format png --out /tmp/muonium.png"
  • cd muonium-kotlin && ./tools/gradle.sh :cli:run --args="../vendor/pygments-swift/sample-code/fibonacci.json --format pdf --out /tmp/muonium.pdf"

Note: PDF generation may log PDFBox font-cache warnings on first run; that’s expected.

Completion checklist (required)

After completing or implementing a task, always validate by running the repo Make targets and then return control to the user.

  • Prefer: make build && make test && make run
  • If the task touches Kotlin export/rendering, additionally run an export smoke (HTML/PNG/PDF) and confirm files are non-empty.
  • If the task is vendor/OCR related, additionally run the vendor targets you touched (e.g. make vendor-test, make vendor-render-samples, make ocr-check).
  • If a target is a placeholder (for example, Kotlin Gradle scaffolding not present yet), still run it and report what it did (or that it no-op’d) along with any actionable follow-up.
  • If explicitly requested, run make in each subfolder that contains a Makefile by cd into the folder and executing make.

Return control after:

  • commands complete successfully, or
  • failures are explained with the exact error output and the next minimal fix.