@agentage/extension 0.1.2 → 0.2.1

package/dist/runtime/part-runners.d.ts

@@ -0,0 +1,20 @@
+import { type Express } from 'express';
+import { type PartContext } from '../context/context.js';
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type ImportModule } from '../manifest/entry.js';
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
+import { type PartAppBase } from '../server/app.js';
+import { type Env } from './build-info.js';
+export interface RunnerInput {
+    dir: string;
+    pkg: ExtensionPackage;
+    env: Env;
+    ctx: () => PartContext;
+    base: PartAppBase;
+    importModule?: ImportModule;
+}
+export interface Running {
+    app: Express;
+    stop?: () => void;
+}
+export declare const RUNNERS: Record<ImagePartKind, (input: RunnerInput) => Promise<Running>>;

package/dist/runtime/part-runners.js

@@ -0,0 +1,63 @@
+import { join } from 'node:path';
+import {} from 'express';
+import {} from '../context/context.js';
+import { readOpenapi } from '../discovery/openapi.js';
+import {} from '../manifest/manifest.schema.js';
+import { loadCreate } from '../manifest/entry.js';
+import { hasPostgres } from '../manifest/parts.js';
+import {} from '../manifest/primitives.schema.js';
+import { createMcpApp } from '../mcp/mcp-app.js';
+import { createToolRegistry } from '../mcp/tools.js';
+import { createPagesApp } from '../pages/pages-app.js';
+import { createApiApp, createPartApp } from '../server/app.js';
+import {} from '../server/part.types.js';
+import {} from './build-info.js';
+import { createUiApp } from '../ui/ui-app.js';
+import { runLog } from '../worker/run-log.js';
+import { memoryRuns, storeRuns } from '../worker/runs.js';
+import { createScheduler } from '../worker/scheduler.js';
+// ui has no code to run; every other part is its create(ctx).
+const callCreate = async (input, part, ctx) => (await loadCreate(input.dir, input.pkg, part, input.importModule))(ctx);
+const api = async (input) => {
+    const router = (await callCreate(input, 'api', input.ctx()));
+    const openapi = await readOpenapi(input.dir);
+    return { app: createApiApp({ ...input.base, router, openapi }) };
+};
+const mcp = async (input) => {
+    const registry = createToolRegistry();
+    const ctx = input.ctx();
+    await callCreate(input, 'mcp', { ...ctx, tool: registry.tool });
+    const listing = ctx.settings['mcp.listing'] === 'token' ? 'token' : 'open';
+    return { app: createMcpApp({ ...input.base, tools: registry.tools, listing }) };
+};
+const pages = async (input) => {
+    const site = (await callCreate(input, 'pages', input.ctx()));
+    return { app: createPagesApp({ ...input.base, site }) };
+};
+const ui = async (input) => ({
+    app: createUiApp({
+        ...input.base,
+        dir: join(input.dir, 'dist', 'ui'),
+        devIssuer: input.env['AGENTAGE_DEV_ISSUER'],
+    }),
+});
+const worker = async (input) => {
+    const ctx = input.ctx();
+    const log = runLog(ctx.log);
+    const runs = hasPostgres(input.pkg) ? storeRuns(ctx.store) : memoryRuns();
+    const scheduler = createScheduler({ runs, log });
+    await callCreate(input, 'worker', { ...ctx, log, schedule: scheduler.schedule });
+    const checks = { ...input.base.checks, ...scheduler.checks() };
+    scheduler.start();
+    return {
+        app: createPartApp({ ...input.base, checks, part: 'worker', mount: () => undefined }),
+        stop: scheduler.stop,
+    };
+};
+export const RUNNERS = {
+    api,
+    mcp,
+    pages,
+    ui,
+    worker,
+};

package/dist/runtime/run-part.d.ts

@@ -1,13 +1,17 @@
 import { type Server } from 'node:http';
-import { type ApiCreate } from '../server/part.types.js';
+import { type TokenCheck } from '../auth/token-check.js';
+import { type ImportModule } from '../manifest/entry.js';
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type ServeOptions } from '../server/serve.js';
 import { type Env } from './build-info.js';
 export interface RunPartOptions {
     dir: string;
     part: string;
     env: Env;
-    importModule?: (file: string) => Promise<unknown>;
+    importModule?: ImportModule;
     serve?: Pick<ServeOptions, 'signals' | 'exit'>;
+    tokenCheck?: TokenCheck;
 }
-export declare const createOf: (mod: unknown, file: string) => ApiCreate;
+export declare const partOf: (pkg: ExtensionPackage, part: string) => ImagePartKind;
 export declare const runPart: (options: RunPartOptions) => Promise<Server>;

package/dist/runtime/run-part.js

@@ -1,23 +1,20 @@
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import {} from 'node:http';
 import { createContext } from '../context/context.js';
+import { settingsFromEnv } from '../context/settings.js';
 import { DEFAULT_RECORD_FILE, loadRecord } from '../discovery/discovery.js';
+import {} from '../auth/token-check.js';
+import {} from '../health/health.js';
 import { createLog } from '../log/log.js';
-import { entryOf } from '../manifest/parts.js';
+import {} from '../manifest/entry.js';
 import {} from '../manifest/manifest.schema.js';
+import { hasPostgres, imageParts } from '../manifest/parts.js';
+import {} from '../manifest/primitives.schema.js';
 import { readManifest } from '../manifest/read-manifest.js';
-import { createApiApp } from '../server/app.js';
-import {} from '../server/part.types.js';
 import { serve } from '../server/serve.js';
+import { createStore, storeCheck } from '../store/store.js';
+import {} from '../store/store.types.js';
 import { buildInfoFromEnv, portFromEnv } from './build-info.js';
-const importFile = (file) => import(pathToFileURL(file).href);
-export const createOf = (mod, file) => {
-    const create = mod?.create;
-    if (typeof create !== 'function')
-        throw new Error(`${file} does not export create(ctx)`);
-    return create;
-};
+import { RUNNERS } from './part-runners.js';
 const recordFor = async (env, log) => {
     const file = env['AGENTAGE_RECORD_FILE'] || DEFAULT_RECORD_FILE;
     const record = await loadRecord(file);
@@ -25,24 +22,65 @@ const recordFor = async (env, log) => {
         log.warn('no release record mounted; discovery lists this image by tag', { file });
     return record;
 };
-const createRouter = async (options, ctx, pkg) => {
-    const file = join(options.dir, entryOf(pkg, 'api'));
-    const mod = await (options.importModule ?? importFile)(file);
-    return createOf(mod, file)(ctx);
+export const partOf = (pkg, part) => {
+    const parts = imageParts(pkg);
+    if (!parts.includes(part))
+        throw new Error(`part ${part} is not an image part of this manifest`);
+    return part;
+};
+// ui serves files and gets no ctx; every other part gets the store when the manifest has postgres.
+const storeFor = ({ pkg, part, env, log }) => part !== 'ui' && hasPostgres(pkg) ? createStore(env, log) : undefined;
+const contextFor = (start, part, store) => createContext({
+    pkg: start.pkg,
+    part,
+    origin: start.env['AGENTAGE_ORIGIN'] || `http://127.0.0.1:${portFromEnv(start.env)}`,
+    commit: buildInfoFromEnv(start.env).commit,
+    log: start.log,
+    settings: settingsFromEnv(start.pkg, start.env, start.log),
+    store,
+});
+// Built on first use, so the ui runner, which never asks, has no ctx at all.
+const lazyContext = (start, store) => {
+    let ctx;
+    return () => {
+        if (start.part === 'ui')
+            throw new Error('the ui part gets no ctx');
+        return (ctx ??= contextFor(start, start.part, store));
+    };
+};
+const baseFor = async (options, start, store) => {
+    const { pkg, env, log } = start;
+    const checks = store ? { store: storeCheck(store) } : {};
+    return {
+        pkg,
+        log,
+        checks,
+        build: buildInfoFromEnv(env),
+        record: await recordFor(env, log),
+        origin: env['AGENTAGE_ORIGIN'] || undefined,
+        ownImage: env['AGENTAGE_IMAGE'],
+        tokenCheck: options.tokenCheck,
+    };
+};
+const inputFor = async (options, start) => {
+    const store = storeFor(start);
+    return {
+        dir: options.dir,
+        pkg: start.pkg,
+        env: start.env,
+        ctx: lazyContext(start, store),
+        base: await baseFor(options, start, store),
+        importModule: options.importModule,
+    };
 };
-const contextFor = (pkg, origin, port, log) => createContext({ pkg, part: 'api', origin: origin ?? `http://127.0.0.1:${port}`, log });
 export const runPart = async (options) => {
-    if (options.part !== 'api')
-        throw new Error(`part ${options.part} is not served by kit 0.1`);
-    const { env } = options;
     const pkg = await readManifest(options.dir);
-    const log = createLog({ extension: pkg.agentage.id, part: 'api' });
-    const port = portFromEnv(env);
-    const origin = env['AGENTAGE_ORIGIN'] || undefined;
-    const router = await createRouter(options, contextFor(pkg, origin, port, log), pkg);
-    const build = buildInfoFromEnv(env);
-    const record = await recordFor(env, log);
-    const ownImage = env['AGENTAGE_IMAGE'];
-    const app = createApiApp({ pkg, build, router, log, record, origin, ownImage });
-    return serve({ app, port, log, ...options.serve });
+    const part = partOf(pkg, options.part);
+    const log = createLog({ extension: pkg.agentage.id, part });
+    const start = { pkg, part, env: options.env, log };
+    const { app, stop } = await RUNNERS[part](await inputFor(options, start));
+    if (stop)
+        for (const signal of options.serve?.signals ?? ['SIGTERM', 'SIGINT'])
+            process.once(signal, stop);
+    return serve({ app, port: portFromEnv(options.env), log, ...options.serve });
 };

package/dist/server/app.d.ts

@@ -1,16 +1,34 @@
+import { type CorsOptions } from 'cors';
 import { type Express } from 'express';
+import { type HelmetOptions } from 'helmet';
+import { type TokenCheck } from '../auth/token-check.js';
 import { type BuildInfo } from '../discovery/discovery.js';
 import { type ExtensionRecord } from '../discovery/discovery.schema.js';
+import { type HealthCheck } from '../health/health.js';
 import { type Log } from '../log/log.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type ApiHandler } from './part.types.js';
-export interface ApiAppOptions {
+export interface PartAppBase {
     pkg: ExtensionPackage;
     build: BuildInfo;
-    router: ApiHandler;
     log: Log;
     record?: ExtensionRecord | null;
     ownImage?: string;
     origin?: string;
+    checks?: Record<string, HealthCheck>;
+    tokenCheck?: TokenCheck;
+}
+export interface PartAppOptions extends PartAppBase {
+    part: ImagePartKind;
+    mount: (app: Express) => void;
+    helmet?: HelmetOptions;
+}
+export interface ApiAppOptions extends PartAppBase {
+    router: ApiHandler;
+    openapi?: Record<string, unknown> | null;
 }
+export declare const PUBLIC_CORS: CorsOptions;
+export declare const BODY_LIMIT = "1mb";
+export declare const createPartApp: (options: PartAppOptions) => Express;
 export declare const createApiApp: (options: ApiAppOptions) => Express;

package/dist/server/app.js

@@ -1,25 +1,28 @@
 import cors, {} from 'cors';
 import express, {} from 'express';
-import helmet from 'helmet';
+import helmet, {} from 'helmet';
 import { agcidMiddleware } from '../agcid/scope.js';
+import { routeAccess } from '../auth/route-access.js';
+import { setCaller } from '../auth/token-check.js';
 import { discoveryDocument, recordOf, } from '../discovery/discovery.js';
 import {} from '../discovery/discovery.schema.js';
 import { createHealthHandler } from '../health/health.js';
 import {} from '../log/log.js';
 import {} from '../manifest/manifest.schema.js';
+import {} from '../manifest/primitives.schema.js';
 import { errorHandler, notFound } from './errors.js';
 import {} from './part.types.js';
-// api-standards section 6: CORS * without credentials on /.well-known/ and /api/.
-const PUBLIC_CORS = {
+// api-standards section 6: CORS * without credentials on /.well-known/, /api/, /ui/ and /mcp.
+export const PUBLIC_CORS = {
     origin: '*',
     credentials: false,
     allowedHeaders: ['Authorization', 'Content-Type', 'agcid', 'traceparent', 'If-Match'],
     exposedHeaders: ['agcid', 'ETag', 'Retry-After', 'RateLimit', 'WWW-Authenticate'],
 };
-const BODY_LIMIT = '1mb';
+export const BODY_LIMIT = '1mb';
 const requestOrigin = (req) => `${req.protocol}://${req.get('host') ?? ''}`;
 const discoveryHandler = (options) => {
-    const images = options.ownImage ? { api: options.ownImage } : {};
+    const images = options.ownImage ? { [options.part]: options.ownImage } : {};
     const record = options.record ?? recordOf(options.pkg, options.build, images);
     return (req, res) => {
         res.json(discoveryDocument(record, options.origin ?? requestOrigin(req)));
@@ -27,20 +30,45 @@ const discoveryHandler = (options) => {
 };
 const healthHandler = (options) => createHealthHandler({
     extension: options.pkg.agentage.id,
-    part: 'api',
+    part: options.part,
     version: options.pkg.version,
     build: options.build,
+    checks: options.checks,
 });
-export const createApiApp = (options) => {
+// The kit app every part image runs: agcid, headers, /health, discovery, the part, the envelope.
+export const createPartApp = (options) => {
     const app = express();
     // The gateway calls parts over a private network; its X-Forwarded-Proto then sets req.protocol.
     app.set('trust proxy', 'loopback, linklocal, uniquelocal');
-    app.use(agcidMiddleware, helmet());
+    app.use(agcidMiddleware, helmet(options.helmet));
     app.get('/health', healthHandler(options));
-    app.use('/.well-known', cors(PUBLIC_CORS));
-    app.get('/.well-known/agentage-extension.json', discoveryHandler(options));
-    app.use('/api/v1', cors(PUBLIC_CORS), express.json({ limit: BODY_LIMIT }), options.router);
+    if (options.part !== 'worker') {
+        app.use('/.well-known', cors(PUBLIC_CORS));
+        app.get('/.well-known/agentage-extension.json', discoveryHandler(options));
+    }
+    options.mount(app);
     app.use(notFound);
     app.use(errorHandler(options.log));
     return app;
 };
+// The committed OpenAPI document, bare JSON and anonymous like discovery (api-standards section 1).
+const openapiHandler = (doc) => (_req, res) => void res.json(doc);
+// Before the body is read: each request checked for the access its OpenAPI operation declares.
+const routeGuard = (options) => async (req, _res, next) => {
+    if (!options.tokenCheck)
+        return next();
+    const access = routeAccess(options.openapi, req.method, `/api/v1${req.path}`);
+    setCaller(req, await options.tokenCheck(req.get('authorization'), access));
+    next();
+};
+export const createApiApp = (options) => createPartApp({
+    ...options,
+    part: 'api',
+    mount: (app) => {
+        app.use('/api/v1', cors(PUBLIC_CORS));
+        if (options.openapi)
+            app.get('/api/v1/openapi.json', openapiHandler(options.openapi));
+        const json = express.json({ limit: BODY_LIMIT });
+        app.use('/api/v1', routeGuard(options), json, options.router);
+    },
+});

package/dist/store/migrate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/store/migrate.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { createLog } from '../log/log.js';
+import { readManifest } from '../manifest/read-manifest.js';
+import { migrate } from './migrations.js';
+import { createStore } from './store.js';
+// A migration may rewrite a table: minutes, not a request's seconds; the job itself has no retry.
+const MIGRATE_TIMEOUTS = { connectMs: 10_000, statementMs: 300_000 };
+// The api image's migrate entry (`node dist/store/migrate.js` in /app), run as a job before a rollout.
+// Until the manifest is read the id is unknown; every line after it carries the extension.
+let log = createLog({ extension: 'unknown', part: 'migrate' });
+try {
+    const pkg = await readManifest(process.cwd());
+    log = createLog({ extension: pkg.agentage.id, part: 'migrate' });
+    const store = createStore(process.env, log, MIGRATE_TIMEOUTS);
+    const result = await migrate(store, process.cwd(), log);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    await store.end();
+}
+catch (err) {
+    log.error(err);
+    process.exit(1);
+}

package/dist/store/migrations.d.ts

@@ -0,0 +1,12 @@
+import { type Log } from '../log/log.js';
+import { type Store } from './store.types.js';
+export declare const SQL_FILE: RegExp;
+export interface MigrateResult {
+    migrations: number;
+    applied: number;
+    seeds: number;
+    seedsBefore: number;
+}
+export declare const sqlFiles: (dir: string) => Promise<string[]>;
+export declare const SEEDS_OWED = "seeds:owed";
+export declare const migrate: (store: Store, dir: string, log: Log) => Promise<MigrateResult>;

package/dist/store/migrations.js

@@ -0,0 +1,81 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { messageOf } from '../log/log.js';
+import {} from './store.types.js';
+export const SQL_FILE = /^[0-9]{3}-[a-z0-9-]+\.sql$/;
+// Filename order; anything else in the folder is refused, so a typo never silently skips a file.
+export const sqlFiles = async (dir) => {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const bad = names.filter((name) => !SQL_FILE.test(name));
+    if (bad.length > 0)
+        throw new Error(`${dir}: not NNN-name.sql: ${bad.join(', ')}`);
+    return names.sort();
+};
+const LEDGER = `create table if not exists _migrations (
+  name text primary key,
+  applied_at timestamptz not null default now()
+)`;
+const SEED = 'seed:';
+// Written by the first run on an empty store, removed once the seeds ran: a failed first run still seeds later.
+export const SEEDS_OWED = 'seeds:owed';
+// Tables other than the kit's own: a store holding any (a restored dump) never gets the seeds.
+const USER_TABLES = `select count(*)::int as n from information_schema.tables
+  where table_schema not in ('pg_catalog', 'information_schema')
+  and table_name not in ('_migrations', 'agentage_job_runs')`;
+const isEmpty = async (store, done) => done.size === 0 && ((await store.query(USER_TABLES)).rows[0]?.n ?? 0) === 0;
+const appliedNames = async (store) => {
+    await store.query(LEDGER);
+    const { rows } = await store.query('select name from _migrations');
+    return new Set(rows.map((row) => row.name));
+};
+// One string, one round trip: the file and its ledger row commit together or not at all.
+const applyFile = async (store, file, name) => {
+    const sql = await readFile(file, 'utf8');
+    try {
+        await store.query(`begin;\n${sql}\n;insert into _migrations (name) values ('${name}');\ncommit;`);
+    }
+    catch (err) {
+        await store.query('rollback').catch(() => undefined);
+        const kind = name.startsWith(SEED) ? 'seed' : 'migration';
+        throw new Error(`${kind} ${name.replace(SEED, '')} failed: ${messageOf(err)}`, { cause: err });
+    }
+};
+const applyAll = async (store, dir, prefix, done) => {
+    let count = 0;
+    for (const file of await sqlFiles(dir)) {
+        const name = `${prefix}${file}`;
+        if (done.has(name))
+            continue;
+        await applyFile(store, join(dir, file), name);
+        count += 1;
+    }
+    return count;
+};
+const seedOnce = async (store, dir, done) => {
+    const seeds = await applyAll(store, join(dir, 'seeds'), SEED, done);
+    await store.query(`delete from _migrations where name = '${SEEDS_OWED}'`);
+    return seeds;
+};
+// Migrations in order, each once; seeds once, only on a store with no ledger row and no user table.
+export const migrate = async (store, dir, log) => {
+    const done = await appliedNames(store);
+    const empty = await isEmpty(store, done);
+    if (empty)
+        await store.query(`insert into _migrations (name) values ('${SEEDS_OWED}')`);
+    const owed = empty || done.has(SEEDS_OWED);
+    const migrations = (await sqlFiles(join(dir, 'migrations'))).length;
+    const applied = await applyAll(store, join(dir, 'migrations'), '', done);
+    const seeds = owed ? await seedOnce(store, dir, done) : 0;
+    const seedsBefore = [...done].filter((name) => name.startsWith(SEED)).length;
+    const result = { migrations, applied, seeds, seedsBefore };
+    log.info('migrated', { ...result });
+    return result;
+};

package/dist/store/store.d.ts

@@ -0,0 +1,16 @@
+import { type HealthCheck } from '../health/health.js';
+import { type Log } from '../log/log.js';
+import { type Env } from '../runtime/build-info.js';
+import { type Store } from './store.types.js';
+export interface PoolStore extends Store {
+    end(): Promise<void>;
+}
+export interface StoreTimeouts {
+    connectMs: number;
+    statementMs: number;
+}
+export declare const PART_TIMEOUTS: StoreTimeouts;
+export declare const storeUrl: (env: Env, read?: (file: string) => string) => string | undefined;
+export declare const isOutage: (err: unknown) => boolean;
+export declare const createStore: (env: Env, log: Log, timeouts?: StoreTimeouts) => PoolStore;
+export declare const storeCheck: (store: Store) => HealthCheck;

package/dist/store/store.js

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import pg from 'pg';
+import { fail } from '../envelope/envelope.js';
+import {} from '../health/health.js';
+import { messageOf } from '../log/log.js';
+import {} from '../runtime/build-info.js';
+import {} from './store.types.js';
+// A part's query is bounded by the server and, if the network itself hangs, by the client too.
+export const PART_TIMEOUTS = { connectMs: 5_000, statementMs: 10_000 };
+const CLIENT_SLACK_MS = 2_000;
+// The host sets the connection: AGENTAGE_STORE_URL, a secret file named by _FILE, else libpq PG* env.
+export const storeUrl = (env, read = (file) => readFileSync(file, 'utf8')) => {
+    const file = env['AGENTAGE_STORE_URL_FILE'];
+    if (file)
+        return read(file).trim();
+    return env['AGENTAGE_STORE_URL'] || undefined;
+};
+// Connection classes 08 and 57P01-03 (shutdown), 57014 (statement timeout), socket errors, pg's own timeouts.
+const OUTAGE_SQLSTATE = /^(08|57P0[1-3]$|57014$)/;
+const OUTAGE_SOCKET = /^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|EPIPE)$/;
+const OUTAGE_MESSAGE = /timeout exceeded when trying to connect|Query read timeout|Connection terminated/;
+export const isOutage = (err) => {
+    const code = err?.code;
+    if (typeof code === 'string' && (OUTAGE_SQLSTATE.test(code) || OUTAGE_SOCKET.test(code)))
+        return true;
+    return OUTAGE_MESSAGE.test(messageOf(err));
+};
+// A store that cannot answer is UNAVAILABLE (503, Retry-After), never an INTERNAL 500; no retry here.
+const guarded = (pool, log) => async function query(text, params) {
+    try {
+        return await pool.query(text, params);
+    }
+    catch (err) {
+        if (!isOutage(err))
+            throw err;
+        log.warn('store unavailable', { reason: messageOf(err) });
+        throw fail('UNAVAILABLE', 'The store is unavailable');
+    }
+};
+export const createStore = (env, log, timeouts = PART_TIMEOUTS) => {
+    const pool = new pg.Pool({
+        connectionString: storeUrl(env),
+        max: 5,
+        idleTimeoutMillis: 30_000,
+        connectionTimeoutMillis: timeouts.connectMs,
+        statement_timeout: timeouts.statementMs,
+        query_timeout: timeouts.statementMs + CLIENT_SLACK_MS,
+    });
+    pool.on('error', (err) => log.error(err, { store: 'pool' }));
+    return { query: guarded(pool, log), end: () => pool.end() };
+};
+export const storeCheck = (store) => async () => {
+    await store.query('select 1');
+    return 'ok';
+};

package/dist/store/store.types.d.ts

@@ -0,0 +1,7 @@
+export type Row = Record<string, unknown>;
+export interface QueryResult<R extends Row = Row> {
+    rows: R[];
+}
+export interface Store {
+    query<R extends Row = Row>(text: string, params?: unknown[]): Promise<QueryResult<R>>;
+}

package/dist/store/store.types.js

@@ -0,0 +1 @@
+export {};

package/dist/store/test-store.d.ts

@@ -0,0 +1,5 @@
+import { type Store } from './store.types.js';
+export interface TestStore extends Store {
+    close(): Promise<void>;
+}
+export declare const createTestStore: (prepare: (store: Store) => Promise<unknown>) => TestStore;

package/dist/store/test-store.js

@@ -0,0 +1,39 @@
+import {} from './store.types.js';
+const open = async () => {
+    try {
+        const { PGlite } = (await import('@electric-sql/pglite'));
+        return new PGlite();
+    }
+    catch {
+        throw new Error('a test store needs @electric-sql/pglite: npm install -D @electric-sql/pglite');
+    }
+};
+// Like pg: a parameterless query may hold several statements (migrations), the last one answers.
+const bound = (db) => ({
+    query: async (text, params) => {
+        if (params && params.length > 0)
+            return db.query(text, params);
+        const results = await db.exec(text);
+        return { rows: (results.at(-1)?.rows ?? []) };
+    },
+});
+// In-process Postgres (WASM): a throwaway store of the same kind, prepared once on first use.
+export const createTestStore = (prepare) => {
+    let ready;
+    const start = async () => {
+        const db = await open();
+        const store = bound(db);
+        await prepare(store);
+        return { ...store, db };
+    };
+    return {
+        query: async (text, params) => {
+            ready ??= start();
+            return (await ready).query(text, params);
+        },
+        close: async () => {
+            if (ready)
+                await (await ready).db.close();
+        },
+    };
+};

package/dist/testing/test-server.d.ts

@@ -1,12 +1,18 @@
 import { type PartContext } from '../context/context.js';
+import { type McpContext } from '../mcp/tools.js';
 import { type ApiCreate } from '../server/part.types.js';
 export interface TestServerOptions<C extends PartContext> {
     create: ApiCreate<C>;
     ctx?: C;
 }
+export interface TestMcpOptions {
+    create: (ctx: McpContext) => unknown;
+    ctx?: PartContext;
+}
 export interface TestServer {
     url: string;
     fetch(path: string, init?: RequestInit): Promise<Response>;
     close(): Promise<void>;
 }
 export declare const startTestServer: <C extends PartContext = PartContext>(options: TestServerOptions<C>) => Promise<TestServer>;
+export declare const startTestMcp: (options: TestMcpOptions) => Promise<TestServer>;