Post-v0.1 product hardening roadmap

[abhiksark]

Summary

Track the next product/code quality work after the v0.1 release work, excluding PyPI publishing tasks. The goal is to make Pylings feel more reliable, maintainable, and learner-friendly before expanding the curriculum further.

Scope

This issue covers product hardening, learner experience, contributor ergonomics, and curriculum maintainability.

Out of scope for this issue:

• PyPI trusted publishing setup
• Package name changes
• Release automation fixes unrelated to local product behavior

Workstreams

1. Add pylings doctor

Create a diagnostic command that helps users and contributors understand whether their install/workspace is healthy.

Suggested checks:

• Python version is supported.
• Installed package version is visible.
• Current root has info.toml.
• exercises/, checks/, and solutions/ exist.
• Every manifest exercise has a matching exercise file, check file, solution file, hint, and official docs URL.
• .pylings/state.json is readable or can be safely recreated.
• .pylings/originals/ exists for initialized workspaces.
• Bundled local docs snippets are available.

Expected output:

• Human-readable status table.
• Exit 0 when healthy.
• Exit non-zero when required files are missing or corrupt.
• Include actionable repair hints such as pylings update or pylings init --path ....

2. Implement Real File Watching

--watch-files is wired through the CLI/app but currently does not watch filesystem events.

Desired behavior:

• Use watchdog.Observer to watch exercises/ in the current workspace.
• Ignore __pycache__, .pyc, temp files, and non-Python files.
• Debounce rapid save events.
• Trigger the active exercise check when the current exercise file changes.
• Keep behavior predictable if the user edits a different exercise from the active one.
• Shut down watcher threads cleanly when the TUI exits.

3. Convert Reference Solutions Into Readable Files

Current solution files are small stubs that load source from solutions/_answers.py. That passes verification but is hard to review and weak as teaching material.

Target state:

• Each solutions/<exercise>.py contains the actual readable solution.
• Remove or greatly reduce solutions/_answers.py.
• Keep pylings solution <name> behavior unchanged.
• Preserve tests that prove every reference solution passes.
• Prefer straightforward teaching-quality code over clever/minimal code.

4. Improve First-Run UX

Add an in-app first-run/onboarding experience so learners do not rely only on the README.

Potential content:

• What Pylings is.
• What file the learner should edit.
• Why checks fail initially.
• How to open hints and docs.
• How reset works.
• How to quit.

Acceptance criteria:

• New users get guidance on first launch.
• Experienced users can dismiss/skip it.
• State persists so the intro does not appear every time.

5. Add Curriculum Audit Tooling

Create a contributor-facing check that audits curriculum structure and quality signals.

Suggested command:

pylings audit-curriculum

Suggested validations:

• Manifest ordering is valid.
• Exercise/check/solution files are mirrored.
• Docs URL is official Python docs where expected.
• Local docs snippet exists for each topic.
• Hints are non-empty.
• No duplicate exercise names.
• No solution file is still a loader stub after the solution migration.

6. Add Topic Intros

Add short topic introductions for each major topic.

Target behavior:

• Store topic intro Markdown locally, for example pylings/docs/topic_intros/<topic>.md or similar.
• Show the intro before the first exercise in a topic or from the docs panel.
• Keep intros brief and practical: concepts, common mistakes, and what the learner will practice.

7. Improve Workspace Update Safety

pylings update currently preserves exercises and overwrites checks/solutions. Make updates more transparent and safer.

Potential improvements:

• Add curriculum/package version metadata to initialized workspaces.
• Print an update report: added, changed, preserved, skipped.
• Back up overwritten managed files before replacing them.
• Detect local edits in managed directories such as checks/ and solutions/.
• Add --dry-run for updates.

8. Expand Installed-Wheel CI Coverage

CI already builds and installs the wheel, but the installed smoke test is minimal.

Add installed-wheel checks for:

pylings --version
pylings init --path /tmp/pylings-workspace
pylings --root /tmp/pylings-workspace list
pylings --root /tmp/pylings-workspace solution variables1
pylings --root /tmp/pylings-workspace reset variables1 --yes
pylings --root tests/fixtures/passing_curriculum verify

Recommended Order

1. Add pylings doctor.
2. Implement real file watching.
3. Convert solutions into readable files.
4. Improve first-run UX.
5. Add curriculum audit tooling.
6. Add topic intros.
7. Improve workspace update safety.
8. Expand installed-wheel CI coverage.

Done Criteria

• Each workstream either has a merged implementation PR or a dedicated follow-up issue.
• New commands include integration tests.
• TUI changes include Textual pilot tests where practical.
• README and contributor docs reflect new commands/behavior.
• Full test suite and installed-wheel smoke path pass.