Add Rust-first Spec API

[domenkozar]

What changed

• Add a public, Rust-first Spec API with builders for profiles, secrets, typed generation, and password character sets.
• Route TOML loading, runtime secret loading, derive-time code generation, CLI code generation, and shell-completion metadata through the same validated semantic CompiledSpec model.
• Expose Secrets::from_spec while keeping Config as an internal TOML wire format.
• Add a runnable Rust-first example, SDK documentation marked for 0.20+, tests, and an Unreleased changelog entry.

Why

Rust callers should be able to describe secrets directly without constructing a TOML-shaped configuration type or serializing and reparsing TOML. Making every frontend lower through Spec gives Rust-first and file-backed projects identical validation, inheritance, generation, and provider behavior.

Developer impact

New integrations can build a Spec and pass it directly to Secrets::from_spec. Existing TOML projects continue to use the same syntax, but parsing now crosses the public Spec abstraction. The old crate-root Config export is removed because it represented the storage format rather than the supported semantic API.

Validation

• devenv shell cargo check --workspace --all-targets
• commit hooks: Clippy and Rustfmt
• devenv shell cargo test -p secretspec spec:: (6 passed)
• devenv shell cargo test -p secretspec cli::completion::tests (12 passed)
• devenv shell cargo test -p secretspec --lib (1,223 passed, 4 ignored)
• devenv shell cargo test -p secretspec-derive --test compile_tests
• devenv shell npm --prefix docs run build

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	secretspec	6e6ab4c	Commit Preview URL Branch Preview URL	Aug 15 2026, 05:21 PM

[djbclark]

Heads-up: this now fails to compile against current main, as of #355 merging (faa9645). GitHub still reports the PR as mergeable, and it is — the merge is textually clean. The breakage is semantic.

#355 added a test that calls the old signature:

// secretspec/src/codegen.rs, on main
let ir = build_ir(&config_with(vec![( /* ... */ )]));

This PR re-signatures pub fn build_ir to take &Spec, and migrates the existing tests to the new build_ir_from_config helper in the test module. That new test didn't exist when this branch was written, so it wasn't migrated — and because it lands in a region the branch never touched, the merge succeeds and only the compile fails.

Reproduced locally by merging pull/334/head into main (e9004eb):

$ cargo check -p secretspec --tests
error[E0308]: mismatched types
   --> secretspec/src/codegen.rs:573:27
    |
573 |           let ir = build_ir(&config_with(vec![(
    |                    --------  ^ expected `&Spec`, found `&Config`

Exactly one error; nothing else in the crate breaks.

The fix is the same migration applied to the other tests — at codegen.rs:573:

-        let ir = build_ir(&config_with(vec![(
+        let ir = build_ir_from_config(&config_with(vec![(

I verified that compiles and that cargo test -p secretspec --lib codegen:: passes (11 passed, including schema_emits_description_when_declared).

Posting rather than opening a PR since it's a one-liner on your branch, but happy to send it if that's easier.