@modootoday/envs 0.1.0

package/.agent/skills/env-value-store/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: env-value-store
+description: Use when environment values are spread across several .env files, layers or machines and something reads the wrong one — a key defined twice with different values, a config file loaded as if it were env, a value that works locally and is missing in CI, or a secret that needs rotating in more than one place. Covers @modootoday/envs, which keeps the values in an encrypted catalog and answers where each one came from.
+---
+
+# Using `@modootoday/envs`
+
+## When to reach for it
+
+Use the catalog when multiple env files or machines make provenance, conflicts,
+rotation and rollback hard to track. For one file in one project, dotenv is
+usually sufficient. The parser, catalog, keyring, loader and command dispatch
+exist; that does not establish that this package has been published to a registry.
+
+## Install and wire
+
+The package is not published yet. Build it in its owning repository and install
+an approved local directory or tarball; do not assume a registry version exists.
+
+```sh
+npm install /path/to/approved/envs-package
+```
+
+Two entries. `import { config } from "@modootoday/envs"` calls it explicitly,
+and `import "@modootoday/envs/config"` loads on import the way `dotenv/config`
+does; both resolve under `require` as well, so `node -r @modootoday/envs/config`
+works. The CLI executable is `envs`.
+
+## What the consuming repository must supply
+
+Supply the project directory, env inputs, a supported SQLite runtime and an
+unlock method. Keep the catalog gitignored and recovery codes outside it. For
+CI, disable the personal global layer and declare required key names rather
+than copying personal secrets. Backup destinations and server credentials are
+explicit configuration, not values this package discovers by guessing.
+
+## API
+
+### Public module and command boundary
+
+The root exports parsing (`parseEnv`, `toRecord`), catalog and keyring operations,
+`config`, and command dispatch. `parseEnv` returns `{ ok, entries, findings }`;
+`toRecord` returns a record only for a valid parse and `null` otherwise. CLI help
+comes from command definitions, so consult it rather than guessing option names.
+
+### build is the dangerous one
+
+It bakes values into a module for targets that cannot read a file. Default is **nothing
+selected**, and a key not classified `low` is refused even when named — unclassified
+reads as `medium`, so saying nothing gives the safe answer. `--allow-sensitive` exists
+and should be argued for, not reached for: a deployed bundle cannot be recalled.
+
+### serve hands over bytes, not values
+
+It serves the sealed catalog. It holds no key and cannot decrypt, so a compromised server
+gives up what a stolen catalog file would and no more. Requiring a token of real length
+is the whole security of the endpoint, so it is required rather than generated quietly,
+and binding to anything but localhost warns that the token crosses the wire.
+
+`--once` stops after the catalog is **handed over**, not after any request: an
+unauthorised probe must not end a one-shot pull before the client with the token arrives.
+
+### Backups follow the same provider rule as the sqlite backends
+
+Differences are data, eligibility is declared rather than discovered by failing, and a
+pin exercises the non-default path. `s3` covers S3, R2, MinIO and Backblaze — what
+differs between them is a hostname — and `file` writes to a directory. Neither is
+eligible unless configured: a destination nobody set is a missing setting, not a failed
+write.
+
+A snapshot seals the catalog under its data key and carries that key's **wraps in the
+header**. Without them a backup could only be opened by the catalog it came from, which
+is the thing that may be gone — so **a recovery code alone restores**, which is the whole
+point. The wraps are already sealed blobs, so the header leaks nothing.
+
+SigV4 is implemented here rather than depended on, and verified against the derivation
+vector AWS publishes. **No live endpoint was exercised**; say so rather than implying the
+S3 path has been run against a real bucket.
+
+- **Restore must delete the `-wal` and `-shm` beside the catalog.** Replacing only the
+  main file leaves the old journal, and sqlite replays it onto the restored database —
+  the values the snapshot was taken to undo come straight back. Measured on bun, where
+  the write had not been checkpointed; node passed by luck. It pairs with the
+  `wal_checkpoint(TRUNCATE)` backup takes before reading the file.
+
+### The surface deliberately matches dotenvx
+
+dotenvx, Doppler and Infisical have converged on the same shape, so this package uses it
+rather than inventing names: `run -- <cmd>` to inject, `get`/`set`/`del` for values,
+`ls` to list, `export --format` to take them out, plus `rotate`, `genexample`,
+`gitignore` and `precommit`. `set` accepts both `KEY VALUE` and `KEY=VALUE` because the
+three tools disagree about which one is canonical — but refuses them mixed, since
+`set A=1 B=2` could be read either way.
+
+Three deliberate differences, worth stating when a user expects dotenvx exactly:
+
+- **No `encrypt`/`decrypt`.** dotenvx encrypts a file in place; this keeps a store, and
+  the round trip is `load` then `export`.
+- **`get` with no key does not print everything.** dotenvx does, but that would make the
+  `export --yes` gate meaningless. Names come from `ls --keys`, values from `export`.
+- **No `native`, `armor` or `lock`** — those are that service's own features.
+
+`rotate` is cheap here because of the key hierarchy: it re-wraps the data key and
+re-encrypts nothing. New wraps are written **before** the old ones are retired, so an
+interruption leaves too many ways in rather than none.
+
+### The shape of a change
+
+Releases are immutable. `load` and `set` both write a **new** release carrying every
+value with the change applied, and move the pointer; `rollback` moves the pointer back.
+Nothing is deleted, which is what makes going back cheap and reversible. Two consequences
+worth telling a user: `load` carries other sources forward unless `--replace`, so loading
+one file does not empty the rest; and `set` refuses to guess which source owns a key when
+there is more than one.
+
+`doctor` answers where a value came from. Same key with the same value in two sources
+warns, different values error, and neither prints a value. It also names the catalogs it
+actually read — running in the wrong directory is the one trap this layout has.
+
+### Losing a key does not lose the catalog
+
+Values are sealed under a random DEK, and the DEK is wrapped once per way back: the KEK,
+and each recovery code. Any one wrap opens it, so a lost KEK costs nothing while a
+recovery code survives, and a new way back can be added without re-encrypting a value.
+
+**Recovery codes are printed once at `init` and never stored** — the table holds only the
+wrapped DEK, so it cannot give a code back. Codes are Crockford base32 (no I, L, O or U)
+and are accepted in any case with any separators, because refusing a transcription slip
+the alphabet was designed to absorb would mean a lost catalog.
+
+To open a catalog with one:
+
+```
+printf '%s' "$CODE" | npx @modootoday/envs export --yes --recovery-code -
+```
+
+`export` is the only command that prints values, so it refuses without `--yes`, prefers
+stdin over argv for the code, and warns when a code is passed inline where other
+processes can see it. Its CSV quotes every field — env values really do contain commas,
+quotes and newlines — and a value starting with `=`, `+`, `-` or `@` is **reported, not
+rewritten**: altering it would hand back something the catalog does not hold.
+
+## Worked examples
+
+### Parse without changing the environment
+
+```ts
+import { parseEnv, toRecord } from "@modootoday/envs";
+
+const parsed = parseEnv("MODE=test\n");
+if (!parsed.ok) throw new Error("Invalid env document");
+const values = toRecord(parsed);
+// values is local data; no process environment or catalog has been modified.
+```
+
+### Refuse an input that is not env format
+
+```ts
+import { parseEnv, toRecord } from "@modootoday/envs";
+
+const parsed = parseEnv("name: service\n");
+if (parsed.ok || toRecord(parsed) !== null) throw new Error("Expected refusal");
+// Report parsed.findings (codes and line numbers), never candidate values.
+```
+
+## Testing against it
+
+### Runtime and database fixtures
+
+The suite must pass under **both** runtimes, and running only one hides real defects.
+`npx vitest run` uses node; `bunx --bun vitest run` uses bun.
+
+Three sqlite backends sit behind one interface, and everything they disagree about is
+data in `src/sqlite/provider.ts`. Do not reintroduce these differences in calling code:
+
+- **Booleans.** node and better-sqlite3 throw on a bound boolean, bun accepts it. Bind
+  through the adapter, which normalises to 0/1.
+- **A missing row.** bun returns `null` from `get()` and node returns `undefined`, so a
+  `!== undefined` check passes on one and dereferences null on the other. The adapter
+  returns `undefined` on both; do not compare against `null` in calling code.
+- **Named parameters.** bun needs the sigil form (`$a`), better-sqlite3 needs the bare
+  name (`a`), node takes either. Getting it wrong is **not always an error**: bun binds
+  NULL and says nothing, so the adapter matches keys against the statement's own
+  placeholders.
+- **Constructor options.** bun rejects `{}` and `{readonly:false}` and wants
+  `create: true`; node spells it `readOnly` and **silently ignores** the lowercase
+  spelling, handing back a writable database; better-sqlite3 wants the lowercase name.
+  Assert that a write is actually refused, never that a flag was passed.
+- **Eligibility is checked, not attempted.** Loading better-sqlite3 under bun 1.3.14
+  panics the process with `NAPI FATAL ERROR` — no try/catch contains it. A provider
+  declares where it may run.
+- **Import through a variable specifier.** A literal makes TypeScript try to resolve
+  `bun:sqlite` and makes bundlers treat the absent module as a hard failure.
+
+`config()` is synchronous. Its entry point resolves the binding through
+`createRequire` and uses `node:crypto` rather than Web Crypto. Adding an `await`
+changes the public contract. The supported call is the named root export;
+there is no exported `/config` side-effect subpath.
+
+Commands are values in `src/commands/`: name, description, option specs, `run`. Help is
+generated from the spec, so a flag cannot exist in the parser and not the help, and an
+option the command did not declare is an **error** rather than a silently ignored typo.
+Output goes through `src/cli/ui.ts` — values to stdout so they can be piped, everything
+else to stderr, colour only on a TTY without `NO_COLOR`. No dependency for either.
+
+- **Never write a control byte into a source file.** Build it from `String.fromCharCode`
+  and reference the constant. This has gone wrong twice here: a NUL in a test fixture and
+  raw escape bytes in the colour table.
+- better-sqlite3 is an **optional peer**: not installed by this package, so its rows in
+  the backend matrix only run where someone installed it. `ENVS_SQLITE_BACKEND` pins one
+  backend when you need to exercise a specific path.
+
+### Values are never syntax
+
+Env values are arbitrary text from files this package does not control, so no statement
+is ever built from data — no interpolation, no concatenation, parameters only. A guard
+test scans every source file for both patterns and proves the detector fires on a
+fixture. Two consequences worth keeping in mind:
+
+- Key names reach the database as HMACs and values as sealed blobs, so even the
+  identifier surface carries no caller text.
+- A string containing a NUL is **refused**. Measured: sqlite TEXT ends at the first NUL,
+  so `a\0b` is stored and read back as `a`, losing the rest without an error.
+
+Do not tell a user a command works until it appears in the list above.
+
+## Invariants
+
+### Catalog ownership
+
+`dotenv` reads a file and puts it in `process.env`. That is enough until there is more
+than one file. Then nobody can answer which file supplied a value, a key defined in two
+places silently resolves to one of them, and rotating a credential means finding every
+copy.
+
+This package keeps the values in a catalog — a small encrypted SQLite database — and
+treats files as inputs to it. Because there is a store rather than a file, it can answer
+where a value came from, hold releases and a pointer so a rollback moves the pointer, and
+carry an audit trail.
+
+Reach for it when:
+
+- The same key exists in more than one file and you need to know which one wins.
+- A value works on one machine and is missing on another.
+- A credential must be rotated and you do not know how many copies exist.
+- A `.env` path actually points at YAML or JSON and is being read as env anyway.
+
+Do not reach for it to hold one `.env` in one project. `dotenv` is the right size there.
+
+### The format rule, and why it is strict
+
+An env document is a sequence of logical entries, each one of exactly three kinds:
+
+1. a line starting with `#`
+2. a blank line
+3. `KEY=VALUE`
+
+Entries are logical, not physical: a quoted value may span several lines. Anything that
+is not one of the three means the file is not env format, and then **none** of it loads.
+
+This matters because `dotenv` is lenient in ways that produce plausible wrong answers.
+Measured against dotenv 17.4.2:
+
+| Input                                      | dotenv                                | this package        |
+| ------------------------------------------ | ------------------------------------- | ------------------- |
+| `name: envs` over two lines (YAML)         | parses into keys                      | rejected            |
+| `KEY: value`                               | `{KEY: "value"}`                      | rejected            |
+| `A="oops` unterminated, rest of file valid | `A` becomes `"oops`, rest still loads | whole file rejected |
+| `{"a": 1}` (JSON)                          | `{}`, no error                        | rejected            |
+
+Pointing a loader at the wrong file should fail, not return something that looks like
+configuration.
+
+### Value syntax
+
+- `VALUE` may be bare, or wrapped in `"`, `'`, or a backtick.
+- Inside quotes, `#` and `=` are literal. A bare value ends at the first `#`.
+- Whitespace is trimmed only from bare values.
+- **Double quotes expand `\n` and `\r` and nothing else.** `\t`, `\\` and `\"` stay
+  literal, which is what keeps `"C:\path\to"` intact. Never parse a value with
+  `JSON.parse` — it throws on Windows paths and expands escapes dotenv does not.
+- Keys are not required to be uppercase. `api_key=secret` is env format. Casing is a
+  convention, so `lint` mentions it and the parser does not enforce it.
+
+### Where things live
+
+|                           | Path                                                                                       | Note                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Catalog (source of truth) | `<project>/.envs/catalog.sqlite`                                                           | `~/.envs/` only when there is no project root; `ENVS_CATALOG_PATH` overrides |
+| Cache (derived)           | `node_modules/.cache/envs/` when installed, `~/.envs/cache/` under npx or a global install | Safe to delete; rebuilt from the catalog                                     |
+| Requirements              | `envs.requires` at the project root                                                        | Committed. Names only, never values                                          |
+
+Two rules follow from this and are worth stating to a user before they are surprised:
+
+- **The catalog stays with the project even under a global install.** Installing the CLI
+  with `-g` while the runtime is a devDependency is the ordinary setup; a home-directory
+  catalog would mean a value set inside a project is invisible to that project.
+- **`.envs/` must be gitignored.** It holds envelopes, history and audit rows. `doctor`
+  reports an error, not a warning, if it is ever tracked.
+
+### The global layer
+
+`~/.envs` is a settings layer, not a second store. It holds what belongs to a person and
+a machine — a personal API key, `ENVS_PROVIDER`, backup targets — and the loader resolves:
+
+```
+process.env  >  project catalog and files  >  ~/.envs
+```
+
+The project always wins; the global layer only fills keys the project does not define.
+It is switched off with `config({ global: false })` or `ENVS_NO_GLOBAL=1`, and CI should
+switch it off, because a build that passes locally on a home-directory value and fails in
+CI is the standard failure of this pattern.
+
+### Diagnosing, and repairing a split
+
+`doctor` answers where each value came from and never prints a value.
+
+When it reports keys that exist only in the global layer, there are two repairs and they
+move different things:
+
+- `doctor --require <KEY>` records that the key is needed, in `envs.requires`. It carries
+  no value, so it can be committed, which is what lets it reach a teammate or CI at all.
+  `config()` then throws when a required key resolves nowhere, instead of the application
+  receiving `undefined`.
+- `doctor --adopt <KEY>` moves the value into the project. Correct only when the value was
+  project scoped and had been left global by mistake.
+
+Prefer `--require`. Copying a value into `<project>/.envs/` makes the project
+self-contained on one machine only — that directory is gitignored, so a teammate and CI
+are exactly where they were. `--adopt --all` is refused by default: personal credentials
+are what the global layer exists to hold once, and copying them per project turns one
+rotation into many edits.
+
+## What it will not do
+
+It does not provision credentials, make a registry release available, or prove
+that an S3 destination has been exercised live. Sealed data still needs an
+external recovery path. Report the tested runtime and backend rather than
+claiming every deployment has been validated.
+
+### Reporting rules
+
+When surfacing anything from this tool to a user:
+
+- **Never print a value.** Report the key, the file, the line, and whether two values are
+  the same or different. The existing lint rule `duplicate-key-across-layers` sets the
+  convention: same value warns, different value errors, neither prints.
+- Say which catalog was actually used. Running in a directory with no project root writes
+  to `~/.envs`, and a user who does not notice will look for the value in the wrong place.

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/NOTICE

@@ -0,0 +1,24 @@
+@modootoday/envs
+
+Copyright (c) 2026 modootoday. All rights reserved.
+
+Licensor: modootoday
+Licensed under the Elastic License 2.0; see LICENSE.
+
+The licensor is modootoday, the company, not any individual contributor.
+This file names the licensor because the Elastic License 2.0 defines that term
+rather than carrying a copyright line of its own; LICENSE is kept unmodified.
+
+What the licence permits, in short, without replacing the terms in LICENSE:
+
+  - Using this software inside your own company, on any scale.
+  - Embedding it in a product you sell, and modifying or forking it.
+  - Redistributing it, with these notices intact.
+
+What it does not permit:
+
+  - Offering this software to third parties as a hosted or managed service.
+  - Circumventing licence key functionality.
+  - Removing or obscuring these notices.
+
+LICENSE governs. Where this summary and LICENSE differ, LICENSE is what applies.

package/README.md

@@ -0,0 +1,97 @@
+# @modootoday/envs
+
+Environment values in an encrypted catalog rather than scattered `.env` files.
+
+**[envs.build](https://envs.build)** has the documentation. This page is the introduction.
+
+```console
+$ npx @modootoday/envs init
++ catalog created
++ added to .gitignore
+
+Recovery codes — 5, shown once, not stored
+  1575H-MPBMP-K41AR-PXAVB-NN920-G
+  G8T2M-4KQZR-7VXWD-3NBHE-J05YA-P
+  …
+
+$ envs load .env
++ .env 12 keys
++ release 8f21ac04 is current
+
+$ envs run -- node server.js
+```
+
+## What it does that a file cannot
+
+`dotenv` reads a file into `process.env`, which is all most projects need. This is for
+the ones with four files, three machines, and a credential that gets rotated.
+
+- **Tells you which file set a key.** When `.env` and `.env.local` both declare
+  `DATABASE_URL`, `envs doctor` names the one that won. It prints the key and the
+  source, never the value.
+- **Survives a lost key.** `init` prints five recovery codes once. Any one of them opens
+  the catalog on its own, and none of them is ever stored.
+- **Refuses a file that is not env format.** `dotenv` reads a two-line YAML document as
+  environment variables. This checks first, and if the file fails, nothing loads.
+- **Rolls back without deleting anything.** Changing a value writes a new release. Going
+  back moves a pointer.
+
+## Migrating from dotenv
+
+`config()` takes the same options — `path`, `encoding`, `override`, `processEnv` — and it
+is synchronous, so the side-effect import still works.
+
+```diff
+- import "dotenv/config";
++ import "@modootoday/envs/config";
+```
+
+Both module systems resolve, so the preload form works without touching your code:
+
+```console
+$ node -r @modootoday/envs/config server.js
+```
+
+One difference worth knowing before you switch: `dotenv` returns quietly when there is no
+file, while this throws when there is no catalog. A missing store is the failure this
+exists to make visible, so it is loud rather than empty.
+
+The command names follow dotenvx: `run -- cmd`, `get`, `set`, `ls`, `rotate`. If you have
+used it, most of this is already familiar.
+
+## Documentation
+
+| | |
+| --- | --- |
+| Getting started | <https://envs.build/guide/> |
+| The format rule, measured against dotenv | <https://envs.build/format/> |
+| Recovery codes | <https://envs.build/recovery/> |
+| How it compares to dotenv, dotenvx, Doppler and Infisical | <https://envs.build/compare/> |
+| Sharing a catalog, and what the server cannot see | <https://envs.build/hosted/> |
+| All 28 commands | <https://envs.build/commands/> |
+
+## Requirements
+
+Node.js 22 or Bun 1.3. Nothing to sign up for, and no network call unless you ask for one.
+
+## Before you commit to it
+
+- **The licence is not OSI open source.** See below.
+- **It starts slower than dotenv** — about 6.6 ms for a hundred keys against 0.2 ms.
+- **One `.env` and one developer does not need this.** dotenv already does that job, with
+  no key to manage and nothing to back up.
+
+## Licence
+
+Elastic License 2.0. Licensor: **modootoday**. See [`LICENSE`](LICENSE) and
+[`NOTICE`](NOTICE), and <https://envs.build/licence/>.
+
+Use it inside your company at any scale, ship it in a product you sell, fork it. What you
+cannot do is offer this software to third parties as a hosted or managed service. It
+carries a patent grant with a retaliation clause: asserting patent claims over this
+software ends your licence.
+
+---
+
+Repository <https://github.com/modootoday/envs> · npm
+[`@modootoday/envs`](https://www.npmjs.com/package/@modootoday/envs)