pinnace 0.2.0 → 0.3.0

package/README.md

@@ -26,7 +26,9 @@ Requires Node >= 22.
 
 ## Configuration + secrets
 
-Every setting resolves **CLI arg > env (via `ldenv`) > `pinnace.json`**.
+Every setting resolves **CLI arg > exported env > `.env.local` > `.env` > `pinnace.json`**.
+
+On startup the `pinnace` bin auto-loads `.env` then `.env.local` from the current directory into the environment (via `ldenv`), so a global install (`npm install -g pinnace`) picks up your secrets with no wrapper: just drop them in `.env.local` and run `pinnace …`. Loading is silent and cwd-only (never a home/global location), and it only AUGMENTS the environment: a value you exported explicitly still wins over the file (`.env.local` overrides `.env`, both sit below an exported var and above `pinnace.json`).
 
 `pinnace.json` holds only NON-secret structure (commit-safe):
 
@@ -46,13 +48,13 @@ Every setting resolves **CLI arg > env (via `ldenv`) > `pinnace.json`**.
 Secrets are **env-only, never in the config file** (structurally: the resolver has no file path for them). Each host's bearer token is read from `PINNACE_HOST_<NAME>_TOKEN` (the name upper-cased), and the master from `PINNACE_MASTER`:
 
 ```sh
-# .env.local (git-ignored) — the ONLY place secrets live
+# .env.local (git-ignored) — the ONLY place secrets live; auto-loaded from cwd
 PINNACE_MASTER=<your high-entropy master secret>
 PINNACE_HOST_PUBLISHER_TOKEN=<publisher bearer token>
 PINNACE_HOST_REPLICA_TOKEN=<replica bearer token>
 ```
 
-A missing token fails loud (naming the exact env var), never a silent empty token. Point the CLI at a config anywhere with `--config <path>`.
+This `.env.local` is loaded automatically from the directory you run `pinnace` in (no `export` needed); an explicitly exported value still takes precedence over it. A missing token fails loud (naming the exact env var), never a silent empty token. Point the CLI at a config anywhere with `--config <path>`.
 
 ## The end-to-end setup
 

package/dist/cli/bin.js

@@ -8,9 +8,15 @@
  * on-box `pinnace node <verb>` subcommands share this same binary but are wired
  * by their own task. Config/env/core are all injectable there so the dispatch
  * is unit-tested without a process or the operator's real env/config.
+ *
+ * Startup: the bin calls the {@link main} shim (`./startup.ts`), which loads the
+ * cwd's `.env` / `.env.local` into `process.env` via `ldenv` BEFORE `run()`
+ * reads env — so a global `npm install -g pinnace` gets the env-only secrets
+ * model with no `pnpm ldenv` dev wrapper. The pure `run(argv, {env})` path stays
+ * hermetic (the dotenv load lives in the shim, not in `run()`).
  */
-import { run } from './run.js';
-run(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+import { main } from './startup.js';
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
 });

package/dist/cli/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AACH,OAAO,EAAC,GAAG,EAAC,MAAM,UAAU,CAAC;AAE7B,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC9B,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC5B,CAAC,GAAG,EAAE,EAAE;IACP,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CACD,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAC,IAAI,EAAC,MAAM,cAAc,CAAC;AAElC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC/B,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC5B,CAAC,GAAG,EAAE,EAAE;IACP,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CACD,CAAC"}

package/dist/cli/startup.d.ts

@@ -0,0 +1,19 @@
+/** Injectable seams for the startup shim (defaulted to the real ones). */
+export interface StartupOptions {
+    /**
+     * Load `.env` / `.env.local` from the cwd into `process.env`. Defaults to
+     * `ldenv`'s `loadEnv` (reads `.env` then `.env.local`, local overriding,
+     * never overriding an already-exported value). Injected only for tests.
+     */
+    loadDotEnv?: () => void;
+}
+/**
+ * The CLI startup entry: load the cwd's `.env` / `.env.local` into
+ * `process.env` (so a global install gets the env-only secrets), THEN dispatch
+ * `run()` over the process argv. Returns the process exit code.
+ *
+ * This is what the `pinnace` bin calls. It keeps the `loadEnv()` side effect
+ * out of the pure `run()` path so `run(argv, {env})` stays hermetic.
+ */
+export declare function main(argv?: readonly string[], options?: StartupOptions): Promise<number>;
+//# sourceMappingURL=startup.d.ts.map

package/dist/cli/startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../../src/cli/startup.ts"],"names":[],"mappings":"AA+BA,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CACzB,IAAI,GAAE,SAAS,MAAM,EAA0B,EAC/C,OAAO,GAAE,cAAmB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/dist/cli/startup.js

@@ -0,0 +1,46 @@
+/**
+ * The `pinnace` CLI STARTUP shim: the thin process-entry glue that runs BEFORE
+ * the pure {@link run} dispatch. Its whole job is to make the env-only secrets
+ * model (CONTEXT.md `master key` / `token`) ergonomic for EVERY user, including
+ * a global `npm install -g pinnace`, by loading `.env` / `.env.local` from the
+ * cwd into `process.env` at startup, so no `pnpm ldenv` dev wrapper is needed.
+ *
+ * WHY a shim (and not inside {@link run}): `run(argv, {env})` is pure and
+ * hermetically unit-tested with an INJECTED `env` record; it must never read a
+ * real `.env` / touch a real cwd. So the ONE impure, filesystem-touching step
+ * (`ldenv`'s {@link loadEnv}) lives HERE, in the bin/startup layer, in front of
+ * `run()`. Config resolution + {@link resolveMasterSecret} read `process.env`,
+ * so `loadEnv()` must have mutated it BEFORE `run()` runs.
+ *
+ * PRECEDENCE (preserved, not changed). `loadEnv()` reads `.env` then
+ * `.env.local` (local overriding default) and MUTATES `process.env`, but it
+ * does NOT override a value ALREADY set in `process.env`. So dotenv slots in
+ * BELOW an explicitly-exported env var and ABOVE `pinnace.json`, keeping the
+ * documented "env > file" rule intact. The effective chain becomes:
+ * **CLI arg > exported `process.env` > `.env.local` > `.env` > `pinnace.json`**.
+ * The master + host tokens stay env-only: `.env.local` is merely a FILE SOURCE
+ * for those env vars, never a `pinnace.json` field.
+ *
+ * The `loadEnv` call is injected (defaulting to the real `ldenv` one) purely so
+ * the shim is unit-testable; production always uses the real `ldenv.loadEnv`,
+ * which is cwd-based only (never a global/home location), silent, and only
+ * AUGMENTS env — an already-exported value is left untouched.
+ */
+import { loadEnv } from 'ldenv';
+import { run } from './run.js';
+/**
+ * The CLI startup entry: load the cwd's `.env` / `.env.local` into
+ * `process.env` (so a global install gets the env-only secrets), THEN dispatch
+ * `run()` over the process argv. Returns the process exit code.
+ *
+ * This is what the `pinnace` bin calls. It keeps the `loadEnv()` side effect
+ * out of the pure `run()` path so `run(argv, {env})` stays hermetic.
+ */
+export async function main(argv = process.argv.slice(2), options = {}) {
+    const loadDotEnv = options.loadDotEnv ?? (() => void loadEnv());
+    // Load the cwd's dotenv files BEFORE run() reads process.env. This only
+    // augments process.env; an already-exported value still wins.
+    loadDotEnv();
+    return run(argv);
+}
+//# sourceMappingURL=startup.js.map

package/dist/cli/startup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.js","sourceRoot":"","sources":["../../src/cli/startup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAC,OAAO,EAAC,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAC,GAAG,EAAC,MAAM,UAAU,CAAC;AAY7B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACzB,OAA0B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAC/C,UAA0B,EAAE;IAE5B,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;IAChE,wEAAwE;IACxE,8DAA8D;IAC9D,UAAU,EAAE,CAAC;IACb,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC"}

package/dist/provision/cloud-init.js

@@ -10,7 +10,7 @@ const DEFAULT_KUBO_VERSION = 'v0.38.1';
  * the same agent. Overridable per-box via {@link ProvisionInput.pinnaceVersion}.
  * `pinnace@0.1.0` is the first published release (npm, public, OIDC provenance).
  */
-const DEFAULT_PINNACE_VERSION = '0.2.0';
+const DEFAULT_PINNACE_VERSION = '0.3.0';
 /**
  * The pinned Node.js major the box installs via NodeSource (`setup_<this>.x`).
  * Node 22 is a current active LTS; Node 20 (the old literal) is the OLDEST LTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinnace",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "description": "Self-host a static website on IPFS across one or more self-owned Kubo nodes.",
   "repository": {
@@ -27,7 +27,8 @@
   ],
   "dependencies": {
     "files-from-path": "^1.1.4",
-    "ipfs-car": "^3.1.0"
+    "ipfs-car": "^3.1.0",
+    "ldenv": "^0.3.16"
   },
   "devDependencies": {
     "@ipld/car": "^5.4.6",

package/src/cli/bin.ts

@@ -8,10 +8,16 @@
  * on-box `pinnace node <verb>` subcommands share this same binary but are wired
  * by their own task. Config/env/core are all injectable there so the dispatch
  * is unit-tested without a process or the operator's real env/config.
+ *
+ * Startup: the bin calls the {@link main} shim (`./startup.ts`), which loads the
+ * cwd's `.env` / `.env.local` into `process.env` via `ldenv` BEFORE `run()`
+ * reads env — so a global `npm install -g pinnace` gets the env-only secrets
+ * model with no `pnpm ldenv` dev wrapper. The pure `run(argv, {env})` path stays
+ * hermetic (the dotenv load lives in the shim, not in `run()`).
  */
-import {run} from './run.js';
+import {main} from './startup.js';
 
-run(process.argv.slice(2)).then(
+main(process.argv.slice(2)).then(
 	(code) => process.exit(code),
 	(err) => {
 		console.error(err instanceof Error ? err.message : String(err));

package/src/cli/startup.ts

@@ -0,0 +1,59 @@
+/**
+ * The `pinnace` CLI STARTUP shim: the thin process-entry glue that runs BEFORE
+ * the pure {@link run} dispatch. Its whole job is to make the env-only secrets
+ * model (CONTEXT.md `master key` / `token`) ergonomic for EVERY user, including
+ * a global `npm install -g pinnace`, by loading `.env` / `.env.local` from the
+ * cwd into `process.env` at startup, so no `pnpm ldenv` dev wrapper is needed.
+ *
+ * WHY a shim (and not inside {@link run}): `run(argv, {env})` is pure and
+ * hermetically unit-tested with an INJECTED `env` record; it must never read a
+ * real `.env` / touch a real cwd. So the ONE impure, filesystem-touching step
+ * (`ldenv`'s {@link loadEnv}) lives HERE, in the bin/startup layer, in front of
+ * `run()`. Config resolution + {@link resolveMasterSecret} read `process.env`,
+ * so `loadEnv()` must have mutated it BEFORE `run()` runs.
+ *
+ * PRECEDENCE (preserved, not changed). `loadEnv()` reads `.env` then
+ * `.env.local` (local overriding default) and MUTATES `process.env`, but it
+ * does NOT override a value ALREADY set in `process.env`. So dotenv slots in
+ * BELOW an explicitly-exported env var and ABOVE `pinnace.json`, keeping the
+ * documented "env > file" rule intact. The effective chain becomes:
+ * **CLI arg > exported `process.env` > `.env.local` > `.env` > `pinnace.json`**.
+ * The master + host tokens stay env-only: `.env.local` is merely a FILE SOURCE
+ * for those env vars, never a `pinnace.json` field.
+ *
+ * The `loadEnv` call is injected (defaulting to the real `ldenv` one) purely so
+ * the shim is unit-testable; production always uses the real `ldenv.loadEnv`,
+ * which is cwd-based only (never a global/home location), silent, and only
+ * AUGMENTS env — an already-exported value is left untouched.
+ */
+import {loadEnv} from 'ldenv';
+import {run} from './run.js';
+
+/** Injectable seams for the startup shim (defaulted to the real ones). */
+export interface StartupOptions {
+	/**
+	 * Load `.env` / `.env.local` from the cwd into `process.env`. Defaults to
+	 * `ldenv`'s `loadEnv` (reads `.env` then `.env.local`, local overriding,
+	 * never overriding an already-exported value). Injected only for tests.
+	 */
+	loadDotEnv?: () => void;
+}
+
+/**
+ * The CLI startup entry: load the cwd's `.env` / `.env.local` into
+ * `process.env` (so a global install gets the env-only secrets), THEN dispatch
+ * `run()` over the process argv. Returns the process exit code.
+ *
+ * This is what the `pinnace` bin calls. It keeps the `loadEnv()` side effect
+ * out of the pure `run()` path so `run(argv, {env})` stays hermetic.
+ */
+export async function main(
+	argv: readonly string[] = process.argv.slice(2),
+	options: StartupOptions = {},
+): Promise<number> {
+	const loadDotEnv = options.loadDotEnv ?? (() => void loadEnv());
+	// Load the cwd's dotenv files BEFORE run() reads process.env. This only
+	// augments process.env; an already-exported value still wins.
+	loadDotEnv();
+	return run(argv);
+}

package/src/provision/cloud-init.ts

@@ -164,7 +164,7 @@ const DEFAULT_KUBO_VERSION = 'v0.38.1';
  * the same agent. Overridable per-box via {@link ProvisionInput.pinnaceVersion}.
  * `pinnace@0.1.0` is the first published release (npm, public, OIDC provenance).
  */
-const DEFAULT_PINNACE_VERSION = '0.2.0';
+const DEFAULT_PINNACE_VERSION = '0.3.0';
 /**
  * The pinned Node.js major the box installs via NodeSource (`setup_<this>.x`).
  * Node 22 is a current active LTS; Node 20 (the old literal) is the OLDEST LTS