@t09tanaka/stoneage 0.1.0

package/dist/deploy.js

@@ -0,0 +1,203 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export async function writeDeployArtifacts(options) {
+    if (options.provider === "github-pages") {
+        return writeGitHubPagesArtifacts(options);
+    }
+    if (options.provider !== "netlify") {
+        throw new Error(`Unsupported deploy provider: ${options.provider}`);
+    }
+    const redirects = await readRedirectsManifest(join(options.outDir, "redirects.json"));
+    const headers = await readHeadersManifest(join(options.outDir, "headers.json"));
+    const written = [];
+    if (redirects.redirects.length > 0) {
+        await writeText(join(options.outDir, "_redirects"), renderNetlifyRedirects(redirects.redirects));
+        written.push("_redirects");
+    }
+    else {
+        await rm(join(options.outDir, "_redirects"), { force: true });
+    }
+    if (headers.headers.length > 0) {
+        await writeText(join(options.outDir, "_headers"), renderNetlifyHeaders(headers.headers));
+        written.push("_headers");
+    }
+    else {
+        await rm(join(options.outDir, "_headers"), { force: true });
+    }
+    return {
+        provider: options.provider,
+        files: written,
+        redirects: redirects.redirects.length,
+        headers: headers.headers.length,
+    };
+}
+async function writeGitHubPagesArtifacts(options) {
+    const written = [];
+    // .nojekyll lets GitHub Pages serve paths that start with an underscore.
+    // It is always written as an empty, idempotent file.
+    await writeIfChanged(join(options.outDir, ".nojekyll"), "");
+    written.push(".nojekyll");
+    const cname = normalizeCname(options.cname);
+    if (cname !== undefined) {
+        await writeIfChanged(join(options.outDir, "CNAME"), `${cname}\n`);
+        written.push("CNAME");
+    }
+    return {
+        provider: options.provider,
+        files: written,
+        redirects: 0,
+        headers: 0,
+    };
+}
+export function normalizeCname(cname) {
+    if (cname === undefined) {
+        return undefined;
+    }
+    const trimmed = cname.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (/\s/.test(trimmed)) {
+        throw new Error("CNAME must be a single host without whitespace or multiple lines.");
+    }
+    // Accept full URLs by extracting the host only (no protocol, no path).
+    const withProtocol = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)
+        ? trimmed
+        : `https://${trimmed}`;
+    let parsed;
+    try {
+        parsed = new URL(withProtocol);
+    }
+    catch {
+        throw new Error(`Invalid CNAME domain: ${cname}`);
+    }
+    // GitHub Pages CNAME accepts only a bare hostname, so drop any port,
+    // userinfo, or path that may have been supplied with a full URL.
+    const host = parsed.hostname;
+    if (!host || parsed.port || parsed.username || parsed.password) {
+        throw new Error(`Invalid CNAME domain: ${cname}`);
+    }
+    return host;
+}
+export function renderNetlifyRedirects(redirects) {
+    return redirects
+        .map((redirect) => `${redirect.from} ${redirect.to} ${redirect.status}`)
+        .join("\n")
+        .concat("\n");
+}
+export function renderNetlifyHeaders(headers) {
+    return headers
+        .map((entry) => {
+        const lines = [entry.path];
+        for (const [name, value] of Object.entries(entry.headers)) {
+            lines.push(`  ${netlifyHeaderName(name)}: ${value}`);
+        }
+        return lines.join("\n");
+    })
+        .join("\n\n")
+        .concat("\n");
+}
+async function readRedirectsManifest(path) {
+    const raw = await readOptionalText(path);
+    if (!raw) {
+        return { redirects: [] };
+    }
+    const parsed = parseManifestJson(raw, "redirects.json");
+    if (!isRedirectsManifest(parsed)) {
+        throw new Error("redirects.json must contain a redirects array with from, to, and status entries.");
+    }
+    return parsed;
+}
+async function readHeadersManifest(path) {
+    const raw = await readOptionalText(path);
+    if (!raw) {
+        return { headers: [] };
+    }
+    const parsed = parseManifestJson(raw, "headers.json");
+    if (!isHeadersManifest(parsed)) {
+        throw new Error("headers.json must contain a headers array with path and headers entries.");
+    }
+    return parsed;
+}
+function parseManifestJson(raw, name) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${name} is not valid JSON: ${errorMessage(error)}.`);
+    }
+}
+function isRedirectsManifest(value) {
+    if (!value || typeof value !== "object" || !("redirects" in value)) {
+        return false;
+    }
+    const redirects = value.redirects;
+    return Array.isArray(redirects) && redirects.every(isRedirectManifestEntry);
+}
+function isRedirectManifestEntry(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const entry = value;
+    return (typeof entry.from === "string" &&
+        Boolean(entry.from) &&
+        typeof entry.to === "string" &&
+        Boolean(entry.to) &&
+        typeof entry.status === "number");
+}
+function isHeadersManifest(value) {
+    if (!value || typeof value !== "object" || !("headers" in value)) {
+        return false;
+    }
+    const headers = value.headers;
+    return Array.isArray(headers) && headers.every(isHeadersManifestEntry);
+}
+function isHeadersManifestEntry(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const entry = value;
+    return typeof entry.path === "string" && Boolean(entry.path) && isStringRecord(entry.headers);
+}
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((item) => typeof item === "string"));
+}
+function netlifyHeaderName(name) {
+    return name
+        .split("-")
+        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1).toLowerCase()}`)
+        .join("-");
+}
+async function readOptionalText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingPath(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function writeText(path, contents) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents);
+}
+// Writes only when the file is absent or its contents differ, so reruns are
+// idempotent.
+async function writeIfChanged(path, contents) {
+    const existing = await readOptionalText(path);
+    if (existing === contents) {
+        return;
+    }
+    await writeText(path, contents);
+}
+function isMissingPath(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/dev.d.ts

@@ -0,0 +1,36 @@
+export type DevServerOptions = {
+    outDir: string;
+    host?: string;
+    port?: number;
+    watchPaths?: string[];
+    buildCommand?: string;
+    debounceMs?: number;
+    cwd?: string;
+    logger?: Pick<Console, "error" | "log">;
+};
+export type DevServer = {
+    url: string;
+    close: () => Promise<void>;
+    reload: () => void;
+};
+export type DevServerFile = {
+    absolutePath: string;
+    contentType: string;
+    injectHotReload: boolean;
+};
+export type BuildScheduler = {
+    schedule: () => Promise<void>;
+};
+type BuildSchedulerOptions = {
+    debounceMs: number;
+    runBuild: () => Promise<void>;
+    onReload: () => void;
+    onError: (error: Error) => void;
+    onStart?: () => void;
+};
+export declare function injectHotReloadClient(html: string): string;
+export declare function resolveDevServerFile(outDir: string, requestUrl: string): Promise<DevServerFile | undefined>;
+export declare function createBuildScheduler(options: BuildSchedulerOptions): BuildScheduler;
+export declare function startDevServer(options: DevServerOptions): Promise<DevServer>;
+export declare function runBuildCommand(command: string, cwd?: string): Promise<void>;
+export {};

package/dist/dev.js

@@ -0,0 +1,313 @@
+import { spawn } from "node:child_process";
+import { watch } from "node:fs";
+import { mkdir, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+const reloadEventsPath = "/__stoneage/events";
+const hotReloadClient = `<script type="module">const events = new EventSource("${reloadEventsPath}");
+events.addEventListener("reload", () => location.reload());
+</script>`;
+export function injectHotReloadClient(html) {
+    const closingBody = /<\/body\s*>/i.exec(html);
+    if (!closingBody) {
+        return `${html}${hotReloadClient}`;
+    }
+    return `${html.slice(0, closingBody.index)}${hotReloadClient}${html.slice(closingBody.index)}`;
+}
+export async function resolveDevServerFile(outDir, requestUrl) {
+    const root = await realpath(outDir).catch(() => resolve(outDir));
+    let pathname;
+    try {
+        pathname = decodeURIComponent(new URL(requestUrl, "http://stoneage.local").pathname);
+    }
+    catch {
+        return undefined;
+    }
+    if (pathname.includes("\0") || pathname === reloadEventsPath) {
+        return undefined;
+    }
+    const relativePath = pathname.replace(/^\/+/, "");
+    const baseCandidate = resolve(root, relativePath || ".");
+    if (!isInsidePath(root, baseCandidate)) {
+        return undefined;
+    }
+    const candidates = pathname.endsWith("/")
+        ? [join(baseCandidate, "index.html")]
+        : [
+            baseCandidate,
+            join(baseCandidate, "index.html"),
+            `${baseCandidate}.html`,
+        ];
+    for (const candidate of candidates) {
+        if (!isInsidePath(root, candidate)) {
+            continue;
+        }
+        const candidateStat = await stat(candidate).catch(() => undefined);
+        if (!candidateStat?.isFile()) {
+            continue;
+        }
+        const realCandidate = await realpath(candidate).catch(() => candidate);
+        if (!isInsidePath(root, realCandidate)) {
+            continue;
+        }
+        const contentType = contentTypeForPath(candidate);
+        return {
+            absolutePath: candidate,
+            contentType,
+            injectHotReload: contentType.startsWith("text/html"),
+        };
+    }
+    return undefined;
+}
+async function readNotFoundPage(outDir) {
+    const root = await realpath(outDir).catch(() => resolve(outDir));
+    const candidate = join(root, "404.html");
+    const candidateStat = await stat(candidate).catch(() => undefined);
+    if (!candidateStat?.isFile()) {
+        return undefined;
+    }
+    return readFile(candidate, "utf8").catch(() => undefined);
+}
+export function createBuildScheduler(options) {
+    let timer;
+    let active = Promise.resolve();
+    let waiters = [];
+    const resolveWaiters = () => {
+        const current = waiters;
+        waiters = [];
+        for (const resolveWaiter of current) {
+            resolveWaiter();
+        }
+    };
+    const run = async () => {
+        try {
+            options.onStart?.();
+            await options.runBuild();
+            options.onReload();
+        }
+        catch (error) {
+            options.onError(error instanceof Error ? error : new Error(String(error)));
+        }
+    };
+    return {
+        schedule: () => new Promise((resolveSchedule) => {
+            waiters.push(resolveSchedule);
+            if (timer) {
+                clearTimeout(timer);
+            }
+            timer = setTimeout(() => {
+                timer = undefined;
+                active = active.then(run, run).finally(resolveWaiters);
+            }, options.debounceMs);
+        }),
+    };
+}
+export async function startDevServer(options) {
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? 4321;
+    const debounceMs = options.debounceMs ?? 100;
+    const logger = options.logger ?? console;
+    const clients = new Set();
+    const watchers = [];
+    const outDir = resolve(options.outDir);
+    const notifyReload = () => {
+        for (const client of clients) {
+            client.write("event: reload\ndata: {}\n\n");
+        }
+    };
+    const scheduler = createBuildScheduler({
+        debounceMs,
+        runBuild: options.buildCommand
+            ? () => runBuildCommand(options.buildCommand, options.cwd ?? process.cwd())
+            : async () => undefined,
+        onStart: () => {
+            if (options.buildCommand) {
+                logger.log(`StoneAge dev rebuild started: ${options.buildCommand}`);
+            }
+        },
+        onReload: () => {
+            logger.log("StoneAge dev reload");
+            notifyReload();
+        },
+        onError: (error) => logger.error(`StoneAge dev build failed: ${error.message}`),
+    });
+    if (options.buildCommand) {
+        logger.log(`StoneAge dev initial build: ${options.buildCommand}`);
+        await runBuildCommand(options.buildCommand, options.cwd ?? process.cwd()).catch((error) => {
+            logger.error(`StoneAge dev initial build failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    const server = createServer(async (request, response) => {
+        const requestUrl = request.url ?? "/";
+        if (new URL(requestUrl, "http://stoneage.local").pathname === reloadEventsPath) {
+            response.writeHead(200, {
+                "Content-Type": "text/event-stream; charset=utf-8",
+                "Cache-Control": "no-cache, no-transform",
+                Connection: "keep-alive",
+            });
+            response.write(": connected\n\n");
+            clients.add(response);
+            request.on("close", () => clients.delete(response));
+            return;
+        }
+        const file = await resolveDevServerFile(outDir, requestUrl);
+        if (!file) {
+            const notFoundHtml = await readNotFoundPage(outDir);
+            if (notFoundHtml !== undefined) {
+                response.writeHead(404, {
+                    "Content-Type": "text/html; charset=utf-8",
+                    "Cache-Control": "no-cache",
+                });
+                response.end(injectHotReloadClient(notFoundHtml));
+                return;
+            }
+            response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            response.end("Not found\n");
+            return;
+        }
+        const body = await readFile(file.absolutePath, file.injectHotReload ? "utf8" : undefined);
+        response.writeHead(200, {
+            "Content-Type": file.contentType,
+            "Cache-Control": "no-cache",
+        });
+        response.end(file.injectHotReload ? injectHotReloadClient(body) : body);
+    });
+    await listen(server, port, host);
+    for (const watchPath of options.watchPaths ?? []) {
+        watchers.push(...(await watchDirectories(resolve(options.cwd ?? process.cwd(), watchPath), outDir, () => {
+            void scheduler.schedule();
+        })));
+    }
+    const address = server.address();
+    const actualPort = typeof address === "object" && address ? address.port : port;
+    const url = `http://${host}:${actualPort}`;
+    return {
+        url,
+        reload: notifyReload,
+        close: async () => {
+            for (const watcher of watchers) {
+                watcher.close();
+            }
+            for (const client of clients) {
+                client.end();
+            }
+            await new Promise((resolveClose, rejectClose) => {
+                server.close((error) => (error ? rejectClose(error) : resolveClose()));
+            });
+        },
+    };
+}
+export function runBuildCommand(command, cwd = process.cwd()) {
+    return new Promise((resolveRun, rejectRun) => {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            stdio: "inherit",
+        });
+        child.on("error", rejectRun);
+        child.on("exit", (code, signal) => {
+            if (code === 0) {
+                resolveRun();
+                return;
+            }
+            rejectRun(new Error(signal ? `${command} exited with ${signal}` : `${command} exited with ${code}`));
+        });
+    });
+}
+async function listen(server, port, host) {
+    await new Promise((resolveListen, rejectListen) => {
+        server.once("error", rejectListen);
+        server.listen(port, host, () => {
+            server.off("error", rejectListen);
+            resolveListen();
+        });
+    });
+}
+async function watchDirectories(root, outDir, onChange) {
+    const watchers = [];
+    const watchedDirs = new Set();
+    const rootStat = await stat(root).catch(() => undefined);
+    if (rootStat?.isFile()) {
+        const fileDir = dirname(root);
+        const fileName = basename(root);
+        watchers.push(watch(fileDir, (_eventType, filename) => {
+            if (!filename || String(filename) === fileName) {
+                onChange();
+            }
+        }));
+        return watchers;
+    }
+    if (!rootStat) {
+        await mkdir(root, { recursive: true });
+    }
+    const visit = async (dir) => {
+        if (shouldIgnoreWatchPath(dir, outDir)) {
+            return;
+        }
+        if (watchedDirs.has(dir)) {
+            return;
+        }
+        watchedDirs.add(dir);
+        watchers.push(watch(dir, (_eventType, filename) => {
+            if (filename) {
+                const changedPath = resolve(dir, String(filename));
+                if (shouldIgnoreWatchPath(changedPath, outDir)) {
+                    return;
+                }
+                void stat(changedPath).then((changedStat) => {
+                    if (changedStat.isDirectory()) {
+                        void visit(changedPath);
+                    }
+                }, () => undefined);
+            }
+            onChange();
+        }));
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                await visit(join(dir, entry.name));
+            }
+        }
+    };
+    await visit(root);
+    return watchers;
+}
+function shouldIgnoreWatchPath(path, outDir) {
+    const name = path.split(sep).at(-1);
+    return (name === ".git" ||
+        name === "node_modules" ||
+        isInsidePath(outDir, path));
+}
+function isInsidePath(root, path) {
+    const resolvedRoot = resolve(root);
+    const resolvedPath = resolve(path);
+    const pathRelativeToRoot = relative(resolvedRoot, resolvedPath);
+    return (pathRelativeToRoot === "" ||
+        (!pathRelativeToRoot.startsWith("..") && !pathRelativeToRoot.startsWith(sep)));
+}
+function contentTypeForPath(path) {
+    switch (extname(path).toLowerCase()) {
+        case ".html":
+            return "text/html; charset=utf-8";
+        case ".css":
+            return "text/css; charset=utf-8";
+        case ".js":
+        case ".mjs":
+            return "text/javascript; charset=utf-8";
+        case ".json":
+            return "application/json; charset=utf-8";
+        case ".xml":
+            return "application/xml; charset=utf-8";
+        case ".svg":
+            return "image/svg+xml";
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".webp":
+            return "image/webp";
+        default:
+            return "application/octet-stream";
+    }
+}

package/dist/example.d.ts

@@ -0,0 +1,134 @@
+import { type BuildConfig, type BuildResult } from "./core.js";
+import { type ImageConverter } from "./images.js";
+import type { CompressionMetrics } from "./optimize.js";
+import { type PaginatedPage } from "./pagination.js";
+export type ExampleCounts = {
+    members: number;
+    sessions: number;
+    conversations: number;
+    bills: number;
+};
+export type ExampleBuildOptions = {
+    outDir: string;
+    counts?: Partial<ExampleCounts>;
+    trailingSlash?: BuildConfig["trailingSlash"];
+    recordHashCache?: ExampleRecordHashCache;
+    conversationIndexCache?: ExampleConversationIndexCache;
+    includePublicDataExports?: boolean;
+    sitemapMaxUrlsPerFile?: number;
+    mutateConversationId?: string;
+    partialConversationId?: string;
+    imageConverter?: ImageConverter;
+    loadImageConverter?: () => Promise<ImageConverter | undefined>;
+};
+export type ExampleBuildResult = BuildResult & {
+    imageOptimization: ImageOptimizationSummary;
+    dataNormalization: DataNormalizationSummary;
+    dataHashing: DataHashingSummary;
+    pagination: PaginationSummary;
+};
+export type ExampleBenchmark = {
+    pageCount: number;
+    fullBuildMs: number;
+    incrementalBuildMs: number;
+    fullBuildPagesWritten: number;
+    incrementalBuildPagesWritten: number;
+    changedBuildMs: number;
+    changedBuildPagesWritten: number;
+    normalizedDataSnapshots: number;
+    normalizedDataBytes: number;
+    fullBuildNormalizedDataWrites: number;
+    incrementalBuildNormalizedDataWrites: number;
+    changedBuildNormalizedDataWrites: number;
+    fullBuildRecordHashes: number;
+    incrementalBuildRecordHashes: number;
+    changedBuildRecordHashes: number;
+    fullBuildConversationIndexItemsMaterialized: number;
+    incrementalBuildConversationIndexItemsMaterialized: number;
+    changedBuildConversationIndexItemsMaterialized: number;
+    totalOutputBytes: number;
+    publicOutputBytes: number;
+    internalOutputBytes: number;
+    htmlOutputBytes: number;
+    cssOutputBytes: number;
+    jsOutputBytes: number;
+    imageOutputBytes: number;
+    dataOutputBytes: number;
+    averageHtmlBytes: number;
+    p95HtmlBytes: number;
+    compressedTransferBytes?: CompressionSummary;
+    imageOptimization: ImageOptimizationSummary;
+    largestHtml: Array<{
+        path: string;
+        bytes: number;
+    }>;
+    routeFamilies: Record<string, number>;
+    sitemapUrlCount: number;
+    sitemapFileCount: number;
+    sitemapBytes?: number;
+    largestSitemapBytes?: number;
+    missingLinkCount: number;
+    validationIssueCount: number;
+    largestDependencyFanout: number;
+    publicDataRecordCounts?: ExampleDataRecordCounts;
+};
+export type ExampleOutputSizes = {
+    totalOutputBytes: number;
+    publicOutputBytes: number;
+    internalOutputBytes: number;
+    htmlOutputBytes: number;
+    cssOutputBytes: number;
+    jsOutputBytes: number;
+    imageOutputBytes: number;
+    dataOutputBytes: number;
+    averageHtmlBytes: number;
+    p95HtmlBytes: number;
+};
+type CompressionSummary = Omit<CompressionMetrics, "files">;
+type ImageOptimizationSummary = {
+    generated: number;
+    skipped: number;
+    outputBytes: number;
+};
+type DataNormalizationSummary = {
+    snapshots: number;
+    written: number;
+    bytes: number;
+};
+type DataHashingSummary = {
+    recordsHashed: number;
+};
+export type ExampleDataRecordCounts = {
+    members: number;
+    sessions: number;
+    conversations: number;
+    bills: number;
+    categories: number;
+    votes: number;
+    yearlyAggregates: number;
+};
+export type ExampleRecordHashCache = Map<string, RecordHashCacheEntry>;
+type RecordHashCacheEntry = {
+    fingerprint: string;
+    hash: string;
+};
+type PaginationSummary = {
+    conversationIndexItemsMaterialized: number;
+};
+type ExampleConversationIndexCache = Map<string, PaginatedPage<Conversation>[]>;
+type Conversation = {
+    id: string;
+    slug: string;
+    memberId: string;
+    sessionId: string;
+    categoryId: string;
+    title: string;
+    body: string;
+};
+export declare function buildExampleSite(options: ExampleBuildOptions): Promise<ExampleBuildResult>;
+export declare function benchmarkExampleSite(options: ExampleBuildOptions): Promise<ExampleBenchmark>;
+export declare function measureExampleOutputSizes(outDir: string, options?: {
+    includePublicDataExports?: boolean;
+    knownHtmlOutputBytes?: ReadonlyMap<string, number>;
+}): Promise<ExampleOutputSizes>;
+export {};