@agentage/extension 0.1.2 → 0.2.0

package/dist/runtime/run-part.js

@@ -1,23 +1,18 @@
-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 '../health/health.js';
 import { createLog } from '../log/log.js';
-import { entryOf } from '../manifest/parts.js';
 import {} from '../manifest/manifest.schema.js';
+import { imageParts, normalizeParts } 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 { 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';
+export { createOf } 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 +20,51 @@ 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;
 };
-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`);
+// 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' && normalizeParts(pkg.agentage.parts).store === 'postgres'
+    ? createStore(env, log)
+    : undefined;
+const inputFor = async (options, pkg, part, log) => {
     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 store = storeFor(pkg, part, env, log);
+    const settings = settingsFromEnv(pkg, env, log);
+    const ctxOrigin = origin ?? `http://127.0.0.1:${portFromEnv(env)}`;
+    const ctxPart = (part === 'ui' ? 'pages' : part);
+    const ctx = createContext({
+        pkg,
+        part: ctxPart,
+        origin: ctxOrigin,
+        commit: build.commit,
+        log,
+        settings,
+        store,
+    });
     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 checks = store ? { store: storeCheck(store) } : {};
+    const base = { pkg, build, log, record, origin, ownImage: env['AGENTAGE_IMAGE'], checks };
+    return {
+        dir: options.dir,
+        pkg,
+        ctx,
+        base,
+        importModule: options.importModule,
+    };
+};
+export const runPart = async (options) => {
+    const pkg = await readManifest(options.dir);
+    const part = partOf(pkg, options.part);
+    const log = createLog({ extension: pkg.agentage.id, part });
+    const { app, stop } = await RUNNERS[part](await inputFor(options, pkg, part, log));
+    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,32 @@
+import { type CorsOptions } from 'cors';
 import { type Express } from 'express';
+import { type HelmetOptions } from 'helmet';
 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>;
+}
+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,26 @@
 import cors, {} from 'cors';
 import express, {} from 'express';
-import helmet from 'helmet';
+import helmet, {} from 'helmet';
 import { agcidMiddleware } from '../agcid/scope.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 +28,36 @@ 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);
+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));
+        app.use('/api/v1', express.json({ limit: BODY_LIMIT }), 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,18 @@
+#!/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';
+// The api image's migrate entry (`node dist/store/migrate.js` in /app), run as a job before a rollout.
+const log = createLog({ extension: 'unknown', part: 'migrate' });
+try {
+    const pkg = await readManifest(process.cwd());
+    const store = createStore(process.env, log);
+    const result = await migrate(store, process.cwd(), createLog({ extension: pkg.agentage.id, part: 'migrate' }));
+    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,10 @@
+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;
+}
+export declare const sqlFiles: (dir: string) => Promise<string[]>;
+export declare const migrate: (store: Store, dir: string, log: Log) => Promise<MigrateResult>;

package/dist/store/migrations.js

@@ -0,0 +1,55 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import {} 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 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');
+    await store.query(`begin;\n${sql}\n;insert into _migrations (name) values ('${name}');\ncommit;`);
+};
+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;
+};
+// Migrations in order, each once; seeds once, only when the store had no ledger row before.
+export const migrate = async (store, dir, log) => {
+    const done = await appliedNames(store);
+    const migrations = (await sqlFiles(join(dir, 'migrations'))).length;
+    const applied = await applyAll(store, join(dir, 'migrations'), '', done);
+    const seeds = done.size === 0 ? await applyAll(store, join(dir, 'seeds'), 'seed:', done) : 0;
+    log.info('migrated', { migrations, applied, seeds });
+    return { migrations, applied, seeds };
+};

package/dist/store/store.d.ts

@@ -0,0 +1,10 @@
+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 declare const storeUrl: (env: Env, read?: (file: string) => string) => string | undefined;
+export declare const createStore: (env: Env, log: Log) => PoolStore;
+export declare const storeCheck: (store: Store) => HealthCheck;

package/dist/store/store.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import pg from 'pg';
+import {} from '../health/health.js';
+import {} from '../log/log.js';
+import {} from '../runtime/build-info.js';
+import {} from './store.types.js';
+// 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;
+};
+export const createStore = (env, log) => {
+    const pool = new pg.Pool({ connectionString: storeUrl(env), max: 5, idleTimeoutMillis: 30_000 });
+    pool.on('error', (err) => log.error(err, { store: 'pool' }));
+    return {
+        query: async (text, params) => pool.query(text, params),
+        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>;

package/dist/testing/test-server.js

@@ -1,21 +1,21 @@
 import {} from 'node:net';
-import { createTestContext } from '../context/context.js';
+import {} from 'express';
+import {} from '../context/context.js';
+import { createTestContext } from '../context/test-context.js';
 import {} from '../manifest/manifest.schema.js';
+import { createMcpApp } from '../mcp/mcp-app.js';
+import { createToolRegistry } from '../mcp/tools.js';
 import { createApiApp } from '../server/app.js';
 import {} from '../server/part.types.js';
 import { listen } from '../server/serve.js';
 const TEST_BUILD = { commit: '0'.repeat(40), buildTime: '2026-01-01T00:00:00Z' };
-const testPackage = (ctx) => ({
+const testPackage = (ctx, parts) => ({
     name: `@agentage/extension-${ctx.extension.id}`,
     version: ctx.extension.version,
-    engines: { agentage: '^0.1.0' },
-    agentage: { id: ctx.extension.id, parts: { api: true } },
+    engines: { agentage: '^0.2.0' },
+    agentage: { id: ctx.extension.id, parts },
 });
-// Runs an api part's create(ctx) inside the kit's real app on 127.0.0.1, port chosen by the OS.
-export const startTestServer = async (options) => {
-    const ctx = options.ctx ?? createTestContext();
-    const router = await options.create(ctx);
-    const app = createApiApp({ pkg: testPackage(ctx), build: TEST_BUILD, router, log: ctx.log });
+const startOn = async (app) => {
     const server = await listen(app, 0, '127.0.0.1');
     const url = `http://127.0.0.1:${server.address().port}`;
     return {
@@ -24,3 +24,25 @@ export const startTestServer = async (options) => {
         close: () => new Promise((resolve) => server.close(() => resolve())),
     };
 };
+// Runs an api part's create(ctx) inside the kit's real app on 127.0.0.1, port chosen by the OS.
+export const startTestServer = async (options) => {
+    const ctx = options.ctx ?? createTestContext();
+    const router = await options.create(ctx);
+    const pkg = testPackage(ctx, { api: true });
+    return startOn(createApiApp({ pkg, build: TEST_BUILD, router, log: ctx.log }));
+};
+// Runs an mcp part's create(ctx) inside the kit's real /mcp app: tools named {id}__{name}.
+export const startTestMcp = async (options) => {
+    const ctx = options.ctx ?? createTestContext();
+    const registry = createToolRegistry();
+    await options.create({ ...ctx, tool: registry.tool });
+    const pkg = testPackage(ctx, { mcp: true });
+    const app = createMcpApp({
+        pkg,
+        build: TEST_BUILD,
+        log: ctx.log,
+        tools: registry.tools,
+        listing: 'open',
+    });
+    return startOn(app);
+};

package/dist/tool/build.d.ts

@@ -1,8 +1,11 @@
+import { type BuildInfo } from '../discovery/discovery.js';
+import { type ExtensionRecord } from '../discovery/discovery.schema.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
 import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type Env } from '../runtime/build-info.js';
 import { type Docker } from './docker.js';
 import { type Run } from './exec.js';
+export declare const DEFAULT_REGISTRY = "ghcr.io/agentage";
 export interface BuildOptions {
     dir?: string;
     push?: boolean;
@@ -29,4 +32,7 @@ export interface BuildResult {
     recordFile?: string;
 }
 export declare const imageTag: (registry: string, pkg: ExtensionPackage, part: ImagePartKind) => string;
+export declare const recordFor: (dir: string, pkg: ExtensionPackage, info: BuildInfo, images: BuiltImage[]) => Promise<ExtensionRecord>;
+declare const writeRecord: (dir: string, record: ExtensionRecord, file?: string) => Promise<string>;
 export declare const build: (options?: BuildOptions, deps?: BuildDeps) => Promise<BuildResult>;
+export { writeRecord };

package/dist/tool/build.js

@@ -1,6 +1,7 @@
 import { rm, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { recordOf, validateRecord } from '../discovery/discovery.js';
+import {} from '../discovery/discovery.schema.js';
 import {} from '../manifest/manifest.schema.js';
 import { imageParts } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
@@ -10,18 +11,10 @@ import { resolveBuildInfo } from './build-info.js';
 import { createDocker } from './docker.js';
 import { mustRun, runCommand } from './exec.js';
 import { labelsOf } from './labels.js';
+import { recordExtras } from './record-extras.js';
 import { RECORD_FILE, stageContext } from './stage.js';
-const DEFAULT_REGISTRY = 'ghcr.io/agentage';
-const SUPPORTED_PARTS = ['api'];
+export const DEFAULT_REGISTRY = 'ghcr.io/agentage';
 export const imageTag = (registry, pkg, part) => `${registry}/${pkg.agentage.id}-${part}:${pkg.version}`;
-const partsToBuild = (pkg) => {
-    const parts = imageParts(pkg);
-    const unsupported = parts.filter((part) => !SUPPORTED_PARTS.includes(part));
-    if (unsupported.length > 0) {
-        throw new Error(`@agentage/extension 0.1 builds the api part only, not: ${unsupported.join(', ')}`);
-    }
-    return parts;
-};
 const compile = async (dir, pkg, run) => {
     const scripts = pkg.scripts;
     if (typeof scripts?.['build'] === 'string')
@@ -35,12 +28,8 @@ const buildImage = async (job, docker, tmpRoot) => {
             BUILD_TIME: job.info.buildTime,
             IMAGE: job.tag,
         };
-        await docker.build({
-            context,
-            tag: job.tag,
-            buildArgs,
-            labels: labelsOf(job.pkg, job.part, job.info),
-        });
+        const labels = labelsOf(job.pkg, job.part, job.info);
+        await docker.build({ context, tag: job.tag, buildArgs, labels });
     }
     finally {
         await rm(context, { recursive: true, force: true });
@@ -51,32 +40,36 @@ const pushImage = async (job, docker) => {
     const repository = job.tag.slice(0, job.tag.lastIndexOf(':'));
     return { part: job.part, tag: job.tag, digest, image: `${repository}@${digest}` };
 };
-const writeRecord = async (dir, pkg, info, images) => {
+// The record from the code and the images by digest; `up` writes the same shape from local digests.
+export const recordFor = async (dir, pkg, info, images) => {
     const byPart = Object.fromEntries(images.map((built) => [built.part, built.image]));
-    const record = validateRecord(recordOf(pkg, info, byPart));
-    const file = join(dir, 'dist', RECORD_FILE);
+    return validateRecord(recordOf(pkg, info, byPart, await recordExtras(dir, pkg)));
+};
+const writeRecord = async (dir, record, file = join(dir, 'dist', RECORD_FILE)) => {
     await writeFile(file, `${JSON.stringify(record, null, 2)}\n`);
     return file;
 };
-const buildParts = async (base, parts, options, deps) => {
+const buildParts = async (base, options, deps) => {
     const docker = deps.docker ?? createDocker(deps.run);
     const registry = options.registry ?? DEFAULT_REGISTRY;
     const images = [];
-    for (const part of parts) {
+    for (const part of imageParts(base.pkg)) {
         const job = { ...base, part, tag: imageTag(registry, base.pkg, part) };
         await buildImage(job, docker, deps.tmpRoot);
         images.push(options.push ? await pushImage(job, docker) : { part, tag: job.tag });
     }
     return images;
 };
+// Validate, compile, one image per part from the kit recipe; --push pushes and writes the record.
 export const build = async (options = {}, deps = { run: runCommand }) => {
     const dir = resolve(options.dir ?? '.');
     const pkg = await readManifest(dir);
-    const parts = partsToBuild(pkg);
     const info = await resolveBuildInfo(dir, options.env ?? process.env, deps.run);
     await compile(dir, pkg, deps.run);
-    const images = await buildParts({ dir, pkg, info }, parts, options, deps);
-    const recordFile = options.push ? await writeRecord(dir, pkg, info, images) : undefined;
+    const images = await buildParts({ dir, pkg, info }, options, deps);
     const result = { id: pkg.agentage.id, version: pkg.version, ...info, images };
-    return recordFile ? { ...result, recordFile } : result;
+    if (!options.push)
+        return result;
+    return { ...result, recordFile: await writeRecord(dir, await recordFor(dir, pkg, info, images)) };
 };
+export { writeRecord };

package/dist/tool/exec.d.ts

@@ -1,11 +1,15 @@
 export interface RunOptions {
     cwd?: string;
     echo?: boolean;
+    quiet?: boolean;
+    env?: Record<string, string | undefined>;
 }
 export interface RunResult {
     code: number;
     stdout: string;
+    stderr?: string;
 }
 export type Run = (command: string, args: string[], options?: RunOptions) => Promise<RunResult>;
 export declare const runCommand: Run;
 export declare const mustRun: (run: Run, command: string, args: string[], options?: RunOptions) => Promise<string>;
+export declare const quietly: (run: Run) => Run;

package/dist/tool/exec.js

@@ -1,20 +1,32 @@
 import { spawn } from 'node:child_process';
+import {} from 'node:stream';
 // stdout is captured (and echoed to stderr with `echo`); stderr streams through as progress.
 export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
-    const child = spawn(command, args, { cwd: options.cwd, stdio: ['ignore', 'pipe', 'inherit'] });
+    const stdio = ['ignore', 'pipe', options.quiet ? 'pipe' : 'inherit'];
+    const env = options.env ? { ...process.env, ...options.env } : process.env;
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        stdio: [...stdio],
+        env,
+    });
     let stdout = '';
+    let stderr = '';
     child.stdout.on('data', (chunk) => {
         stdout += chunk.toString();
         if (options.echo)
             process.stderr.write(chunk);
     });
+    child.stderr?.on('data', (chunk) => void (stderr += chunk.toString()));
     child.on('error', (err) => reject(err.code === 'ENOENT' ? new Error(`${command} is not installed or not on PATH`) : err));
-    child.on('close', (code) => resolve({ code: code ?? 1, stdout }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, ...(options.quiet ? { stderr } : {}) }));
 });
+const tail = (text) => text ? `\n${text.trim().split('\n').slice(-15).join('\n')}` : '';
 export const mustRun = async (run, command, args, options) => {
     const result = await run(command, args, options);
     if (result.code !== 0) {
-        throw new Error(`${command} ${args[0] ?? ''} failed with exit code ${result.code}`);
+        throw new Error(`${command} ${args[0] ?? ''} failed with exit code ${result.code}${tail(result.stderr)}`);
     }
     return result.stdout;
 };
+// Every command a runner starts runs quiet: what `up` and `down` print are their own lines.
+export const quietly = (run) => (command, args, options) => run(command, args, { ...options, quiet: true });

package/dist/tool/index.d.ts

@@ -1,2 +1,10 @@
+export { checkCli } from '../command/check-cli.js';
+export { runCommand, type RunCommandOptions } from '../command/run-command.js';
+export { type ExtensionPackage, type CommandSpec } from '../manifest/manifest.schema.js';
+export { readManifest, validateManifest } from '../manifest/read-manifest.js';
 export { build, type BuildDeps, type BuildOptions, type BuildResult, type BuiltImage, } from './build.js';
 export { buildLines } from './format.js';
+export { KIT_VERSION } from './kit-version.js';
+export { down, type DownOptions, type DownResult } from './up/down.js';
+export { token, type TokenOptions } from './up/token.js';
+export { up, type UpDeps, type UpOptions, type UpResult } from './up/up.js';