@contentrail/reader 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# `@contentrail/reader`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js / build-time reader for local JSON content. Validates entries with `@contentrail/core`.
+
+**Not browser-safe.** Do not import this package from client bundles. Use it in Astro frontmatter, Vite plugins, or other build-time Node code.
+
+## Requirements
+
+- Node.js **≥ 22**
+- `@contentrail/core` (and Zod via core)
+
+## Install
+
+> **Not on the public npm registry yet.** See `docs/PUBLISHING.md`.
+
+### Monorepo (current)
+
+```sh
+pnpm install
+pnpm --filter @contentrail/reader build
+```
+
+### Intended after first public `0.1.0` release
+
+```sh
+pnpm add @contentrail/core @contentrail/reader zod
+```
+
+## Layout
+
+```text
+{rootDir}/
+  {collection.name}/
+    {entryId}.json
+```
+
+Example: `content/articles/welcome.json`
+
+## Usage
+
+```ts
+import { defineCollection } from "@contentrail/core";
+import {
+  createLocalJsonSource,
+  loadCollection,
+  loadEntry,
+} from "@contentrail/reader";
+import { z } from "zod";
+
+const articles = defineCollection({
+  name: "articles",
+  schema: z.object({
+    title: z.string().min(1),
+    slug: z.string().min(1),
+    published: z.boolean(),
+  }),
+});
+
+const source = await createLocalJsonSource({ rootDir: "./content" });
+const all = await loadCollection(source, articles);
+const one = await loadEntry(source, articles, "welcome");
+```
+
+## Behaviour
+
+| Case                         | Result                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| Valid files                  | Returned as `{ id, sourcePath, data }`                                 |
+| Empty collection directory   | `[]`                                                                   |
+| Missing collection directory | `ContentReadError` `MISSING_COLLECTION`                                |
+| Missing entry file           | `ContentReadError` `MISSING_ENTRY`                                     |
+| Malformed JSON               | `ContentReadError` `INVALID_JSON`                                      |
+| Schema failure               | `ContentReadError` `INVALID_ENTRY` (cause is `ContentValidationError`) |
+| Path escape / unsafe segment | `ContentReadError` `PATH_ESCAPE`                                       |
+| Duplicate file ids           | `ContentReadError` `DUPLICATE_ID`                                      |
+| Duplicate `slug` values      | `ContentReadError` `DUPLICATE_SLUG` (disable with `uniqueBy: null`)    |
+
+Default sort: entry `id` ascending. Invalid content always fails the load (no silent skip).
+
+## Compatibility
+
+- Node.js 22+
+- ESM only
+- Depends on `@contentrail/core` (Zod schemas)

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+import type { ContentValidationError } from "@contentrail/core";
+export type ContentReadErrorCode = "INVALID_ROOT" | "PATH_ESCAPE" | "MISSING_COLLECTION" | "MISSING_ENTRY" | "INVALID_JSON" | "INVALID_ENTRY" | "DUPLICATE_ID" | "DUPLICATE_SLUG" | "EMPTY_ID";
+export declare class ContentReadError extends Error {
+    readonly code: ContentReadErrorCode;
+    readonly collection?: string;
+    readonly entryId?: string;
+    readonly path?: string;
+    constructor(code: ContentReadErrorCode, message: string, options?: {
+        collection?: string;
+        entryId?: string;
+        path?: string;
+        cause?: unknown;
+    });
+}
+export declare function isContentValidationError(error: unknown): error is ContentValidationError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,MAAM,MAAM,oBAAoB,GAC5B,cAAc,GACd,aAAa,GACb,oBAAoB,GACpB,eAAe,GACf,cAAc,GACd,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,UAAU,CAAC;AAEf,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAGrB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;CAkBT;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,sBAAsB,CAOjC"}

package/dist/errors.js

@@ -0,0 +1,27 @@
+export class ContentReadError extends Error {
+    code;
+    collection;
+    entryId;
+    path;
+    constructor(code, message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "ContentReadError";
+        this.code = code;
+        if (options.collection !== undefined) {
+            this.collection = options.collection;
+        }
+        if (options.entryId !== undefined) {
+            this.entryId = options.entryId;
+        }
+        if (options.path !== undefined) {
+            this.path = options.path;
+        }
+    }
+}
+export function isContentValidationError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "CONTENT_VALIDATION_ERROR");
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAaA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAuB;IAC3B,UAAU,CAAU;IACpB,OAAO,CAAU;IACjB,IAAI,CAAU;IAEvB,YACE,IAA0B,EAC1B,OAAe,EACf,UAKI,EAAE;QAEN,KAAK,CACH,OAAO,EACP,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CACnE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACrC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACvC,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACjC,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,wBAAwB,CACtC,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACd,KAA2B,CAAC,IAAI,KAAK,0BAA0B,CACjE,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ContentReadError, type ContentReadErrorCode } from "./errors.js";
+export { createLocalJsonSource } from "./source.js";
+export { loadCollection, loadEntry } from "./load.js";
+export type { ContentRailEntry, LoadCollectionOptions, LocalJsonSource, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { ContentReadError } from "./errors.js";
+export { createLocalJsonSource } from "./source.js";
+export { loadCollection, loadEntry } from "./load.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAA6B,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/load.d.ts

@@ -0,0 +1,16 @@
+import { type ContentCollection } from "@contentrail/core";
+import type { ContentRailEntry, LoadCollectionOptions, LocalJsonSource } from "./types.js";
+/**
+ * Loads and validates a single entry from `{root}/{collection}/{id}.json`.
+ */
+export declare function loadEntry<TCollection extends ContentCollection>(source: LocalJsonSource, collection: TCollection, id: string): Promise<ContentRailEntry<TCollection>>;
+/**
+ * Loads every `*.json` file in `{root}/{collection}/`, validates each entry,
+ * and returns them in deterministic order (by `id` ascending by default).
+ *
+ * An existing empty collection directory yields an empty array.
+ * A missing collection directory fails with `MISSING_COLLECTION`.
+ * Invalid JSON or schema failures fail the whole load (no silent skip).
+ */
+export declare function loadCollection<TCollection extends ContentCollection>(source: LocalJsonSource, collection: TCollection, options?: LoadCollectionOptions): Promise<Array<ContentRailEntry<TCollection>>>;
+//# sourceMappingURL=load.d.ts.map

package/dist/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,iBAAiB,EAAiB,MAAM,mBAAmB,CAAC;AAO1E,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EAChB,MAAM,YAAY,CAAC;AAkEpB;;GAEG;AACH,wBAAsB,SAAS,CAAC,WAAW,SAAS,iBAAiB,EACnE,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,WAAW,EACvB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAqCxC;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,WAAW,SAAS,iBAAiB,EACxE,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,WAAW,EACvB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CA+D/C"}

package/dist/load.js

@@ -0,0 +1,153 @@
+import fs from "node:fs/promises";
+import { validateEntry } from "@contentrail/core";
+import { ContentReadError } from "./errors.js";
+import { assertSafeSegment, entryIdFromFileName, resolveUnderRoot, } from "./paths.js";
+function assertSource(source) {
+    if (source === null ||
+        typeof source !== "object" ||
+        source.kind !== "local-json" ||
+        typeof source.rootDir !== "string") {
+        throw new TypeError("Expected a LocalJsonSource from createLocalJsonSource().");
+    }
+}
+async function readJsonFile(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        throw new ContentReadError("MISSING_ENTRY", `Unable to read content file: ${filePath}`, { path: filePath, cause: error });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ContentReadError("INVALID_JSON", `Malformed JSON in content file: ${filePath}`, { path: filePath, cause: error });
+    }
+}
+async function loadValidatedEntry(source, collection, id, filePath) {
+    const json = await readJsonFile(filePath);
+    const result = validateEntry(collection, json);
+    if (!result.success) {
+        throw new ContentReadError("INVALID_ENTRY", `Invalid content for collection "${collection.name}" entry "${id}": ${result.error.message}`, {
+            collection: collection.name,
+            entryId: id,
+            path: filePath,
+            cause: result.error,
+        });
+    }
+    return Object.freeze({
+        id,
+        sourcePath: filePath,
+        data: result.data,
+    });
+}
+/**
+ * Loads and validates a single entry from `{root}/{collection}/{id}.json`.
+ */
+export async function loadEntry(source, collection, id) {
+    assertSource(source);
+    assertSafeSegment(collection.name, "collection name");
+    assertSafeSegment(id, "entry id");
+    let filePath;
+    try {
+        filePath = await resolveUnderRoot(source.rootDir, [collection.name, `${id}.json`], { mustExist: true });
+    }
+    catch (error) {
+        if (error instanceof ContentReadError && error.code === "PATH_ESCAPE") {
+            throw error;
+        }
+        throw new ContentReadError("MISSING_ENTRY", `Content entry not found: ${collection.name}/${id}.json`, {
+            collection: collection.name,
+            entryId: id,
+            cause: error,
+        });
+    }
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) {
+        throw new ContentReadError("MISSING_ENTRY", `Content entry path is not a file: ${filePath}`, { collection: collection.name, entryId: id, path: filePath });
+    }
+    return loadValidatedEntry(source, collection, id, filePath);
+}
+/**
+ * Loads every `*.json` file in `{root}/{collection}/`, validates each entry,
+ * and returns them in deterministic order (by `id` ascending by default).
+ *
+ * An existing empty collection directory yields an empty array.
+ * A missing collection directory fails with `MISSING_COLLECTION`.
+ * Invalid JSON or schema failures fail the whole load (no silent skip).
+ */
+export async function loadCollection(source, collection, options = {}) {
+    assertSource(source);
+    assertSafeSegment(collection.name, "collection name");
+    let collectionDir;
+    try {
+        collectionDir = await resolveUnderRoot(source.rootDir, [collection.name], {
+            mustExist: true,
+        });
+    }
+    catch (error) {
+        if (error instanceof ContentReadError && error.code === "PATH_ESCAPE") {
+            throw error;
+        }
+        throw new ContentReadError("MISSING_COLLECTION", `Content collection directory not found: ${collection.name}`, { collection: collection.name, cause: error });
+    }
+    const dirStat = await fs.stat(collectionDir);
+    if (!dirStat.isDirectory()) {
+        throw new ContentReadError("MISSING_COLLECTION", `Content collection path is not a directory: ${collectionDir}`, { collection: collection.name, path: collectionDir });
+    }
+    const dirents = await fs.readdir(collectionDir, { withFileTypes: true });
+    const jsonFiles = dirents
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+    const entries = [];
+    const seenIds = new Set();
+    for (const fileName of jsonFiles) {
+        const id = entryIdFromFileName(fileName);
+        if (seenIds.has(id)) {
+            throw new ContentReadError("DUPLICATE_ID", `Duplicate entry id "${id}" in collection "${collection.name}".`, { collection: collection.name, entryId: id });
+        }
+        seenIds.add(id);
+        const filePath = await resolveUnderRoot(source.rootDir, [collection.name, fileName], { mustExist: true });
+        entries.push(await loadValidatedEntry(source, collection, id, filePath));
+    }
+    const uniqueBy = options.uniqueBy === undefined ? "slug" : options.uniqueBy;
+    if (uniqueBy !== null) {
+        assertUniqueField(collection.name, entries, uniqueBy);
+    }
+    return sortEntries(entries, options);
+}
+function assertUniqueField(collectionName, entries, field) {
+    const seen = new Map();
+    for (const entry of entries) {
+        const value = entry.data[field];
+        if (value === undefined) {
+            continue;
+        }
+        if (typeof value !== "string") {
+            continue;
+        }
+        const previous = seen.get(value);
+        if (previous !== undefined) {
+            throw new ContentReadError("DUPLICATE_SLUG", `Duplicate "${field}" value "${value}" in collection "${collectionName}" (entries "${previous}" and "${entry.id}").`, { collection: collectionName, entryId: entry.id });
+        }
+        seen.set(value, entry.id);
+    }
+}
+function sortEntries(entries, options) {
+    const sortBy = options.sortBy ?? "id";
+    const sortOrder = options.sortOrder ?? "asc";
+    const direction = sortOrder === "desc" ? -1 : 1;
+    const sorted = [...entries].sort((left, right) => {
+        const leftValue = sortBy === "id"
+            ? left.id
+            : String(left.data[sortBy] ?? "");
+        const rightValue = sortBy === "id"
+            ? right.id
+            : String(right.data[sortBy] ?? "");
+        return leftValue.localeCompare(rightValue) * direction;
+    });
+    return sorted;
+}
+//# sourceMappingURL=load.js.map

package/dist/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"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"}

package/dist/paths.d.ts

@@ -0,0 +1,12 @@
+export declare function resolveRootDir(rootDir: string): Promise<string>;
+export declare function assertSafeSegment(segment: string, label: string): void;
+/**
+ * Joins segments under root and ensures the normalized path stays inside root.
+ * When the path exists, resolves symlinks via realpath and re-checks containment.
+ */
+export declare function resolveUnderRoot(rootDir: string, segments: readonly string[], options?: {
+    mustExist?: boolean;
+}): Promise<string>;
+export declare function isPathInsideRoot(rootDir: string, candidate: string): boolean;
+export declare function entryIdFromFileName(fileName: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAMA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BrE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAetE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACpC,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAQ5E;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU5D"}

package/dist/paths.js

@@ -0,0 +1,84 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ContentReadError } from "./errors.js";
+const SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export async function resolveRootDir(rootDir) {
+    if (typeof rootDir !== "string" || rootDir.trim() === "") {
+        throw new ContentReadError("INVALID_ROOT", 'Local JSON source requires a non-empty "rootDir" string.');
+    }
+    const absolute = path.resolve(rootDir);
+    try {
+        const real = await fs.realpath(absolute);
+        const stat = await fs.stat(real);
+        if (!stat.isDirectory()) {
+            throw new ContentReadError("INVALID_ROOT", `Content root is not a directory: ${real}`, { path: real });
+        }
+        return real;
+    }
+    catch (error) {
+        if (error instanceof ContentReadError) {
+            throw error;
+        }
+        throw new ContentReadError("INVALID_ROOT", `Content root does not exist or is not readable: ${absolute}`, { path: absolute, cause: error });
+    }
+}
+export function assertSafeSegment(segment, label) {
+    if (segment === "" ||
+        segment === "." ||
+        segment === ".." ||
+        segment.includes("/") ||
+        segment.includes("\\") ||
+        segment.includes("\0") ||
+        !SEGMENT_PATTERN.test(segment)) {
+        throw new ContentReadError("PATH_ESCAPE", `Unsafe ${label} segment rejected: ${JSON.stringify(segment)}`);
+    }
+}
+/**
+ * Joins segments under root and ensures the normalized path stays inside root.
+ * When the path exists, resolves symlinks via realpath and re-checks containment.
+ */
+export async function resolveUnderRoot(rootDir, segments, options = {}) {
+    for (const segment of segments) {
+        assertSafeSegment(segment, "path");
+    }
+    const joined = path.resolve(rootDir, ...segments);
+    if (!isPathInsideRoot(rootDir, joined)) {
+        throw new ContentReadError("PATH_ESCAPE", `Resolved path escapes content root: ${joined}`, { path: joined });
+    }
+    if (options.mustExist === false) {
+        return joined;
+    }
+    try {
+        const real = await fs.realpath(joined);
+        if (!isPathInsideRoot(rootDir, real)) {
+            throw new ContentReadError("PATH_ESCAPE", `Resolved path escapes content root after symlink resolution: ${real}`, { path: real });
+        }
+        return real;
+    }
+    catch (error) {
+        if (error instanceof ContentReadError) {
+            throw error;
+        }
+        if (options.mustExist === true) {
+            throw error;
+        }
+        // Path does not exist yet — return the verified joined path.
+        return joined;
+    }
+}
+export function isPathInsideRoot(rootDir, candidate) {
+    const relative = path.relative(rootDir, candidate);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+export function entryIdFromFileName(fileName) {
+    if (!fileName.endsWith(".json")) {
+        throw new ContentReadError("EMPTY_ID", `Content files must use a .json extension: ${fileName}`);
+    }
+    const id = fileName.slice(0, -".json".length);
+    assertSafeSegment(id, "entry id");
+    return id;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/source.d.ts

@@ -0,0 +1,15 @@
+import type { LocalJsonSource } from "./types.js";
+/**
+ * Creates a local JSON content source rooted at `rootDir`.
+ *
+ * Layout:
+ * ```text
+ * {rootDir}/{collection.name}/{entryId}.json
+ * ```
+ *
+ * This API is Node.js / build-time only. Do not import it from browser bundles.
+ */
+export declare function createLocalJsonSource(options: {
+    rootDir: string;
+}): Promise<LocalJsonSource>;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,eAAe,CAAC,CAM3B"}

package/dist/source.js

@@ -0,0 +1,19 @@
+import { resolveRootDir } from "./paths.js";
+/**
+ * Creates a local JSON content source rooted at `rootDir`.
+ *
+ * Layout:
+ * ```text
+ * {rootDir}/{collection.name}/{entryId}.json
+ * ```
+ *
+ * This API is Node.js / build-time only. Do not import it from browser bundles.
+ */
+export async function createLocalJsonSource(options) {
+    const rootDir = await resolveRootDir(options.rootDir);
+    return Object.freeze({
+        kind: "local-json",
+        rootDir,
+    });
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAE3C;IACC,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,YAAqB;QAC3B,OAAO;KACR,CAAC,CAAC;AACL,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+import type { ContentCollection, InferEntry } from "@contentrail/core";
+export interface LocalJsonSource {
+    readonly kind: "local-json";
+    readonly rootDir: string;
+}
+export interface ContentRailEntry<TCollection extends ContentCollection> {
+    /** File basename without `.json`. */
+    readonly id: string;
+    /** Absolute path of the source file (build-time only; do not ship to browsers). */
+    readonly sourcePath: string;
+    readonly data: InferEntry<TCollection>;
+}
+export interface LoadCollectionOptions {
+    /**
+     * Sort key. `"id"` (default) sorts by entry id.
+     * Any other string sorts by that top-level data field as a string.
+     */
+    readonly sortBy?: "id" | (string & {});
+    /** Default: `"asc"`. */
+    readonly sortOrder?: "asc" | "desc";
+    /**
+     * Field used to detect duplicate public identifiers across entries.
+     * Defaults to `"slug"` when present on entries; set `null` to disable.
+     */
+    readonly uniqueBy?: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEvE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB,CAAC,WAAW,SAAS,iBAAiB;IACrE,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACvC,wBAAwB;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@contentrail/reader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Build-time ContentRail local JSON content reader (Node.js).",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "node": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@contentrail/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "5.9.3",
+    "zod": "3.25.76"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hridhin-k/contentrail.git",
+    "directory": "packages/reader"
+  },
+  "bugs": {
+    "url": "https://github.com/Hridhin-k/contentrail/issues"
+  },
+  "homepage": "https://github.com/Hridhin-k/contentrail#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && tsc -p tsconfig.test.json && node --test test-dist/**/*.test.js"
+  }
 }