## Link to GitHub Issue or related Pull Request, if one exists
N/A
## Description of change
I am developing [spice.nimabe.net](https://spice.nimabe.net), a static
frontend for SpiceAPI. It already supports generating and inserting new
card IDs, but SpiceAPI does not provide a way to discover cards already
configured on the game machine.
This makes the frontend inconvenient for existing users who generated
and saved their card IDs locally. They currently have to open each card
file on the game machine and manually copy its ID into the frontend.
This change adds a `card.get_cards` API function that enumerates the
current cards for readers supported by the running game. Each entry
contains:
- reader index
- canonical 16-character card ID
- `source`, set to `file` or `override`
- `file_name` for file-backed cards
File-backed cards expose only the save-file basename. Active `-card0`
and `-card1` values are returned with `source: "override"` and no
`file_name`, instead of representing an override as a file. spicefe
derives the useful default import names `card0` and `card1` from the
reader index. Reader enumeration uses `eamuse_get_game_keypads()` so
games with only one reader do not expose a second card.
This allows spicefe and other API clients to offer one-click import for
existing cards, without requiring users to manually find and copy their
card IDs.
Because card IDs are sensitive, `card.get_cards` can only be used when
the operator has configured an API password. No full filesystem path is
exposed. Missing, unreadable, and invalid cards are omitted.
The existing `card.insert` function remains unchanged. To avoid
requiring a password for the whole card module, this change adds support
for password requirements on individual API functions while preserving
existing module-wide password behavior.
Access to configured card paths and runtime card overrides is
synchronized because API requests may read them concurrently with
configuration updates.
The Python and Dart API wrappers and README documentation have been
updated for the new function and source metadata.
## Testing
- Ran the complete `src/spice2x/build_docker.sh` build successfully.
- Built all required 32-bit and 64-bit targets.
- Built the Windows XP-compatible 32-bit targets.
- Passed static import checks.
- Passed Windows 7 and Windows XP compatibility checks.
- Completed release packaging successfully.
- Verified both updated Dart wrappers are correctly formatted.
- Ran all 106 spicefe tests successfully.
- `git diff --check` passes.
*This implementation was prepared with assistance from OpenAI Codex.*
Jiongjia LuandGitHub
dad88caf01