@q32/core 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./mcp.js";
 export * from "./oauth.js";
 export * from "./ops-events.js";
 export * from "./pg.js";
+export * from "./pg-kysely.js";
 export * from "./r2-json.js";
 export * from "./rate-limit.js";
 export * from "./seo.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./mcp.js";
 export * from "./oauth.js";
 export * from "./ops-events.js";
 export * from "./pg.js";
+export * from "./pg-kysely.js";
 export * from "./r2-json.js";
 export * from "./rate-limit.js";
 export * from "./seo.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/pg-kysely.d.ts

@@ -0,0 +1,53 @@
+import { Kysely } from "kysely";
+import postgres from "postgres";
+export type PgConnectionSource = "hyperdrive" | "url" | "fallback";
+export type PgSslMode = "auto" | "disable" | "require" | "verify-ca";
+export type HyperdriveLike = {
+    connectionString?: string;
+};
+export type PgEnvLike = Record<string, unknown> & {
+    HYPERDRIVE?: HyperdriveLike;
+    PG_URL?: string;
+    PG_CA_CERT?: string;
+};
+export type ResolvedPgConnection = {
+    connectionString: string;
+    source: PgConnectionSource;
+    closeConnection: boolean;
+    caCert?: string;
+};
+export type PgConnectionOptions = {
+    hyperdriveKey?: string;
+    urlKey?: string;
+    caCertKey?: string;
+    fallbackConnectionString?: string;
+    requireConnection?: boolean;
+    closeConnection?: boolean;
+};
+export type PgClientOptions = {
+    max?: number;
+    prepare?: boolean;
+    idleTimeoutSeconds?: number;
+    connectTimeoutSeconds?: number;
+    sslMode?: PgSslMode;
+};
+export type KyselyPgOptions = PgConnectionOptions & PgClientOptions & {
+    onDestroyError?: (error: unknown) => void;
+};
+type PostgresOptions = NonNullable<Parameters<typeof postgres>[1]>;
+export declare function resolvePgConnection(env: PgEnvLike, options?: PgConnectionOptions): ResolvedPgConnection;
+export declare function postgresClientOptions(connection: Pick<ResolvedPgConnection, "connectionString" | "source" | "caCert">, options?: PgClientOptions): PostgresOptions;
+export declare function createPostgresSql(connection: ResolvedPgConnection, options?: PgClientOptions): postgres.Sql;
+export declare function createKyselyPg<Database>(env: PgEnvLike, options?: KyselyPgOptions): {
+    db: Kysely<Database>;
+    sql: postgres.Sql;
+    connection: ResolvedPgConnection;
+    destroy(): Promise<void>;
+};
+export declare function withKyselyPg<Database, Result>(env: PgEnvLike, fn: (db: Kysely<Database>, context: {
+    sql: postgres.Sql;
+    connection: ResolvedPgConnection;
+}) => Promise<Result>, options?: KyselyPgOptions): Promise<Result>;
+export declare function normalizePem(value?: string): string | undefined;
+export {};
+//# sourceMappingURL=pg-kysely.d.ts.map

package/dist/pg-kysely.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-kysely.d.ts","sourceRoot":"","sources":["../src/pg-kysely.ts"],"names":[],"mappings":"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"}

package/dist/pg-kysely.js

@@ -0,0 +1,128 @@
+import { Kysely } from "kysely";
+import { PostgresJSDialect } from "kysely-postgres-js";
+import postgres from "postgres";
+export function resolvePgConnection(env, options = {}) {
+    const hyperdriveKey = options.hyperdriveKey ?? "HYPERDRIVE";
+    const urlKey = options.urlKey ?? "PG_URL";
+    const caCertKey = options.caCertKey ?? "PG_CA_CERT";
+    const hyperdrive = env[hyperdriveKey];
+    const hyperdriveString = cleanString(hyperdrive?.connectionString);
+    if (hyperdriveString) {
+        return {
+            connectionString: hyperdriveString,
+            source: "hyperdrive",
+            closeConnection: options.closeConnection ?? false,
+        };
+    }
+    const urlString = cleanString(env[urlKey]);
+    if (urlString) {
+        return {
+            connectionString: urlString,
+            source: "url",
+            closeConnection: options.closeConnection ?? true,
+            caCert: normalizePem(cleanString(env[caCertKey])),
+        };
+    }
+    const fallback = cleanString(options.fallbackConnectionString);
+    if (fallback) {
+        return {
+            connectionString: fallback,
+            source: "fallback",
+            closeConnection: options.closeConnection ?? true,
+            caCert: normalizePem(cleanString(env[caCertKey])),
+        };
+    }
+    if (options.requireConnection ?? true) {
+        throw new Error(`${urlKey} or ${hyperdriveKey}.connectionString is required for Postgres.`);
+    }
+    return {
+        connectionString: "",
+        source: "fallback",
+        closeConnection: options.closeConnection ?? true,
+    };
+}
+export function postgresClientOptions(connection, options = {}) {
+    const clientOptions = {
+        max: options.max ?? 1,
+        prepare: options.prepare ?? false,
+        idle_timeout: options.idleTimeoutSeconds ?? 20,
+        connect_timeout: options.connectTimeoutSeconds ?? 5,
+    };
+    const ssl = resolvePgSsl(connection, options.sslMode ?? "auto");
+    if (ssl !== undefined)
+        clientOptions.ssl = ssl;
+    return clientOptions;
+}
+export function createPostgresSql(connection, options = {}) {
+    return postgres(connection.connectionString, postgresClientOptions(connection, options));
+}
+export function createKyselyPg(env, options = {}) {
+    const connection = resolvePgConnection(env, options);
+    const sql = createPostgresSql(connection, options);
+    const db = new Kysely({
+        dialect: new PostgresJSDialect({ postgres: sql }),
+    });
+    return {
+        db,
+        sql,
+        connection,
+        async destroy() {
+            try {
+                await db.destroy();
+            }
+            catch (error) {
+                options.onDestroyError?.(error);
+                if (!options.onDestroyError)
+                    throw error;
+            }
+        },
+    };
+}
+export async function withKyselyPg(env, fn, options = {}) {
+    const handle = createKyselyPg(env, options);
+    try {
+        return await fn(handle.db, { sql: handle.sql, connection: handle.connection });
+    }
+    finally {
+        if (handle.connection.closeConnection) {
+            await handle.destroy();
+        }
+    }
+}
+export function normalizePem(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.includes("\\n") ? trimmed.replace(/\\n/g, "\n") : trimmed;
+}
+function resolvePgSsl(connection, mode) {
+    if (mode === "disable")
+        return false;
+    if (mode === "require")
+        return "require";
+    if (mode === "verify-ca") {
+        if (!connection.caCert)
+            throw new Error("PG_CA_CERT is required when sslMode is verify-ca.");
+        return { ca: connection.caCert, rejectUnauthorized: true };
+    }
+    if (connection.source === "hyperdrive")
+        return false;
+    if (connection.caCert)
+        return { ca: connection.caCert, rejectUnauthorized: true };
+    if (isLocalPgUrl(connection.connectionString))
+        return false;
+    return "require";
+}
+function isLocalPgUrl(connectionString) {
+    try {
+        const host = new URL(connectionString).hostname;
+        return host === "localhost" || host === "127.0.0.1" || host === "::1";
+    }
+    catch {
+        return false;
+    }
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+//# sourceMappingURL=pg-kysely.js.map

package/dist/pg-kysely.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-kysely.js","sourceRoot":"","sources":["../src/pg-kysely.ts"],"names":[],"mappings":"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"}

package/docs/commonality-adgiro-relin-dirtsignal.md

@@ -0,0 +1,28 @@
+# Adgiro, Relin, and DirtSignal Commonality
+
+This is the current direction for `@q32/core`: choose the best reusable pattern across the projects, then move the projects toward it.
+
+## Chosen Defaults
+
+- Postgres access should use Kysely over raw SQL once a project has long-lived relational read models. DirtSignal has the largest raw `postgres` surface today, but Relin's Kysely layer is the better long-term default because it makes schema ownership, joins, transactions, and refactors safer.
+- Cloudflare Workers should create PG clients per request, queue invocation, cron tick, or script scope. Hyperdrive owns pooling in Worker runtime; Node scripts and tests should close clients explicitly.
+- PG connection resolution should prefer Hyperdrive, then `PG_URL`, then an explicit test fallback only when the caller opts in.
+- Non-local PG should use TLS by default. A provided `PG_CA_CERT` should be normalized and used for certificate verification.
+- PG migrations should be explicit, status/dry-run capable, and separated from runtime credentials. Relin's admin/runtime split is the better default; DirtSignal's typed migration-array model is better than ad hoc SQL file parsing for application-owned schema modules.
+- D1 remains the default for small control-plane state, but shared auth, jobs, and ops-event tables should be configurable D1 modules, not app-local forks.
+
+## Core Modules To Grow
+
+- `pg-kysely`: Kysely + `postgres.js` construction, Hyperdrive/PG_URL/CA-cert policy, and scoped `withKyselyPg`.
+- `pg-migrations`: one migration runner that can consume SQL files or typed migration arrays, with status, dry-run, reset guard, and configurable migrations table.
+- `d1-auth`: configurable users/orgs/memberships/identities/magic-link/session helpers. Apps keep policy and copy; core owns token hashing, one-time consume, identity upsert, and session persistence patterns.
+- `mcp-oauth-d1`: the common OAuth client/code/token/device-flow repository used by Relin and DirtSignal, with app-provided principal lookup and entitlement policy.
+- `d1-jobs`: Adgiro's richer job driver is closer to the target than the current minimal core job helper. Core should own enqueue policies, active locks, concurrency keys, delayed requeue, stale-running recovery, and linked ops events.
+- `queue`: a typed Cloudflare Queue publisher/consumer adapter with inline mode for tests and local single-process execution.
+- `ops-events`: converge on run IDs, event names, statuses/severity, target identifiers, metadata/error normalization, and best-effort writes.
+
+## Project Movement
+
+- Relin should keep using Kysely for PG and replace its local connection lifecycle with `@q32/core/pg-kysely`.
+- DirtSignal should migrate new PG repositories to Kysely first, then wrap existing raw `postgres` repositories behind Kysely-compatible interfaces as they change.
+- Adgiro should adopt the shared D1 job driver shape and ops-event schema before adding PG. If it adds PG, it should start on Kysely rather than raw `postgres`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q32/core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Shared TypeScript primitives for Q32 Cloudflare Worker projects.",
   "license": "MIT",
   "type": "module",
@@ -88,6 +88,10 @@
       "types": "./dist/pg.d.ts",
       "default": "./dist/pg.js"
     },
+    "./pg-kysely": {
+      "types": "./dist/pg-kysely.d.ts",
+      "default": "./dist/pg-kysely.js"
+    },
     "./r2-json": {
       "types": "./dist/r2-json.d.ts",
       "default": "./dist/r2-json.js"
@@ -120,15 +124,28 @@
     "README.md",
     "LICENSE"
   ],
+  "peerDependencies": {
+    "kysely": ">=0.28 <0.30",
+    "kysely-postgres-js": "^3.0.0",
+    "postgres": "^3.4.0"
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260606.0",
     "@vitest/coverage-v8": "^4.1.8",
+    "kysely": "^0.29.2",
+    "kysely-postgres-js": "^3.0.0",
+    "postgres": "^3.4.9",
     "typescript": "^5.9.3",
     "vitest": "^4.0.15"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "kysely": "^0.29.2",
+    "kysely-postgres-js": "^3.0.0",
+    "postgres": "^3.4.9"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./mcp.js";
 export * from "./oauth.js";
 export * from "./ops-events.js";
 export * from "./pg.js";
+export * from "./pg-kysely.js";
 export * from "./r2-json.js";
 export * from "./rate-limit.js";
 export * from "./seo.js";

package/src/pg-kysely.ts

@@ -0,0 +1,198 @@
+import { Kysely } from "kysely";
+import { PostgresJSDialect } from "kysely-postgres-js";
+import postgres from "postgres";
+
+export type PgConnectionSource = "hyperdrive" | "url" | "fallback";
+export type PgSslMode = "auto" | "disable" | "require" | "verify-ca";
+
+export type HyperdriveLike = {
+  connectionString?: string;
+};
+
+export type PgEnvLike = Record<string, unknown> & {
+  HYPERDRIVE?: HyperdriveLike;
+  PG_URL?: string;
+  PG_CA_CERT?: string;
+};
+
+export type ResolvedPgConnection = {
+  connectionString: string;
+  source: PgConnectionSource;
+  closeConnection: boolean;
+  caCert?: string;
+};
+
+export type PgConnectionOptions = {
+  hyperdriveKey?: string;
+  urlKey?: string;
+  caCertKey?: string;
+  fallbackConnectionString?: string;
+  requireConnection?: boolean;
+  closeConnection?: boolean;
+};
+
+export type PgClientOptions = {
+  max?: number;
+  prepare?: boolean;
+  idleTimeoutSeconds?: number;
+  connectTimeoutSeconds?: number;
+  sslMode?: PgSslMode;
+};
+
+export type KyselyPgOptions = PgConnectionOptions &
+  PgClientOptions & {
+    onDestroyError?: (error: unknown) => void;
+  };
+
+type PostgresOptions = NonNullable<Parameters<typeof postgres>[1]>;
+
+export function resolvePgConnection(
+  env: PgEnvLike,
+  options: PgConnectionOptions = {},
+): ResolvedPgConnection {
+  const hyperdriveKey = options.hyperdriveKey ?? "HYPERDRIVE";
+  const urlKey = options.urlKey ?? "PG_URL";
+  const caCertKey = options.caCertKey ?? "PG_CA_CERT";
+  const hyperdrive = env[hyperdriveKey] as HyperdriveLike | undefined;
+  const hyperdriveString = cleanString(hyperdrive?.connectionString);
+  if (hyperdriveString) {
+    return {
+      connectionString: hyperdriveString,
+      source: "hyperdrive",
+      closeConnection: options.closeConnection ?? false,
+    };
+  }
+
+  const urlString = cleanString(env[urlKey]);
+  if (urlString) {
+    return {
+      connectionString: urlString,
+      source: "url",
+      closeConnection: options.closeConnection ?? true,
+      caCert: normalizePem(cleanString(env[caCertKey])),
+    };
+  }
+
+  const fallback = cleanString(options.fallbackConnectionString);
+  if (fallback) {
+    return {
+      connectionString: fallback,
+      source: "fallback",
+      closeConnection: options.closeConnection ?? true,
+      caCert: normalizePem(cleanString(env[caCertKey])),
+    };
+  }
+
+  if (options.requireConnection ?? true) {
+    throw new Error(`${urlKey} or ${hyperdriveKey}.connectionString is required for Postgres.`);
+  }
+
+  return {
+    connectionString: "",
+    source: "fallback",
+    closeConnection: options.closeConnection ?? true,
+  };
+}
+
+export function postgresClientOptions(
+  connection: Pick<ResolvedPgConnection, "connectionString" | "source" | "caCert">,
+  options: PgClientOptions = {},
+): PostgresOptions {
+  const clientOptions: PostgresOptions = {
+    max: options.max ?? 1,
+    prepare: options.prepare ?? false,
+    idle_timeout: options.idleTimeoutSeconds ?? 20,
+    connect_timeout: options.connectTimeoutSeconds ?? 5,
+  };
+
+  const ssl = resolvePgSsl(connection, options.sslMode ?? "auto");
+  if (ssl !== undefined) clientOptions.ssl = ssl;
+  return clientOptions;
+}
+
+export function createPostgresSql(
+  connection: ResolvedPgConnection,
+  options: PgClientOptions = {},
+): postgres.Sql {
+  return postgres(connection.connectionString, postgresClientOptions(connection, options));
+}
+
+export function createKyselyPg<Database>(
+  env: PgEnvLike,
+  options: KyselyPgOptions = {},
+): {
+  db: Kysely<Database>;
+  sql: postgres.Sql;
+  connection: ResolvedPgConnection;
+  destroy(): Promise<void>;
+} {
+  const connection = resolvePgConnection(env, options);
+  const sql = createPostgresSql(connection, options);
+  const db = new Kysely<Database>({
+    dialect: new PostgresJSDialect({ postgres: sql }),
+  });
+
+  return {
+    db,
+    sql,
+    connection,
+    async destroy() {
+      try {
+        await db.destroy();
+      } catch (error) {
+        options.onDestroyError?.(error);
+        if (!options.onDestroyError) throw error;
+      }
+    },
+  };
+}
+
+export async function withKyselyPg<Database, Result>(
+  env: PgEnvLike,
+  fn: (db: Kysely<Database>, context: { sql: postgres.Sql; connection: ResolvedPgConnection }) => Promise<Result>,
+  options: KyselyPgOptions = {},
+): Promise<Result> {
+  const handle = createKyselyPg<Database>(env, options);
+  try {
+    return await fn(handle.db, { sql: handle.sql, connection: handle.connection });
+  } finally {
+    if (handle.connection.closeConnection) {
+      await handle.destroy();
+    }
+  }
+}
+
+export function normalizePem(value?: string): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  return trimmed.includes("\\n") ? trimmed.replace(/\\n/g, "\n") : trimmed;
+}
+
+function resolvePgSsl(
+  connection: Pick<ResolvedPgConnection, "connectionString" | "source" | "caCert">,
+  mode: PgSslMode,
+): PostgresOptions["ssl"] | undefined {
+  if (mode === "disable") return false;
+  if (mode === "require") return "require";
+  if (mode === "verify-ca") {
+    if (!connection.caCert) throw new Error("PG_CA_CERT is required when sslMode is verify-ca.");
+    return { ca: connection.caCert, rejectUnauthorized: true };
+  }
+  if (connection.source === "hyperdrive") return false;
+  if (connection.caCert) return { ca: connection.caCert, rejectUnauthorized: true };
+  if (isLocalPgUrl(connection.connectionString)) return false;
+  return "require";
+}
+
+function isLocalPgUrl(connectionString: string): boolean {
+  try {
+    const host = new URL(connectionString).hostname;
+    return host === "localhost" || host === "127.0.0.1" || host === "::1";
+  } catch {
+    return false;
+  }
+}
+
+function cleanString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}