blogwright-analytics 0.3.3

package/dist/paths.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The plugin's composition root for *paths*: the one module in
+ * `packages/analytics/src/` permitted to touch `import.meta.url`.
+ *
+ * `analytics-transform-function` (`nodes.ts`) deploys an artifact this package
+ * ships inside itself - the rolldown bundle and the manifest stamped beside it
+ * under `transform-hash.ts`'s `TRANSFORM_BUNDLE_DIR` - so something has to know where the
+ * installed package is on disk. The CLI answers the identical question for the
+ * build-agent at `packages/cli/src/context.ts` (`cliPackageDir()`, joined to
+ * `agent` and put on the context as `agentDir`), and the rule that keeps that
+ * honest is DEVELOPMENT.md §Hexagonal architecture: a location is resolved at
+ * a composition root and handed to domain code as *data*.
+ *
+ * `nodes.ts` has no wiring step of its own to resolve it in - the SPI reaches
+ * it through `plugin.nodes(ctx)` with nothing in between - so this module is
+ * that step. Resolving it inline in `nodes.ts` would satisfy the package's ban
+ * on Node's own filesystem module (`import.meta.url` is not a restricted
+ * import) while breaking the composition-root rule anyway, and it would put a
+ * second `import.meta.url` in the package the day a second artifact needs
+ * locating.
+ *
+ * This module resolves a directory and nothing else. The *bytes* under it are
+ * still read through `ctx.ports.fs`, never here: this package imports Node's
+ * filesystem module nowhere at all, and no `packages/analytics/src/` path joins
+ * the `no-restricted-imports` override list in `.oxlintrc.json`. (Named in
+ * prose rather than spelled as the specifier, so the definition of done's grep
+ * for it over this tree does not trip over a comment - the same care
+ * `ports.ts` takes with its own vendor name.)
+ */
+/**
+ * The `blogwright-analytics` package root, resolved from this module's own
+ * location - `<package>/dist/paths.js` once compiled, `<package>/src/paths.ts`
+ * under vitest, and one level up from either.
+ *
+ * `resolve` is here for the reason `cliPackageDir()` states: `new URL('..', …)`
+ * yields a trailing separator, unlike every other directory value in the repo,
+ * so a caller writing `${ANALYTICS_PACKAGE_DIR}/x` would get a doubled one - in
+ * the path and in any error message built from it.
+ *
+ * The relative location of the transform artifacts under this directory is not
+ * restated here: `transform-hash.ts` owns `TRANSFORM_BUNDLE_DIR` as "where
+ * the build puts the Lambda artifacts, relative to the package root", and
+ * `nodes.ts` joins the two.
+ */
+export declare const ANALYTICS_PACKAGE_DIR: string;

package/dist/paths.js

@@ -0,0 +1,47 @@
+/**
+ * The plugin's composition root for *paths*: the one module in
+ * `packages/analytics/src/` permitted to touch `import.meta.url`.
+ *
+ * `analytics-transform-function` (`nodes.ts`) deploys an artifact this package
+ * ships inside itself - the rolldown bundle and the manifest stamped beside it
+ * under `transform-hash.ts`'s `TRANSFORM_BUNDLE_DIR` - so something has to know where the
+ * installed package is on disk. The CLI answers the identical question for the
+ * build-agent at `packages/cli/src/context.ts` (`cliPackageDir()`, joined to
+ * `agent` and put on the context as `agentDir`), and the rule that keeps that
+ * honest is DEVELOPMENT.md §Hexagonal architecture: a location is resolved at
+ * a composition root and handed to domain code as *data*.
+ *
+ * `nodes.ts` has no wiring step of its own to resolve it in - the SPI reaches
+ * it through `plugin.nodes(ctx)` with nothing in between - so this module is
+ * that step. Resolving it inline in `nodes.ts` would satisfy the package's ban
+ * on Node's own filesystem module (`import.meta.url` is not a restricted
+ * import) while breaking the composition-root rule anyway, and it would put a
+ * second `import.meta.url` in the package the day a second artifact needs
+ * locating.
+ *
+ * This module resolves a directory and nothing else. The *bytes* under it are
+ * still read through `ctx.ports.fs`, never here: this package imports Node's
+ * filesystem module nowhere at all, and no `packages/analytics/src/` path joins
+ * the `no-restricted-imports` override list in `.oxlintrc.json`. (Named in
+ * prose rather than spelled as the specifier, so the definition of done's grep
+ * for it over this tree does not trip over a comment - the same care
+ * `ports.ts` takes with its own vendor name.)
+ */
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The `blogwright-analytics` package root, resolved from this module's own
+ * location - `<package>/dist/paths.js` once compiled, `<package>/src/paths.ts`
+ * under vitest, and one level up from either.
+ *
+ * `resolve` is here for the reason `cliPackageDir()` states: `new URL('..', …)`
+ * yields a trailing separator, unlike every other directory value in the repo,
+ * so a caller writing `${ANALYTICS_PACKAGE_DIR}/x` would get a doubled one - in
+ * the path and in any error message built from it.
+ *
+ * The relative location of the transform artifacts under this directory is not
+ * restated here: `transform-hash.ts` owns `TRANSFORM_BUNDLE_DIR` as "where
+ * the build puts the Lambda artifacts, relative to the package root", and
+ * `nodes.ts` joins the two.
+ */
+export const ANALYTICS_PACKAGE_DIR = resolve(fileURLToPath(new URL('..', import.meta.url)));

package/dist/plugin.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The package's `Plugin` default export: the object the CLI's discovery
+ * loads once `package.json`'s `{ "blogwright": { "plugin": "analytics" } }`
+ * manifest field marks this package as a plugin. Everything the host learns
+ * about this plugin - its namespace, its help text, the config key it owns,
+ * its validator, its actions and its `init` contributor - it learns from
+ * here.
+ *
+ * **The command table, and what is deliberately missing from it.** Task 16's
+ * precedence rules (`packages/cli/src/plugin-commands.ts`, its TASK 13 and
+ * TASK 16 PRECEDENCE sections) decide which verbs a plugin may declare:
+ *
+ *   - `bootstrap` and `destroy` are ALWAYS the CLI's generic verbs. They run
+ *     `applyGraph`/`destroyGraph` over `nodes(ctx)`, and a plugin may not
+ *     import the CLI, so a plugin cannot run that engine itself. Declaring
+ *     either is not merely redundant, it is rejected at discovery -
+ *     `rejectDeclaredLifecycleCollisions` (`packages/cli/src/plugins.ts`)
+ *     turns the whole package into a load failure naming the colliding
+ *     action. They are absent here for that reason, not for tidiness.
+ *   - `status` is the generic verb UNLESS the plugin declares its own, and
+ *     this one does: `analytics status` reports strictly more than the
+ *     generic verb can - the stream's delivery health and the table's
+ *     current row count on top of the node listing - and needs no engine
+ *     call to do it, because `read()` lives on the plugin's own nodes.
+ *   - `init` is ABSENT from the table on purpose, and this is the trap
+ *     worth stating plainly: a declared command takes precedence over the
+ *     generic action, so an `init` entry here would shadow the generic
+ *     config-block splice. `blogwright analytics init` would then ask the
+ *     operator every question below and write nothing at all. The `init`
+ *     contributor ({@link Plugin.init}) is the ONLY way this plugin supplies
+ *     `init`. (pds is the opposite case: it declares a real `init` command
+ *     that creates the publication record and writes no config block, which
+ *     precedence permits - a declared `init` owns the action, not an
+ *     obligation to write config.) Declaring both is itself a discovery
+ *     rejection, `rejectDeclaredInitCollisions` in the same collision pass.
+ *   - `backfill` is legal to declare precisely because only `bootstrap` and
+ *     `destroy` are reserved; it is the spec's optional, run-by-hand,
+ *     one-shot action.
+ *
+ * None of the three declared actions is destructive, so no summary here
+ * states `--yes`. The one destructive verb this namespace answers is
+ * `analytics destroy --yes`, which is generic: its refusal without `--yes`
+ * is `runGenericDestroy`'s, and its summary is the CLI's own.
+ *
+ * **`nodes` is declared, and declaring it is what turns the generic verbs
+ * on.** `genericLifecycleCommand` and `genericLifecycleActions`
+ * (`packages/cli/src/plugin-commands.ts`) both gate all three generic verbs
+ * on `plugin.nodes` being declared at all, so before task 54 wired
+ * {@link buildAnalyticsNodes} to it, `analytics bootstrap` and `analytics
+ * destroy` were neither answered nor advertised in `blogwright --help`.
+ * They are both now, and `analytics status` still runs the declared command
+ * above rather than the generic verb, because a declared action wins.
+ *
+ * The property `nodes` carries is not just "twelve nodes": it is that the
+ * CLI's engine reconciles them against the store `toPluginContext` scoped to
+ * this plugin's name, `state/<env>.analytics.json` - never the site's
+ * `state/<env>.json`. `blogwright bootstrap` therefore provisions none of
+ * these twelve (the site's `buildNodes` does not consult discovery), and
+ * `blogwright destroy --yes` removes none of them, because
+ * `assertNoScopedState` (`packages/cli/src/commands.ts`) refuses the site
+ * teardown for as long as that scoped object exists and names
+ * `blogwright analytics destroy <env> --yes` as the way through.
+ *
+ * The builder itself is passed by reference - `nodes: buildAnalyticsNodes`,
+ * no wrapper. The array is not shared: each call builds a fresh one. There is
+ * nothing for a wrapper to do either, because the set does not vary with
+ * the context, and re-ordering it here would only hide that the order the
+ * builder returns is already a topological one.
+ *
+ * **`validateConfig` is task 44's validator, bound - not wrapped.** The
+ * property below is `validateAnalyticsConfig` itself. That matters twice
+ * over. It is the function that applies the four literal defaults and stamps
+ * the module-private symbol `resolveAnalyticsConfig` unseals
+ * (`config.ts`'s `unsealEnvDerivedOverrides`), so any wrapper that reshaped
+ * or re-defaulted the block would produce one the resolver rejects at
+ * runtime. And the CLI calls it with `undefined` when the operator's config
+ * carries no `analytics` key at all (`resolvePluginConfig`,
+ * `packages/cli/src/plugins.ts`, over `pluginBlock`'s plain property read),
+ * so the plugin's own defaults - not a bare `{}` - are what such an operator
+ * gets; `validateAnalyticsConfig` treats an absent block as an empty one for
+ * exactly that reason. Passing the function by reference keeps both
+ * properties instead of restating them.
+ */
+import type { Plugin } from 'blogwright-core';
+import { type AnalyticsConfig } from './config.js';
+/**
+ * The CLI namespace this plugin claims (`blogwright analytics <action>`),
+ * and - deliberately the same string - the single top-level config key it
+ * owns (`config.analytics`), the way pds's namespace and key coincide too.
+ * Re-exported from `index.ts`, where it lived before the default export
+ * existed to consume it.
+ */
+export declare const ANALYTICS_NAMESPACE = "analytics";
+/**
+ * The plugin the CLI discovers. `Plugin<AnalyticsConfig>` names the block
+ * `validateConfig` returns, which is what the host puts on
+ * `ctx.pluginConfig` - the only route to this plugin's settings, and (for
+ * the two environment-carrying ones) only through
+ * `resolveAnalyticsConfig(ctx)`.
+ */
+declare const analyticsPlugin: Plugin<AnalyticsConfig>;
+export default analyticsPlugin;

package/dist/plugin.js

@@ -0,0 +1,248 @@
+/**
+ * The package's `Plugin` default export: the object the CLI's discovery
+ * loads once `package.json`'s `{ "blogwright": { "plugin": "analytics" } }`
+ * manifest field marks this package as a plugin. Everything the host learns
+ * about this plugin - its namespace, its help text, the config key it owns,
+ * its validator, its actions and its `init` contributor - it learns from
+ * here.
+ *
+ * **The command table, and what is deliberately missing from it.** Task 16's
+ * precedence rules (`packages/cli/src/plugin-commands.ts`, its TASK 13 and
+ * TASK 16 PRECEDENCE sections) decide which verbs a plugin may declare:
+ *
+ *   - `bootstrap` and `destroy` are ALWAYS the CLI's generic verbs. They run
+ *     `applyGraph`/`destroyGraph` over `nodes(ctx)`, and a plugin may not
+ *     import the CLI, so a plugin cannot run that engine itself. Declaring
+ *     either is not merely redundant, it is rejected at discovery -
+ *     `rejectDeclaredLifecycleCollisions` (`packages/cli/src/plugins.ts`)
+ *     turns the whole package into a load failure naming the colliding
+ *     action. They are absent here for that reason, not for tidiness.
+ *   - `status` is the generic verb UNLESS the plugin declares its own, and
+ *     this one does: `analytics status` reports strictly more than the
+ *     generic verb can - the stream's delivery health and the table's
+ *     current row count on top of the node listing - and needs no engine
+ *     call to do it, because `read()` lives on the plugin's own nodes.
+ *   - `init` is ABSENT from the table on purpose, and this is the trap
+ *     worth stating plainly: a declared command takes precedence over the
+ *     generic action, so an `init` entry here would shadow the generic
+ *     config-block splice. `blogwright analytics init` would then ask the
+ *     operator every question below and write nothing at all. The `init`
+ *     contributor ({@link Plugin.init}) is the ONLY way this plugin supplies
+ *     `init`. (pds is the opposite case: it declares a real `init` command
+ *     that creates the publication record and writes no config block, which
+ *     precedence permits - a declared `init` owns the action, not an
+ *     obligation to write config.) Declaring both is itself a discovery
+ *     rejection, `rejectDeclaredInitCollisions` in the same collision pass.
+ *   - `backfill` is legal to declare precisely because only `bootstrap` and
+ *     `destroy` are reserved; it is the spec's optional, run-by-hand,
+ *     one-shot action.
+ *
+ * None of the three declared actions is destructive, so no summary here
+ * states `--yes`. The one destructive verb this namespace answers is
+ * `analytics destroy --yes`, which is generic: its refusal without `--yes`
+ * is `runGenericDestroy`'s, and its summary is the CLI's own.
+ *
+ * **`nodes` is declared, and declaring it is what turns the generic verbs
+ * on.** `genericLifecycleCommand` and `genericLifecycleActions`
+ * (`packages/cli/src/plugin-commands.ts`) both gate all three generic verbs
+ * on `plugin.nodes` being declared at all, so before task 54 wired
+ * {@link buildAnalyticsNodes} to it, `analytics bootstrap` and `analytics
+ * destroy` were neither answered nor advertised in `blogwright --help`.
+ * They are both now, and `analytics status` still runs the declared command
+ * above rather than the generic verb, because a declared action wins.
+ *
+ * The property `nodes` carries is not just "twelve nodes": it is that the
+ * CLI's engine reconciles them against the store `toPluginContext` scoped to
+ * this plugin's name, `state/<env>.analytics.json` - never the site's
+ * `state/<env>.json`. `blogwright bootstrap` therefore provisions none of
+ * these twelve (the site's `buildNodes` does not consult discovery), and
+ * `blogwright destroy --yes` removes none of them, because
+ * `assertNoScopedState` (`packages/cli/src/commands.ts`) refuses the site
+ * teardown for as long as that scoped object exists and names
+ * `blogwright analytics destroy <env> --yes` as the way through.
+ *
+ * The builder itself is passed by reference - `nodes: buildAnalyticsNodes`,
+ * no wrapper. The array is not shared: each call builds a fresh one. There is
+ * nothing for a wrapper to do either, because the set does not vary with
+ * the context, and re-ordering it here would only hide that the order the
+ * builder returns is already a topological one.
+ *
+ * **`validateConfig` is task 44's validator, bound - not wrapped.** The
+ * property below is `validateAnalyticsConfig` itself. That matters twice
+ * over. It is the function that applies the four literal defaults and stamps
+ * the module-private symbol `resolveAnalyticsConfig` unseals
+ * (`config.ts`'s `unsealEnvDerivedOverrides`), so any wrapper that reshaped
+ * or re-defaulted the block would produce one the resolver rejects at
+ * runtime. And the CLI calls it with `undefined` when the operator's config
+ * carries no `analytics` key at all (`resolvePluginConfig`,
+ * `packages/cli/src/plugins.ts`, over `pluginBlock`'s plain property read),
+ * so the plugin's own defaults - not a bare `{}` - are what such an operator
+ * gets; `validateAnalyticsConfig` treats an absent block as an empty one for
+ * exactly that reason. Passing the function by reference keeps both
+ * properties instead of restating them.
+ */
+import { backfill, dashboard, status } from './commands.js';
+import { validateAnalyticsConfig } from './config.js';
+import { buildAnalyticsNodes } from './nodes.js';
+/**
+ * The CLI namespace this plugin claims (`blogwright analytics <action>`),
+ * and - deliberately the same string - the single top-level config key it
+ * owns (`config.analytics`), the way pds's namespace and key coincide too.
+ * Re-exported from `index.ts`, where it lived before the default export
+ * existed to consume it.
+ */
+export const ANALYTICS_NAMESPACE = 'analytics';
+/** The answers {@link isYes} accepts, matching `confirm`'s (`packages/cli/src/logger.ts`). */
+const YES_ANSWERS = new Set(['y', 'yes']);
+/** True when the operator agreed. Empty input never reaches here - `ask` substitutes the default first. */
+function isYes(answer) {
+    return YES_ANSWERS.has(answer.trim().toLowerCase());
+}
+/**
+ * Run `block` past {@link validateAnalyticsConfig} and return the message it
+ * raised, or `undefined` when it holds - the shape `PluginQuestion.validate`
+ * asks for. Every prompt below validates through this, so the wizard rejects
+ * exactly what the config validator rejects, with the validator's own
+ * message, and neither list of rules nor set of messages has a second home.
+ *
+ * These validators are also the only thing standing between a typed answer
+ * and the JSON text the entries below interpolate it into. An answer carrying
+ * a quote would close its own string and open a setting the wizard never
+ * asked about - `tableBucket` above all, the field task 44 sealed behind a
+ * module-private symbol precisely so that no code path can produce an
+ * env-less bucket name (`config.ts`, and what an env-less one destroys). Such
+ * a splice would survive the host's re-parse AND `validateAnalyticsConfig`,
+ * because the key it opens is a legitimate one; what refuses it is the
+ * `table` prompt's own rule, that an Iceberg identifier has no quote in it.
+ */
+function rejectionOf(block) {
+    try {
+        validateAnalyticsConfig(block);
+        return undefined;
+    }
+    catch (err) {
+        return err.message;
+    }
+}
+/**
+ * Validate a typed port answer. A non-numeric answer is handed to the
+ * validator as the string it is, so the rejection quotes what the operator
+ * typed rather than `NaN`.
+ */
+function portRejection(answer) {
+    const numeric = Number(answer);
+    return rejectionOf({ dashboard: { port: Number.isNaN(numeric) ? answer : numeric } });
+}
+/**
+ * Ask the operator for this plugin's config block and return it as the
+ * property/comment entries `renderConfigBlock` (`packages/cli/src/config-block.ts`)
+ * renders - the entry shape `renderConfig` (`packages/cli/src/init.ts`)
+ * mirrors at the top level. Both paths that reach a contributor - the
+ * first-run wizard (`blogwright init`) and the generic per-plugin action
+ * (`blogwright analytics init`) - call this one function.
+ *
+ * Only the four settings whose defaults are plain literals are asked. The
+ * other two the block accepts - `tableBucket` and `saltSecretName` - are
+ * deliberately not asked: their defaults carry the environment (`config.ts`),
+ * a contributor is handed no environment (`PluginInitIo` is terminal-shaped
+ * and nothing more), and a prompt whose default is wrong for every
+ * environment but one is worse than no prompt at all. An operator overriding
+ * either writes it into the block by hand, where the validator still checks
+ * it.
+ *
+ * The defaults offered come from `validateAnalyticsConfig(undefined)` -
+ * task 44's validator applied to an absent block - rather than from
+ * constants restated here, so the value the wizard offers is by construction
+ * the value an operator gets by leaving the setting out. That is also the
+ * exact call the CLI makes for an operator with no `analytics` key.
+ *
+ * No question carries `required`. Every default below is a non-empty string,
+ * and `ask` (`packages/cli/src/init.ts`) substitutes the default before it
+ * consults `required`, so the flag has no reachable effect on any of them.
+ *
+ * Returns an empty array - never `undefined` - when the operator declines or
+ * the session cannot ask, so the composing caller writes no key, no block
+ * and no stray comma. Touches no filesystem: `PluginInitIo` carries no `fs`,
+ * and writing the answers is the host's job on both paths.
+ */
+async function askAnalyticsBlock(io) {
+    if (!io.isInteractive) {
+        io.logger.warn('analytics: not an interactive session - skipping the analytics block; run `blogwright analytics init` later, or write it by hand');
+        return [];
+    }
+    const defaults = validateAnalyticsConfig(undefined);
+    const enable = await io.ask({
+        prompt: 'set up analytics now? CloudFront access logs into an Iceberg table (y/n)',
+        defaultValue: 'y',
+    });
+    if (!isYes(enable))
+        return [];
+    const namespace = await io.ask({
+        prompt: 'Iceberg namespace holding the table',
+        defaultValue: defaults.namespace,
+        validate: (answer) => rejectionOf({ namespace: answer }),
+    });
+    const table = await io.ask({
+        prompt: 'Iceberg table the page views land in',
+        defaultValue: defaults.table,
+        validate: (answer) => rejectionOf({ table: answer }),
+    });
+    const bots = await io.ask({
+        prompt: 'bot traffic in dashboard queries - flag (keep, marked) or filter (excluded)',
+        defaultValue: defaults.bots,
+        validate: (answer) => rejectionOf({ bots: answer }),
+    });
+    const port = await io.ask({
+        prompt: 'port the local dashboard listens on',
+        defaultValue: String(defaults.dashboard.port),
+        validate: portRejection,
+    });
+    return [
+        { property: `"namespace": "${namespace}"`, comment: 'Iceberg namespace holding the table' },
+        { property: `"table": "${table}"`, comment: 'Iceberg table the page views land in' },
+        {
+            property: `"bots": "${bots}"`,
+            comment: 'flag keeps bot rows and marks them; filter excludes them from queries',
+        },
+        // The number is rendered from the parsed value, not the typed text: a
+        // `04317` an operator types validates fine as a number but is not legal
+        // JSON, and this block is re-parsed before it reaches disk.
+        {
+            property: `"dashboard": { "port": ${Number(port)} }`,
+            comment: 'the dashboard binds 127.0.0.1 on this port',
+        },
+    ];
+}
+/**
+ * The plugin the CLI discovers. `Plugin<AnalyticsConfig>` names the block
+ * `validateConfig` returns, which is what the host puts on
+ * `ctx.pluginConfig` - the only route to this plugin's settings, and (for
+ * the two environment-carrying ones) only through
+ * `resolveAnalyticsConfig(ctx)`.
+ */
+const analyticsPlugin = {
+    name: ANALYTICS_NAMESPACE,
+    description: 'CloudFront access logs in an Iceberg table, with a local dashboard',
+    configKey: ANALYTICS_NAMESPACE,
+    validateConfig: validateAnalyticsConfig,
+    init: askAnalyticsBlock,
+    nodes: buildAnalyticsNodes,
+    commands: [
+        {
+            action: 'status',
+            summary: "show resources, stream delivery health and the table's row count",
+            run: status,
+        },
+        {
+            action: 'dashboard',
+            summary: 'serve the local dashboard over the table on 127.0.0.1',
+            run: dashboard,
+        },
+        {
+            action: 'backfill',
+            summary: "one-shot fill of pre-Firehose days from the site's logs",
+            run: backfill,
+        },
+    ],
+};
+export default analyticsPlugin;

package/dist/ports.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Analytics-owned ports. Shared ports (`FileSystem`, `Terminal`) come from
+ * blogwright-core; the ports here serve only this package, following the CLI's
+ * private-ports precedent (`packages/cli/src/ports.ts:1-6`).
+ *
+ * **The vendor library lives only behind these interfaces.** DuckDB is what
+ * actually answers a named query - it attaches the S3 Tables catalog in
+ * read-only mode and runs the statement - and what writes a backfilled day,
+ * through a second attach of the same catalog that is not read-only. DuckDB's
+ * node-api package is imported nowhere in this package except the two adapters
+ * under `adapters/` that implement {@link AnalyticsQuery} and
+ * {@link AnalyticsIngest}. (Named in prose rather than spelled as the package
+ * specifier, so the definition of done's grep for that specifier over this
+ * tree does not trip over a comment.) Nothing in the signatures below names a
+ * DuckDB type either: a result row is this package's own {@link QueryRow} and
+ * an inserted row is {@link PageView} off `schema.ts`, neither of them a
+ * vendor object, so the named query set, the local server, the dashboard's
+ * data shaping and the backfill command all compile with no knowledge that
+ * DuckDB exists.
+ *
+ * That containment is load-bearing rather than tidy. The change spec records
+ * DuckDB's iceberg extension as *preview*, so its attach syntax may move, and
+ * it records that the "no Lake Formation grant" assumption holds only while
+ * the table bucket stays in IAM access-control mode. The port is what keeps
+ * either of those turning into an edit spread across the dashboard: both land
+ * in one adapter, which is also where DuckDB's errors are mapped into the
+ * repo's own vocabulary.
+ *
+ * Tests never start DuckDB. They substitute at these ports with the
+ * fixture-backed fake in `fixture-query.ts`, which answers the same named set
+ * through the same lookup and range validation the real adapter uses, and with
+ * the recording fake in `fixture-ingest.ts`, which keeps every day it was
+ * handed so a test can assert what was written rather than that something was.
+ */
+import type { QueryName, QueryParams } from './queries.js';
+import type { PageView } from './schema.js';
+/**
+ * One cell of a result row. `null` is deliberately not among them: a SQL NULL
+ * reaches a caller as an absent key, so no reader ever has to tell "the column
+ * was null" from "the column means null" - the repo's rule that no `null`
+ * stands for a domain value, applied at the read boundary.
+ *
+ * Not exported: no consumer needs the bare union today - one can reach the
+ * same type as `QueryRow[string]`. Export it once a real consumer needs it by
+ * name.
+ */
+type QueryValue = string | number | boolean;
+/**
+ * One result row, keyed by the result column names the query's definition
+ * declares (`resultColumns` in `queries.ts`). A generic record rather than a
+ * per-query row type: the seven definitions' shapes are data, and a caller
+ * that wants a narrower type narrows it at its own boundary.
+ */
+export type QueryRow = Readonly<Record<string, QueryValue>>;
+/**
+ * Reading the `page_views` table, in domain vocabulary: one operation, "answer
+ * this named query over this date range".
+ *
+ * `name` is a {@link QueryName} and not a `string`, which is the port's half of
+ * the spec's *Named queries, never client-supplied SQL* decision - a caller
+ * cannot ask this port for a statement, only for one of the seven the package
+ * defines. An implementation still validates at run time, because the one seam
+ * that feeds it is an HTTP path off the local server, where the compiler's
+ * guarantee has already been erased: an unknown name raises an error listing
+ * the available names, and an absent or inverted range raises rather than
+ * quietly standing in a default (see `prepareQuery`).
+ */
+export interface AnalyticsQuery {
+    /**
+     * Answer one of the named queries. Rows come back in the definition's own
+     * order (the `ORDER BY` it carries), so a caller never re-sorts to get a
+     * stable chart.
+     */
+    run(name: QueryName, params: QueryParams): Promise<readonly QueryRow[]>;
+}
+/**
+ * Writing whole days into the `page_views` table, in domain vocabulary: one
+ * operation, "insert these rows for this UTC day".
+ *
+ * **It exists for the one-shot `analytics backfill` action and nothing else.**
+ * The steady-state pipeline never reaches it: CloudFront's logs arrive through
+ * Firehose, which writes the table itself (§Analytics pipeline → Shape), so
+ * the only writer on this side of the port is the hand-run pull of history
+ * that predates the Firehose delivery. The dashboard's read path is never
+ * handed an implementation of this interface - `createDashboardServer` takes
+ * an {@link AnalyticsQuery} and has no member to put one in - so a named query
+ * cannot become a write however the server is called.
+ *
+ * `day` is the `YYYY-MM-DD` UTC day every row in `rows` carries in its own
+ * `day` column, passed separately because it is the unit of the operation: an
+ * implementation inserts the whole day or none of it. Passing it also lets an
+ * implementation refuse a batch whose rows do not all belong to the day it was
+ * asked to write, which is a mistake no row-shaped signature could express.
+ *
+ * There is deliberately no `close()`. Task 55 measured the read side - an
+ * unclosed in-memory DuckDB instance holds no libuv handle and the process
+ * exits - and the write side adds nothing that outlives a call: each
+ * {@link insertDay} is its own transaction, committed or rolled back before it
+ * returns, so a command that stops between days leaves no open transaction and
+ * no half-written day behind. A `close()` here would be an interface member
+ * with no caller, which `pnpm knip` cannot see and a reader would take for a
+ * resource that needs releasing.
+ */
+export interface AnalyticsIngest {
+    /**
+     * Insert one whole UTC day's rows, atomically. An empty `rows` is a caller
+     * error rather than a no-op: a day with nothing to write is a day the caller
+     * should not have asked to insert, and treating it as success would make an
+     * "inserted" report line true of a day that got nothing.
+     */
+    insertDay(day: string, rows: readonly PageView[]): Promise<void>;
+}
+export {};

package/dist/ports.js

@@ -0,0 +1,35 @@
+/**
+ * Analytics-owned ports. Shared ports (`FileSystem`, `Terminal`) come from
+ * blogwright-core; the ports here serve only this package, following the CLI's
+ * private-ports precedent (`packages/cli/src/ports.ts:1-6`).
+ *
+ * **The vendor library lives only behind these interfaces.** DuckDB is what
+ * actually answers a named query - it attaches the S3 Tables catalog in
+ * read-only mode and runs the statement - and what writes a backfilled day,
+ * through a second attach of the same catalog that is not read-only. DuckDB's
+ * node-api package is imported nowhere in this package except the two adapters
+ * under `adapters/` that implement {@link AnalyticsQuery} and
+ * {@link AnalyticsIngest}. (Named in prose rather than spelled as the package
+ * specifier, so the definition of done's grep for that specifier over this
+ * tree does not trip over a comment.) Nothing in the signatures below names a
+ * DuckDB type either: a result row is this package's own {@link QueryRow} and
+ * an inserted row is {@link PageView} off `schema.ts`, neither of them a
+ * vendor object, so the named query set, the local server, the dashboard's
+ * data shaping and the backfill command all compile with no knowledge that
+ * DuckDB exists.
+ *
+ * That containment is load-bearing rather than tidy. The change spec records
+ * DuckDB's iceberg extension as *preview*, so its attach syntax may move, and
+ * it records that the "no Lake Formation grant" assumption holds only while
+ * the table bucket stays in IAM access-control mode. The port is what keeps
+ * either of those turning into an edit spread across the dashboard: both land
+ * in one adapter, which is also where DuckDB's errors are mapped into the
+ * repo's own vocabulary.
+ *
+ * Tests never start DuckDB. They substitute at these ports with the
+ * fixture-backed fake in `fixture-query.ts`, which answers the same named set
+ * through the same lookup and range validation the real adapter uses, and with
+ * the recording fake in `fixture-ingest.ts`, which keeps every day it was
+ * handed so a test can assert what was written rather than that something was.
+ */
+export {};