Skip to content

refactor: command-shaped app API and per-base extract contract #710

Open

Description

@moonD4rk

Why

The package layout is sound, but the orchestration layer and the extractor contract are hard to follow:

  • internal/app exports twelve stage functions that cmd has to choreograph, so no single function shows what a command does.
  • Secrets and extractors travel as function values and closures, so finding where a value comes from takes several hops.
  • browser.Input is a union of what the three bases need.
  • Several names describe a mechanism rather than a meaning, and a few words name two things.

Goals

  • internal/app exports one function per command (Dump, DumpKeys, Archive, Restore, List). cmd only parses flags, calls it, and prints.
  • Secrets are passed as values with an explicit scope: per run, per user data dir, or per profile.
  • Each base package exports the same three functions, Discover, Sources, and Extract, and takes its own secret as a typed parameter. browser.Input goes away, and browser.ProfileSnapshot holds a profile's captured files only.
  • Names follow a few rules: a type name carries a domain noun, one word names one concept, Path is absolute and RelativePath is relative, and a field named X holds the X itself.

Non-goals

  • No change to commands, flags, defaults, output formats, keys.json, the archive layout, or exit codes.
  • No change to parsing or key-retrieval internals.
  • No package moves under internal/.

Plan

  • 1. Preparation: goldens for the rendered help and error output, and renames only (refactor: pin CLI output and rename path fields #711)
  • 2. app exports one function per command, and -o of dumpkeys and archive is validated up front
  • 3. Secrets as values, with the RFC-001 and RFC-003 wording updated
  • 4. Per-base Sources and Extract, ProfileSnapshot, cleanup, and a package map in CONTRIBUTING.md

Every step keeps the existing golden files unchanged.

Behavior changes

Only step 3 changes behavior on purpose:

  • A secret is retrieved when the first extraction needs it, not the first record. A run that asks only for passwords or credit cards may therefore retrieve a key, and on macOS prompt, even when the store holds no encrypted row.
  • --firefox-pw-stdin reads stdin at startup.
  • The locked-keychain warning is printed once at the end of the run.

Activity

  1. added
    refactorCode restructuring without changing external behavior
    on Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    refactorCode restructuring without changing external behavior

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions