Skip to content

roadmap.md

Latest commit

 

History

History
101 lines (82 loc) · 5.48 KB

roadmap.md

File metadata and controls

101 lines (82 loc) · 5.48 KB

plait Roadmap

Version planning and the honest answer to "what's planned next?"

Current status

v1.0.0 is feature-complete for the initial vision. The core composition engine, resolver, preset system, plugin interfaces, hooks, generators, and CLI are all shipping and stable. The project is in active maintenance — bug fixes, dependency updates, documentation improvements, and small enhancements land as they're identified.

Larger features are considered but not committed. The list in v1.1 candidates below is the set of ideas that have come up during design and reviews, not a schedule of promised work. If one of these blocks a real use case you have, open an issue describing the problem (not the feature) and it will be prioritized against everything else being considered.

Version history

Version Status Notes
v1.0.0 Released 2026-01-03 Core feature set complete

v1.0.0 — shipped

Core functionality for modular content composition. Plait is a domain-neutral engine — the same release weaves AI prompts, technical documentation, configuration files, and any other structured text where reusable fragments need declarative ordering.

Features

  • Module parsing (TOML frontmatter + markdown body)
  • Dependency resolution: requires, suggests, conflicts
  • Cycle detection with full cycle-path reporting
  • Preset inheritance with multi-parent and diamond support
  • Glob patterns in include / exclude
  • Variable interpolation (MiniJinja, strict undefined-variable behavior)
  • Configuration hierarchy: CLI > project > user > environment
  • CLI: compile, list, show, graph, resolve, check, lint, init, doctor, completions, hooks, plugins, schema
  • Shell completions (bash, zsh, fish, powershell, elvish)
  • Multiple output formats: Markdown, plain text, JSON, YAML, HTML
  • JSON Schema generation for editor/IDE tooling, with schemas derived directly from the real parser types (no hand-maintained duplicates)
  • Fuzzy matching suggestions in error messages
  • Rich errors via miette with source spans and fuzzy hints
  • Programmatic hooks: pre_resolve, post_resolve, pre_render, post_render
  • Runtime generators: dynamic modules from JSON/YAML/TOML data files rendered through MiniJinja templates
  • Plugin architecture: WASM (wasmtime) and external processes
  • Module content inheritance via extends and {{ parent() }}
  • Conditional dependencies (when clause, validated at load time)
  • Fragment includes ({{ include_fragment("path") }})
  • Documented exit codes (0 success / 1 usage / 2 config / 3 resolution / 4 I/O)

Publication

The original plait name on crates.io is owned by an unrelated HTML templating crate. The plait crate is published under the plaited slug (see Cargo.toml); the binary name, the library use plait::... API, the ~/.config/plait/ config directory, and the plait.toml project file all keep the original name.

v1.1 candidates

These are candidates, not commitments. Each carries an honest note about why it's considered and why it hasn't been started.

Candidate Why considered Why not yet
Module versioning Real module libraries benefit from explicit version constraints (like cargo's ^1.2). Git handles most versioning concerns today. Needs concrete user pain before the complexity is justified.
Lockfile (plait.lock) Reproducible output across environments. Depends on versioning. Without versioning, a lockfile would just pin file hashes, which git already does.
Module scaffolding (plait new) Lower friction for first-time users. The examples/hello/ minimal example serves most of the same need and is maintained without extra code.
Watch mode Auto-recompile on module changes during authoring. Straightforward to implement, but adds a file-watcher dependency for a workflow most users solve with entr or fd | xargs plait.
Deprecation metadata Warn when a preset includes a module marked deprecated. Depends on versioning for "deprecated in X.Y" semantics.
Language server (LSP) Autocomplete for module IDs in requires/suggests, jump-to-definition from preset includes to module files, hover docs from module descriptions, live diagnostics for unresolved or cyclic dependencies. The JSON Schema groundwork already present in v1.0 is about 70% of what an LSP needs. Substantial effort; would ship as a separate plait-lsp crate. Needs a concrete user driver (which editor / which feature first).
Web-based module browser / registry Sharing and discovering community modules. No evidence of a community yet large enough to justify the infrastructure.
IDE extensions (VS Code, JetBrains) Distribution channel for the LSP once it exists. Depends on LSP.

How to influence the roadmap

If one of the candidates above would unblock real work for you, or if you have a use case plait doesn't address, the best thing to do is open a GitHub issue describing the problem, not the feature. The issue template asks for:

  1. What you're trying to do
  2. What you tried with the current plait version
  3. Where it fell short
  4. What would have to be true for plait to serve the use case

This framing makes prioritization against other candidates straightforward. Feature requests framed as solutions ("add X") without the problem context are harder to compare.