@ciqol/resenv 0.1.0-beta.1 → 0.1.0

package/CONTRIBUTING.md

@@ -1,18 +1,16 @@
 # Contributing
 
 Starting a new session? Read the [maintainer handoff](docs/maintainer-handoff.md)
-and [repository instructions](https://github.com/ciqol/resenv/blob/beta/AGENTS.md) before editing or releasing.
+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.
 
-Releases start at `0.1.0-beta.1` on the sole branch `beta`, using npm channel
-`beta`. Semantic-release's official commit-analysis and release-notes plugins
-select releasable changes and generate notes; actual beta tags supply the next
-prerelease counter. The root and ordinary local builds remain private prototypes.
-CI generates the publishable manifest before packing and testing it, then stages
-the exact archive through npm OIDC for maintainer approval. See
-[releasing](docs/releasing.md) and the bounded [release-tool review](docs/release-security.md).
+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
@@ -25,6 +23,14 @@ 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`.
@@ -60,14 +66,27 @@ shipping them in JavaScript or declarations. Do not maintain separate handwritte
 ```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 and lcov output
+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
-helpers, browser launchers and process control in unit tests. Keep checks that
-spawn actual commands or temporary applications in `test/`. The unit coverage
+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
@@ -87,6 +106,8 @@ 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.
 
@@ -109,7 +130,7 @@ 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-beta.1.tgz
+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
@@ -127,22 +148,20 @@ 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.
-If you only created the package link, run its CLI directly:
+Authenticate with the official Doppler CLI from the application's directory:
 
 ```sh
-node node_modules/@ciqol/resenv/bin/resenv.cjs login doppler
+doppler login
 ```
 
-For login from the resenv checkout, use
-`node dist/bin/resenv.cjs login doppler`. Real login is a manual integration
-check; automated tests must use injected or mocked credentials.
+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.
-See [the review](docs/security-performance-review.md) for the recorded comparison.
 
 With an existing Nx installation:
 
@@ -168,7 +187,8 @@ 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`.
-Dependency changes require an updated [review record](docs/dependencies.md).
+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
@@ -177,6 +197,8 @@ 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

package/README.md

@@ -20,45 +20,60 @@ 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.
 
-Requires Node.js 20 or later. This is an experimental beta, currently distributed
-as a package archive; it has not been published to npm.
+Requires Node.js 20 or later. The package is experimental and remains in initial
+development; its API may change between 0.x releases.
+
+Background: [A new Git worktree shouldn't mean another copy of your secrets](https://dev.to/titanron/a-new-git-worktree-shouldnt-mean-another-copy-of-your-secrets-424).
 
 ## Install
 
-Install the archive supplied by the maintainer in your application project:
+Install in your application project:
 
 ```sh
-npm install --save-exact /path/to/ciqol-resenv-0.1.0-beta.1.tgz
+npm install --save-exact @ciqol/resenv
 ```
 
-This records resenv in your project's manifest and lockfile. Keep the archive
-available wherever that project installs dependencies. Once the beta is
-published to npm, you will be able to install `@ciqol/resenv@beta` instead.
+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.
 
 ## 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
 
-After installing the package, run:
+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:
 
 ```sh
-npx --no-install resenv login doppler
+doppler login
 ```
 
-Each developer authenticates with their own Doppler access. Secret reads use
-the HTTPS API. Credentials come from `DOPPLER_TOKEN`, the saved OS credential,
-or an existing Doppler CLI login, in that order. Startup reports missing access
-and stops; it does not open a login prompt.
+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.
 
-Native login uses the browser flow observed in Doppler's official MCP client
-and saves the token in macOS Keychain or Linux Secret Service. The CLI is a
-fallback; the browser protocol is not a public OAuth contract and fresh native
-login is not yet verified end to end. Windows needs `DOPPLER_TOKEN` because
-native login/storage is not implemented there. See
-[Doppler login and platform details](docs/doppler.md).
+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.
 
 ### 2. Declare references in the environment your app already loads
 
@@ -94,7 +109,8 @@ 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.
+SIGHUP to that child. On POSIX, the child runs in its own session so terminal
+signals reach it only through the wrapper.
 
 ## Nx integration
 

package/SECURITY.md

@@ -9,22 +9,24 @@ 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 token, resenv's OS credential store or a fixed Doppler CLI
-helper. An API rejection never triggers a switch to another identity. Native
-browser login uses endpoints observed in Doppler's official MCP client rather
-than a public third-party OAuth contract. See [Doppler details](docs/doppler.md)
-for fallback rules, credential scope and platform limits.
+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; the separate login command rejects CI and
-noninteractive sessions.
+Startup does not initiate login. Use `doppler login` separately for local
+development or supply a suitably scoped token for unattended runs.
 
-The local credential store does not prevent code running as the same user from
-requesting credentials. resenv does not automatically remove an explicitly
-supplied `DOPPLER_TOKEN` from the application environment. Interactive login
-displays a temporary human authorization code; tokens and the polling code are
-not logged. The Node preload's private worker exchanges credentials and results
-over captured pipes, never process arguments or dotenv files.
+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
@@ -57,17 +59,15 @@ 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. Validation
-evidence and platform limits are recorded in [docs/validation.md](docs/validation.md).
+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. Open the repository's Security tab and use "Report a vulnerability"
-when available. If that option is unavailable, contact the maintainer through
-an existing private channel. Before the public transition is complete,
-maintainers must enable GitHub private vulnerability reporting and verify that
-it is available.
+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.

package/bin/resenv.cjs

@@ -6,32 +6,15 @@ var node_os = require('node:os');
 var assertSafeDiagnostics = require('../assert-safe-diagnostics.cjs');
 var preload = require('../preload.cjs');
 var index = require('../index.cjs');
-var auth = require('../doppler/auth.cjs');
-var system = require('../doppler/system.cjs');
-var references = require('../doppler/references.cjs');
 var values = require('../values.cjs');
 
-const usage = 'Usage: resenv run [--commands] -- <command> [arguments...]\n       resenv login [doppler] [--cli] [--no-browser]\n       resenv logout doppler\nInfer secret providers from values already in the environment.\n--doppler remains accepted for compatibility.\n--commands enables whole-value $(command) expressions using /bin/sh.\n';
-async function main() {
+const usage = 'Usage: resenv run [--commands] -- <command> [arguments...]\nInfer secret providers from values already in the environment.\nManage authentication with doppler login and doppler logout, or supply DOPPLER_TOKEN.\n--doppler remains accepted for compatibility.\n--commands enables whole-value $(command) expressions using /bin/sh.\n';
+function main() {
     const args = process.argv.slice(2);
     if (args.length === 1 && ['--help', '-h'].includes(args[0] || '')) {
         process.stdout.write(usage);
         return;
     }
-    const explicitProvider = args[1] === 'doppler';
-    if (args[0] === 'login' && args.slice(explicitProvider ? 2 : 1).every(arg => ['--cli', '--no-browser'].includes(arg))) {
-        if (!explicitProvider && !references.references(process.env).length) {
-            process.stderr.write('Nothing to handle: no cloud secret references in the environment. Load your target environment first, or use resenv login doppler.\n');
-            return;
-        }
-        await auth.login({ cli: args.includes('--cli'), noBrowser: args.includes('--no-browser') });
-        return;
-    }
-    if (args.length === 2 && args[0] === 'logout' && args[1] === 'doppler') {
-        system.createSystem().remove();
-        process.stderr.write('Removed the resenv credential. Doppler CLI credentials and DOPPLER_TOKEN are unchanged; revoke the token in Doppler to invalidate it.\n');
-        return;
-    }
     let commands = false;
     while (args[0] === 'run' && ['--commands', '--doppler'].includes(args[1] || '')) {
         if (args[1] === '--commands')
@@ -55,11 +38,23 @@ async function main() {
         return;
     }
     assertSafeDiagnostics.assertSafeDiagnostics();
-    const child = node_child_process.spawn(command, commandArgs, { env, stdio: 'inherit', shell: false });
+    // Isolate the child from terminal group signals; the wrapper forwards them once.
+    const child = node_child_process.spawn(command, commandArgs, { env, stdio: 'inherit', shell: false, detached: process.platform !== 'win32' });
     const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
     const handlers = new Map();
     for (const signal of signals) {
-        const handler = () => { child.kill(signal); };
+        const handler = () => {
+            try {
+                if (process.platform !== 'win32' && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch (err) {
+                if (!values.hasErrorCode(err, 'ESRCH'))
+                    throw err;
+            }
+        };
         handlers.set(signal, handler);
         process.on(signal, handler);
     }
@@ -85,7 +80,10 @@ async function main() {
         }
     });
 }
-void main().catch(err => {
+try {
+    main();
+}
+catch (err) {
     process.stderr.write(`${index.formatError(err)}\n`);
     process.exitCode = 1;
-});
+}

package/docs/build.md

@@ -71,7 +71,7 @@ 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. This intentionally tightens the unpublished API.
+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
@@ -90,11 +90,11 @@ 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 builds retain `private: true`. The CI build accepts a validated
-release plan and sets its computed version, removing `private` before the final
-archive is packed and tested. The development root stays private. Earlier
-builds kept both manifests private while the package was an unpublished
-prototype. There is no publishing workflow.
+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
@@ -114,23 +114,26 @@ consumer artifact is rebuilt in place by these tests.
 
 ## CI
 
-The `build` job uses normal npm lifecycle behavior, checks dependency advisories and
-signatures, runs typed lint, implementation/spec checks and Vitest source coverage,
-builds once and uploads the packed
-archive. The `test` matrix downloads that artifact, verifies the installed
-package, extracts the same build
-for the process tests, and never recompiles it. The matrix checks Node 20
-and 22 on Linux plus the `.nvmrc` version on Linux and macOS.
-
-Jobs have read-only repository permissions and receive no application or
-registry secrets. Missing artifacts and digest mismatches fail the run. The
-archive is retained for seven days for maintainer review. The workflow has no
-publish or deploy step. Hosted results must be observed before treating the
-workflow definition as a passing CI run.
-
-Checkout and setup/download actions use full commit pins. The GitHub-owned
-upload action uses the Tashtit exception for a complete release tag; major tags
-and third-party movable refs are not permitted. Installs use normal npm lifecycle
-behavior, and dependency updates require an install-hook review. Build commands
-run explicitly.
-See the [maturity evaluation](maturity.md) for the static catalog results.
+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.