@wxxb789/anc 0.0.1

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@wxxb789/anc",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Build a static, privacy-preserving site from a directory of Markdown",
+  "keywords": [
+    "static-site-generator",
+    "static-site",
+    "markdown",
+    "obsidian",
+    "digital-garden",
+    "knowledge-base",
+    "backlinks",
+    "full-text-search",
+    "pagefind",
+    "privacy",
+    "self-hosted",
+    "astro",
+    "sqlite",
+    "wasm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wxxb789/anc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wxxb789/anc/issues"
+  },
+  "homepage": "https://github.com/wxxb789/anc#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@11.18.0",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "bin": {
+    "anc": "bin/anc.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "astro.config.mjs",
+    "bin",
+    "public",
+    "scripts",
+    "src",
+    "tsconfig.json",
+    "!src/data/content.json",
+    "!scripts/build-fixture.ts",
+    "!scripts/compile-package.ts",
+    "!scripts/build-site.ts",
+    "!scripts/dist-lock.ts",
+    "!scripts/npm-command.ts",
+    "!scripts/benchmark-browser.ts",
+    "!scripts/benchmark-candidate.ts",
+    "!scripts/benchmark-corpus.ts",
+    "!scripts/benchmark-driver.ts",
+    "!scripts/benchmark-files.ts",
+    "!scripts/benchmark-host.ts",
+    "!scripts/benchmark-identity.ts",
+    "!scripts/benchmark-limits.ts",
+    "!scripts/benchmark-oracle.ts",
+    "!scripts/benchmark-package.ts",
+    "!scripts/benchmark-page.ts",
+    "!scripts/benchmark-server.ts",
+    "!scripts/benchmark-snapshot.ts",
+    "!scripts/benchmark-stats.ts",
+    "!scripts/benchmark-transfer.ts",
+    "!scripts/benchmark-workload-driver.ts",
+    "!scripts/benchmark-workload-report.ts",
+    "!scripts/benchmark-workload-ui.ts",
+    "!scripts/benchmark-workload.ts",
+    "!scripts/release-changelog.ts",
+    "!scripts/smoke-tarball.ts"
+  ],
+  "dependencies": {
+    "@astrojs/prism": "4.1.2",
+    "@sqlite.org/sqlite-wasm": "3.53.4-build1",
+    "astro": "7.4.5",
+    "github-slugger": "2.0.0",
+    "happy-dom": "20.14.5",
+    "mermaid": "12.2.0",
+    "pagefind": "1.6.0",
+    "prismjs": "1.30.0",
+    "sanitize-html": "2.18.1",
+    "satteri": "0.11.6",
+    "temml": "0.14.0",
+    "yaml": "2.9.1"
+  }
+}

package/public/_headers

@@ -0,0 +1,45 @@
+# The `style-src` value is coupled to `DIAGRAM_MODE` in `src/lib/diagram-mode.ts`
+# and must be changed with it: `'self'` for build-time diagrams, which ship as
+# markup, and `'self' 'unsafe-inline'` for client mode, whose renderer writes
+# inline styles and an injected `<style>` element that this policy would
+# otherwise block — producing a solid black rectangle where the diagram should
+# be. `tests/math-and-diagrams.test.ts` and `tests/built-output.test.ts` both
+# fail if the two disagree.
+#
+# Hash-pinning was measured and cannot replace the relaxation: a CSP hash never
+# covers a `style=` attribute, so `'unsafe-inline'` survives in `style-src-attr`
+# and is merely relocated. See the Mermaid feasibility probe, section 7.3.
+/*
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+  Permissions-Policy: camera=(), microphone=(), geolocation=()
+  Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self'; worker-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'
+
+# Everything Astro content-hashes. The hash is derived from the file's own
+# bytes, so a changed file is a changed URL and a cached copy of the old one can
+# never be stale — which is the only condition under which `immutable` is safe.
+#
+# The rule sets no header the `/*` block above sets. That matters on Cloudflare
+# Pages, which joins same-named headers from every matching rule with a comma
+# rather than choosing the most specific: two rules setting `Cache-Control`
+# would emit both values. Overriding an inherited header needs an explicit
+# `! Header-Name`. `tests/deployment.test.ts` gates exactly that.
+/_astro/*
+  Cache-Control: public, max-age=31536000, immutable
+
+# Deliberately NOT listed: `/pagefind/*`.
+#
+# Only two of its four asset classes are content-hashed. `pagefind/index/*` and
+# `pagefind/fragment/*` carry a hash; `pagefind-entry.json` and
+# `wasm.*.pagefind` are stable-named and rewritten on every build. Marking the
+# directory immutable would pin a returning reader's `pagefind-entry.json` to a
+# year-old copy pointing at index chunks that no longer exist — search would
+# break silently after the first republish, for exactly the readers who visit
+# most often. The platform default (`public, max-age=0, must-revalidate` plus an
+# `ETag`) revalidates cheaply and is correct for all four.
+#
+# Also not listed: HTML and the JSON data files. Requirements section 20 asks
+# for a short cache or revalidation for HTML and a short cache with `ETag` for
+# JSON, and Cloudflare Pages already serves precisely that by default on every
+# 200. A rule restating the platform default would be one more thing to keep in
+# sync with it.

package/public/favicon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 128 128">
+    <path d="M50.4 78.5a75.1 75.1 0 0 0-28.5 6.9l24.2-65.7c.7-2 1.9-3.2 3.4-3.2h29c1.5 0 2.7 1.2 3.4 3.2l24.2 65.7s-11.6-7-28.5-7L67 45.5c-.4-1.7-1.6-2.8-2.9-2.8-1.3 0-2.5 1.1-2.9 2.7L50.4 78.5Zm-1.1 28.2Zm-4.2-20.2c-2 6.6-.6 15.8 4.2 20.2a17.5 17.5 0 0 1 .2-.7 5.5 5.5 0 0 1 5.7-4.5c2.8.1 4.3 1.5 4.7 4.7.2 1.1.2 2.3.2 3.5v.4c0 2.7.7 5.2 2.2 7.4a13 13 0 0 0 5.7 4.9v-.3l-.2-.3c-1.8-5.6-.5-9.5 4.4-12.8l1.5-1a73 73 0 0 0 3.2-2.2 16 16 0 0 0 6.8-11.4c.3-2 .1-4-.6-6l-.8.6-1.6 1a37 37 0 0 1-22.4 2.7c-5-.7-9.7-2-13.2-6.2Z" />
+    <style>
+        path { fill: #000; }
+        @media (prefers-color-scheme: dark) {
+            path { fill: #FFF; }
+        }
+    </style>
+</svg>

package/scripts/build-snapshot.js

@@ -0,0 +1,69 @@
+/**
+ * Build the public snapshot for a content artifact and bind it for the build.
+ *
+ * Writes two private files into the snapshot workspace: `snapshot.sqlite`, the
+ * finalized database, and `binding.json`, the digest-named URL the Astro build
+ * and the output copy step read. Neither is public output; only the copied,
+ * digest-named file under `dist/data/` is.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { DatabaseSync } from "../src/lib/sqlite.js";
+import { ARTIFACT_PATH, loadArtifact } from "../src/lib/artifact-source.js";
+import { snapshotWorkspace } from "../src/lib/snapshot-reader.js";
+import { writeSnapshot } from "./write-snapshot.js";
+/**
+ * Build the snapshot from the producer's in-memory entries and write the binding.
+ *
+ * The packaged build calls this directly: its serialized artifact deliberately
+ * omits `outgoing`/`backlinks`, so the edge authorities reach the snapshot
+ * builder as the transient producer result rather than through a file.
+ */
+export function buildSnapshotFromEntries(entries, workspace = snapshotWorkspace()) {
+    mkdirSync(workspace, { recursive: true });
+    const written = writeSnapshot({ version: 1, entries: [...entries] }, resolve(workspace, 'snapshot.sqlite'));
+    writeFileSync(resolve(workspace, 'binding.json'), `${JSON.stringify(
+    // The header constants live in code; the binding names the bytes.
+    { url: written.url, digest: written.digest }, null, 2)}\n`, 'utf8');
+    const database = loadSnapshotCounts(written.path);
+    return { ...written, workspace, ...database };
+}
+/**
+ * Build the snapshot and write the binding beside it.
+ *
+ * @param artifactPath Repository-relative artifact to read; defaults to the one
+ *   this build selected (`CONTENT_ARTIFACT` or `src/data/content.json`).
+ * @param workspace Absolute private directory. Defaults to `SNAPSHOT_WORKSPACE`
+ *   or `.astro/snapshot`.
+ */
+export function buildSnapshot(artifactPath = ARTIFACT_PATH, workspace = snapshotWorkspace()) {
+    return buildSnapshotFromEntries(loadArtifact(artifactPath).entries, workspace);
+}
+/** Read the finalized file back, so the reported counts are the published rows. */
+function loadSnapshotCounts(path) {
+    const database = new DatabaseSync(path, { readOnly: true });
+    try {
+        return {
+            nodes: database.prepare('SELECT count(*) AS c FROM nodes').get().c,
+            edges: database.prepare('SELECT count(*) AS c FROM edges').get().c,
+            tags: database.prepare('SELECT count(*) AS c FROM tags').get().c,
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+function main() {
+    try {
+        const built = buildSnapshot();
+        console.log(`snapshot ok: nodes=${built.nodes} edges=${built.edges} tags=${built.tags} bytes=${built.size} sha256=${built.digest}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main());

package/scripts/build-wasm.js

@@ -0,0 +1,67 @@
+/**
+ * Stage the pinned SQLite browser runtime into the private build workspace.
+ *
+ * The package is **not** bundled by Vite: bundling it inlined its Emscripten glue
+ * into the Worker chunk, which both mixed a third-party runtime into ANC's own
+ * provenance and made the residue scan read the library's `[[` and `file://`
+ * strings as findings. Instead the package's browser entry and its WASM are
+ * copied verbatim under `/wasm/`, and the Worker imports the entry by URL at
+ * runtime (`import(/* @vite-ignore *\/ …)`), so it stays external and same-origin.
+ *
+ * The WASM is digest-named and the Worker verifies the bytes it downloads; the
+ * entry keeps its stable name because the package resolves `sqlite3.wasm`
+ * relative to itself, and `locateFile` redirects that to the hashed copy.
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WASM_DIRECTORY, WASM_MODULE_NAME, wasmModuleUrl, wasmMemberName, wasmRoute } from "../src/lib/wasm-asset.js";
+import { snapshotWorkspace } from "../src/lib/snapshot-reader.js";
+const require = createRequire(import.meta.url);
+/** Members copied verbatim beside the entry, keeping the package's own names. */
+const STABLE_MEMBERS = ['sqlite3-worker1.mjs', 'sqlite3-opfs-async-proxy.js'];
+function packageDist() {
+    const manifest = require.resolve('@sqlite.org/sqlite-wasm/package.json');
+    return join(dirname(manifest), 'dist');
+}
+/**
+ * Resolve, hash, and stage the browser runtime.
+ *
+ * @param workspace Absolute private directory. Defaults to `SNAPSHOT_WORKSPACE`.
+ */
+export function buildWasm(workspace = snapshotWorkspace()) {
+    const dist = packageDist();
+    const wasmBytes = readFileSync(join(dist, 'sqlite3.wasm'));
+    const digest = createHash('sha256').update(wasmBytes).digest('hex');
+    const staging = resolve(workspace, WASM_DIRECTORY);
+    mkdirSync(staging, { recursive: true });
+    copyFileSync(join(dist, 'index.mjs'), resolve(staging, WASM_MODULE_NAME));
+    for (const member of STABLE_MEMBERS)
+        copyFileSync(join(dist, member), resolve(staging, member));
+    const wasmName = wasmMemberName(digest);
+    copyFileSync(join(dist, 'sqlite3.wasm'), resolve(staging, wasmName));
+    const binding = {
+        moduleUrl: wasmModuleUrl(),
+        url: wasmRoute(digest),
+        digest,
+        members: [`${WASM_DIRECTORY}/${WASM_MODULE_NAME}`, ...STABLE_MEMBERS.map((m) => `${WASM_DIRECTORY}/${m}`), `${WASM_DIRECTORY}/${wasmName}`],
+        size: wasmBytes.length,
+    };
+    writeFileSync(resolve(workspace, 'wasm.json'), `${JSON.stringify({ moduleUrl: binding.moduleUrl, url: binding.url, digest: binding.digest, members: binding.members }, null, 2)}\n`, 'utf8');
+    return binding;
+}
+function main() {
+    try {
+        const staged = buildWasm();
+        console.log(`wasm ok: bytes=${staged.size} sha256=${staged.digest} members=${staged.members.length}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main());

package/scripts/build-workspace.js

@@ -0,0 +1,50 @@
+/** Retention for packaged-build workspaces left by interruption or deferred cleanup. */
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+export const STALE_BUILD_WORKSPACE_AGE_MS = 24 * 60 * 60 * 1000;
+const WORKSPACE_NAME = /^\.anc-build-[A-Za-z0-9]{6}$/;
+/** Remove one completed workspace without replacing the build result on failure. */
+export async function removeBuildWorkspace(directory, remove = (target) => rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })) {
+    try {
+        await remove(directory);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Best-effort removal of this tool's stale sibling workspaces.
+ *
+ * Workspaces must live beside the package so Astro's staging and output stay on
+ * one device. A killed process never reaches its `finally`, and Windows may hold
+ * a just-written file past the final retry, so a later run converges the state.
+ * The 24-hour age bound keeps concurrent workspaces out of the candidate set.
+ * Symlinks, junctions, files, and unfamiliar names are never traversed or removed.
+ */
+export async function pruneStaleBuildWorkspaces(root, now = Date.now()) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const entry of entries) {
+        if (!WORKSPACE_NAME.test(entry.name) || !entry.isDirectory())
+            continue;
+        const directory = join(root, entry.name);
+        try {
+            const metadata = await stat(directory);
+            if (now - metadata.mtimeMs <= STALE_BUILD_WORKSPACE_AGE_MS)
+                continue;
+            await rm(directory, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            removed += 1;
+        }
+        catch {
+            // Cleanup must never replace or prevent the build the user requested.
+        }
+    }
+    return removed;
+}

package/scripts/copy-snapshot.js

@@ -0,0 +1,48 @@
+/**
+ * Copy the finalized snapshot into the built output under its digest name.
+ *
+ * Runs after Astro has emptied and rewritten the output directory, so a DB built
+ * before the render is not deleted by the render. The copied bytes are re-hashed
+ * against the binding: the public filename is a claim about the file, and this is
+ * where the build proves it.
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { snapshotFileName } from "../src/lib/snapshot.js";
+import { readBuildBinding, snapshotWorkspace } from "../src/lib/snapshot-reader.js";
+/**
+ * @param outputDirectory Directory to copy into, absolute or cwd-relative.
+ * @returns The same-origin URL the copied file is bound to.
+ * @throws when no binding exists or the copied bytes do not match the digest.
+ */
+export function copySnapshotToOutput(outputDirectory, workspace = snapshotWorkspace()) {
+    const binding = readBuildBinding(workspace);
+    if (binding === undefined) {
+        throw new Error('no snapshot binding: run the snapshot build before copying it into the output');
+    }
+    const source = resolve(workspace, 'snapshot.sqlite');
+    const target = resolve(outputDirectory, snapshotFileName(binding.digest));
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(source, target);
+    const digest = createHash('sha256').update(readFileSync(target)).digest('hex');
+    if (digest !== binding.digest) {
+        throw new Error('copied snapshot bytes do not match the digest in its bound URL');
+    }
+    return binding.url;
+}
+function main() {
+    const output = process.argv[2] ?? 'dist';
+    try {
+        const url = copySnapshotToOutput(output);
+        console.log(`snapshot bound: ${url}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main());

package/scripts/copy-wasm.js

@@ -0,0 +1,57 @@
+/**
+ * Copy the staged SQLite runtime into the built output under `/wasm/`.
+ *
+ * Mirrors `copy-snapshot.ts`: runs after Astro has rewritten the output, copies
+ * every staged member, and re-hashes the WASM against the binding so the public
+ * filename is proven about the published bytes.
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readWasmBinding } from "../src/lib/wasm-asset.js";
+import { snapshotWorkspace } from "../src/lib/snapshot-reader.js";
+/** Read the staged runtime binding, or `undefined` when this build staged none. */
+export function readStagedWasm(workspace = snapshotWorkspace()) {
+    try {
+        return readWasmBinding(JSON.parse(readFileSync(resolve(workspace, 'wasm.json'), 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * @returns The same-origin URL the copied WASM is bound to.
+ * @throws when no binding exists or the copied bytes do not match the digest.
+ */
+export function copyWasmToOutput(outputDirectory, workspace = snapshotWorkspace()) {
+    const binding = readStagedWasm(workspace);
+    if (binding === undefined) {
+        throw new Error('no wasm binding: run the wasm build before copying it into the output');
+    }
+    const staging = resolve(workspace, 'wasm');
+    for (const member of binding.members) {
+        const name = member.split('/').at(-1);
+        const target = resolve(outputDirectory, member);
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(resolve(staging, name), target);
+    }
+    const digest = createHash('sha256').update(readFileSync(resolve(outputDirectory, binding.url.slice(1)))).digest('hex');
+    if (digest !== binding.digest) {
+        throw new Error('copied wasm bytes do not match the digest in their bound URL');
+    }
+    return binding.url;
+}
+function main() {
+    const output = process.argv[2] ?? 'dist';
+    try {
+        console.log(`wasm bound: ${copyWasmToOutput(output)}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main());

package/scripts/emit-redirects.js

@@ -0,0 +1,64 @@
+/**
+ * Emits `dist/_redirects` after the Astro build.
+ *
+ * Generated rather than committed under `public/`, so the redirect map cannot
+ * drift from the artifact it describes.
+ *
+ * The map is empty today, and correctly so: no public URL has ever been
+ * stranded (see {@link renderRedirects}). What ships is the version-stamped
+ * header, which is what ties a deployed map back to the artifact that produced
+ * it — and the working, tested emission path for the first rename that does
+ * strand one.
+ *
+ * A build step rather than an Astro route: `src/pages/_redirects.ts` would be
+ * ignored (Astro excludes underscore-prefixed files from routing), and the file
+ * is consumed by the host rather than served, so it does not belong in the
+ * route model. It follows `scripts/validate-content.ts` — same shape, same
+ * place in the build chain.
+ */
+import { writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { SCHEMA_VERSION } from "../src/lib/schema.js";
+import { REDIRECT_RULES, renderRedirects } from "../src/lib/routes.js";
+import { loadArtifact, readArtifact } from "../src/lib/artifact-source.js";
+import { contentVersion } from "./validate-content.js";
+const DIST = fileURLToPath(new URL('../dist', import.meta.url));
+/**
+ * Write `_redirects` into a built site.
+ *
+ * @param outDirectory Where the build actually wrote. Defaults to this
+ *   repository's own `dist/`, which is where `pnpm run build` puts it. The
+ *   packaged CLI builds into a staging directory instead — Astro renames assets
+ *   out of `<root>/.astro` and a rename cannot cross a device — so the emitter
+ *   must be told, rather than assuming the one path that used to be the only
+ *   possibility.
+ */
+export function emitRedirects(outDirectory = DIST) {
+    // Re-validated rather than imported through `src/lib/content.ts`: the
+    // accessor is written for the Astro build, and reading the artifact here
+    // keeps this script runnable on its own. It reads whichever artifact the
+    // build read, so a fixture build's redirect map describes the fixture.
+    //
+    // The validated result is discarded: the rule set is a literal, so nothing
+    // emitted here is derived from the entries. The call is the validation.
+    loadArtifact();
+    writeFileSync(join(outDirectory, '_redirects'), renderRedirects(REDIRECT_RULES, {
+        schema: SCHEMA_VERSION,
+        content: contentVersion(readArtifact()),
+    }), 'utf8');
+    return REDIRECT_RULES.length;
+}
+function main() {
+    try {
+        const rules = emitRedirects();
+        console.log(`redirects ok: ${rules} permanent rule${rules === 1 ? '' : 's'}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main());