npm - @ciqol/resenv - Versions diffs - 0.1.0 → 0.1.2 - Mend

@ciqol/resenv 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +92 -158
package/package.json +2 -8
package/CONTRIBUTING.md +0 -211
package/SECURITY.md +0 -74
package/docs/build.md +0 -139
package/docs/dependencies.md +0 -68
package/docs/doppler.md +0 -155
package/docs/maintainer-handoff.md +0 -40
package/docs/release-security.md +0 -64
package/docs/releasing.md +0 -78
package/docs/security-exceptions.json +0 -6

package/README.md CHANGED Viewed

@@ -1,29 +1,20 @@
 # @ciqol/resenv
-**Replace references already in `process.env` with their resolved values at
-application startup.** Your existing loader, such as Nx, chooses the dotenv
-files. resenv resolves the resulting environment before application code runs.
-**Doppler is the only built-in cloud provider.** A value such as
-`doppler://my-project/dev/API_TOKEN` tells resenv which secret to fetch. The
-application then reads the actual value from `process.env.API_TOKEN`.
-```text
-Nx or another loader sets process.env
-                  |
-resenv fetches the referenced values and replaces them in memory
-                  |
-Application starts with ordinary environment values
-```
+[![🏗️ CI](https://github.com/ciqol/resenv/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ciqol/resenv/actions/workflows/ci.yml)
+[![NPM Version](https://img.shields.io/npm/v/@ciqol/resenv)](https://www.npmjs.com/package/@ciqol/resenv)
+[![NPM Downloads](https://img.shields.io/npm/dm/@ciqol/resenv)](https://www.npmjs.com/package/@ciqol/resenv)
-Resolution happens once at startup. It does not watch the provider for changes;
-restart the application to fetch updated values. No filename is passed to
-resenv, and dotenv files are never rewritten.
+**Resolve secret references already in `process.env` before application code
+runs.** Your existing loader, such as Nx, chooses and loads dotenv files;
+resenv replaces references in memory. It never rewrites those files.
-Requires Node.js 20 or later. The package is experimental and remains in initial
-development; its API may change between 0.x releases.
+Doppler is the only built-in cloud provider. For example,
+`API_TOKEN=doppler://my-project/dev/API_TOKEN` becomes the fetched secret in
+`process.env.API_TOKEN`. Resolution happens once at startup; restart the
+application to fetch updated values.
-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).
+Requires Node.js 20 or later. The package has no runtime npm dependencies and
+is experimental; its API may change between 0.x releases.
 ## Install
@@ -33,84 +24,60 @@ Install in your application project:
 npm install --save-exact @ciqol/resenv
 ```
-This records the version selected by npm's `latest` tag in your project's
-manifest and lockfile.
-The CLI examples below use `npx --no-install` to run the copy installed in your
-project. In an npm script, use `resenv` directly.
+The CLI examples use `npx --no-install` to run that installed copy. In an npm
+script, use `resenv` directly.
 ## Use with Doppler
-Doppler manages application secrets. If you're new to it, start with
-[Doppler's introduction](https://docs.doppler.com/docs/start).
-### 1. Authenticate locally
+### 1. Authenticate
-Follow the [official Doppler CLI installation guide](https://docs.doppler.com/docs/cli#installation)
-for your operating system, then log in from your application directory:
+Install the [official Doppler CLI](https://docs.doppler.com/docs/cli#installation),
+then log in from your application directory:
 ```sh
 doppler login
 ```
-Each developer authenticates with their own Doppler access.
-> [!WARNING]
-> Authentication and credential storage depend on the Doppler CLI's implementation
-> and may vary by platform or CLI version. resenv only reuses its existing token;
-> it does not manage login, logout or credential storage, or access the OS
-> credential store directly.
-At startup, resenv uses `DOPPLER_TOKEN` when supplied; otherwise it reads the
-existing Doppler CLI token for the application's working directory. It then
-fetches only referenced secrets through the HTTPS API. Missing credentials or
-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
-migration from the earlier resenv-managed login.
+resenv uses `DOPPLER_TOKEN` when supplied; otherwise it reuses the CLI login
+selected for the application's working directory. Doppler owns login, logout
+and credential storage. Missing credentials or access stop startup without
+prompting for login.
-Need another secrets provider, operating system or CLI installation method?
-[Request support](https://github.com/ciqol/resenv/issues/new) with your use case
-and platform details.
+For CI and other unattended environments, supply a suitably scoped
+`DOPPLER_TOKEN` through your runner's secret facility; no CLI is needed.
+See [authentication and platform details](https://github.com/ciqol/resenv/blob/main/docs/doppler.md)
+for supported CLI locations and lookup rules.
-### 2. Declare references in the environment your app already loads
+### 2. Declare references
-For example, in an Nx application's `.env.serve`:
+In the environment your application already loads, such as Nx's `.env.serve`:
 ```dotenv
 API_TOKEN=doppler://my-project/dev/API_TOKEN
 PORT=3000
 ```
-The reference contains the Doppler project, config and secret name. This is
-resenv's reference syntax. Plain values such as `PORT` pass through unchanged.
-The reference itself grants no access: the authenticated identity needs
-permission to read that secret. Doppler references need no dotenvx private key.
+Each reference names a project, config and secret. The authenticated identity
+must have access to that secret. Plain values such as `PORT` pass through.
-### 3. Preload resenv on the application process
+### 3. Preload on the application process
-Once the environment has been loaded:
+After your loader has populated the environment:
 ```sh
 node --require @ciqol/resenv/resolve app.cjs
 node --import @ciqol/resenv/resolve app.mjs
 ```
-The preload replaces `process.env.API_TOKEN` before the application and its
-imports execute. It infers Doppler from the value, so no provider flag is needed.
+The preload replaces references before the application and its imports execute.
 Alternatively, wrap a command whose environment is already populated:
 ```sh
 npx --no-install resenv run -- node app.mjs
 ```
-The wrapper supplies resolved values to the child process. It inherits
-stdin/stdout/stderr, preserves exit status and forwards SIGINT, SIGTERM and
-SIGHUP to that child. On POSIX, the child runs in its own session so terminal
-signals reach it only through the wrapper.
+The wrapper passes the resolved environment to its child, inherits terminal I/O,
+preserves exit status and forwards termination signals.
 ## Nx integration
@@ -133,126 +100,93 @@ Put the preload on the application's target, after Nx loads its dotenv files:
 }
 ```
-Run `nx serve app`. Nx selects `.env.serve` and any applicable overrides,
-then starts the application with resenv. Use your application's existing path
-and target options. For an existing `@nx/js:node` target, add:
+Run `nx serve app`, using your application's existing path and target options.
+For an existing `@nx/js:node` target, add:
 ```json
 "runtimeArgs": ["--require", "@ciqol/resenv/resolve"]
 ```
-Preloading the outer `nx` process runs too early. A shell-wide `NODE_OPTIONS`
-setting also affects unrelated processes. Keep the preload on the application
-target. If a build needs secrets, its process needs its own integration after
-its environment is loaded; values embedded in build output remain in that output.
-## Resolution behavior
-- Only the enabled reference forms are resolved. Ordinary values pass through.
-- Doppler fetches only the named secrets; repeated references share one request
-  within a resolution pass. Values are not cached on disk.
-- All lookups must succeed before the environment is changed or a child starts.
-  Missing access, malformed references and provider failures stop startup.
-- Fetched values stay literal, even if they contain `$()` or another reference.
-- The canonical preload leaves shell expressions literal. Executing commands
-  requires the separate opt-in described below.
-- 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).
+Preloading the outer `nx` process runs too early. Keep the preload on each
+application or build process that needs secrets, after its environment is loaded.
+Secrets embedded in build output remain in that output.
 ## Library API
-Call the library after your loader has populated the environment, before
-importing modules that read configuration:
+Call the synchronous resolver after loading the environment, before importing
+modules that read configuration:
 ```js
 import { resolve } from '@ciqol/resenv'
 const childEnv = resolve()
-// Also replace values in process.env; the returned copy can be ignored.
 resolve(process.env, { replace: true })
 ```
-`resolve(env = process.env, options = {})` always returns a new resolved
-environment. `replace` defaults to `false`, leaving the input unchanged. With
-`replace: true`, it also replaces values in the input after every lookup succeeds;
-the return value is still an independent copy.
+`resolve(env = process.env, options = {})` always returns an independent
+resolved copy. CommonJS uses `require('@ciqol/resenv')`.
-Providers are inferred from each original value, just as with `/resolve` and
-`run`. Doppler is the only supported cloud provider today. No options are
-required: without references, the result is an unchanged copy and no credentials
-are accessed. An environment can contain several references, including different
-Doppler projects/configs. Each value selects its own source; a command can supply
-a Doppler token. Commands still require
-`commands: true`. Returned secret values are never interpreted again.
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `replace` | `false` | Also replace input values after all lookups succeed. Requires `process.env` or writable data properties. |
+| `commands` | `false` | Execute whole-value `$(command)` expressions through POSIX `/bin/sh`. |
+| `commandTimeoutMs` | `30000` | Per-command timeout in milliseconds; a positive integer up to `2147483647`. |
-CommonJS uses the same API through
-`require('@ciqol/resenv')`. Both formats share the `ResenvError` class, whose
-`code` identifies the failure. CLI and preload failures exit with a safe message.
+Doppler is inferred from original values. Without references, the result is an
+unchanged copy and no credentials are accessed. Library failures throw
+`ResenvError`; its `code` identifies the failure. CLI and preload failures exit
+with a safe message.
-Using `replace: true` requires `process.env` or writable data properties. A read-only
-property, setter or Proxy target fails before any replacement is committed.
-Keep the default copy mode for inputs that should remain unchanged. The Node
-preloads enable in-place replacement so application imports see resolved values.
+## Resolution and safety
-## Debug startup
+- All lookups must succeed before the input environment changes or a child starts.
+- Only named secrets are fetched; repeated references share a request within a
+  resolution pass. Values are not cached on disk.
+- Fetched values stay literal, even if they contain another reference or `$()`.
+- Shell commands require explicit opt-in and run with your permissions. Failed
+  resolution cannot undo their file or network effects.
+- Use one preload mode per process. Combining modes or a preload with the CLI
+  fails with `CONFLICTING_PRELOADS`. Avoid additional resolvers in `NODE_OPTIONS`.
+- Application code can read its secrets and any credentials supplied to it.
-```sh
-NODE_DEBUG=ciqol:resenv node --require @ciqol/resenv/resolve app.mjs
+See [Doppler limits and compatibility](https://github.com/ciqol/resenv/blob/main/docs/doppler.md)
+and [security guidance](https://github.com/ciqol/resenv/blob/main/SECURITY.md).
+## Optional commands
+Enable commands alongside Doppler references through the library:
+```js
+const env = resolve({ BUILD_LABEL: '$(printf local)' }, { commands: true })
 ```
-For the Nx target above, use `NODE_DEBUG=ciqol:resenv nx serve app`. Set `NODE_DEBUG`
-when launching Node, before dotenv loading. Diagnostics use `node:util`'s
-`debuglog` and are off by default:
+Or use `resenv run --commands -- ...`, or preload
+`@ciqol/resenv/resolve-commands`. The canonical `/resolve` preload leaves shell
+expressions literal. Only use command mode with trusted configuration; see
+[command limits](https://github.com/ciqol/resenv/blob/main/SECURITY.md#command-execution).
+## Debug startup
-```text
-CIQOL:RESENV 12345: Replaced secret value for "API_TOKEN".
-CIQOL:RESENV 12345: Done: replaced 1 secret value(s).
+```sh
+NODE_DEBUG=ciqol:resenv node --require @ciqol/resenv/resolve app.mjs
 ```
-With no matching references, the only message is `Nothing to handle.` Failures
-include a safe error and completion summary. Logs omit values, tokens, command
-text and provider responses; no log files are created.
+For Nx, use `NODE_DEBUG=ciqol:resenv nx serve app`. Enable it when launching Node,
+before dotenv loading. Diagnostics omit secrets, tokens, commands and provider
+responses. `NODE_DEBUG=child_process` or `NODE_DEBUG=*` can expose credentials;
+resenv blocks its subprocess operations in that mode. See
+[diagnostic details](https://github.com/ciqol/resenv/blob/main/SECURITY.md#diagnostics).
-`NODE_DEBUG=child_process` (including `NODE_DEBUG=*`) makes Node print spawn
-options containing credentials. resenv blocks its subprocess operations with
-`UNSAFE_DEBUG_LOGGING` in that mode. Use `NODE_DEBUG=ciqol:resenv` instead.
+## Further reading
-## Optional commands
+Each npm package includes this README for its installed version. The
+[repository README](https://github.com/ciqol/resenv#readme) and linked online
+guides follow current development and may describe newer versions. GitHub
+[releases](https://github.com/ciqol/resenv/releases) contain version change notes.
-- **Opt-in shell commands:** `/resolve-commands` resolves complete `$(command)`
-  values through `/bin/sh`. The canonical `/resolve` preload leaves these values
-  literal for both `--require` and `--import`, including when `RESENV_COMMANDS`
-  is set in the environment. `resenv run --commands -- ...` enables commands
-  alongside inferred Doppler references, as does the command preload. Use only
-  trusted configuration; commands run with your permissions. A timeout limits
-  execution time, but cannot undo file changes, network requests or other effects.
-  Leave this option disabled when the environment can contain untrusted input.
-  Commands have closed stdin, a 30-second timeout and a 64 KiB combined output
-  limit. Trailing LF characters are removed; fetched output stays literal.
-  Embedded forms such as `prefix$(command)suffix` are unsupported.
-Values beginning with `encrypted:` are left unchanged. resenv resolves cloud
-references; dotenvx decryption is outside its scope. The package has no runtime
-npm dependencies.
-`/resolve-doppler` is an equivalent name for `/resolve`; `run --doppler` remains
-accepted. New integrations should use the canonical entry points above.
-Use one preload mode per process. Combining `/resolve` and `/resolve-commands`
-or combining a preload with `resenv run` fails with `CONFLICTING_PRELOADS` to
-prevent reinterpreting fetched values. Do not configure a second resolver in
-the child process through `NODE_OPTIONS` or other launch hooks.
-For both modes together, use `resenv run --commands -- ...` or one library call
-with `{ commands: true }`.
-## Contributing
-For checkout setup, building, testing, trying local changes in another project
-and submitting fixes, see [CONTRIBUTING.md](CONTRIBUTING.md).
+- [Contributing, development and tests](https://github.com/ciqol/resenv/blob/main/CONTRIBUTING.md)
+- [Request provider or platform support](https://github.com/ciqol/resenv/issues/new)
+- [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)
 ## License

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ciqol/resenv",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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": []
-}