Skip to content

v0.1.0 — Initial implementation

This roadmap decomposes the initial v0.1.0 implementation into an ordered list of pull requests. Each PR is a self-contained feature: code + tests + user-facing documentation land together. Ordering follows the module's dependency direction (overview.md §6) — leaf packages first, so every PR builds and tests green on its own.

Conventions applied to every PR:

  • Tests are mandatory — no PR merges without tests covering its feature.
  • User-facing API is documented under docs/user-guide/, one page per package/topic, registered in the Zensical nav.
  • Specs are authoritative — implementation follows docs/specs/*; any deviation discovered while coding is called out in the PR description.

PR list

# PR Branch Feature Status
1 #4 docs/implementation-roadmap This roadmap. ✅
2 #5 feat/flexprompt flexprompt leaf package: Prompter, PromptRequest, process-wide singleton (SetPrompter/GetPrompter), NewCLIPrompter/NewMapPrompter/NewEnvPrompter/PrompterFunc, sentinel errors (prompter.md). Reference page docs/user-guide/flexprompt.md. ✅
3 #6 feat/flexvault-core flexvault core: VaultDriver + Initializer interfaces, Capabilities, sentinel errors, Manager (lifecycle enforcement, dispatch, retry, address validation, serialization), driver registration (Register/New), MapDecoder/EnvDecoder (vault-drivers.md §1–§9). Reference page docs/user-guide/flexvault.md. ✅
4 #7 feat/keepass-driver flexvault/driver/keepass: KeePass driver over gokeepasslib — Configure/Credentials/Unlock/Get/Set/List/Lock, Initializer, group/entry ↔ namespace/key mapping (vault-drivers.md §10). Reference page section. ✅
5 #8 feat/variant-engine internal/variant: generic Registry[V] — variant registration, discriminator, selectors, subset matching, exactly-one resolution, duplicate detection (variants.md §2–§7). Internal; public re-export lands with PR #11. ✅
6 #9 feat/loader-core flexconf loader core: New(dirs...), Load(name, &dst), options plumbing, YAML read, layer merge (§3), per-file shape validation, reflection binder (flexconf tag, defaults-by-instance, required, strict unknown keys, coercion incl. time.Duration/time.Time/TextUnmarshaler, Validate() hook, all-or-nothing), sentinel errors (config-loading.md, schema-and-binding.md). No token resolution yet (static pipeline). Reference pages docs/user-guide/flexconf.md, docs/user-guide/schema.md. ✅
7 #10 feat/templating Templating engine: token grammar, $$( escaping, node-tree substitution, typed whole-value vs string mixed scalars, Resolver interface, RegisterResolver/WithResolver/WithResolvers, env: (+WithEnv), file: (+WithFS), $(config:) includes (cycle detection, depth cap, containment), secret-origin flagging plumbing (templating.md, resolvers.md §1–§4). Reference page docs/user-guide/templating.md. ✅
8 #11 feat/variants-binding Variant locations in binding (V, []V, map[string]V), selector derivation, process-wide registry, flexconf re-exports (Registry[V] alias, RegisterVariant, Resolve, Get, Select, WithDiscriminator, WithRegistry) (variants.md). Reference page docs/user-guide/variants.md. ✅
9 #12 feat/vault-registry Vault registry: env-derived layer list (FLEXCONF_VAULTS / well-known file), static-loader front-end, whole-entry replacement, default: vault, ~/relative path normalization, VaultID derivation (vault-registry.md). Reference page docs/user-guide/vaults.md. ✅
10 #13 feat/agent-runtime internal/agent: socket protocol (length-prefixed JSON), server loop with idle auto-lock, client Dial, self-exec spawn + RunAgentIfRequested, lock/PID/err files, peer-UID check, agent-proxy VaultDriver (cli.md §6, resolvers.md §5.2, §5.5). ✅
11 #14 feat/secret-resolver secret: resolver: [vault:]namespace/key parsing, registry lookup, PolicyAgent (via agent proxy) and PolicyInProcess, WithSecretPolicy, flexconf.RunAgentIfRequested re-export, secret-origin redaction in errors (resolvers.md §5, errors.md). Reference page docs/user-guide/secrets.md. ✅
12 #15 feat/flexcli flexcli Cobra secret group (init/unlock/lock/get/set/list/vaults, --vault root flag, auto-unlock, exit codes) + cmd/flexconf standalone binary (cli.md). Reference page docs/user-guide/cli.md. ✅
13 #16 docs/reference-polish Docs polish: reference index page, nav registration for all reference pages, README quick-start refresh. ✅

Sequencing notes

  • Dependency direction matches overview.md §6: flexprompt → flexvault → (internal/variant, flexconf) → internal/agent → flexcli → cmd/flexconf.
  • PR 6 lands the Loader with an effectively empty resolver set; PR 7 turns on the default resolvers minus secret:, which arrives in PR 11 once the registry (PR 9) and agent (PR 10) exist.
  • External dependencies are introduced where first needed: golang.org/x/term (PR 2), gopkg.in/yaml.v3 (PR 6), github.com/tobischo/gokeepasslib (PR 4), github.com/spf13/cobra (PR 12).