blogwright-analytics 0.3.3

package/dist/config.js

@@ -0,0 +1,317 @@
+/**
+ * This package owns the `analytics` config key end to end: its shape, its
+ * defaults, and the validator core's `parseConfig` deliberately does not run
+ * (`packages/core/src/config.ts:242` merges an `analytics` block through
+ * untouched, so a config carrying one is valid and inert when the plugin is
+ * not installed).
+ *
+ * **Two shapes, and why the seam between them is where it is.**
+ * `validateAnalyticsConfig` is the function this package's
+ * `Plugin.validateConfig` hands core's raw block to, so whatever it returns is
+ * what the host puts on `ctx.pluginConfig` (`packages/core/src/plugin.ts:85-93`).
+ * It applies every default it can: `namespace`, `table`, `bots` and
+ * `dashboard.port` default to plain literals, so they come back total and no
+ * reader downstream re-checks them for `undefined`.
+ *
+ * `tableBucket` and `saltSecretName` cannot be defaulted there. Both carry the
+ * environment, and the SPI hands `validateConfig` the block and nothing else -
+ * no `env`, no `siteName`. So an operator's overrides for those two are
+ * carried under {@link ENV_DERIVED}, a symbol this module does not export, and
+ * {@link resolveAnalyticsConfig} - which takes the plugin context, and
+ * therefore always has the environment - is the only way to a bucket name or a
+ * salt name.
+ *
+ * That sealing is load-bearing, not tidiness. Were `tableBucket` merely
+ * optional on the validated block, a node downstream could write
+ * ``ctx.pluginConfig.tableBucket ?? `${ctx.config.siteName}-analytics` `` and
+ * it would compile, typecheck and pass its own tests - and staging would then
+ * resolve to production's bucket. With the field absent from the type, that
+ * read is `TS2339: Property 'tableBucket' does not exist on type
+ * 'AnalyticsConfig'`, which `pnpm typecheck` fails on; `config.test.ts` pins
+ * the diagnostic so the seal cannot be opened silently.
+ *
+ * **Every derived default carries the environment**, matching `deriveNames`'
+ * `<env>-<siteName>` prefix (`packages/core/src/config.ts:352`):
+ * `tableBucket` is `<env>-<siteName>-analytics` and `saltSecretName` is
+ * `<siteName>/<env>/analytics-salt`. Do not "simplify" the environment out of
+ * either one. Without it staging and production resolve to the *same* Iceberg
+ * table and the same salt, and `blogwright analytics destroy --yes` run in
+ * staging issues `DeleteTableBucket` against production's data. Nothing in the
+ * system catches that: state is scoped per environment
+ * (`state/<env>.analytics.json`), so each environment's state file correctly
+ * records the bucket it was told to use and neither can see the collision.
+ * AWS gives a second, quieter reason - it "does not recommend using multiple
+ * Firehose streams to write data to the same Apache Iceberg table", because
+ * Iceberg's optimistic concurrency makes the streams contend.
+ *
+ * Pure data and pure functions only: no `node:` builtin, no vendor SDK, no
+ * `fetch`. See [the change spec's §Configuration → The `analytics`
+ * block](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md).
+ */
+/**
+ * The key an operator's `tableBucket`/`saltSecretName` overrides ride on. A
+ * module-private `unique symbol`: TypeScript emits it into `config.d.ts`
+ * unexported, so no module outside this one can name it, and neither
+ * `ctx.pluginConfig.tableBucket` nor `ctx.pluginConfig[ENV_DERIVED]` compiles
+ * anywhere else. That is the point - see this module's doc comment for the
+ * `?? <env-less fallback>` line it exists to make unwritable.
+ */
+const ENV_DERIVED = Symbol('analytics env-derived overrides');
+/** Default Iceberg namespace. */
+const DEFAULT_NAMESPACE = 'web';
+/** Default Iceberg table - the one `schema.ts` describes. */
+const DEFAULT_TABLE = 'page_views';
+/** Default bot handling: keep bot rows, mark them, and leave filtering to the query. */
+const DEFAULT_BOTS = 'flag';
+/**
+ * Default port for the local dashboard server. Exported because the dashboard
+ * server binds this exact number: it imports the constant rather than
+ * restating it, so the default has one home.
+ */
+export const DEFAULT_DASHBOARD_PORT = 4317;
+/** Lowest port the dashboard may bind - anything below it needs root on Unix. */
+const MIN_DASHBOARD_PORT = 1024;
+/** Highest port there is. */
+const MAX_DASHBOARD_PORT = 65535;
+/** Shortest S3 bucket name S3 accepts. */
+const TABLE_BUCKET_MIN_LENGTH = 3;
+/** Longest S3 bucket name S3 accepts - the same limit `deriveNames` enforces. */
+const TABLE_BUCKET_MAX_LENGTH = 63;
+/**
+ * S3 bucket naming, narrowed to what an S3 Tables bucket takes: lowercase
+ * alphanumerics and dashes, {@link TABLE_BUCKET_MIN_LENGTH} to
+ * {@link TABLE_BUCKET_MAX_LENGTH} characters. Composed from those two
+ * constants rather than hard-coded inside the pattern, so the bounds have one
+ * home and the rejection message quotes the same numbers the pattern enforces.
+ */
+const TABLE_BUCKET_PATTERN = new RegExp(`^[0-9a-z-]{${TABLE_BUCKET_MIN_LENGTH},${TABLE_BUCKET_MAX_LENGTH}}$`);
+/** Iceberg identifier: an S3 Tables catalog rejects anything else. */
+const IDENTIFIER_PATTERN = /^[a-z0-9_]+$/;
+/** Characters permitted in a Secrets Manager secret name - the class `pds.secretName` uses. */
+const SECRET_NAME_PATTERN = /^[\w/+=.@-]+$/;
+/** The `bots` union, as data, so the validator and its message read one list. */
+const BOTS_MODES = ['flag', 'filter'];
+/** Every key the block allows - the schema's `additionalProperties: false`, as data. */
+const ANALYTICS_KEYS = [
+    'tableBucket',
+    'namespace',
+    'table',
+    'bots',
+    'saltSecretName',
+    'dashboard',
+];
+/** Every key the `dashboard` sub-block allows. */
+const DASHBOARD_KEYS = ['port'];
+/**
+ * Narrow an `unknown` to an object. The `!== null` is the `typeof` guard's
+ * usual companion, not a domain value: nothing in this module returns or
+ * accepts `null` for a setting - absence is `undefined`.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Render a rejected value for a message: strings quoted, as core's messages quote them. */
+function formatValue(value) {
+    if (typeof value === 'string')
+        return `"${value}"`;
+    if (isRecord(value) || Array.isArray(value))
+        return JSON.stringify(value);
+    return String(value);
+}
+function isBotHandling(value) {
+    return BOTS_MODES.some((mode) => mode === value);
+}
+/**
+ * The `tableBucket` default. Carries `env` first, matching `deriveNames`'
+ * `<env>-<siteName>` prefix - see this module's doc comment for what dropping
+ * it destroys.
+ */
+function defaultTableBucket(site) {
+    return `${site.env}-${site.siteName}-analytics`;
+}
+/**
+ * The `saltSecretName` default. Carries `env` as a path segment, so two
+ * environments hash `visitor_key` with two different salts.
+ */
+function defaultSaltSecretName(site) {
+    return `${site.siteName}/${site.env}/analytics-salt`;
+}
+/**
+ * Validate a raw `analytics` config block, boundary-checked as `unknown`
+ * because it comes off `parseConfigDocument`'s `raw` half (a plugin's block
+ * has no type until its own package narrows it). An absent block validates as
+ * an empty one, so installing the plugin without writing an `analytics` key is
+ * valid.
+ *
+ * Applies the four literal defaults, so `namespace`, `table`, `bots` and
+ * `dashboard.port` are total on the returned block. `tableBucket` and
+ * `saltSecretName` are validated here too, but sealed under
+ * {@link ENV_DERIVED}: their defaults carry the environment, which this
+ * signature does not, so {@link resolveAnalyticsConfig} is where they resolve.
+ *
+ * Raises in the repo's vocabulary (`packages/core/src/config.ts:274-340`),
+ * naming the offending key and value.
+ */
+export function validateAnalyticsConfig(raw) {
+    const block = raw === undefined ? {} : raw;
+    if (!isRecord(block)) {
+        throw new Error(`config.analytics must be an object, got ${formatValue(block)}`);
+    }
+    for (const key of Object.keys(block)) {
+        if (!ANALYTICS_KEYS.some((known) => known === key)) {
+            throw new Error(`config.analytics.${key} is not a known setting - allowed keys are ${ANALYTICS_KEYS.join(', ')}`);
+        }
+    }
+    return {
+        namespace: validateIdentifier(block['namespace'], 'namespace') ?? DEFAULT_NAMESPACE,
+        table: validateIdentifier(block['table'], 'table') ?? DEFAULT_TABLE,
+        bots: validateBots(block['bots']) ?? DEFAULT_BOTS,
+        dashboard: { port: validateDashboardPort(block['dashboard']) },
+        [ENV_DERIVED]: validateEnvDerivedOverrides(block),
+    };
+}
+/**
+ * Validate the two settings whose defaults need the environment, returning
+ * them as the sealed overrides {@link resolveAnalyticsConfig} later reads. An
+ * absent setting stays absent: this function has no environment to default it
+ * with, which is the whole reason the seal exists.
+ */
+function validateEnvDerivedOverrides(raw) {
+    const overrides = {};
+    const tableBucket = raw['tableBucket'];
+    if (tableBucket !== undefined) {
+        if (typeof tableBucket !== 'string' || !TABLE_BUCKET_PATTERN.test(tableBucket)) {
+            throw new Error(`config.analytics.tableBucket must be ${TABLE_BUCKET_MIN_LENGTH}..${TABLE_BUCKET_MAX_LENGTH} lowercase alphanumeric/dash characters, got ${formatValue(tableBucket)}`);
+        }
+        overrides.tableBucket = tableBucket;
+    }
+    const saltSecretName = raw['saltSecretName'];
+    if (saltSecretName !== undefined) {
+        // Same character class and same message shape as `config.pds.secretName`
+        // (`packages/core/src/config.ts:337`): both name a Secrets Manager secret,
+        // so an operator who has hit one message recognises the other.
+        if (typeof saltSecretName !== 'string' || !SECRET_NAME_PATTERN.test(saltSecretName)) {
+            throw new Error(`config.analytics.saltSecretName has invalid characters: ${formatValue(saltSecretName)}`);
+        }
+        overrides.saltSecretName = saltSecretName;
+    }
+    return overrides;
+}
+/**
+ * Validate an Iceberg identifier (`namespace`, `table`), returning `undefined`
+ * when the setting is absent so the caller applies its own named default.
+ */
+function validateIdentifier(raw, key) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || !IDENTIFIER_PATTERN.test(raw)) {
+        throw new Error(`config.analytics.${key} must be lowercase alphanumeric/underscores, got ${formatValue(raw)}`);
+    }
+    return raw;
+}
+/** Validate the `bots` setting, returning `undefined` when it is absent. */
+function validateBots(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isBotHandling(raw)) {
+        throw new Error(`config.analytics.bots must be one of ${BOTS_MODES.join(', ')}, got ${formatValue(raw)}`);
+    }
+    return raw;
+}
+/**
+ * Validate the `dashboard` sub-block and return the port it settles on -
+ * {@link DEFAULT_DASHBOARD_PORT} when the sub-block or the setting is absent.
+ * Split out to keep the validator at one level of detail.
+ */
+function validateDashboardPort(raw) {
+    if (raw === undefined)
+        return DEFAULT_DASHBOARD_PORT;
+    if (!isRecord(raw)) {
+        throw new Error(`config.analytics.dashboard must be an object, got ${formatValue(raw)}`);
+    }
+    for (const key of Object.keys(raw)) {
+        if (!DASHBOARD_KEYS.some((known) => known === key)) {
+            throw new Error(`config.analytics.dashboard.${key} is not a known setting - allowed keys are ${DASHBOARD_KEYS.join(', ')}`);
+        }
+    }
+    const port = raw['port'];
+    if (port === undefined)
+        return DEFAULT_DASHBOARD_PORT;
+    // One message for one validity condition: an integer inside the range. A
+    // fractional or non-numeric port is outside that range as much as `80` is.
+    // The `typeof` does the narrowing `Number.isInteger` does not - its lib
+    // signature returns `boolean`, not a predicate - so at runtime it is
+    // redundant with the next clause, which already rejects every non-number.
+    if (typeof port !== 'number' ||
+        !Number.isInteger(port) ||
+        port < MIN_DASHBOARD_PORT ||
+        port > MAX_DASHBOARD_PORT) {
+        throw new Error(`config.analytics.dashboard.port must be in ${MIN_DASHBOARD_PORT}..${MAX_DASHBOARD_PORT}, got ${formatValue(port)}`);
+    }
+    return port;
+}
+/**
+ * Unseal the environment-carrying overrides off a validated block, rejecting a
+ * block that never went through {@link validateAnalyticsConfig}.
+ *
+ * The type says that cannot happen and the runtime says otherwise, because the
+ * one seam that fills `ctx.pluginConfig` erases `TConfig`: the CLI dispatches
+ * over `Plugin<unknown>` and `toPluginContext(ops)` returns
+ * `PluginContext<unknown>` (`packages/cli/src/plugin-commands.ts:241,466`), so
+ * an unvalidated block passes the compiler exactly there - and
+ * {@link resolveAnalyticsConfig} is exported, so a caller can hand one over
+ * directly too. Such a block carries neither this symbol nor the four literal
+ * defaults, and without this check the first read raised `TypeError: Cannot
+ * read properties of undefined (reading 'tableBucket')` - an internal field
+ * name and no fix.
+ *
+ * Nothing is recovered here, deliberately. The literal defaults are missing on
+ * that block as well, so a fabricated one would carry `undefined` at runtime
+ * for `namespace`, `table`, `bots` and `dashboard.port` - fields whose type
+ * says total - and every reader downstream trusts that type. A throw naming
+ * the function that must run first is loud; a recovered block is silently
+ * wrong.
+ */
+function unsealEnvDerivedOverrides(block) {
+    // Justified by the line below, which is the validation: the declared type
+    // has no `undefined` here precisely because a validated block always has it.
+    const overrides = block[ENV_DERIVED];
+    if (overrides === undefined) {
+        throw new Error('analytics config was not validated: ctx.pluginConfig must come from validateAnalyticsConfig, which applies the defaults this resolver reads');
+    }
+    return overrides;
+}
+/**
+ * Resolve the environment-carrying settings a validated block sealed, giving
+ * the total config every reader downstream holds. Takes the plugin context
+ * rather than a `{ env, siteName }` pair, so the site identity is read out of
+ * `ctx` in one place instead of at each call site and no caller can supply an
+ * environment other than the one it is running in.
+ *
+ * Raises when handed a block the validator did not produce - see
+ * {@link unsealEnvDerivedOverrides}.
+ *
+ * The derived bucket name is length-checked here, where it is derived, exactly
+ * as `deriveNames` checks the site bucket it derives
+ * (`packages/core/src/config.ts:355`). Only the length is checked: `env` and
+ * `siteName` are already held to `^[a-z0-9-]+$` by `deriveNames` and
+ * `validateConfig`, and a second character check here would be a second home
+ * for a rule core already owns.
+ */
+export function resolveAnalyticsConfig(ctx) {
+    const site = { env: ctx.env, siteName: ctx.config.siteName };
+    const block = ctx.pluginConfig;
+    const overrides = unsealEnvDerivedOverrides(block);
+    const tableBucket = overrides.tableBucket ?? defaultTableBucket(site);
+    if (tableBucket.length > TABLE_BUCKET_MAX_LENGTH) {
+        throw new Error(`derived analytics table bucket "${tableBucket}" exceeds S3's ${TABLE_BUCKET_MAX_LENGTH}-char limit; shorten env or siteName`);
+    }
+    return {
+        tableBucket,
+        namespace: block.namespace,
+        table: block.table,
+        bots: block.bots,
+        saltSecretName: overrides.saltSecretName ?? defaultSaltSecretName(site),
+        dashboard: { port: block.dashboard.port },
+    };
+}

package/dist/fixture-ingest.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The recording {@link AnalyticsIngest} the backfill's tests substitute at the
+ * write port, so no test in this package starts DuckDB to prove what was
+ * written. It is the write-side counterpart of `fixture-query.ts`, and it is
+ * shipped beside the interface it implements for the same reason
+ * `createMemoryFileSystem` (`packages/core/src/adapters/memory-fs.ts`) is: a
+ * real implementation of the port, not a stub that agrees with anything.
+ *
+ * **It records rather than judges, with two exceptions, and both are the
+ * contract rather than a convenience.** {@link AnalyticsIngest.insertDay}
+ * documents that a batch is one whole day and that an empty batch is a caller
+ * error; a fake that quietly accepted a row belonging to another day, or an
+ * insert of nothing, would let a backfill defect pass through it and land on
+ * an assertion about something else. Everything a test actually asserts - which
+ * days were written, in which order, with which rows - it reads off
+ * {@link RecordingAnalyticsIngest.calls}, and the fake takes no view on it.
+ * The bound (no day at or after the recorded `createdDay`) in particular is
+ * deliberately NOT enforced here: it is the property the backfill exists to
+ * hold, so a fake that enforced it would answer the question under test.
+ */
+import type { AnalyticsIngest } from './ports.js';
+import type { PageView } from './schema.js';
+/**
+ * One accepted {@link AnalyticsIngest.insertDay}, exactly as it arrived.
+ *
+ * Not exported, following `ports.ts`' `QueryValue`: no consumer needs the
+ * shape by name today - a test reaches it as
+ * `RecordingAnalyticsIngest['calls'][number]` or, in practice, by reading
+ * `call.day` and `call.rows` off it. Export it once something names it.
+ */
+interface RecordedInsert {
+    /** The UTC day the call named. */
+    readonly day: string;
+    /** The rows it carried, in the order the caller handed them over. */
+    readonly rows: readonly PageView[];
+}
+/** The fake, plus the record of what it was asked to write. */
+export interface RecordingAnalyticsIngest extends AnalyticsIngest {
+    /** Every accepted insert, in call order. */
+    readonly calls: readonly RecordedInsert[];
+    /** The days of {@link calls}, in call order - the shape most assertions want. */
+    readonly days: readonly string[];
+}
+/**
+ * Build a {@link RecordingAnalyticsIngest}. Takes nothing: an ingest port has
+ * no result to seed, so the only thing a test needs from it is what it saw.
+ */
+export declare function createRecordingAnalyticsIngest(): RecordingAnalyticsIngest;
+export {};

package/dist/fixture-ingest.js

@@ -0,0 +1,43 @@
+/**
+ * The recording {@link AnalyticsIngest} the backfill's tests substitute at the
+ * write port, so no test in this package starts DuckDB to prove what was
+ * written. It is the write-side counterpart of `fixture-query.ts`, and it is
+ * shipped beside the interface it implements for the same reason
+ * `createMemoryFileSystem` (`packages/core/src/adapters/memory-fs.ts`) is: a
+ * real implementation of the port, not a stub that agrees with anything.
+ *
+ * **It records rather than judges, with two exceptions, and both are the
+ * contract rather than a convenience.** {@link AnalyticsIngest.insertDay}
+ * documents that a batch is one whole day and that an empty batch is a caller
+ * error; a fake that quietly accepted a row belonging to another day, or an
+ * insert of nothing, would let a backfill defect pass through it and land on
+ * an assertion about something else. Everything a test actually asserts - which
+ * days were written, in which order, with which rows - it reads off
+ * {@link RecordingAnalyticsIngest.calls}, and the fake takes no view on it.
+ * The bound (no day at or after the recorded `createdDay`) in particular is
+ * deliberately NOT enforced here: it is the property the backfill exists to
+ * hold, so a fake that enforced it would answer the question under test.
+ */
+/**
+ * Build a {@link RecordingAnalyticsIngest}. Takes nothing: an ingest port has
+ * no result to seed, so the only thing a test needs from it is what it saw.
+ */
+export function createRecordingAnalyticsIngest() {
+    const calls = [];
+    const days = [];
+    return {
+        calls,
+        days,
+        async insertDay(day, rows) {
+            if (rows.length === 0) {
+                throw new Error(`analytics ingest was asked to insert day ${day} with no rows`);
+            }
+            const foreign = rows.find((row) => row.day !== day);
+            if (foreign !== undefined) {
+                throw new Error(`analytics ingest was asked to insert day ${day} carrying a row for day ${foreign.day}`);
+            }
+            calls.push({ day, rows });
+            days.push(day);
+        },
+    };
+}

package/dist/fixture-query.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The fixture-backed {@link AnalyticsQuery} every consumer's test substitutes
+ * at the port, so no test in this package starts DuckDB. It is the analytics
+ * counterpart of `packages/core/src/adapters/memory-fs.ts`: a real
+ * implementation of the port, seeded with data, shipped beside the interface
+ * it implements.
+ *
+ * It is not a stub that answers anything. It runs the *same*
+ * {@link prepareQuery} the DuckDB adapter runs, so an unknown name and an
+ * absent or inverted range are refused here with the same messages a real
+ * dashboard would produce, and it refuses at construction to hold rows that do
+ * not match the query's declared result columns. That second check is the
+ * point: a fake seeded with rows shaped like nothing the query returns lets a
+ * consumer's assertions pass for the wrong reason, which is the commonest way
+ * a test stops being able to fail.
+ *
+ * `calls` records what each accepted call resolved to, so a consumer can
+ * assert *what was bound* - that its date range reached the query, that its
+ * bot flag defaulted from `config.analytics.bots` - without a spy or a mock.
+ */
+import { type AnalyticsConfig } from './config.js';
+import type { AnalyticsQuery, QueryRow } from './ports.js';
+import { type PreparedQuery, type QueryName } from './queries.js';
+/** Rows to answer with, per query name. A name with no entry raises when asked for. */
+export type QueryFixtures = Partial<Record<QueryName, readonly QueryRow[]>>;
+/** The fake, plus the record of what it was asked. */
+export interface FixtureAnalyticsQuery extends AnalyticsQuery {
+    /** Every accepted call, in order, as the shared lookup resolved it. */
+    readonly calls: readonly PreparedQuery[];
+}
+/**
+ * Build an {@link AnalyticsQuery} that answers from `fixtures`.
+ *
+ * `config` defaults to a validated empty `analytics` block, so a consumer that
+ * does not care about bot handling gets task 44's own default rather than a
+ * second copy of it stated here; a consumer that does care passes a block
+ * validated from the raw config it is exercising.
+ */
+export declare function createFixtureAnalyticsQuery(fixtures: QueryFixtures, config?: Pick<AnalyticsConfig, 'bots'>): FixtureAnalyticsQuery;

package/dist/fixture-query.js

@@ -0,0 +1,70 @@
+/**
+ * The fixture-backed {@link AnalyticsQuery} every consumer's test substitutes
+ * at the port, so no test in this package starts DuckDB. It is the analytics
+ * counterpart of `packages/core/src/adapters/memory-fs.ts`: a real
+ * implementation of the port, seeded with data, shipped beside the interface
+ * it implements.
+ *
+ * It is not a stub that answers anything. It runs the *same*
+ * {@link prepareQuery} the DuckDB adapter runs, so an unknown name and an
+ * absent or inverted range are refused here with the same messages a real
+ * dashboard would produce, and it refuses at construction to hold rows that do
+ * not match the query's declared result columns. That second check is the
+ * point: a fake seeded with rows shaped like nothing the query returns lets a
+ * consumer's assertions pass for the wrong reason, which is the commonest way
+ * a test stops being able to fail.
+ *
+ * `calls` records what each accepted call resolved to, so a consumer can
+ * assert *what was bound* - that its date range reached the query, that its
+ * bot flag defaulted from `config.analytics.bots` - without a spy or a mock.
+ */
+import { validateAnalyticsConfig } from './config.js';
+import { prepareQuery, queryDefinition, } from './queries.js';
+/** Render a list for a message, saying so when it is empty rather than trailing off. */
+function formatList(items) {
+    return items.length === 0 ? 'none' : items.join(', ');
+}
+/**
+ * Refuse fixture rows that are not shaped like the query's own result. Checked
+ * once, at construction, so the failure names the test's own fixture rather
+ * than surfacing later as an assertion that passed against the wrong keys.
+ */
+function checkFixtureShape(name, rows) {
+    const expected = [...queryDefinition(name).resultColumns].sort();
+    rows.forEach((row, index) => {
+        const actual = Object.keys(row).sort();
+        if (actual.join(',') !== expected.join(',')) {
+            throw new Error(`fixture row ${index} for analytics query "${name}" must carry exactly its result columns ${formatList(expected)}, got ${formatList(actual)}`);
+        }
+    });
+}
+/**
+ * Build an {@link AnalyticsQuery} that answers from `fixtures`.
+ *
+ * `config` defaults to a validated empty `analytics` block, so a consumer that
+ * does not care about bot handling gets task 44's own default rather than a
+ * second copy of it stated here; a consumer that does care passes a block
+ * validated from the raw config it is exercising.
+ */
+export function createFixtureAnalyticsQuery(fixtures, config = validateAnalyticsConfig({})) {
+    const recorded = new Map();
+    for (const [name, rows] of Object.entries(fixtures)) {
+        if (rows === undefined)
+            continue;
+        checkFixtureShape(name, rows);
+        recorded.set(name, rows);
+    }
+    const calls = [];
+    return {
+        calls,
+        async run(name, params) {
+            const prepared = prepareQuery(name, params, config);
+            calls.push(prepared);
+            const rows = recorded.get(prepared.name);
+            if (rows === undefined) {
+                throw new Error(`no fixture rows recorded for analytics query "${prepared.name}" - recorded queries are ${formatList([...recorded.keys()])}`);
+            }
+            return rows;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Public surface of blogwright-analytics: CloudFront access logs routed
+ * through Firehose into an Iceberg table, with a local dashboard over it.
+ * The plugin is installed on demand with `blogwright plugin add analytics`,
+ * never shipped with the CLI - see DEVELOPMENT.md §Hexagonal architecture
+ * ("Features live in their own packages"). This module carries the package's
+ * own AWS service clients (built over core's shared SigV4 transport through
+ * the plugin-supplied `ServiceDescriptor` seam) and, since task 47, the
+ * `Plugin` default export the CLI's discovery loads.
+ *
+ * The default export and the package's `blogwright.plugin` manifest field
+ * landed together, deliberately: a package carrying the manifest without a
+ * conforming default export is a discovery error naming this package, so
+ * neither half may ship ahead of the other.
+ */
+/**
+ * The plugin's own four AWS service clients and the shapes they return. They
+ * live here rather than in `blogwright-core` because core enumerates no
+ * `firehose`, `glue`, `lambda` or `s3tables` signing name: each signs through
+ * the plugin-supplied `ServiceDescriptor` seam over the host's us-east-1
+ * signer. Each module carries the client's own documentation.
+ */
+export * from './aws/firehose.js';
+export * from './aws/glue.js';
+export * from './aws/lambda.js';
+export * from './aws/s3tables.js';
+/**
+ * The `Plugin` object the CLI discovers, and the namespace constant its
+ * `name` is built from. Both live in `plugin.ts`; `ANALYTICS_NAMESPACE`
+ * moved there from this module when the default export arrived to consume
+ * it, so the namespace has one home rather than a constant here and a
+ * literal there. Its conformance to core's `PLUGIN_NAME_PATTERN` is pinned
+ * by `index.test.ts` and again, through `validatePlugin`, by `plugin.test.ts`.
+ */
+export { default, ANALYTICS_NAMESPACE } from './plugin.js';

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * Public surface of blogwright-analytics: CloudFront access logs routed
+ * through Firehose into an Iceberg table, with a local dashboard over it.
+ * The plugin is installed on demand with `blogwright plugin add analytics`,
+ * never shipped with the CLI - see DEVELOPMENT.md §Hexagonal architecture
+ * ("Features live in their own packages"). This module carries the package's
+ * own AWS service clients (built over core's shared SigV4 transport through
+ * the plugin-supplied `ServiceDescriptor` seam) and, since task 47, the
+ * `Plugin` default export the CLI's discovery loads.
+ *
+ * The default export and the package's `blogwright.plugin` manifest field
+ * landed together, deliberately: a package carrying the manifest without a
+ * conforming default export is a discovery error naming this package, so
+ * neither half may ship ahead of the other.
+ */
+/**
+ * The plugin's own four AWS service clients and the shapes they return. They
+ * live here rather than in `blogwright-core` because core enumerates no
+ * `firehose`, `glue`, `lambda` or `s3tables` signing name: each signs through
+ * the plugin-supplied `ServiceDescriptor` seam over the host's us-east-1
+ * signer. Each module carries the client's own documentation.
+ */
+export * from './aws/firehose.js';
+export * from './aws/glue.js';
+export * from './aws/lambda.js';
+export * from './aws/s3tables.js';
+/**
+ * The `Plugin` object the CLI discovers, and the namespace constant its
+ * `name` is built from. Both live in `plugin.ts`; `ANALYTICS_NAMESPACE`
+ * moved there from this module when the default export arrived to consume
+ * it, so the namespace has one home rather than a constant here and a
+ * literal there. Its conformance to core's `PLUGIN_NAME_PATTERN` is pinned
+ * by `index.test.ts` and again, through `validatePlugin`, by `plugin.test.ts`.
+ */
+export { default, ANALYTICS_NAMESPACE } from './plugin.js';