@pikku/kysely 0.13.2 → 0.13.4

package/src/schema/schema.test.ts

@@ -0,0 +1,273 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  Kysely,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+  SqliteDialect,
+  DummyDriver,
+} from 'kysely'
+import Database from 'better-sqlite3'
+import {
+  pikkuSchemas,
+  compilePikkuSchemas,
+  applyPikkuSchemas,
+  ensurePikkuSchema,
+  unsatisfiedRequirements,
+  type PikkuSchema,
+} from './index.js'
+import { workflowSchema } from './workflow.schema.js'
+
+const dialect = (kind: 'postgres' | 'sqlite') =>
+  kind === 'postgres'
+    ? {
+        createAdapter: () => new PostgresAdapter(),
+        createDriver: () => new DummyDriver(),
+        createIntrospector: (db: Kysely<any>) => new PostgresIntrospector(db),
+        createQueryCompiler: () => new PostgresQueryCompiler(),
+      }
+    : {
+        createAdapter: () => new SqliteAdapter(),
+        createDriver: () => new DummyDriver(),
+        createIntrospector: (db: Kysely<any>) => new SqliteIntrospector(db),
+        createQueryCompiler: () => new SqliteQueryCompiler(),
+      }
+
+const compileFor = (kind: 'postgres' | 'sqlite') =>
+  compilePikkuSchemas(new Kysely<any>({ dialect: dialect(kind) }))
+
+describe('pikku runtime schema', () => {
+  test('declares logical names and compiles them to physical ones', () => {
+    const sql = compileFor('postgres')
+
+    // The declaration says `aiThreads.resourceId`, matching how every query in
+    // the package addresses it; the plugin is what makes the table `ai_threads`.
+    assert.match(sql, /create table "ai_threads"/)
+    assert.match(sql, /"resource_id" varchar\(255\) not null/)
+    assert.doesNotMatch(
+      sql,
+      /"aiThreads"/,
+      'a camelCase table name means the plugin was not applied'
+    )
+  })
+
+  test('rewrites foreign key targets too', () => {
+    assert.match(
+      compileFor('postgres'),
+      /references "ai_threads" \("id"\)/,
+      'an unrewritten reference target points at a table that does not exist'
+    )
+  })
+
+  test('compiles for every dialect from the one declaration', () => {
+    for (const kind of ['postgres', 'sqlite'] as const) {
+      const sql = compileFor(kind)
+      assert.match(sql, /create table "workflow_runs"/, `${kind} workflow_runs`)
+      assert.match(sql, /create table "pikku_scopes"/, `${kind} pikku_scopes`)
+    }
+  })
+
+  test('carries the ai_run column the two old declarations disagreed on', () => {
+    assert.match(compileFor('postgres'), /"pending_approvals" text/)
+  })
+
+  test('creates tables outright rather than if-not-exists', () => {
+    // A migration runs once. `if not exists` would let a table that already
+    // exists in a different shape pass silently, which is the drift the
+    // migration is supposed to surface.
+    assert.doesNotMatch(compileFor('postgres'), /create table if not exists/)
+  })
+
+  test('drops the frozen uuid default from workflow primary keys', () => {
+    // It was `sql.raw("'" + crypto.randomUUID() + "'")`, evaluated once when the
+    // statement was built, so every row shared one default.
+    assert.match(
+      compileFor('postgres'),
+      /"workflow_run_id" text primary key,/,
+      'the primary key should carry no default at all'
+    )
+    assert.match(compileFor('postgres'), /"workflow_step_id" text primary key,/)
+    assert.match(compileFor('postgres'), /"history_id" text primary key,/)
+  })
+
+  test('every schema is named, for the migration it will be written into', () => {
+    const names = pikkuSchemas.map((s) => s.name)
+    assert.equal(new Set(names).size, names.length, 'names must be unique')
+    assert.ok(names.every((n) => /^[a-z][a-z-]*$/.test(n)))
+  })
+})
+
+describe('pikku runtime schema — prerequisites', () => {
+  const memoryDb = () =>
+    new Kysely<any>({
+      dialect: new SqliteDialect({ database: new Database(':memory:') }),
+    })
+
+  test('names the missing table and who owns it, before creating anything', async () => {
+    const db = memoryDb()
+    try {
+      await assert.rejects(
+        applyPikkuSchemas(db),
+        /The 'scope' schema requires 'user\.id', which nothing has created\. Better Auth owns it/
+      )
+
+      const created = await db.introspection.getTables()
+      assert.deepEqual(
+        created.map((t) => t.name),
+        [],
+        'a failed prerequisite must not leave a half-applied database'
+      )
+    } finally {
+      await db.destroy()
+    }
+  })
+
+  test('applies in full once the prerequisite is there', async () => {
+    const db = memoryDb()
+    try {
+      await db.schema
+        .createTable('user')
+        .addColumn('id', 'text', (col) => col.primaryKey())
+        .execute()
+
+      assert.deepEqual(await unsatisfiedRequirements(db), [])
+      await applyPikkuSchemas(db)
+
+      const created = new Set(
+        (await db.introspection.getTables()).map((t) => t.name)
+      )
+      assert.ok(created.has('pikku_user_role'))
+      assert.ok(created.has('workflow_runs'))
+    } finally {
+      await db.destroy()
+    }
+  })
+
+  test('takes the grant column type from the user id it references', () => {
+    // The hand-written DDL said `text`. Better Auth generates a `uuid` primary
+    // key on postgres, and postgres rejects a text column referencing it —
+    // which is why projects ended up writing these tables by hand.
+    const sql = compilePikkuSchemas(
+      new Kysely<any>({ dialect: dialect('postgres') }),
+      pikkuSchemas,
+      { 'user.id': 'uuid' }
+    )
+    assert.match(
+      sql,
+      /create table "pikku_user_role" \("user_id" uuid not null references "user" \("id"\)/
+    )
+    assert.match(
+      sql,
+      /create table "pikku_user_scope" \("user_id" uuid not null references "user" \("id"\)/
+    )
+  })
+
+  test('reports the gap as data, so a caller can describe it instead of dying', async () => {
+    const db = memoryDb()
+    try {
+      const unmet = await unsatisfiedRequirements(db)
+      assert.deepEqual(
+        unmet.map(({ schema, requirement }) => ({
+          schema: schema.name,
+          ...requirement,
+        })),
+        [{ schema: 'scope', table: 'user', column: 'id', owner: 'Better Auth' }]
+      )
+
+      // The rest of the declaration does not depend on auth, so it still applies.
+      const satisfiable = pikkuSchemas.filter((s) => s.name !== 'scope')
+      await applyPikkuSchemas(db, satisfiable)
+      const created = new Set(
+        (await db.introspection.getTables()).map((t) => t.name)
+      )
+      assert.ok(created.has('workflow_runs'))
+      assert.equal(created.has('pikku_user_role'), false)
+    } finally {
+      await db.destroy()
+    }
+  })
+
+  test('a statement failing part way takes the ones before it with it', async () => {
+    const db = memoryDb()
+    try {
+      await db.schema.createTable('taken').addColumn('id', 'text').execute()
+
+      // The prerequisite check cannot see this coming: nothing is missing, the
+      // second statement simply collides with a table the database already has.
+      const collides: PikkuSchema = {
+        name: 'collides',
+        statements: [
+          (db) => db.schema.createTable('first').addColumn('id', 'text'),
+          (db) => db.schema.createTable('taken').addColumn('id', 'text'),
+        ],
+      }
+
+      await assert.rejects(applyPikkuSchemas(db, [collides]))
+
+      const created = new Set(
+        (await db.introspection.getTables()).map((t) => t.name)
+      )
+      assert.equal(
+        created.has('first'),
+        false,
+        'the statement that succeeded must roll back with the one that did not'
+      )
+    } finally {
+      await db.destroy()
+    }
+  })
+})
+
+describe('ensurePikkuSchema — what a service does at boot', () => {
+  const memoryDb = () =>
+    new Kysely<any>({
+      dialect: new SqliteDialect({ database: new Database(':memory:') }),
+    })
+
+  test('creates the tables the first time and finds them the second', async () => {
+    const db = memoryDb()
+    try {
+      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'created')
+      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'present')
+    } finally {
+      await db.destroy()
+    }
+  })
+
+  test('two services declaring the same schema do not fight over it', async () => {
+    // The workflow service and the workflow mirror both own these tables, and
+    // both call init(). Whoever runs second must find them and stop, rather
+    // than issuing DDL the database will reject.
+    const db = memoryDb()
+    try {
+      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'created')
+      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'present')
+    } finally {
+      await db.destroy()
+    }
+  })
+
+  test('refuses a half-applied schema rather than filling in the rest', async () => {
+    // Something else already owns part of it — a migration, an older release,
+    // a hand-run script. Creating the remainder at boot leaves two authorities
+    // over one set of tables, which is the condition all of this exists to end.
+    const db = memoryDb()
+    try {
+      await db.schema
+        .createTable('workflow_runs')
+        .addColumn('workflow_run_id', 'text', (col) => col.primaryKey())
+        .execute()
+
+      await assert.rejects(
+        ensurePikkuSchema(db, workflowSchema),
+        /The 'workflow' schema is half applied/
+      )
+    } finally {
+      await db.destroy()
+    }
+  })
+})

package/src/schema/scope.schema.ts

@@ -0,0 +1,95 @@
+import { sql } from 'kysely'
+import { requiredType, type PikkuSchema } from './pikku-schema.types.js'
+
+/**
+ * Scopes, roles and the grants that bind them to users.
+ *
+ * `pikkuUserRole` and `pikkuUserScope` reference `user.id`, which Better Auth
+ * owns. Auth is a prerequisite rather than an optional companion: a grant is
+ * made to a user, so without the table the user lives in there is nothing to
+ * grant to, and the cascade that revokes grants when a user is deleted has
+ * nothing to hang off.
+ *
+ * `userId` takes its type from `user.id` rather than declaring one, because
+ * that type is Better Auth's to decide: `text` by default, `uuid` under
+ * `generateId: 'uuid'`, an identity `integer` under `'serial'`. The old
+ * hand-written DDL said `text`, and postgres rejects a `text` column
+ * referencing either of the others — so the whole statement failed and projects
+ * wrote these tables by hand instead.
+ */
+export const scopeSchema: PikkuSchema = {
+  name: 'scope',
+  requires: [{ table: 'user', column: 'id', owner: 'Better Auth' }],
+  statements: [
+    (db) =>
+      db.schema
+        .createTable('pikkuScopes')
+        .addColumn('name', 'text', (col) => col.primaryKey())
+        .addColumn('description', 'text')
+        .addColumn('declared', 'boolean', (col) =>
+          col.defaultTo(true).notNull()
+        ),
+
+    (db) =>
+      db.schema
+        .createTable('pikkuRoles')
+        .addColumn('name', 'text', (col) => col.primaryKey())
+        .addColumn('description', 'text')
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        ),
+
+    (db) =>
+      db.schema
+        .createTable('pikkuRoleScopes')
+        .addColumn('role', 'text', (col) =>
+          col.notNull().references('pikkuRoles.name').onDelete('cascade')
+        )
+        .addColumn('scope', 'text', (col) =>
+          col.notNull().references('pikkuScopes.name').onDelete('cascade')
+        )
+        .addPrimaryKeyConstraint('pikku_role_scopes_pk', ['role', 'scope']),
+
+    (db, types) =>
+      db.schema
+        .createTable('pikkuUserRole')
+        .addColumn('userId', requiredType(types, 'user', 'id'), (col) =>
+          col.notNull().references('user.id').onDelete('cascade')
+        )
+        .addColumn('role', 'text', (col) =>
+          col.notNull().references('pikkuRoles.name').onDelete('cascade')
+        )
+        .addColumn('grantedBy', 'text')
+        .addColumn('grantedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addPrimaryKeyConstraint('pikku_user_role_pk', ['userId', 'role']),
+
+    (db, types) =>
+      db.schema
+        .createTable('pikkuUserScope')
+        .addColumn('userId', requiredType(types, 'user', 'id'), (col) =>
+          col.notNull().references('user.id').onDelete('cascade')
+        )
+        .addColumn('scope', 'text', (col) =>
+          col.notNull().references('pikkuScopes.name').onDelete('cascade')
+        )
+        .addColumn('grantedBy', 'text')
+        .addColumn('grantedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addPrimaryKeyConstraint('pikku_user_scope_pk', ['userId', 'scope']),
+
+    (db) =>
+      db.schema
+        .createIndex('pikku_role_scopes_scope_idx')
+        .on('pikkuRoleScopes')
+        .column('scope'),
+
+    (db) =>
+      db.schema
+        .createIndex('pikku_user_role_role_idx')
+        .on('pikkuUserRole')
+        .column('role'),
+  ],
+}

package/src/schema/secret.schema.ts

@@ -0,0 +1,40 @@
+import { sql } from 'kysely'
+import type { PikkuSchema } from './pikku-schema.types.js'
+
+/**
+ * Encrypted secrets and their audit trail.
+ *
+ * The audit table is declared unconditionally, where `init()` created it only
+ * when the service was constructed with auditing on. A migration cannot depend
+ * on runtime configuration, and the asymmetry favours declaring it: an unused
+ * table costs nothing, while turning auditing on against a database that never
+ * got the table fails on the first write.
+ */
+export const secretSchema: PikkuSchema = {
+  name: 'secret',
+  statements: [
+    (db) =>
+      db.schema
+        .createTable('secrets')
+        .addColumn('key', 'varchar(255)', (col) => col.primaryKey())
+        .addColumn('ciphertext', 'text', (col) => col.notNull())
+        .addColumn('wrappedDek', 'text', (col) => col.notNull())
+        .addColumn('keyVersion', 'integer', (col) => col.notNull())
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addColumn('updatedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        ),
+
+    (db) =>
+      db.schema
+        .createTable('secretsAudit')
+        .addColumn('id', 'varchar(36)', (col) => col.primaryKey())
+        .addColumn('secretKey', 'varchar(255)', (col) => col.notNull())
+        .addColumn('action', 'varchar(20)', (col) => col.notNull())
+        .addColumn('performedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        ),
+  ],
+}

package/src/schema/session.schema.ts

@@ -0,0 +1,20 @@
+import { sql } from 'kysely'
+import type { PikkuSchema } from './pikku-schema.types.js'
+
+/** Server-side session storage. */
+export const sessionSchema: PikkuSchema = {
+  name: 'session',
+  statements: [
+    (db) =>
+      db.schema
+        .createTable('pikkuUserSessions')
+        .addColumn('pikkuUserId', 'text', (col) => col.primaryKey())
+        .addColumn('session', 'text', (col) => col.notNull())
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addColumn('updatedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        ),
+  ],
+}

package/src/schema/webhook.schema.ts

@@ -0,0 +1,57 @@
+import { sql } from 'kysely'
+import type { PikkuSchema } from './pikku-schema.types.js'
+
+/** Webhook deliveries and one row per delivery attempt. */
+export const webhookSchema: PikkuSchema = {
+  name: 'webhook',
+  statements: [
+    (db) =>
+      db.schema
+        .createTable('webhookDelivery')
+        .addColumn('deliveryId', 'text', (col) => col.primaryKey())
+        .addColumn('organizationId', 'text')
+        .addColumn('url', 'text', (col) => col.notNull())
+        .addColumn('event', 'text')
+        .addColumn('status', 'text', (col) =>
+          col.defaultTo('pending').notNull()
+        )
+        .addColumn('attempts', 'integer', (col) => col.defaultTo(0).notNull())
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addColumn('updatedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addColumn('deliveredAt', 'timestamp'),
+
+    (db) =>
+      db.schema
+        .createTable('webhookDeliveryAttempt')
+        .addColumn('attemptId', 'text', (col) => col.primaryKey())
+        .addColumn('deliveryId', 'text', (col) =>
+          col
+            .notNull()
+            .references('webhookDelivery.deliveryId')
+            .onDelete('cascade')
+        )
+        .addColumn('attemptNumber', 'integer', (col) => col.notNull())
+        .addColumn('statusCode', 'integer')
+        .addColumn('responseBody', 'text')
+        .addColumn('error', 'text')
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        ),
+
+    (db) =>
+      db.schema
+        .createIndex('idx_webhook_delivery_org')
+        .on('webhookDelivery')
+        .column('organizationId'),
+
+    (db) =>
+      db.schema
+        .createIndex('idx_webhook_delivery_attempt_delivery')
+        .on('webhookDeliveryAttempt')
+        .column('deliveryId'),
+  ],
+}

package/src/schema/workflow.schema.ts

@@ -0,0 +1,113 @@
+import { sql } from 'kysely'
+import type { PikkuSchema } from './pikku-schema.types.js'
+
+/**
+ * Workflow runs, their steps, per-step history and the versioned graphs.
+ *
+ * Two things from the boot-time DDL are deliberately not carried over. The
+ * primary keys had `defaultTo(sql.raw("'" + crypto.randomUUID() + "'"))`, which
+ * evaluates once while the statement is built — every row would have taken the
+ * same default, so it was never a generator; the services supply the id. And
+ * `workflowStep.fromStepName` was backfilled by an `alterTable(...).catch(() =>
+ * {})` bolted on after the fact, which is the job a migration does.
+ *
+ * `KyselyWorkflowMirror` created these same four tables separately. There is one
+ * declaration now, and both services read it.
+ */
+export const workflowSchema: PikkuSchema = {
+  name: 'workflow',
+  statements: [
+    (db) =>
+      db.schema
+        .createTable('workflowRuns')
+        .addColumn('workflowRunId', 'text', (col) => col.primaryKey())
+        .addColumn('workflow', 'text', (col) => col.notNull())
+        .addColumn('status', 'text', (col) => col.notNull())
+        .addColumn('input', 'text', (col) => col.notNull())
+        .addColumn('output', 'text')
+        .addColumn('error', 'text')
+        .addColumn('state', 'text', (col) => col.defaultTo('{}'))
+        .addColumn('inline', 'boolean', (col) => col.defaultTo(false))
+        .addColumn('graphHash', 'text')
+        .addColumn('deterministic', 'boolean', (col) => col.defaultTo(false))
+        .addColumn('plannedSteps', 'text')
+        .addColumn('wire', 'text')
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addColumn('updatedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        ),
+
+    (db) =>
+      db.schema
+        .createTable('workflowStep')
+        .addColumn('workflowStepId', 'text', (col) => col.primaryKey())
+        .addColumn('workflowRunId', 'text', (col) =>
+          col
+            .notNull()
+            .references('workflowRuns.workflowRunId')
+            .onDelete('cascade')
+        )
+        .addColumn('stepName', 'text', (col) => col.notNull())
+        .addColumn('rpcName', 'text')
+        .addColumn('data', 'text')
+        .addColumn('status', 'text', (col) =>
+          col.notNull().defaultTo('pending')
+        )
+        .addColumn('result', 'text')
+        .addColumn('error', 'text')
+        .addColumn('childRunId', 'text')
+        .addColumn('branchTaken', 'text')
+        .addColumn('retries', 'integer')
+        .addColumn('retryDelay', 'text')
+        .addColumn('fromStepName', 'text')
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addColumn('updatedAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addUniqueConstraint('workflow_step_run_name_unique', [
+          'workflowRunId',
+          'stepName',
+        ]),
+
+    (db) =>
+      db.schema
+        .createTable('workflowStepHistory')
+        .addColumn('historyId', 'text', (col) => col.primaryKey())
+        .addColumn('workflowStepId', 'text', (col) =>
+          col
+            .notNull()
+            .references('workflowStep.workflowStepId')
+            .onDelete('cascade')
+        )
+        .addColumn('status', 'text', (col) => col.notNull())
+        .addColumn('result', 'text')
+        .addColumn('error', 'text')
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addColumn('runningAt', 'timestamp')
+        .addColumn('scheduledAt', 'timestamp')
+        .addColumn('succeededAt', 'timestamp')
+        .addColumn('failedAt', 'timestamp'),
+
+    (db) =>
+      db.schema
+        .createTable('workflowVersions')
+        .addColumn('workflowName', 'text', (col) => col.notNull())
+        .addColumn('graphHash', 'text', (col) => col.notNull())
+        .addColumn('graph', 'text', (col) => col.notNull())
+        .addColumn('source', 'text', (col) => col.notNull())
+        .addColumn('status', 'text', (col) => col.notNull().defaultTo('active'))
+        .addColumn('createdAt', 'timestamp', (col) =>
+          col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+        )
+        .addPrimaryKeyConstraint('workflow_versions_pk', [
+          'workflowName',
+          'graphHash',
+        ]),
+  ],
+}