@pikku/kysely 0.13.23 → 0.13.27

package/CHANGELOG.md

@@ -1,3 +1,251 @@
+## 0.13.27
+
+### Patch Changes
+
+- 78237ac: The console shows feature flags as a launch board, and analytics events as a
+  declared catalog.
+
+  A flag's state is four fields — `enabled`, `rolloutPercent`, `declared`,
+  `backed` — and none of them is the question an operator actually asks, which is
+  how far this has got. The board answers that directly: every declared flag sits
+  in the lane its rollout has reached, `dark` → `rolling` → `live`, with
+  `attention` for the flags that are not resolving in a way anybody chose.
+
+  Attention is evaluated before every other reading, and that ordering is the
+  whole point rather than an implementation detail. A flag declared in code with
+  no row in the store fails open, and it reports `enabled: true` with no rollout
+  limit — byte-identical to a deliberate full launch. Read the fields in the
+  obvious order and the one production-severity state on the board renders as the
+  healthiest one. `groupFlagsByLane` also returns all four lanes whether or not
+  they hold anything, because a board read by shape must not rearrange itself the
+  moment a lane empties.
+
+  Selecting a flag opens its controls beside the board rather than over it: the
+  switch, the rollout bucket, and the subjects pinned on or off past that bucket.
+  They share one surface because they are read together — "off for everyone except
+  these three" is a switch and an override row, and an operator who has to leave
+  one screen to see the other is the operator who turns a flag on for everybody by
+  mistake. The panel tracks the open flag by name and re-reads it from the list, so
+  committing a rollout moves the card and the panel together instead of leaving the
+  panel describing the flag as it was before the operator changed it.
+
+  A board whose flags come from a `FeatureFlagSource` — a provider Pikku reads but
+  does not own — says so and offers no controls, rather than offering controls that
+  would fail.
+
+  The analytics screen is a catalog of what the code declares, read from build-time
+  meta: the events a client may emit and the props each carries, with every prop
+  rendered as the schema source text the declaration wrote. It is deliberately not
+  a volume report — nothing here counts what was emitted — and saying which of the
+  two it is turned out to be the only design question the screen had.
+
+  Turning a flag on while it carries no rollout limit now asks first. That press
+  is the one irreversible thing the board can do — with no bucket left to hold
+  anybody back it admits everyone the flag's capabilities allow — and it used to
+  be a single click on a switch. The panel also reports what a mutation is doing
+  and what it refused to do: the controls it is waiting on go into a pending
+  state, and a failed write raises an inline `<Alert>` rather than reverting in
+  silence. The console mounts no notification provider, so the feedback is inline
+  where the action is, which is the idiom the rest of the console already uses.
+
+  `@pikku/mantine`'s theme gains four aliases, and they close a contrast defect
+  that predates this board:
+
+  ```ts
+  '--mantine-color-orange-light': 'var(--app-surface-warning)',
+  '--mantine-color-orange-light-color': 'var(--app-amber)',
+  '--mantine-color-teal-light': 'var(--app-surface-success)',
+  '--mantine-color-teal-light-color': 'var(--app-green)',
+  ```
+
+  The theme already documents two colour tiers — TEXT must clear AA, GRAPHIC only
+  3:1 — and already pulls Mantine's own variables into that contract rather than
+  linting call sites. What it had not covered was Mantine's _light variants_:
+  `<Alert color="orange">` renders #d9480f on #ffe8cc at 3.62:1, and
+  `<Badge variant="light" color="teal">` at 4.33:1, neither reachable from an
+  `--app-*` token because the component never asks for one. The ramp itself is
+  deliberately untouched: Mantine conflates `--mantine-color-orange-filled`
+  between `c="orange"` text and a `variant="filled"` background, so darkening it
+  for light-mode text would make an existing filled badge unreadable in dark mode.
+  Eight pre-existing `c="orange"` call sites moved onto the amber TEXT tier in the
+  same pass.
+
+  The analytics catalog is grouped by the file that declares each event, and its
+  rows are real buttons rather than table cells carrying a tabindex.
+
+  `ShellHeaderAction` gains `loading` and `testId`, and `ActionCluster` gains a
+  `measurement` flag. `ShellHeader` sizes its actions by rendering them a second
+  time off-screen, and that measuring copy was carrying the same `data-testid` and
+  `data-help` as the real one — so every action on a page with a collapsing header
+  resolved to two elements. The flags board also moved its two header actions from
+  `actionsNode` (documented as the non-collapsing escape hatch) onto the structured
+  `actions` array, which is what stopped them clipping off the right edge at 400px.
+
+- Updated dependencies [78237ac]
+- Updated dependencies [add56d2]
+  - @pikku/core@0.12.111
+
+## 0.13.26
+
+### Patch Changes
+
+- 1c9a55a: Review fixes across the feature-flag and analytics primitives:
+
+  - An addon function's `featureFlag:` gate now reads the consuming application's
+    flag source rather than the package's own services, which never carry one.
+  - A flag named `__proto__`, `constructor` or `prototype` is rejected instead of
+    being silently dropped from the generated metadata.
+  - Two declarations of one flag with different descriptions are a hard error,
+    rather than the inspector's traversal order deciding what operators read.
+  - `subjectIdOf` falls through an empty organization id to the user, instead of
+    resolving to no subject and skipping every override and rollout bucket.
+  - `CachedFlagSource.invalidate()` retires the in-flight read, so a webhook that
+    lands mid-fetch is not answered by the pre-webhook snapshot for another TTL.
+  - The generated `/feature-flags` wire resolves against the compiled fallback
+    when no source is wired, so a scope-gated flag is not reported to a caller
+    who cannot hold it.
+  - `pruneFlags()` rechecks `declared = false` in the delete and reports only
+    what it removed, so a redeclaration between the two keeps its overrides.
+  - A destination's `accepts` throwing no longer costs every later sink its batch.
+  - The React analytics client drops events at collection time when analytics is
+    disabled, so a later consent grant cannot send what was gathered before it.
+  - The React flag client keeps its map when the wire answers a non-object.
+  - `KyselyAnalyticsService` mints event ids from `crypto` rather than a
+    timestamp with a short random tail.
+
+- 1c9a55a: Add `KyselyAnalyticsService`, so declared events have somewhere to land.
+
+  Every other pikku primitive backed by a table had a Kysely implementation and
+  analytics did not, which meant a project that declared events either wired a
+  vendor sink or watched them go to the logger — and the logger is not somewhere
+  you can answer a question from. The new service appends to `pikkuAnalyticsEvents`,
+  gated by `ownedBy: ['analyticsService']` so only a project that declares events
+  carries the table.
+
+- 1c9a55a: Export `flagSchema` beside the other schemas.
+
+  `KyselyFeatureFlagStore.init()` expects its tables to exist, and the only way
+  an app creates them is `applyPikkuSchemas(db, [flagSchema])`. Every other store
+  in this package exports the schema that backs it; this one did not, so the
+  store was unusable outside the package that defined it.
+
+- 1c9a55a: Feature flags, declared in source and resolved from two independent booleans.
+
+  `defineFeatureFlags` declares a flag the way `defineScopes` declares a scope —
+  the inspector collects it, the CLI emits a `FeatureFlagName` union, and a
+  misspelled `featureFlag:` is a type error rather than a gate that silently fails
+  open.
+
+  A flag answers two questions that are not the same question. `capable` comes
+  from the session's scopes and is per-user, advisory, and protects nothing — it
+  hides UI. `available` comes from one global config snapshot, is caller-blind,
+  and is the only half the runner enforces: `override(subject) ?? (enabled AND
+bucket)`, so "off for everyone except these three organizations" is one row, and
+  a kill is one write rather than a fan-out. Authorization stays where it was, in
+  the function's own `scopes:` — enforcing capability would make a flag a second
+  authorization path OR-ing against them. An unavailable feature throws 503, not
+  403, because the caller was allowed; the feature was not on.
+
+  `featureFlag:` is deliberately available on sessionless functions too. It reads
+  the config, not the session, so the kill switch reaches a cron task, a queue
+  worker and a webhook — which is where it matters most, since nobody is watching
+  a UI to notice the feature is off.
+
+  Refresh is pull-on-demand, so the TTL is the kill-switch latency. Where that is
+  too long, `invalidate()` is public: a provider's change webhook lands on an HTTP
+  wiring, drops the cache, and the next request does the read. It deliberately
+  does not fetch — a burst of webhooks would be N round trips, and on a serverless
+  runtime the isolate that took the signal may be gone before anything reads the
+  result.
+
+  Availability fails open through three layers: a fresh read, then the last good
+  cached read, then the compiled declaration. The middle layer is load-bearing —
+  dropping straight to the compiled fallback on a blip would switch on every flag
+  that was deliberately dark.
+
+  Backing stores split along what they can honestly do. `FeatureFlagSource` is
+  read-only (`snapshot()`) and is what a third-party provider implements;
+  `FeatureFlagStore` adds the write half and is for stores Pikku owns.
+  `@pikku/kysely` ships the store, with declarations synced additively — a removed
+  declaration is marked undeclared, never revoked, and a sync never re-enables a
+  killed flag. Third-party providers implement the read-only half in the addons
+  repository, over plain `fetch` rather than a vendor SDK — those poll on a timer
+  belonging to a long-lived process, which a serverless isolate cannot hold
+  between requests.
+
+  A client asks for its flags once per session rather than per flag:
+  `scaffold.featureFlags` generates a `GET /feature-flags` returning every
+  declared flag resolved for the caller, keyed by this app's `FeatureFlagName`.
+  Generated into the app rather than shipped in an addon precisely for that union
+  — an addon never sees the host's, and could only answer
+  `Record<string, boolean>`. It returns `show` alone: sending `available` apart
+  from `capable` would tell every visitor which features exist but are dark.
+
+  The write half is the operator's, and lives in `@pikku/addon-admin` beside the
+  scope RPCs, under a new `admin:flags` scope. `flagList` reports `writable:
+false` rather than failing when flags come from a provider, because a provider's
+  own UI is its operator surface and a console full of buttons that 500 is worse
+  than a read-only tab. It still lists the flags: a source may report its declared
+  set through `declaredFlags()`, and each row carries `backed`, false where the
+  provider has never heard of a declared flag. That row is the one worth seeing —
+  an absent row fails open, so a dark launch nobody created in PostHog is already
+  live for everyone, and a store pikku owns can reconcile that on deploy where a
+  provider cannot.
+
+  On the client, `createFeatureFlags` fetches that map once and `useFeatureFlag`
+  reads it synchronously after, through the same provider the analytics client
+  hangs off. It takes a `bootstrap` map so a server-rendered page hydrates onto
+  the answer it already computed: without one there is a gap in which neither
+  default is right, since false hides a feature the user has and true flashes one
+  they do not. A failed refresh keeps the map already on screen rather than
+  relabelling every flag on a blip.
+
+- Updated dependencies [1c9a55a]
+- Updated dependencies [1c9a55a]
+- Updated dependencies [1c9a55a]
+  - @pikku/core@0.12.110
+
+## 0.13.25
+
+### Patch Changes
+
+- 4c7a1b5: Run the monorepo's own scripts through bun instead of yarn. What moves is the
+  package manager each package's `prepublishOnly` and build scripts invoke, plus
+  the two manifest fixes bun needs to resolve the tree: `uWebSockets.js` is
+  declared with an explicit `github:` specifier, and `@pikku/uws-handler` marks
+  its `uWebSockets.js` peer optional so a bun install of a consumer that brings
+  its own uWS app does not try to fetch it from the registry.
+
+  Three published behaviours change, all of them cases where an isolated
+  `node_modules` or bun as the runtime had been papered over by yarn's hoisting:
+
+  - `@pikku/migrator-sql` turns foreign keys on when it opens a sqlite database
+    through bun. `node:sqlite` enforces them by default and `bun:sqlite` does not,
+    which silently turned every `ON DELETE CASCADE` into a no-op under
+    `bunx --bun pikku`.
+  - `@pikku/cli` resolves a deploy provider against the project being deployed
+    rather than against wherever the CLI itself is installed, which is what its
+    own "is not installed" error asks the user to arrange.
+  - `@pikku/cli` treats a specifier a runtime hands straight back — bun does this
+    for the modules it implements itself — as not resolved from the project, so
+    it falls back rather than loading the runtime's own copy.
+
+- Updated dependencies [4c7a1b5]
+  - @pikku/core@0.12.108
+
+## 0.13.24
+
+### Patch Changes
+
+- f10162a: `send()` now reports the delivery id it wrote, not only the broker's job id.
+
+  `KyselyWebhookService.send()` returned `{ jobId }` straight from `queueService.add()`, and callers handed that to `getDelivery()`. That only worked because every queue in the test suite echoed the requested `jobId` back. A broker is free to assign its own identity — the JetStream queue returns a stream sequence — so on those the read-back looked up an id that was never written and 404'd.
+
+  `SendWebhookResult` gains an optional `deliveryId`, which store-backed implementations always populate.
+
+- Updated dependencies [f10162a]
+  - @pikku/core@0.12.104
+
 ## 0.13.23
 
 ### Patch Changes

package/dist/src/index.d.ts

@@ -11,16 +11,19 @@ export { KyselySecretService } from './kysely-secret-service.js';
 export { KyselyCredentialService } from './kysely-credential-service.js';
 export { KyselySessionStore } from './kysely-session-store.js';
 export { KyselyScopeService } from './kysely-scope-service.js';
+export { KyselyFeatureFlagStore } from './kysely-feature-flag-store.js';
+export type { KyselyFeatureFlagStoreOptions } from './kysely-feature-flag-store.js';
 export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { createAuditedKysely, type CreateAuditedKyselyOptions, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
+export { KyselyAnalyticsService } from './kysely-analytics-service.js';
 export { KyselyVirtualUserRunStore } from './kysely-virtual-user-run-store.js';
 export { KyselyVirtualUserScheduleStore } from './kysely-virtual-user-schedule-store.js';
 export { SerializePlugin, BaseSerializePlugin, type Serializer, type Deserializer, } from './serialize-plugin.js';
 export { createCoercionPlugin, type ColumnKind, type CoercionMap, type CreateCoercionPluginOptions, } from './coercion-plugin.js';
 export { createClassificationPlugin, type CreateClassificationPluginOptions, } from './classification-plugin.js';
 export { ClassificationCrypto, DEFAULT_KEY_ID, isColumnEnvelope, parseColumnEnvelope, type ClassificationCryptoOptions, type ColumnEnvelope, type KEKResolver, type ResolvedKEK, } from './classification-crypto.js';
-export { agentSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, type PikkuSchema, type RequiredTypes, type UnmetRequirement, type SchemaStatementFactory, } from './schema/index.js';
+export { agentSchema, analyticsSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, flagSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, type PikkuSchema, type RequiredTypes, type UnmetRequirement, type SchemaStatementFactory, } from './schema/index.js';
 export type { KyselyPikkuDB } from './kysely-tables.js';
 export type { WorkflowRunService } from '@pikku/core/workflow';
 export type { AgentRunService, AgentRunRow } from '@pikku/core/agent';

package/dist/src/index.js

@@ -11,13 +11,15 @@ export { KyselySecretService } from './kysely-secret-service.js';
 export { KyselyCredentialService } from './kysely-credential-service.js';
 export { KyselySessionStore } from './kysely-session-store.js';
 export { KyselyScopeService } from './kysely-scope-service.js';
+export { KyselyFeatureFlagStore } from './kysely-feature-flag-store.js';
 export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { createAuditedKysely, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
+export { KyselyAnalyticsService } from './kysely-analytics-service.js';
 export { KyselyVirtualUserRunStore } from './kysely-virtual-user-run-store.js';
 export { KyselyVirtualUserScheduleStore } from './kysely-virtual-user-schedule-store.js';
 export { SerializePlugin, BaseSerializePlugin, } from './serialize-plugin.js';
 export { createCoercionPlugin, } from './coercion-plugin.js';
 export { createClassificationPlugin, } from './classification-plugin.js';
 export { ClassificationCrypto, DEFAULT_KEY_ID, isColumnEnvelope, parseColumnEnvelope, } from './classification-crypto.js';
-export { agentSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, } from './schema/index.js';
+export { agentSchema, analyticsSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, flagSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, } from './schema/index.js';

package/dist/src/kysely-analytics-service.d.ts

@@ -0,0 +1,30 @@
+import type { AnalyticsRecord, AnalyticsService } from '@pikku/core/analytics';
+import type { Kysely } from 'kysely';
+/**
+ * A durable {@link AnalyticsService} that appends events to a table pikku owns.
+ *
+ * The destination of last resort, and the one a project gets for free: without
+ * it an app that declares events either wires a vendor sink or watches them go
+ * to the logger, and neither is somewhere you can answer a question from. It is
+ * append-only by design — there is no read side here, because querying events
+ * is what a warehouse or the console does with the rows, not what the ingest
+ * path needs.
+ *
+ * Every column is text on every engine, so the same table reads the same
+ * whether it was filled by a locally-run project or a deployed stage. Names are
+ * written camelCase, as the declaration spells them, and `CamelCasePlugin`
+ * turns both into the physical snake_case the migration created.
+ */
+export declare class KyselyAnalyticsService implements AnalyticsService {
+    private db;
+    private initialized;
+    constructor(db: Kysely<any>);
+    /**
+     * Refuse to start unless the table is already there.
+     *
+     * Never creates it: `pikku db generate` writes the migration and `pikku db
+     * migrate` applies it, and those are the only authors of this table.
+     */
+    init(): Promise<void>;
+    write(batch: AnalyticsRecord[]): Promise<void>;
+}

package/dist/src/kysely-analytics-service.js

@@ -0,0 +1,80 @@
+import { requirePikkuSchema } from './schema/index.js';
+import { analyticsSchema } from './schema/analytics.schema.js';
+const jsonOrNull = (value) => value != null ? JSON.stringify(value) : null;
+/**
+ * The primary key. `AnalyticsRecord` carries no id, so every row is given one
+ * here, and a whole batch is minted inside one millisecond — a timestamp with
+ * a short random tail would collide and `doNothing()` would drop the loser
+ * without a word. `randomUUID` where the runtime has it, a 128-bit random hex
+ * where it does not.
+ */
+const eventId = () => {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === 'function') {
+        return `ana_${c.randomUUID()}`;
+    }
+    if (typeof c?.getRandomValues === 'function') {
+        const bytes = c.getRandomValues(new Uint8Array(16));
+        return `ana_${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+    }
+    return `ana_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+};
+/**
+ * A durable {@link AnalyticsService} that appends events to a table pikku owns.
+ *
+ * The destination of last resort, and the one a project gets for free: without
+ * it an app that declares events either wires a vendor sink or watches them go
+ * to the logger, and neither is somewhere you can answer a question from. It is
+ * append-only by design — there is no read side here, because querying events
+ * is what a warehouse or the console does with the rows, not what the ingest
+ * path needs.
+ *
+ * Every column is text on every engine, so the same table reads the same
+ * whether it was filled by a locally-run project or a deployed stage. Names are
+ * written camelCase, as the declaration spells them, and `CamelCasePlugin`
+ * turns both into the physical snake_case the migration created.
+ */
+export class KyselyAnalyticsService {
+    db;
+    initialized = false;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Refuse to start unless the table is already there.
+     *
+     * Never creates it: `pikku db generate` writes the migration and `pikku db
+     * migrate` applies it, and those are the only authors of this table.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        await requirePikkuSchema(this.db, analyticsSchema);
+        this.initialized = true;
+    }
+    async write(batch) {
+        if (!batch.length)
+            return;
+        const rows = batch.map((record) => ({
+            eventId: eventId(),
+            name: record.name,
+            occurredAt: record.occurredAt ?? new Date().toISOString(),
+            source: record.source ?? 'server',
+            functionId: record.functionId ?? null,
+            wireType: record.wireType ?? null,
+            traceId: record.traceId ?? null,
+            userId: record.userIdentity?.userId ?? null,
+            orgId: record.userIdentity?.orgId ?? null,
+            pikkuUserId: record.userIdentity?.pikkuUserId ?? null,
+            anonymousId: record.userIdentity?.anonymousId ?? null,
+            vendorIds: jsonOrNull(record.userIdentity?.vendorIds),
+            consent: jsonOrNull(record.userIdentity?.consent),
+            props: jsonOrNull(record.props),
+        }));
+        await this.db
+            .insertInto('pikkuAnalyticsEvents')
+            .values(rows)
+            .onConflict((oc) => oc.doNothing())
+            .execute();
+    }
+}

package/dist/src/kysely-feature-flag-store.d.ts

@@ -0,0 +1,37 @@
+import type { FeatureFlagStore, FlagOverrideRow, FlagRow } from '@pikku/core/services';
+import type { CachedFlagSourceOptions, DeclaredFlag, FlagConfigSnapshot, FlagSubject } from '@pikku/core/flag';
+import { CachedFlagSource } from '@pikku/core/flag';
+import type { Kysely } from 'kysely';
+import type { KyselyPikkuDB } from './kysely-tables.js';
+export type KyselyFeatureFlagStoreOptions = CachedFlagSourceOptions;
+/**
+ * Feature flags backed by two tables pikku owns.
+ *
+ * The full store, not just a source: the declaration lifecycle and the operator
+ * controls both live here, which is what makes the console's Flags tab
+ * writable. A third-party provider implements `FeatureFlagSource` alone.
+ */
+export declare class KyselyFeatureFlagStore extends CachedFlagSource implements FeatureFlagStore {
+    private db;
+    private initialized;
+    constructor(db: Kysely<KyselyPikkuDB>, options?: KyselyFeatureFlagStoreOptions);
+    init(): Promise<void>;
+    protected fetchSnapshot(): Promise<FlagConfigSnapshot>;
+    syncFlags(flags: DeclaredFlag[]): Promise<void>;
+    listFlags(): Promise<FlagRow[]>;
+    listOverrides(key: string): Promise<FlagOverrideRow[]>;
+    setEnabled(key: string, enabled: boolean, actor?: string, note?: string): Promise<void>;
+    setRollout(key: string, percent: number | null, actor?: string): Promise<void>;
+    setOverride(key: string, subject: FlagSubject, enabled: boolean, actor?: string): Promise<void>;
+    clearOverride(key: string, subject: FlagSubject): Promise<void>;
+    findStaleFlags(): Promise<string[]>;
+    /**
+     * Deletes what is still undeclared, and reports only what it deleted.
+     *
+     * The `declared = false` predicate is repeated on the delete rather than
+     * carried over from the read: a deploy running `syncFlags` between the two
+     * would redeclare a flag, and deleting on the earlier answer would take a
+     * live flag and cascade away every override an operator had set on it.
+     */
+    pruneFlags(): Promise<string[]>;
+}