Community Help-Desk CLI

Time-box: 2–2.5 hours over two sessions
Milestone: a dependable menu program can open, list, search, close, summarise, save, and reload community requests.

Companion learning path: Python From First Principles. If Python or Git is not ready yet, use the free installation guide.

Start your own copy

On GitHub, select Use this template → Create a new repository, then clone your new repository and work in that copy. The starting red checks are intentional; your goal is to turn them green and complete the two human-review gates in MASTERY.md.

This final build combines pure functions, collections, text normalisation, JSON, expected exceptions, modules, a loop, and automated tests.

Program shape

• help_desk.py owns ticket rules, search, summaries, and JSON persistence.
• cli.py owns prompts, menu choices, and terminal output.
• Each ticket has an integer id, requester, issue, normalised category, one of three priorities (low, normal, high), and an open or closed status.
• Every state-changing function returns a new list instead of mutating its input.

Start here

python3 -B -I tests/run_tests.py

The untouched starter has exactly seven intentional test_todo_... failures. Its validation, missing-file, malformed-file, unknown-ticket, and empty-state checks should pass. Work in help_desk.py; the supplied cli.py menu will begin working as those domain functions become complete.

Suggested milestones:

1. Core (35 min): open_ticket, search_tickets, and close_ticket.
2. Insights (25 min): summarize_tickets with stable top issue words.
3. Persistence (30 min): load_tickets and save_tickets.
4. Integration (30 min): run the menu, inspect its data file, and repair any failed CLI flow.
5. Review (20 min): complete the mastery gate and rebuild one function from its test without another implementation open.

Behaviour contract

• New IDs are one greater than the largest existing ID and are never based on list length alone.
• Requester and issue text are stripped; category and priority are also case-folded.
• Search normalises alphabetic words and requires every query word to occur in a ticket's searchable text.
• Closing an existing ticket preserves all other data; an unknown ID raises LookupError with that ID.
• Summary counts statuses and categories and returns three deterministic issue-word counts.
• Missing JSON starts an empty desk. Invalid JSON, invalid UTF-8, unsupported fields, or invalid records stop with a clear message rather than being overwritten.
• A save writes a complete temporary file before replacing the destination. The menu commits an opened or closed ticket in memory only after that save succeeds.
• Input/output are injected into run_cli, which keeps its complete flow testable and lets ended input exit without a traceback.

Run it manually

After the starter tests are green, choose a disposable path:

python3 cli.py scratch-tickets.json

Do not put secrets or sensitive personal details in the file.

Then finish MASTERY.md.

Get your automatic project grade

1. Create your own copy from this template.

2. Read MASTERY.md, then create an attempt branch:

   git switch -c attempt/my-project

3. Build the project and run the same check GitHub uses:

   python3 -B -I tests/run_tests.py

4. Commit and push the attempt branch:

   git add .
   git commit -m "Complete project attempt"
   git push -u origin attempt/my-project

GitHub Actions grades every pushed attempt automatically. PASS — NAILED IT means every required check passed. REVISE — KEEP BUILDING means the run shows what to fix before you push again. You do not need the KODE Ń VIBE owner to review or start anything; the template's main branch stays quiet on purpose.

The free grading guide explains the result and its limits.