blogwright-analytics 0.3.3

package/dist/write-transform-manifest.mjs

@@ -0,0 +1,365 @@
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+//#region ../core/dist/ports.js
+/**
+* Repo-owned ports shared across packages. Domain code depends on these
+* interfaces; adapters (see `adapters/`) implement them against real
+* infrastructure and are constructed only at a composition root.
+*/
+/** Raised by {@link FileSystem} implementations when a path has no file. */
+var FileNotFoundError = class extends Error {
+	path;
+	constructor(path) {
+		super(`file not found: ${path}`);
+		this.name = "FileNotFoundError";
+		this.path = path;
+	}
+};
+//#endregion
+//#region ../core/dist/adapters/node-fs.js
+/** Node adapter for the FileSystem port (real disk I/O via node:fs). */
+function isAbsence(err) {
+	const code = err.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+function contextualise(operation, path, err) {
+	return new Error(`${operation} ${path} failed: ${err.message}`, { cause: err });
+}
+/** Build the real-disk FileSystem adapter. */
+function createNodeFileSystem() {
+	return {
+		async readText(path) {
+			try {
+				return await readFile(path, "utf8");
+			} catch (err) {
+				throw isAbsence(err) ? new FileNotFoundError(path) : contextualise("reading", path, err);
+			}
+		},
+		async readBytes(path) {
+			try {
+				return await readFile(path);
+			} catch (err) {
+				throw isAbsence(err) ? new FileNotFoundError(path) : contextualise("reading", path, err);
+			}
+		},
+		async writeText(path, text) {
+			try {
+				await mkdir(dirname(path), { recursive: true });
+				await writeFile(path, text);
+			} catch (err) {
+				throw contextualise("writing", path, err);
+			}
+		},
+		async exists(path) {
+			try {
+				await stat(path);
+				return true;
+			} catch (err) {
+				if (isAbsence(err)) return false;
+				throw contextualise("checking", path, err);
+			}
+		},
+		async listFiles(dir) {
+			try {
+				return (await readdir(dir, {
+					recursive: true,
+					withFileTypes: true
+				})).filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name))).sort();
+			} catch (err) {
+				throw isAbsence(err) ? new FileNotFoundError(dir) : contextualise("listing", dir, err);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/transform/handler.ts
+/**
+* The environment variable naming the Secrets Manager secret behind
+* `visitor_key`, set on the function by the `analytics-transform-function`
+* node (task 50). The *name* travels in the environment; the value never does,
+* so it cannot be read off the function's configuration.
+*/
+const SALT_SECRET_NAME_ENV = "ANALYTICS_SALT_SECRET_NAME";
+//#endregion
+//#region src/transform-hash.ts
+/**
+* The transform Lambda's build identity: a reproducible hash of the *source*
+* the function is bundled from, the artifact names that hash is stamped
+* beside, and the one derivation of the zip key that hash produces.
+*
+* This is step 5 of
+* [§Implementation notes](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md) -
+* "The hash keys the uploaded zip so identical source never redeploys the
+* function" - and it exists as its own module so `nodes.ts` (task 50) consumes
+* a derivation rather than restating a key format. A key spelled twice is a key
+* that can disagree with itself, and the disagreement is invisible: the
+* function silently redeploys on every reconcile, or worse, never redeploys
+* after a real source change.
+*
+* ## Why the *source*, never the bundle
+*
+* `DEVELOPMENT.md` §Repository hygiene states the rule this module obeys: "The
+* build-agent manifest hashes the agent's *source*, not the built bundle, so
+* image keys do not vary by platform." Bundler output varies with the
+* toolchain and the host (macOS laptop vs the Linux CI runner); source bytes do
+* not. Hashing the bundle would key the same code under two different zip keys
+* depending on who ran `pnpm build`, redeploying the function on every
+* platform switch for no change at all. So the bundle path appears nowhere in
+* the input list below - which is also why `packages/analytics/src/aws/lambda.ts`
+* (task 36) deliberately does not surface `CodeSha256`: that digests the zip
+* Lambda holds, and comparing it to this hash would compare two different
+* things.
+*
+* ## What is in the hash, and why each input is there
+*
+* The shape follows `agentSourceHash` (`packages/build-agent/src/agent-hash.ts`)
+* exactly: collect, label, sort by label with a codepoint comparison, and
+* digest each input as `label` NUL `bytes` NUL. The framing matters - without
+* the labels a file rename would leave the hash unchanged, and without the NUL
+* separators two adjacent inputs could be split differently and collide.
+*
+* The inputs are a deliberate superset of what rolldown actually tree-shakes
+* into the bundle: an unrelated change to this package or to core can force a
+* (harmless) redeploy, which is the right trade against ever shipping a stale
+* transform. `core/src` is in because the bundle genuinely inlines it - the
+* entry constructs core's `SigningClient` and `SecretsManagerClient` - and the
+* lockfile, `tsconfig.json` and the rolldown config are in because each of them
+* changes the emitted bundle without changing a single line of this package's
+* own source. The rolldown config lives at `src/transform/rolldown.config.ts`,
+* so the `analytics/src` collection below already carries it; it is not listed
+* a second time, because hashing the same bytes under two labels adds nothing.
+* `transform-hash.test.ts` proves each of those inputs is live by changing one
+* byte of it and asserting the hash moves.
+*
+* Test files are excluded (the `.test.ts` filter, as in `agentSourceHash`):
+* they are never bundled, so a test-only edit must not redeploy the function.
+*
+* ## No direct filesystem call here
+*
+* Reading crosses the {@link FileSystem} port rather than Node's `fs` module,
+* so this stays a domain module under DEVELOPMENT.md §Hexagonal architecture
+* and no `packages/analytics/src/` path has to join the `no-restricted-imports`
+* override list in `.oxlintrc.json`. The real adapter is constructed in
+* `transform/write-manifest.ts`, the build-time edge that runs this.
+*/
+/**
+* Hex characters kept from the SHA-256 digest. Twelve, as `agentSourceHash`
+* slices to: enough that a collision between two revisions of one small source
+* tree is not a practical concern, short enough to read in a resource name.
+*/
+const HASH_LENGTH = 12;
+/** A well-formed {@link transformSourceHash} result. */
+const HASH_PATTERN = new RegExp(`^[0-9a-f]{${HASH_LENGTH}}$`);
+/**
+* Where the build puts the Lambda artifacts, relative to the package root.
+* Its own directory, not `dist/transform/` (which `tsc` fills with the
+* unbundled modules), so the bundle can never be overwritten by the compiler.
+*
+* It holds two files, and they are not both deployment artifacts:
+* {@link TRANSFORM_BUNDLE_FILE} is the zip's single entry, and
+* {@link TRANSFORM_MANIFEST_FILE} is read *beside* the zip at deploy time for
+* the hash and the key it derives. Task 50 zips the bundle file alone - see
+* {@link TRANSFORM_BUNDLE_FILE} for why a one-file zip is the shape the
+* `Handler` string assumes - and never the directory wholesale.
+*/
+const TRANSFORM_BUNDLE_DIR = "dist/transform-bundle";
+/**
+* The bundle's file name inside {@link TRANSFORM_BUNDLE_DIR} - and, unchanged,
+* inside the zip task 50 uploads.
+*
+* `.mjs`, not `.js`: the bundle is ESM, and the Lambda Node runtime reads a
+* `.js` file in the deployment package as CommonJS unless the zip also carries
+* a `package.json` declaring `"type": "module"`. A one-file zip with a `.mjs`
+* extension needs no such companion, so there is no second file to forget - and
+* this file, alone, is what that zip contains.
+*
+* That the emitted bundle really is ESM exporting this module's binding is
+* asserted by `transform/write-manifest.ts` on every build, because no test
+* sees the emitted file.
+*/
+const TRANSFORM_BUNDLE_FILE = "index.mjs";
+/**
+* The build-time manifest carrying the hash and the key it derives, written
+* beside the bundle in {@link TRANSFORM_BUNDLE_DIR} and read beside the zip -
+* never packed inside it.
+*/
+const TRANSFORM_MANIFEST_FILE = "transform-manifest.json";
+/**
+* The `Handler` string the function is configured with (task 50), spelled here
+* because it is derived from this module's artifact names and nothing else:
+* the bundle's base name, then the binding `transform/entry.ts` exports.
+*
+* It is here rather than in `nodes.ts` because getting it wrong fails at
+* *invoke* time with an AWS-side error and no build error - every record would
+* land in the Firehose error prefix with nothing in this repo reporting it, and
+* the only symptom is an empty dashboard. Two checks pin this constant against
+* a real export rather than a comment: `transform/entry.test.ts` against the
+* entry *module*'s, and `transform/write-manifest.ts` against the emitted
+* *bundle*'s, on every build. A rename or a bundler-config change reddens one
+* of them instead of silently emptying the warehouse.
+*/
+const TRANSFORM_LAMBDA_HANDLER = "index.handler";
+/**
+* Every non-test file under `root`, labelled by its path under `prefix`.
+*
+* `listFiles` is contracted to return sorted, `root`-relative paths, so the
+* collection order does not depend on the host filesystem's readdir order;
+* separators are normalised to `/` so a label is the same on every platform.
+*/
+async function collectSource(fs, root, prefix) {
+	return (await fs.listFiles(root)).filter((relativePath) => !relativePath.endsWith(".test.ts")).map((relativePath) => ({
+		label: `${prefix}/${relativePath.split(sep).join("/")}`,
+		path: join(root, relativePath)
+	}));
+}
+/**
+* A hash of the transform's *source*, computed at bundle time and stamped into
+* `dist/transform-bundle/transform-manifest.json` (see
+* `transform/write-manifest.ts`) so the plugin reads it at runtime without any
+* access to the source tree.
+*
+* `dir` is the analytics package root; core and the workspace root are located
+* from it the way `agentSourceHash` locates its own siblings. Only labels,
+* never absolute paths, reach the digest, so the same tree checked out at two
+* different paths hashes identically - a property `transform-hash.test.ts`
+* asserts, because a hash that moves with the checkout directory would key the
+* same code under a different zip on every machine.
+*/
+async function transformSourceHash(dir, fs) {
+	const coreDir = join(dir, "..", "core");
+	const rootDir = join(dir, "..", "..");
+	const inputs = [
+		...await collectSource(fs, join(dir, "src"), "analytics/src"),
+		...await collectSource(fs, join(coreDir, "src"), "core/src"),
+		{
+			label: "analytics/package.json",
+			path: join(dir, "package.json")
+		},
+		{
+			label: "analytics/tsconfig.json",
+			path: join(dir, "tsconfig.json")
+		},
+		{
+			label: "core/package.json",
+			path: join(coreDir, "package.json")
+		},
+		{
+			label: "workspace/tsconfig.base.json",
+			path: join(rootDir, "tsconfig.base.json")
+		},
+		{
+			label: "workspace/pnpm-lock.yaml",
+			path: join(rootDir, "pnpm-lock.yaml")
+		}
+	].sort((a, b) => a.label < b.label ? -1 : 1);
+	const digest = createHash("sha256");
+	for (const { label, path } of inputs) {
+		digest.update(label);
+		digest.update("\0");
+		digest.update(await fs.readBytes(path));
+		digest.update("\0");
+	}
+	return digest.digest("hex").slice(0, HASH_LENGTH);
+}
+/**
+* The key the bundled transform's zip is stored and compared under, derived
+* from {@link transformSourceHash} and spelled in this one place. Task 50's
+* `analytics-transform-function` records it and skips the code update when it
+* has not moved, so identical source provably maps to an identical key.
+*
+* A malformed hash raises rather than producing a key: `transform-undefined.zip`
+* is a key that compares equal to itself forever, which would pin the deployed
+* function at whatever code first shipped and never update it again.
+*/
+function transformZipKey(hash) {
+	if (!HASH_PATTERN.test(hash)) throw new Error(`the analytics transform's source hash must be ${HASH_LENGTH} lowercase hex characters, not "${hash}" - rebuild the package so ${TRANSFORM_MANIFEST_FILE} is regenerated`);
+	return `analytics/transform/transform-${hash}.zip`;
+}
+//#endregion
+//#region src/transform/write-manifest.ts
+/**
+* Build step: check the emitted bundle, then stamp
+* `dist/transform-bundle/transform-manifest.json` with the reproducible source
+* hash and the zip key derived from it.
+*
+* Runs after the rolldown bundle with the analytics package root as its cwd
+* (see the package's `build` script), so the shipped artifact set - the bundle
+* and this manifest - is self-describing and the plugin's function node reads
+* the hash at deploy time without any access to the source trees. It is the
+* `packages/build-agent/src/write-manifest.ts` precedent, moved onto the
+* FileSystem port.
+*
+* This is the build-time edge component of the pair: it constructs the real
+* disk adapter - core's `createNodeFileSystem` - which is why
+* `transform-hash.ts` never has to. That keeps every `packages/analytics/src/`
+* module free of a direct filesystem import and out of the `.oxlintrc.json`
+* `no-restricted-imports` override list.
+*
+* ## Why the emitted bundle is checked here
+*
+* `entry.test.ts` pins the *source* module's exports against
+* {@link TRANSFORM_LAMBDA_HANDLER}, and that is all it can do: under vitest
+* `import('./entry.js')` resolves to `entry.ts`, never to the file rolldown
+* emits. So everything between the source and the artifact - the output
+* `format`, `codeSplitting`, the `input` rolldown is pointed at - is asserted
+* by no test at all. Changing `format: 'esm'` to `'cjs'` in
+* `rolldown.config.ts` is a one-token edit that leaves build, typecheck, test,
+* lint, oxfmt and knip green while emitting a bundle Lambda cannot resolve
+* `index.handler` from at all: every record would go to the Firehose error
+* prefix, and the only symptom would be an empty dashboard - the same failure
+* `entry.ts` and `transform-hash.ts` are written against, reached by a
+* different route.
+*
+* The check therefore loads the emitted `.mjs` the way Lambda's runtime will
+* and asserts the configured `Handler` resolves. It lives in this build step
+* rather than in a `dist`-gated case in `entry.test.ts` for two reasons:
+*
+* - **It cannot be skipped.** This runs on every `pnpm build`; a test that
+*   needs `dist/` to exist runs only when someone happens to have built, which
+*   is a weaker guarantee than a build step in the chain.
+* - **It runs before the stamp.** A bundle that fails the check never acquires
+*   a hash or a zip key, so task 50 has nothing to deploy rather than a fresh
+*   key over a function that cannot start.
+*/
+/** Lambda reads `Handler` as `<module base name>.<exported binding>`. */
+const [, handlerBinding] = TRANSFORM_LAMBDA_HANDLER.split(".");
+/**
+* A stand-in secret *name*, never a secret. `entry.ts` binds its handler at
+* module load and the factory resolves the secret's name then, so importing
+* the bundle at all requires {@link SALT_SECRET_NAME_ENV} to be set - that
+* reject-at-init is deliberate, and `entry.test.ts` sets a placeholder for the
+* same reason. Nothing is invoked and no secret is read: the check ends at the
+* shape of the export.
+*/
+const EXPORT_CHECK_SECRET_NAME = "build-time-export-check/not-a-real-secret";
+/**
+* Assert the bundle rolldown just emitted exports the binding the function's
+* configured `Handler` names, as the async function Lambda awaits. Throws -
+* failing `pnpm build` - if it does not.
+*/
+async function assertBundleExportsHandler() {
+	if (!process.env["ANALYTICS_SALT_SECRET_NAME"]?.trim()) process.env[SALT_SECRET_NAME_ENV] = EXPORT_CHECK_SECRET_NAME;
+	const bundlePath = resolve(TRANSFORM_BUNDLE_DIR, TRANSFORM_BUNDLE_FILE);
+	let bundle;
+	try {
+		bundle = await import(pathToFileURL(bundlePath).href);
+	} catch (cause) {
+		throw new Error(`${TRANSFORM_BUNDLE_DIR}/${TRANSFORM_BUNDLE_FILE} could not be loaded as an ES module, so Lambda would fail to initialise it and every record would land in the Firehose error prefix - the cause below says why, and a rolldown output \`format\` other than 'esm' is the usual one`, { cause });
+	}
+	const bound = bundle[handlerBinding];
+	if (typeof bound !== "function") throw new Error(`${TRANSFORM_BUNDLE_DIR}/${TRANSFORM_BUNDLE_FILE} exports [${Object.keys(bundle).join(", ")}], so the configured Handler "${TRANSFORM_LAMBDA_HANDLER}" resolves to nothing at invoke time and every record would land in the Firehose error prefix - check the rolldown \`input\` and the binding \`transform/entry.ts\` exports`);
+	if (bound.constructor.name !== "AsyncFunction") throw new Error(`${TRANSFORM_BUNDLE_DIR}/${TRANSFORM_BUNDLE_FILE} exports "${handlerBinding}" as an ordinary ${bound.constructor.name}, not the async function Lambda awaits - \`transform/entry.ts\` must export the handler \`createTransformHandler\` returns, not the factory itself`);
+}
+await assertBundleExportsHandler();
+const fs = createNodeFileSystem();
+const hash = await transformSourceHash(process.cwd(), fs);
+const manifest = {
+	hash,
+	key: transformZipKey(hash)
+};
+await fs.writeText(`${TRANSFORM_BUNDLE_DIR}/${TRANSFORM_MANIFEST_FILE}`, `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(`${TRANSFORM_MANIFEST_FILE}: ${hash}`);
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "blogwright-analytics",
+  "blogwright": {
+    "plugin": "analytics"
+  },
+  "version": "0.3.3",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "dist/app"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rolldown -c src/transform/rolldown.config.ts && node dist/write-transform-manifest.mjs && tsc -p tsconfig.json && cd app && vite build",
+    "typecheck": "tsc -p tsconfig.typecheck.json && cd app && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings",
+    "lint": "oxlint src app",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@duckdb/node-api": "1.5.5-r.4",
+    "blogwright-core": "workspace:*",
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.70.3",
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
+    "@types/node": "^26.1.0",
+    "layerchart": "2.0.2",
+    "oxlint": "^1.72.0",
+    "rolldown": "^1.1.4",
+    "svelte": "^5.57.0",
+    "svelte-check": "^4.7.6",
+    "typescript": "^6.0.3",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.9"
+  },
+  "description": "Traffic analytics for blogwright: CloudFront access logs routed through Firehose into an Iceberg table, with a local dashboard. Installed on demand with `blogwright plugin add analytics`, never shipped with the CLI.",
+  "keywords": [
+    "analytics",
+    "cloudfront",
+    "firehose",
+    "iceberg"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antstanley/blogwright.git"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}