@philkrpp/phase-loader 0.1.2 → 0.1.5

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"]
 }
 ```
 
@@ -42,9 +43,11 @@ secrets: host, app ids, paths and keyring account names only.
 | `targets.<name>.env` | Phase environment name, e.g. `Development`. |
 | `targets.<name>.account` | OS keyring account (service `phase`) holding the service token for this target. |
 | `targets.<name>.layers` | Apps (`appId` = Phase app UUID; `app` = name for messages) and paths, exported in order; later layers win. |
+| `targets.<name>.require` | Optional; replaces the top-level `require` for this target (e.g. a release target without a database). |
 | `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
 

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-DuN8Wqw9.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) {
@@ -73,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,7 +101,8 @@ function trackedFiles(dir) {
 				"ignore",
 				"pipe",
 				"ignore"
-			]
+			],
+			maxBuffer: 268435456
 		}).split("\0").filter(Boolean);
 	} catch {
 		throw new PhaseLoaderError(`"git ls-files" failed in ${dir}: check needs a git repository.`);
@@ -114,15 +132,17 @@ function usedNames(dir) {
 * 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, quoted } = 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) && !quoted.has(n))]];
+	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

@@ -16,6 +16,8 @@ interface PhaseTarget {
   personal?: {
     account: string;
   };
+  /** Replaces the top-level `require` for this target (e.g. a release target without a database). */
+  require?: string[];
 }
 interface PhaseConfig {
   /** Directory that contains `phase.config.json`. */
@@ -26,6 +28,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-DuN8Wqw9.js";

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

@@ -77,6 +77,7 @@ function parseConfig(file, dir) {
 			if (!isObject$1(value.personal)) return fail(`${at}: "personal" must be an object`);
 			target.personal = { account: str(value.personal.account, ACCOUNT, `${at}: "personal.account" must be a keyring account name`) };
 		}
+		if (value.require !== void 0) target.require = keys(value.require, `targets.${name}.require`);
 		targets[name] = target;
 	}
 	return {
@@ -84,7 +85,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) {
@@ -231,7 +233,7 @@ async function fetchLayers(target, cwd) {
 function merge(target, config, fetched, keep) {
 	const exported = {};
 	for (const layer of fetched) for (const [key, value] of layer.entries) exported[key] = value;
-	const missing = config.require.filter((key) => !Object.hasOwn(exported, key));
+	const missing = (config.targets[target]?.require ?? config.require).filter((key) => !Object.hasOwn(exported, key));
 	if (missing.length > 0) throw new PhaseLoaderError(`Phase export for "${target}" lacks required key(s): ${missing.join(", ")}. Check the token's access.`);
 	const env = {};
 	for (const [key, value] of Object.entries(exported)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@philkrpp/phase-loader",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "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": {