feat(tools): add P2 typed CLI-text read tools (TP-3)

[millsmillsymills]

Implements the P2 band and its TP-3 prerequisite from docs/superpowers/plans/2026-06-23-tool-coverage-to-90pct.md. P0/P1 landed in #130; this is the next phase.

What's here

• TP-3 — cli_typed helper (tools/_common.py): benign-only wrapper over client.cli_exec, reusing the existing _io_lock-held exchange. It refuses any gated command, so a transmit/destructive subcommand can never hide behind a typed tool.
• Four typed CLI-text read tools (tools/cli_typed.py, gate none, USB-only):
  • flipperzero_core_status — free + uptime → heap fields, heap_free_bytes, uptime.
  • flipperzero_fs_tree — storage tree <path> → depth-tagged file/dir entries, complete/truncated.
  • flipperzero_loader_list — loader list → app names.
  • flipperzero_i2c_scan — i2c → responding 7-bit addresses.
• Each returns the raw output alongside parsed fields (firmware CLI text is free-form/unversioned).
• All raise the typed CLI text mode unavailable error over the WiFi bridge (TP-2).

Grounded in real device output

Parsers were built and validated against output captured live over USB (Momentum firmware), and the four tools were exercised end-to-end through the MCP server against the device. Notably the i2c output is a positional grid, not Found: 0x.. lines — the parser maps each non-- cell's (row, column) to its 7-bit address.

Deferred (intentional)

• crypto_status (5th P2 tool in the plan): the device crypto command is a usage dump (encrypt/decrypt/has_key/store_key) with no benign read-only status subcommand. Shipping it would return raw help text, which the plan's §1 says does not earn coverage. Left out pending a real read command.
• Golden fixtures (§6.4): the byte-replay fixtures are per-firmware and need both Momentum and Official hardware; only Momentum is on hand. Parser shapes are locked by unit tests against captured output in the meantime. Follow-up once Official firmware is available.

Coverage

P2 lands +4 (not +5) typed counting tools → matrix now 28 registered tools, new cli_typed group.

Tests

• tests/unit/test_tool_cli_typed.py — parser tests against real captured output (incl. the i2c grid and the app-open uptime case) + WiFi refusal.
• tests/integration/test_cli_typed_reads.py — usb-marked live reads.
• Schema-matrix drift test + GATE map updated. Full non-integration suite: 276 passed.

Note

While capturing reference output, a storage tree /ext (whole volume) flooded USB and briefly wedged the CLI link mid-stream — it recovered on its own. fs_tree's docstring warns to pass a specific subdirectory; bounding large-tree captures cleanly is the TP-4a streaming-primitive work in a later phase.

🤖 Generated with Claude Code

[millsmillsymills]

Review summary (/review-pr)

Parallel agents: code-quality, silent-failure, test-coverage.

Must-fix: none. The feared cli_typed None-fall-off does not fire — _classify_client_error is NoReturn and ty validates the -> CliExecResult annotation; the pattern matches ~25 existing call sites.

Fixed in 4a385aa:

• _parse_i2c hardened: row regex [0-9a-fA-F]→[0-7], column bound < 16 — malformed grid output can no longer surface addresses outside the 7-bit space.
• New tests: multi-device i2c, out-of-range row, fs_tree truncated (completed=False) path, and the gated-command refusal in cli_typed (sev-9 defense-in-depth control, previously zero coverage).

Gates: ruff + ty clean, 281 passed / 13 deselected.

Deferred to followup (not blocking): device-unreachable path test for the shared cli_typed helper, ANSI-embedded fixtures for _parse_i2c/_parse_tree, and _parse_tree sizeless-file / ANSI-before-indent depth edges.