nuxt-observe 0.0.2

package/dist/runtime/server/auth/providers/config-provider.d.ts

@@ -0,0 +1,18 @@
+import type { AuthProvider } from '../../../shared/auth/types.js';
+import type { ObserveUser } from '../../../shared/auth/schema.js';
+/**
+ * Crypto is INJECTED, never statically imported (CP5-HANDOFF §3.4): nuxt-auth-utils'
+ * hashPassword/verifyPassword transitively pull '#imports', which a node-env vitest
+ * cannot transform. getAuthProvider() supplies the ambient Nitro auto-imports in
+ * production; tests supply real scrypt (from @adonisjs/hash) or deterministic fakes.
+ * This mirrors the repo-wide `opts.db ?? useObserveDb()` injection convention.
+ *
+ * The whole provider is a pure factory so CP16 can reuse it verbatim as the gated
+ * bootstrap-admin fallback (roles.ts lifecycle note) without touching this file.
+ */
+export interface ConfigProviderDeps {
+    users: ObserveUser[];
+    hashPassword: (plain: string) => Promise<string>;
+    verifyPassword: (hash: string, plain: string) => Promise<boolean>;
+}
+export declare function createConfigAuthProvider(deps: ConfigProviderDeps): AuthProvider;

package/dist/runtime/server/auth/providers/config-provider.js

@@ -0,0 +1,54 @@
+import { ALL } from "../../../shared/auth/roles.js";
+function isScryptHash(material) {
+  return material.startsWith("$scrypt$");
+}
+export function createConfigAuthProvider(deps) {
+  const { users, hashPassword, verifyPassword } = deps;
+  let map;
+  let dummyHash;
+  async function buildMap() {
+    const m = /* @__PURE__ */ new Map();
+    for (const u of users) {
+      const material = u.passwordHash ?? (u.passwordEnv ? process.env[u.passwordEnv] : void 0);
+      if (!material) {
+        console.warn(`[observe] auth user "${u.name}" has no password material (passwordHash/passwordEnv); skipping`);
+        continue;
+      }
+      const passwordHash = isScryptHash(material) ? material : await hashPassword(material);
+      const assignment = u.role === "admin" ? { services: [ALL], groups: [ALL] } : { services: u.assignedServices ?? [], groups: u.assignedGroups ?? [] };
+      const principal = {
+        sub: u.name,
+        name: u.name,
+        role: u.role,
+        assignment,
+        provider: "config"
+      };
+      m.set(u.name, { principal, passwordHash });
+    }
+    return m;
+  }
+  async function getDummyHash() {
+    dummyHash ??= await hashPassword("observe-anti-enumeration-dummy");
+    return dummyHash;
+  }
+  return {
+    id: "config",
+    async authenticate(credentials) {
+      if (!("password" in credentials)) {
+        return { ok: false, reason: "config provider needs name+password" };
+      }
+      map ??= await buildMap();
+      const entry = map.get(credentials.name);
+      if (!entry) {
+        await verifyPassword(await getDummyHash(), credentials.password);
+        return { ok: false, reason: "unknown user" };
+      }
+      const ok = await verifyPassword(entry.passwordHash, credentials.password);
+      return ok ? { ok: true, principal: entry.principal } : { ok: false, reason: "bad password" };
+    },
+    async resolvePrincipal(sub) {
+      map ??= await buildMap();
+      return map.get(sub)?.principal ?? null;
+    }
+  };
+}

package/dist/runtime/server/auth/providers/db-provider.d.ts

@@ -0,0 +1,16 @@
+import type { AuthProvider } from '../../../shared/auth/types.js';
+import type { Database } from '../../utils/db.js';
+/**
+ * DB-backed dashboard auth (CP16). Crypto is INJECTED (same reason as config-provider:
+ * hashPassword/verifyPassword transitively pull '#imports', which a node-env vitest can't
+ * transform). getAuthProvider() supplies the ambient Nitro auto-imports; tests supply real
+ * scrypt or deterministic fakes. `configFallback` is a createConfigAuthProvider(...) result
+ * used ONLY while the DB has zero enabled admins (the gated bootstrap-admin window).
+ */
+export interface DbProviderDeps {
+    hashPassword: (plain: string) => Promise<string>;
+    verifyPassword: (hash: string, plain: string) => Promise<boolean>;
+    configFallback: AuthProvider;
+    db?: Database;
+}
+export declare function createDbAuthProvider(deps: DbProviderDeps): AuthProvider;

package/dist/runtime/server/auth/providers/db-provider.js

@@ -0,0 +1,42 @@
+import {
+  getUserByUsername,
+  getUserById,
+  getUserAssignments,
+  countAdmins,
+  principalFromUser
+} from "../../utils/db/users.js";
+export function createDbAuthProvider(deps) {
+  const { hashPassword, verifyPassword, configFallback, db } = deps;
+  const opts = db ? { db } : {};
+  let dummyHash;
+  const getDummyHash = async () => dummyHash ??= await hashPassword("observe-anti-enumeration-dummy");
+  async function assemble(userId, row) {
+    const assignment = await getUserAssignments(userId, opts);
+    return principalFromUser(row, assignment);
+  }
+  return {
+    id: "db",
+    async authenticate(credentials, event) {
+      if (!("password" in credentials)) {
+        return { ok: false, reason: "db provider needs name+password" };
+      }
+      const { name, password } = credentials;
+      const user = await getUserByUsername(name, opts);
+      if (user && !user.disabled && user.password_hash) {
+        const ok = await verifyPassword(user.password_hash, password);
+        if (ok) return { ok: true, principal: await assemble(user.id, user) };
+      } else {
+        await verifyPassword(await getDummyHash(), password);
+      }
+      if (await countAdmins(opts) === 0) {
+        return configFallback.authenticate(credentials, event);
+      }
+      return { ok: false, reason: "bad credentials" };
+    },
+    async resolvePrincipal(sub) {
+      const user = await getUserById(sub, opts);
+      if (!user || user.disabled) return null;
+      return await assemble(user.id, user);
+    }
+  };
+}

package/dist/runtime/server/auth/providers/jwt-provider.d.ts

@@ -0,0 +1,24 @@
+import type { AuthProvider, Role } from '../../../shared/auth/types.js';
+import type { Database } from '../../utils/db.js';
+/**
+ * External-JWT verification (CP16). VERIFY only, never issue. Maps verified claims to a
+ * Principal. Any verification failure resolves to { ok:false } (never throws): the Bearer
+ * path wants a clean 401, not a 500. Stateless, so resolvePrincipal is not meaningful.
+ */
+export interface JwtConfig {
+    enabled?: boolean;
+    algorithms?: Array<'HS256' | 'RS256'>;
+    secret?: string;
+    publicKey?: string;
+    jwksUri?: string;
+    issuer?: string;
+    audience?: string;
+    clockTolerance?: string;
+    roleClaim?: string;
+    subjectClaim?: string;
+    assignmentsClaim?: string;
+    roleMap?: Record<string, Role>;
+    claimsSource?: 'token' | 'db';
+    db?: Database;
+}
+export declare function createJwtAuthProvider(cfg: JwtConfig): AuthProvider;

package/dist/runtime/server/auth/providers/jwt-provider.js

@@ -0,0 +1,72 @@
+import { jwtVerify, importSPKI, createRemoteJWKSet } from "jose";
+import { ALL } from "../../../shared/auth/roles.js";
+import { assignmentSchema } from "../../../shared/auth/schema.js";
+import { findUserByIdentity, getUserAssignments } from "../../utils/db/users.js";
+function wildcardIfAdmin(role, assignment) {
+  return role === "admin" ? { services: [ALL], groups: [ALL] } : assignment;
+}
+export function createJwtAuthProvider(cfg) {
+  const roleClaim = cfg.roleClaim ?? "observe_role";
+  const subjectClaim = cfg.subjectClaim ?? "sub";
+  const assignmentsClaim = cfg.assignmentsClaim ?? "observe_assignment";
+  const claimsSource = cfg.claimsSource ?? "token";
+  const dbOpts = cfg.db ? { db: cfg.db } : {};
+  const rsAlg = cfg.algorithms?.find((a) => a === "RS256") ?? "RS256";
+  let keyPromise;
+  const getKey = () => keyPromise ??= (async () => {
+    if (cfg.jwksUri) return createRemoteJWKSet(new URL(cfg.jwksUri));
+    if (cfg.publicKey) return await importSPKI(cfg.publicKey, rsAlg);
+    if (cfg.secret) return new TextEncoder().encode(cfg.secret);
+    return null;
+  })();
+  return {
+    id: "jwt",
+    async authenticate(credentials) {
+      if (!("token" in credentials)) {
+        return { ok: false, reason: "jwt provider needs a token" };
+      }
+      try {
+        const key = await getKey();
+        if (!key) return { ok: false, reason: "jwt provider not configured" };
+        const { payload } = await jwtVerify(credentials.token, key, {
+          // Empty strings arrive from the materialised runtimeConfig defaults; treat as unset
+          // so jose does not require iss/aud to equal '' (see module.ts jwtConfig).
+          issuer: cfg.issuer || void 0,
+          audience: cfg.audience || void 0,
+          algorithms: cfg.algorithms,
+          clockTolerance: cfg.clockTolerance || void 0
+        });
+        const sub = payload[subjectClaim];
+        if (typeof sub !== "string" || !sub) return { ok: false, reason: "no subject claim" };
+        const rawRole = payload[roleClaim];
+        const role = typeof rawRole === "string" && cfg.roleMap?.[rawRole] || "viewer";
+        if (claimsSource === "db") {
+          const user = await findUserByIdentity("jwt", sub, dbOpts);
+          if (!user || user.disabled) return { ok: false, reason: "unknown or disabled identity" };
+          const assignment2 = await getUserAssignments(user.id, dbOpts);
+          const principal2 = {
+            sub,
+            name: user.display_name ?? user.username,
+            role,
+            assignment: wildcardIfAdmin(role, assignment2),
+            provider: "jwt"
+          };
+          return { ok: true, principal: principal2 };
+        }
+        const parsed = assignmentSchema.safeParse(payload[assignmentsClaim]);
+        const assignment = parsed.success ? parsed.data : { services: [], groups: [] };
+        const name = typeof payload.name === "string" ? payload.name : sub;
+        const principal = {
+          sub,
+          name,
+          role,
+          assignment: wildcardIfAdmin(role, assignment),
+          provider: "jwt"
+        };
+        return { ok: true, principal };
+      } catch {
+        return { ok: false, reason: "verification failed" };
+      }
+    }
+  };
+}

package/dist/runtime/server/migrations/0001-services-kind.d.ts

@@ -0,0 +1,8 @@
+import type { Migration } from './types.js';
+/**
+ * Adopted from the pre-CP17 `ensureServicesKindColumn` helper. A fresh DB already has
+ * `kind` from OBSERVE_DDL (the PRAGMA guard sees it and skips); a pre-CP10.5 DB has the
+ * column added here, backfilling existing rows to 'server'. The guard keeps re-running a
+ * no-op, so recording it on the very first CP17 boot never touches existing data.
+ */
+export declare const m0001AddServicesKind: Migration;

package/dist/runtime/server/migrations/0001-services-kind.js

@@ -0,0 +1,14 @@
+export const m0001AddServicesKind = {
+  id: "0001-services-kind",
+  class: "additive",
+  description: "Add services.kind column (server/browser)",
+  async up(db, log) {
+    const cols = await db.prepare(`PRAGMA table_info('services')`).all();
+    if (!cols.some((c) => c.name === "kind")) {
+      log("adding services.kind column");
+      await db.exec(`ALTER TABLE services ADD COLUMN kind TEXT NOT NULL DEFAULT 'server'`);
+    } else {
+      log("services.kind already present, skipping");
+    }
+  }
+};

package/dist/runtime/server/migrations/0002-services-type.d.ts

@@ -0,0 +1,7 @@
+import type { Migration } from './types.js';
+/**
+ * Adopted from the pre-CP17 `ensureServicesTypeColumn` helper. Mirrors the kind column:
+ * a fresh DB already has `type` from OBSERVE_DDL; a pre-CP11 DB gets it added here,
+ * backfilling existing rows to 'service'. Guarded so a re-run is a no-op.
+ */
+export declare const m0002AddServicesType: Migration;

package/dist/runtime/server/migrations/0002-services-type.js

@@ -0,0 +1,14 @@
+export const m0002AddServicesType = {
+  id: "0002-services-type",
+  class: "additive",
+  description: "Add services.type column (UI badge category)",
+  async up(db, log) {
+    const cols = await db.prepare(`PRAGMA table_info('services')`).all();
+    if (!cols.some((c) => c.name === "type")) {
+      log("adding services.type column");
+      await db.exec(`ALTER TABLE services ADD COLUMN type TEXT NOT NULL DEFAULT 'service'`);
+    } else {
+      log("services.type already present, skipping");
+    }
+  }
+};

package/dist/runtime/server/migrations/0003-services-deleted-at.d.ts

@@ -0,0 +1,6 @@
+import type { Migration } from './types.js';
+/**
+ * Adopted from the pre-CP17 `ensureServicesDeletedAtColumn` helper (CP11 soft-delete).
+ * NULL default = every pre-existing row is active. Guarded so a re-run is a no-op.
+ */
+export declare const m0003AddServicesDeletedAt: Migration;

package/dist/runtime/server/migrations/0003-services-deleted-at.js

@@ -0,0 +1,14 @@
+export const m0003AddServicesDeletedAt = {
+  id: "0003-services-deleted-at",
+  class: "additive",
+  description: "Add services.deleted_at soft-delete marker",
+  async up(db, log) {
+    const cols = await db.prepare(`PRAGMA table_info('services')`).all();
+    if (!cols.some((c) => c.name === "deleted_at")) {
+      log("adding services.deleted_at column");
+      await db.exec(`ALTER TABLE services ADD COLUMN deleted_at INTEGER NULL`);
+    } else {
+      log("services.deleted_at already present, skipping");
+    }
+  }
+};

package/dist/runtime/server/migrations/0004-logs-error-fingerprint.d.ts

@@ -0,0 +1,11 @@
+import type { Migration } from './types.js';
+/**
+ * Adopted from the pre-CP17 `ensureLogsErrorFingerprintColumn` helper (CP14). A fresh DB
+ * already has the column from OBSERVE_DDL; a pre-CP14 DB gets it added here, leaving every
+ * existing row NULL until the backfill task runs. The index is created here (not in
+ * OBSERVE_DDL) so the column is guaranteed to exist first on a pre-CP14 DB: the ALTER above
+ * runs before it, whereas running the index inside the DDL batch would fail on the still-
+ * columnless table. Composite so the GROUP BY scan and the `= ? ORDER BY time` drill-down
+ * both ride it. Both statements are guarded/`IF NOT EXISTS`, so a re-run is a no-op.
+ */
+export declare const m0004AddLogsErrorFingerprint: Migration;

package/dist/runtime/server/migrations/0004-logs-error-fingerprint.js

@@ -0,0 +1,15 @@
+export const m0004AddLogsErrorFingerprint = {
+  id: "0004-logs-error-fingerprint",
+  class: "additive",
+  description: "Add logs.error_fingerprint column + index",
+  async up(db, log) {
+    const cols = await db.prepare(`PRAGMA table_info('logs')`).all();
+    if (!cols.some((c) => c.name === "error_fingerprint")) {
+      log("adding logs.error_fingerprint column");
+      await db.exec(`ALTER TABLE logs ADD COLUMN error_fingerprint TEXT`);
+    } else {
+      log("logs.error_fingerprint already present, skipping");
+    }
+    await db.exec(`CREATE INDEX IF NOT EXISTS idx_logs_fingerprint ON logs(error_fingerprint, time)`);
+  }
+};

package/dist/runtime/server/migrations/0005-users-columns.d.ts

@@ -0,0 +1,9 @@
+import type { Migration } from './types.js';
+/**
+ * Adopted from the pre-CP17 `ensureUsersColumns` helper (CP16). A fresh DB already has
+ * role/disabled/created_by/updated_at from the OBSERVE_DDL `users` block; a pre-CP16 DB
+ * (username + password_hash + source only) gets them added here so a clean install and a
+ * migrated install converge on the same shape. Defaults match the DDL, so existing rows
+ * backfill to role='viewer', disabled=0. Each ADD is guarded, so a re-run is a no-op.
+ */
+export declare const m0005AddUsersColumns: Migration;

package/dist/runtime/server/migrations/0005-users-columns.js

@@ -0,0 +1,25 @@
+export const m0005AddUsersColumns = {
+  id: "0005-users-columns",
+  class: "additive",
+  description: "Add users role/disabled/created_by/updated_at columns",
+  async up(db, log) {
+    const cols = await db.prepare(`PRAGMA table_info('users')`).all();
+    const has = (name) => cols.some((c) => c.name === name);
+    if (!has("role")) {
+      log("adding users.role column");
+      await db.exec(`ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'viewer'`);
+    }
+    if (!has("disabled")) {
+      log("adding users.disabled column");
+      await db.exec(`ALTER TABLE users ADD COLUMN disabled INTEGER NOT NULL DEFAULT 0`);
+    }
+    if (!has("created_by")) {
+      log("adding users.created_by column");
+      await db.exec(`ALTER TABLE users ADD COLUMN created_by TEXT NULL`);
+    }
+    if (!has("updated_at")) {
+      log("adding users.updated_at column");
+      await db.exec(`ALTER TABLE users ADD COLUMN updated_at INTEGER NULL`);
+    }
+  }
+};

package/dist/runtime/server/migrations/index.d.ts

@@ -0,0 +1,13 @@
+import type { Migration } from './types.js';
+/**
+ * The ordered migration registry shipped with the package. Publishing a new module
+ * version = appending a descriptor here. Rules:
+ * - Ordering is by array position and MUST match ascending `id`. The runner sorts
+ *   defensively, but authors keep them in order.
+ * - Never reorder and never edit a migration's `up()` after it has shipped in a release:
+ *   a change alters its checksum and triggers a drift warning. A correction is a NEW
+ *   migration with a new id.
+ * - The first five entries are the adopted pre-CP17 `ensure*` helpers, all idempotent
+ *   `additive` migrations, so recording them on the first CP17 boot is a safe no-op.
+ */
+export declare const MIGRATIONS: readonly Migration[];

package/dist/runtime/server/migrations/index.js

@@ -0,0 +1,13 @@
+import { m0001AddServicesKind } from "./0001-services-kind.js";
+import { m0002AddServicesType } from "./0002-services-type.js";
+import { m0003AddServicesDeletedAt } from "./0003-services-deleted-at.js";
+import { m0004AddLogsErrorFingerprint } from "./0004-logs-error-fingerprint.js";
+import { m0005AddUsersColumns } from "./0005-users-columns.js";
+export const MIGRATIONS = [
+  m0001AddServicesKind,
+  m0002AddServicesType,
+  m0003AddServicesDeletedAt,
+  m0004AddLogsErrorFingerprint,
+  m0005AddUsersColumns
+  // future entries appended here, never reordered, never edited after shipping
+];

package/dist/runtime/server/migrations/types.d.ts

@@ -0,0 +1,15 @@
+import type { Database } from '../utils/db.js';
+import type { MigrationClass } from '../../shared/schema/migrations.js';
+export type { MigrationClass };
+/** Sink the runner passes into up(); every line is streamed to the admin console. */
+export type MigrationLog = (line: string) => void;
+export interface Migration {
+    /** Sortable, unique, stable forever once shipped. Convention: 'NNNN-kebab-summary'. */
+    id: string;
+    /** 'additive' = auto-runs at boot; 'destructive' = held for an admin click. */
+    class: MigrationClass;
+    /** Human summary shown in the pending list and console header. */
+    description: string;
+    /** Idempotent forward migration. Runs inside a transaction the runner opens. */
+    up: (db: Database, log: MigrationLog) => Promise<void>;
+}

package/dist/runtime/server/plugins/observe-migrate.server.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nitropack/types").NitroAppPlugin;
+export default _default;

package/dist/runtime/server/plugins/observe-migrate.server.js

@@ -0,0 +1,18 @@
+import { defineNitroPlugin, useRuntimeConfig } from "nitropack/runtime";
+import { ensureObserveSchema } from "../utils/migrate.js";
+import { purgeOldLogs } from "../utils/logs.js";
+import { seedObserveRegistry } from "../utils/seed.js";
+export default defineNitroPlugin(async () => {
+  await ensureObserveSchema();
+  try {
+    const observe = useRuntimeConfig().observe;
+    await seedObserveRegistry(observe);
+  } catch (e) {
+    console.error("[observe] registry seed failed", e);
+  }
+  try {
+    await purgeOldLogs();
+  } catch (e) {
+    console.error("[observe] boot purge failed", e);
+  }
+});

package/dist/runtime/server/tasks/backfill-fingerprints.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Recompute error_fingerprint for error-bearing rows whose fingerprint is missing or
+ * stale (not the current `v1:` algorithm). Manual/one-shot: run after the CP14 migration
+ * lands on an existing DB, or after an algorithm bump. Keyed off the `v1:` prefix so a
+ * future v2 is detectable and re-backfillable without touching already-current rows. The
+ * "row carries an error" predicate is the flat error_* columns (there is no error_json).
+ */
+declare const _default: import("nitropack/types").Task<{
+    updated: number;
+}>;
+export default _default;

package/dist/runtime/server/tasks/backfill-fingerprints.js

@@ -0,0 +1,41 @@
+import { defineTask } from "nitropack/runtime";
+import { fingerprintError } from "../../shared/schema/error-fingerprint.js";
+import { useObserveDb } from "../utils/db.js";
+const BATCH = 500;
+export default defineTask({
+  meta: { name: "observe:backfill-fingerprints", description: "Recompute error fingerprints for rows with NULL or non-v1 fingerprint" },
+  async run() {
+    const db = useObserveDb();
+    let updated = 0;
+    for (; ; ) {
+      const rows = await db.prepare(
+        `SELECT id, error_name, error_message, error_stack, error_code
+         FROM logs
+         WHERE (error_name IS NOT NULL OR error_message IS NOT NULL OR error_stack IS NOT NULL OR error_code IS NOT NULL)
+           AND (error_fingerprint IS NULL OR error_fingerprint NOT LIKE 'v1:%')
+         ORDER BY id
+         LIMIT ?`
+      ).all(BATCH);
+      if (rows.length === 0) break;
+      await db.sql`BEGIN`;
+      try {
+        for (const r of rows) {
+          const { fingerprint } = fingerprintError({
+            name: r.error_name ?? void 0,
+            message: r.error_message ?? void 0,
+            stack: r.error_stack ?? void 0,
+            code: r.error_code ?? void 0
+          });
+          await db.sql`UPDATE logs SET error_fingerprint = ${fingerprint} WHERE id = ${r.id}`;
+        }
+        await db.sql`COMMIT`;
+      } catch (e) {
+        await db.sql`ROLLBACK`;
+        throw e;
+      }
+      updated += rows.length;
+      if (rows.length < BATCH) break;
+    }
+    return { result: { updated } };
+  }
+});

package/dist/runtime/server/tasks/purge.d.ts

@@ -0,0 +1,5 @@
+declare const _default: import("nitropack/types").Task<{
+    deleted: number;
+    servicesPurged: number;
+}>;
+export default _default;

package/dist/runtime/server/tasks/purge.js

@@ -0,0 +1,12 @@
+import { defineTask } from "nitropack/runtime";
+import { purgeOldLogs } from "../utils/logs.js";
+import { purgeExpiredServices } from "../utils/services.js";
+import { SERVICE_DELETE_RETENTION_MS } from "../utils/provisioning.js";
+export default defineTask({
+  meta: { name: "observe:purge", description: "Delete observe logs older than retentionDays and purge expired soft-deleted services" },
+  async run() {
+    const { deleted } = await purgeOldLogs();
+    const { purged } = await purgeExpiredServices(SERVICE_DELETE_RETENTION_MS);
+    return { result: { deleted, servicesPurged: purged } };
+  }
+});

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/server/utils/activity-query.d.ts

@@ -0,0 +1,28 @@
+import type { ActivityData, ActivityDimension, ActivitySort } from '../../shared/schema/activity.js';
+import { type Database } from './db.js';
+/**
+ * CP10 ranked aggregate behind GET /api/observe/activity: a GROUP BY over the canonical
+ * route/feature columns of `logs`, ordered by the requested sort. Same contract as the
+ * CP7 getOverview / CP8 getStats helpers: takes a RESOLVED scope (string[] | '*'), not an
+ * event — the handler runs requireCapability/getAllowedServiceIds/resolveEffectiveScope
+ * first — so this stays pure and node-testable via `opts.db`.
+ *
+ * Two prepared statements per request: the ranked list (Query A) and a cheap totals pass
+ * (Query B) that detects the degraded state — logs exist in the window but none carry the
+ * dimension (the frogger route/feature emit gap CP15 closes). No N+1: keys are their own
+ * labels. The window is always time-bounded, riding idx_logs_service_time when scoped and
+ * idx_logs_time for admin.
+ */
+interface DbOpts {
+    db?: Database;
+}
+export interface ActivityFilters {
+    dimension: ActivityDimension;
+    env?: string;
+    level?: number;
+    q?: string;
+    sort: ActivitySort;
+    limit: number;
+}
+export declare function getActivity(scope: string[] | '*', from: number, to: number, filters: ActivityFilters, opts?: DbOpts): Promise<ActivityData>;
+export {};

package/dist/runtime/server/utils/activity-query.js

@@ -0,0 +1,70 @@
+import { useObserveDb } from "./db.js";
+import { escapeLike } from "./logs.js";
+const DIMENSION_EXPR = {
+  auto: { key: "COALESCE(route, feature)", present: "(route IS NOT NULL OR feature IS NOT NULL)" },
+  route: { key: "route", present: "route IS NOT NULL" },
+  feature: { key: "feature", present: "feature IS NOT NULL" }
+};
+const SORT_EXPR = {
+  count: "count DESC",
+  errors: "errors DESC, count DESC",
+  errorRate: "(errors * 1.0 / count) DESC, count DESC",
+  lastSeen: "lastSeen DESC"
+};
+export async function getActivity(scope, from, to, filters, opts = {}) {
+  if (scope !== "*" && scope.length === 0) return { items: [], total: 0, withKey: 0, degraded: false };
+  const db = opts.db ?? useObserveDb();
+  const dim = DIMENSION_EXPR[filters.dimension];
+  const scoped = scope === "*" ? { clause: "", params: [] } : { clause: `AND service_id IN (${scope.map(() => "?").join(",")})`, params: [...scope] };
+  const filt = [];
+  const filtParams = [];
+  if (filters.env != null) {
+    filt.push("AND env = ?");
+    filtParams.push(filters.env);
+  }
+  if (filters.level != null) {
+    filt.push("AND level = ?");
+    filtParams.push(filters.level);
+  }
+  const where = `WHERE time >= ? AND time <= ? ${scoped.clause} ${filt.join(" ")}`;
+  const baseParams = [from, to, ...scoped.params, ...filtParams];
+  const qClause = filters.q ? `AND ${dim.key} LIKE ? ESCAPE '\\'` : "";
+  const listParams = [
+    ...baseParams,
+    ...filters.q ? [`%${escapeLike(filters.q)}%`] : [],
+    filters.limit
+  ];
+  const listRows = await db.prepare(
+    `SELECT ${dim.key} AS key,
+            SUM(route IS NOT NULL) AS routeHits,
+            COUNT(*) AS count,
+            SUM(level = 0) AS errors,
+            MAX(time) AS lastSeen,
+            MIN(time) AS firstSeen
+     FROM logs
+     ${where} AND ${dim.present} ${qClause}
+     GROUP BY key
+     ORDER BY ${SORT_EXPR[filters.sort]}
+     LIMIT ?`
+  ).all(...listParams);
+  const totalsRow = await db.prepare(
+    `SELECT COUNT(*) AS total,
+            COALESCE(SUM(${dim.present}), 0) AS withKey
+     FROM logs ${where}`
+  ).get(...baseParams);
+  const items = listRows.map((r) => {
+    const errors = r.errors ?? 0;
+    return {
+      key: r.key,
+      dim: filters.dimension === "auto" ? r.routeHits > 0 ? "route" : "feature" : filters.dimension,
+      count: r.count,
+      errors,
+      errorRate: r.count ? errors / r.count : 0,
+      lastSeen: r.lastSeen,
+      firstSeen: r.firstSeen
+    };
+  });
+  const total = totalsRow.total;
+  const withKey = totalsRow.withKey ?? 0;
+  return { items, total, withKey, degraded: total > 0 && withKey === 0 };
+}