refactor(core,wasm): migrate parsers + base32 dedup + WASM exports (Plan B Phases 7, 8) #5

Open
alee wants to merge 0 commits from feature/cli-tail-stream-c-core-wasm-seam into main
Owner

Summary

  • Phase 7parse_month_year, base32_decode_lenient, guess_mime migrated from CLI to relicario-core (MonthYear::parse, new base32 module with encode_rfc4648 / decode_rfc4648_lenient, new mime::guess_for_extension). Base32 dedup folds crates/relicario-core/src/item.rs:255-275 (base32_encode) and import_lastpass.rs:202-220 (decode_base32_totp) into the new shared module. Steam alphabet at item_types/totp.rs:13 left alone with a [crate::base32] neighbour comment.
  • Phase 8#[wasm_bindgen] exports for the three migrated parsers; extension/src/wasm.d.ts mirror updated in the same commit; snake_case JS naming consistent with existing exports.
  • CLI parse.rs is a thin re-export shim — existing callsites in commands/{add,edit,attach}.rs need no import changes; RelicarioError auto-converts to anyhow::Error at `?` boundaries.

Spec / coordination

  • Implements docs/superpowers/specs/2026-05-04-cli-restructure-design.md Phases 7 and 8.
  • See docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md for cycle-2 partition.
  • Pairs with DEV-A's P2 base32 dedup finding (three RFC 4648 impls in core).

Spec-vs-reality decision

Plan B Phase 7 said `pub(crate) mod base32` — but the CLI shim and the new Phase 8 WASM exports both need to reach `decode_rfc4648_lenient` from outside `relicario-core`. Promoted to `pub mod base32`. PM ack'd in directive 2026-05-09T15:13Z.

Test plan

  • `cargo test --workspace` — green (143 core lib tests, +7 from new MonthYear::parse / mime / parse_secret coverage; 8 wasm session/parser tests; full CLI integration suite)
  • `cargo clippy --workspace --all-targets` — silent
  • `cargo build -p relicario-wasm --target wasm32-unknown-unknown` — clean
  • `cd extension && npm run test` — 17 pre-existing failures only (identical to PM's 2026-05-06 baseline cluster: 6 popup/devices, 9 popup/settings, 1 SW/router, 1 SW/devices); no new regressions; `wasm.d.ts` compiles against TS callers
  • Existing `crates/relicario-cli/tests/*` pass without modification
  • Existing `crates/relicario-core/tests/*` pass without modification
  • simplify pass run on full branch diff; two findings addressed (lib.rs module list mention; totp.rs neighbour comment style unification)

Out of scope (deferred)

  • Extension consumption of the new WASM exports — Plan C territory; no SW message handlers wired in this PR
  • camelCase JS naming for the three new exports — explicitly snake_case per Plan B; the camelCase decision is its own future plan
  • `commands/{edit,get}.rs`'s `data_encoding::BASE32.encode` for TOTP-secret display — could unify with `relicario_core::base32::encode_rfc4648` in a follow-up but switches output padding (user-visible). Deferred.
  • Bringing `MonthYear::new` to `RelicarioError` — DEV-A's separate P3 nit, kept out of scope per Plan B's recommendation.

🤖 Generated with Claude Code

## Summary - **Phase 7** — `parse_month_year`, `base32_decode_lenient`, `guess_mime` migrated from CLI to `relicario-core` (`MonthYear::parse`, new `base32` module with `encode_rfc4648` / `decode_rfc4648_lenient`, new `mime::guess_for_extension`). Base32 dedup folds `crates/relicario-core/src/item.rs:255-275` (`base32_encode`) and `import_lastpass.rs:202-220` (`decode_base32_totp`) into the new shared module. Steam alphabet at `item_types/totp.rs:13` left alone with a [`crate::base32`] neighbour comment. - **Phase 8** — `#[wasm_bindgen]` exports for the three migrated parsers; `extension/src/wasm.d.ts` mirror updated in the same commit; snake_case JS naming consistent with existing exports. - **CLI `parse.rs`** is a thin re-export shim — existing callsites in `commands/{add,edit,attach}.rs` need no import changes; `RelicarioError` auto-converts to `anyhow::Error` at \`?\` boundaries. ## Spec / coordination - Implements `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phases 7 and 8. - See `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` for cycle-2 partition. - Pairs with **DEV-A's P2 base32 dedup** finding (three RFC 4648 impls in core). ## Spec-vs-reality decision Plan B Phase 7 said \`pub(crate) mod base32\` — but the CLI shim and the new Phase 8 WASM exports both need to reach \`decode_rfc4648_lenient\` from outside \`relicario-core\`. Promoted to \`pub mod base32\`. PM ack'd in directive 2026-05-09T15:13Z. ## Test plan - [x] \`cargo test --workspace\` — green (143 core lib tests, +7 from new MonthYear::parse / mime / parse_secret coverage; 8 wasm session/parser tests; full CLI integration suite) - [x] \`cargo clippy --workspace --all-targets\` — silent - [x] \`cargo build -p relicario-wasm --target wasm32-unknown-unknown\` — clean - [x] \`cd extension && npm run test\` — 17 pre-existing failures only (identical to PM's 2026-05-06 baseline cluster: 6 popup/devices, 9 popup/settings, 1 SW/router, 1 SW/devices); no new regressions; \`wasm.d.ts\` compiles against TS callers - [x] Existing \`crates/relicario-cli/tests/*\` pass without modification - [x] Existing \`crates/relicario-core/tests/*\` pass without modification - [x] simplify pass run on full branch diff; two findings addressed (lib.rs module list mention; totp.rs neighbour comment style unification) ## Out of scope (deferred) - **Extension consumption of the new WASM exports** — Plan C territory; no SW message handlers wired in this PR - **camelCase JS naming** for the three new exports — explicitly snake_case per Plan B; the camelCase decision is its own future plan - **\`commands/{edit,get}.rs\`'s \`data_encoding::BASE32.encode\`** for TOTP-secret display — could unify with \`relicario_core::base32::encode_rfc4648\` in a follow-up but switches output padding (user-visible). Deferred. - **Bringing \`MonthYear::new\` to \`RelicarioError\`** — DEV-A's separate P3 nit, kept out of scope per Plan B's recommendation. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
alee added 39 commits 2026-05-09 15:34:53 +00:00
Three-reviewer architecture audit (DEV-A: core, DEV-B: cli/server/wasm,
DEV-C: extension/relay) plus PM synthesis. Lens: make the codebase
readable for a smart developer who doesn't know Rust but wants to learn
by tinkering.

Top synthesis findings (P1):
- SessionHandle has no impl Drop; .free() is a cleanup no-op (cross-cutting Rust+JS)
- cli/main.rs is a 2641-line monolith with no submodule boundaries
- setup.ts (1220 LOC) bypasses the SW and orchestrates WASM directly
- vault.ts (1027 LOC) owns shell + sidebar + list + drawer + routing
- shared/state.ts is fully any-typed
- recovery_qr.rs is undocumented vs. rest of crypto-adjacent core
- duplicated SW router helpers (storage + itemToManifestEntry)
- pure parsers (parse_month_year, base32_decode_lenient) belong in core
- 16x duplicated git invocation boilerplate with one-line errors

CLI/extension parity: 22/23 capabilities ✓; only true gap is `relicario
status` (no get_vault_status); `detach` is partial via update_item.

Also fixes tools/relay/queue.test.ts:54 to match the dev-c role
expansion already in queue.ts (was failing 1/4; now 5/5 pass).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Catches the workspace and the extension manifests up to the v0.5.x
release line (was still showing 0.2.0).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
GLYPH_TYPE_IDENTITY changed from ⌬ to ◍ so it's visually distinct from
GLYPH_DEVICES (also ⌬). Adds a CSS rule asserting [hidden] over the
.form-actions display:flex so the fullscreen sticky save bar can hide
the inner action row by attribute.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
queue.ts and server.ts now know about dev-c alongside pm/dev-a/dev-b
so the four-role coordination paradigm works end-to-end. start.sh
opens a fourth window for dev-c. call.py and call.ts are HTTP shims
that agents can use when the MCP relay tools aren't registered in
their session (the kickoff prompts reference call.py by path as a
fallback).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds the four kickoff prompts that drove the 2026-05-04 whole-codebase
architecture audit (PM + DEV-A/B/C reviewers), the planning prompt
that converts the synthesis into three implementation plans, and the
PM + DEV-A/B/C kickoff prompts for executing those plans in parallel.

Also updates the existing v0.5.1-* prompts with the relay-server
fallback section that references the new tools/relay/call.py shim.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
.gitea_env_vars is local Gitea config that shouldn't be checked in
(synthesis open decision #8). The .dev-c-content.md hidden file is a
raw subagent-output draft from the 2026-05-04 review — the canonical
notes are already in dev-c-notes.md alongside its peers.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Plan A (security & docs polish, S): SessionHandle impl Drop + JS .free()
audit + recovery_qr.rs documentation + relay launcher dev-c expansion.
Independent of B/C; ships first.

Plan B (CLI restructure, M-L): split cli/main.rs (2641 LOC) into commands/
folder + prompt.rs + parse.rs; helpers::git_run captures stderr; Vault::
after_manifest_change centralizes the groups-cache discipline; canonical
ParamsFile; batched purge; migrate parse_month_year/base32_decode_lenient/
guess_mime to relicario-core with WASM re-exports.

Plan C (extension restructure, L): typed StateHost (precondition); extract
service-worker/storage.ts; setup.ts SW migration via create_vault/
attach_vault messages + step-registry pattern; vault.ts split into
shell/sidebar/list/drawer/form-wrapper with vault_locked channel
unified through shared/state.ts; P2 cluster (timer reset, gitHost clear,
teardown helper, allSettled, MutationObserver debounce); get_vault_status
closes the relicario status parity gap.

Cross-boundary cites verified: Plan B Phase 8 WASM exports are the seam
Plan C consumes (deferred to a future plan); Plan A owns the .free() swallow
removal that Plan C respects without redoing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
TL;DR-first guide to the PM/Senior-Dev paradigm: how to invoke
/multi-agent-kickoff, how the launcher's three modes (manual/tmux/kitty)
work, the in-memory queue + per-role inbox semantics, the call.py /
call.ts fallback shims, message kinds, conventions, and troubleshooting.

Lives next to the kickoff prompts in docs/superpowers/coordination/ so
the workflow's docs and outputs share one home.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Generated by /multi-agent-kickoff for the three architecture-review
followup plans. PM coordinates; Dev-A owns Plan A (security & docs polish,
S, ships first); Dev-B owns Plan B (CLI restructure, M-L); Dev-C owns
Plan C (extension restructure, L).

Each dev prompt forces cd into its worktree (per project memory rule),
includes the relay tool calls + Python shim fallback, scopes hard-rules
to the planning subagents' flagged judgment calls, and ships an opinionated
PR title + body template that mirrors the plan's Done criteria.

PM prompt enforces the cross-plan boundaries: A is independent; B Phase 8
WASM exports are a seam C does not consume in this train; A owns the
.free() swallow removal and Drop impl; if both B and C touch wasm.d.ts,
B sequences first.

Launcher discovers these via `ls -t coordination/*-<role>-prompt.md | head -1`
so they take precedence over previous kickoff sets.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Closes the P1.1 defense-in-depth gap: wasm-bindgen's auto-generated
.free() previously dropped the SessionHandle wrapper (a u32) without
removing the SESSIONS HashMap entry, leaving the master key and
image_secret in WASM linear memory until JS explicitly called
lock(handle). Drop now wires .free() to session::remove, and the
new native test pins the contract.

Refs: docs/superpowers/specs/2026-05-04-security-polish-design.md (Phase 1)
Refs: docs/superpowers/reviews/2026-05-04-architecture-review.md (P1.1)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 1 added impl Drop for SessionHandle on the Rust side so .free()
now actually removes the SESSIONS registry entry. The JS-side
try { current.free() } catch { /* already freed */ } swallow was
hiding the fact that .free() wasn't doing the cleanup at all;
post-Phase-1 it has to go so failures surface instead of being lost.

.free() callsite audit: exactly one match under extension/src/ — the
SW session.ts line this commit edits. Lifecycle audit: clearCurrent()
is reached via (a) popup lock → router popup-only.ts and (b)
session-timer expiry → service-worker/index.ts.

Refs: docs/superpowers/specs/2026-05-04-security-polish-design.md (Phase 2)
Refs: docs/superpowers/reviews/2026-05-04-architecture-review.md (P1.1, DEV-C P2 service-worker)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 3 of the security-polish series. Brings recovery_qr.rs up to
the documentation density of crypto.rs / imgsecret.rs / backup.rs /
tar_safe.rs. No runtime behaviour change: just module-level //! header
explaining the format + KDF domain separation + parameter-pinning
rationale, an ASCII diagram of the 109-byte payload layout pinned by
a static assertion, doc-comments on the four public items, and named
slice-range constants for the offset arithmetic.

production_params() is replaced with a top-level const so the "pinned,
do not change once shipped" property is visible at every use site.

Refs: docs/superpowers/specs/2026-05-04-security-polish-design.md (Phase 3)
Refs: docs/superpowers/reviews/2026-05-04-architecture-review.md (P1.7)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 3 code-quality review caught that the [`RECOVERY_PRODUCTION_PARAMS`]
form in the module header introduced a new rustdoc warning (the const is
module-private, so the link only resolves under --document-private-items).
Drop the brackets so it renders as plain backticks — same visual, no
broken link, no need to widen visibility.

Refs: docs/superpowers/specs/2026-05-04-security-polish-design.md (Phase 3)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 4 of the security-polish series. The relay was expanded from 3
roles (pm + dev-a + dev-b) to 4 (adds dev-c) in dd0010d, but the
launcher script never followed — it still opened only 3 windows and
the manual-mode banner said "3 new terminals". Add DEV_C_PROMPT
discovery alongside the existing PM/Dev-A/Dev-B lines, and a fourth
window/tab/terminal in each of the three modes (manual / tmux / kitty)
plus the corresponding banner and summary-print updates.

The queue.test.ts assertion update part of P1.8 already shipped in
061facd — this commit closes the launcher half.

Refs: docs/superpowers/specs/2026-05-04-security-polish-design.md (Phase 4)
Refs: docs/superpowers/reviews/2026-05-04-architecture-review.md (P1.8)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Partitions Plan B's remaining phases (3-8) across three cycle-2 streams
once cycle-1 Stream A and Stream B's bundled Phase 1+2 PR have merged.
Stream A picks up Phase 3 (prompt_or_flag + builder compression),
Stream B owns Phases 4/5/6 (after_manifest_change, ParamsFile, batched
purge), Stream C owns Phases 7/8 (parser migration to relicario-core +
WASM exports). Plan C (extension restructure) is not in cycle 2.

Each kickoff bakes in cycle-1 lessons: prefer single-line relay body
content, avoid the f-string footgun in Python inbox-monitor scripts,
narration discipline (IN-PROGRESS updates at meaningful in-flight
moments, not just phase boundaries). The PM prompt also captures
cycle-1 outcomes (commits/PRs landed, the 17 pre-existing extension
test failures pattern, DEV-B's option-(b) git_run choice) so the new
PM picks up cold without relay history.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Each Dev A/B/C kickoff now declares the project's `.claude/settings.json`
auto-allow surface (write/cargo/npm/bun/python3/commit/push/PR), enumerates
the hard deny-list guardrails (no rm, no force-push, no reset --hard, no
branch -D, no worktree remove, no clean -f*, no checkout -- *, no sudo,
no chmod 777, no DB drops), and bakes in the simplify discipline required
before every REVIEW-READY: invoke superpowers:simplify on changed code,
no parallel implementations of existing helpers, no defensive checks for
impossible scenarios, no comments unless the WHY is non-obvious, no
half-finished implementations.

Why now: cycle-1 Stream B reached final-validation in roughly an hour
and a half. The bottleneck for cycle-2 is review/iteration cadence, not
typing speed — pushing devs to move at full auto-allow speed while
forcing a simplify pass shifts the cost from "PM rework after merge"
to "dev catches duplication before REVIEW-READY".

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
5 commits from feature/arch-followup-stream-a-security-polish:
- 1e858e1 fix(wasm): impl Drop for SessionHandle clears registry entry
- 03d0781 fix(ext): unswallow free() errors in SW session.clearCurrent + vitest
- 229e483 docs(core): bring recovery_qr.rs to the documented-zone standard
- f8296fa docs(core): drop intra-doc link to private RECOVERY_PRODUCTION_PARAMS
- 0c9387f fix(relay): start.sh opens fourth window for dev-c

Pre-merge checklist on tip 0c9387f:
- cargo test --workspace: 254 tests, 0 failures
- cargo clippy --workspace --all-targets: silent
- cargo build -p relicario-wasm --target wasm32-unknown-unknown: clean

Plan A complete.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
18 commits from feature/arch-followup-stream-b-cli-restructure landing the
mechanical split of crates/relicario-cli/src/main.rs into commands/ +
parse.rs + prompt.rs (Plan B Phase 1) plus the git_run helper and 15-site
sweep (Plan B Phase 2). main.rs lands at 509 LOC: substance criterion
met (clap surface + dispatch + 2 shim families only); the 9-LOC overshoot
vs spec's =500 is #[arg(...)] attribute density on 9 sub-enums and was
accepted at cycle-1 review.

Phase 1 (split):
- 02e05f7 refactor(cli): add commands/, prompt.rs, parse.rs scaffold (no-op)
- 272b6a3 refactor(cli): move prompt helpers into prompt.rs
- 5240023 refactor(cli): move parse helpers into parse.rs
- 17bde16 refactor(cli): move cmd_generate + cmd_rate into commands/
- b9b07ec refactor(cli): move cmd_init into commands/init.rs (carries inline ParamsFile)
- 13c2fc2 refactor(cli): hoist commit_paths + resolve_query into commands/mod.rs
- da7d7d1 refactor(cli): move cmd_get/list/history/status/sync into commands/
- 530c479 refactor(cli): move trash family (rm/restore/purge/trash) into commands/
- c2f3c35 refactor(cli): move cmd_backup into commands/backup.rs
- 615afd7 refactor(cli): move cmd_import into commands/import.rs
- 6676d25 refactor(cli): move attach family (attach/attachments/extract/detach)
- 3811b07 refactor(cli): move cmd_recovery_qr family into commands/recovery_qr.rs
- 08bdfbc refactor(cli): move cmd_settings into commands/settings.rs
- 2d5b86b refactor(cli): move cmd_device + load_gitea_client into commands/device.rs
- 64275bc refactor(cli): move cmd_edit family into commands/edit.rs
- 2d1f092 refactor(cli): move cmd_add + 7 build_*_item helpers into commands/add.rs

Phase 2 (git_run):
- f3cdbed feat(cli): add helpers::git_run with stderr capture + context bail
- 97c8f99 refactor(cli): sweep 15 bail("git X") sites to use git_run with context labels

Pre-merge checklist on tip 97c8f99:
- cargo test --workspace: all green (helpers, attachments, basic_flows, backup,
  edit_and_history, import, settings, vault_detection)
- cargo clippy --workspace --all-targets: silent
- cargo build -p relicario-wasm --target wasm32-unknown-unknown: clean

Plan B Phases 1+2 complete. Phases 3-8 partitioned across cycle-2 streams.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
New crates/relicario-core/src/base32.rs hosts encode_rfc4648 +
decode_rfc4648_lenient (case-insensitive, optional padding, whitespace
stripped). Folds inline base32_encode (item.rs:255-275) and
decode_base32_totp (import_lastpass.rs:202-220) into the shared module;
both call sites updated.

- New RelicarioError::InvalidBase32(String) variant for the decoder
  error path
- Module is pub(crate); public API surface unchanged
- Steam alphabet (item_types/totp.rs:13) intentionally separate with
  neighbour comment pointing at crate::base32

Plan B Phase 7 sub-step 1 (DEV-A P2 base32 dedup half).
docs/superpowers/specs/2026-05-04-cli-restructure-design.md.

cargo test --workspace: green
cargo clippy --workspace: silent

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Plan B Phase 7 sub-step 2 — moves the bodies of parse_month_year,
base32_decode_lenient, guess_mime from crates/relicario-cli/src/parse.rs
to relicario-core. The CLI's parse.rs becomes a 19-line shim re-exporting
the new core API.

New core surface:
- time::MonthYear::parse (Result<_, RelicarioError>)
- mime::guess_for_extension (new mime module)
- item_types::TotpConfig::parse_secret — Zeroizing<Vec<u8>> wrapper
  over base32::decode_rfc4648_lenient

base32 module promoted from pub(crate) to pub so non-core consumers
(CLI shim, future Phase 8 WASM exports) can reach it. New
RelicarioError::InvalidMonthYear(String) for the parse error path
(mirrors sub-step 1's InvalidBase32). MonthYear::new keeps its
&'static str error type — bringing it to RelicarioError is DEV-A's P3.

CLI callsites unchanged (commands/{add,edit,attach}.rs); RelicarioError
auto-converts to anyhow::Error at ? boundaries.

cargo test --workspace: green (core 143, +7 from new tests)
cargo clippy --workspace: silent

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Plan B Phase 8 — three #[wasm_bindgen] exports for the parsers migrated
in Phase 7, mirrored in extension/src/wasm.d.ts under "Pure parsers
(no session needed)". snake_case JS naming consistent with every
existing export; SessionHandle not required.

- parse_month_year(s) → { month, year } via js_value_for
- base32_decode_lenient(s) → Uint8Array
- guess_mime(filename) → string

Tests in session_tests mod cover the OK paths; error-path / JsValue
serialization can't be tested natively (JsError construction panics
off-wasm) and is covered in core (time::tests + base32::tests).

Plan C will wire SW message handlers consuming these exports in a
future round; this commit delivers only the seam.

Includes simplify-feedback fixes:
- relicario-core lib.rs module-list mentions base32 and mime
- item_types/totp.rs neighbour comment unified to ///-style block

cargo test --workspace: green
cargo clippy --workspace: silent
cargo build -p relicario-wasm --target wasm32-unknown-unknown: clean
cd extension && npm run test: 17 pre-existing failures only (baseline)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This branch is already included in the target branch. There is nothing to merge.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feature/cli-tail-stream-c-core-wasm-seam:feature/cli-tail-stream-c-core-wasm-seam
git checkout feature/cli-tail-stream-c-core-wasm-seam
Sign in to join this conversation.
No Reviewers
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: alee/relicario#5