Improve CLI or Frontend

This page outlines how to contribute improvements to the SnapsOS CLI and the Marketplace UI, including scope, quality standards, and the expected workflow. If you’re proposing new features rather than coding them, see Feature Requests.

What We Welcome

SnapsOS (CLI)

• Reliability & DX
  • Safer defaults, clearer errors, better help text
  • Idempotent “apply” behavior, dry-run/verify-only modes
  • Resume-able downloads, progress & speed reporting
• Integrity & Validation
  • Hash verification UX, schema validation improvements
  • Additional preflight checks (disk space, permissions, pruning compatibility)
• Automation
  • JSON logs/outputs, stable exit codes, CI-friendly flags
  • Better non-interactive flows (-yes, -format json)
• Performance
  • Streamed extraction, lower temp-space usage, parallelizable steps (where safe)

Marketplace (Frontend)

• Discovery UX
  • Rich filters (network, type, height range, date, contributor)
  • Sorting (Newest/Oldest, Size, ProviderSince, Trusted Score)
  • Deep-linking to filtered views; copy/share query
• Trust & Transparency
  • Provider profile cards, ProviderSince, NetworksCovered
  • Show Trusted Score, Snapshot Freshness, integrity state badges
• Quality
  • Accessibility (a11y), keyboard navigation, focus states
  • Skeletons/empty states, error boundaries, robust retry
  • Snappy list rendering (virtualization), pagination/infinite scroll

Getting Started

1. Discuss Open (or join) an issue describing the problem and proposed approach. Attach mocks or CLI examples if applicable.
2. Fork & Branch Fork the repo and create a descriptive branch (e.g., feat/cli-verify-only, ui/provider-since).
3. Build Locally Follow the repository’s README for environment setup. Keep changes focused and incremental.
4. Tests & Linting Add/adjust tests. Ensure linters and formatters pass before opening a PR.
5. Document Update relevant docs (this site, Quickstart pages, API notes) and include screenshots or CLI -help diffs.
6. Pull Request Use the PR template; include what, why, how, and before/after visuals (for UI). Link to the issue.

Repository: https://github.com/denodesxyz/snapsvault-dev

(CLI and Marketplace code locations are indicated in the repo README.)

Quality Standards

Coding & Style

• Prefer small, cohesive PRs.
• Clear names, minimal side effects, predictable flags/options.
• Keep user-visible text concise and action-oriented.

Testing

• CLI: unit tests for helpers; “golden” tests for output where sensible.
• Frontend: unit tests for logic; e2e for critical flows (filters, sorting, download CTA).
• Mock network; avoid flaky time-based assertions.

UX Consistency

• CLI: consistent flag names, consistent exit codes, -help updated.
• Frontend: consistent typography, spacing, and badge styles; align with Marketplace patterns.

Performance & Accessibility

• Avoid blocking the UI; stream & virtualize large lists.
• Meet basic a11y: landmarks, labels, focus order, color contrast.

Versioning & Docs

• Use SemVer when releasing user-impacting changes.
• Breaking changes (flags, API shapes, URL params) require a clear migration note.
• Update Quickstart / How to use SnapsOS CLI when CLI UX changes.
• Add a short CHANGELOG entry summarizing user-facing impact.

Security & Privacy

• Never commit secrets. Use environment variables and .env.example.
• Be mindful with telemetry/logs; keep them opt-in or documented.
• Validate all external inputs (URLs, checksums, feed JSON).

Roadmap Ideas (Pick & Ship)

• CLI: -dry-run, -verify-only, resumable downloads, structured logs, partial-apply safeguards.
• Frontend: Provider profiles, Trusted Score surfacing, “Top Providers” view, shareable filter URLs, snapshot freshness badges.

Key Takeaways

• Keep PRs focused, tested, and documented.
• Favor reliability, integrity, and clear UX over feature bloat.
• Reflect any CLI/UI changes in the docs and changelog.

Next Steps

• See Feature Requests for proposing new ideas.
• See Contribute Snapshots to add or maintain snapshot feeds.
• Open an issue in denodesxyz/snapsvault-dev to discuss your plan before you code.