@contentrail/astro 0.0.0-stage → 0.2.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,51 @@
-# Temporary Holding Version
+# `@contentrail/astro`
 
-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.
+Build-time helpers for loading ContentRail local JSON content in Astro.
+
+**Supported / tested:** Astro **7.3.8** (peer `astro@^7.3.3`) on Node.js **≥ 22.12.0**.
+
+Astro 5.x is **not** a supported peer. Official advisories including critical
+[GHSA-26w7-cxv4-gfx2](https://github.com/advisories/GHSA-26w7-cxv4-gfx2)
+(AVIF / Sharp RCE) list affected range `< 7.2.8`. ContentRail does not claim
+Astro 5 is secure. See ADR 024 and `docs/RELEASE_READINESS_8A.md` § Phase 8A.2.
+
+Consumers who enable Astro’s default Sharp image service must keep Astro (and
+its Sharp optional dependency) on patched releases. ContentRail’s helper only
+reads local JSON; it does not disable Sharp.
+
+## Install
+
+### Monorepo
+
+```sh
+pnpm install
+pnpm --filter @contentrail/astro build
+```
+
+### From npm (upcoming `0.2.0` after authorized publish)
+
+```sh
+pnpm add @contentrail/core@0.2.0 @contentrail/reader@0.2.0 @contentrail/astro@0.2.0 zod@^4.6.7
+pnpm add -D astro@^7.3.3
+```
+
+## Workflow
+
+1. Define a collection with `@contentrail/core`.
+2. Add JSON files under `{rootDir}/{collection}/`.
+3. Call `createContentRail` from Astro frontmatter or `getStaticPaths`.
+4. Build with `astro build`. Invalid content fails the build.
+
+```ts
+import path from "node:path";
+import { createContentRail } from "@contentrail/astro";
+import { articles } from "../content/config";
+
+// Prefer process.cwd() for content roots. Astro 7 prerender bundles modules
+// under dist/.prerender/, so import.meta.url-relative paths often break.
+const rootDir = path.join(process.cwd(), "content");
+const rail = await createContentRail({ rootDir });
+const entries = await rail.loadCollection(articles);
+```
+
+This package re-exports the Node reader. Do not import it from client-side scripts.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { ContentCollection } from "@contentrail/core";
+import { ContentReadError, createLocalJsonSource, loadCollection, loadEntry, type LoadCollectionOptions, type LocalJsonSource } from "@contentrail/reader";
+export interface ContentRailOptions {
+    /** Absolute or process-relative path to the content root directory. */
+    readonly rootDir: string;
+}
+export interface ContentRail {
+    readonly source: LocalJsonSource;
+    loadEntry: <TCollection extends ContentCollection>(collection: TCollection, id: string) => ReturnType<typeof loadEntry<TCollection>>;
+    loadCollection: <TCollection extends ContentCollection>(collection: TCollection, options?: LoadCollectionOptions) => ReturnType<typeof loadCollection<TCollection>>;
+}
+/**
+ * Creates a build-time ContentRail helper for Astro pages and `getStaticPaths`.
+ * Uses the local JSON reader. Not for browser bundles.
+ */
+export declare function createContentRail(options: ContentRailOptions): Promise<ContentRail>;
+export { ContentReadError, createLocalJsonSource, loadCollection, loadEntry };
+export type { LoadCollectionOptions, LocalJsonSource };
+//# 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,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,SAAS,EAAE,CAAC,WAAW,SAAS,iBAAiB,EAC/C,UAAU,EAAE,WAAW,EACvB,EAAE,EAAE,MAAM,KACP,UAAU,CAAC,OAAO,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAC/C,cAAc,EAAE,CAAC,WAAW,SAAS,iBAAiB,EACpD,UAAU,EAAE,WAAW,EACvB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,UAAU,CAAC,OAAO,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC;CACrD;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;AAE9E,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { ContentReadError, createLocalJsonSource, loadCollection, loadEntry, } from "@contentrail/reader";
+/**
+ * Creates a build-time ContentRail helper for Astro pages and `getStaticPaths`.
+ * Uses the local JSON reader. Not for browser bundles.
+ */
+export async function createContentRail(options) {
+    const source = await createLocalJsonSource({ rootDir: options.rootDir });
+    return {
+        source,
+        loadEntry: (collection, id) => loadEntry(source, collection, id),
+        loadCollection: (collection, loadOptions) => loadCollection(source, collection, loadOptions),
+    };
+}
+export { ContentReadError, createLocalJsonSource, loadCollection, loadEntry };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,SAAS,GAGV,MAAM,qBAAqB,CAAC;AAmB7B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA2B;IAE3B,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACzE,OAAO;QACL,MAAM;QACN,SAAS,EAAE,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;QAChE,cAAc,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,EAAE,CAC1C,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC;KAClD,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@contentrail/astro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "description": "Astro build-time helpers for ContentRail local JSON content.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "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.2.0",
+    "@contentrail/reader": "0.2.0"
+  },
+  "peerDependencies": {
+    "astro": "^7.3.3"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "astro": "7.3.8",
+    "typescript": "5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hridhin-k/contentrail.git",
+    "directory": "packages/astro"
+  },
+  "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"
+  }
 }