@pikku/kysely 0.13.24 → 0.13.27

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.27",
+  "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.111"
   },
   "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[@]}"

package/bin/pikku-kysely-pure.ts

@@ -1,59 +0,0 @@
-#!/usr/bin/env node
-
-import { mkdir, readFile, writeFile } from 'fs/promises'
-import { dirname } from 'path'
-import { fileURLToPath } from 'url'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-const main = async (output: string, input?: string) => {
-  let execDirectory = process.cwd()
-  let inputPath = `${__dirname}/../node_modules/kysely-codegen/dist/db.d.ts`
-  if (input) {
-    inputPath = `${execDirectory}/${input}`
-  }
-
-  let kysely: string
-  try {
-    kysely = await readFile(inputPath, 'utf8')
-  } catch {
-    console.error(`Could not read file ${input}`)
-    process.exit(1)
-  }
-
-  kysely = kysely
-    .replace('import type { ColumnType } from "kysely";', '')
-    .replace(
-      new RegExp('^export\\s+type\\s+Generated<[^>]+>.*?;\\s*$', 'ms'),
-      ''
-    )
-    .replace(/Generated<(.*)>/g, '$1')
-    .replace(
-      /export type Numeric =.*;/,
-      'export type Numeric = string | number'
-    )
-    .replace(/export type Timestamp =.*;/, 'export type Timestamp = Date')
-    .replace(
-      /export type ArrayType<T> = ArrayTypeImpl<T> extends \(infer U\)\[\]\s*\?\s*U\[\]\s*:\s*ArrayTypeImpl<T>;\s*export type ArrayTypeImpl<T> = T extends ColumnType<infer S, infer I, infer U>\s*\?\s*ColumnType<S\[\], I\[\], U\[\]>\s*:\s*T\[\];/gs,
-      ''
-    )
-    .replace(/ArrayType<([^>]+)>/g, '$1[]')
-
-  console.log('Writing kysely-pure.gen.ts')
-
-  const outputPath = `${execDirectory}/${output}`
-  const outputDirectory = dirname(outputPath)
-  await mkdir(outputDirectory, { recursive: true })
-  await writeFile(outputPath, kysely, 'utf-8')
-  console.log(outputPath)
-}
-
-if (process.argv.length !== 4) {
-  console.error('Expected the following usage:')
-  console.error('node kysely-pure.js <output> <input>')
-  process.exit(1)
-}
-
-const [, , output, input] = process.argv
-main(output!, input)

package/dist/src/kysely-lock-vault.d.ts

@@ -1,34 +0,0 @@
-import type { Kysely } from 'kysely';
-import type { LockRecord, LockVault } from '@pikku/core/classification';
-import type { KyselyPikkuDB } from './kysely-tables.js';
-/**
- * Lock records kept in the application's own database.
- *
- * This is what makes a sealed column survive a restart. `createMemoryLockVault`
- * is fine for a test, but its salts die with the process and a sealed row whose
- * salt is gone is not recoverable by anyone — so a real deployment stores them
- * next to the rows they protect, in the same backup and the same restore.
- *
- * The table holds no plaintext key material, only salts and verifiers, which is
- * why it is readable while the store is locked.
- */
-export declare class KyselyLockVault implements LockVault {
-    private readonly db;
-    constructor(db: Kysely<KyselyPikkuDB>);
-    read(): Promise<LockRecord[]>;
-    /**
-     * Replace the whole record set.
-     *
-     * Whole-set rather than per-row because the callers that write are
-     * initialization and rotation, and both produce a complete keyring: applying
-     * one as a partial update would leave records from the previous key behind,
-     * and a stale salt is indistinguishable from a current one.
-     */
-    write(records: LockRecord[]): Promise<void>;
-    /**
-     * Asked through introspection rather than by matching the driver's error
-     * text, so the answer does not depend on which engine phrased the failure or
-     * on the language it phrased it in.
-     */
-    private tableExists;
-}

package/dist/src/kysely-lock-vault.js

@@ -1,77 +0,0 @@
-import { unsafeAsWrapped } from '@pikku/core/classification';
-/**
- * Lock records kept in the application's own database.
- *
- * This is what makes a sealed column survive a restart. `createMemoryLockVault`
- * is fine for a test, but its salts die with the process and a sealed row whose
- * salt is gone is not recoverable by anyone — so a real deployment stores them
- * next to the rows they protect, in the same backup and the same restore.
- *
- * The table holds no plaintext key material, only salts and verifiers, which is
- * why it is readable while the store is locked.
- */
-export class KyselyLockVault {
-    db;
-    constructor(db) {
-        this.db = db;
-    }
-    async read() {
-        try {
-            const rows = await this.db
-                .selectFrom('dataLocks')
-                .select(['keyId', 'keyVersion', 'salt', 'verifier'])
-                .execute();
-            return rows.map((row) => ({
-                keyId: row.keyId,
-                // SQLite hands back whatever it stored and postgres can widen an
-                // integer to a string over the wire, while `keyVersion` is compared
-                // and stamped as a number.
-                keyVersion: Number(row.keyVersion),
-                salt: row.salt,
-                verifier: unsafeAsWrapped(row.verifier),
-            }));
-        }
-        catch (cause) {
-            if (await this.tableExists()) {
-                throw cause;
-            }
-            // No table yet is a legitimate first run — the migration has not been
-            // applied, nobody has chosen a passphrase, and the server should come up
-            // and offer to initialize rather than refuse to start.
-            return [];
-        }
-    }
-    /**
-     * Replace the whole record set.
-     *
-     * Whole-set rather than per-row because the callers that write are
-     * initialization and rotation, and both produce a complete keyring: applying
-     * one as a partial update would leave records from the previous key behind,
-     * and a stale salt is indistinguishable from a current one.
-     */
-    async write(records) {
-        await this.db.transaction().execute(async (trx) => {
-            await trx.deleteFrom('dataLocks').execute();
-            if (records.length) {
-                await trx
-                    .insertInto('dataLocks')
-                    .values(records.map((record) => ({
-                    keyId: record.keyId,
-                    keyVersion: record.keyVersion,
-                    salt: record.salt,
-                    verifier: record.verifier,
-                })))
-                    .execute();
-            }
-        });
-    }
-    /**
-     * Asked through introspection rather than by matching the driver's error
-     * text, so the answer does not depend on which engine phrased the failure or
-     * on the language it phrased it in.
-     */
-    async tableExists() {
-        const tables = await this.db.introspection.getTables();
-        return tables.some((table) => table.name === 'data_locks');
-    }
-}

package/dist/src/schema/data-lock.schema.d.ts

@@ -1,15 +0,0 @@
-import type { PikkuSchema } from './pikku-schema.types.js';
-/**
- * Where the passphrase's salts and verifiers live.
- *
- * Deliberately the one table in a classified deployment that holds nothing
- * encrypted. It has to be readable before anything has been unlocked — a store
- * that needed its own key to find out how to open itself could never be opened
- * — and that costs nothing, because a salt and a verifier reveal no key
- * material.
- *
- * Losing this table is losing the data: every sealed row is opened by a KEK
- * derived from the salt kept here, so a deployment that ships without the
- * migration silently turns its own rows into noise the first time it restarts.
- */
-export declare const dataLockSchema: PikkuSchema;

package/dist/src/schema/data-lock.schema.js

@@ -1,27 +0,0 @@
-import { sql } from 'kysely';
-/**
- * Where the passphrase's salts and verifiers live.
- *
- * Deliberately the one table in a classified deployment that holds nothing
- * encrypted. It has to be readable before anything has been unlocked — a store
- * that needed its own key to find out how to open itself could never be opened
- * — and that costs nothing, because a salt and a verifier reveal no key
- * material.
- *
- * Losing this table is losing the data: every sealed row is opened by a KEK
- * derived from the salt kept here, so a deployment that ships without the
- * migration silently turns its own rows into noise the first time it restarts.
- */
-export const dataLockSchema = {
-    name: 'data-lock',
-    ownedBy: ['dataLock'],
-    statements: [
-        (db) => db.schema
-            .createTable('dataLocks')
-            .addColumn('keyId', 'varchar(255)', (col) => col.primaryKey())
-            .addColumn('keyVersion', 'integer', (col) => col.notNull())
-            .addColumn('salt', 'varchar(64)', (col) => col.notNull())
-            .addColumn('verifier', 'text', (col) => col.notNull())
-            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
-    ],
-};

package/dist/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["../src/classification-crypto.ts","../src/classification-plugin.ts","../src/coercion-plugin.ts","../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-agent-run-scores.ts","../src/kysely-agent-run-service.ts","../src/kysely-agent-run-state-service.ts","../src/kysely-agent-storage-service.ts","../src/kysely-audit-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-scope-service.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-virtual-user-run-store.ts","../src/kysely-virtual-user-schedule-store.ts","../src/kysely-webhook-service.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../src/schema/agent.schema.ts","../src/schema/audit.schema.ts","../src/schema/channel.schema.ts","../src/schema/credential.schema.ts","../src/schema/deployment.schema.ts","../src/schema/index.ts","../src/schema/pikku-schema.types.ts","../src/schema/scope.schema.ts","../src/schema/secret.schema.ts","../src/schema/session.schema.ts","../src/schema/virtual-user-schedule.schema.ts","../src/schema/virtual-user.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}