@ciqol/resenv 0.1.0-beta.2 → 0.1.1

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.
package/README.md CHANGED
@@ -20,19 +20,25 @@ Resolution happens once at startup. It does not watch the provider for changes;
20
20
  restart the application to fetch updated values. No filename is passed to
21
21
  resenv, and dotenv files are never rewritten.
22
22
 
23
- Requires Node.js 20 or later. This is an experimental beta, published on npm's
24
- `beta` channel.
23
+ Requires Node.js 20 or later. The package is experimental and remains in initial
24
+ development; its API may change between 0.x releases.
25
+
26
+ Each npm package includes this README for the version you installed. The
27
+ [repository README](https://github.com/ciqol/resenv#readme) and linked online
28
+ guides follow current development and may describe newer versions.
29
+
30
+ 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).
25
31
 
26
32
  ## Install
27
33
 
28
- Install the beta in your application project:
34
+ Install in your application project:
29
35
 
30
36
  ```sh
31
- npm install --save-exact @ciqol/resenv@beta
37
+ npm install --save-exact @ciqol/resenv
32
38
  ```
33
39
 
34
- This records the selected beta version in your project's manifest and lockfile.
35
- The `latest` tag points to the same beta; omitting `@beta` installs it too.
40
+ This records the version selected by npm's `latest` tag in your project's
41
+ manifest and lockfile.
36
42
 
37
43
  The CLI examples below use `npx --no-install` to run the copy installed in your
38
44
  project. In an npm script, use `resenv` directly.
@@ -66,7 +72,7 @@ access stop startup without opening a browser or prompting for login.
66
72
 
67
73
  For CI and other unattended environments, supply `DOPPLER_TOKEN` through your
68
74
  runner's secret facility; the CLI is not needed in that mode. See
69
- [Doppler authentication and platform details](docs/doppler.md), including
75
+ [Doppler authentication and platform details](https://github.com/ciqol/resenv/blob/main/docs/doppler.md), including
70
76
  migration from the earlier resenv-managed login.
71
77
 
72
78
  Need another secrets provider, operating system or CLI installation method?
@@ -157,8 +163,8 @@ its environment is loaded; values embedded in build output remain in that output
157
163
  - Application code can read its resolved environment. Access to the same
158
164
  credentials also permits other code or sessions to retrieve those secrets.
159
165
 
160
- See [Doppler limits](docs/doppler.md#resolution-and-security-boundaries) and
161
- [security guidance](SECURITY.md).
166
+ See the current [Doppler limits](https://github.com/ciqol/resenv/blob/main/docs/doppler.md#resolution-and-security-boundaries)
167
+ and [security guidance](https://github.com/ciqol/resenv/blob/main/SECURITY.md).
162
168
 
163
169
  ## Library API
164
170
 
@@ -250,7 +256,7 @@ with `{ commands: true }`.
250
256
  ## Contributing
251
257
 
252
258
  For checkout setup, building, testing, trying local changes in another project
253
- and submitting fixes, see [CONTRIBUTING.md](CONTRIBUTING.md).
259
+ and submitting fixes, see [CONTRIBUTING.md](https://github.com/ciqol/resenv/blob/main/CONTRIBUTING.md).
254
260
 
255
261
  ## License
256
262
 
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@ciqol/resenv",
3
- "version": "0.1.0-beta.2",
3
+ "version": "0.1.1",
4
4
  "description": "Replace environment references with their resolved values at application startup",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
7
7
  "access": "public",
8
- "tag": "beta",
8
+ "tag": "latest",
9
9
  "registry": "https://registry.npmjs.org/"
10
10
  },
11
11
  "repository": {
@@ -71,7 +71,6 @@
71
71
  "engines": {
72
72
  "node": ">=20"
73
73
  },
74
- "dependencies": {},
75
74
  "files": [
76
75
  "*.cjs",
77
76
  "*.mjs",
@@ -79,11 +78,6 @@
79
78
  "*.d.mts",
80
79
  "doppler",
81
80
  "bin",
82
- "types",
83
- "README.md",
84
- "LICENSE",
85
- "CONTRIBUTING.md",
86
- "SECURITY.md",
87
- "docs"
81
+ "types"
88
82
  ]
89
83
  }
package/CONTRIBUTING.md DELETED
@@ -1,209 +0,0 @@
1
- # Contributing
2
-
3
- Starting a new session? Read the [maintainer handoff](docs/maintainer-handoff.md)
4
- and [repository instructions](https://github.com/ciqol/resenv/blob/beta/AGENTS.md) before editing or releasing.
5
-
6
- The [README](README.md) covers using resenv in an application. This guide covers
7
- changing resenv itself and verifying those changes.
8
-
9
- Releases start at `0.1.0-beta.1` on the sole branch `beta`, using npm tags
10
- `beta` and `latest` for the same tested version. Semantic-release's official
11
- commit-analysis and release-notes plugins select releasable changes and generate
12
- notes; actual beta tags supply the next
13
- prerelease counter. The root and ordinary local builds remain private prototypes.
14
- CI generates the publishable manifest before packing and testing it, then stages
15
- the exact archive through npm OIDC for maintainer approval. See
16
- [releasing](docs/releasing.md) and the bounded [release-tool review](docs/release-security.md).
17
- The source uses the [MIT license](LICENSE), copyright ciqol contributors.
18
-
19
- ## Local development
20
-
21
- Use the Node version in `.nvmrc` and npm:
22
-
23
- ```sh
24
- nvm use
25
- npm ci
26
- npm run verify
27
- ```
28
-
29
- The committed `.npmrc` omits automatically installed peer dependencies. The
30
- release planner calls the two official plugins directly, so their full engine
31
- peer and its publisher dependencies are intentionally not installed. Audit and
32
- planning enforce that absence. `npm ls` still reports the declared missing
33
- engine peers; standalone plugin behavior is covered directly by the release
34
- specs. Keep this install policy when refreshing the lockfile; do not use force
35
- or legacy peer resolution. See [the dependency review](docs/dependencies.md).
36
-
37
- `npm run verify` is the complete local check: lint, strict source/spec type
38
- checks, build, unit/process tests and installed-package checks. To build without
39
- running the checks, use `npm run build`.
40
-
41
- After building, try the CLI from this checkout:
42
-
43
- ```sh
44
- node dist/bin/resenv.cjs --help
45
- ```
46
-
47
- Author library and CLI code as `.ts`; Rollup's TypeScript plugin produces both
48
- module formats and declarations from that implementation. Colocate Vitest unit
49
- specs as `*.spec.ts` beside each tested module and import its source. Build and
50
- release scripts have colocated `*.spec.mjs` Vitest specs. Keep
51
- process, package and integration checks in `test/` as `.mjs`; they exercise
52
- compiled output and installed packages. Tests use dummy credentials and commands.
53
- Never use real secrets in fixtures, terminal output, screenshots, issues, or
54
- pull requests.
55
-
56
- Provider detection belongs to the original environment values, including library
57
- calls without options. Keep shell execution behind `commands: true`, preserve
58
- literal fetched output, and validate references before any command runs.
59
-
60
- ESLint applies rules that use type information to the TypeScript implementation and specs
61
- and checks the JavaScript build tooling.
62
- Use `npm run lint:fix` for available automatic fixes; preserve the repository's
63
- existing compact formatting. Public object shapes use `type` with `readonly`
64
- properties. `Environment` is intentionally mutable because in-place resolution
65
- updates it. `npm run typecheck` checks the entire library and CLI with `strict`
66
- and `noUncheckedIndexedAccess`. A separate spec configuration checks tests without
67
- shipping them in JavaScript or declarations. Do not maintain separate handwritten declarations.
68
-
69
- ```sh
70
- npm run test:unit # colocated Vitest specs, no build required
71
- npm run test:watch # watch unit specs while editing
72
- npm run test:coverage # source unit coverage, text, lcov and Cobertura output
73
- npm run test:integration # process checks, requires a build
74
- ```
75
-
76
- `npm test` runs unit and process tests. Mock or inject provider calls, credential
77
- lookup and process control in unit tests. Keep checks that spawn actual commands
78
- or temporary applications in `test/`. The unit coverage
79
- report measures source and is separate from packed-package and process checks.
80
- `npm run verify` enforces a 90% global floor for source statements, branches,
81
- functions and lines. Worker and preload entry files stay in the denominator;
82
- the CLI is checked separately by process and packed-package tests. CI retains
83
- LCOV and Cobertura reports for seven days in the `resenv-coverage` artifact.
84
- The official `actions/upload-code-coverage` action uploads Cobertura in a separate
85
- job; fork PRs retain the local gate and reports but cannot upload. CLI lookup
86
- checks use injected helpers and temporary dummy executables; they never access
87
- a developer credential store or authenticated provider session.
88
-
89
- Use normal npm lifecycle behavior locally and in CI. Review install hooks,
90
- including implicit native builds, when changing dependencies; record any
91
- required setup in [the dependency review](docs/dependencies.md). Suppressing
92
- lifecycle hooks can skip required setup, so it is not part of the standard
93
- installation commands. The explicit build/check commands remain required.
94
-
95
- The package check packs `dist/` and installs that tarball into a temporary
96
- consumer outside the repository. The install is offline, uses npm's existing
97
- cache and the repository's reviewed runtime lock entries. It installs with
98
- `npm ci` without needing cached registry metadata. It does not link the source
99
- tree or publish. Run `npm ci` first to populate the archive cache. The check
100
- exercises both module formats, CLI and preloads, shared error identity, single
101
- preload execution and `.cts`/`.mts` consumer types.
102
-
103
- Pass an existing archive to test the same build CI uses:
104
- `npm run test:package -- /absolute/path/to/package.tgz`. For a final CI candidate,
105
- also pass its `release.json` as the second argument. The supplied package's
106
- name, version, executable mode and manifest are checked before runtime probes.
107
- The README inside the archive must match the checkout, install from npm's
108
- `beta` channel and avoid unpublished or local-archive installation guidance.
109
- `npm run verify` runs lint, typecheck, build and tests; `npm run release:check`
110
- also previews the package contents. Neither publishes or creates a tag.
111
-
112
- Rebuild after source, declarations, metadata or documentation changes. The build
113
- cleans `dist/` first and generates its manifest from the root package. See
114
- [docs/build.md](docs/build.md). Ordinary local builds remain private. Only a validated CI release plan removes
115
- that guard from the distribution manifest; never edit it by hand.
116
-
117
- ## Try changes in an application
118
-
119
- ### Install a local archive
120
-
121
- From the resenv checkout:
122
-
123
- ```sh
124
- npm run build
125
- npm run pack:local
126
- ```
127
-
128
- Install the resulting archive from the application's directory:
129
-
130
- ```sh
131
- npm install --save-exact /absolute/path/to/ciqol-resenv-0.1.0-beta.1.tgz
132
- ```
133
-
134
- This changes the application's manifest and lockfile. The archive must exist
135
- wherever it installs dependencies. Use a new archive version for changes to an
136
- already shared build; never overwrite an archive another project uses. Root
137
- package overrides do not propagate to consumers; inspect the installed tree
138
- against [the dependency review](docs/dependencies.md).
139
-
140
- ### Try local changes without changing the application's CI
141
-
142
- Link this checkout's built `dist/` directory at the application's ignored
143
- `node_modules/@ciqol/resenv`, retaining any existing installation first. Keep
144
- references in an ignored `.env.serve.local` and the application's target edit
145
- local. Leave its manifest, lockfile and CI configuration unchanged.
146
-
147
- Rebuild resenv after source, metadata or documentation changes and restart the
148
- application. An application `npm ci` can remove the link; recreate it when needed.
149
- Authenticate with the official Doppler CLI from the application's directory:
150
-
151
- ```sh
152
- doppler login
153
- ```
154
-
155
- resenv reuses that login at runtime. Automated tests use injected or mocked
156
- credentials; real login is a manual integration check owned by Doppler's CLI.
157
-
158
- ## Optional integration checks
159
-
160
- `npm run bench` measures fresh-process startup, a plain 200-variable environment,
161
- and a mocked provider with eight distinct lookups. It needs a build first and
162
- does not contact a provider. Timings are observations, not CI pass/fail thresholds.
163
-
164
- With an existing Nx installation:
165
-
166
- ```sh
167
- npm run test:nx -- /absolute/path/to/workspace/node_modules
168
- ```
169
-
170
- This creates a temporary Nx workspace and checks target-file loading,
171
- precedence and secret resolution with dummy values. It does not use the
172
- source workspace's dotenv files, credentials or remote cache.
173
-
174
- ## Changes
175
-
176
- Keep dotenv file discovery with the caller. Doppler is the only built-in cloud
177
- provider; its authentication and lookups live under `src/doppler/`.
178
- Preserve all-or-nothing environment updates, strict failures, explicit command
179
- opt-in and literal handling of resolved values. Update the public API types and
180
- documentation together with behavior changes.
181
-
182
- Keep one public resolver, `resolve()`. It always returns an independent
183
- resolved copy and replaces input values only with `{ replace: true }`. Preloads
184
- enable that option; the CLI passes the returned copy to its child process.
185
-
186
- Add regression tests for changed behavior and avoid real provider calls. Use
187
- Conventional Commit subjects, for example `fix(resolver): preserve empty values`.
188
- Review dependency changes under the [dependency policy](docs/dependencies.md)
189
- and put the evidence in the PR. Update the guide when a lasting choice changes.
190
-
191
- CODEOWNERS identifies the maintainer. Keep bug reports and pull requests focused
192
- on observable behavior and include the checks run. Weekly dependency updates are
193
- grouped, with major version updates reviewed separately; bots cannot merge them.
194
-
195
- Keep the README focused on installation, authentication, application integration,
196
- API behavior and troubleshooting. Put contributor tooling, test commands and
197
- local development instructions here; detailed internals belong in `docs/`.
198
- Keep docs current rather than appending session logs, dated audit reports or
199
- test transcripts. Record run results in PRs and CI.
200
-
201
- Security reports follow [SECURITY.md](SECURITY.md). Publication and repository
202
- visibility changes require a separate maintainer decision; see the
203
- [release checklist](docs/releasing.md).
204
-
205
- npm releases run only through GitHub Actions with npm trusted publishing (OIDC).
206
- The maintainer configures the npm side. Local development and release checks
207
- do not require `npm login`; do not publish from a developer machine or add npm
208
- publishing tokens. CI must publish the exact candidate archive that its tests
209
- verified.
package/SECURITY.md DELETED
@@ -1,74 +0,0 @@
1
- # Security
2
-
3
- ## Scope and trust
4
-
5
- resenv resolves values in a process environment. It does not provide a vault,
6
- access-control service, key rotation, or isolation between programs running
7
- with the same credentials. The application can read its resolved secrets and
8
- any credentials supplied to it.
9
-
10
- Doppler mode uses a fixed HTTPS API origin, disables redirects and fetches only
11
- referenced secret names. It does not execute shell expressions. Credentials
12
- come from an explicit `DOPPLER_TOKEN` or the current directory's existing
13
- Doppler CLI login. A fixed CLI helper captures that token privately; resenv
14
- does not parse Doppler's config files. An API rejection never triggers a switch
15
- to another identity. The official Doppler CLI owns browser authorization,
16
- token storage, login and logout. See [Doppler details](docs/doppler.md)
17
- for lookup rules, credential scope, migration and platform limits.
18
- The canonical `resolve` preload and `run` command select Doppler only for
19
- `doppler://` values. They do not infer shell execution from `$()` values.
20
- Startup does not initiate login. Use `doppler login` separately for local
21
- development or supply a suitably scoped token for unattended runs.
22
-
23
- Doppler's credential storage does not isolate credentials from other code
24
- running as the same user with access to them. resenv does not read or write the
25
- OS credential store directly or persist login tokens or fetched secrets.
26
- It does not automatically remove an explicitly supplied `DOPPLER_TOKEN` from
27
- the application environment. Tokens, captured CLI output and provider response
28
- bodies are not logged. The Node preload's private worker exchanges credentials
29
- and results over captured pipes, never process arguments or dotenv files.
30
-
31
- Command mode executes trusted configuration with the current user's
32
- permissions. Enable it only for configuration you have reviewed. Commands can
33
- access files and the network; failed resolution cannot undo their external
34
- effects. Commands are bounded by timeout and output limits, and their output
35
- is not included in resenv diagnostics.
36
-
37
- Node's `child_process` debug category prints spawn options, including stdin
38
- and environment values. resenv refuses its own subprocess and credential-helper
39
- operations when that category is enabled, including through `NODE_DEBUG=*`.
40
- Use `NODE_DEBUG=ciqol:resenv` for diagnostics that omit values. This guard does not
41
- control application logs, other instrumentation, or a debugger attached to the
42
- process.
43
-
44
- All values are resolved before resenv updates the caller's environment or
45
- starts the application. Provider failures, command failures and invalid
46
- environment values stop startup. Fetched values are never evaluated recursively. Application logs are outside resenv's control.
47
-
48
- Different automatic preload modes cannot be combined in one process. Otherwise
49
- the second mode could execute literal data fetched by the first.
50
- Combining a preload with the CLI is rejected for the same reason. Do not add
51
- another resolver to the child through `NODE_OPTIONS` or other launch hooks.
52
- Use one `resenv run --commands` invocation or one library call with commands
53
- enabled to resolve cloud references and commands together. Repeated manual
54
- library calls are separate operations; only pass original configuration to them.
55
-
56
- Provider responses must be valid UTF-8 and JSON, and resolved strings must not
57
- contain lone Unicode surrogates or null bytes. In-place replacement preflights
58
- all changed properties; read-only properties, setters and Proxy targets are
59
- rejected before any values are committed. Use `resolve()` to obtain a copy
60
- when the input is not a writable environment record.
61
-
62
- This experimental package has not had an independent security audit. See
63
- [verification](CONTRIBUTING.md) and [Doppler platform limits](docs/doppler.md).
64
-
65
- ## Reporting a vulnerability
66
-
67
- Do not open a public issue containing a vulnerability, credentials or sensitive
68
- output. [Report a vulnerability privately](https://github.com/ciqol/resenv/security/advisories/new)
69
- through GitHub. If that option is unavailable, contact the maintainer through
70
- an existing private channel.
71
-
72
- Include affected versions, platform, impact and a minimal reproduction using
73
- dummy data. Never include production tokens, private keys or environment dumps.
74
- There is no guaranteed response time or long-term support policy yet.
package/docs/build.md DELETED
@@ -1,135 +0,0 @@
1
- # Build and package contract
2
-
3
- The repository is one Node.js package. The library and CLI are authored in
4
- strict TypeScript. Vitest unit specs use colocated `*.spec.ts` files. Process,
5
- package and integration checks and build orchestration use `.mjs`. Rollup's official
6
- TypeScript plugin compiles the implementation; consumers need no TypeScript
7
- loader or compiler.
8
-
9
- ```sh
10
- npm ci
11
- npm run build
12
- npm test
13
- npm run test:package
14
- ```
15
-
16
- ## Output
17
-
18
- | Public entry | ESM | CommonJS | Declarations |
19
- | --- | --- | --- | --- |
20
- | `@ciqol/resenv` | `index.mjs` | `index.cjs` | `index.d.mts`, `index.d.cts` |
21
- | `@ciqol/resenv/resolve` | `resolve.mjs` | `resolve.cjs` | `resolve.d.mts`, `resolve.d.cts` |
22
- | `@ciqol/resenv/resolve-commands` | `resolve-commands.mjs` | `resolve-commands.cjs` | `resolve-commands.d.mts`, `resolve-commands.d.cts` |
23
- | `@ciqol/resenv/resolve-doppler` | `resolve-doppler.mjs` | `resolve-doppler.cjs` | `resolve-doppler.d.mts`, `resolve-doppler.d.cts` |
24
-
25
- These paths are relative to `dist/`. The executable points to
26
- `bin/resenv.cjs`; Rollup also emits its ESM wrapper. The command's user-facing
27
- name stays `resenv`.
28
-
29
- `resolve` reads the inherited environment and replaces Doppler references with
30
- their fetched values before application code starts. Doppler is the only
31
- built-in cloud provider. Original `encrypted:` values remain literal.
32
- `resolve-doppler` imports that same preload, so loading both names does not resolve fetched output again. Arbitrary commands require the
33
- separate `resolve-commands` entry or `run --commands`.
34
-
35
- The private `doppler-worker.cjs` entry lets synchronous preloads wait for HTTPS
36
- without turning the public CommonJS API into a promise. The worker is packed
37
- alongside the entries but is not a public export. It is located through package
38
- self-resolution, so the installed tarball does not depend on source paths.
39
-
40
- The root exports map defines the public entries. The build compiles their
41
- source with Rollup and its TypeScript plugin, then generates ESM facades from the exported
42
- names. Both formats load one CommonJS implementation. This preserves error
43
- class identity and shares the module cache when both preload forms are used.
44
- It follows Node's documented mitigation for the
45
- [dual-package hazard](https://nodejs.org/api/packages.html#dual-commonjs-es-module-packages).
46
-
47
- The CommonJS build preserves the module graph. Source unit specs import their
48
- adjacent modules; higher-level process and clean-consumer checks exercise the
49
- compiled modules and the same archive. Matrix jobs do not recompile TypeScript. Only the
50
- entries in the exports map are public package imports.
51
-
52
- The package has no runtime npm dependencies. Node built-ins remain external;
53
- Rollup does not bundle build tools into the application package. The build
54
- resolves `import.meta.url` to the Node filename in CJS output; browser-like
55
- globals in a Node test environment cannot change it.
56
- [Rollup's external option](https://rollupjs.org/configuration-options/#external)
57
- controls which imports remain outside the bundle.
58
-
59
- The compiler emits declarations into `dist/types/`. Generated `.d.mts` and
60
- `.d.cts` entry facades re-export that shared declaration graph; there is no
61
- handwritten public declaration file or separate declaration-bundler dependency.
62
- The generated package has no `type` field, so its shared `.d.ts` graph describes
63
- the CommonJS implementation. The exports map lists `types` first and selects
64
- the entry facade for the consumer's
65
- module format, as described by
66
- [TypeScript's ESM/CommonJS package guidance](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html).
67
- Consumer compilation checks both formats, including invalid inputs that must
68
- remain type errors.
69
-
70
- Public options use type aliases and readonly properties. `Environment` stays
71
- mutable for optional in-place replacement. `resolve()` always returns a new
72
- `Environment`, with input replacement enabled only by `{ replace: true }`. It
73
- does not preserve a generic input type: resolved strings cannot retain a
74
- literal reference type.
75
- ESLint uses type information and enforces the selected style rules. The compiler
76
- checks all library/CLI source, colocated unit specs and both consumer formats with `strict` and
77
- `noUncheckedIndexedAccess`. Provider responses and parsed worker input start as
78
- `unknown` and are validated before use. Compiler failures stop the build.
79
-
80
- The source target is ES2023. `ES2024.String` supplies the declaration for
81
- `isWellFormed()`, whose availability is also checked by the Node 20/22/24 runtime
82
- tests. Node types match the Node 24 development toolchain; the runtime matrix
83
- remains necessary to detect use of APIs absent from the oldest supported Node.
84
-
85
- ## Generated manifest and packing
86
-
87
- The build removes stale output first. It derives `dist/package.json` from the
88
- root manifest, rebases entry paths, and omits development dependencies, scripts,
89
- overrides and a package-wide `type` field. Explicit `.mjs` and `.cjs` extensions
90
- select the output format. README, the MIT `LICENSE`, contributor/security guides
91
- and docs are copied into the distribution and included in the archive.
92
-
93
- Ordinary local builds retain `private: true`. The CI build accepts a validated
94
- release plan and sets its computed version, removing `private` before the final
95
- archive is packed and tested. The development root stays private. Only the
96
- manual release workflow stages that tested archive for npm approval; see
97
- [releasing](releasing.md).
98
-
99
- `npm run pack:local` packs the generated directory. `npm run test:package`
100
- instead packs into a temporary directory and installs it offline into a clean
101
- consumer. It checks imports, requires, preloads, CLI behavior and declarations;
102
- the consumer cannot load resenv's source files or build dependencies. The
103
- runtime entries from the repository lockfile are used in the consumer lockfile.
104
- Its only direct dependency is the packed archive. An offline `npm ci` verifies
105
- archive integrity and installs the reviewed versions without registry metadata.
106
-
107
- With `npm run test:package -- /path/to/package.tgz`, the same checks inspect
108
- and install the supplied archive without rebuilding it. Its name, version,
109
- manifest and executable mode must match the package contract. CI uses this
110
- form so every platform checks the same built bytes.
111
-
112
- Keep tarballs already consumed by other projects immutable. No existing
113
- consumer artifact is rebuilt in place by these tests.
114
-
115
- ## CI
116
-
117
- The `build` job uses normal npm lifecycle behavior, checks dependency advisories and
118
- signatures, runs typed lint, implementation/spec checks and Vitest source coverage,
119
- builds once and uploads the packed
120
- archive. The `test` matrix downloads that artifact, verifies the installed
121
- package, extracts the same build
122
- for the process tests, and never recompiles it. The matrix checks Node 20
123
- and 22 on Linux plus the `.nvmrc` version on Linux and macOS.
124
-
125
- Build and test jobs have read-only repository permissions and receive no application or
126
- registry secrets. Missing artifacts and digest mismatches fail the run. The
127
- archive is retained for seven days for maintainer review. A separate release
128
- job requires manual dispatch on `beta`, the protected `release` environment and
129
- all candidate checks. Hosted results must be observed before treating the workflow definition
130
- as a passing CI run.
131
-
132
- Official `actions/*` and `github/*` actions use exact release tags under the
133
- repository's GitHub publisher trust policy. Other remote actions require full
134
- commit SHAs. Installs use normal npm lifecycle behavior, and dependency updates
135
- require an install-hook review. Build commands run explicitly.
@@ -1,61 +0,0 @@
1
- # Dependencies
2
-
3
- resenv has no runtime npm dependencies. Build, test and release tools are
4
- development-only and excluded from the consumer archive. Exact versions live
5
- in the [source manifest](https://github.com/ciqol/resenv/blob/beta/package.json);
6
- the lockfile pins their resolved artifacts.
7
-
8
- ## Tool choices
9
-
10
- | Packages | Purpose | License |
11
- | --- | --- | --- |
12
- | `rollup`, `@rollup/plugin-typescript` | Compile TypeScript, preserve the module graph and generate declarations | MIT |
13
- | `typescript` | Strict implementation, spec and consumer type checks | Apache-2.0 |
14
- | `tslib` | Helpers used by the TypeScript build plugin | 0BSD |
15
- | `@types/node` | Node platform types for the pinned development runtime | MIT |
16
- | `eslint`, `typescript-eslint` | Lint source and tooling, including rules that use type information | MIT |
17
- | `vitest`, `@vitest/coverage-v8` | Colocated unit tests and source coverage | MIT |
18
- | `@semantic-release/commit-analyzer`, `@semantic-release/release-notes-generator` | Official Conventional Commit classification and release notes | MIT |
19
-
20
- The [Doppler CLI](doppler.md) is a separately installed authentication helper,
21
- owned and updated by the user. resenv does not download or vendor it. Supplying
22
- `DOPPLER_TOKEN` avoids the CLI dependency.
23
-
24
- ## Installation policy
25
-
26
- Use the Node version in `.nvmrc`, `npm ci` and normal npm lifecycle behavior.
27
- Do not disable scripts globally. Review published install hooks and implicit
28
- native builds when dependencies change. Rollup uses platform-specific optional
29
- binaries; keep the Linux/macOS clean-install checks. The lockfile marks optional
30
- `fsevents` as having an install script, although its reviewed artifact has no
31
- install hook or `binding.gyp`; npm may warn about that metadata.
32
-
33
- The committed `.npmrc` sets `omit=peer`. The two release plugins export the
34
- standalone functions the planner uses, but declare the full `semantic-release`
35
- engine as a peer for their usual integration. Omitting that unused peer also
36
- keeps its npm/GitHub publisher dependency graph off disk. Audit and planning
37
- guards require those modules to be unresolvable from the project and both
38
- plugins. See [release security](release-security.md).
39
-
40
- npm still resolves omitted peers into the lockfile. `npm ls` reports the
41
- deliberately missing engine peers; an audit with `--include=peer` can report
42
- vulnerabilities in those uninstalled entries. Do not conceal the peer warning
43
- with `--force`, `--legacy-peer-deps` or an alias package. Restoring the engine
44
- requires a dependency/security review and a deliberate guard change.
45
-
46
- ## Updating dependencies
47
-
48
- Maintainers own dependency admission and updates. Keep direct versions exact
49
- and review the manifest and lockfile diff, upstream source and release notes,
50
- distributed licenses, provenance, advisories and install hooks. Keep Vitest and
51
- its coverage provider compatible. Changes to release plugins also require
52
- reviewing their standalone exports and executable guards.
53
-
54
- Run `npm ci`, `npm run audit`, `npm audit signatures` and `npm run verify`.
55
- Review hosted matrix checks before release. Record review evidence and check
56
- results in the PR and CI; update this guide only when a lasting choice or
57
- installation requirement changes. Do not append dated intake or test logs.
58
-
59
- Official `actions/*` and `github/*` actions use exact release tags under the
60
- repository's GitHub publisher trust policy. Other remote actions require full
61
- commit SHAs. Review action source, permissions and license when updating them.
package/docs/doppler.md DELETED
@@ -1,155 +0,0 @@
1
- # Doppler references and CLI authentication
2
-
3
- Doppler is resenv's only built-in cloud provider. After Nx or another loader
4
- populates the environment, resenv fetches referenced values through HTTPS and
5
- replaces them in memory before application startup. It resolves once per startup;
6
- restart the application to fetch changed secrets. This mode does not execute
7
- shell commands.
8
- The canonical `--require @ciqol/resenv/resolve` preload infers Doppler from
9
- `doppler://` values. The equivalent `--import` and `resenv run -- ...` do the
10
- same. The library also infers Doppler from values; call `resolve()` without
11
- a provider option. `resolve-doppler` and
12
- `run --doppler` remain supported for compatibility.
13
-
14
- ## Local setup
15
-
16
- After [installing resenv](../README.md#install) in your application project,
17
- install the [official Doppler CLI](https://docs.doppler.com/docs/cli) and run
18
- this from the application's directory:
19
-
20
- ```sh
21
- doppler login
22
- ```
23
-
24
- Doppler owns browser authorization, token persistence, login scopes and logout.
25
- Use `doppler logout` to manage the CLI login. resenv never opens a browser,
26
- prompts for login, issues or revokes tokens, or reads or writes the OS
27
- credential store directly. There is no separate resenv login.
28
-
29
- Existing Doppler users can reuse their login. resenv asks the CLI for the token
30
- selected by its current working directory, so Doppler's directory-scoped
31
- workplace identities continue to apply. See
32
- [Doppler's scope guide](https://docs.doppler.com/docs/multiple-workplaces).
33
- `doppler setup` is not required for resenv references: their project and config
34
- are already explicit in each `doppler://` value. Nx or the caller remains
35
- responsible for dotenv file loading.
36
-
37
- ### Platforms and installation locations
38
-
39
- The CLI handles its own credential storage on macOS, Linux and Windows. resenv
40
- does not require `secret-tool`, a separate keyring package or native Node addons.
41
- It discovers the CLI in these standard locations:
42
-
43
- | Platform | Locations, in lookup order |
44
- | --- | --- |
45
- | macOS / Linux | `/opt/homebrew/bin/doppler`, `/usr/local/bin/doppler`, `/usr/bin/doppler`, `~/.local/bin/doppler`, `~/bin/doppler` |
46
- | Windows | `~/AppData/Local/Microsoft/WinGet/Links/doppler.exe`, `~/scoop/apps/doppler/current/doppler.exe` |
47
-
48
- Here `~` is the OS user's home directory. Windows paths cover default per-user
49
- WinGet and Scoop installations. Custom and system-wide Windows installations
50
- outside these locations need an explicit `DOPPLER_TOKEN`. WSL uses the Linux
51
- installation and login within WSL. The runtime deliberately ignores the
52
- application's `PATH` so a repository-local executable cannot replace the
53
- credential helper.
54
-
55
- Windows discovery is covered with injected process tests; a native Windows
56
- end-to-end run is not yet verified. Automated checks never use a developer's
57
- Doppler login or OS credential store.
58
-
59
- ### Migration from resenv-managed login
60
-
61
- `resenv login` and `resenv logout` have been removed. Run `doppler login` to
62
- establish the CLI identity, then start the application normally. Earlier resenv
63
- credentials stored under service `ciqol.envref.doppler`, account `default`, are
64
- ignored and are not migrated or deleted automatically. If you used that flow,
65
- remove the obsolete entry through your OS credential manager and revoke the
66
- obsolete token in Doppler when it is no longer needed.
67
-
68
- ## Declare a reference
69
-
70
- Put references in the dotenv file Nx already selects, such as `.env.serve`:
71
-
72
- ```dotenv
73
- API_TOKEN=doppler://my-project/dev/API_TOKEN
74
- ```
75
-
76
- This is **resenv's own syntax**, not an official Doppler URI standard or
77
- SecretSpec's provider URI. All three fields are required: project, config and
78
- secret name. Project/config slugs must be lowercase letters, digits, `_` or
79
- `-`. Secret names can use Doppler's permissive punctuation; percent encoding
80
- is accepted for a secret name, such as `payments%2Fapi.key`. Query strings,
81
- fragments, credentials, ports and executable expressions are rejected.
82
-
83
- For an Nx Node target, put the preload on the application process:
84
-
85
- ```json
86
- "runtimeArgs": ["--require", "@ciqol/resenv/resolve"]
87
- ```
88
-
89
- For an Nx command target, use `resenv run -- node app.mjs` inside the
90
- target. Preloading the outer Nx process would run before Nx loads target files.
91
- resenv does not choose, read or rewrite dotenv files.
92
-
93
- ## Runtime credential lookup
94
-
95
- Resolution checks these sources in order:
96
-
97
- 1. An explicitly supplied `DOPPLER_TOKEN`.
98
- 2. The current directory's existing Doppler CLI login, retrieved with the
99
- documented `doppler configure get token --plain` operation.
100
-
101
- resenv captures the token internally and fetches secrets through HTTPS; it does
102
- not parse the CLI's private config format. The command uses a fixed executable,
103
- separate arguments, `--no-check-version` and `--no-read-env`, with a restricted
104
- environment. It inherits the application's working directory to preserve login
105
- scopes. Lookup has a fifteen-second timeout and a 16 KiB output limit. Captured
106
- output and helper errors are never forwarded to application logs.
107
-
108
- If the CLI is missing, install it in a supported location and run `doppler login`,
109
- or supply `DOPPLER_TOKEN`. A failed or empty CLI lookup reports that login is
110
- required. An explicitly supplied invalid token, malformed CLI token, access
111
- denial or network failure stops the operation without switching identities or
112
- starting login.
113
-
114
- In CI, containers and other unattended environments, supply a suitably scoped
115
- `DOPPLER_TOKEN` through the runner's secret facility. No CLI installation or
116
- local credential store is needed in that mode. Changing the CLI login affects
117
- the next application startup; resenv does not keep a persistent token cache.
118
-
119
- ## Resolution and security boundaries
120
-
121
- - Fetches only named secrets from the public retrieve-secret endpoint. Repeated
122
- references share one request per startup; values are not cached on disk.
123
- - Requires the computed value. Restricted, missing, null and invalid values
124
- fail startup; resenv never substitutes a raw value as a fallback.
125
- - Keeps fetched output literal, including strings that start with `encrypted:`
126
- or contain `$()`. Neither fetched nor original ciphertext is decrypted.
127
- - Resolves everything before applying changes. A failure leaves the caller's
128
- environment untouched. Existing command mode remains separately opt-in.
129
- - Uses a fixed HTTPS origin, disables redirects, and has a ten-second timeout
130
- per request. The synchronous preload uses a private Node worker with a
131
- sixty-second overall limit. Up to four distinct lookups run concurrently;
132
- duplicate references share one lookup. After a failure, no new lookups are
133
- scheduled and active requests settle before failure is returned. Limits are
134
- 128 references, 64 KiB per value and
135
- 1 MiB for each response and the worker's captured output.
136
- - Preloads use a child Node process to wait for asynchronous HTTPS while
137
- retaining `--require` compatibility. It receives only references and an
138
- explicit credential through stdin, with results returned through a private
139
- pipe. No Doppler CLI is required when `DOPPLER_TOKEN` is supplied.
140
- - Diagnostics show variable names and error codes, never tokens, provider
141
- response bodies, CLI output or resolved values.
142
-
143
- This removes shell evaluation from Doppler lookups. It does not isolate
144
- untrusted repository code or agents that can access the same user's credential
145
- store. Doppler account permissions remain the authorization boundary. CLI user
146
- tokens inherit the user's privileges; a read-only service token can limit CI
147
- to a specific config.
148
-
149
- ## Sources
150
-
151
- - [Doppler CLI installation and authentication](https://docs.doppler.com/docs/cli)
152
- - [Directory-scoped workplace logins](https://docs.doppler.com/docs/multiple-workplaces)
153
- - [Retrieve a secret](https://docs.doppler.com/reference/secrets-get)
154
- - [API authentication](https://docs.doppler.com/reference/api)
155
- - [Retrieve the CLI token](https://docs.doppler.com/docs/cli#fetch-cli-token-from-your-local-environment)
@@ -1,39 +0,0 @@
1
- # Maintainer guide
2
-
3
- Start with [AGENTS.md](https://github.com/ciqol/resenv/blob/beta/AGENTS.md) for repository policy and
4
- [CONTRIBUTING.md](../CONTRIBUTING.md) for setup and verification. Work in an
5
- isolated task worktree on a `titan/*` branch. Authenticate as `titan-ron` for
6
- [ciqol/resenv](https://github.com/ciqol/resenv); `beta` is the default and sole
7
- release branch.
8
-
9
- Inspect current Git status, branches, push remote and recent commits before
10
- editing. Read live GitHub checks, releases and npm metadata before release
11
- work; old chat messages or check results are not authoritative. Never copy
12
- credentials between sessions.
13
-
14
- | Guide | Maintained information |
15
- | --- | --- |
16
- | [README](../README.md) | Application installation, API and CLI usage |
17
- | [Doppler](doppler.md) | CLI authentication, lookup, migration and platform limits |
18
- | [Build](build.md) | Module formats, declarations, archive and CI contract |
19
- | [Dependencies](dependencies.md) | Tool rationale, installation and update policy |
20
- | [Releasing](releasing.md) | Candidate checks, npm staging/approval and recovery |
21
- | [Release security](release-security.md) | Isolation guards, advisory policy and platform review deadline |
22
- | [Security](../SECURITY.md) | Trust boundaries and private vulnerability reporting |
23
-
24
- ## Code map
25
-
26
- | Path | Responsibility |
27
- | --- | --- |
28
- | `src/index.ts` | Resolution API and atomic environment replacement |
29
- | `src/preload.ts`, `src/resolve*.ts` | Startup integration and shared preload state |
30
- | `src/doppler/` | References, HTTPS, concurrency and CLI credential lookup |
31
- | `src/commands.ts` | Explicit shell substitution and process limits |
32
- | `bin/resenv.ts` | Child-process CLI |
33
- | `rollup.config.mjs`, `scripts/build.mjs` | CJS implementation, ESM facades, types and manifest |
34
- | `scripts/release-plan.mjs` | Official release plugins and beta counter |
35
- | `scripts/publish.mjs` | Tested-archive staging and verified release recording |
36
- | `.github/workflows/ci.yml` | Build once, archive matrix tests and manual release |
37
-
38
- Keep docs focused on current contracts, decisions and procedures. Put per-run
39
- test results, benchmarks, audit snapshots and session history in PRs or CI.
@@ -1,70 +0,0 @@
1
- # Release-tool security
2
-
3
- Maintainer: `titan-ron`. Runtime dependencies have no advisory exceptions.
4
- The executable development policy is [security-exceptions.json](security-exceptions.json).
5
- Its review expires **November 9, 2026 at 00:00 UTC**. This is a project review
6
- deadline, also enforced by the publisher for platform npm; removing unused
7
- development tools does not extend it.
8
-
9
- ## Release planning
10
-
11
- The planner calls the official commit-analysis and release-notes plugins
12
- directly. It reads Git history and published beta tags without GitHub write,
13
- npm or OIDC credentials. The full `semantic-release` engine and its publishing
14
- plugins are unnecessary for this beta-only workflow.
15
-
16
- The committed peer-omission policy keeps the engine, `@semantic-release/npm`,
17
- `@semantic-release/github` and their npm module off disk. Before auditing or
18
- planning, `scripts/release-guards.mjs` requires that none resolve from the
19
- project or either selected plugin. Its planner hook also rejects bare and
20
- resolved imports of those tools. An audit explicitly including omitted peers
21
- can still report their locked entries; see [installation policy](dependencies.md).
22
-
23
- The guard pins both plugins, micromatch and braces. It replaces every callable
24
- braces export with a throwing guard before loading the plugins. The selected
25
- micromatch matching calls use picomatch; vulnerable brace expansion must never
26
- execute. Version drift fails until the guards are reviewed.
27
-
28
- `npm run audit` checks runtime dependencies without exceptions, then the
29
- installed development tree. Moderate/high/critical findings must match an exact
30
- advisory URL, development-only lockfile path, version and unexpired policy
31
- entry. New advisories, changed paths, runtime occurrences and expired
32
- exceptions fail. The retained exception entries do not authorize reinstalling
33
- the excluded tools. Prefer an upstream fix or removing unused dependencies;
34
- never broaden the policy to make a check pass.
35
-
36
- ## Publishing platform
37
-
38
- The privileged publisher installs no release-tool dependencies and accepts only
39
- the archive described by the verified candidate plan. It checks source identity
40
- and hashes before invoking npm. Publication follows the [release runbook](releasing.md).
41
-
42
- The platform is pinned to Node.js 24.19.0 and its npm 11.17.0. Platform npm has
43
- separately reviewed bundled-component risks; omitting development peers does
44
- not fix those components. `scripts/publish.mjs` rejects platform version drift
45
- and an expired review, including on a failed-job retry.
46
-
47
- The staging command accepts a fixed tarball and HTTPS npm registry, with no
48
- package lifecycle scripts in the generated manifest. It runs with a fresh home,
49
- configuration and cache, strips proxy/token/arbitrary npm configuration, and
50
- uses the protected workflow's OIDC identity. It accepts no login, shell,
51
- selector or arbitrary URL input. Registry and signing services remain trusted
52
- inputs. These controls bound exposure; they do not patch the platform CLI.
53
-
54
- The publisher validates the staging receipt's package name, version and
55
- integrity. npm approval publishes the stage. A retry verifies the public
56
- archive's integrity and both npm tags before recording the Git tag/release.
57
- No tag is created for a pending stage.
58
-
59
- ## Reviewing changes
60
-
61
- Review the actual published artifacts, including bundled copies; patching a
62
- standalone package does not establish that npm's bundled copy is fixed.
63
- Recheck platform npm before the deadline and remove obsolete exception entries
64
- when upstream fixes or dependency removal make them unnecessary. Do not extend
65
- the deadline or bypass executable controls to unblock publication.
66
-
67
- Run `npm run audit`, `npm audit signatures` and `npm run verify`. Release tooling
68
- specs cover absence/version guards, policy scope and expiry, adversarial commit
69
- analysis, real Git release history and publisher isolation. Keep review evidence
70
- in the PR and CI, and maintain this document as the current policy.
package/docs/releasing.md DELETED
@@ -1,154 +0,0 @@
1
- # Releases
2
-
3
- ## Versions
4
-
5
- `beta` is the sole release and default branch. Releases start at `0.1.0-beta.1`
6
- and use npm tags `beta` and `latest`, both pointing to the same tested beta.
7
-
8
- The planner uses semantic-release's official commit-analysis and release-notes
9
- plugins. Conventional Commits decide whether changes need a release. Each
10
- releasable update increments the counter from the latest reachable
11
- `v0.1.0-beta.N` tag; docs-only changes do not release. Breaking changes during
12
- this experimental line also increment the beta counter. Selecting a stable
13
- line or another base version is a separate release-policy change.
14
-
15
- The full semantic-release engine requires a normal release branch and defaults
16
- to a first version of 1.0.0. Using its official plugins directly preserves the
17
- requested sole-beta-branch setup without inventing a stable branch or a release
18
- that never happened. The base line is declared in `release.config.mjs`.
19
-
20
- The development manifest and ordinary local builds stay private. Only a valid
21
- release plan sets the distribution version and removes `private` before packing.
22
- Never edit a generated manifest or overwrite a previously shared archive.
23
-
24
- ## CI pipeline
25
-
26
- The [CI workflow](https://github.com/ciqol/resenv/blob/beta/.github/workflows/ci.yml) builds one archive:
27
-
28
- 1. **Build:** normal npm installation, runtime/development audits, registry
29
- signatures, lint, strict types and colocated Vitest specs. The read-only
30
- planner generates the beta version and notes from Git history. Rollup builds
31
- it once; npm packs it and records SHA-256 and SHA-512 integrity.
32
- 2. **Consumers:** Linux Node 20, 22 and the pinned Node 24, plus macOS Node 24,
33
- install and test the same archive. Checks cover ESM, CJS, types, preloads,
34
- CLI, literal secret output and failure boundaries. Nothing is rebuilt.
35
- 3. **Release:** a manual dispatch from `beta` with `publish: true`, after every
36
- check passes. The protected job verifies hashes, workflow identity and the
37
- current branch head. It installs no project dependencies and runs no package
38
- code. `npm stage publish` submits the exact archive through OIDC with
39
- provenance and the explicit `beta` tag. The job validates and saves npm's
40
- staging receipt; no Git tag or GitHub release is created yet.
41
- 4. **Approval and recording:** the maintainer reviews and approves the staged
42
- package in npm using interactive 2FA. Wait for npm to make it available,
43
- update `latest` to the approved version, then rerun the original release job.
44
- It verifies the published integrity against the original tested archive and
45
- requires npm tags `beta` and `latest` to point to that version before creating
46
- its Git tag and GitHub prerelease. It does not stage or publish the package again.
47
-
48
- Pushes, PRs and dispatches with `publish: false` cannot stage a package. Release
49
- jobs are serialized and not cancelled. Artifacts last seven days. A fresh
50
- workflow run is not a substitute for rerunning the original release job when
51
- recovering an already staged/published candidate.
52
-
53
- ## Required setup
54
-
55
- The existing npm trusted publisher must match:
56
-
57
- | Field | Value |
58
- | --- | --- |
59
- | Provider | GitHub Actions |
60
- | Organization | `ciqol` |
61
- | Repository | `resenv` |
62
- | Workflow filename | `ci.yml` |
63
- | Environment | `release` |
64
- | Permission | `npm stage publish` |
65
-
66
- No permanent npm token or direct-publish permission is needed. The pinned
67
- Node 24.19.0/npm 11.17.0 platform includes staged publishing. New trusted
68
- publisher configurations must be validated by a successful CI operation before
69
- the deadline shown in npm settings.
70
-
71
- The GitHub environment `release` accepts only the `beta` branch and has no
72
- required GitHub reviewers. CI submits staged packages; the maintainer approves
73
- publication in npm. After reading back the branch policy and verifying npm
74
- setup, set Actions variable `RELEASE_ENABLED=true`. Leave it unset until then
75
- to prevent a dispatch from creating an unrestricted environment automatically.
76
- Environment creation or protection changes require explicit authorization.
77
-
78
- ## Run a beta release
79
-
80
- Open [CI](https://github.com/ciqol/resenv/actions/workflows/ci.yml), choose
81
- **Run workflow**, select `beta`, and enable the staging input. When build and
82
- consumer checks pass, the release job stages the archive without another GitHub
83
- approval. Its summary and the `resenv-stage` artifact contain the stage
84
- identifier and tested integrity.
85
-
86
- Review the staged package in npm, then approve it with the stage identifier:
87
-
88
- ```sh
89
- npm stage view <stage-id> --json
90
- npm stage approve <stage-id>
91
- ```
92
-
93
- These are maintainer review/approval commands; the archive is built and staged
94
- by GitHub Actions. OIDC cannot perform the approval step. Wait for npm scanning
95
- and public availability, then update the default install tag in the maintainer
96
- session:
97
-
98
- ```sh
99
- npm dist-tag add @ciqol/resenv@<approved-version> latest
100
- ```
101
-
102
- Rerun the original release job to record the release. Verify the npm version,
103
- `beta` and `latest` tags, archive integrity, provenance and GitHub
104
- prerelease. Never infer success from a staging receipt alone.
105
-
106
- For a hosted rehearsal, leave the staging input off. Local verification is:
107
-
108
- ```sh
109
- npm ci
110
- npm run audit
111
- npm run release:check
112
- ```
113
-
114
- None of these commands publishes. The planner can generate a non-publishing
115
- plan with `node scripts/release-plan.mjs /absolute/path/to/candidate-directory`.
116
-
117
- ## Recovery and old versions
118
-
119
- A failed stage operation creates no Git tag or GitHub release. Check npm before
120
- retrying an ambiguous outcome: a staged version reserves its version number.
121
- Do not attempt to stage it again while awaiting approval. Approve or reject the
122
- existing stage through npm. Rejection requires a reviewed replacement candidate.
123
-
124
- The original release job accepts an existing public version only if integrity
125
- matches its candidate. A conflicting archive, changed beta head or conflicting
126
- Git tag stops recovery. Keep the beta branch at the reviewed commit until the
127
- release is recorded. If its artifact expires, review recovery separately.
128
-
129
- Retain the `0.0.0-stage` placeholder until a functional beta is publicly
130
- available and verified.
131
- With explicit authorization, remove that exact placeholder version and check
132
- remaining versions and tags. Never unpublish the whole package. npm's unpublish
133
- policy still applies; deleted versions cannot be reused.
134
- See [npm's policy](https://docs.npmjs.com/policies/unpublish/).
135
-
136
- ## Security and platform limits
137
-
138
- The runtime package has no npm dependencies or advisory exceptions. Installed
139
- runtime and development audits must pass with the unused engine/publisher peer graph
140
- omitted. Audit and planning enforce that absence; the lockfile still records
141
- the uninstalled peers. The existing November 9, 2026 review deadline remains
142
- for the policy and separately reviewed platform npm. The privileged job does
143
- not install release-tool modules. See [release security](release-security.md).
144
-
145
- Doppler is the only built-in cloud provider. Authentication is owned by the
146
- Doppler CLI; resenv reads its existing directory-scoped token or accepts
147
- `DOPPLER_TOKEN` for unattended use. It does not manage native credential storage
148
- or browser login. Standard Windows CLI discovery has injected coverage but no
149
- native Windows end-to-end verification. Commands require explicit opt-in.
150
- Dotenvx ciphertext is left unchanged. See [Security](../SECURITY.md).
151
-
152
- Sources: [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/),
153
- [staged publishing](https://docs.npmjs.com/cli/v11/commands/npm-stage/),
154
- [semantic-release branching](https://semantic-release.org/foundation/workflow-configuration/).
@@ -1,139 +0,0 @@
1
- {
2
- "expires": "2026-11-09T00:00:00.000Z",
3
- "owner": "titan-ron",
4
- "scope": "Release planning only; runtime audit has no exceptions.",
5
- "exceptions": [
6
- {
7
- "advisory": "https://github.com/advisories/GHSA-q2hr-2g5m-vwhr",
8
- "package": "brace-expansion",
9
- "versions": [
10
- "5.0.9"
11
- ],
12
- "nodes": [
13
- "node_modules/npm/node_modules/brace-expansion"
14
- ],
15
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
16
- },
17
- {
18
- "advisory": "https://github.com/advisories/GHSA-qhr7-859c-m2p7",
19
- "package": "brace-expansion",
20
- "versions": [
21
- "5.0.9"
22
- ],
23
- "nodes": [
24
- "node_modules/npm/node_modules/brace-expansion"
25
- ],
26
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
27
- },
28
- {
29
- "advisory": "https://github.com/advisories/GHSA-6j4f-fj2g-mc7p",
30
- "package": "brace-expansion",
31
- "versions": [
32
- "5.0.9"
33
- ],
34
- "nodes": [
35
- "node_modules/npm/node_modules/brace-expansion"
36
- ],
37
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
38
- },
39
- {
40
- "advisory": "https://github.com/advisories/GHSA-vfj7-8cjw-p6xm",
41
- "package": "braces",
42
- "versions": [
43
- "3.0.3"
44
- ],
45
- "nodes": [
46
- "node_modules/braces"
47
- ],
48
- "reason": "The planner blocks every braces callable and only uses micromatch matching, which delegates to picomatch."
49
- },
50
- {
51
- "advisory": "https://github.com/advisories/GHSA-ch52-4w7c-c8xp",
52
- "package": "http-cache-semantics",
53
- "versions": [
54
- "4.2.0"
55
- ],
56
- "nodes": [
57
- "node_modules/npm/node_modules/http-cache-semantics"
58
- ],
59
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
60
- },
61
- {
62
- "advisory": "https://github.com/advisories/GHSA-rpw4-54j3-4h4q",
63
- "package": "ip-address",
64
- "versions": [
65
- "10.5.0"
66
- ],
67
- "nodes": [
68
- "node_modules/npm/node_modules/ip-address"
69
- ],
70
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
71
- },
72
- {
73
- "advisory": "https://github.com/advisories/GHSA-2vr4-cq9g-pvrc",
74
- "package": "ip-address",
75
- "versions": [
76
- "10.5.0"
77
- ],
78
- "nodes": [
79
- "node_modules/npm/node_modules/ip-address"
80
- ],
81
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
82
- },
83
- {
84
- "advisory": "https://github.com/advisories/GHSA-j6r3-76f7-8jcv",
85
- "package": "ip-address",
86
- "versions": [
87
- "10.5.0"
88
- ],
89
- "nodes": [
90
- "node_modules/npm/node_modules/ip-address"
91
- ],
92
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
93
- },
94
- {
95
- "advisory": "https://github.com/advisories/GHSA-h3mg-xc3c-68pw",
96
- "package": "ip-address",
97
- "versions": [
98
- "10.5.0"
99
- ],
100
- "nodes": [
101
- "node_modules/npm/node_modules/ip-address"
102
- ],
103
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
104
- },
105
- {
106
- "advisory": "https://github.com/advisories/GHSA-rj75-hqrm-r3gf",
107
- "package": "postcss-selector-parser",
108
- "versions": [
109
- "7.1.4"
110
- ],
111
- "nodes": [
112
- "node_modules/npm/node_modules/postcss-selector-parser"
113
- ],
114
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
115
- },
116
- {
117
- "advisory": "https://github.com/advisories/GHSA-3wwx-pv8p-q78v",
118
- "package": "undici",
119
- "versions": [
120
- "6.28.0"
121
- ],
122
- "nodes": [
123
- "node_modules/npm/node_modules/undici"
124
- ],
125
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
126
- },
127
- {
128
- "advisory": "https://github.com/advisories/GHSA-rfgv-xxqx-mfg5",
129
- "package": "undici",
130
- "versions": [
131
- "6.28.0"
132
- ],
133
- "nodes": [
134
- "node_modules/npm/node_modules/undici"
135
- ],
136
- "reason": "Bundled inside npm for the unselected @semantic-release/npm plugin. The planner blocks loading that plugin, the GitHub plugin and bundled npm; the publisher does not install release dependencies."
137
- }
138
- ]
139
- }