Skip to main content

Roadmap

Missing pieces​

  • CTS-style command contracts for each public command (purpose, invocation, inputs, stdout/stderr, machine-readable mode, exit codes, examples, stability notes)
  • Documented exit code table matching CTS bands
  • Machine-readable JSON output mode and a documented output schema (CommandOutput envelope, or a justification for a custom schema)
  • Documented machine-readable error object and error examples
  • Explicit --version output behavior (no version flag currently documented)
  • Release checklist and artifact verification — build/tests/release were not executed during governance migration
  • Automation-focused examples, including an explicit note that --quiet (if added) must not hide failures

Next steps​

  1. Reconcile and record concrete command contracts for fhtoolkit query and fhtoolkit download (under docs/ or CLI_CONTRACTS/)
  2. Document and publish an exit code table consistent with CTS bands
  3. Add a machine-readable output mode (e.g. --json) implementing the CTS CommandOutput envelope, or document exceptions
  4. Add a --version flag or equivalent version output, and document its behavior
  5. Run package build, tests, and artifact verification; record results in the manifest's verification section
  6. Add automation examples to the README demonstrating parsing of machine-readable output and handling exit codes
  7. Keep the legacy wrappers, but explicitly document the packaged CLI as preferred and mark wrappers as compatibility shims

Potential improvements​

  • --json emitting the CTS envelope (status/tool/version/data/warnings/errors)
  • Ensure all diagnostic/progress output goes to stderr, normal data to stdout
  • A documented exit-code-to-failure-mode mapping in the README, with a small exit-code test matrix
  • Caching for fetched AppStream XML with a TTL, to avoid repeated downloads
  • Concurrent/parallel download option with configurable workers and retry/backoff policy
  • Basic unit tests around parsing, ref generation, and download routines, recorded in manifest verification

Creative enhancements (ideas on file, not committed)​

  • A local index (DuckDB or SQLite) of available AppStream components, for fast ad-hoc queries, diffs between snapshots, and analytic queries across releases
  • A "refs delta" mode comparing two AppStream snapshots and emitting added/removed app refs, for auditing or deployment rollouts
  • A small localhost HTTP service serving generated ref lists and descriptor metadata to other local tools or dashboards
  • Export adapters producing CSV, JSONL, or a pre-seeded DuckDB table of refs for downstream dataset workflows
  • Integration with an Aptlantis archive pipeline storing fetched .flatpakref descriptors and AppStream snapshots with semantic metadata for long-term reproducibility