@c9up/station 0.1.11 → 0.1.13

package/src/StationProvider.ts

@@ -26,10 +26,10 @@ import type {
 	DatabaseConnection,
 	DateColumnConfig,
 } from "@c9up/atlas";
-import { inProduction } from "./nodeEnv.js";
 import { ResourceRegistry } from "./ResourceRegistry.js";
-import { setStation } from "./services/main.js";
+import { clearStation, getStation, setStation } from "./services/main.js";
 import type { AuditEvent, Resource, ResourceAction } from "./types.js";
+import { inProduction } from "./vendor/nodeEnv.js";
 // note: AuditEvent + ResourceAction are used by the CRUD handlers below;
 // the imports stay in one block for clarity.
 import { buildFormViewModel } from "./views/form.js";
@@ -287,7 +287,7 @@ type RuneValidationResult =
 /**
  * A built rune schema — only the result-based check is consumed.
  *
- * `validateResult`, NOT `validate`: rune reserves `validate()` for the VineJS
+ * `validateResult`, NOT `validate`: rune reserves `validate()` for the
  * contract (async, throwing). Reading `.valid` off a Promise gives `undefined`,
  * so keeping the old name would have made every admin write fail closed with an
  * empty error list.
@@ -548,11 +548,14 @@ export function resourcesNeedValidation(
  * NEVER `in` on an instance (`@Column() declare` makes `in` always false —
  * mirror `BaseRepository.#hydrate`).
  *
- * Per-column rule mapping tolerates the form-post wire shape (values arrive as
- * strings — rune does NOT coerce): booleans `.parse(isCheckedValue)`, numbers
+ * Per-column rule mapping tolerates the form-post wire shape, where every
+ * value arrives as a string: booleans `.parse(isCheckedValue)`, numbers
  * `.parse` string→Number (NaN falls through to a type error), everything else
- * `rules.string()`. `.parse`/`.optional`/`.nullable` force rune's TS path, so
- * no native `.node` is touched.
+ * `rules.string()`. The explicit `.parse` is deliberate even though rune now
+ * coerces both itself — a checkbox posts the values IT chooses (`isCheckedValue`
+ * is the column's own truthy spelling), which is a wider set than any
+ * general-purpose coercion should accept. `.parse`/`.optional`/`.nullable`
+ * force rune's TS path, so no native `.node` is touched.
  *
  * Returns the built schema plus the set of boolean columns — the handler
  * default-fills an ABSENT boolean key to `false` before validating (an
@@ -653,7 +656,7 @@ function fieldErrors(
 	const out: Record<string, string> = {};
 	for (const e of errors) {
 		if (e.field === "_root") continue;
-		// Collapse a nested VineJS-style path (`profile.name`) to its top-level
+		// Collapse a nested dotted path (`profile.name`) to its top-level
 		// key — `form.ts` keys errors by column propertyKey. `split` always yields
 		// a non-empty array, so `[0]` is a string (no fallback needed).
 		const [key = e.field] = e.field.split(".");
@@ -834,6 +837,9 @@ let auditCloneWarnEmitted = false;
 const TEMPLATES_ROOT = fileURLToPath(new URL("../templates/", import.meta.url));
 
 export default class StationProvider {
+	/** What this provider bound, so shutdown only clears its own. */
+	#owned: ResourceRegistry | undefined;
+
 	#contexts: Map<Resource, ResourceContext> = new Map();
 	#viewRenderer: InkerViewRenderer | undefined;
 	/**
@@ -871,7 +877,8 @@ export default class StationProvider {
 	async boot(): Promise<void> {
 		// Force-resolve so `setStation` runs even if no preload touches the
 		// singleton. Mirrors AuroraProvider.boot().
-		await this.app.container.resolve<ResourceRegistry>(ResourceRegistry);
+		this.#owned =
+			await this.app.container.resolve<ResourceRegistry>(ResourceRegistry);
 	}
 
 	async start(): Promise<void> {
@@ -879,8 +886,14 @@ export default class StationProvider {
 
 		const registry =
 			await this.app.container.resolve<ResourceRegistry>(ResourceRegistry);
-		const resources = registry.all();
-		if (resources.length === 0) return;
+
+		// NOT gated on the registry being non-empty any more. Providers start
+		// BEFORE preloads run, and a preload is where the docs say to write
+		// `station.register(...)`, so reading a snapshot here and giving up when
+		// it was empty meant an application that followed the documentation got
+		// no admin at all. The surface is prepared here and each resource is
+		// mounted as it is declared — the shape upstream's Transmit uses for the
+		// same ordering problem.
 
 		// 54.7 — read the optional `station` config block. Defaults bake
 		// in `requireAuth: true` when @c9up/warden is detected later in
@@ -894,67 +907,94 @@ export default class StationProvider {
 		if (!peers) return;
 		const { router, atlas, rune } = peers;
 
-		// 57.7 fail-closed: a write-capable admin (create/edit) validates + guards
-		// mass-assignment through a rune-derived schema. If atlas is present (CRUD
-		// is live) but `@c9up/rune` is NOT installed, refuse to boot rather than
-		// silently accept unvalidated bodies — there is NO fallback to the deleted
-		// key-filter (`feedback_security_first`). Read-only admins need no rune.
-		if (rune === null && resourcesNeedValidation(resources)) {
-			throw new Error(
-				"[station] @c9up/rune is required to validate admin write forms (create/edit) but is not installed. Add @c9up/rune (a Station peer dependency) — Station will NOT fall back to unvalidated mass-assignment. See https://ream.dev/modules/station#mass-assignment.",
-			);
-		}
-
 		// Phase 1a2 — resolve the SHARED inker renderer (AdonisJS/Edge parity)
 		// and mount Station's package templates as the `station` disk. Unlike
 		// warden (whose absence keeps the open dev-preview path), a view engine
 		// is a HARD render requirement (D2): once an admin surface exists there
-		// is no page without it. Fail LOUD at boot when @c9up/inker is not wired
-		// — mirrors #resolveDb's loud-on-missing posture — rather than degrade
-		// silently or 500 on the first request.
-		const renderer = await this.#resolveViewRenderer();
-		// Mount once: `station::<template>` now resolves to this package's
-		// templates/ dir on the host's single inker engine (edge.mount parity).
-		renderer.mount("station", TEMPLATES_ROOT);
-		this.#viewRenderer = renderer;
+		// is no page without it.
+		//
+		// The failure is HELD rather than thrown: with no resource declared
+		// there is no admin surface, and an application that installed the
+		// provider without ever registering a resource must not be forced to
+		// wire a view engine. It is rethrown on the first resource, which is the
+		// moment the requirement becomes real.
+		let rendererFailure: unknown;
+		try {
+			const renderer = await this.#resolveViewRenderer();
+			// Mount once: `station::<template>` now resolves to this package's
+			// templates/ dir on the host's single inker engine (edge.mount parity).
+			renderer.mount("station", TEMPLATES_ROOT);
+			this.#viewRenderer = renderer;
+		} catch (err) {
+			rendererFailure = err;
+		}
 
 		// Phase 1b — wire the warden auth gate (or warn-once when it stays open).
 		await this.#configureAuth(userConfig);
 
-		// Phase 2 — build per-resource context ONCE. `#resolveDb()` is
-		// loud: if the host installed `@c9up/atlas` but didn't register
-		// `@c9up/atlas/provider` in `reamrc.ts`, AC11's "surface
-		// AtlasProvider misconfiguration" intent kicks in.
 		const db = await this.#resolveDb();
-		for (const resource of resources) {
+
+		// Phase 2 — mount every resource, now and as they arrive. The shell (the
+		// login surface, the `/admin` index) goes up with the first one: an
+		// application with no resources has no admin, and had none before.
+		let shellMounted = false;
+		registry.useMounter((resource) => {
+			if (!shellMounted) {
+				if (rendererFailure !== undefined) throw rendererFailure;
+				try {
+					this.#registerShellRoutes(router);
+				} catch (err) {
+					// The router proxy may still throw "Router accessed before
+					// initialization" on first property access (a boot-ordering
+					// hazard where the proxy module imported but Ignitor's
+					// `setRouter` never fired). That is a legitimate degraded-host
+					// shape — give up quietly. Anything else propagates.
+					if (isRouterProxyUninit(err)) return;
+					throw err;
+				}
+				shellMounted = true;
+			}
+			// 57.7 fail-closed: a write-capable admin (create/edit) validates +
+			// guards mass-assignment through a rune-derived schema. If atlas is
+			// present (CRUD is live) but `@c9up/rune` is NOT installed, refuse
+			// rather than silently accept unvalidated bodies — there is NO
+			// fallback to the deleted key-filter. Read-only admins need no rune.
+			// Checked per resource, so the refusal names the one at fault.
+			if (rune === null && resourcesNeedValidation([resource])) {
+				throw new Error(
+					`[station] @c9up/rune is required to validate the write forms of the '${resource.name}' admin (create/edit) but is not installed. Add @c9up/rune (a Station peer dependency) — Station will NOT fall back to unvalidated mass-assignment. See https://ream.dev/modules/station#mass-assignment.`,
+				);
+			}
 			this.#contexts.set(
 				resource,
 				buildResourceContext(resource, db, atlas, rune),
 			);
-		}
+			this.#registerResourceRoutes(router, resource);
+		});
+
+		this.#started = true;
+	}
 
-		// 56.5 + 54.6 boot-time warn-onces. We surface the "auth wired but no
-		// permissions seeded" and "no audit sink" gaps loud-and-once so a
-		// half-wired install can't ship to prod without operators noticing.
-		// (CSRF is no longer a boot-time warn — enforcement is request-time and
-		// honest now: every write route fail-closes on `ctx.request.csrfProtected`.)
+	/**
+	 * The gaps worth reporting once, when the full set of resources is known.
+	 *
+	 * `ready()` runs after every preload, so this is the first moment the whole
+	 * admin surface exists. Nothing is mounted here — the routes were built as
+	 * each resource was declared.
+	 */
+	async ready(): Promise<void> {
+		if (!this.#started) return;
+		const registry =
+			await this.app.container.resolve<ResourceRegistry>(ResourceRegistry);
+		const resources = registry.all();
+		if (resources.length === 0) return;
+		// 56.5 + 54.6 — "auth wired but no permissions seeded" and "no audit
+		// sink" are surfaced loud-and-once so a half-wired install cannot ship to
+		// prod without operators noticing. (CSRF is not a boot-time warn:
+		// enforcement is request-time, and every write route fail-closes on
+		// `ctx.request.csrfProtected`.)
 		this.#warnSeedPermissionsOnce(resources);
 		this.#warnAuditGapsOnce(resources);
-
-		// Phase 3 — route registration. The router proxy may still throw
-		// "Router accessed before initialization" on first property access
-		// (boot ordering hazard where the proxy module imported but
-		// Ignitor's `setRouter` never fired). That's another legitimate
-		// degraded-host shape — silent return. Anything else (slug
-		// collision, future validation) propagates.
-		try {
-			this.#registerAdminRoutes(router, resources);
-		} catch (err) {
-			if (isRouterProxyUninit(err)) return;
-			throw err;
-		}
-
-		this.#started = true;
 	}
 
 	/**
@@ -986,7 +1026,11 @@ export default class StationProvider {
 			const rune = await this.#loadRune();
 			return { router, atlas, rune };
 		} catch (err) {
-			if (isModuleNotFound(err)) return null;
+			// ONLY when atlas itself is what is missing. An atlas that is
+			// installed but cannot load — a dependency of its own gone, a broken
+			// build — is not a host without atlas, and disabling the admin over
+			// it hides the actual fault.
+			if (isPackageMissing(err, "@c9up/atlas")) return null;
 			throw err;
 		}
 	}
@@ -1001,7 +1045,7 @@ export default class StationProvider {
 		try {
 			return loadBearingCast<RuneModule>(await import("@c9up/rune"));
 		} catch (err) {
-			if (isModuleNotFound(err)) return null;
+			if (isPackageMissing(err, "@c9up/rune")) return null;
 			throw err;
 		}
 	}
@@ -1198,10 +1242,20 @@ export default class StationProvider {
 	}
 
 	/** Phase 3 — mount the login surface + per-resource CRUD routes. */
-	#registerAdminRoutes(
-		router: StationRouter,
-		resources: ReadonlyArray<Resource>,
-	): void {
+	/** Wrap a handler in the auth gate when one is configured. */
+	#gate(
+		handler: (ctx: StationHttpContext) => Promise<void>,
+	): (ctx: StationHttpContext) => Promise<void> {
+		return this.#authConfig.requireAuth ? this.#withAuth(handler) : handler;
+	}
+
+	/**
+	 * The routes that belong to the admin itself rather than to a resource.
+	 *
+	 * Registered once, while the provider starts — before the HTTP server is
+	 * listening, and before any resource has necessarily been declared.
+	 */
+	#registerShellRoutes(router: StationRouter): void {
 		// 54.7 — mount login surface first when auth is required, so
 		// `/admin/login` is reachable even when the auth gate redirects every
 		// other path to it.
@@ -1211,22 +1265,30 @@ export default class StationProvider {
 			router.post("/admin/logout", this.#buildLogoutHandler());
 		}
 
-		const gate = (
-			handler: (ctx: StationHttpContext) => Promise<void>,
-		): ((ctx: StationHttpContext) => Promise<void>) =>
-			this.#authConfig.requireAuth ? this.#withAuth(handler) : handler;
-
-		// `/admin` index — send the operator to the first listable resource (or the
-		// login surface). Without it, the post-login redirect("/admin") lands on a 404.
+		// `/admin` index — send the operator to the first listable resource (or
+		// the login surface). Without it, the post-login redirect("/admin") lands
+		// on a 404.
+		//
+		// The registry is read WHEN THE REQUEST ARRIVES, not when this route is
+		// built: resources are declared in preloads, so a list captured here
+		// would name whatever happened to exist first — or nothing at all.
 		router.get(
 			"/admin",
-			gate(async (ctx) => {
-				const home = resources.find((r) => r.actions.includes("list"));
+			this.#gate(async (ctx) => {
+				const registry =
+					await this.app.container.resolve<ResourceRegistry>(ResourceRegistry);
+				const home = registry.all().find((r) => r.actions.includes("list"));
 				ctx.response.redirect(home ? `/admin/${home.name}` : "/admin/login");
 			}),
 		);
+	}
 
-		for (const resource of resources) {
+	/** Every route one resource contributes, mounted the moment it is declared. */
+	#registerResourceRoutes(router: StationRouter, resource: Resource): void {
+		const gate = (
+			handler: (ctx: StationHttpContext) => Promise<void>,
+		): ((ctx: StationHttpContext) => Promise<void>) => this.#gate(handler);
+		{
 			const slug = resource.name;
 			if (resource.actions.includes("list")) {
 				router.get(`/admin/${slug}`, gate(this.#buildListHandler(resource)));
@@ -1310,9 +1372,15 @@ export default class StationProvider {
 		);
 	}
 
-	async ready(): Promise<void> {}
-
-	async shutdown(): Promise<void> {}
+	async shutdown(): Promise<void> {
+		// Release the module-level singleton, while it is still ours. A stopped
+		// application left a dead resource registry reachable through `services/main`, and
+		// with two applications in one process the survivor's binding must not
+		// be the one cleared.
+		if (this.#owned !== undefined && getStation() === this.#owned)
+			clearStation();
+		this.#owned = undefined;
+	}
 
 	#requireContext(resource: Resource): ResourceContext {
 		const ctx = this.#contexts.get(resource);
@@ -1344,7 +1412,7 @@ export default class StationProvider {
 	 * Fail-closed response for invalid write input (57.7, AC4). Content-negotiated:
 	 *
 	 *  - **JSON/XHR** → `422` with `{ error, code: "E_VALIDATION_ERROR", messages }`
-	 *    (Adonis/Vine parity — API clients get the machine-readable errors).
+	 *    (Adonis parity — API clients get the machine-readable errors).
 	 *  - **HTML with a session** → the AdonisJS web idiom (PRG): flash the old
 	 *    input + per-field errors, then `redirect().back()` to the form `GET`,
 	 *    which re-reads the flash and re-renders with values + errors. No inline
@@ -1367,7 +1435,7 @@ export default class StationProvider {
 	): Promise<void> {
 		if (wantsJsonResponse(ctx)) {
 			ctx.response.status(422);
-			// AdonisJS/VineJS parity: `{ errors: [{ field, rule, message }] }` —
+			// AdonisJS parity: `{ errors: [{ field, rule, message }] }` —
 			// the same shape ream's own `E_VALIDATION_ERROR` handler emits.
 			ctx.response.json({
 				errors: errors.map((e) => ({
@@ -2155,6 +2223,35 @@ export function isModuleNotFound(err: unknown): boolean {
 	return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
 }
 
+/**
+ * Is THIS package the one that is missing?
+ *
+ * The code alone does not say. `@c9up/atlas` installed but missing one of its
+ * OWN dependencies raises the same `ERR_MODULE_NOT_FOUND`, and station read
+ * that as "atlas is absent" and disabled the admin — silently, which is the
+ * whole point of the degraded-host path and exactly wrong here: the peer IS
+ * there and something inside it is broken, which the operator has to be told.
+ *
+ * Node distinguishes the two in the message it writes:
+ *
+ *   Cannot find package '@c9up/atlas' imported from …   ← the peer is absent
+ *   Cannot find module '/…/node_modules/@c9up/atlas/…'  ← something inside it
+ *
+ * A bare-specifier miss names the PACKAGE; a miss inside an installed package
+ * names a path. Anything that is not unmistakably the first is re-thrown.
+ */
+export function isPackageMissing(err: unknown, specifier: string): boolean {
+	if (!isModuleNotFound(err)) return false;
+	const message = err instanceof Error ? err.message : String(err);
+	// The exact forms Node emits for a bare specifier that resolves to nothing.
+	return (
+		message.includes(`Cannot find package '${specifier}'`) ||
+		message.includes(`Cannot find module '${specifier}'`) ||
+		// The CJS wording, kept for a host that transpiles.
+		message.includes(`Cannot find module "${specifier}"`)
+	);
+}
+
 /** Ream's router proxy throws this exact string before Ignitor wires it. */
 function isRouterProxyUninit(err: unknown): boolean {
 	return (

package/src/services/main.ts

@@ -23,6 +23,18 @@ export function getStation(): ResourceRegistry | undefined {
 	return instance;
 }
 
+/**
+ * @internal Release the singleton, so a shut-down application does not leave a
+ * dead resource registry reachable through `services/main`.
+ *
+ * The caller checks ownership first (`getStation() === mine`): two applications
+ * share this module in one process, and the one shutting down must not clear
+ * what the other has since bound.
+ */
+export function clearStation(): void {
+	instance = undefined;
+}
+
 const station: ResourceRegistry = new Proxy({} as ResourceRegistry, {
 	get(_target, prop) {
 		if (!instance) {

package/src/{nodeEnv.ts → vendor/nodeEnv.ts}

@@ -1,13 +1,20 @@
+// Generated from scripts/vendor/nodeEnv.ts — do not edit.
+//
+// This package is published and built from its own repository, so the file
+// has to exist here rather than be imported. `pnpm vendor:sync` rewrites it,
+// and `pnpm vendor:check` fails if this copy has drifted from the original.
+
 /**
- * Reading `NODE_ENV`, with the aliases people actually set.
+ * `NODE_ENV`, read the way every runtime actually spells it.
  *
- * `NODE_ENV=prod` is ordinary in a Dockerfile or a platform dashboard. Read
- * verbatim it answers "not production" — and here that decides whether an
- * admin panel mounts with no authorisation at all.
+ * `NODE_ENV=prod` is ordinary in a Dockerfile or a platform dashboard, and a
+ * bare `=== "production"` answers "not production" for it. What that costs
+ * differs per package, so the consequence is stated where the decision is
+ * taken, not here.
  *
- * Duplicated rather than imported: station's peers are all optional, and a
- * safety decision that only holds when one of them is installed is not a
- * decision.
+ * The tables mirror the framework's (`@c9up/ream`, src/env/nodeEnv.ts), which
+ * is the origin rather than a peer: it formats to different rules and exposes
+ * `currentNodeEnv()` instead of `inProduction()`.
  */
 
 const DEV_ENVS = ["dev", "develop", "development"];

package/dist/nodeEnv.d.ts

@@ -1,16 +0,0 @@
-/**
- * Reading `NODE_ENV`, with the aliases people actually set.
- *
- * `NODE_ENV=prod` is ordinary in a Dockerfile or a platform dashboard. Read
- * verbatim it answers "not production" — and here that decides whether an
- * admin panel mounts with no authorisation at all.
- *
- * Duplicated rather than imported: station's peers are all optional, and a
- * safety decision that only holds when one of them is installed is not a
- * decision.
- */
-/** The canonical name for whatever `NODE_ENV` holds. */
-export declare function normalizeNodeEnv(value: string | undefined): string;
-/** Whether this process is running in production, under any spelling. */
-export declare function inProduction(): boolean;
-//# sourceMappingURL=nodeEnv.d.ts.map

package/dist/nodeEnv.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nodeEnv.d.ts","sourceRoot":"","sources":["../src/nodeEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAOlE;AAED,yEAAyE;AACzE,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}

package/dist/nodeEnv.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"nodeEnv.js","sourceRoot":"","sources":["../src/nodeEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;AACnD,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AACzC,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEtC,wDAAwD;AACxD,MAAM,UAAU,gBAAgB,CAAC,KAAyB;IACzD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAChC,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,aAAa,CAAC;IACjD,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IACjD,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAC3C,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY;IAC3B,OAAO,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,YAAY,CAAC;AAChE,CAAC"}