@c9up/inker 0.1.6 → 0.1.7

package/src/helpers.ts

@@ -1,76 +0,0 @@
-import type { SafeString } from "./SafeString.js";
-
-/**
- * A caller-registered template helper. Receives the in-scope-evaluated
- * argument values and returns a string (HTML-escaped by the renderer) or a
- * `SafeString` (emitted verbatim). Re-homed here from the deleted `render.ts`
- * when the lex/parse/render hot path moved to the Rust engine (Story 55.1).
- *
- * NOTE (55.1): argument values are evaluated in the Rust engine and cross the
- * NAPI boundary as JSON, so they are JSON-coerced before reaching the helper:
- * a `Date` arrives as a string, a `bigint` as a (possibly lossy) number, and
- * `NaN` / `±Infinity` as `null`. Pass pre-stringified values for any type that
- * does not survive JSON if the helper needs the original form.
- */
-export type HelperFn = (...args: readonly unknown[]) => string | SafeString;
-
-/**
- * Signature for the canonical `t(key, params?)` helper.
- *
- * Inker ships ZERO body for this helper — implementations come from
- * the caller via `TemplatesOptions.helpers`. The Ream provider (Story
- * 53.5) wires this signature to `@c9up/rosetta`'s `Rosetta#t(key,
- * params?, options?)`.
- */
-export type THelper = (key: string, params?: Record<string, unknown>) => string;
-
-/**
- * Signature for the canonical `csrfField()` helper.
- *
- * Returns a `SafeString` containing the `<input type="hidden"
- * name="_csrf" value="…">` element. Returning a `SafeString` is
- * mandatory — a plain string would be HTML-escaped by the renderer
- * and the resulting `&lt;input …&gt;` would not be a usable form
- * field. Implementation is provided by the Ream provider (Story 53.5)
- * wiring the session's CSRF token.
- */
-export type CsrfFieldHelper = () => SafeString;
-
-/**
- * Signature for the canonical `csrfMeta()` helper.
- *
- * Returns a `SafeString` containing the `<meta name="csrf-token" …>` element
- * (for JS clients to read the token). Like `csrfField`, returning a `SafeString`
- * is mandatory so the renderer doesn't escape the markup. Provided by the Ream
- * provider wiring the session's CSRF token.
- */
-export type CsrfMetaHelper = () => SafeString;
-
-/**
- * Signature for the canonical `cspNonce()` helper.
- *
- * Returns the per-request Content-Security-Policy nonce (a plain string) so
- * inline `<script nonce="…">` tags match the response CSP header, or `""` when
- * no nonce is set. Provided by the Ream provider.
- */
-export type CspNonceHelper = () => string;
-
-/**
- * Signature for the canonical `url(name, params?)` helper.
- *
- * Resolves a named route + interpolates path params. Implementation
- * is provided by the Ream provider (Story 53.5) wiring the router.
- */
-export type UrlHelper = (
-	name: string,
-	params?: Record<string, unknown>,
-) => string;
-
-/**
- * Signature for the canonical `asset(name)` helper.
- *
- * Resolves an asset manifest entry to its hashed public URL.
- * Implementation is provided by the Ream provider (Story 53.5) wiring
- * the asset manifest.
- */
-export type AssetHelper = (name: string) => string;

package/src/identifierGuards.ts

@@ -1,49 +0,0 @@
-/**
- * Identifier denylists shared between `parseBlockTag.ts` (each-binding +
- * component-arg-key validation) and `parseExpression.ts` (object-literal
- * key validation).
- *
- * `PROTOTYPE_POLLUTION_KEYS` blocks the three keys whose own-property
- * assignment can shadow `Object.prototype` methods or invoke
- * `Object.create` semantics in surprising ways. The gate is
- * defence-in-depth: JavaScript's `obj[key] = value` semantics make
- * `__proto__` non-exploitable when used via square brackets on a
- * non-frozen object built via `Object.create(null)`, but template
- * authors cannot reason about the renderer's storage shape and the
- * cost of the guard is one Set membership check per object key.
- *
- * `RESERVED_BINDING_NAMES` blocks identifiers that would collide with
- * Inker grammar keywords (e.g. `as`) or JavaScript reserved words when
- * used as `{% each items as <name> %}` bindings or `{% each items as
- * [<a>, <b>] %}` destructured names. The block is per-position rather
- * than universal — Inker permits these names inside path expressions
- * since paths cannot collide with the grammar.
- */
-export const PROTOTYPE_POLLUTION_KEYS: ReadonlySet<string> = new Set([
-	"__proto__",
-	"constructor",
-	"prototype",
-]);
-
-export const RESERVED_BINDING_NAMES: ReadonlySet<string> = new Set([
-	"as",
-	"if",
-	"else",
-	"each",
-	"do",
-	"for",
-	"while",
-	"let",
-	"const",
-	"var",
-	"return",
-	"function",
-	"class",
-	"new",
-	"this",
-	"super",
-	"null",
-	"undefined",
-	"true",
-	"false",
-]);

package/src/index.ts

@@ -1,16 +0,0 @@
-export type {
-	AssetHelper,
-	CspNonceHelper,
-	CsrfFieldHelper,
-	CsrfMetaHelper,
-	HelperFn,
-	THelper,
-	UrlHelper,
-} from "./helpers.js";
-export {
-	type InkerErrorCode,
-	type InkerErrorContext,
-	InkerRenderError,
-} from "./InkerRenderError.js";
-export { SafeString } from "./SafeString.js";
-export { Templates, type TemplatesOptions } from "./Templates.js";

package/src/loadNapi.ts

@@ -1,270 +0,0 @@
-// PATTERN: copy-and-rename for 55.2/55.3/55.4 — Rust hot-path packages.
-//
-// Loads the native `inker-engine-napi` binary built by `scripts/copy-napi.mjs`
-// and re-throws load failures as `E_INKER_NAPI_REQUIRED` per cerebrum
-// NAPI-loader pattern (2026-04-27) — actionable hint points at
-// `pnpm --filter @c9up/inker build:napi`.
-//
-// Per cerebrum 2026-04-15 there is NO JS fallback. If the binary fails to
-// load, consumers get a typed error. Zero `as` / `any` per cerebrum 2026-05-04.
-
-import { createRequire } from "node:module";
-import { arch, platform } from "node:process";
-import { fileURLToPath } from "node:url";
-import { type InkerErrorCode, InkerRenderError } from "./InkerRenderError.js";
-
-const SUFFIX_MAP: Readonly<Record<string, string>> = {
-	"linux-x64": "linux-x64-gnu",
-	"linux-arm64": "linux-arm64-gnu",
-	"darwin-x64": "darwin-x64",
-	"darwin-arm64": "darwin-arm64",
-	"win32-x64": "win32-x64-msvc",
-};
-
-function platformSuffix(): string {
-	const key = `${platform}-${arch}`;
-	const suffix = SUFFIX_MAP[key];
-	if (typeof suffix !== "string") {
-		throw new InkerRenderError(
-			"E_INKER_NAPI_REQUIRED",
-			`Unsupported platform/arch '${key}' for @c9up/inker native binary. Supported: ${Object.keys(SUFFIX_MAP).join(", ")}.`,
-		);
-	}
-	return suffix;
-}
-
-/** A `{% include %}` / `{% component %}` reference with source position. */
-export interface NapiNodeRef {
-	readonly name: string;
-	readonly line: number;
-	readonly column: number;
-}
-
-/** A `{{> name }}` slot reference. */
-export interface NapiSlotRef {
-	readonly name: string;
-	readonly line: number;
-	readonly column: number;
-}
-
-/** First disk-requiring node (`renderString` E_INKER_DISK_REQUIRED guard). */
-export interface NapiDiskNodeRef {
-	readonly kind: string;
-	readonly name: string;
-}
-
-/** All composition metadata for one parsed AST (one NAPI call). */
-export interface NapiComposeInfo {
-	readonly hasLayout: boolean;
-	readonly layoutName: string | null;
-	readonly layoutLine: number | null;
-	readonly layoutColumn: number | null;
-	readonly slots: readonly NapiSlotRef[];
-	readonly partials: readonly NapiNodeRef[];
-	readonly components: readonly NapiNodeRef[];
-	readonly hasContent: boolean;
-	readonly firstDiskNode: NapiDiskNodeRef | null;
-}
-
-/** Opaque handle to a parsed Rust AST. */
-export interface NapiInkerAst {
-	readonly composeInfo: NapiComposeInfo;
-}
-
-/** One in-scope-evaluated helper invocation request (collect pass). */
-export interface NapiInvocation {
-	readonly id: number;
-	readonly name: string;
-	/** JSON array of the evaluated argument values. */
-	readonly args: readonly unknown[];
-}
-
-/** One pre-resolved helper result (consumed in tape order by the renderer). */
-export interface NapiHelperResult {
-	readonly value: string;
-	readonly isSafe: boolean;
-}
-
-export interface NapiRenderContext {
-	readonly partials: Record<string, NapiInkerAst>;
-	readonly components: Record<string, NapiInkerAst>;
-	readonly bodyHtml: string | undefined;
-	readonly templateName: string | undefined;
-	readonly templatePath: string | undefined;
-}
-
-interface NativeExports {
-	readonly engineVersion: () => string;
-	readonly parseTemplate: (
-		source: string,
-		helpers: readonly string[],
-	) => NapiInkerAst;
-	readonly collectInvocations: (
-		ast: NapiInkerAst,
-		data: unknown,
-		ctx: NapiRenderContext,
-	) => NapiInvocation[];
-	readonly renderAst: (
-		ast: NapiInkerAst,
-		data: unknown,
-		resolved: readonly NapiHelperResult[],
-		ctx: NapiRenderContext,
-	) => string;
-}
-
-function isNativeExports(value: unknown): value is NativeExports {
-	if (value === null || typeof value !== "object") return false;
-	return (
-		typeof Reflect.get(value, "engineVersion") === "function" &&
-		typeof Reflect.get(value, "parseTemplate") === "function" &&
-		typeof Reflect.get(value, "collectInvocations") === "function" &&
-		typeof Reflect.get(value, "renderAst") === "function"
-	);
-}
-
-let cachedNative: NativeExports | undefined;
-
-export function getNative(): NativeExports {
-	if (cachedNative !== undefined) return cachedNative;
-
-	const require = createRequire(import.meta.url);
-	const here = fileURLToPath(import.meta.url);
-	// `here` is `…/packages/inker/{src,dist}/loadNapi.ts|js`. The `.node` lives
-	// one level up at `…/packages/inker/index.<suffix>.node`. `..` traversal
-	// resolved via require (handles both dev `src/` and publish `dist/`).
-	const suffix = platformSuffix();
-	const candidates: readonly string[] = [`../index.${suffix}.node`];
-	let loaded: unknown;
-	let lastErr: unknown;
-	for (const candidate of candidates) {
-		try {
-			loaded = require(candidate);
-			break;
-		} catch (err) {
-			lastErr = err;
-		}
-	}
-	if (loaded === undefined) {
-		const causeMessage =
-			lastErr instanceof Error ? lastErr.message : String(lastErr);
-		// The prebuilt linux binaries target glibc (`-gnu`). On musl hosts (Alpine
-		// containers) the `-gnu` binary fails to dlopen with a libc symbol error —
-		// surface that explicitly rather than only pointing at the build step.
-		const muslHint = suffix.endsWith("-gnu")
-			? " If you are on Alpine/musl, note the prebuilt binaries target glibc (musl is not a supported target)."
-			: "";
-		throw new InkerRenderError(
-			"E_INKER_NAPI_REQUIRED",
-			`@c9up/inker native binary 'index.${suffix}.node' not found or failed to load near ${here} — run 'pnpm --filter @c9up/inker build:napi' to build it.${muslHint} Cause: ${causeMessage}`,
-			undefined,
-			{ cause: lastErr },
-		);
-	}
-	if (!isNativeExports(loaded)) {
-		throw new InkerRenderError(
-			"E_INKER_NAPI_REQUIRED",
-			`@c9up/inker native binary loaded but missing expected exports (engineVersion / parseTemplate / renderAst). Rebuild with 'pnpm --filter @c9up/inker build:napi'.`,
-		);
-	}
-	cachedNative = loaded;
-	return cachedNative;
-}
-
-/**
- * Shape of the JSON payload Rust packs into `napi::Error::from_reason`. Rust
- * guarantees `code` / `message` present; positional fields optional.
- */
-interface NapiErrorPayload {
-	readonly code: string;
-	readonly message: string;
-	readonly line?: number;
-	readonly column?: number;
-	readonly templateName?: string;
-}
-
-function readString(target: unknown, key: string): string | undefined {
-	const v = Reflect.get(Object(target), key);
-	return typeof v === "string" ? v : undefined;
-}
-
-function readNumber(target: unknown, key: string): number | undefined {
-	const v = Reflect.get(Object(target), key);
-	return typeof v === "number" ? v : undefined;
-}
-
-function isNapiErrorPayload(value: unknown): value is NapiErrorPayload {
-	if (value === null || typeof value !== "object") return false;
-	return (
-		typeof Reflect.get(value, "code") === "string" &&
-		typeof Reflect.get(value, "message") === "string"
-	);
-}
-
-const CODE_MAP: Readonly<Record<string, InkerErrorCode>> = {
-	E_INKER_TEMPLATE_NOT_FOUND: "E_INKER_TEMPLATE_NOT_FOUND",
-	E_INKER_PARSE_ERROR: "E_INKER_PARSE_ERROR",
-	E_INKER_UNKNOWN_IDENTIFIER: "E_INKER_UNKNOWN_IDENTIFIER",
-	E_INKER_INVALID_PATH: "E_INKER_INVALID_PATH",
-	E_INKER_UNCLOSED_INTERPOLATION: "E_INKER_UNCLOSED_INTERPOLATION",
-	E_INKER_UNCLOSED_BLOCK_TAG: "E_INKER_UNCLOSED_BLOCK_TAG",
-	E_INKER_UNKNOWN_DIRECTIVE: "E_INKER_UNKNOWN_DIRECTIVE",
-	E_INKER_INVALID_LAYOUT_POSITION: "E_INKER_INVALID_LAYOUT_POSITION",
-	E_INKER_DUPLICATE_LAYOUT: "E_INKER_DUPLICATE_LAYOUT",
-	E_INKER_NESTED_LAYOUT_UNSUPPORTED: "E_INKER_NESTED_LAYOUT_UNSUPPORTED",
-	E_INKER_LAYOUT_IN_PARTIAL: "E_INKER_LAYOUT_IN_PARTIAL",
-	E_INKER_CIRCULAR_INCLUDE: "E_INKER_CIRCULAR_INCLUDE",
-	E_INKER_MISSING_SLOT: "E_INKER_MISSING_SLOT",
-	E_INKER_UNKNOWN_SLOT: "E_INKER_UNKNOWN_SLOT",
-	E_INKER_DISK_REQUIRED: "E_INKER_DISK_REQUIRED",
-	E_INKER_UNCLOSED_BLOCK: "E_INKER_UNCLOSED_BLOCK",
-	E_INKER_UNMATCHED_BLOCK_END: "E_INKER_UNMATCHED_BLOCK_END",
-	E_INKER_MISMATCHED_BLOCK_END: "E_INKER_MISMATCHED_BLOCK_END",
-	E_INKER_INVALID_EXPRESSION: "E_INKER_INVALID_EXPRESSION",
-	E_INKER_INVALID_ITERABLE: "E_INKER_INVALID_ITERABLE",
-	E_INKER_UNKNOWN_HELPER: "E_INKER_UNKNOWN_HELPER",
-	E_INKER_HELPER_THROW: "E_INKER_HELPER_THROW",
-	E_INKER_NAPI_REQUIRED: "E_INKER_NAPI_REQUIRED",
-};
-
-/**
- * Translate a thrown value from a NAPI call into an `InkerRenderError`.
- * If it's already an `InkerRenderError` (helper threw and propagated), pass through.
- * If it's a `napi::Error` carrying our JSON envelope, reconstruct typed.
- * Otherwise wrap as parse error.
- */
-export function napiThrowToInker(err: unknown): InkerRenderError {
-	if (err instanceof InkerRenderError) return err;
-	if (err instanceof Error) {
-		let parsed: unknown;
-		try {
-			parsed = JSON.parse(err.message);
-		} catch {
-			parsed = undefined;
-		}
-		if (isNapiErrorPayload(parsed)) {
-			const code = CODE_MAP[parsed.code];
-			if (code !== undefined) {
-				return new InkerRenderError(
-					code,
-					parsed.message,
-					{
-						line: readNumber(parsed, "line"),
-						column: readNumber(parsed, "column"),
-						templateName: readString(parsed, "templateName"),
-					},
-					{ cause: err },
-				);
-			}
-		}
-		return new InkerRenderError(
-			"E_INKER_PARSE_ERROR",
-			`Native call failed: ${err.message}`,
-			undefined,
-			{ cause: err },
-		);
-	}
-	return new InkerRenderError(
-		"E_INKER_PARSE_ERROR",
-		`Native call failed with non-Error: ${String(err)}`,
-	);
-}

package/src/services/main.ts

@@ -1,56 +0,0 @@
-/**
- * Default `InkerRenderer` singleton — Adonis-style:
- *
- *   import inker from '@c9up/inker/provider/services/main'
- *
- *   await inker.render(ctx, 'invoice', { user })
- *
- * Populated by `InkerProvider.start()` (registered via reamrc.ts) or by the
- * app itself via `setInker(myRenderer)`.
- */
-
-import type { InkerRenderer } from "../InkerRenderer.js";
-
-let instance: InkerRenderer | undefined;
-
-/**
- * @internal Bind (or clear) the singleton. Called by InkerProvider.start() to
- * wire the renderer, or by tests passing `undefined` to reset between cases
- * (the type field already permits `undefined`, so the signature mirrors it
- * honestly rather than requiring a `bypassTypeCheck` cast at every call site).
- */
-export function setInker(renderer: InkerRenderer | undefined): void {
-	instance = renderer;
-}
-
-/** @internal Read the singleton (or `undefined` pre-boot). */
-export function getInker(): InkerRenderer | undefined {
-	return instance;
-}
-
-// Sanctioned `as InkerRenderer` site — typed-Proxy idiom shared by
-// station/rosetta/aurora/inker `services/main.ts`. Every property access is
-// guarded by the `instance` check below, so the cast is structural and
-// bounded. DNR `feedback_no_any_types` documents this as one of two
-// permitted `as` patterns alongside `loadBearingCast` in `InkerProvider.ts`.
-const inker: InkerRenderer = new Proxy({} as InkerRenderer, {
-	get(_target, prop) {
-		// Short-circuit the thenable probe: an accidental `await mod.default`
-		// (or `Promise.resolve(mod.default)`) would otherwise trigger our
-		// pre-boot throw inside the await machinery and surface a confusing
-		// rejected Promise. Returning `undefined` makes the value plainly
-		// non-thenable, so the caller's await resolves immediately to the
-		// Proxy itself — subsequent real property access still throws.
-		if (prop === "then") return undefined;
-		if (!instance) {
-			throw new Error(
-				"[inker] InkerRenderer singleton accessed before InkerProvider.start() ran " +
-					"or `setInker(myRenderer)` was called. Wire one of them first.",
-			);
-		}
-		const value = Reflect.get(instance, prop, instance);
-		return typeof value === "function" ? value.bind(instance) : value;
-	},
-});
-
-export default inker;