@pikku/kysely 0.13.24 → 0.13.28

package/dist/src/kysely-feature-flag-store.js

@@ -0,0 +1,239 @@
+import { CachedFlagSource, subjectIdOf } from '@pikku/core/flag';
+import { requirePikkuSchema } from './schema/index.js';
+import { flagSchema } from './schema/flag.schema.js';
+/**
+ * Reads the stored `anyOf`, which arrives as either shape.
+ *
+ * The column holds JSON text, but `SerializePlugin` parses it back on the way
+ * out of a sqlite-style dialect while postgres hands over the string as
+ * written. One store serving both engines has to accept both, and the column
+ * type can only describe one of them.
+ */
+const parseAnyOf = (value) => {
+    if (!value)
+        return undefined;
+    const parsed = typeof value === 'string'
+        ? (() => {
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return undefined;
+            }
+        })()
+        : value;
+    return Array.isArray(parsed)
+        ? parsed.filter((v) => typeof v === 'string')
+        : undefined;
+};
+/**
+ * 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 class KyselyFeatureFlagStore extends CachedFlagSource {
+    db;
+    initialized = false;
+    constructor(db, options = {}) {
+        super({ ttlMs: 10_000, ...options });
+        this.db = db;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        await requirePikkuSchema(this.db, flagSchema);
+        this.initialized = true;
+    }
+    async fetchSnapshot() {
+        const [flags, overrides] = await Promise.all([
+            this.db
+                .selectFrom('pikkuFeatureFlags')
+                .select(['name', 'enabled', 'rolloutPercent'])
+                .execute(),
+            this.db
+                .selectFrom('pikkuFeatureFlagOverrides')
+                .select(['flag', 'subjectId', 'enabled'])
+                .execute(),
+        ]);
+        const snapshot = {};
+        for (const flag of flags) {
+            snapshot[flag.name] = {
+                enabled: !!flag.enabled,
+                rolloutPercent: flag.rolloutPercent ?? null,
+                overrides: {},
+            };
+        }
+        for (const override of overrides) {
+            const row = snapshot[override.flag];
+            if (row) {
+                row.overrides[override.subjectId] = !!override.enabled;
+            }
+        }
+        return snapshot;
+    }
+    async syncFlags(flags) {
+        this.setDeclared(flags);
+        await this.db.transaction().execute(async (trx) => {
+            for (const flag of flags) {
+                await trx
+                    .insertInto('pikkuFeatureFlags')
+                    .values({
+                    name: flag.name,
+                    description: flag.description ?? null,
+                    anyOf: flag.anyOf ? JSON.stringify(flag.anyOf) : null,
+                    declared: true,
+                })
+                    .onConflict((oc) => 
+                // `enabled`, `rolloutPercent` and every override are the operator's
+                // and are never touched here. A deploy that re-enabled a flag
+                // somebody killed an hour earlier would make the kill switch
+                // useless exactly when it is being relied on.
+                oc.column('name').doUpdateSet((eb) => ({
+                    description: eb.ref('excluded.description'),
+                    anyOf: eb.ref('excluded.anyOf'),
+                    declared: true,
+                })))
+                    .execute();
+            }
+            const markStale = trx
+                .updateTable('pikkuFeatureFlags')
+                .set({ declared: false });
+            await (flags.length > 0
+                ? markStale.where('name', 'not in', flags.map((f) => f.name))
+                : markStale).execute();
+        });
+        this.invalidate();
+    }
+    async listFlags() {
+        const rows = await this.db
+            .selectFrom('pikkuFeatureFlags')
+            .selectAll()
+            .orderBy('name')
+            .execute();
+        return rows.map((row) => ({
+            name: row.name,
+            description: row.description ?? undefined,
+            anyOf: parseAnyOf(row.anyOf),
+            enabled: !!row.enabled,
+            rolloutPercent: row.rolloutPercent ?? null,
+            declared: !!row.declared,
+        }));
+    }
+    async listOverrides(key) {
+        const rows = await this.db
+            .selectFrom('pikkuFeatureFlagOverrides')
+            .selectAll()
+            .where('flag', '=', key)
+            .orderBy('subjectId')
+            .execute();
+        return rows.map((row) => ({
+            subjectId: row.subjectId,
+            subjectKind: row.subjectKind,
+            enabled: !!row.enabled,
+            grantedBy: row.grantedBy ?? undefined,
+            // ISO 8601 rather than the driver's date: the row crosses an RPC boundary
+            // to reach the console, and every driver spells a timestamp differently.
+            grantedAt: row.grantedAt
+                ? new Date(row.grantedAt).toISOString()
+                : undefined,
+        }));
+    }
+    async setEnabled(key, enabled, actor, note) {
+        await this.db
+            .updateTable('pikkuFeatureFlags')
+            .set({
+            enabled,
+            updatedBy: actor ?? null,
+            note: note ?? null,
+            updatedAt: new Date(),
+        })
+            .where('name', '=', key)
+            .execute();
+        this.invalidate();
+    }
+    async setRollout(key, percent, actor) {
+        if (percent !== null && (percent < 0 || percent > 100)) {
+            throw new Error(`Feature flag '${key}': rollout must be between 0 and 100, got ${percent}.`);
+        }
+        await this.db
+            .updateTable('pikkuFeatureFlags')
+            .set({
+            rolloutPercent: percent === null ? null : Math.round(percent),
+            updatedBy: actor ?? null,
+            updatedAt: new Date(),
+        })
+            .where('name', '=', key)
+            .execute();
+        this.invalidate();
+    }
+    async setOverride(key, subject, enabled, actor) {
+        const subjectId = subjectIdOf(subject);
+        if (!subjectId) {
+            throw new Error(`Feature flag '${key}': an override needs an organization or a user to be about.`);
+        }
+        await this.db
+            .insertInto('pikkuFeatureFlagOverrides')
+            .values({
+            flag: key,
+            subjectId,
+            subjectKind: subject.organizationId ? 'organization' : 'user',
+            enabled,
+            grantedBy: actor ?? null,
+            grantedAt: new Date(),
+        })
+            .onConflict((oc) => oc.columns(['flag', 'subjectId']).doUpdateSet((eb) => ({
+            enabled: eb.ref('excluded.enabled'),
+            subjectKind: eb.ref('excluded.subjectKind'),
+            grantedBy: eb.ref('excluded.grantedBy'),
+            // The column defaults on insert only, and the panel reads this as
+            // when the pin was last granted — not when the subject was first
+            // pinned to something else.
+            grantedAt: eb.ref('excluded.grantedAt'),
+        })))
+            .execute();
+        this.invalidate();
+    }
+    async clearOverride(key, subject) {
+        const subjectId = subjectIdOf(subject);
+        if (!subjectId) {
+            return;
+        }
+        await this.db
+            .deleteFrom('pikkuFeatureFlagOverrides')
+            .where('flag', '=', key)
+            .where('subjectId', '=', subjectId)
+            .execute();
+        this.invalidate();
+    }
+    async findStaleFlags() {
+        const rows = await this.db
+            .selectFrom('pikkuFeatureFlags')
+            .select('name')
+            .where('declared', '=', false)
+            .orderBy('name')
+            .execute();
+        return rows.map((row) => row.name);
+    }
+    /**
+     * 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.
+     */
+    async pruneFlags() {
+        const deleted = await this.db
+            .deleteFrom('pikkuFeatureFlags')
+            .where('declared', '=', false)
+            .returning('name')
+            .execute();
+        if (deleted.length === 0) {
+            return [];
+        }
+        this.invalidate();
+        return deleted.map((row) => row.name).sort();
+    }
+}

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

@@ -61,6 +61,7 @@ export declare class KyselyScopeService implements ScopeService {
     addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>;
     removeUserFromRole(userId: string, role: string): Promise<void>;
     listUserRoles(userId: string): Promise<string[]>;
+    listRolesForUsers(userIds: string[]): Promise<Record<string, string[]>>;
     addScopeToUser(userId: string, scope: string, grantedBy?: string): Promise<void>;
     removeScopeFromUser(userId: string, scope: string): Promise<void>;
     listUserScopes(userId: string): Promise<string[]>;

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

@@ -236,6 +236,35 @@ export class KyselyScopeService {
             .execute();
         return rows.map((row) => row.role);
     }
+    async listRolesForUsers(userIds) {
+        // Seeded with every id asked for, so a user holding no roles is an empty
+        // array rather than a missing key.
+        const byUser = {};
+        for (const userId of userIds) {
+            byUser[userId] = [];
+        }
+        const distinct = Object.keys(byUser);
+        if (distinct.length === 0) {
+            return byUser;
+        }
+        // Chunked because an `in` list is one bound parameter per id, and every
+        // engine caps those — SQLite at 999 on older builds, Postgres at 65535 for
+        // the whole statement. A caller asking for a page of users stays well
+        // inside one chunk; one asking for thousands still gets an answer instead
+        // of a driver error.
+        for (let i = 0; i < distinct.length; i += 500) {
+            const chunk = distinct.slice(i, i + 500);
+            const rows = await this.db
+                .selectFrom('pikkuUserRole')
+                .select(['userId', 'role'])
+                .where('userId', 'in', chunk)
+                .execute();
+            for (const row of rows) {
+                byUser[row.userId].push(row.role);
+            }
+        }
+        return byUser;
+    }
     async addScopeToUser(userId, scope, grantedBy) {
         await this.db
             .insertInto('pikkuUserScope')

package/dist/src/kysely-tables.d.ts

@@ -222,6 +222,29 @@ export interface PikkuRolesTable {
     declared: Generated<boolean>;
     createdAt: Generated<Date>;
 }
+/** A feature flag's operator state. What code declared lives beside it. */
+export interface PikkuFeatureFlagsTable {
+    name: string;
+    description: string | null;
+    /** The declared `anyOf` scope list as JSON, or null for a pure switch. */
+    anyOf: string | null;
+    enabled: Generated<boolean>;
+    rolloutPercent: number | null;
+    /** False for a flag whose declaration has gone: switchable, but not offered. */
+    declared: Generated<boolean>;
+    updatedBy: string | null;
+    note: string | null;
+    updatedAt: Generated<Date>;
+}
+/** One subject's short-circuit, in either direction, over a flag's rollout. */
+export interface PikkuFeatureFlagOverridesTable {
+    flag: string;
+    subjectId: string;
+    subjectKind: string;
+    enabled: boolean;
+    grantedBy: string | null;
+    grantedAt: Generated<Date>;
+}
 export interface PikkuRoleScopesTable {
     role: string;
     scope: string;
@@ -317,6 +340,25 @@ export interface AuditTable {
     old: string | null;
     data: string | null;
 }
+/** One analytics event, as {@link KyselyAnalyticsService} appended it. */
+export interface PikkuAnalyticsEventsTable {
+    eventId: string;
+    name: string;
+    /** ISO 8601, because string ordering is chronological ordering. */
+    occurredAt: string;
+    source: string;
+    functionId: string | null;
+    wireType: string | null;
+    traceId: string | null;
+    userId: string | null;
+    orgId: string | null;
+    pikkuUserId: string | null;
+    /** The device id for a visitor with no session yet. */
+    anonymousId: string | null;
+    vendorIds: string | null;
+    consent: string | null;
+    props: string | null;
+}
 /**
  * One turn of a run's transcript.
  *
@@ -366,6 +408,8 @@ export interface KyselyPikkuDB {
     pikkuRoleScopes: PikkuRoleScopesTable;
     pikkuUserRole: PikkuUserRoleTable;
     pikkuUserScope: PikkuUserScopeTable;
+    pikkuFeatureFlags: PikkuFeatureFlagsTable;
+    pikkuFeatureFlagOverrides: PikkuFeatureFlagOverridesTable;
     channels: ChannelsTable;
     channelSubscriptions: ChannelSubscriptionsTable;
     workflowRuns: WorkflowRunsTable;
@@ -393,4 +437,5 @@ export interface KyselyPikkuDB {
     virtualUserRunStep: VirtualUserRunStepTable;
     virtualUserSchedule: VirtualUserScheduleTable;
     audit: AuditTable;
+    pikkuAnalyticsEvents: PikkuAnalyticsEventsTable;
 }

package/dist/src/schema/analytics.schema.d.ts

@@ -0,0 +1,17 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * The `pikkuAnalyticsEvents` table {@link KyselyAnalyticsService} appends to.
+ *
+ * Gated by `ownedBy` so it arrives only for a project that declares events: a
+ * database that measures nothing should not carry a table for it.
+ *
+ * Every column is text, and `occurredAt` is an ISO 8601 string rather than a
+ * timestamp, for the same reason the audit trail is: a warehouse loader reading
+ * these rows has no shared type to agree on, and string ordering of ISO 8601 is
+ * chronological ordering.
+ *
+ * The identity is spread across columns rather than left inside the JSON
+ * because it is what every query groups by — one visitor's funnel, one org's
+ * usage — while `props` differs per event and is only ever read back whole.
+ */
+export declare const analyticsSchema: PikkuSchema;

package/dist/src/schema/analytics.schema.js

@@ -0,0 +1,48 @@
+/**
+ * The `pikkuAnalyticsEvents` table {@link KyselyAnalyticsService} appends to.
+ *
+ * Gated by `ownedBy` so it arrives only for a project that declares events: a
+ * database that measures nothing should not carry a table for it.
+ *
+ * Every column is text, and `occurredAt` is an ISO 8601 string rather than a
+ * timestamp, for the same reason the audit trail is: a warehouse loader reading
+ * these rows has no shared type to agree on, and string ordering of ISO 8601 is
+ * chronological ordering.
+ *
+ * The identity is spread across columns rather than left inside the JSON
+ * because it is what every query groups by — one visitor's funnel, one org's
+ * usage — while `props` differs per event and is only ever read back whole.
+ */
+export const analyticsSchema = {
+    name: 'analytics',
+    ownedBy: ['analyticsService'],
+    statements: [
+        (db) => db.schema
+            .createTable('pikkuAnalyticsEvents')
+            .addColumn('eventId', 'text', (col) => col.primaryKey())
+            .addColumn('name', 'text', (col) => col.notNull())
+            .addColumn('occurredAt', 'text', (col) => col.notNull())
+            .addColumn('source', 'text', (col) => col.notNull())
+            .addColumn('functionId', 'text')
+            .addColumn('wireType', 'text')
+            .addColumn('traceId', 'text')
+            .addColumn('userId', 'text')
+            .addColumn('orgId', 'text')
+            .addColumn('pikkuUserId', 'text')
+            // The device id for a visitor with no session. Its own column beside
+            // `userId` and not folded into it: the whole point of the anonymous id
+            // is the traffic that has no user to be attributed to yet.
+            .addColumn('anonymousId', 'text')
+            .addColumn('vendorIds', 'text')
+            .addColumn('consent', 'text')
+            .addColumn('props', 'text'),
+        (db) => db.schema
+            .createIndex('idx_pikku_analytics_events_occurred_at')
+            .on('pikkuAnalyticsEvents')
+            .column('occurredAt'),
+        (db) => db.schema
+            .createIndex('idx_pikku_analytics_events_name')
+            .on('pikkuAnalyticsEvents')
+            .column('name'),
+    ],
+};

package/dist/src/schema/flag.schema.d.ts

@@ -0,0 +1,16 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * Feature flags and their per-subject overrides.
+ *
+ * Two tables and not one because the two halves have different cardinality: a
+ * flag is one row an operator flips, an override is an unbounded set keyed by
+ * organization or user. Folding the overrides into a JSON column on the flag
+ * would make granting one tenant early access a read-modify-write of a blob two
+ * consoles can race on.
+ *
+ * Nothing here references `user` or any organization table. A subject id is
+ * stored as opaque text on purpose: pikku does not own the organization
+ * concept, and a foreign key would make flags require a table shape that only
+ * some projects have.
+ */
+export declare const flagSchema: PikkuSchema;

package/dist/src/schema/flag.schema.js

@@ -0,0 +1,62 @@
+import { sql } from 'kysely';
+/**
+ * Feature flags and their per-subject overrides.
+ *
+ * Two tables and not one because the two halves have different cardinality: a
+ * flag is one row an operator flips, an override is an unbounded set keyed by
+ * organization or user. Folding the overrides into a JSON column on the flag
+ * would make granting one tenant early access a read-modify-write of a blob two
+ * consoles can race on.
+ *
+ * Nothing here references `user` or any organization table. A subject id is
+ * stored as opaque text on purpose: pikku does not own the organization
+ * concept, and a foreign key would make flags require a table shape that only
+ * some projects have.
+ */
+export const flagSchema = {
+    name: 'flag',
+    ownedBy: ['featureFlags'],
+    statements: [
+        (db) => db.schema
+            .createTable('pikkuFeatureFlags')
+            .addColumn('name', 'text', (col) => col.primaryKey())
+            .addColumn('description', 'text')
+            // The declared `anyOf` scope list, as JSON. Read by the console to say
+            // who would see the feature; never read on the request path, where the
+            // capability half comes from the session's own scopes.
+            .addColumn('anyOf', 'text')
+            // Off until somebody turns it on. A flag exists so a feature can ship
+            // dark, so the row a deploy creates has to start closed — the opposite
+            // default would make merging the declaration the moment of launch.
+            .addColumn('enabled', 'boolean', (col) => col.defaultTo(false).notNull())
+            // 0-100, or null for no rollout constraint. Null and 100 are not the
+            // same statement: null says the percentage is not part of this flag's
+            // story, 100 says a rollout reached everyone and could be wound back.
+            .addColumn('rolloutPercent', 'integer')
+            // False once the declaration has gone from code: still switchable, no
+            // longer offered, awaiting `pikku flags prune`. The same additive
+            // contract as `pikkuScopes.declared`.
+            .addColumn('declared', 'boolean', (col) => col.defaultTo(true).notNull())
+            .addColumn('updatedBy', 'text')
+            // Why it was flipped. A kill switch is pulled during an incident, and
+            // the one question afterwards is always who turned it off and why.
+            .addColumn('note', 'text')
+            .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+        (db) => db.schema
+            .createTable('pikkuFeatureFlagOverrides')
+            .addColumn('flag', 'text', (col) => col.notNull().references('pikkuFeatureFlags.name').onDelete('cascade'))
+            .addColumn('subjectId', 'text', (col) => col.notNull())
+            // Which id this is, for the console to render. Resolution keys on the
+            // id alone, because that is all the resolver has: it prefers the
+            // organization and falls back to the user, and by then the two are one
+            // string.
+            .addColumn('subjectKind', 'text', (col) => col.notNull())
+            .addColumn('enabled', 'boolean', (col) => col.notNull())
+            .addColumn('grantedBy', 'text')
+            .addColumn('grantedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addPrimaryKeyConstraint('pikku_feature_flag_overrides_pk', [
+            'flag',
+            'subjectId',
+        ]),
+    ],
+};

package/dist/src/schema/index.d.ts

@@ -18,10 +18,12 @@ export { rawStatement, requiredType, schemaContext, unqualifiedContext, } from '
  */
 export declare const pikkuSchemas: PikkuSchema[];
 export { agentSchema } from './agent.schema.js';
+export { analyticsSchema } from './analytics.schema.js';
 export { auditSchema } from './audit.schema.js';
 export { channelSchema } from './channel.schema.js';
 export { credentialSchema } from './credential.schema.js';
 export { deploymentSchema } from './deployment.schema.js';
+export { flagSchema } from './flag.schema.js';
 export { scopeSchema } from './scope.schema.js';
 export { secretSchema } from './secret.schema.js';
 export { sessionSchema } from './session.schema.js';

package/dist/src/schema/index.js

@@ -1,11 +1,13 @@
 import { CamelCasePlugin } from 'kysely';
 import { schemaContext, } from './pikku-schema.types.js';
 import { agentSchema } from './agent.schema.js';
+import { analyticsSchema } from './analytics.schema.js';
 import { auditSchema } from './audit.schema.js';
 import { channelSchema } from './channel.schema.js';
 import { credentialSchema } from './credential.schema.js';
 import { deploymentSchema } from './deployment.schema.js';
 import { scopeSchema } from './scope.schema.js';
+import { flagSchema } from './flag.schema.js';
 import { secretSchema } from './secret.schema.js';
 import { sessionSchema } from './session.schema.js';
 import { webhookSchema } from './webhook.schema.js';
@@ -37,15 +39,19 @@ export const pikkuSchemas = [
     workflowSchema,
     agentSchema,
     scopeSchema,
+    flagSchema,
     auditSchema,
+    analyticsSchema,
     virtualUserSchema,
     virtualUserScheduleSchema,
 ];
 export { agentSchema } from './agent.schema.js';
+export { analyticsSchema } from './analytics.schema.js';
 export { auditSchema } from './audit.schema.js';
 export { channelSchema } from './channel.schema.js';
 export { credentialSchema } from './credential.schema.js';
 export { deploymentSchema } from './deployment.schema.js';
+export { flagSchema } from './flag.schema.js';
 export { scopeSchema } from './scope.schema.js';
 export { secretSchema } from './secret.schema.js';
 export { sessionSchema } from './session.schema.js';

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.24",
+  "version": "0.13.28",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikkujs/pikku.git",
+    "directory": "packages/services/kysely"
+  },
   "description": "Kysely-backed Pikku services — workflow state, secrets, sessions, scopes and audit",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -18,23 +23,23 @@
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
     "release": "npm run build && npm test",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "bun run build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.104"
+    "@pikku/core": "^0.12.120"
   },
   "dependencies": {
     "kysely": "^0.29.5"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.5",
     "@types/better-sqlite3": "^9.6.0",
     "better-sqlite3": "^13.0.3",
     "kysely-codegen": "^0.20.0",
     "kysely-postgres-js": "^3.0.0",
-    "postgres": "^3.4.9",
-    "typescript": "^6.0.3"
+    "postgres": "^3.4.9"
   },
   "exports": {
     ".": "./dist/src/index.js"
   }
-}
+}

package/run-tests.sh

@@ -34,10 +34,17 @@ files=($(find src -type f -name "*.test.ts"))
 # Check if any files matched the pattern
 if [ ${#files[@]} -eq 0 ]; then
   echo "No test files found matching pattern: $pattern"
+  if [ "${STRICT_TEST_DISCOVERY}" = "1" ]; then
+    exit 1
+  fi
   exit 0
 fi
 
 # Construct the node command
+#
+# Every other package runs its tests on bun. This one stays on node because
+# better-sqlite3, which every one of these suites opens its fixture database
+# with, aborts the bun process on load.
 node_cmd=(node --import tsx --test)
 
 # Append options based on flags
@@ -47,7 +54,8 @@ fi
 
 if [ "$coverage_mode" = true ]; then
   node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
+  export PIKKU_TEST_COVERAGE=1
 fi
 
 # Execute the node command with the expanded list of files
-"${node_cmd[@]}" "${files[@]}"
+"${node_cmd[@]}" "${files[@]}"