blogwright-analytics 0.3.3

package/dist/commands.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The bodies behind the three actions `plugin.ts` declares, and **the
+ * plugin's composition root**. The command TABLE is written once, in
+ * `plugin.ts`, and no later task edits it; each action's behaviour lands here
+ * instead - `status` and `dashboard` below in full, and `backfill` as the
+ * three lines that construct its two adapters, its logic living in
+ * `backfill.ts`. All three are dispatchable from the moment the manifest field
+ * makes this package discoverable.
+ *
+ * A body takes exactly the parameters it needs. `PluginCommand.run(ctx, args)`
+ * accepts a narrower function - a zero-argument function is assignable to it,
+ * and so is one taking a `Pick` of `PluginContext` - so filling a body in
+ * never changes the table in `plugin.ts`.
+ *
+ * **Composition root** means one thing concretely: this is the only module in
+ * the package that constructs a DuckDB adapter and the only one that resolves
+ * credentials, exactly as `packages/cli/src/context.ts` is for the CLI's own
+ * adapters. Every module below it - the server, the named query set, the data
+ * shaping, the backfill - is handed a *port* and can name no vendor at all.
+ * All three commands that reach the table construct their adapters on their
+ * own line here: `dashboard` hands one to the server it starts, and `status`
+ * and `backfill` take theirs as defaulted parameters, which is what lets a
+ * test drive the whole command over a fake without patching a module.
+ *
+ * `backfill` is the only one that constructs two of them, and they are not
+ * interchangeable: its occupancy count crosses `AnalyticsQuery`, whose attach
+ * is read-only, and its insert crosses `AnalyticsIngest`, whose attach is not.
+ * One writable session answering both would be shorter and would put the
+ * dashboard's own read path one refactor away from a connection that can
+ * write.
+ *
+ * `bootstrap` and `destroy` are deliberately absent from this module as well
+ * as from the table: they are always the CLI's generic lifecycle verbs, run
+ * by an engine a plugin may not import - see `plugin.ts`'s own comment.
+ */
+import { type PluginContext } from 'blogwright-core';
+import { type BackfillPorts } from './backfill.js';
+import { type AnalyticsConfig } from './config.js';
+import type { AnalyticsQuery } from './ports.js';
+/**
+ * `analytics status`: the plugin's own nodes read against
+ * `state/<env>.analytics.json`, plus the Firehose stream's delivery health
+ * and the table's current row count. Declared rather than left to the
+ * generic `status` verb because it does strictly more than that verb does
+ * (§Analytics plugin → Namespace and commands), which task 16's precedence
+ * permits: only `bootstrap` and `destroy` are reserved.
+ *
+ * **It takes the whole `PluginContext`, not a `Pick` of it.** Every other
+ * consumer in this package narrows (`DashboardCommandContext`,
+ * `DuckDbSessionContext`, `AnalyticsConfigContext`), and this one cannot: it
+ * hands `ctx` to `read()` on each of the plugin's own nodes, and a node is a
+ * `ResourceNode<PluginContext<AnalyticsConfig>>`, so the narrowest type that
+ * type-checks is the SPI context entire. A `Pick` listing its fifteen required members
+ * would be that type with a second name.
+ *
+ * `args` is accepted and unused: the host calls `run(ctx, args)` for every
+ * declared command, and this one takes no arguments of its own - the
+ * environment is a positional the dispatcher has already consumed, and
+ * `--plain` reaches this command as `ctx.ports.terminal.isInteractive` rather
+ * than as a flag to parse.
+ *
+ * `query` is a defaulted parameter for the reason the site's own
+ * `status(ctx, nodes = buildNodes(ctx))` takes its node set that way: every
+ * real call site passes nothing and gets the composition root's adapter, and a
+ * test hands it the fixture-backed fake instead of patching a module. The
+ * default constructs the adapter but does not connect - the connection and the
+ * credentials are resolved inside the first query - so a status that never
+ * reaches the table starts nothing.
+ */
+export declare function status(ctx: PluginContext<AnalyticsConfig>, _args?: string[], query?: AnalyticsQuery): Promise<void>;
+/**
+ * The slice of a plugin context {@link dashboard} reads, taken as a `Pick` of
+ * core's own `PluginContext` rather than a restatement of it, the way
+ * `DuckDbSessionContext` and `AnalyticsConfigContext` already are: the members
+ * cannot drift from the SPI, any `PluginContext<AnalyticsConfig>` satisfies
+ * it, and a test builds the six it needs instead of the SPI's sixteen.
+ */
+export type DashboardCommandContext = Pick<PluginContext<AnalyticsConfig>, 'env' | 'config' | 'pluginConfig' | 'accountId' | 'ports' | 'logger'>;
+/**
+ * `analytics dashboard`: serve the local dashboard over the Iceberg table,
+ * bound to `127.0.0.1` on the resolved `dashboard.port`.
+ *
+ * This is the composition root the module comment describes, and the three
+ * lines that make it one are the adapter construction, the credential
+ * resolution and the `appDir`. **Credentials are core's own provider chain**
+ * (`createCredentialProvider`, `packages/core/src/aws/credentials.ts`),
+ * resolved here and handed to the adapter, which is the spec's §Analytics
+ * dashboard → Credentials: one credential source serves the whole CLI, so a
+ * session that works for `deploy` works for the dashboard. It is built with no
+ * `override`, matching `transform/entry.ts`: that flag substitutes an
+ * emulator's dummy `test`/`test` pair when a real chain fails, and the
+ * dashboard has no emulator to talk to - the adapter attaches a real S3 Tables
+ * ARN with no endpoint override at all, so dummy credentials would turn "you
+ * are not logged in" into an opaque authorisation failure from AWS.
+ *
+ * Constructing the adapter touches neither the network nor the native library
+ * - it opens its connection lazily on the first query - so the listener is
+ * bound and the URL is printed before AWS is ever consulted.
+ *
+ * The `finally` is the shutdown path, and it covers both ways out: the signal
+ * {@link untilStopped} waits for, and a failure raised while waiting. Either
+ * way `close()` is awaited, so the port is released before this function
+ * returns and the next `analytics dashboard` binds it again.
+ */
+export declare function dashboard(ctx: DashboardCommandContext): Promise<void>;
+/**
+ * `analytics backfill`: the optional, one-shot, idempotent pull of history
+ * that predates the Firehose delivery, from the site's CloudWatch log group
+ * into the table. Never part of the steady-state pipeline. What it does is
+ * `backfill.ts`'s; what this line owns is the two adapters it does it through.
+ *
+ * `ports` is a defaulted parameter for the reason `status`'s `query` is: every
+ * real call site passes nothing and gets the composition root's adapters, and
+ * a test hands it a recording pair instead of patching a module. Constructing
+ * either adapter touches neither the network nor the native library - both
+ * open their connection inside the first statement - so the command's refusal
+ * when the plugin's state carries no delivery bound still happens before
+ * anything is opened.
+ *
+ * `args` is accepted and unused: the host calls `run(ctx, args)` for every
+ * declared command and this one takes no arguments of its own - the
+ * environment is a positional the dispatcher has already consumed.
+ */
+export declare function backfill(ctx: PluginContext<AnalyticsConfig>, _args?: string[], ports?: BackfillPorts): Promise<void>;

package/dist/commands.js

@@ -0,0 +1,336 @@
+/**
+ * The bodies behind the three actions `plugin.ts` declares, and **the
+ * plugin's composition root**. The command TABLE is written once, in
+ * `plugin.ts`, and no later task edits it; each action's behaviour lands here
+ * instead - `status` and `dashboard` below in full, and `backfill` as the
+ * three lines that construct its two adapters, its logic living in
+ * `backfill.ts`. All three are dispatchable from the moment the manifest field
+ * makes this package discoverable.
+ *
+ * A body takes exactly the parameters it needs. `PluginCommand.run(ctx, args)`
+ * accepts a narrower function - a zero-argument function is assignable to it,
+ * and so is one taking a `Pick` of `PluginContext` - so filling a body in
+ * never changes the table in `plugin.ts`.
+ *
+ * **Composition root** means one thing concretely: this is the only module in
+ * the package that constructs a DuckDB adapter and the only one that resolves
+ * credentials, exactly as `packages/cli/src/context.ts` is for the CLI's own
+ * adapters. Every module below it - the server, the named query set, the data
+ * shaping, the backfill - is handed a *port* and can name no vendor at all.
+ * All three commands that reach the table construct their adapters on their
+ * own line here: `dashboard` hands one to the server it starts, and `status`
+ * and `backfill` take theirs as defaulted parameters, which is what lets a
+ * test drive the whole command over a fake without patching a module.
+ *
+ * `backfill` is the only one that constructs two of them, and they are not
+ * interchangeable: its occupancy count crosses `AnalyticsQuery`, whose attach
+ * is read-only, and its insert crosses `AnalyticsIngest`, whose attach is not.
+ * One writable session answering both would be shorter and would put the
+ * dashboard's own read path one refactor away from a connection that can
+ * write.
+ *
+ * `bootstrap` and `destroy` are deliberately absent from this module as well
+ * as from the table: they are always the CLI's generic lifecycle verbs, run
+ * by an engine a plugin may not import - see `plugin.ts`'s own comment.
+ */
+import { fileURLToPath } from 'node:url';
+import { colors, createCredentialProvider } from 'blogwright-core';
+import { createDuckDbAnalyticsIngest } from './adapters/duckdb-ingest.js';
+import { createDuckDbAnalyticsQuery } from './adapters/duckdb-query.js';
+import { runBackfill } from './backfill.js';
+import { resolveAnalyticsConfig } from './config.js';
+import { buildAnalyticsNodes, FIREHOSE_STREAM_NODE } from './nodes.js';
+import { ROW_COUNT_COLUMN, ROW_COUNT_QUERY, WHOLE_TABLE_RANGE } from './queries.js';
+import { createDashboardServer } from './server.js';
+/**
+ * The signals that stop a foreground command. `SIGTERM` joins `SIGINT`
+ * because a dashboard is as likely to be stopped by a supervisor or a
+ * container runtime as by an operator's Ctrl+C, and both must release the
+ * listener rather than leave the port held by a half-dead process.
+ */
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM'];
+/** The tree glyphs the pretty form marks each state with - the CLI's own. */
+const STATUS_MARKS = {
+    present: colors.green('✓'),
+    missing: colors.yellow('◌'),
+    error: colors.red('✗'),
+};
+/**
+ * The one {@link DeliveryState} that means records are reaching the table.
+ * Typed against the client's own union rather than spelled as a bare string,
+ * so renaming a state there is a compile error here instead of a status line
+ * that silently never reports healthy again.
+ */
+const HEALTHY_DELIVERY_STATE = 'active';
+/**
+ * Read every node the plugin contributes against the live account, in the
+ * order {@link buildAnalyticsNodes} returns them (no topological sort - a
+ * status is a read, not a reconcile).
+ *
+ * A `read()` that throws becomes an `error` entry rather than ending the
+ * listing: one unreadable item must not take down the whole listing, which is
+ * `history`'s manifest loop in `packages/cli/src/commands.ts` and, for exactly
+ * this shape, the CLI's own `readNodeStatus`. Nothing is saved - `read()`
+ * hydrates `ctx.state` in memory and this command never calls `ctx.save()`, so
+ * a status can neither create nor rewrite `state/<env>.analytics.json`.
+ */
+async function readNodeEntries(ctx) {
+    const entries = [];
+    for (const node of buildAnalyticsNodes()) {
+        try {
+            const exists = await node.read(ctx);
+            entries.push({ id: node.id, title: node.title, state: exists ? 'present' : 'missing' });
+        }
+        catch (err) {
+            entries.push({
+                id: node.id,
+                title: node.title,
+                state: 'error',
+                detail: err.message,
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * Report the node listing: the drift tree on an interactive terminal, one
+ * stable line per node otherwise. The same split, the same marks and the same
+ * `read failed` wording as the site's own `status`
+ * (`packages/cli/src/commands.ts`, through `logStatusEntries` in its
+ * `render.ts`), restated here because a plugin may not import that module.
+ *
+ * One deliberate difference in the plain form: the CLI appends
+ * `JSON.stringify` of the node's recorded outputs to each line. This command
+ * does not. The plain form is the contract CI and agents read, and a line
+ * carrying an ARN carries the account id, the environment and a
+ * service-generated table id with it - so the "same" line would differ between
+ * two environments of the same site and could never be asserted as a contract.
+ * What the outputs say is in `state/<env>.analytics.json`, and the two lines
+ * this command adds after the listing are what a reader wants them for.
+ */
+function logNodeEntries(entries, pretty, logger) {
+    if (pretty) {
+        entries.forEach((entry, index) => {
+            const connector = index === entries.length - 1 ? '╰─' : '├─';
+            const detail = entry.detail === undefined ? '' : ` ${colors.dim(entry.detail)}`;
+            logger.info(`${connector} ${STATUS_MARKS[entry.state]} ${entry.title}${detail}`);
+        });
+        return;
+    }
+    // The plain form is the stable contract for CI logs and agents.
+    for (const entry of entries) {
+        if (entry.state === 'error') {
+            logger.warn(`${entry.title}: read failed (${entry.detail})`);
+            continue;
+        }
+        const mark = entry.state === 'present' ? colors.green('present') : colors.yellow('missing');
+        logger.info(`  ${mark}  ${entry.title}`);
+    }
+}
+/**
+ * Report the delivery stream's health from the state its own `read` hydrated a
+ * moment ago (task 51's `recordStream` puts the stream's `state` and, when the
+ * service reports one, its `failure` into the plugin's scoped state). No
+ * second describe is issued: the node has just made that call, and a status
+ * that made it twice would report two different answers on a stream that
+ * changed in between.
+ *
+ * A stream that is absent is reported as a warning rather than as health, and
+ * that choice is worth stating because the definition of done does not pin it:
+ * "no stream" and "a stream in `create-failed`" are the same operational fact
+ * - nothing is being delivered - and the listing above already says which node
+ * is missing, so a health line that stayed silent would read as healthy.
+ */
+function logStreamHealth(ctx, entries) {
+    const entry = entries.find((candidate) => candidate.id === FIREHOSE_STREAM_NODE);
+    if (entry?.state === 'error') {
+        ctx.logger.warn(`Firehose delivery: unavailable - reading the stream failed (${entry.detail})`);
+        return;
+    }
+    if (entry?.state !== 'present') {
+        ctx.logger.warn(`Firehose delivery: no delivery stream - \`blogwright analytics bootstrap ${ctx.env}\` creates it`);
+        return;
+    }
+    const recorded = ctx.state.resources[FIREHOSE_STREAM_NODE];
+    const state = typeof recorded?.['state'] === 'string' ? recorded['state'] : 'unrecorded';
+    const failure = typeof recorded?.['failure'] === 'string' ? ` - ${recorded['failure']}` : '';
+    if (state === HEALTHY_DELIVERY_STATE) {
+        ctx.logger.info(`  Firehose delivery: ${state}`);
+        return;
+    }
+    ctx.logger.warn(`Firehose delivery: ${state}${failure}`);
+}
+/**
+ * Report the table's current row count, taken through the `AnalyticsQuery`
+ * port by name. The command writes no SQL: `ROW_COUNT_QUERY` names one of the
+ * definitions in `queries.ts`, and {@link WHOLE_TABLE_RANGE} is what "current
+ * row count" means for a set whose every definition is bounded on the `day`
+ * partition. `includeBots` is bound explicitly rather than left to
+ * `config.analytics.bots`, because this is the table's row count and not a
+ * dashboard figure - a bot row is still a row.
+ *
+ * A failed read degrades to a warning, which is the whole point of doing it
+ * last: the table is the one part of this listing that needs credentials the
+ * node reads do not (the vendor library attaches the catalog itself), so an
+ * operator with no session still gets all twelve nodes and the stream's health.
+ */
+async function logRowCount(ctx, query) {
+    const config = resolveAnalyticsConfig(ctx);
+    const relation = `${config.namespace}.${config.table}`;
+    try {
+        const rows = await query.run(ROW_COUNT_QUERY, {
+            range: WHOLE_TABLE_RANGE,
+            includeBots: true,
+        });
+        const count = rows[0]?.[ROW_COUNT_COLUMN];
+        if (typeof count !== 'number') {
+            throw new Error(`the ${ROW_COUNT_QUERY} query answered no ${ROW_COUNT_COLUMN}`);
+        }
+        ctx.logger.info(`  rows in ${relation}: ${count}`);
+    }
+    catch (err) {
+        ctx.logger.warn(`rows in ${relation}: unavailable - ${err.message}`);
+    }
+}
+/**
+ * `analytics status`: the plugin's own nodes read against
+ * `state/<env>.analytics.json`, plus the Firehose stream's delivery health
+ * and the table's current row count. Declared rather than left to the
+ * generic `status` verb because it does strictly more than that verb does
+ * (§Analytics plugin → Namespace and commands), which task 16's precedence
+ * permits: only `bootstrap` and `destroy` are reserved.
+ *
+ * **It takes the whole `PluginContext`, not a `Pick` of it.** Every other
+ * consumer in this package narrows (`DashboardCommandContext`,
+ * `DuckDbSessionContext`, `AnalyticsConfigContext`), and this one cannot: it
+ * hands `ctx` to `read()` on each of the plugin's own nodes, and a node is a
+ * `ResourceNode<PluginContext<AnalyticsConfig>>`, so the narrowest type that
+ * type-checks is the SPI context entire. A `Pick` listing its fifteen required members
+ * would be that type with a second name.
+ *
+ * `args` is accepted and unused: the host calls `run(ctx, args)` for every
+ * declared command, and this one takes no arguments of its own - the
+ * environment is a positional the dispatcher has already consumed, and
+ * `--plain` reaches this command as `ctx.ports.terminal.isInteractive` rather
+ * than as a flag to parse.
+ *
+ * `query` is a defaulted parameter for the reason the site's own
+ * `status(ctx, nodes = buildNodes(ctx))` takes its node set that way: every
+ * real call site passes nothing and gets the composition root's adapter, and a
+ * test hands it the fixture-backed fake instead of patching a module. The
+ * default constructs the adapter but does not connect - the connection and the
+ * credentials are resolved inside the first query - so a status that never
+ * reaches the table starts nothing.
+ */
+export async function status(ctx, _args = [], query = createDuckDbAnalyticsQuery({
+    ctx,
+    credentials: createCredentialProvider({}),
+})) {
+    ctx.logger.info(colors.bold(`Analytics status for "${ctx.env}" (bucket ${ctx.names.bucket})`));
+    const entries = await readNodeEntries(ctx);
+    logNodeEntries(entries, ctx.ports.terminal.isInteractive, ctx.logger);
+    logStreamHealth(ctx, entries);
+    await logRowCount(ctx, query);
+}
+/**
+ * The prebuilt dashboard application task 57 emits, beside this module's own
+ * compiled output (`dist/commands.js` → `dist/app`). Located from
+ * `import.meta.url` for the reason `cliPackageDir` (`packages/cli/src/context.ts`)
+ * is: a package's own files are not reachable through its `exports` map, so
+ * self-location is a composition-root concern and not something the server -
+ * which is handed the resolved directory as data - can derive. Under the test
+ * runner it resolves beside the sources instead, where no application is
+ * built, and the server answers a 503 naming the directory.
+ */
+function dashboardAppDir() {
+    return fileURLToPath(new URL('app', import.meta.url));
+}
+/**
+ * Resolve once a stop signal arrives, un-registering both listeners first so
+ * a finished command leaves the process exactly as it found it. Resolves with
+ * the signal, so the line the operator sees says which one stopped it.
+ */
+function untilStopped() {
+    return new Promise((resolve) => {
+        const listeners = new Map();
+        const stop = (signal) => {
+            for (const [name, listener] of listeners)
+                process.off(name, listener);
+            resolve(signal);
+        };
+        for (const signal of STOP_SIGNALS) {
+            const listener = () => stop(signal);
+            listeners.set(signal, listener);
+            process.on(signal, listener);
+        }
+    });
+}
+/**
+ * `analytics dashboard`: serve the local dashboard over the Iceberg table,
+ * bound to `127.0.0.1` on the resolved `dashboard.port`.
+ *
+ * This is the composition root the module comment describes, and the three
+ * lines that make it one are the adapter construction, the credential
+ * resolution and the `appDir`. **Credentials are core's own provider chain**
+ * (`createCredentialProvider`, `packages/core/src/aws/credentials.ts`),
+ * resolved here and handed to the adapter, which is the spec's §Analytics
+ * dashboard → Credentials: one credential source serves the whole CLI, so a
+ * session that works for `deploy` works for the dashboard. It is built with no
+ * `override`, matching `transform/entry.ts`: that flag substitutes an
+ * emulator's dummy `test`/`test` pair when a real chain fails, and the
+ * dashboard has no emulator to talk to - the adapter attaches a real S3 Tables
+ * ARN with no endpoint override at all, so dummy credentials would turn "you
+ * are not logged in" into an opaque authorisation failure from AWS.
+ *
+ * Constructing the adapter touches neither the network nor the native library
+ * - it opens its connection lazily on the first query - so the listener is
+ * bound and the URL is printed before AWS is ever consulted.
+ *
+ * The `finally` is the shutdown path, and it covers both ways out: the signal
+ * {@link untilStopped} waits for, and a failure raised while waiting. Either
+ * way `close()` is awaited, so the port is released before this function
+ * returns and the next `analytics dashboard` binds it again.
+ */
+export async function dashboard(ctx) {
+    const config = resolveAnalyticsConfig(ctx);
+    const server = await createDashboardServer({
+        query: createDuckDbAnalyticsQuery({ ctx, credentials: createCredentialProvider({}) }),
+        config: ctx.pluginConfig,
+        port: config.dashboard.port,
+        appDir: dashboardAppDir(),
+        fs: ctx.ports.fs,
+    });
+    ctx.logger.info(`analytics dashboard on ${server.url} - press Ctrl+C to stop`);
+    try {
+        const signal = await untilStopped();
+        ctx.logger.info(`${signal} received - stopping the analytics dashboard`);
+    }
+    finally {
+        await server.close();
+        ctx.logger.ok(`analytics dashboard stopped; port ${server.address.port} released`);
+    }
+}
+/**
+ * `analytics backfill`: the optional, one-shot, idempotent pull of history
+ * that predates the Firehose delivery, from the site's CloudWatch log group
+ * into the table. Never part of the steady-state pipeline. What it does is
+ * `backfill.ts`'s; what this line owns is the two adapters it does it through.
+ *
+ * `ports` is a defaulted parameter for the reason `status`'s `query` is: every
+ * real call site passes nothing and gets the composition root's adapters, and
+ * a test hands it a recording pair instead of patching a module. Constructing
+ * either adapter touches neither the network nor the native library - both
+ * open their connection inside the first statement - so the command's refusal
+ * when the plugin's state carries no delivery bound still happens before
+ * anything is opened.
+ *
+ * `args` is accepted and unused: the host calls `run(ctx, args)` for every
+ * declared command and this one takes no arguments of its own - the
+ * environment is a positional the dispatcher has already consumed.
+ */
+export async function backfill(ctx, _args = [], ports = {
+    query: createDuckDbAnalyticsQuery({ ctx, credentials: createCredentialProvider({}) }),
+    ingest: createDuckDbAnalyticsIngest({ ctx, credentials: createCredentialProvider({}) }),
+}) {
+    await runBackfill(ctx, ports);
+}

package/dist/config.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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).
+ */
+import type { PluginContext } from 'blogwright-core';
+/**
+ * Whether bot traffic is excluded from dashboard queries. Records are stored
+ * either way. Not exported: no consumer needs the bare union today - one can
+ * reach the same type as `AnalyticsConfig['bots']`. Export it once a real
+ * consumer needs the union by name.
+ */
+type BotHandling = 'flag' | 'filter';
+/**
+ * The settings whose defaults are plain literals - the ones needing no
+ * environment to resolve, and so total on both the validated block and the
+ * resolved config.
+ */
+interface EnvIndependentSettings {
+    /** Iceberg namespace holding the table. */
+    namespace: string;
+    /** Iceberg table name. */
+    table: string;
+    /** Bot handling for dashboard queries. */
+    bots: BotHandling;
+    /** Local dashboard settings. */
+    dashboard: {
+        port: number;
+    };
+}
+/**
+ * The two settings whose defaults carry the environment. Never readable off a
+ * validated block - see {@link ENV_DERIVED}.
+ */
+interface EnvDerivedOverrides {
+    tableBucket?: string | undefined;
+    saltSecretName?: string | undefined;
+}
+/**
+ * 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.
+ */
+declare const ENV_DERIVED: unique symbol;
+/**
+ * A validated `analytics` block: what {@link validateAnalyticsConfig} returns,
+ * and therefore what the host puts on `ctx.pluginConfig` for this plugin. The
+ * four settings whose defaults are literals are already applied and total; the
+ * two that need the environment are sealed under {@link ENV_DERIVED} and reach
+ * a reader only through {@link resolveAnalyticsConfig}.
+ */
+export interface AnalyticsConfig extends EnvIndependentSettings {
+    readonly [ENV_DERIVED]: EnvDerivedOverrides;
+}
+/**
+ * An `analytics` block with every default applied, the environment-carrying
+ * ones included: the shape every reader downstream keeps a total type on, so
+ * no call site re-applies a default or re-checks for `undefined`.
+ */
+export interface ResolvedAnalyticsConfig extends EnvIndependentSettings {
+    tableBucket: string;
+    saltSecretName: string;
+}
+/**
+ * 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 declare const DEFAULT_DASHBOARD_PORT = 4317;
+/**
+ * The slice of a plugin context {@link resolveAnalyticsConfig} reads, taken as
+ * a `Pick` of core's own `PluginContext` rather than a restatement of it, so
+ * the three members cannot drift from the SPI. Any
+ * `PluginContext<AnalyticsConfig>` satisfies it, so a node passes `ctx`
+ * straight through. Not exported: a caller passes its context and never names
+ * this type.
+ */
+type AnalyticsConfigContext = Pick<PluginContext<AnalyticsConfig>, 'env' | 'config' | 'pluginConfig'>;
+/**
+ * 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 declare function validateAnalyticsConfig(raw: unknown): AnalyticsConfig;
+/**
+ * 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 declare function resolveAnalyticsConfig(ctx: AnalyticsConfigContext): ResolvedAnalyticsConfig;
+export {};