@rulebookguard/site 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Carlos Jimenez
+
+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,9 @@
-# Temporary Holding Version
+# @rulebookguard/site
 
-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.
+Builds the static site of a [rulebookguard](https://github.com/JuanCJR/rulebookguard#readme) rulebook with Astro Starlight. Install it next to `rulebookguard` to use the `site:generate` and `site:run` commands:
+
+```sh
+npm install --save-dev rulebookguard @rulebookguard/site
+```
+
+It is kept apart so that `rulebookguard lint` does not download Astro. It requires Node.js 22.23.4 or later.

package/index.d.mts

@@ -0,0 +1,13 @@
+export declare class SiteBuildError extends Error {
+  readonly detail: string;
+  constructor(detail: string);
+}
+
+/** Writes `files` as an Astro project, builds it and replaces `out` with the build. */
+export declare function buildSite(files: ReadonlyMap<string, string>, out: string): Promise<void>;
+
+/** The directory where generated projects are built, inside the node_modules that holds Astro. */
+export declare function siteWorkRoot(): string;
+
+/** The first lines of Astro's error output, without its stack trace. */
+export declare function astroFailureDetail(output: string): string;

package/index.mjs

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export class SiteBuildError extends Error {
+  constructor(detail) {
+    super(`The site build failed:\n${detail}`);
+    this.name = 'SiteBuildError';
+    this.detail = detail;
+  }
+}
+
+/** Writes `files` as an Astro project, builds it and replaces `out` with the build. */
+export async function buildSite(files, out) {
+  const work = join(siteWorkRoot(), randomUUID());
+  try {
+    for (const [path, content] of files) {
+      await mkdir(dirname(join(work, path)), { recursive: true });
+      await writeFile(join(work, path), content);
+    }
+    await buildWithAstro(work);
+    await rm(out, { recursive: true, force: true });
+    await cp(join(work, 'dist'), out, { recursive: true });
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Starlight injects its routes as package specifiers that Astro resolves from the project root, so the generated
+ * project must live inside the node_modules directory that holds this package's own dependencies.
+ */
+export function siteWorkRoot() {
+  const root = dirname(fileURLToPath(import.meta.url));
+  let parent = dirname(root);
+  if (basename(parent).startsWith('@')) {
+    parent = dirname(parent);
+  }
+  const modules = basename(parent) === 'node_modules' ? parent : join(root, 'node_modules');
+  return join(modules, '.rulebookguard-site');
+}
+
+// Astro writes temporary prerender files under the process cwd, so it runs in its own process from the project.
+async function buildWithAstro(work) {
+  const astro = join(dirname(siteWorkRoot()), 'astro');
+  const { bin } = JSON.parse(readFileSync(join(astro, 'package.json'), 'utf8'));
+  try {
+    await execFileAsync(process.execPath, [join(astro, bin.astro), 'build', '--silent'], {
+      cwd: work,
+      env: { ...process.env, ASTRO_TELEMETRY_DISABLED: '1' },
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch (error) {
+    const { stderr, stdout } = error;
+    throw new SiteBuildError(astroFailureDetail(`${stderr ?? ''}${stdout ?? ''}`));
+  }
+}
+
+/** The first lines of Astro's error output, without its stack trace. */
+export function astroFailureDetail(output) {
+  return output
+    .split('\n')
+    .filter((line) => !/^\s*at /.test(line) && !/^\s*Stack trace:/.test(line))
+    .filter((line) => line.trim() !== '')
+    .slice(0, 12)
+    .join('\n');
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@rulebookguard/site",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Astro Starlight builder for the rulebookguard site commands.",
+  "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
+  "bugs": {
+    "url": "https://github.com/JuanCJR/rulebookguard/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JuanCJR/rulebookguard.git",
+    "directory": "packages/site"
+  },
+  "files": [
+    "index.mjs",
+    "index.d.mts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "default": "./index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "^7.3.2",
+    "@astrojs/starlight": "^0.42.6",
+    "astro": "^7.3.8"
+  },
+  "engines": {
+    "node": ">=22.23.4"
+  }
+}