119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
---
|
|
id: PLN-0133
|
|
ticket: system-run-cart
|
|
title: Implement Games Root Library Discovery
|
|
status: done
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0036]
|
|
tags: []
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0036` requires a host-provided games root and an expandable internal
|
|
library model before Home can render or launch games. This plan implements the
|
|
library discovery and host plumbing only; UI launch wiring is handled by
|
|
`PLN-0134`.
|
|
|
|
## Objective
|
|
|
|
Add a tested games-root discovery model that scans immediate child directory
|
|
cartridges, filters to valid Game manifests, records diagnostics for invalid
|
|
candidates, and carries enough metadata for Home rendering and later launch.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: `DEC-0036`.
|
|
- `PLN-0132` should be completed first so code follows the documented contract.
|
|
- Existing cartridge manifest and directory loader behavior in the console
|
|
crates.
|
|
- Existing host CLI and `HostRunner` boot setup.
|
|
|
|
## Scope
|
|
|
|
- Add `--games-root <PATH>` to the desktop host CLI.
|
|
- Pass the optional games root into the host runner / firmware initialization
|
|
path without changing direct `--run` or `--debug` boot behavior.
|
|
- Add a SystemOS-owned games library model for directory cartridge discovery.
|
|
- Scan only immediate child directories of the root.
|
|
- Read and retain manifest data for each valid candidate.
|
|
- Include only candidates whose manifest declares `app_mode: Game`.
|
|
- Retain internal cartridge path and operational discovery metadata on each
|
|
entry.
|
|
- Emit diagnostics for invalid, unreadable, or non-Game candidates and omit
|
|
them from the returned entries.
|
|
- Keep discovery independent from full cartridge launch: discovery reads
|
|
metadata; launch still uses the existing loader in `PLN-0134`.
|
|
|
|
## Non-Goals
|
|
|
|
- No Home list rendering.
|
|
- No click handling or `LoadCartridge` transition.
|
|
- No `.pmc` discovery.
|
|
- No recursive scan.
|
|
- No Shell/System app catalog.
|
|
- No marketplace metadata, icons, search, sorting UI, or polished errors.
|
|
- No new guest syscall.
|
|
|
|
## Execution Method
|
|
|
|
1. Introduce a library/discovery module in the SystemOS side, preferably under
|
|
`crates/console/prometeu-system/src/services/` unless the existing module
|
|
layout has a more local owner.
|
|
2. Define an internal entry type with at least:
|
|
- loaded cartridge manifest data;
|
|
- `title`;
|
|
- `app_id`;
|
|
- `app_version`;
|
|
- internal cartridge path;
|
|
- discovery metadata, using `SystemTime` or another explicit discovery
|
|
marker.
|
|
3. Define discovery diagnostics that can be logged by the caller and asserted in
|
|
tests.
|
|
4. Implement a scanner that:
|
|
- accepts an optional root path;
|
|
- returns an empty library when no root is configured;
|
|
- iterates only immediate child directories;
|
|
- parses `manifest.json` using structured manifest types, not ad hoc string
|
|
matching;
|
|
- filters to `app_mode: Game`;
|
|
- sorts entries deterministically for stable Home presentation and tests.
|
|
5. Add `--games-root <PATH>` to
|
|
[crates/host/prometeu-host-desktop-winit/src/lib.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/lib.rs)
|
|
and pass the path into
|
|
[crates/host/prometeu-host-desktop-winit/src/runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs).
|
|
6. Store or expose the discovered library to firmware/SystemOS in a way that
|
|
`PLN-0134` can consume without re-scanning inside the Home click path.
|
|
7. Add focused unit tests using temporary cartridge roots with:
|
|
- one valid Game directory cartridge;
|
|
- one valid non-Game cartridge;
|
|
- one invalid directory;
|
|
- one nested directory that must not be discovered.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `--games-root <PATH>` is accepted by the desktop host CLI.
|
|
- Absence of `--games-root` leaves existing Hub boot behavior unchanged.
|
|
- Direct `--run <cart>` and `--debug <cart>` behavior remains unchanged.
|
|
- Discovery returns only immediate valid Game directory cartridges.
|
|
- Each library entry retains manifest data, path, title, app id, app version,
|
|
and discovery metadata.
|
|
- Invalid candidates are represented in diagnostics and excluded from entries.
|
|
- Discovery does not fully load or boot cartridge programs.
|
|
|
|
## Tests
|
|
|
|
- Add and run focused games-library discovery tests in the owning console crate.
|
|
- Run `cargo test -p prometeu-system` if the library lives in
|
|
`prometeu-system`.
|
|
- Run `cargo test -p prometeu-host-desktop-winit` for CLI/runner plumbing.
|
|
- Run `discussion validate`.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-system/src/services/`
|
|
- `crates/console/prometeu-system/src/lib.rs` or module exports as needed
|
|
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
|
|
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
|
- `discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md`
|