@philkrpp/phase-loader 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philipp Krapp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @philkrpp/phase-loader
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Load env values from a self-hosted [Phase](https://phase.dev) secrets manager at dev time, without the Phase CLI.
+Values go into a child process (`phase-loader run`) or are returned to your code (`loadPhaseEnv`); they are never
+written to disk or printed. Built on the official SDK [`@phase.dev/phase-node`](https://github.com/phasehq/node-sdk).
+
+Requires Node.js 22 or newer.
+
+## Install
+
+```sh
+pnpm add -D @philkrpp/phase-loader
+```
+
+## Configure: `phase.config.json`
+
+Commit one `phase.config.json` at the repository root (found by walking up from the current directory). It holds no
+secrets: host, app ids, paths and keyring account names only.
+
+```json
+{
+  "host": "https://phase.example.com",
+  "targets": {
+    "dev": {
+      "env": "Development",
+      "account": "my-repo/dev",
+      "layers": [
+        { "app": "my-repo", "appId": "00000000-0000-4000-8000-000000000000", "path": "/" },
+        { "app": "my-repo", "appId": "00000000-0000-4000-8000-000000000000", "path": "/local" }
+      ],
+      "personal": { "account": "my-repo/personal-app" }
+    }
+  },
+  "require": ["DATABASE_URL"],
+  "allowLiteral": []
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `host` | Phase host, `https://` only, no credentials in the URL. |
+| `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>.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. |
+
+## Tokens
+
+The token of a target is read from the OS keyring: service `phase`, account `targets.<name>.account`.
+
+The env variable `PHASE_TOKEN_<ACCOUNT>` (account upper-cased, every non-alphanumeric character replaced by `_`,
+e.g. `my-repo/dev` → `PHASE_TOKEN_MY_REPO_DEV`) is used instead when `PHASE_TOKEN_SOURCE=env` is set, or when the
+keyring is unavailable or has no entry.
+
+The personal app comes from `PHASE_PERSONAL_APP` (app id or name), else from the keyring account
+`personal.account`. If neither is set, the layer is skipped and a line on stderr says why. The same token reads it.
+
+## Run a command
+
+```sh
+phase-loader run dev -- node server.js
+```
+
+Spawns the command through `cross-spawn` (Windows `.cmd` shims such as pnpm work), never with `shell: true`. Its env is `process.env` plus the Phase values plus `PHASE_ENV_LOADED=<target>`.
+SIGINT and SIGTERM are forwarded; the exit code is the child's. On stderr:
+
+```
+[env] loaded 12 keys from Phase (dev: my-repo / + my-repo /local + personal /)
+```
+
+## Set up a token
+
+```sh
+phase-loader setup dev              # hidden prompt, stores the service token in the OS keyring
+phase-loader setup dev --personal   # stores the personal app id or name
+```
+
+The value is written to service `phase`, account `targets.<name>.account` (or `personal.account`). Empty input
+changes nothing; the value is never printed. Consumer repos typically add `"phase:setup": "phase-loader setup"`.
+
+## `.env.example` and drift check
+
+```sh
+phase-loader example            # name diff between Phase (target dev) and .env.example
+phase-loader example --write    # write .env.example: sections "# <app> <path>", sorted KEY= lines, no values
+phase-loader check --offline    # .env.example vs env reads in git-tracked files; no token, no network
+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`.
+
+## API
+
+```ts
+import { loadPhaseEnv, PhaseLoaderError } from "@philkrpp/phase-loader";
+
+const { env, layers } = await loadPhaseEnv("dev", { keep: ["PORT"] });
+Object.assign(process.env, env);
+```
+
+- `loadConfig(cwd)` returns the validated config.
+- `readToken(account)` returns the token of a keyring account.
+- `loadPhaseEnv(target, { cwd?, keep? })` returns `{ env, layers }` and does not touch `process.env`. `keep` lists
+  keys whose existing `process.env` value wins; they are left out of `env`.
+- `loadPhaseEnvSync(target, { cwd?, keep? })` blocks, assigns the values to `process.env` (keys in `keep` that are
+  already set stay untouched) and returns `{ env, layers }`. It runs the same SDK child through `execFileSync`; use it
+  where nothing can be awaited, e.g. a config module evaluated at import time.
+- `run(target, argv)` resolves with the child's exit code.
+- Every expected failure is a `PhaseLoaderError` whose message names keys, apps, paths, accounts or status codes,
+  never a value or a token.
+
+The SDK runs in a short-lived child process (token via stdin, its stderr discarded, 60 s timeout, minimal env: `PATH`, home, proxy and CA variables only), so SDK errors
+and hangs end as a `PhaseLoaderError` naming the app, path and status. Phase cross-app references (`${app::Env.KEY}`)
+are resolved by the SDK. A reference the token cannot read stays
+literal in Phase's output, so `phase-loader` fails on it and names the key instead of starting with `${…}`.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,213 @@
+#!/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 { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+// src/example.ts
+const EXAMPLE_FILE = ".env.example";
+const EXAMPLE_TARGET = "dev";
+/** Key names of the committed layers of `dev` (the personal app is not part of the repo's contract), by section. */
+async function phaseNames(cwd) {
+	const { config, layers } = await fetchLayers(EXAMPLE_TARGET, cwd);
+	const seen = /* @__PURE__ */ new Set();
+	const sections = layers.filter((layer) => layer.label !== "personal /").map((layer) => {
+		const names = layer.entries.map(([key]) => key).filter((key) => !seen.has(key)).sort();
+		for (const key of names) seen.add(key);
+		return {
+			label: layer.label,
+			names
+		};
+	});
+	return {
+		dir: config.dir,
+		sections
+	};
+}
+/** Names (`KEY=` lines) of an `.env.example` text. */
+function exampleNames(text) {
+	return [...text.matchAll(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)].map((m) => m[1]);
+}
+/**
+* Builds `.env.example` from the key names of target `dev` (sections `# <app> <path>`, `KEY=` lines, sorted).
+* `write` replaces the file in the config directory; otherwise the result is a name diff against the current file.
+* 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 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) {
+		writeFileSync(file, text);
+		return `Wrote ${EXAMPLE_FILE} (${sections.reduce((n, s) => n + s.names.length, 0)} names).`;
+	}
+	const current = new Set(existsSync(file) ? exampleNames(readFileSync(file, "utf8")) : []);
+	const wanted = new Set(sections.flatMap((s) => s.names));
+	const lines = [...[...wanted].filter((n) => !current.has(n)).sort().map((n) => `+ ${n}`), ...[...current].filter((n) => !wanted.has(n)).sort().map((n) => `- ${n}`)];
+	return lines.length > 0 ? `${lines.join("\n")}\n(run with --write to update ${EXAMPLE_FILE})` : `${EXAMPLE_FILE} is up to date.`;
+}
+// src/check.ts
+const SOURCE = /\.(?:[cm]?[jt]sx?|vue|svelte|py)$/;
+const USAGE$1 = [
+	/process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
+	/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
+];
+/** Provided by the runtime or by phase-loader itself, never documented in `.env.example`. */
+const BUILT_IN = /* @__PURE__ */ new Set([
+	"NODE_ENV",
+	"MODE",
+	"DEV",
+	"PROD",
+	"SSR",
+	"BASE_URL",
+	"CI",
+	"PHASE_ENV_LOADED"
+]);
+function trackedFiles(dir) {
+	try {
+		return execFileSync("git", ["ls-files", "-z"], {
+			cwd: dir,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).split("\0").filter(Boolean);
+	} catch {
+		throw new PhaseLoaderError(`"git ls-files" failed in ${dir}: check needs a git repository.`);
+	}
+}
+function usedNames(dir) {
+	const used = /* @__PURE__ */ new Set();
+	for (const file of trackedFiles(dir)) {
+		if (!SOURCE.test(file) || file.split("/").includes("node_modules")) continue;
+		let text;
+		try {
+			text = readFileSync(join(dir, file), "utf8");
+		} catch {
+			continue;
+		}
+		for (const pattern of USAGE$1) for (const m of text.matchAll(pattern)) if (!BUILT_IN.has(m[1])) used.add(m[1]);
+	}
+	return used;
+}
+/**
+* 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 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 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))]];
+	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))]);
+	}
+	const lines = findings.filter(([, names]) => names.length > 0).flatMap(([title, names]) => [title, `  ${names.sort().join(", ")}`]);
+	return lines.length > 0 ? {
+		ok: false,
+		report: lines.join("\n")
+	} : {
+		ok: true,
+		report: "Env names are consistent."
+	};
+}
+// src/setup.ts
+/** Prompts on `output` and reads one line from `input` without echoing it. */
+function readHidden(prompt, input, output) {
+	let muted = false;
+	const sink = new Writable({ write(chunk, _encoding, callback) {
+		if (!muted) output.write(chunk);
+		callback();
+	} });
+	const rl = createInterface({
+		input,
+		output: sink,
+		terminal: Boolean(input.isTTY)
+	});
+	return new Promise((resolve) => {
+		let settled = false;
+		const done = (answer) => {
+			if (settled) return;
+			settled = true;
+			output.write("\n");
+			rl.close();
+			resolve(answer);
+		};
+		rl.once("close", () => done(""));
+		rl.question(prompt, done);
+		muted = true;
+	});
+}
+/**
+* Stores a token (or, with `personal`, the personal app id/name) in the OS keyring, service `phase`, account from
+* `phase.config.json`. Empty input changes nothing. Returns the message to print; it never contains the value.
+*/
+async function setup(target, opts = {}) {
+	const config = loadConfig(opts.cwd ?? process.cwd());
+	const t = Object.hasOwn(config.targets, target) ? config.targets[target] : void 0;
+	if (!t) throw new PhaseLoaderError(`Unknown target "${target}" (phase.config.json defines: ${Object.keys(config.targets).join(", ")}).`);
+	if (opts.personal && !t.personal) throw new PhaseLoaderError(`Target "${target}" has no "personal" account configured.`);
+	const account = opts.personal ? t.personal.account : t.account;
+	const what = opts.personal ? "personal app (id or name)" : "service token";
+	const value = (await (opts.ask ?? ((prompt) => readHidden(prompt, process.stdin, process.stderr)))(`Phase ${what} for "${account}" (empty = keep current): `)).trim();
+	if (!value) return `Unchanged: keyring account "${account}".`;
+	writeKeyring(account, value);
+	return `Stored in the OS keyring (service "${KEYRING_SERVICE}", account "${account}").`;
+}
+// src/cli.ts
+const USAGE = `Usage:
+  phase-loader setup <target> [--personal]
+  phase-loader run <target> -- <command> [args...]
+  phase-loader example [--write]
+  phase-loader check [--offline]`;
+/** Exit code of the command, or 2 for a usage error. */
+async function main(argv) {
+	const [command, ...args] = argv;
+	const flags = (allowed) => args.every((a) => a.startsWith("--") && allowed.includes(a)) ? args : void 0;
+	if (command === "run") {
+		const [target, separator, ...rest] = args;
+		if (!target || separator !== "--" || rest.length === 0) return usage();
+		return run(target, rest);
+	}
+	if (command === "setup") {
+		const [target, ...flagArgs] = args;
+		if (!target || target.startsWith("--") || !flagArgs.every((a) => a === "--personal")) return usage();
+		process.stderr.write(`${await setup(target, { personal: flagArgs.includes("--personal") })}\n`);
+		return 0;
+	}
+	if (command === "example") {
+		const given = flags(["--write"]);
+		if (!given) return usage();
+		process.stdout.write(`${await example({ write: given.includes("--write") })}\n`);
+		return 0;
+	}
+	if (command === "check") {
+		const given = flags(["--offline"]);
+		if (!given) return usage();
+		const { ok, report } = await check({ offline: given.includes("--offline") });
+		process.stdout.write(`${report}\n`);
+		return ok ? 0 : 1;
+	}
+	return usage();
+}
+function usage() {
+	process.stderr.write(`${USAGE}\n`);
+	return 2;
+}
+try {
+	process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+	const message = error instanceof PhaseLoaderError ? error.message : `unexpected ${error?.name ?? "error"}`;
+	process.stderr.write(`phase-loader: ${message}\n`);
+	process.exitCode = 1;
+}
+export {};

package/dist/fetch-child.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/fetch-child.js

@@ -0,0 +1,87 @@
+import Phase from "@phase.dev/phase-node";
+// src/fetch-core.ts
+const UNREACHABLE = /ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|Network Error|timeout|Failed to initialize session/i;
+/** Short reason for an SDK error; nothing of the error text itself leaves the child. */
+function failureReason(error) {
+	const text = typeof error === "string" ? error : error instanceof Error ? error.message : "";
+	const status = /^Error: (\d{3}):/.exec(text)?.[1];
+	if (status) return status;
+	if (text === "Invalid app id") return "invalid-app";
+	if (text.startsWith("Invalid environment name")) return "invalid-env";
+	if (text.startsWith("Invalid token format")) return "invalid-token";
+	if (UNREACHABLE.test(text)) return "unreachable";
+	return "error";
+}
+/** Reads a FetchRequest from stdin, exports every layer, writes FetchMessages to stdout and exits. */
+async function runFetchChild(Phase) {
+	let current = "init";
+	let finished = false;
+	const finish = (message, code) => {
+		if (finished) return;
+		finished = true;
+		process.stdout.write(`${JSON.stringify(message)}\n`, () => process.exit(code));
+	};
+	const fail = (error) => finish({
+		ok: false,
+		error: `${current} (${failureReason(error)})`
+	}, 1);
+	const progress = (label) => {
+		current = label;
+		process.stdout.write(`${JSON.stringify({ progress: label })}\n`);
+	};
+	process.on("unhandledRejection", fail);
+	process.on("uncaughtException", fail);
+	try {
+		const chunks = [];
+		for await (const chunk of process.stdin) chunks.push(chunk);
+		const request = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+		progress("init");
+		const phase = new Phase(request.token, request.host);
+		await phase.init();
+		const layers = request.layers.map((l) => ({
+			label: `${l.app} ${l.path}`,
+			appId: l.appId,
+			path: l.path
+		}));
+		if (request.personal) {
+			progress("personal /");
+			const apps = phase.apps ?? [];
+			const byId = apps.filter((a) => a.id === request.personal);
+			const matches = byId.length > 0 ? byId : apps.filter((a) => a.name === request.personal);
+			if (matches.length !== 1) {
+				finish({
+					ok: false,
+					error: `personal / (${matches.length === 0 ? "invalid-app" : "ambiguous-app"})`
+				}, 1);
+				return;
+			}
+			layers.push({
+				label: "personal /",
+				appId: matches[0].id,
+				path: "/"
+			});
+		}
+		const fetched = [];
+		for (const layer of layers) {
+			progress(layer.label);
+			const result = await phase.get({
+				appId: layer.appId,
+				envName: request.envName,
+				path: layer.path
+			});
+			fetched.push({
+				label: layer.label,
+				entries: result.map((s) => [s.key, s.value])
+			});
+		}
+		finish({
+			ok: true,
+			layers: fetched
+		}, 0);
+	} catch (error) {
+		fail(error);
+	}
+}
+// src/fetch-child.ts
+await runFetchChild(Phase);
+export {};

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/** One Phase app + path exported as a layer; layers merge in order, later wins. */
+interface PhaseLayer {
+  /** App name, used in messages only. */
+  app: string;
+  /** App id (UUID); the SDK addresses apps by id. */
+  appId: string;
+  path: string;
+}
+interface PhaseTarget {
+  /** Phase environment name, e.g. `Development`. */
+  env: string;
+  /** Keyring account (service `phase`) holding the token for this target. */
+  account: string;
+  layers: PhaseLayer[];
+  /** Keyring account holding the personal app id or name; exported last with path `/`. */
+  personal?: {
+    account: string;
+  };
+}
+interface PhaseConfig {
+  /** Directory that contains `phase.config.json`. */
+  dir: string;
+  host: string;
+  targets: Record<string, PhaseTarget>;
+  /** Keys the merged export must contain. */
+  require: string[];
+  /** Keys whose value may start with `${` (not a Phase reference). */
+  allowLiteral: string[];
+}
+/** Finds the nearest `phase.config.json` from `cwd` upwards, validates and returns it. */
+export declare function loadConfig(cwd: string): PhaseConfig;
+/**
+ * The only error this package throws on purpose. Messages name keys, apps, paths, accounts and status codes only,
+ * never a secret value or a token.
+ */
+export declare class PhaseLoaderError extends Error {
+  constructor(message: string);
+}
+interface LoadedPhaseEnv {
+  /** Merged values; never print them. */
+  env: Record<string, string>;
+  /** Exported layers in order, e.g. `["repo /", "repo /local", "personal /"]`. */
+  layers: string[];
+}
+/**
+ * Exports the layers of `target` from Phase and returns the merged values without touching `process.env`.
+ * Layers merge in order (later wins), the personal app comes last. The SDK runs in a child process (it can throw
+ * outside its promises) and resolves `${…}` references; a value that still starts with `${` (unreadable reference)
+ * throws unless the key is in `allowLiteral`.
+ * `keep`: keys whose existing `process.env` value wins; they are left out of the result.
+ */
+export declare function loadPhaseEnv(target: string, opts?: {
+  cwd?: string;
+  keep?: string[];
+}): Promise<LoadedPhaseEnv>;
+/**
+ * Blocking variant for code that cannot await (e.g. a config module loaded at import time): same child, same
+ * checks, but the values are assigned to `process.env` (keys in `keep` that are already set stay untouched).
+ * The child's output is captured through pipes, never inherited.
+ */
+export declare function loadPhaseEnvSync(target: string, opts?: {
+  cwd?: string;
+  keep?: string[];
+}): LoadedPhaseEnv;
+/**
+ * Loads `target` and runs `argv` (no `shell: true`; cross-spawn resolves Windows `.cmd` shims) with `process.env` + the Phase values + `PHASE_ENV_LOADED=<target>`.
+ * SIGINT/SIGTERM are forwarded to the child; resolves with its exit code (128 + signal number when killed).
+ */
+export declare function run(target: string, argv: string[]): Promise<number>;
+/**
+ * Token of a keyring account: the OS keyring (service `phase`) unless `PHASE_TOKEN_SOURCE=env`; the env variable
+ * {@link tokenEnvVar} when the keyring is skipped, unavailable or has no entry.
+ */
+export declare function readToken(account: string): string;
+export type { LoadedPhaseEnv, PhaseConfig, PhaseLayer, PhaseTarget };

package/dist/index.js

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

package/dist/run-QGYeawST.js

@@ -0,0 +1,407 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { execFileSync, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { Entry } from "@napi-rs/keyring";
+import { constants } from "node:os";
+import spawn$1 from "cross-spawn";
+// src/errors.ts
+/**
+* The only error this package throws on purpose. Messages name keys, apps, paths, accounts and status codes only,
+* never a secret value or a token.
+*/
+var PhaseLoaderError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PhaseLoaderError";
+	}
+};
+// src/config.ts
+const CONFIG_FILE = "phase.config.json";
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const ENV_NAME = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PATH = /^\/[A-Za-z0-9._/-]*$/;
+const KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ACCOUNT = /^[^\p{Cc}]{1,200}$/u;
+/** Finds the nearest `phase.config.json` from `cwd` upwards, validates and returns it. */
+function loadConfig(cwd) {
+	let dir = resolve(cwd);
+	for (;;) {
+		const file = join(dir, CONFIG_FILE);
+		if (existsSync(file)) return parseConfig(file, dir);
+		const parent = dirname(dir);
+		if (parent === dir) throw new PhaseLoaderError(`No ${CONFIG_FILE} found in ${cwd} or any parent directory.`);
+		dir = parent;
+	}
+}
+function parseConfig(file, dir) {
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		throw new PhaseLoaderError(`${file} is not readable JSON.`);
+	}
+	const fail = (what) => {
+		throw new PhaseLoaderError(`Invalid ${CONFIG_FILE} (${file}): ${what}.`);
+	};
+	const str = (value, pattern, what) => typeof value === "string" && pattern.test(value) ? value : fail(what);
+	const keys = (value, field) => {
+		if (value === void 0) return [];
+		if (!Array.isArray(value)) return fail(`"${field}" must be a list of key names`);
+		return value.map((key) => str(key, KEY, `"${field}" must contain env key names`));
+	};
+	if (!isObject$1(raw)) return fail("expected an object");
+	const host = str(raw.host, /^https:\/\/[^\s/@]+(\/[^\s@]*)?$/, `"host" must be an https:// URL without credentials`).replace(/\/+$/, "");
+	if (!isObject$1(raw.targets) || Object.keys(raw.targets).length === 0) return fail(`"targets" must be a non-empty object`);
+	const targets = {};
+	for (const [name, value] of Object.entries(raw.targets)) {
+		const at = `target "${name}"`;
+		str(name, NAME, `${at} has an invalid name`);
+		if (!isObject$1(value)) return fail(`${at} must be an object`);
+		if (!Array.isArray(value.layers) || value.layers.length === 0) return fail(`${at}: "layers" must be a non-empty list`);
+		const target = {
+			env: str(value.env, ENV_NAME, `${at}: "env" must be a Phase environment name`),
+			account: str(value.account, ACCOUNT, `${at}: "account" must be a keyring account name`),
+			layers: value.layers.map((layer, i) => {
+				const li = `${at} layer ${i}`;
+				if (!isObject$1(layer)) return fail(`${li} must be an object`);
+				return {
+					app: str(layer.app, NAME, `${li}: "app" must be a Phase app name`),
+					appId: str(layer.appId, UUID, `${li}: "appId" must be a Phase app id (UUID)`),
+					path: str(layer.path, PATH, `${li}: "path" must start with "/"`)
+				};
+			})
+		};
+		if (value.personal !== void 0) {
+			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`) };
+		}
+		targets[name] = target;
+	}
+	return {
+		dir,
+		host,
+		targets,
+		require: keys(raw.require, "require"),
+		allowLiteral: keys(raw.allowLiteral, "allowLiteral")
+	};
+}
+function isObject$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// src/fetch-protocol.ts
+const FETCH_TIMEOUT_MS = 6e4;
+const LABEL = /^(?:init|personal \/|[A-Za-z0-9][A-Za-z0-9._-]* \/[A-Za-z0-9._/-]*)$/;
+const REASON = /^(?:\d{3}|timeout|unreachable|invalid-app|invalid-env|invalid-token|ambiguous-app|crashed|invalid-response|error)$/;
+const FAILURE = /^(.+) \(([a-z0-9-]+)\)$/;
+/**
+* Turns the child's stdout and exit into the fetched layers, or throws a {@link PhaseLoaderError} built only from
+* validated labels and reasons (never from free text of the child).
+*/
+function readFetchOutput(stdout, outcome, ctx) {
+	let last = "init";
+	let response;
+	for (const line of stdout.split("\n")) {
+		let message;
+		try {
+			message = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (!isObject(message)) continue;
+		if (typeof message.progress === "string" && LABEL.test(message.progress)) last = message.progress;
+		else if (typeof message.ok === "boolean") response = message;
+	}
+	if (outcome.timedOut) throw fetchFailure(last, "timeout", ctx);
+	if (response?.ok === true) {
+		if (isLayers(response.layers)) return response.layers;
+		throw fetchFailure(last, "invalid-response", ctx);
+	}
+	if (response?.ok === false) {
+		const match = typeof response.error === "string" ? FAILURE.exec(response.error) : null;
+		if (match && LABEL.test(match[1]) && REASON.test(match[2])) throw fetchFailure(match[1], match[2], ctx);
+		throw fetchFailure(last, "invalid-response", ctx);
+	}
+	throw fetchFailure(last, outcome.exitCode === 0 ? "invalid-response" : "crashed", ctx);
+}
+function fetchFailure(label, reason, ctx) {
+	if (label === "init") {
+		if (/^\d{3}$/.test(reason)) return new PhaseLoaderError(`Phase rejected the token for account "${ctx.account}" at ${ctx.host} (${reason}).`);
+		if (reason === "invalid-token") return new PhaseLoaderError(`The Phase token for account "${ctx.account}" has an invalid format.`);
+		if (reason === "unreachable" || reason === "timeout") return new PhaseLoaderError(`Phase not reachable at ${ctx.host} (${reason}; tailnet?).`);
+	}
+	return new PhaseLoaderError(`Phase export failed: ${label} (${reason})${label === "personal /" && ctx.personalSource ? ` Check the personal app from ${ctx.personalSource}.` : ""}`);
+}
+function isLayers(value) {
+	return Array.isArray(value) && value.every((layer) => isObject(layer) && typeof layer.label === "string" && LABEL.test(layer.label) && Array.isArray(layer.entries) && layer.entries.every((s) => Array.isArray(s) && s.length === 2 && typeof s[0] === "string" && typeof s[1] === "string"));
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// src/token.ts
+const KEYRING_SERVICE = "phase";
+/** Env variable that can carry the token of a keyring account: `repo/dev` → `PHASE_TOKEN_REPO_DEV`. */
+function tokenEnvVar(account) {
+	return `PHASE_TOKEN_${account.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+}
+/** Trimmed keyring entry of service `phase`, `null` when there is none. Throws when the keyring is unavailable. */
+function readKeyring(account) {
+	return new Entry("phase", account).getPassword()?.trim() || null;
+}
+/** Stores `value` under service `phase`; throws a {@link PhaseLoaderError} without the value when it fails. */
+function writeKeyring(account, value) {
+	try {
+		new Entry(KEYRING_SERVICE, account).setPassword(value);
+	} catch {
+		throw new PhaseLoaderError(`Could not write the OS keyring (service "${KEYRING_SERVICE}", account "${account}").`);
+	}
+}
+/**
+* Token of a keyring account: the OS keyring (service `phase`) unless `PHASE_TOKEN_SOURCE=env`; the env variable
+* {@link tokenEnvVar} when the keyring is skipped, unavailable or has no entry.
+*/
+function readToken(account) {
+	const envVar = tokenEnvVar(account);
+	let keyring = "keyring skipped (PHASE_TOKEN_SOURCE=env)";
+	if (process.env.PHASE_TOKEN_SOURCE !== "env") try {
+		const token = readKeyring(account);
+		if (token) return token;
+		keyring = "no keyring entry";
+	} catch {
+		keyring = "keyring unavailable";
+	}
+	const fromEnv = process.env[envVar]?.trim();
+	if (fromEnv) return fromEnv;
+	throw new PhaseLoaderError(`No Phase token for account "${account}" (${keyring}, ${envVar} unset). Store it in the OS keyring (service "${KEYRING_SERVICE}", account "${account}") with "phase-loader setup", or set ${envVar}.`);
+}
+// src/load.ts
+/** SDK child script, its timeout and extra env; internal, tests point `script` at a fake and pass its config. */
+const fetchChild = {
+	script: fileURLToPath(new URL("./fetch-child.js", import.meta.url)),
+	timeoutMs: FETCH_TIMEOUT_MS,
+	extraEnv: {}
+};
+/** Env the SDK child inherits: PATH, home, Windows root, proxy and CA settings; no token, no other secret. */
+const CHILD_ENV = /^(?:PATH|HOME|USERPROFILE|SYSTEMROOT|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)$/i;
+function childEnv() {
+	const env = {};
+	for (const [key, value] of Object.entries(process.env)) if (value !== void 0 && CHILD_ENV.test(key)) env[key] = value;
+	return {
+		...env,
+		...fetchChild.extraEnv
+	};
+}
+function prepare(target, cwd) {
+	const config = loadConfig(cwd);
+	const t = Object.hasOwn(config.targets, target) ? config.targets[target] : void 0;
+	if (!t) throw new PhaseLoaderError(`Unknown target "${target}" (phase.config.json defines: ${Object.keys(config.targets).join(", ")}).`);
+	const token = readToken(t.account);
+	const personal = personalApp(t);
+	return {
+		config,
+		request: {
+			host: config.host,
+			token,
+			envName: t.env,
+			layers: t.layers.map(({ app, appId, path }) => ({
+				app,
+				appId,
+				path
+			})),
+			...personal ? { personal: personal.ref } : {}
+		},
+		ctx: {
+			host: config.host,
+			account: t.account,
+			personalSource: personal?.source
+		}
+	};
+}
+/** Exports every layer (unmerged, `personal /` last) after the shared child run; used by `example` and `check`. */
+async function fetchLayers(target, cwd) {
+	const { config, request, ctx } = prepare(target, cwd);
+	const outcome = await fetchInChild(request);
+	return {
+		config,
+		layers: readFetchOutput(outcome.stdout, outcome, ctx)
+	};
+}
+/** Merges the layers later-wins, applies `require`, `keep` and the `${` check; shared by the async and sync loader. */
+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));
+	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)) {
+		if (keep?.includes(key) && process.env[key] !== void 0) continue;
+		env[key] = value;
+	}
+	const literal = Object.keys(env).filter((key) => env[key]?.startsWith("${") && !config.allowLiteral.includes(key));
+	if (literal.length > 0) throw new PhaseLoaderError(`Unresolved Phase reference in: ${literal.join(", ")}. Grant the token access to the referenced app, or list the key in "allowLiteral" if the value is meant literally.`);
+	return {
+		env,
+		layers: fetched.map((l) => l.label)
+	};
+}
+/**
+* Exports the layers of `target` from Phase and returns the merged values without touching `process.env`.
+* Layers merge in order (later wins), the personal app comes last. The SDK runs in a child process (it can throw
+* outside its promises) and resolves `${…}` references; a value that still starts with `${` (unreadable reference)
+* throws unless the key is in `allowLiteral`.
+* `keep`: keys whose existing `process.env` value wins; they are left out of the result.
+*/
+async function loadPhaseEnv(target, opts = {}) {
+	const { config, layers } = await fetchLayers(target, opts.cwd ?? process.cwd());
+	return merge(target, config, layers, opts.keep);
+}
+/**
+* Blocking variant for code that cannot await (e.g. a config module loaded at import time): same child, same
+* checks, but the values are assigned to `process.env` (keys in `keep` that are already set stay untouched).
+* The child's output is captured through pipes, never inherited.
+*/
+function loadPhaseEnvSync(target, opts = {}) {
+	const { config, request, ctx } = prepare(target, opts.cwd ?? process.cwd());
+	const loaded = merge(target, config, readFetchOutput(...fetchSync(request), ctx), opts.keep);
+	Object.assign(process.env, loaded.env);
+	return loaded;
+}
+function fetchSync(request) {
+	try {
+		return [execFileSync(process.execPath, [fetchChild.script], {
+			input: JSON.stringify(request),
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			env: childEnv(),
+			timeout: fetchChild.timeoutMs,
+			killSignal: "SIGKILL",
+			encoding: "utf8",
+			maxBuffer: 67108864
+		}), {
+			timedOut: false,
+			exitCode: 0
+		}];
+	} catch (error) {
+		const e = error;
+		return [e.stdout ?? "", {
+			timedOut: e.code === "ETIMEDOUT",
+			exitCode: e.status ?? null
+		}];
+	}
+}
+/**
+* Personal app reference (`PHASE_PERSONAL_APP`, else the keyring account `personal.account`), only for targets with
+* `personal`. When neither is set the layer is skipped with a stderr line.
+*/
+function personalApp(t) {
+	if (!t.personal) return void 0;
+	const fromEnv = process.env.PHASE_PERSONAL_APP?.trim();
+	if (fromEnv) return {
+		ref: fromEnv,
+		source: "PHASE_PERSONAL_APP"
+	};
+	const account = t.personal.account;
+	let reason;
+	try {
+		const ref = readKeyring(account);
+		if (ref) return {
+			ref,
+			source: `keyring account "${account}"`
+		};
+		reason = `no keyring entry for account "${account}" and PHASE_PERSONAL_APP unset`;
+	} catch {
+		reason = `keyring unavailable for account "${account}" and PHASE_PERSONAL_APP unset`;
+	}
+	process.stderr.write(`[env] personal layer skipped: ${reason}\n`);
+}
+/** Runs the SDK child: request (with the token) on stdin, messages on stdout, stderr drained and discarded. */
+function fetchInChild(request) {
+	return new Promise((resolve) => {
+		let stdout = "";
+		let timedOut = false;
+		let timer;
+		let settled = false;
+		const done = (exitCode) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve({
+				stdout,
+				timedOut,
+				exitCode
+			});
+		};
+		let child;
+		try {
+			child = spawn(process.execPath, [fetchChild.script], {
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				],
+				env: childEnv()
+			});
+		} catch {
+			done(null);
+			return;
+		}
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr?.resume();
+		child.stdin?.on("error", () => {});
+		child.once("error", () => done(null));
+		child.once("close", (code) => done(code));
+		timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGKILL");
+		}, fetchChild.timeoutMs);
+		child.stdin?.end(JSON.stringify(request));
+	});
+}
+// src/run.ts
+const FORWARDED = ["SIGINT", "SIGTERM"];
+/**
+* Loads `target` and runs `argv` (no `shell: true`; cross-spawn resolves Windows `.cmd` shims) with `process.env` + the Phase values + `PHASE_ENV_LOADED=<target>`.
+* SIGINT/SIGTERM are forwarded to the child; resolves with its exit code (128 + signal number when killed).
+*/
+async function run(target, argv) {
+	const [command, ...args] = argv;
+	if (!command) throw new PhaseLoaderError("No command given: phase-loader run <target> -- <command> [args...]");
+	const { env, layers } = await loadPhaseEnv(target);
+	process.stderr.write(`[env] loaded ${Object.keys(env).length} keys from Phase (${target}: ${layers.join(" + ")})\n`);
+	let child;
+	try {
+		child = spawn$1(command, args, {
+			stdio: "inherit",
+			env: {
+				...process.env,
+				...env,
+				PHASE_ENV_LOADED: target
+			}
+		});
+	} catch (error) {
+		throw new PhaseLoaderError(`Could not start "${command}" (${error.code ?? "error"}).`);
+	}
+	const handlers = FORWARDED.map((signal) => [signal, () => child.kill(signal)]);
+	for (const [signal, handler] of handlers) process.on(signal, handler);
+	const detach = () => {
+		for (const [signal, handler] of handlers) process.off(signal, handler);
+	};
+	return new Promise((resolve, reject) => {
+		child.once("error", (error) => {
+			detach();
+			reject(new PhaseLoaderError(`Could not start "${command}" (${error.code ?? "error"}).`));
+		});
+		child.once("exit", (code, signal) => {
+			detach();
+			resolve(code ?? 128 + (signal ? constants.signals[signal] : 0));
+		});
+	});
+}
+export { KEYRING_SERVICE as a, loadConfig as c, loadPhaseEnvSync as i, PhaseLoaderError as l, fetchLayers as n, readToken as o, loadPhaseEnv as r, writeKeyring as s, run as t };

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@philkrpp/phase-loader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/philkrpp/phase-loader.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "phase-loader": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "2.1.2",
+    "@phase.dev/phase-node": "3.2.0",
+    "cross-spawn": "7.0.6"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "6.0.6",
+    "@types/node": "22.20.5",
+    "tsdown": "0.23.1",
+    "typescript": "6.0.3",
+    "vitest": "5.0.5"
+  }
+}