@stacksjs/env 0.74.69 → 0.74.70

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './runtime';
 export * from './deployment';
+export * from './integrations';
 export * from './types';
 export * from './crypto';
 export * from './parser';

package/dist/index.js

@@ -1 +1 @@
-export*from"./runtime";export*from"./deployment";export*from"./types";export*from"./crypto";export*from"./parser";export*from"./plugin";export*from"./cli";export*from"./plaintext";export*from"./tenants";export*from"./utils";
+export*from"./runtime";export*from"./deployment";export*from"./integrations";export*from"./types";export*from"./crypto";export*from"./parser";export*from"./plugin";export*from"./cli";export*from"./plaintext";export*from"./tenants";export*from"./utils";

package/dist/integrations.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Fold the spellings that mean the same deployment onto one name, so an
+ * allowlist of `['prod']` admits `APP_ENV=production` and the reverse.
+ *
+ * Only these three aliases, and only exact matches. `local`, `development` and
+ * `test` are deliberately **not** folded together: they are three different
+ * places with three different reasons to be excluded, and a framework that
+ * quietly treated them as one would make "allow my machine" also mean "allow
+ * CI". `@stacksjs/env`'s own loader normalizes the same three aliases when it
+ * picks an `.env` file to read.
+ */
+export declare function normalizeEnvironmentName(value: string | undefined | null): string | undefined;
+/**
+ * The environment an integration should gate on, or `undefined` when nothing
+ * declared one.
+ *
+ * Read at call time rather than at import: `APP_ENV` is routinely set after the
+ * module graph loads - a test harness pinning it, a CLI resolving `--env` - and
+ * a const would freeze whatever happened to be set first (stacksjs/stacks#2581).
+ *
+ * Unlike `appEnv()`, which answers `local` so callers always have a string, this
+ * answers `undefined`. The difference matters here: an unset or unreadable
+ * `APP_ENV` must not be *guessed* into a label that an allowlist might admit.
+ */
+export declare function integrationEnvironment(): string | undefined;
+/**
+ * Decide whether an integration may initialize in this process.
+ *
+ * Same answer in a web or API server, the dashboard, a worker and a CLI
+ * command, because all of them read the same `APP_ENV`.
+ *
+ * @param options the integration's own configuration
+ * @param defaultEnvironments the allowlist to use when the app did not set one
+ */
+export declare function integrationGate(options: EnvironmentGatedIntegration | undefined | null, defaultEnvironments?: readonly string[]): IntegrationGate;
+/**
+ * One environment gate, shared by every integration that talks to a remote
+ * service (stacksjs/stacks#2792).
+ *
+ * The problem it solves is not labelling. An adapter that attaches
+ * unconditionally and tags its events `development` still transmits them, so a
+ * laptop and a CI run report into the same project as production and a local
+ * startup failure reads as a live incident. The label describes the event; it
+ * does not stop it leaving.
+ *
+ * So the gate is evaluated *before* an adapter initializes. A gate that answers
+ * `false` means no upload client, no remote capture hook, no injected tracking
+ * script, no flush timer and no request - not "send it marked local". Ordinary
+ * console and file logging are unaffected: they are not this gate's business.
+ *
+ * The configuration surface is deliberately one option:
+ *
+ * ```ts
+ * bughq: {
+ *   key: env.BUGHQ_KEY,
+ *   environments: ['production', 'staging'],
+ * }
+ * ```
+ *
+ * There is no sibling `environment` field and no `enabledIn`. An application
+ * never repeats `env.APP_ENV` in each integration: the effective value is
+ * resolved here once, used to check the allowlist, and handed back on
+ * {@link IntegrationGate.environment} so the adapter can attach it as event
+ * metadata without asking.
+ *
+ * **`APP_ENV` is a configuration label, not proof of deployment identity.** A
+ * command launched locally with `APP_ENV=production` passes a production
+ * allowlist, because nothing here can tell the difference. Treat the allowlist
+ * as "which labels may transmit", not as an authorization boundary.
+ */
+/**
+ * The default allowlist for a remote-telemetry integration.
+ *
+ * Deployed environments report; a developer's machine, CI and test runs do not,
+ * until someone adds their label. New integrations should adopt this rather than
+ * inventing a policy, and an existing installation's behaviour should not be
+ * changed silently by picking it up.
+ */
+export declare const REMOTE_TELEMETRY_ENVIRONMENTS: readonly string[];
+/** The environment-gating surface an integration's own options extend. */
+export declare interface EnvironmentGatedIntegration {
+  enabled?: boolean
+  environments?: readonly string[]
+}
+export declare interface IntegrationGate {
+  enabled: boolean
+  environment: string | undefined
+  reason: IntegrationGateReason
+}
+/** Why the gate answered as it did. Worth logging; worth asserting in tests. */
+export type IntegrationGateReason = | 'disabled-explicitly'
+  | 'empty-allowlist'
+  | 'environment-unknown'
+  | 'environment-excluded'
+  | 'environment-allowed';

package/dist/integrations.js

@@ -0,0 +1 @@
+export const REMOTE_TELEMETRY_ENVIRONMENTS=["production","staging"];export function normalizeEnvironmentName(value){if(typeof value!=="string")return;const normalized=value.trim().toLowerCase();if(!/^[a-z0-9_-]+$/.test(normalized))return;if(normalized==="prod")return"production";if(normalized==="stage")return"staging";if(normalized==="dev")return"development";return normalized}export function integrationEnvironment(){return normalizeEnvironmentName(process.env.APP_ENV)??normalizeEnvironmentName("development")}export function integrationGate(options,defaultEnvironments=REMOTE_TELEMETRY_ENVIRONMENTS){const environment=integrationEnvironment();if(options?.enabled===!1)return{enabled:!1,environment,reason:"disabled-explicitly"};const allowlist=options?.environments??defaultEnvironments;if(allowlist.length===0)return{enabled:!1,environment,reason:"empty-allowlist"};if(environment===void 0)return{enabled:!1,environment,reason:"environment-unknown"};const permitted=new Set;for(const entry of allowlist){const name=normalizeEnvironmentName(entry);if(name!==void 0)permitted.add(name)}return permitted.has(environment)?{enabled:!0,environment,reason:"environment-allowed"}:{enabled:!1,environment,reason:"environment-excluded"}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/env",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.69",
+  "version": "0.74.70",
   "description": "Stacks env helper methods.",
   "author": "Chris Breuer",
   "contributors": [
@@ -56,10 +56,10 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/path": "0.74.69"
+    "@stacksjs/path": "0.74.70"
   },
   "devDependencies": {
     "better-dx": "^0.2.24",
-    "@stacksjs/validation": "0.74.69"
+    "@stacksjs/validation": "0.74.70"
   }
 }