@philkrpp/phase-loader 0.1.1 → 0.1.3

package/README.md

@@ -32,7 +32,8 @@ secrets: host, app ids, paths and keyring account names only.
     }
   },
   "require": ["DATABASE_URL"],
-  "allowLiteral": []
+  "allowLiteral": [],
+  "external": ["WORKER_TIER"]
 }
 ```
 
@@ -45,6 +46,7 @@ secrets: host, app ids, paths and keyring account names only.
 | `targets.<name>.personal.account` | Optional keyring account holding a personal app id or name; exported last (path `/`). |
 | `require` | Keys the merged export must contain; otherwise loading fails and lists the missing names. |
 | `allowLiteral` | Keys whose value may start with `${`. Any other value starting with `${` is an unresolved Phase reference and fails the load. |
+| `external` | Names set or read outside the Phase `dev` export: Coolify-only values, CI, runtime, variables read by libraries (`OTEL_*`). `example --write` lists them in their own section; `check` never reports them. |
 
 ## Tokens
 
@@ -89,9 +91,11 @@ phase-loader check --offline    # .env.example vs env reads in git-tracked files
 phase-loader check              # additionally vs the key names in Phase
 ```
 
-`check` recognises `process.env.X`, `process.env["X"]`, `import.meta.env.X`, `os.environ["X"]` and `os.getenv("X")`
-in tracked `.js/.ts/.vue/.py` files (not under `node_modules`), ignores runtime built-ins such as `NODE_ENV`, prints
-names only and exits 1 on any undocumented or orphan name. The personal app is not part of `.env.example`.
+`check` recognises `process.env.X`, `process.env["X"]`, `import.meta.env.X`, `os.environ["X"]`, `os.environ.get("X")`
+and `os.getenv("X")` in tracked `.js/.ts/.vue/.py` files (not under `node_modules`), ignores runtime built-ins such as
+`NODE_ENV`, prints names only and exits 1 on any undocumented or orphan name. A name from `.env.example` that appears
+quoted anywhere in that code (`optional('KEY')`, `env("KEY")`) counts as read, so env helpers cause no orphans; a new
+key read only through such a helper is not reported as undocumented. The personal app is not part of `.env.example`.
 
 ## API
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as KEYRING_SERVICE, c as loadConfig, l as PhaseLoaderError, n as fetchLayers, s as writeKeyring, t as run } from "./run-QGYeawST.js";
+import { a as KEYRING_SERVICE, c as loadConfig, l as PhaseLoaderError, n as fetchLayers, s as writeKeyring, t as run } from "./run-CkwwrycO.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
@@ -35,7 +35,14 @@ function exampleNames(text) {
 * Returns the text to print; values are never read into the output.
 */
 async function example(opts = {}) {
-	const { dir, sections } = await phaseNames(opts.cwd ?? process.cwd());
+	const cwd = opts.cwd ?? process.cwd();
+	const { dir, sections: phase } = await phaseNames(cwd);
+	const inPhase = new Set(phase.flatMap((s) => s.names));
+	const external = [...new Set(loadConfig(cwd).external)].filter((n) => !inPhase.has(n)).sort();
+	const sections = [...phase, {
+		label: "external (not loaded from Phase: Coolify, CI, runtime, libraries)",
+		names: external
+	}];
 	const text = sections.filter((s) => s.names.length > 0).map((s) => `# ${s.label}\n${s.names.map((n) => `${n}=`).join("\n")}\n`).join("\n");
 	const file = join(dir, EXAMPLE_FILE);
 	if (opts.write) {
@@ -54,8 +61,16 @@ const USAGE$1 = [
 	/process\.env\[\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\s*\]/g,
 	/import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
 	/os\.environ\[\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\s*\]/g,
-	/os\.getenv\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g
+	/os\.getenv\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g,
+	/os\.environ\.get\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g
 ];
+/**
+* A documented name quoted anywhere in tracked code (`optional('KEY')`, `env("KEY")`, a list of names) counts as
+* read, so helpers around `process.env[name]` do not produce orphans.
+* shortcut: undocumented detection still sees only the USAGE patterns, so a new key read only through a helper is
+* not reported; upgrade with a configurable helper list if that bites.
+*/
+const QUOTED = /["'`]([A-Z_][A-Z0-9_]*)["'`]/g;
 /** Provided by the runtime or by phase-loader itself, never documented in `.env.example`. */
 const BUILT_IN = /* @__PURE__ */ new Set([
 	"NODE_ENV",
@@ -65,7 +80,17 @@ const BUILT_IN = /* @__PURE__ */ new Set([
 	"SSR",
 	"BASE_URL",
 	"CI",
-	"PHASE_ENV_LOADED"
+	"PHASE_ENV_LOADED",
+	"VITEST",
+	"PATH",
+	"HOME",
+	"USER",
+	"LOGNAME",
+	"SHELL",
+	"PWD",
+	"TMPDIR",
+	"TZ",
+	"LANG"
 ]);
 function trackedFiles(dir) {
 	try {
@@ -84,6 +109,7 @@ function trackedFiles(dir) {
 }
 function usedNames(dir) {
 	const used = /* @__PURE__ */ new Set();
+	const quoted = /* @__PURE__ */ new Set();
 	for (const file of trackedFiles(dir)) {
 		if (!SOURCE.test(file) || file.split("/").includes("node_modules")) continue;
 		let text;
@@ -93,23 +119,29 @@ function usedNames(dir) {
 			continue;
 		}
 		for (const pattern of USAGE$1) for (const m of text.matchAll(pattern)) if (!BUILT_IN.has(m[1])) used.add(m[1]);
+		for (const m of text.matchAll(QUOTED)) quoted.add(m[1]);
 	}
-	return used;
+	return {
+		used,
+		quoted
+	};
 }
 /**
 * Offline: names in `.env.example` against env reads in tracked source files (undocumented / orphan).
 * Online: also against the key names in Phase (`dev`). Names only, never values. `ok` is false on any finding.
 */
 async function check(opts = {}) {
-	const dir = loadConfig(opts.cwd ?? process.cwd()).dir;
+	const config = loadConfig(opts.cwd ?? process.cwd());
+	const dir = config.dir;
 	const file = join(dir, EXAMPLE_FILE);
 	if (!existsSync(file)) throw new PhaseLoaderError(`${EXAMPLE_FILE} not found in ${dir} (create it with "phase-loader example --write").`);
+	const external = new Set(config.external);
 	const documented = new Set(exampleNames(readFileSync(file, "utf8")));
-	const used = usedNames(dir);
-	const findings = [[`Used in code but undocumented in ${EXAMPLE_FILE}:`, [...used].filter((n) => !documented.has(n))], [`Orphan in ${EXAMPLE_FILE} (never read in tracked code):`, [...documented].filter((n) => !used.has(n))]];
+	const { used, quoted } = usedNames(dir);
+	const findings = [[`Used in code but undocumented in ${EXAMPLE_FILE}:`, [...used].filter((n) => !documented.has(n) && !external.has(n))], [`Orphan in ${EXAMPLE_FILE} (never read in tracked code):`, [...documented].filter((n) => !used.has(n) && !quoted.has(n) && !external.has(n))]];
 	if (!opts.offline) {
 		const inPhase = new Set((await phaseNames(opts.cwd ?? process.cwd())).sections.flatMap((s) => s.names));
-		findings.push([`In ${EXAMPLE_FILE} but not in Phase:`, [...documented].filter((n) => !inPhase.has(n))], [`In Phase but not in ${EXAMPLE_FILE}:`, [...inPhase].filter((n) => !documented.has(n))]);
+		findings.push([`In ${EXAMPLE_FILE} but not in Phase:`, [...documented].filter((n) => !inPhase.has(n) && !external.has(n))], [`In Phase but not in ${EXAMPLE_FILE}:`, [...inPhase].filter((n) => !documented.has(n))]);
 	}
 	const lines = findings.filter(([, names]) => names.length > 0).flatMap(([title, names]) => [title, `  ${names.sort().join(", ")}`]);
 	return lines.length > 0 ? {

package/dist/index.d.ts

@@ -26,6 +26,11 @@ interface PhaseConfig {
   require: string[];
   /** Keys whose value may start with `${` (not a Phase reference). */
   allowLiteral: string[];
+  /**
+   * Names read or set outside the Phase `dev` export (Coolify-only values, CI, runtime, libraries such as OTEL_*):
+   * listed in their own `.env.example` section and never reported by `check`.
+   */
+  external: string[];
 }
 /** Finds the nearest `phase.config.json` from `cwd` upwards, validates and returns it. */
 export declare function loadConfig(cwd: string): PhaseConfig;

package/dist/index.js

@@ -1 +1 @@
-export { l as PhaseLoaderError, c as loadConfig, r as loadPhaseEnv, i as loadPhaseEnvSync, o as readToken, t as run } from "./run-QGYeawST.js";
+export { l as PhaseLoaderError, c as loadConfig, r as loadPhaseEnv, i as loadPhaseEnvSync, o as readToken, t as run } from "./run-CkwwrycO.js";

package/dist/{run-QGYeawST.js → run-CkwwrycO.js}

@@ -84,7 +84,8 @@ function parseConfig(file, dir) {
 		host,
 		targets,
 		require: keys(raw.require, "require"),
-		allowLiteral: keys(raw.allowLiteral, "allowLiteral")
+		allowLiteral: keys(raw.allowLiteral, "allowLiteral"),
+		external: keys(raw.external, "external")
 	};
 }
 function isObject$1(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@philkrpp/phase-loader",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Load env values from a self-hosted Phase secrets manager into a child process or the current process, with layered apps/paths and OS keyring tokens.",
   "license": "MIT",
   "repository": {