@pikku/kysely 0.13.6 → 0.13.10

package/dist/src/schema/pikku-schema.types.d.ts

@@ -11,7 +11,40 @@ export interface SchemaStatement {
     execute(): Promise<unknown>;
     compile(): CompiledQuery;
 }
-export type SchemaStatementFactory = (db: Kysely<any>, types: RequiredTypes) => SchemaStatement;
+export type SchemaStatementFactory = (db: Kysely<any>, types: RequiredTypes, ctx: SchemaContext) => SchemaStatement;
+/**
+ * What a statement needs to know about the schema its DDL lands in.
+ *
+ * Only raw SQL needs this. The schema builder learns the schema from the
+ * connection — `withSchema('app')` qualifies every table it names, foreign key
+ * targets included — but a raw fragment is passed through verbatim, so a
+ * statement that spells its own SQL has to spell the qualifier too.
+ */
+export interface SchemaContext {
+    /**
+     * A table as the surrounding DDL addresses it: `"app"."credentials"` on a
+     * schema-bound connection, `"credentials"` otherwise.
+     *
+     * Takes the physical name, not the camelCase one the schema builder accepts.
+     * Raw SQL does not go through `CamelCasePlugin`, so it is already written in
+     * physical names throughout and this is no exception.
+     */
+    table: (name: string) => RawBuilder<unknown>;
+}
+/**
+ * The `SchemaContext` for DDL that names no schema.
+ *
+ * The default everywhere a schema has not been asked for, which is every engine
+ * but postgres and most postgres projects too.
+ */
+export declare const unqualifiedContext: SchemaContext;
+/**
+ * A `SchemaContext` qualifying every table into `schema`.
+ *
+ * Identifiers are quoted rather than interpolated bare so a schema named after
+ * a reserved word still compiles.
+ */
+export declare const schemaContext: (schema: string | undefined) => SchemaContext;
 /**
  * The physical types of the columns named in `requires`, keyed `table.column`.
  *
@@ -68,8 +101,11 @@ export interface SchemaRequirement {
  * Wrap a raw SQL fragment as a statement.
  *
  * For the DDL kysely's schema builder cannot express — a unique index over an
- * expression, say. Note that raw SQL is *not* rewritten by `withSchema`, so a
- * fragment naming a table unqualified will resolve against the connection's
- * search path rather than the schema the rest of the declaration lands in.
+ * expression, say. Raw SQL is *not* rewritten by `withSchema`, so a fragment
+ * naming a table unqualified resolves against the connection's search path
+ * rather than the schema the rest of the declaration lands in. Take the
+ * function form and name tables through `ctx.table` to stay with them; the
+ * bare-fragment form is for SQL that names no table at all.
  */
-export declare const rawStatement: (fragment: RawBuilder<unknown>) => SchemaStatementFactory;
+export declare function rawStatement(fragment: RawBuilder<unknown>): SchemaStatementFactory;
+export declare function rawStatement(build: (ctx: SchemaContext) => RawBuilder<unknown>): SchemaStatementFactory;

package/dist/src/schema/pikku-schema.types.js

@@ -1,4 +1,22 @@
 import { sql } from 'kysely';
+/**
+ * The `SchemaContext` for DDL that names no schema.
+ *
+ * The default everywhere a schema has not been asked for, which is every engine
+ * but postgres and most postgres projects too.
+ */
+export const unqualifiedContext = {
+    table: (name) => sql.raw(`"${name}"`),
+};
+/**
+ * A `SchemaContext` qualifying every table into `schema`.
+ *
+ * Identifiers are quoted rather than interpolated bare so a schema named after
+ * a reserved word still compiles.
+ */
+export const schemaContext = (schema) => schema
+    ? { table: (name) => sql.raw(`"${schema}"."${name}"`) }
+    : unqualifiedContext;
 /**
  * The declared type for a foreign key onto a column another source owns.
  *
@@ -7,15 +25,12 @@ import { sql } from 'kysely';
  * and only the shape of the statement is being inspected.
  */
 export const requiredType = (types, table, column) => sql.raw(types[`${table}.${column}`] ?? 'text');
-/**
- * Wrap a raw SQL fragment as a statement.
- *
- * For the DDL kysely's schema builder cannot express — a unique index over an
- * expression, say. Note that raw SQL is *not* rewritten by `withSchema`, so a
- * fragment naming a table unqualified will resolve against the connection's
- * search path rather than the schema the rest of the declaration lands in.
- */
-export const rawStatement = (fragment) => (db) => ({
-    execute: () => fragment.execute(db),
-    compile: () => fragment.compile(db),
-});
+export function rawStatement(source) {
+    return (db, _types, ctx = unqualifiedContext) => {
+        const fragment = typeof source === 'function' ? source(ctx) : source;
+        return {
+            execute: () => fragment.execute(db),
+            compile: () => fragment.compile(db),
+        };
+    };
+}

package/dist/src/schema/scope.schema.js

@@ -29,6 +29,18 @@ export const scopeSchema = {
             .createTable('pikkuRoles')
             .addColumn('name', 'text', (col) => col.primaryKey())
             .addColumn('description', 'text')
+            // Declared in code with `defineSystemRole` rather than composed by an
+            // admin. What it buys is the refusals: a system role cannot be renamed,
+            // re-scoped or deleted from the console, and a console role cannot be
+            // created with its name — two rows answering to one name would make
+            // "does Susan hold `buyer`?" depend on which one the store returned.
+            .addColumn('system', 'boolean', (col) => col.defaultTo(false).notNull())
+            // A system role whose declaration has gone: still held by whoever holds
+            // it, no longer offered for new grants, awaiting `pikku roles prune`.
+            // The same additive contract as `pikkuScopes.declared`, and for the same
+            // reason — a mid-deploy revocation is not something a code edit should
+            // be able to cause.
+            .addColumn('declared', 'boolean', (col) => col.defaultTo(true).notNull())
             .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
         (db) => db.schema
             .createTable('pikkuRoleScopes')

package/dist/src/schema/secret.schema.js

@@ -19,6 +19,11 @@ export const secretSchema = {
             .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('secretKekSalts')
+            .addColumn('keyVersion', 'integer', (col) => col.primaryKey())
+            .addColumn('salt', 'varchar(64)', (col) => col.notNull())
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
         (db) => db.schema
             .createTable('secretsAudit')
             .addColumn('id', 'varchar(36)', (col) => col.primaryKey())

package/dist/src/schema/virtual-user.schema.d.ts

@@ -0,0 +1,19 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * The `virtualUserRun` table {@link KyselyVirtualUserRunStore} writes to.
+ *
+ * Deliberately not in `pikkuSchemas`: the runtime never needs this table, only
+ * a project that runs virtual users does, and creating it for everyone would
+ * put an empty table in every database. `KyselyVirtualUserRunStore.init()`
+ * applies it, so it arrives exactly when the thing that fills it does.
+ *
+ * `persona` is text rather than a foreign key: personas are declared in code
+ * with `definePersonas()`, not rows, and a run has to outlive the deletion of
+ * the persona it ran as.
+ *
+ * The JSON columns are text on every engine, like the audit table's, because
+ * the store serialises them itself — a project on SQLite and one on Postgres
+ * then hold the same bytes, and comparing this week's findings against last
+ * week's does not depend on which database they were found in.
+ */
+export declare const virtualUserSchema: PikkuSchema;

package/dist/src/schema/virtual-user.schema.js

@@ -0,0 +1,54 @@
+import { sql } from 'kysely';
+/**
+ * The `virtualUserRun` table {@link KyselyVirtualUserRunStore} writes to.
+ *
+ * Deliberately not in `pikkuSchemas`: the runtime never needs this table, only
+ * a project that runs virtual users does, and creating it for everyone would
+ * put an empty table in every database. `KyselyVirtualUserRunStore.init()`
+ * applies it, so it arrives exactly when the thing that fills it does.
+ *
+ * `persona` is text rather than a foreign key: personas are declared in code
+ * with `definePersonas()`, not rows, and a run has to outlive the deletion of
+ * the persona it ran as.
+ *
+ * The JSON columns are text on every engine, like the audit table's, because
+ * the store serialises them itself — a project on SQLite and one on Postgres
+ * then hold the same bytes, and comparing this week's findings against last
+ * week's does not depend on which database they were found in.
+ */
+export const virtualUserSchema = {
+    name: 'virtualUser',
+    statements: [
+        (db) => db.schema
+            .createTable('virtualUserRun')
+            .addColumn('runId', 'varchar(36)', (col) => col.primaryKey())
+            .addColumn('persona', 'varchar(255)', (col) => col.notNull())
+            .addColumn('disposition', 'varchar(50)', (col) => col.notNull())
+            .addColumn('seed', 'bigint', (col) => col.notNull())
+            // running | completed | failed. Not derived from `finishedAt` being
+            // null: a crashed run has no finish time either, and "crashed" and
+            // "still going" are not the same answer.
+            .addColumn('status', 'varchar(50)', (col) => col.defaultTo('running').notNull())
+            .addColumn('goals', 'text', (col) => col.defaultTo('[]').notNull())
+            .addColumn('memory', 'text', (col) => col.defaultTo('{}').notNull())
+            .addColumn('findings', 'text', (col) => col.defaultTo('[]').notNull())
+            // Counts the engine kept: steps, calls, mutations, tokens, elapsed.
+            .addColumn('tally', 'text')
+            .addColumn('stoppedBy', 'varchar(255)')
+            // Why the run itself failed, as opposed to what it found.
+            .addColumn('error', 'text')
+            .addColumn('startedBy', 'varchar(255)')
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('finishedAt', 'timestamp'),
+        // The two reads: the run list newest-first, and one persona's history when
+        // a finding needs comparing against what that persona found before.
+        (db) => db.schema
+            .createIndex('idx_virtual_user_run_created')
+            .on('virtualUserRun')
+            .column('createdAt'),
+        (db) => db.schema
+            .createIndex('idx_virtual_user_run_persona')
+            .on('virtualUserRun')
+            .columns(['persona', 'createdAt']),
+    ],
+};

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-ai-agent-run-service.ts","../src/kysely-ai-run-state-service.ts","../src/kysely-ai-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-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/ai.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/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}
+{"root":["../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-ai-agent-run-service.ts","../src/kysely-ai-run-state-service.ts","../src/kysely-ai-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-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/ai.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.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.6",
+  "version": "0.13.10",
   "description": "Kysely-backed Pikku services — workflow state, secrets, sessions, scopes and audit",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.71"
+    "@pikku/core": "^0.12.77"
   },
   "dependencies": {
     "kysely": "^0.29.0"

package/src/create-audited-kysely.test.ts

@@ -33,8 +33,8 @@ interface AuditEventTable {
   traceId: string | null
   transactionId: string | null
   queryId: string | null
-  actorUserId: string | null
-  actorOrgId: string | null
+  userId: string | null
+  orgId: string | null
   actorPikkuUserId: string | null
   metadataJson: string | null
 }
@@ -76,8 +76,8 @@ async function createAuditEventsTable(
     .addColumn('traceId', 'text')
     .addColumn('transactionId', 'text')
     .addColumn('queryId', 'text')
-    .addColumn('actorUserId', 'text')
-    .addColumn('actorOrgId', 'text')
+    .addColumn('userId', 'text')
+    .addColumn('orgId', 'text')
     .addColumn('actorPikkuUserId', 'text')
     .addColumn('metadataJson', 'text')
     .execute()
@@ -113,9 +113,9 @@ class ImmediateAuditService implements AuditService {
         traceId: event.traceId ?? null,
         transactionId: event.transactionId ?? null,
         queryId: event.queryId ?? null,
-        actorUserId: event.actor?.userId ?? null,
-        actorOrgId: event.actor?.orgId ?? null,
-        actorPikkuUserId: event.actor?.pikkuUserId ?? null,
+        userId: event.userIdentity?.userId ?? null,
+        orgId: event.userIdentity?.orgId ?? null,
+        actorPikkuUserId: event.userIdentity?.pikkuUserId ?? null,
         metadataJson: event.metadata ? JSON.stringify(event.metadata) : null,
       })
       .execute()
@@ -207,7 +207,7 @@ describe('createAuditedKysely', () => {
       changes: { title: 'write tests', done: 0 },
       rowCount: 1,
     })
-    assert.deepEqual(events[0]?.actor, {
+    assert.deepEqual(events[0]?.userIdentity, {
       userId: 'user-1',
       orgId: 'org-1',
       pikkuUserId: 'user-1',
@@ -257,7 +257,7 @@ describe('createAuditedKysely', () => {
       title: 'after',
       done: 1,
     })
-    assert.deepEqual(events[0]?.actor, {
+    assert.deepEqual(events[0]?.userIdentity, {
       userId: 'user-2',
       orgId: undefined,
       pikkuUserId: 'user-2',
@@ -455,7 +455,7 @@ describe('createAuditedKysely', () => {
       ['todos:best-effort', 'todos:best-effort']
     )
     assert.deepEqual(
-      persisted.map((event) => event.actorUserId),
+      persisted.map((event) => event.userId),
       ['user-best-effort', 'user-best-effort']
     )
     assert.equal(persisted[0]?.queryId, 'q-1')

package/src/index.ts

@@ -19,6 +19,7 @@ export {
   type CreateAuditedKyselyOptions,
 } from './create-audited-kysely.js'
 export { KyselyAuditService } from './kysely-audit-service.js'
+export { KyselyVirtualUserRunStore } from './kysely-virtual-user-run-store.js'
 
 export {
   SerializePlugin,
@@ -34,7 +35,9 @@ export {
   type SerializePluginOptions,
 } from './serialize-plugin.js'
 
+export { virtualUserSchema } from './schema/virtual-user.schema.js'
 export {
+  auditSchema,
   pikkuSchemas,
   applyPikkuSchemas,
   compilePikkuSchemas,
@@ -55,3 +58,7 @@ export {
 export type { KyselyPikkuDB } from './kysely-tables.js'
 export type { WorkflowRunService } from '@pikku/core/workflow'
 export type { AgentRunService, AgentRunRow } from '@pikku/core/ai-agent'
+export type {
+  VirtualUserRunStore,
+  VirtualUserRunRecord,
+} from '@pikku/core/virtual-user'