@ciqol/resenv 0.1.0 → 0.1.1

package/README.md

@@ -23,6 +23,10 @@ resenv, and dotenv files are never rewritten.
 Requires Node.js 20 or later. The package is experimental and remains in initial
 development; its API may change between 0.x releases.
 
+Each npm package includes this README for the version you installed. The
+[repository README](https://github.com/ciqol/resenv#readme) and linked online
+guides follow current development and may describe newer versions.
+
 Background: [A new Git worktree shouldn't mean another copy of your secrets](https://dev.to/titanron/a-new-git-worktree-shouldnt-mean-another-copy-of-your-secrets-424).
 
 ## Install
@@ -68,7 +72,7 @@ access stop startup without opening a browser or prompting for login.
 
 For CI and other unattended environments, supply `DOPPLER_TOKEN` through your
 runner's secret facility; the CLI is not needed in that mode. See
-[Doppler authentication and platform details](docs/doppler.md), including
+[Doppler authentication and platform details](https://github.com/ciqol/resenv/blob/main/docs/doppler.md), including
 migration from the earlier resenv-managed login.
 
 Need another secrets provider, operating system or CLI installation method?
@@ -159,8 +163,8 @@ its environment is loaded; values embedded in build output remain in that output
 - Application code can read its resolved environment. Access to the same
   credentials also permits other code or sessions to retrieve those secrets.
 
-See [Doppler limits](docs/doppler.md#resolution-and-security-boundaries) and
-[security guidance](SECURITY.md).
+See the current [Doppler limits](https://github.com/ciqol/resenv/blob/main/docs/doppler.md#resolution-and-security-boundaries)
+and [security guidance](https://github.com/ciqol/resenv/blob/main/SECURITY.md).
 
 ## Library API
 
@@ -252,7 +256,7 @@ with `{ commands: true }`.
 ## Contributing
 
 For checkout setup, building, testing, trying local changes in another project
-and submitting fixes, see [CONTRIBUTING.md](CONTRIBUTING.md).
+and submitting fixes, see [CONTRIBUTING.md](https://github.com/ciqol/resenv/blob/main/CONTRIBUTING.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciqol/resenv",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Replace environment references with their resolved values at application startup",
   "license": "MIT",
   "publishConfig": {
@@ -71,7 +71,6 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {},
   "files": [
     "*.cjs",
     "*.mjs",
@@ -79,11 +78,6 @@
     "*.d.mts",
     "doppler",
     "bin",
-    "types",
-    "README.md",
-    "LICENSE",
-    "CONTRIBUTING.md",
-    "SECURITY.md",
-    "docs"
+    "types"
   ]
 }

package/CONTRIBUTING.md

@@ -1,211 +0,0 @@
-# Contributing
-
-Starting a new session? Read the [maintainer handoff](docs/maintainer-handoff.md)
-and [repository instructions](https://github.com/ciqol/resenv/blob/main/AGENTS.md) before editing or releasing.
-
-The [README](README.md) covers using resenv in an application. This guide covers
-changing resenv itself and verifying those changes.
-
-Merge to protected `main` approves release. CI uses standard semantic-release
-and the official npm/GitHub plugins to publish regular `0.x.x` versions to
-`latest`. The root and local builds stay private; only the protected release
-job makes the tested build publishable. See [releasing](docs/releasing.md)
-and [release security](docs/release-security.md).
-The source uses the [MIT license](LICENSE), copyright ciqol contributors.
-
-## Local development
-
-Use the Node version in `.nvmrc` and npm:
-
-```sh
-nvm use
-npm ci
-npm run verify
-```
-
-The committed `.npmrc` omits automatically installed peer dependencies. The
-release planner calls the two official plugins directly, so their full engine
-peer and its publisher dependencies are intentionally not installed. Audit and
-planning enforce that absence. `npm ls` still reports the declared missing
-engine peers; standalone plugin behavior is covered directly by the release
-specs. Keep this install policy when refreshing the lockfile; do not use force
-or legacy peer resolution. See [the dependency review](docs/dependencies.md).
-
-`npm run verify` is the complete local check: lint, strict source/spec type
-checks, build, unit/process tests and installed-package checks. To build without
-running the checks, use `npm run build`.
-
-After building, try the CLI from this checkout:
-
-```sh
-node dist/bin/resenv.cjs --help
-```
-
-Author library and CLI code as `.ts`; Rollup's TypeScript plugin produces both
-module formats and declarations from that implementation. Colocate Vitest unit
-specs as `*.spec.ts` beside each tested module and import its source. Build and
-release scripts have colocated `*.spec.mjs` Vitest specs. Keep
-process, package and integration checks in `test/` as `.mjs`; they exercise
-compiled output and installed packages. Tests use dummy credentials and commands.
-Never use real secrets in fixtures, terminal output, screenshots, issues, or
-pull requests.
-
-Provider detection belongs to the original environment values, including library
-calls without options. Keep shell execution behind `commands: true`, preserve
-literal fetched output, and validate references before any command runs.
-
-ESLint applies rules that use type information to the TypeScript implementation and specs
-and checks the JavaScript build tooling.
-Use `npm run lint:fix` for available automatic fixes; preserve the repository's
-existing compact formatting. Public object shapes use `type` with `readonly`
-properties. `Environment` is intentionally mutable because in-place resolution
-updates it. `npm run typecheck` checks the entire library and CLI with `strict`
-and `noUncheckedIndexedAccess`. A separate spec configuration checks tests without
-shipping them in JavaScript or declarations. Do not maintain separate handwritten declarations.
-
-```sh
-npm run test:unit         # colocated Vitest specs, no build required
-npm run test:watch        # watch unit specs while editing
-npm run test:coverage     # source unit coverage, text, lcov and Cobertura output
-npm run test:integration  # process checks, requires a build
-```
-
-`npm test` runs unit and process tests. Mock or inject provider calls, credential
-lookup and process control in unit tests. Keep checks that spawn actual commands
-or temporary applications in `test/`. The unit coverage
-report measures source and is separate from packed-package and process checks.
-`npm run verify` enforces a 90% global floor for source statements, branches,
-functions and lines. Worker and preload entry files stay in the denominator;
-the CLI is checked separately by process and packed-package tests. CI retains
-LCOV and Cobertura reports for seven days in the `resenv-coverage` artifact.
-The official `actions/upload-code-coverage` action uploads Cobertura in a separate
-job for same-repository PRs and `main` runs; other runs retain the local gate and
-report artifacts. The main `ci` job groups audits, lint, types, coverage, build
-and packed-package/process checks on the pinned Node version. CLI lookup checks
-use injected helpers and temporary
-dummy executables; they never access a developer credential store or
-authenticated provider session.
-The `smoke` matrix checks that same archive on Linux Node 20 and 22 and macOS
-with the pinned Node version; it does not build or rerun source unit specs.
-
-Use normal npm lifecycle behavior locally and in CI. Review install hooks,
-including implicit native builds, when changing dependencies; record any
-required setup in [the dependency review](docs/dependencies.md). Suppressing
-lifecycle hooks can skip required setup, so it is not part of the standard
-installation commands. The explicit build/check commands remain required.
-
-The package check packs `dist/` and installs that tarball into a temporary
-consumer outside the repository. The install is offline, uses npm's existing
-cache and the repository's reviewed runtime lock entries. It installs with
-`npm ci` without needing cached registry metadata. It does not link the source
-tree or publish. Run `npm ci` first to populate the archive cache. The check
-exercises both module formats, CLI and preloads, shared error identity, single
-preload execution and `.cts`/`.mts` consumer types.
-
-Pass an existing archive to test the same build CI uses:
-`npm run test:package -- /absolute/path/to/package.tgz`. For a final CI candidate,
-also pass its `release.json` as the second argument. The supplied package's
-name, version, executable mode and manifest are checked before runtime probes.
-The README inside the archive must match the checkout, install from npm's
-`latest` channel and avoid unpublished or local-archive installation guidance.
-`npm run verify` runs lint, typecheck, build and tests; `npm run release:check`
-also previews the package contents. Neither publishes or creates a tag.
-
-Rebuild after source, declarations, metadata or documentation changes. The build
-cleans `dist/` first and generates its manifest from the root package. See
-[docs/build.md](docs/build.md). Ordinary local builds remain private. Only a validated CI release plan removes
-that guard from the distribution manifest; never edit it by hand.
-
-## Try changes in an application
-
-### Install a local archive
-
-From the resenv checkout:
-
-```sh
-npm run build
-npm run pack:local
-```
-
-Install the resulting archive from the application's directory:
-
-```sh
-npm install --save-exact /absolute/path/to/ciqol-resenv-0.1.0.tgz
-```
-
-This changes the application's manifest and lockfile. The archive must exist
-wherever it installs dependencies. Use a new archive version for changes to an
-already shared build; never overwrite an archive another project uses. Root
-package overrides do not propagate to consumers; inspect the installed tree
-against [the dependency review](docs/dependencies.md).
-
-### Try local changes without changing the application's CI
-
-Link this checkout's built `dist/` directory at the application's ignored
-`node_modules/@ciqol/resenv`, retaining any existing installation first. Keep
-references in an ignored `.env.serve.local` and the application's target edit
-local. Leave its manifest, lockfile and CI configuration unchanged.
-
-Rebuild resenv after source, metadata or documentation changes and restart the
-application. An application `npm ci` can remove the link; recreate it when needed.
-Authenticate with the official Doppler CLI from the application's directory:
-
-```sh
-doppler login
-```
-
-resenv reuses that login at runtime. Automated tests use injected or mocked
-credentials; real login is a manual integration check owned by Doppler's CLI.
-
-## Optional integration checks
-
-`npm run bench` measures fresh-process startup, a plain 200-variable environment,
-and a mocked provider with eight distinct lookups. It needs a build first and
-does not contact a provider. Timings are observations, not CI pass/fail thresholds.
-
-With an existing Nx installation:
-
-```sh
-npm run test:nx -- /absolute/path/to/workspace/node_modules
-```
-
-This creates a temporary Nx workspace and checks target-file loading,
-precedence and secret resolution with dummy values. It does not use the
-source workspace's dotenv files, credentials or remote cache.
-
-## Changes
-
-Keep dotenv file discovery with the caller. Doppler is the only built-in cloud
-provider; its authentication and lookups live under `src/doppler/`.
-Preserve all-or-nothing environment updates, strict failures, explicit command
-opt-in and literal handling of resolved values. Update the public API types and
-documentation together with behavior changes.
-
-Keep one public resolver, `resolve()`. It always returns an independent
-resolved copy and replaces input values only with `{ replace: true }`. Preloads
-enable that option; the CLI passes the returned copy to its child process.
-
-Add regression tests for changed behavior and avoid real provider calls. Use
-Conventional Commit subjects, for example `fix(resolver): preserve empty values`.
-Review dependency changes under the [dependency policy](docs/dependencies.md)
-and put the evidence in the PR. Update the guide when a lasting choice changes.
-
-CODEOWNERS identifies the maintainer. Keep bug reports and pull requests focused
-on observable behavior and include the checks run. Weekly dependency updates are
-grouped, with major version updates reviewed separately; bots cannot merge them.
-
-Keep the README focused on installation, authentication, application integration,
-API behavior and troubleshooting. Put contributor tooling, test commands and
-local development instructions here; detailed internals belong in `docs/`.
-Keep docs current rather than appending session logs, dated audit reports or
-test transcripts. Record run results in PRs and CI.
-
-Security reports follow [SECURITY.md](SECURITY.md). Publication and repository
-visibility changes require a separate maintainer decision; see the
-[release checklist](docs/releasing.md).
-
-npm releases run only through GitHub Actions with npm trusted publishing (OIDC).
-The maintainer configures the npm side. Local development and release checks
-do not require `npm login`; do not publish from a developer machine or add npm
-publishing tokens. CI must publish the exact candidate archive that its tests
-verified.

package/SECURITY.md

@@ -1,74 +0,0 @@
-# Security
-
-## Scope and trust
-
-resenv resolves values in a process environment. It does not provide a vault,
-access-control service, key rotation, or isolation between programs running
-with the same credentials. The application can read its resolved secrets and
-any credentials supplied to it.
-
-Doppler mode uses a fixed HTTPS API origin, disables redirects and fetches only
-referenced secret names. It does not execute shell expressions. Credentials
-come from an explicit `DOPPLER_TOKEN` or the current directory's existing
-Doppler CLI login. A fixed CLI helper captures that token privately; resenv
-does not parse Doppler's config files. An API rejection never triggers a switch
-to another identity. The official Doppler CLI owns browser authorization,
-token storage, login and logout. See [Doppler details](docs/doppler.md)
-for lookup rules, credential scope, migration and platform limits.
-The canonical `resolve` preload and `run` command select Doppler only for
-`doppler://` values. They do not infer shell execution from `$()` values.
-Startup does not initiate login. Use `doppler login` separately for local
-development or supply a suitably scoped token for unattended runs.
-
-Doppler's credential storage does not isolate credentials from other code
-running as the same user with access to them. resenv does not read or write the
-OS credential store directly or persist login tokens or fetched secrets.
-It does not automatically remove an explicitly supplied `DOPPLER_TOKEN` from
-the application environment. Tokens, captured CLI output and provider response
-bodies are not logged. The Node preload's private worker exchanges credentials
-and results over captured pipes, never process arguments or dotenv files.
-
-Command mode executes trusted configuration with the current user's
-permissions. Enable it only for configuration you have reviewed. Commands can
-access files and the network; failed resolution cannot undo their external
-effects. Commands are bounded by timeout and output limits, and their output
-is not included in resenv diagnostics.
-
-Node's `child_process` debug category prints spawn options, including stdin
-and environment values. resenv refuses its own subprocess and credential-helper
-operations when that category is enabled, including through `NODE_DEBUG=*`.
-Use `NODE_DEBUG=ciqol:resenv` for diagnostics that omit values. This guard does not
-control application logs, other instrumentation, or a debugger attached to the
-process.
-
-All values are resolved before resenv updates the caller's environment or
-starts the application. Provider failures, command failures and invalid
-environment values stop startup. Fetched values are never evaluated recursively. Application logs are outside resenv's control.
-
-Different automatic preload modes cannot be combined in one process. Otherwise
-the second mode could execute literal data fetched by the first.
-Combining a preload with the CLI is rejected for the same reason. Do not add
-another resolver to the child through `NODE_OPTIONS` or other launch hooks.
-Use one `resenv run --commands` invocation or one library call with commands
-enabled to resolve cloud references and commands together. Repeated manual
-library calls are separate operations; only pass original configuration to them.
-
-Provider responses must be valid UTF-8 and JSON, and resolved strings must not
-contain lone Unicode surrogates or null bytes. In-place replacement preflights
-all changed properties; read-only properties, setters and Proxy targets are
-rejected before any values are committed. Use `resolve()` to obtain a copy
-when the input is not a writable environment record.
-
-This experimental package has not had an independent security audit. See
-[verification](CONTRIBUTING.md) and [Doppler platform limits](docs/doppler.md).
-
-## Reporting a vulnerability
-
-Do not open a public issue containing a vulnerability, credentials or sensitive
-output. [Report a vulnerability privately](https://github.com/ciqol/resenv/security/advisories/new)
-through GitHub. If that option is unavailable, contact the maintainer through
-an existing private channel.
-
-Include affected versions, platform, impact and a minimal reproduction using
-dummy data. Never include production tokens, private keys or environment dumps.
-There is no guaranteed response time or long-term support policy yet.

package/docs/build.md

@@ -1,139 +0,0 @@
-# Build and package contract
-
-The repository is one Node.js package. The library and CLI are authored in
-strict TypeScript. Vitest unit specs use colocated `*.spec.ts` files. Process,
-package and integration checks and build orchestration use `.mjs`. Rollup's official
-TypeScript plugin compiles the implementation; consumers need no TypeScript
-loader or compiler.
-
-```sh
-npm ci
-npm run build
-npm test
-npm run test:package
-```
-
-## Output
-
-| Public entry | ESM | CommonJS | Declarations |
-| --- | --- | --- | --- |
-| `@ciqol/resenv` | `index.mjs` | `index.cjs` | `index.d.mts`, `index.d.cts` |
-| `@ciqol/resenv/resolve` | `resolve.mjs` | `resolve.cjs` | `resolve.d.mts`, `resolve.d.cts` |
-| `@ciqol/resenv/resolve-commands` | `resolve-commands.mjs` | `resolve-commands.cjs` | `resolve-commands.d.mts`, `resolve-commands.d.cts` |
-| `@ciqol/resenv/resolve-doppler` | `resolve-doppler.mjs` | `resolve-doppler.cjs` | `resolve-doppler.d.mts`, `resolve-doppler.d.cts` |
-
-These paths are relative to `dist/`. The executable points to
-`bin/resenv.cjs`; Rollup also emits its ESM wrapper. The command's user-facing
-name stays `resenv`.
-
-`resolve` reads the inherited environment and replaces Doppler references with
-their fetched values before application code starts. Doppler is the only
-built-in cloud provider. Original `encrypted:` values remain literal.
-`resolve-doppler` imports that same preload, so loading both names does not resolve fetched output again. Arbitrary commands require the
-separate `resolve-commands` entry or `run --commands`.
-
-The private `doppler-worker.cjs` entry lets synchronous preloads wait for HTTPS
-without turning the public CommonJS API into a promise. The worker is packed
-alongside the entries but is not a public export. It is located through package
-self-resolution, so the installed tarball does not depend on source paths.
-
-The root exports map defines the public entries. The build compiles their
-source with Rollup and its TypeScript plugin, then generates ESM facades from the exported
-names. Both formats load one CommonJS implementation. This preserves error
-class identity and shares the module cache when both preload forms are used.
-It follows Node's documented mitigation for the
-[dual-package hazard](https://nodejs.org/api/packages.html#dual-commonjs-es-module-packages).
-
-The CommonJS build preserves the module graph. Source unit specs import their
-adjacent modules; higher-level process and clean-consumer checks exercise the
-compiled modules and the same archive. Matrix jobs do not recompile TypeScript. Only the
-entries in the exports map are public package imports.
-
-The package has no runtime npm dependencies. Node built-ins remain external;
-Rollup does not bundle build tools into the application package. The build
-resolves `import.meta.url` to the Node filename in CJS output; browser-like
-globals in a Node test environment cannot change it.
-[Rollup's external option](https://rollupjs.org/configuration-options/#external)
-controls which imports remain outside the bundle.
-
-The compiler emits declarations into `dist/types/`. Generated `.d.mts` and
-`.d.cts` entry facades re-export that shared declaration graph; there is no
-handwritten public declaration file or separate declaration-bundler dependency.
-The generated package has no `type` field, so its shared `.d.ts` graph describes
-the CommonJS implementation. The exports map lists `types` first and selects
-the entry facade for the consumer's
-module format, as described by
-[TypeScript's ESM/CommonJS package guidance](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html).
-Consumer compilation checks both formats, including invalid inputs that must
-remain type errors.
-
-Public options use type aliases and readonly properties. `Environment` stays
-mutable for optional in-place replacement. `resolve()` always returns a new
-`Environment`, with input replacement enabled only by `{ replace: true }`. It
-does not preserve a generic input type: resolved strings cannot retain a
-literal reference type.
-ESLint uses type information and enforces the selected style rules. The compiler
-checks all library/CLI source, colocated unit specs and both consumer formats with `strict` and
-`noUncheckedIndexedAccess`. Provider responses and parsed worker input start as
-`unknown` and are validated before use. Compiler failures stop the build.
-
-The source target is ES2023. `ES2024.String` supplies the declaration for
-`isWellFormed()`, whose availability is also checked by the Node 20/22/24 runtime
-tests. Node types match the Node 24 development toolchain; the runtime matrix
-remains necessary to detect use of APIs absent from the oldest supported Node.
-
-## Generated manifest and packing
-
-The build removes stale output first. It derives `dist/package.json` from the
-root manifest, rebases entry paths, and omits development dependencies, scripts,
-overrides and a package-wide `type` field. Explicit `.mjs` and `.cjs` extensions
-select the output format. README, the MIT `LICENSE`, contributor/security guides
-and docs are copied into the distribution and included in the archive.
-
-Ordinary local and CI builds retain `private: true`. Only the protected release
-job makes the tested build publishable and lets the npm plugin set its version.
-The development root stays private. Release consumer checks validate the final
-versioned package before direct publication; see
-[releasing](releasing.md).
-
-`npm run pack:local` packs the generated directory. `npm run test:package`
-instead packs into a temporary directory and installs it offline into a clean
-consumer. It checks imports, requires, preloads, CLI behavior and declarations;
-the consumer cannot load resenv's source files or build dependencies. The
-runtime entries from the repository lockfile are used in the consumer lockfile.
-Its only direct dependency is the packed archive. An offline `npm ci` verifies
-archive integrity and installs the reviewed versions without registry metadata.
-
-With `npm run test:package -- /path/to/package.tgz`, the same checks inspect
-and install the supplied archive without rebuilding it. Its name, version,
-manifest and executable mode must match the package contract. CI uses this
-form so every platform checks the same built bytes.
-
-Keep tarballs already consumed by other projects immutable. No existing
-consumer artifact is rebuilt in place by these tests.
-
-## CI
-
-The `ci` job checks advisories and registry signatures, lint, types and source
-coverage, then builds and packs once. It tests the private archive and processes
-on the pinned Node version. The `smoke` matrix tests that archive on Linux Node
-20/22 and macOS with pinned Node 24; it never recompiles source. Coverage runs
-once, with a separate job uploading the report on same-repository PRs and main.
-Required archives and coverage reports are retained for seven days.
-
-After a merge to protected `main`, `release` downloads the tested build and runs
-semantic-release with the official npm/GitHub plugins. The npm plugin prepares
-version metadata and a tarball; the local verification hook checks the final
-package's consumer contract before publication. Source is never rebuilt in the
-release job. The official npm plugin publishes the prepared directory with no
-package lifecycle scripts. See [releasing](releasing.md) for the one-time 0.1.0
-bootstrap and failure handling.
-
-PRs and manual dispatches cannot publish. Release permissions are limited to
-GitHub contents write and OIDC. Package and registry secrets are absent from
-validation jobs. Every checkout disables persisted credentials, and the release
-token is scoped to the release step. Official GitHub actions use exact release
-tags; other remote actions require commit SHAs.
-
-The protected branch requires `ci`, `coverage`, all three `smoke` contexts and
-`Analyze (javascript-typescript)`. Keep these names stable when editing CI.

package/docs/dependencies.md

@@ -1,68 +0,0 @@
-# Dependencies
-
-resenv has no runtime npm dependencies. All tools are development-only and
-excluded from the consumer package. Exact direct versions and archive integrity
-live in package.json and package-lock.json. Use the pinned Node version and
-normal `npm ci`; review install hooks instead of disabling them globally.
-
-| Packages | Purpose | License |
-| --- | --- | --- |
-| `rollup`, `@rollup/plugin-typescript` | CommonJS, ESM facades and declarations | MIT |
-| `typescript` | Strict implementation and consumer checks | Apache-2.0 |
-| `tslib` | Build-time compiler helpers | 0BSD |
-| `@types/node` | Pinned runtime types | MIT |
-| `eslint`, `typescript-eslint` | Source and tooling lint | MIT |
-| `vitest`, `@vitest/coverage-v8` | Unit tests and coverage | MIT |
-| `semantic-release` | Standard version, tag and release orchestration | MIT |
-| `@semantic-release/commit-analyzer`, `@semantic-release/release-notes-generator` | Commit classification and release notes | MIT |
-| `@semantic-release/npm`, `@semantic-release/github` | Official npm/GitHub publishing | MIT |
-| `npm-undici-patch`, `npm-ip-address-patch` | Exact upstream fixes for npm's bundled development dependencies | MIT |
-
-## Release tooling
-
-The user selected standard semantic-release on main instead of maintaining a
-custom staging/finalization lifecycle. The official engine and plugins provide
-the release conventions and integrations that would otherwise need custom code.
-They are pinned to 25.0.9 (engine), 13.2.0 (npm), and 12.0.10 (GitHub), alongside
-the existing analysis/notes plugins. npm is pinned transitively to 11.21.1 so its
-bundled implementation remains reviewable.
-
-The temporary development aliases resolve to upstream `undici@6.29.1` and
-`ip-address@10.7.5`. Both have no runtime dependencies or registry install hooks
-and support the pinned Node runtime. The root postinstall hook copies their
-locked registry contents into npm's bundle; see the checks and removal procedure
-in [release security](release-security.md#temporary-npm-bundle-repair). Upstream
-sources are [Undici](https://github.com/nodejs/undici/releases/tag/v6.29.1) and
-[ip-address](https://github.com/beaugunderson/ip-address/releases/tag/v10.7.5).
-
-Canonical sources are [semantic-release](https://github.com/semantic-release/semantic-release),
-[npm plugin](https://github.com/semantic-release/npm) and
-[GitHub plugin](https://github.com/semantic-release/github). Distributed artifacts
-declare MIT, have no install hooks, and expose npm provenance attestations.
-The packages share four listed maintainers and each receives over 12 million
-monthly npm downloads; published updates support the pinned Node runtime.
-Registry signatures and attestations must be verified on changes. Public npm
-metadata does not establish individual maintainer MFA or complete account
-ownership history; provenance and the existing official namespace are the
-available trust evidence.
-
-The engine/plugin tree invokes Git and npm, reads/writes repository/package
-files and contacts GitHub/npm. It runs with release authority only after the
-protected merge. The complete installed tree remains subject to the blocking
-audit; adoption does not authorize accepting an advisory. Bundled npm components
-must be reviewed on disk, not just through root overrides. See
-[release security](release-security.md).
-
-Maintainer `titan-ron` owns updates, advisory review and removal. Replacing this
-toolchain means changing release.config.mjs and the trusted release job; it does
-not alter the library runtime. Use the previous explicit workflow only through
-a reviewed change if upstream becomes unsuitable. Keep review evidence in PRs.
-
-The Doppler CLI is separately installed and managed by the user. Rollup uses
-platform-specific optional binaries; preserve clean Linux/macOS install checks.
-The optional fsevents lock metadata can advertise an install script even when
-its reviewed archive contains neither an install hook nor binding.gyp.
-
-Run `npm ci`, `npm run audit`, `npm audit signatures`, and `npm run verify`.
-Official GitHub actions use exact release tags under the repository publisher
-policy; other remote actions require full SHAs.

package/docs/doppler.md

@@ -1,155 +0,0 @@
-# Doppler references and CLI authentication
-
-Doppler is resenv's only built-in cloud provider. After Nx or another loader
-populates the environment, resenv fetches referenced values through HTTPS and
-replaces them in memory before application startup. It resolves once per startup;
-restart the application to fetch changed secrets. This mode does not execute
-shell commands.
-The canonical `--require @ciqol/resenv/resolve` preload infers Doppler from
-`doppler://` values. The equivalent `--import` and `resenv run -- ...` do the
-same. The library also infers Doppler from values; call `resolve()` without
-a provider option. `resolve-doppler` and
-`run --doppler` remain supported for compatibility.
-
-## Local setup
-
-After [installing resenv](../README.md#install) in your application project,
-install the [official Doppler CLI](https://docs.doppler.com/docs/cli) and run
-this from the application's directory:
-
-```sh
-doppler login
-```
-
-Doppler owns browser authorization, token persistence, login scopes and logout.
-Use `doppler logout` to manage the CLI login. resenv never opens a browser,
-prompts for login, issues or revokes tokens, or reads or writes the OS
-credential store directly. There is no separate resenv login.
-
-Existing Doppler users can reuse their login. resenv asks the CLI for the token
-selected by its current working directory, so Doppler's directory-scoped
-workplace identities continue to apply. See
-[Doppler's scope guide](https://docs.doppler.com/docs/multiple-workplaces).
-`doppler setup` is not required for resenv references: their project and config
-are already explicit in each `doppler://` value. Nx or the caller remains
-responsible for dotenv file loading.
-
-### Platforms and installation locations
-
-The CLI handles its own credential storage on macOS, Linux and Windows. resenv
-does not require `secret-tool`, a separate keyring package or native Node addons.
-It discovers the CLI in these standard locations:
-
-| Platform | Locations, in lookup order |
-| --- | --- |
-| macOS / Linux | `/opt/homebrew/bin/doppler`, `/usr/local/bin/doppler`, `/usr/bin/doppler`, `~/.local/bin/doppler`, `~/bin/doppler` |
-| Windows | `~/AppData/Local/Microsoft/WinGet/Links/doppler.exe`, `~/scoop/apps/doppler/current/doppler.exe` |
-
-Here `~` is the OS user's home directory. Windows paths cover default per-user
-WinGet and Scoop installations. Custom and system-wide Windows installations
-outside these locations need an explicit `DOPPLER_TOKEN`. WSL uses the Linux
-installation and login within WSL. The runtime deliberately ignores the
-application's `PATH` so a repository-local executable cannot replace the
-credential helper.
-
-Windows discovery is covered with injected process tests; a native Windows
-end-to-end run is not yet verified. Automated checks never use a developer's
-Doppler login or OS credential store.
-
-### Migration from resenv-managed login
-
-`resenv login` and `resenv logout` have been removed. Run `doppler login` to
-establish the CLI identity, then start the application normally. Earlier resenv
-credentials stored under service `ciqol.envref.doppler`, account `default`, are
-ignored and are not migrated or deleted automatically. If you used that flow,
-remove the obsolete entry through your OS credential manager and revoke the
-obsolete token in Doppler when it is no longer needed.
-
-## Declare a reference
-
-Put references in the dotenv file Nx already selects, such as `.env.serve`:
-
-```dotenv
-API_TOKEN=doppler://my-project/dev/API_TOKEN
-```
-
-This is **resenv's own syntax**, not an official Doppler URI standard or
-SecretSpec's provider URI. All three fields are required: project, config and
-secret name. Project/config slugs must be lowercase letters, digits, `_` or
-`-`. Secret names can use Doppler's permissive punctuation; percent encoding
-is accepted for a secret name, such as `payments%2Fapi.key`. Query strings,
-fragments, credentials, ports and executable expressions are rejected.
-
-For an Nx Node target, put the preload on the application process:
-
-```json
-"runtimeArgs": ["--require", "@ciqol/resenv/resolve"]
-```
-
-For an Nx command target, use `resenv run -- node app.mjs` inside the
-target. Preloading the outer Nx process would run before Nx loads target files.
-resenv does not choose, read or rewrite dotenv files.
-
-## Runtime credential lookup
-
-Resolution checks these sources in order:
-
-1. An explicitly supplied `DOPPLER_TOKEN`.
-2. The current directory's existing Doppler CLI login, retrieved with the
-   documented `doppler configure get token --plain` operation.
-
-resenv captures the token internally and fetches secrets through HTTPS; it does
-not parse the CLI's private config format. The command uses a fixed executable,
-separate arguments, `--no-check-version` and `--no-read-env`, with a restricted
-environment. It inherits the application's working directory to preserve login
-scopes. Lookup has a fifteen-second timeout and a 16 KiB output limit. Captured
-output and helper errors are never forwarded to application logs.
-
-If the CLI is missing, install it in a supported location and run `doppler login`,
-or supply `DOPPLER_TOKEN`. A failed or empty CLI lookup reports that login is
-required. An explicitly supplied invalid token, malformed CLI token, access
-denial or network failure stops the operation without switching identities or
-starting login.
-
-In CI, containers and other unattended environments, supply a suitably scoped
-`DOPPLER_TOKEN` through the runner's secret facility. No CLI installation or
-local credential store is needed in that mode. Changing the CLI login affects
-the next application startup; resenv does not keep a persistent token cache.
-
-## Resolution and security boundaries
-
-- Fetches only named secrets from the public retrieve-secret endpoint. Repeated
-  references share one request per startup; values are not cached on disk.
-- Requires the computed value. Restricted, missing, null and invalid values
-  fail startup; resenv never substitutes a raw value as a fallback.
-- Keeps fetched output literal, including strings that start with `encrypted:`
-  or contain `$()`. Neither fetched nor original ciphertext is decrypted.
-- Resolves everything before applying changes. A failure leaves the caller's
-  environment untouched. Existing command mode remains separately opt-in.
-- Uses a fixed HTTPS origin, disables redirects, and has a ten-second timeout
-  per request. The synchronous preload uses a private Node worker with a
-  sixty-second overall limit. Up to four distinct lookups run concurrently;
-  duplicate references share one lookup. After a failure, no new lookups are
-  scheduled and active requests settle before failure is returned. Limits are
-  128 references, 64 KiB per value and
-  1 MiB for each response and the worker's captured output.
-- Preloads use a child Node process to wait for asynchronous HTTPS while
-  retaining `--require` compatibility. It receives only references and an
-  explicit credential through stdin, with results returned through a private
-  pipe. No Doppler CLI is required when `DOPPLER_TOKEN` is supplied.
-- Diagnostics show variable names and error codes, never tokens, provider
-  response bodies, CLI output or resolved values.
-
-This removes shell evaluation from Doppler lookups. It does not isolate
-untrusted repository code or agents that can access the same user's credential
-store. Doppler account permissions remain the authorization boundary. CLI user
-tokens inherit the user's privileges; a read-only service token can limit CI
-to a specific config.
-
-## Sources
-
-- [Doppler CLI installation and authentication](https://docs.doppler.com/docs/cli)
-- [Directory-scoped workplace logins](https://docs.doppler.com/docs/multiple-workplaces)
-- [Retrieve a secret](https://docs.doppler.com/reference/secrets-get)
-- [API authentication](https://docs.doppler.com/reference/api)
-- [Retrieve the CLI token](https://docs.doppler.com/docs/cli#fetch-cli-token-from-your-local-environment)

package/docs/maintainer-handoff.md

@@ -1,40 +0,0 @@
-# Maintainer guide
-
-Start with [AGENTS.md](https://github.com/ciqol/resenv/blob/main/AGENTS.md) for repository policy and
-[CONTRIBUTING.md](../CONTRIBUTING.md) for setup and verification. Work in an
-isolated task worktree on a `titan/*` branch. Authenticate as `titan-ron` for
-[ciqol/resenv](https://github.com/ciqol/resenv); `main` is the default and sole
-release branch.
-
-Inspect current Git status, branches, push remote and recent commits before
-editing. Read live GitHub checks, releases and npm metadata before release
-work; old chat messages or check results are not authoritative. Never copy
-credentials between sessions.
-
-| Guide | Maintained information |
-| --- | --- |
-| [README](../README.md) | Application installation, API and CLI usage |
-| [Doppler](doppler.md) | CLI authentication, lookup, migration and platform limits |
-| [Build](build.md) | Module formats, declarations, archive and CI contract |
-| [Dependencies](dependencies.md) | Tool rationale, installation and update policy |
-| [Releasing](releasing.md) | PR approval, main releases and recovery |
-| [Release security](release-security.md) | Dependency audit and release-tool review deadline |
-| [Security](../SECURITY.md) | Trust boundaries and private vulnerability reporting |
-
-## Code map
-
-| Path | Responsibility |
-| --- | --- |
-| `src/index.ts` | Resolution API and atomic environment replacement |
-| `src/preload.ts`, `src/resolve*.ts` | Startup integration and shared preload state |
-| `src/doppler/` | References, HTTPS, concurrency and CLI credential lookup |
-| `src/commands.ts` | Explicit shell substitution and process limits |
-| `bin/resenv.ts` | Child-process CLI |
-| `rollup.config.mjs`, `scripts/build.mjs` | CJS implementation, ESM facades, types and manifest |
-| `release.config.mjs` | Standard semantic-release plugins and main/0.x policy |
-| `scripts/release.mjs` | One-time 0.1.0 bootstrap, then the standard release command |
-| `scripts/verify-release.mjs` | Trusted event, review expiry, 0.x and final package checks |
-| `.github/workflows/ci.yml` | Checks, one compiled build and publication on main merges |
-
-Keep docs focused on current contracts, decisions and procedures. Put per-run
-test results, benchmarks, audit snapshots and session history in PRs or CI.

package/docs/release-security.md

@@ -1,64 +0,0 @@
-# Release-tool security
-
-Maintainer: `titan-ron`. The complete installed tree must pass
-`npm audit --audit-level=moderate`; there are no advisory exceptions. The
-[review deadline](security-exceptions.json) remains **November 9, 2026 at
-00:00 UTC** and is enforced before publication. Do not extend it or suppress
-findings to unblock a release.
-
-Standard semantic-release and the official npm/GitHub plugins replace the
-standalone planner and staging controller. Their dependencies are now installed
-and audited normally. The old peer-omission and module-blocking policy no longer
-applies to tools explicitly selected for this pipeline. No release tool ships
-to package consumers.
-
-## Publishing authority
-
-PR merge is approval. Branch rules require the real CI/CodeQL checks and prevent
-direct pushes, force pushes, deletion and bypass. PRs and manual dispatches
-cannot publish. Only main pushes may enter the `release` environment, with
-contents write and OIDC permissions. There are no npm tokens or additional
-reviewers. The release token is exposed only to the release step, and checkout
-does not persist credentials.
-
-The job consumes compiled output tested by CI. The npm plugin changes release
-metadata and packs it; the verification hook tests the final package. Publishing
-uses the prepared directory, whose manifest has no package lifecycle scripts.
-The source is not rebuilt. The bootstrap publishes its checked tarball directly.
-GitHub issue/PR comments and labels are disabled in the GitHub plugin so it
-needs no issue or pull-request write permission.
-
-## Dependency review
-
-Review actual installed artifacts, including npm's bundled dependencies.
-Overrides are not evidence that bundled files changed: inspect their manifests
-on disk. A failing dependency audit blocks merge and release; it is not a
-non-blocking report. Do not broaden exceptions or silently substitute an
-unreviewed npm version.
-
-### Temporary npm bundle repair
-
-npm 11.21.1 bundles vulnerable `undici` and `ip-address` files that npm overrides
-do not replace. Until an upstream npm release includes the fixes, the reviewed
-root `postinstall` hook replaces those two directories with the exact registry
-packages `undici@6.29.1` and `ip-address@10.7.5`, installed under development-only
-aliases. Their integrity hashes are pinned in the lockfile, which also records
-the repaired bundle versions. This is an actual file replacement, not an audit
-exception or a metadata-only override.
-
-`npm run audit` first compares every installed bundle file with the corresponding
-locked upstream package. Missing, extra or modified files fail the check. The
-repair accepts only the reviewed npm and dependency versions and rejects patch
-packages with runtime dependencies. It does not fetch code or use credentials.
-Registry signatures verify the upstream packages; they do not attest the locally
-repaired npm bundle as an npm-maintained distribution.
-
-Remove the hook, repair script/tests, aliases and repaired lock entries together
-when upgrading to an npm release containing both fixes. Regenerate the lockfile
-and validate a clean install, on-disk versions, audit, signatures and package
-checks before removing the repair. The existing review deadline still applies.
-
-Use pinned versions and the lockfile. Validate normal installs, registry
-signatures/attestations, the full audit and the package tests. See
-[dependencies](dependencies.md) for tool choices. Record dated findings and
-per-run evidence in the PR, not in this document.

package/docs/releasing.md

@@ -1,78 +0,0 @@
-# Releases
-
-**Merge the PR to `main`; CI publishes the release.** There is no separate
-approval button, npm staging queue or Finalize job. Manual workflow dispatch
-runs checks only. The default branch requires a PR, current passing checks,
-resolved review threads and squash merging, with no bypass actors. The sole
-maintainer approves by merging; no second reviewer is required.
-
-## Normal flow
-
-CI audits dependencies, checks signatures, lint, types and coverage, builds
-once, and tests the packed build across Linux Node 20/22/24 and macOS Node 24.
-After a merge, the protected release job downloads that build and invokes
-standard semantic-release. The official npm plugin prepares the release
-version and archive; consumer checks run again on the final package. The
-official npm and GitHub plugins publish to npm `latest` and create the GitHub
-release. No source is rebuilt during release.
-
-Conventional Commits determine releases: fixes and performance changes bump
-patch, features bump minor, and breaking changes bump minor while the package
-remains below 1.0. Docs and maintenance commits alone do not trigger a release.
-Squash PR titles must follow that convention. `0.x.x` denotes initial
-development, not a SemVer prerelease; published versions have no beta suffix.
-A guard blocks 1.0 until that transition is reviewed explicitly.
-
-## Initial 0.1.0 release
-
-semantic-release starts at 1.0.0 when no regular release tag exists. To preserve
-0.x numbering without a fake tag, the first enabled main release publishes the
-tested `0.1.0` archive through npm OIDC and records its real tag and GitHub
-release. Thereafter the normal engine uses that baseline. Existing beta tags
-and npm versions remain historical; the `beta` channel is not updated.
-
-## Setup
-
-- Default/release branch: `main`, protected by PRs and the actual CI/CodeQL checks.
-- npm trusted publisher: `ciqol/resenv`, `ci.yml`, environment `release`, with
-  **direct publish** permission. Stage-only permission cannot run this flow.
-- GitHub environment `release`: allow only `main`, with no required reviewers.
-- `RELEASE_ENABLED=true` only after protection, the npm publisher and dependency
-  audit are verified. The maintainer manages the npm setting.
-
-On npmjs.com, open **@ciqol/resenv → Settings → Trusted publishing** and
-configure its GitHub Actions publisher with these exact values:
-
-| Field | Value |
-| --- | --- |
-| Organization or user | `ciqol` |
-| Repository | `resenv` |
-| Workflow filename | `ci.yml` (filename only) |
-| Environment name | `release` |
-| Allow npm publish | Enabled |
-| Allow npm dist-tag | Not needed for this single-branch release flow |
-
-Save the configuration and complete npm's confirmation if prompted. Staging is
-always allowed; enabling direct publishing is the required change. The branch
-restriction lives in GitHub's `release` environment, which already allows only
-`main`. Keep account 2FA and the existing token restrictions; no npm token is
-needed. See [npm's trusted-publishing guide](https://docs.npmjs.com/trusted-publishers/).
-
-Never publish from a developer machine, configure a permanent npm publishing
-token, or request local npm login. Local `npm run release:check` is read-only
-with respect to publication. Only the trusted main push can pass the release
-guard. A merge does not waive a failing audit or the security review expiry.
-
-## Failures
-
-Inspect the failed run, npm version and GitHub tag before retrying. The standard
-engine creates its tag before calling publishers; a failed publication may
-therefore leave a tag or partial release. Rerunning is not a general repair for
-that state. Recover the intended version using its original source and archive
-after maintainer review; do not retag different code or silently replace a
-published version. The initial bootstrap creates its tag after npm succeeds;
-if GitHub recording fails, recover that published baseline before another run.
-
-No workflow automatically deletes tags, releases or npm versions. Existing
-beta versions without matching GitHub releases need separate recovery from
-their original evidence. See [release security](release-security.md).

package/docs/security-exceptions.json

@@ -1,6 +0,0 @@
-{
-  "expires": "2026-11-09T00:00:00.000Z",
-  "owner": "titan-ron",
-  "scope": "No advisory exceptions; the complete installed tree must pass npm audit at moderate severity.",
-  "exceptions": []
-}