@c9up/station 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+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

@@ -0,0 +1,3 @@
+# @c9up/station
+
+Station is the admin-scaffolding module for the [Ream](https://ream.dev) framework: declare a resource for an Atlas entity in one file and Station owns the route/UI/audit/policy derivation. It centralises the resource catalogue (`defineResource`, `ResourceRegistry`) so every later concern reads from a single declaration. See [docs/en/modules/station.md](https://ream.dev/modules/station) for the full guide.

package/dist/ResourceRegistry.d.ts

@@ -0,0 +1,18 @@
+import type { Resource } from "./types.js";
+/**
+ * Central catalogue of declared resources for a Station-powered admin surface.
+ *
+ * Plain data structure: no boot()/start() lifecycle here — provider wiring
+ * lands in story 54.7. Iteration order is registration order, which is what
+ * the admin sidebar wants.
+ */
+export declare class ResourceRegistry {
+    #private;
+    register<T>(resource: Resource<T>): void;
+    get(name: string): Resource | undefined;
+    getOrThrow(name: string): Resource;
+    has(name: string): boolean;
+    count(): number;
+    all(): ReadonlyArray<Resource>;
+}
+//# sourceMappingURL=ResourceRegistry.d.ts.map

package/dist/ResourceRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceRegistry.d.ts","sourceRoot":"","sources":["../src/ResourceRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,gBAAgB;;IAG5B,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAUxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAUlC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,KAAK,IAAI,MAAM;IAIf,GAAG,IAAI,aAAa,CAAC,QAAQ,CAAC;CAI9B"}

package/dist/ResourceRegistry.js

@@ -0,0 +1,38 @@
+/**
+ * Central catalogue of declared resources for a Station-powered admin surface.
+ *
+ * Plain data structure: no boot()/start() lifecycle here — provider wiring
+ * lands in story 54.7. Iteration order is registration order, which is what
+ * the admin sidebar wants.
+ */
+export class ResourceRegistry {
+    #map = new Map();
+    register(resource) {
+        const existing = this.#map.get(resource.name);
+        if (existing !== undefined) {
+            throw new Error(`[station] ResourceRegistry: duplicate resource name '${resource.name}' (already registered for ${existing.entity.name})`);
+        }
+        this.#map.set(resource.name, resource);
+    }
+    get(name) {
+        return this.#map.get(name);
+    }
+    getOrThrow(name) {
+        const found = this.#map.get(name);
+        if (found === undefined) {
+            throw new Error(`[station] ResourceRegistry: no resource named '${name}'`);
+        }
+        return found;
+    }
+    has(name) {
+        return this.#map.has(name);
+    }
+    count() {
+        return this.#map.size;
+    }
+    all() {
+        const snapshot = [...this.#map.values()];
+        return Object.freeze(snapshot);
+    }
+}
+//# sourceMappingURL=ResourceRegistry.js.map

package/dist/ResourceRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceRegistry.js","sourceRoot":"","sources":["../src/ResourceRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACnB,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE5C,QAAQ,CAAI,QAAqB;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACd,wDAAwD,QAAQ,CAAC,IAAI,6BAA6B,QAAQ,CAAC,MAAM,CAAC,IAAI,GAAG,CACzH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,GAAG,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,UAAU,CAAC,IAAY;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACd,kDAAkD,IAAI,GAAG,CACzD,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,GAAG;QACF,MAAM,QAAQ,GAAe,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;CACD"}

package/dist/StationProvider.d.ts

@@ -0,0 +1,109 @@
+/**
+ * StationProvider — Ream provider that wires Station's `ResourceRegistry`
+ * into the host container and mounts the list + show routes for every
+ * registered resource.
+ *
+ * Story 54.7 EXTENDS this provider with Warden integration (login
+ * surface + `/_assets/station/*` mount). The class shape and lifecycle
+ * stay; only `start()` grows.
+ *
+ * Mirror of `packages/aurora/src/AuroraProvider.ts` — register binds a
+ * singleton + sets the `services/main` proxy backing instance, start
+ * dynamically imports BOTH `@c9up/ream/services/router` AND `@c9up/atlas`
+ * inside try/catch so non-Ream hosts AND Station-without-Atlas consumers
+ * are silently tolerated. Once both modules resolve, the per-resource
+ * repository + column metadata is built ONCE (cached on the instance)
+ * and re-used by every request, then route registration runs OUTSIDE
+ * the catch — real bugs in route registration surface instead of being
+ * swallowed.
+ */
+import type { ColumnMetadata } from "@c9up/atlas";
+/**
+ * Duck-typed slice of the host's IoC container — Station MUST stay
+ * publishable without importing `@c9up/ream` directly (memory
+ * `project_package_extraction`). The Ream container fulfils this shape.
+ */
+interface StationContainer {
+    singleton<T>(key: unknown, factory: () => T): void;
+    resolve<T>(key: unknown): T;
+    has(key: unknown): boolean;
+}
+interface StationConfigStore {
+    get<T>(key: string): T | undefined;
+}
+export interface StationAppContext {
+    container: StationContainer;
+    config: StationConfigStore;
+}
+/**
+ * Config block read from `app.config.get<StationConfig>('station')`.
+ * Every field is optional — the defaults match the 54.2 / 54.3 / 54.4
+ * conventions so an app can leave the config out entirely.
+ */
+export interface StationConfig {
+    /**
+     * When true (default `true` if `@c9up/warden` is installed),
+     * Station mounts a login surface at `/admin/login` and gates every
+     * other `/admin/*` route behind `auth.verify(token)`. Setting this
+     * to `false` keeps the old open-by-default behaviour from 54.2.
+     */
+    requireAuth?: boolean;
+    /**
+     * Role required to pass the auth gate. When omitted, any
+     * authenticated user can access `/admin/*` (the per-action
+     * `<resource>.<action>` permission gate still applies).
+     */
+    requireRole?: string;
+    /**
+     * Where to redirect on a failed auth check. Defaults to
+     * `/admin/login`.
+     */
+    loginPath?: string;
+    /**
+     * Cookie name carrying the auth token. Defaults to `station_auth`
+     * to avoid colliding with app-level session cookies.
+     */
+    cookieName?: string;
+}
+/** @internal Reset module-level flags between tests. */
+export declare function resetStationProviderFlags(): void;
+/**
+ * Mass-assignment guard. Only accepts keys that are:
+ *   1. A declared `@Column` propertyKey on the resource entity, AND
+ *   2. Not the primary key (DB-managed), AND
+ *   3. Not a framework-managed timestamp. Two signals, both honoured:
+ *      (a) the Lucid-style auto flag — `@column.dateTime({ autoCreate })` /
+ *          `{ autoUpdate }` (passed in via `autoManaged`); this is the
+ *          authoritative one and catches custom-named timestamp columns
+ *          (e.g. `registeredAt`) the name list below would miss, AND
+ *      (b) the conventional name fallback (created_at / updated_at /
+ *          deleted_at) for plain `@Column` timestamps declared without the
+ *          auto flag.
+ *
+ * The `_method` synthetic field from browser-form method-overrides is
+ * dropped automatically because it never matches a column propertyKey.
+ *
+ * Returning a fresh object — never the caller's reference — so a
+ * downstream mutation can't poison the audit snapshot.
+ */
+/** @internal Exported for unit tests — the mass-assignment + checkbox coercion guard. */
+export declare function filterWritableBody(body: Record<string, unknown>, columns: ReadonlyArray<ColumnMetadata>, pkColumn: string, autoManaged: ReadonlySet<string>): Record<string, unknown>;
+export default class StationProvider {
+    #private;
+    protected app: StationAppContext;
+    constructor(app: StationAppContext);
+    register(): void;
+    boot(): Promise<void>;
+    start(): Promise<void>;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Node's ERR_MODULE_NOT_FOUND surfaces on an Error subclass with `code`.
+ * Exported for the 54.8 agnostic-peer-missing unit test, which can't
+ * realistically simulate the dynamic-import failure path inside vitest's
+ * mock graph.
+ */
+export declare function isModuleNotFound(err: unknown): boolean;
+export {};
+//# sourceMappingURL=StationProvider.d.ts.map

package/dist/StationProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StationProvider.d.ts","sourceRoot":"","sources":["../src/StationProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAEX,cAAc,EAGd,MAAM,aAAa,CAAC;AAYrB;;;;GAIG;AACH,UAAU,gBAAgB;IACzB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACnD,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,CAAC;IAC5B,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;CAC3B;AAED,UAAU,kBAAkB;IAC3B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,kBAAkB,CAAC;CAC3B;AA2MD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAaD,wDAAwD;AACxD,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAaD;;;;;;;;;;;;;;;;;;GAkBG;AACH,yFAAyF;AACzF,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,EACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AAmDD,MAAM,CAAC,OAAO,OAAO,eAAe;;IAgBvB,SAAS,CAAC,GAAG,EAAE,iBAAiB;gBAAtB,GAAG,EAAE,iBAAiB;IAE5C,QAAQ,IAAI,IAAI;IAWV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0PtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAEtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA+iB/B;AAwED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAItD"}