Roadmap

Harp is delivered in testable stages. Each stage ends with a concrete gate you can verify before the next begins.

Status (2026-06-04): Stages 0–5 complete; packaged as v0.1.0.

Stage	Scope	Gate
0	Scaffold & language registration	Extension installs & activates; .hcl shows as HCL; brackets auto-close; line/block comment toggling works.
1	TextMate highlighter (source.hcl)	A sample .hcl is colored correctly across themes; grammar scope tests pass.
2	Formatter engine core + HCL lexer	Format Document runs without error; lexer round-trips (emit(lex(x)) === x); unit tests pass.
3	HCL formatting passes (terraform fmt parity)	Messy HCL reformats to canonical on save; golden corpus passes; optional diff vs real terraform fmt is empty.
4	Settings, polish, packaging	Clean packaged install (v0.1.0); harp.hcl.enable works; no crash on edge fixtures.
5	Scalability proof	A second language formats + highlights with zero changes to core/; contributes codegen keeps package.json in sync.

Design principles

• Independent — no dependency on other extensions; no external binaries (terraform is never invoked at runtime). Pure-TypeScript formatter, self-authored grammar, zero runtime npm dependencies.
• Scalable — a language-pack architecture (src/languages/<lang>/) over a language-agnostic core/. Adding a language never edits the core.
• Faithful — the formatter mirrors terraform fmt’s own token-stream pipeline, validated against a golden corpus.

Parked (post-v1)

• harp.themes.comments toggle (muted default / lifted) — raise comment contrast via theme-scoped editor.tokenColorCustomizations for readers who find the by-design ~2.5:1 comments too quiet.
• Semantic-tokens provider (context-aware coloring on top of TextMate).
• Range/selection and on-type formatting (whole-document only for now).
• terraform fmt interpolation rewrites ("${ expr }" → expr; trimming inside ${ … }) — string bodies are currently treated verbatim.
• First-class .tf / .tfvars (Terraform) support.
• GitHub Actions CI and Marketplace publishing.