@c9up/station 0.1.5

package/src/casing.ts

@@ -0,0 +1,86 @@
+/**
+ * Convert an identifier (camelCase / PascalCase / digits / already-lowercase)
+ * to kebab-case.
+ *
+ *   BlogPost   -> blog-post
+ *   URLParser  -> url-parser   (consecutive uppercase = one segment)
+ *   My2024Post -> my-2024-post (digit boundaries split too)
+ *   user       -> user         (idempotent on already-lower input)
+ */
+export function kebabCase(input: string): string {
+	const upperAfterLowerOrDigit = input.replace(/([a-z0-9])([A-Z])/g, "$1-$2");
+	const upperAfterUpperBeforeLower = upperAfterLowerOrDigit.replace(
+		/([A-Z])([A-Z][a-z])/g,
+		"$1-$2",
+	);
+	const digitAfterLetter = upperAfterUpperBeforeLower.replace(
+		/([A-Za-z])([0-9])/g,
+		"$1-$2",
+	);
+	return digitAfterLetter.toLowerCase();
+}
+
+/**
+ * Convert kebab-case to space-separated Title Case.
+ *
+ *   blog-posts -> Blog Posts
+ */
+export function titleCase(input: string): string {
+	return input
+		.split("-")
+		.map((part) =>
+			part.length === 0 ? part : part[0].toUpperCase() + part.slice(1),
+		)
+		.join(" ");
+}
+
+/**
+ * Irregular plural table. Lookup is on the LAST kebab segment so
+ * `super-man` -> `super-men` works while `human` falls through.
+ */
+const IRREGULAR_PLURALS: ReadonlyMap<string, string> = new Map([
+	["person", "people"],
+	["child", "children"],
+	["man", "men"],
+	["woman", "women"],
+	["mouse", "mice"],
+	["goose", "geese"],
+	["tooth", "teeth"],
+	["foot", "feet"],
+	["analysis", "analyses"],
+	["crisis", "crises"],
+	["phenomenon", "phenomena"],
+	["criterion", "criteria"],
+	["datum", "data"],
+	["medium", "media"],
+]);
+
+function pluraliseWord(word: string): string {
+	const irregular = IRREGULAR_PLURALS.get(word);
+	if (irregular !== undefined) {
+		return irregular;
+	}
+	if (/[^aeiou]y$/.test(word)) {
+		return `${word.slice(0, -1)}ies`;
+	}
+	if (/(s|x|z|ch|sh)$/.test(word)) {
+		return `${word}es`;
+	}
+	return `${word}s`;
+}
+
+/**
+ * Minimal English pluraliser. Hand-rolled (zero runtime deps).
+ *
+ * Multi-word kebab inputs only have their LAST segment pluralised:
+ *
+ *   user      -> users
+ *   blog-post -> blog-posts
+ *   super-man -> super-men
+ */
+export function pluralise(singular: string): string {
+	const segments = singular.split("-");
+	const last = segments[segments.length - 1];
+	segments[segments.length - 1] = pluraliseWord(last);
+	return segments.join("-");
+}

package/src/defineResource.ts

@@ -0,0 +1,126 @@
+import { kebabCase, pluralise, titleCase } from "./casing.js";
+import {
+	type AuditEvent,
+	type AuditSink,
+	type FormFieldOverride,
+	RESOURCE_ACTIONS,
+	type Resource,
+	type ResourceAction,
+	type ResourceOptions,
+} from "./types.js";
+
+const NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+const ACTION_LOOKUP: ReadonlySet<string> = new Set(RESOURCE_ACTIONS);
+
+function isResourceAction(value: unknown): value is ResourceAction {
+	return typeof value === "string" && ACTION_LOOKUP.has(value);
+}
+
+/**
+ * Build a frozen `Resource` from a developer's declaration.
+ *
+ * Validation is fail-fast and pre-HTTP: a typo in `actions` or `name` throws
+ * here, not at request time, so the offending key surfaces in boot logs.
+ */
+export function defineResource<T>(options: ResourceOptions<T>): Resource<T> {
+	if (typeof options.entity !== "function") {
+		throw new TypeError(
+			"[station] defineResource: 'entity' must be a class constructor",
+		);
+	}
+
+	if (options.actions !== undefined) {
+		if (!Array.isArray(options.actions) || options.actions.length === 0) {
+			throw new Error(
+				"[station] defineResource: 'actions' must contain at least one action",
+			);
+		}
+		for (const action of options.actions) {
+			if (!isResourceAction(action)) {
+				throw new Error(
+					`[station] defineResource: unknown action '${String(action)}' (allowed: list, show, create, edit, destroy)`,
+				);
+			}
+		}
+	}
+
+	if (options.name !== undefined && !NAME_PATTERN.test(options.name)) {
+		throw new Error(
+			`[station] defineResource: 'name' must be lowercase kebab-case (got: '${options.name}')`,
+		);
+	}
+
+	const entityName = options.entity.name;
+	if (entityName === "") {
+		throw new Error(
+			"[station] defineResource: 'entity' class has no name (anonymous class); pass 'name:' explicitly",
+		);
+	}
+	const slugBase = kebabCase(entityName);
+	const name = options.name ?? pluralise(slugBase);
+	if (options.name === undefined && !NAME_PATTERN.test(name)) {
+		throw new Error(
+			`[station] defineResource: entity name '${entityName}' produces invalid slug '${name}'; pass 'name:' explicitly to override`,
+		);
+	}
+	const label = options.label ?? titleCase(pluralise(slugBase));
+
+	const enabled: ReadonlySet<ResourceAction> =
+		options.actions === undefined
+			? new Set<ResourceAction>(RESOURCE_ACTIONS)
+			: new Set<ResourceAction>(options.actions);
+
+	const orderedActions: ReadonlyArray<ResourceAction> = Object.freeze(
+		RESOURCE_ACTIONS.filter((action) => enabled.has(action)),
+	);
+
+	// 54.5: validate per-field overrides — keyed by camelCase property
+	// name on the entity. Validation is shape-only here; the inferred
+	// form vs override merge happens at render time in views/form.ts.
+	const formFieldsRaw = options.formFields ?? {};
+	const formFields: Record<string, FormFieldOverride> = {};
+	for (const [field, override] of Object.entries(formFieldsRaw)) {
+		if (override === null || typeof override !== "object") {
+			throw new TypeError(
+				`[station] defineResource: 'formFields.${field}' must be an object`,
+			);
+		}
+		formFields[field] = override;
+	}
+
+	// 54.6: audit sink shape-check — if provided, must be callable. No
+	// extra validation; the sink is exercised lazily on first write.
+	let audit: AuditSink | undefined;
+	if (options.audit !== undefined) {
+		if (typeof options.audit !== "function") {
+			throw new TypeError(
+				`[station] defineResource: 'audit' must be a function (got ${typeof options.audit})`,
+			);
+		}
+		audit = options.audit;
+	}
+
+	// 54.6 hardening: optional audit-failure observability hook.
+	let onAuditError: ((event: AuditEvent, error: unknown) => void) | undefined;
+	if (options.onAuditError !== undefined) {
+		if (typeof options.onAuditError !== "function") {
+			throw new TypeError(
+				`[station] defineResource: 'onAuditError' must be a function (got ${typeof options.onAuditError})`,
+			);
+		}
+		onAuditError = options.onAuditError;
+	}
+
+	const resource: Resource<T> = {
+		entity: options.entity,
+		name,
+		label,
+		actions: orderedActions,
+		audit,
+		onAuditError,
+		formFields: Object.freeze(formFields),
+	};
+
+	return Object.freeze(resource);
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { kebabCase, pluralise, titleCase } from "./casing.js";
+export { defineResource } from "./defineResource.js";
+export { ResourceRegistry } from "./ResourceRegistry.js";
+export type { StationAppContext } from "./StationProvider.js";
+export { default as StationProvider } from "./StationProvider.js";
+export {
+	type AuditEvent,
+	type AuditSink,
+	type FormFieldOverride,
+	RESOURCE_ACTIONS,
+	type Resource,
+	type ResourceAction,
+	type ResourceOptions,
+} from "./types.js";

package/src/services/main.ts

@@ -0,0 +1,39 @@
+/**
+ * Default `ResourceRegistry` singleton — Adonis-style:
+ *
+ *   import station from '@c9up/station/services/main'
+ *
+ *   station.register(defineResource({ entity: User }))
+ *
+ * Populated either by `StationProvider.boot()` (lands in story 54.7) or by
+ * the app itself via `setStation(myRegistry)`.
+ */
+
+import type { ResourceRegistry } from "../ResourceRegistry.js";
+
+let instance: ResourceRegistry | undefined;
+
+/** @internal Bind the singleton (called by StationProvider or by the app). */
+export function setStation(value: ResourceRegistry): void {
+	instance = value;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getStation(): ResourceRegistry | undefined {
+	return instance;
+}
+
+const station: ResourceRegistry = new Proxy({} as ResourceRegistry, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[station] ResourceRegistry singleton accessed before StationProvider.boot() ran " +
+					"or `setStation(myRegistry)` was called. Wire one of them first.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default station;

package/src/types.ts

@@ -0,0 +1,108 @@
+export type ResourceAction = "list" | "show" | "create" | "edit" | "destroy";
+
+export const RESOURCE_ACTIONS: ReadonlyArray<ResourceAction> = Object.freeze([
+	"list",
+	"show",
+	"create",
+	"edit",
+	"destroy",
+]);
+
+/**
+ * Audit-trail event (Story 54.6). Emitted AFTER a write action lands
+ * successfully — on a 4xx/5xx the event does not fire (the action's
+ * effect is the boundary). `before` is present for `edit` and
+ * `destroy`; `after` is present for `create` and `edit`.
+ */
+export interface AuditEvent {
+	readonly action: ResourceAction;
+	readonly resource: string;
+	readonly recordId?: unknown;
+	readonly userId?: unknown;
+	readonly before?: Readonly<Record<string, unknown>>;
+	readonly after?: Readonly<Record<string, unknown>>;
+	readonly at: Date;
+}
+
+export type AuditSink = (event: AuditEvent) => void | Promise<void>;
+
+/**
+ * Per-field override for the auto-generated form (Story 54.5). Station
+ * infers the form from the entity's `@Column` metadata; consumers can
+ * override one column at a time without losing the inference for the
+ * others.
+ */
+export interface FormFieldOverride {
+	/** Hide the field from the form entirely (still rendered on show). */
+	hidden?: boolean;
+	/** Override the rendered `<input type>`. */
+	inputType?:
+		| "text"
+		| "number"
+		| "email"
+		| "password"
+		| "date"
+		| "datetime-local"
+		| "checkbox"
+		| "textarea";
+	/** Override the visible label (defaults to the column name title-cased). */
+	label?: string;
+	/** Add an `<input placeholder>`. */
+	placeholder?: string;
+	/** Mark the field as required at the HTML level. */
+	required?: boolean;
+}
+
+export interface ResourceOptions<TEntity> {
+	/** Entity class (Atlas `@Entity()`-decorated constructor). */
+	entity: new (
+		...args: never[]
+	) => TEntity;
+	/** Human-readable label shown in the admin sidebar (e.g. "Users"). */
+	label?: string;
+	/** Subset of actions to mount. Default: all five. */
+	actions?: ReadonlyArray<ResourceAction>;
+	/** URL slug override. Default: derived from the entity class name. */
+	name?: string;
+	/**
+	 * Audit sink invoked AFTER each successful write (Story 54.6). When
+	 * omitted, Station falls back to a once-per-process stderr warning
+	 * so apps don't silently lose audit visibility.
+	 */
+	audit?: AuditSink;
+	/**
+	 * Invoked when the audit sink throws (Story 54.6 hardening, retro
+	 * 2026-06-01). The mutation has already committed, so this is a
+	 * compliance-observability hook — emit an alert / enqueue a retry /
+	 * record the gap. Station does NOT block the user request on an audit
+	 * failure; without this handler the failure is logged at `error`
+	 * level. The handler is itself wrapped so a throwing handler can't
+	 * crash the request.
+	 */
+	onAuditError?: (event: AuditEvent, error: unknown) => void;
+	/**
+	 * Per-field overrides on top of the inferred form (Story 54.5).
+	 * Keyed by the entity's camelCase property name; absent keys keep
+	 * the inferred defaults.
+	 */
+	formFields?: Readonly<Record<string, FormFieldOverride>>;
+}
+
+export interface Resource<TEntity = unknown> {
+	/** The entity class passed in. */
+	readonly entity: new (
+		...args: never[]
+	) => TEntity;
+	/** URL slug — e.g. "users", "blog-posts". Always lowercase, kebab-case. */
+	readonly name: string;
+	/** Display label — e.g. "Users". Defaults to a title-cased pluralised entity name. */
+	readonly label: string;
+	/** Frozen list of enabled actions, in canonical order (list, show, create, edit, destroy). */
+	readonly actions: ReadonlyArray<ResourceAction>;
+	/** Optional audit sink (Story 54.6). */
+	readonly audit?: AuditSink;
+	/** Optional audit-failure observability hook (Story 54.6 hardening). */
+	readonly onAuditError?: (event: AuditEvent, error: unknown) => void;
+	/** Frozen per-field overrides for the inferred form (Story 54.5). */
+	readonly formFields: Readonly<Record<string, FormFieldOverride>>;
+}

package/src/views/errors/404.ts

@@ -0,0 +1,27 @@
+/**
+ * Station-branded 404 for `GET /admin/<slug>/:id` where the row doesn't
+ * exist. NOT used for unknown slugs (those fall through to Ream's
+ * default 404 — see story spec D6).
+ */
+
+import type { Resource } from "../../types.js";
+import { escapeHtml, safeHtml } from "../escape.js";
+import { renderLayout } from "../layout.js";
+
+export interface NotFoundPageInput {
+	resource: Resource;
+	id: string;
+}
+
+export function renderNotFoundPage(input: NotFoundPageInput): string {
+	const { resource, id } = input;
+	const slug = encodeURIComponent(resource.name);
+	const body =
+		`<h1>404 Not Found</h1>` +
+		`<p>No ${escapeHtml(resource.label.toLowerCase())} with ID <code>${escapeHtml(id)}</code>.</p>` +
+		`<a class="st-backlink" href="/admin/${slug}">← Back to ${escapeHtml(resource.label)}</a>`;
+	return renderLayout({
+		title: "Not Found",
+		bodyHtml: safeHtml(body),
+	});
+}

package/src/views/escape.ts

@@ -0,0 +1,46 @@
+/**
+ * HTML-escape helpers for Station's hand-rolled view layer.
+ *
+ * Every dynamic value interpolated into a `${…}` slot in a view template
+ * MUST flow through `escapeHtml()`. The lint sweep at
+ * `tests/unit/no-unescaped-interpolation.test.ts` enforces this on a
+ * grep-pass over `src/views/**` so a missing wrap surfaces as a failing
+ * test rather than a stored-XSS bug.
+ *
+ * `safeHtml()` is the escape hatch for pre-escaped fragments that views
+ * compose (e.g., the rendered body the layout helper splices into its
+ * shell). The branded shape (`{ readonly __safe: true; readonly html }`)
+ * makes the boundary explicit and lets the lint sweep skip lines that
+ * mention `__safe` as the only legitimate raw-HTML carrier.
+ */
+
+const ESCAPE_MAP: Readonly<Record<string, string>> = Object.freeze({
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	'"': "&quot;",
+	"'": "&#39;",
+});
+
+/** Escape a value for safe interpolation into HTML text or attribute content. */
+export function escapeHtml(value: unknown): string {
+	if (value === null || value === undefined) return "";
+	const str = typeof value === "string" ? value : String(value);
+	return str.replace(/[&<>"']/g, (ch) => ESCAPE_MAP[ch] ?? ch);
+}
+
+/**
+ * Branded wrapper marking a string as already HTML-escaped (or
+ * deliberately raw, e.g., the inline CSS block in the layout). The
+ * lint sweep that bans bare `${…}` interpolations excludes lines
+ * containing `__safe`.
+ */
+export interface SafeHtml {
+	readonly __safe: true;
+	readonly html: string;
+}
+
+/** Mark a string as pre-escaped / deliberately raw HTML. */
+export function safeHtml(html: string): SafeHtml {
+	return Object.freeze({ __safe: true as const, html });
+}

package/src/views/form.ts

@@ -0,0 +1,191 @@
+/**
+ * `GET /admin/<slug>/new` + `GET /admin/<slug>/:id/edit` — form view
+ * shared between the create and edit actions (Story 54.3).
+ *
+ * Field rendering is INFERRED from the entity's `@Column` metadata
+ * (Story 54.5): column type maps to an `<input type>`, boolean →
+ * checkbox, text-long → textarea, etc. The primary key and any
+ * timestamp columns (`created_at` / `updated_at` / `deleted_at`) are
+ * skipped from the form body. Per-field overrides declared on
+ * `Resource.formFields` win over the inferred defaults.
+ *
+ * Every dynamic value flows through `escapeHtml()` so a malicious
+ * column value rendered into an edit form cannot smuggle markup. The
+ * lint sweep at `tests/unit/no-unescaped-interpolation.test.ts`
+ * enforces the convention.
+ */
+
+import type { ColumnMetadata } from "@c9up/atlas";
+import type { FormFieldOverride, Resource } from "../types.js";
+import { escapeHtml, safeHtml } from "./escape.js";
+import { renderLayout } from "./layout.js";
+
+const SKIPPED_COLUMN_NAMES: ReadonlySet<string> = new Set([
+	"created_at",
+	"updated_at",
+	"deleted_at",
+]);
+
+export interface FormPageInput {
+	resource: Resource;
+	columns: ReadonlyArray<ColumnMetadata>;
+	pkColumn: string;
+	/** Existing row for edit; undefined for create. */
+	row?: Readonly<Record<string, unknown>>;
+	/** Validation errors keyed by column propertyKey. */
+	errors?: Readonly<Record<string, string>>;
+	/** Caller-controlled hidden inputs (e.g. CSRF token). */
+	hiddenInputs?: ReadonlyArray<{ name: string; value: string }>;
+}
+
+export function renderFormPage(input: FormPageInput): string {
+	const { resource, columns, pkColumn, row, errors, hiddenInputs } = input;
+	const isEdit = row !== undefined;
+	const slug = encodeURIComponent(resource.name);
+	const id = isEdit ? String(row[pkColumn] ?? "") : "";
+	const action = isEdit
+		? `/admin/${slug}/${encodeURIComponent(id)}`
+		: `/admin/${slug}`;
+	const methodOverride = isEdit
+		? `<input type="hidden" name="_method" value="PUT">`
+		: "";
+	const heading = isEdit
+		? `Edit ${escapeHtml(resource.label)} #${escapeHtml(id)}`
+		: `New ${escapeHtml(resource.label)}`;
+
+	const hiddens = (hiddenInputs ?? [])
+		.map(
+			(h) =>
+				`<input type="hidden" name="${escapeHtml(h.name)}" value="${escapeHtml(h.value)}">`,
+		)
+		.join("");
+
+	const fieldHtml = columns
+		.filter(
+			(c) => !shouldSkipColumn(c, pkColumn, resource.formFields[c.propertyKey]),
+		)
+		.map((c) => renderField(c, row, errors, resource.formFields[c.propertyKey]))
+		.join("");
+
+	const submitLabel = isEdit ? "Update" : "Create";
+	const cancelUrl = isEdit
+		? `/admin/${slug}/${encodeURIComponent(id)}`
+		: `/admin/${slug}`;
+
+	const body =
+		`<h1>${heading}</h1>` +
+		`<form class="st-form" method="POST" action="${escapeHtml(action)}">` +
+		methodOverride +
+		hiddens +
+		fieldHtml +
+		`<div class="st-form-actions">` +
+		`<button type="submit">${escapeHtml(submitLabel)}</button>` +
+		`<a class="st-cancel" href="${escapeHtml(cancelUrl)}">Cancel</a>` +
+		`</div>` +
+		`</form>`;
+
+	return renderLayout({
+		title: isEdit ? `Edit ${resource.label} #${id}` : `New ${resource.label}`,
+		bodyHtml: safeHtml(body),
+	});
+}
+
+function shouldSkipColumn(
+	c: ColumnMetadata,
+	pkColumn: string,
+	override: FormFieldOverride | undefined,
+): boolean {
+	if (override?.hidden === true) return true;
+	// Atlas's ColumnMetadata exposes the property key (camelCase). The
+	// pkColumn passed by the provider is also camelCase (it comes from
+	// `atlas.getPrimaryKey(entity)`), so the comparison is direct.
+	// snake_case fallbacks live in SKIPPED_COLUMN_NAMES below for the
+	// timestamps convention.
+	if (c.propertyKey === pkColumn) return true;
+	const snake = c.propertyKey.replace(/([A-Z])/g, "_$1").toLowerCase();
+	if (SKIPPED_COLUMN_NAMES.has(snake)) return true;
+	if (SKIPPED_COLUMN_NAMES.has(c.propertyKey)) return true;
+	return false;
+}
+
+function renderField(
+	c: ColumnMetadata,
+	row: Readonly<Record<string, unknown>> | undefined,
+	errors: Readonly<Record<string, string>> | undefined,
+	override: FormFieldOverride | undefined,
+): string {
+	const inputType = override?.inputType ?? inferInputType(c);
+	const labelText = override?.label ?? titleise(c.propertyKey);
+	const required = override?.required === true ? " required" : "";
+	const placeholder =
+		override?.placeholder !== undefined
+			? ` placeholder="${escapeHtml(override.placeholder)}"`
+			: "";
+	const name = c.propertyKey;
+	const fieldId = `f-${escapeHtml(name)}`;
+	const rawValue = row?.[name];
+	const errorMsg = errors?.[name];
+	const errorHtml =
+		errorMsg !== undefined
+			? `<p class="st-field-error">${escapeHtml(errorMsg)}</p>`
+			: "";
+
+	const input = renderInput(
+		inputType,
+		fieldId,
+		name,
+		rawValue,
+		required,
+		placeholder,
+	);
+
+	return (
+		`<div class="st-field">` +
+		`<label for="${escapeHtml(fieldId)}">${escapeHtml(labelText)}</label>` +
+		input +
+		errorHtml +
+		`</div>`
+	);
+}
+
+/** Render the `<input>` / `<textarea>` element for a field by input type. */
+function renderInput(
+	inputType: FormFieldOverride["inputType"],
+	fieldId: string,
+	name: string,
+	rawValue: unknown,
+	required: string,
+	placeholder: string,
+): string {
+	if (inputType === "checkbox") {
+		const checked = rawValue ? " checked" : "";
+		return `<input id="${escapeHtml(fieldId)}" type="checkbox" name="${escapeHtml(name)}" value="1"${checked}>`;
+	}
+	const value =
+		rawValue === undefined || rawValue === null ? "" : String(rawValue);
+	if (inputType === "textarea") {
+		return `<textarea id="${escapeHtml(fieldId)}" name="${escapeHtml(name)}"${required}${placeholder}>${escapeHtml(value)}</textarea>`;
+	}
+	return `<input id="${escapeHtml(fieldId)}" type="${escapeHtml(inputType)}" name="${escapeHtml(name)}" value="${escapeHtml(value)}"${required}${placeholder}>`;
+}
+
+function inferInputType(c: ColumnMetadata): FormFieldOverride["inputType"] {
+	const type = (c.type ?? "").toString().toLowerCase();
+	if (type === "boolean") return "checkbox";
+	if (type === "integer" || type === "bigint" || type === "number") {
+		return "number";
+	}
+	if (type === "date") return "date";
+	if (type === "datetime" || type === "timestamp") return "datetime-local";
+	if (type === "text" || type === "longtext") return "textarea";
+	const name = c.propertyKey.toLowerCase();
+	if (name.includes("email")) return "email";
+	if (name.includes("password")) return "password";
+	return "text";
+}
+
+function titleise(propertyKey: string): string {
+	// camelCase → "Camel Case"
+	const spaced = propertyKey.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}