@agentage/extension 0.1.1 → 0.2.0

package/dist/tool/main.d.ts

@@ -1,8 +1,13 @@
 import { type BuildOptions, type BuildResult } from './build.js';
+import { type DownOptions } from './up/down.js';
+import { type TokenOptions } from './up/token.js';
+import { type UpOptions } from './up/up.js';
 export interface MainDeps {
     build: (options: BuildOptions) => Promise<BuildResult>;
+    up: (options: UpOptions) => Promise<unknown>;
+    down: (options: DownOptions) => Promise<unknown>;
+    token: (options: TokenOptions) => Promise<string>;
     out: (line: string) => void;
     err: (line: string) => void;
 }
-export declare const USAGE = "usage: agentage-extension build [--push] [--dir <path>] [--registry <host/owner>]\n\n  build      one image per server part from the kit recipe\n  --push     push the images and write dist/agentage-extension.json with their digests\n  --dir      the extension package folder (default: the current folder)\n  --registry image registry and owner (default: ghcr.io/agentage)";
 export declare const main: (argv: string[], deps?: MainDeps) => Promise<number>;

package/dist/tool/main.js

@@ -1,28 +1,64 @@
 import { parseArgs } from 'node:util';
 import { build } from './build.js';
 import { buildLines } from './format.js';
-export const USAGE = `usage: agentage-extension build [--push] [--dir <path>] [--registry <host/owner>]
+import { down } from './up/down.js';
+import { token } from './up/token.js';
+import { up } from './up/up.js';
+const USAGE = `usage: agentage-extension <build|up|down|token> [options]
 
-  build      one image per server part from the kit recipe
-  --push     push the images and write dist/agentage-extension.json with their digests
-  --dir      the extension package folder (default: the current folder)
-  --registry image registry and owner (default: ghcr.io/agentage)`;
+  build      one image per part from the kit recipe
+    --push     push the images and write dist/agentage-extension.json with their digests
+    --registry image registry and owner (default: ghcr.io/agentage)
+  up         the release images on Docker: store, dev issuer, gateway on localhost:4280
+  down       remove what up started; --keep-data keeps the store volume
+  token      a dev token: --scope <id>:<verb> [--issuer <url>]
+  --dir      the extension package folder (default: the current folder)`;
 const defaultDeps = {
     build: (options) => build(options),
+    up: (options) => up(options),
+    down: (options) => down(options),
+    token: (options) => token(options),
     out: (line) => void process.stdout.write(`${line}\n`),
     err: (line) => void process.stderr.write(`${line}\n`),
 };
-const parse = (argv) => parseArgs({
-    args: argv,
-    allowPositionals: true,
-    options: {
-        push: { type: 'boolean' },
-        dir: { type: 'string' },
-        registry: { type: 'string' },
-        help: { type: 'boolean', short: 'h' },
+const OPTIONS = {
+    push: { type: 'boolean' },
+    dir: { type: 'string' },
+    registry: { type: 'string' },
+    'keep-data': { type: 'boolean' },
+    scope: { type: 'string' },
+    issuer: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+};
+const parse = (argv) => parseArgs({ args: argv, allowPositionals: true, options: OPTIONS });
+class UsageError extends Error {
+}
+const COMMANDS = {
+    build: async (v, deps) => {
+        for (const line of buildLines(await deps.build({ push: v.push, dir: v.dir, registry: v.registry })))
+            deps.out(line);
     },
-});
-// Exit codes: 0 ok, 1 the build failed, 2 usage.
+    up: async (v, deps) => void (await deps.up({ dir: v.dir, onLine: deps.out })),
+    down: async (v, deps) => void (await deps.down({ dir: v.dir, keepData: v['keep-data'], onLine: deps.out })),
+    token: async (v, deps) => {
+        if (!v.scope)
+            throw new UsageError('token needs --scope <id>:<verb>');
+        deps.out(await deps.token({ scope: v.scope, issuer: v.issuer }));
+    },
+};
+const runOne = async (name, values, deps) => {
+    try {
+        await COMMANDS[name]?.(values, deps);
+        return 0;
+    }
+    catch (err) {
+        deps.err(err instanceof UsageError
+            ? `${err.message}\n${USAGE}`
+            : `${name} failed: ${err.message}`);
+        return err instanceof UsageError ? 2 : 1;
+    }
+};
+// Exit codes: 0 ok, 1 the step failed, 2 usage.
 export const main = async (argv, deps = defaultDeps) => {
     let parsed;
     try {
@@ -33,22 +69,14 @@ export const main = async (argv, deps = defaultDeps) => {
         return 2;
     }
     const { positionals, values } = parsed;
-    if (values.help)
-        return (deps.out(USAGE), 0);
-    if (positionals[0] !== 'build' || positionals.length !== 1)
-        return (deps.err(USAGE), 2);
-    try {
-        const result = await deps.build({
-            push: values.push,
-            dir: values.dir,
-            registry: values.registry,
-        });
-        for (const line of buildLines(result))
-            deps.out(line);
+    if (values.help) {
+        deps.out(USAGE);
         return 0;
     }
-    catch (err) {
-        deps.err(`build failed: ${err.message}`);
-        return 1;
+    const name = positionals[0] ?? '';
+    if (!(name in COMMANDS) || positionals.length !== 1) {
+        deps.err(USAGE);
+        return 2;
     }
+    return runOne(name, values, deps);
 };

package/dist/tool/recipe.d.ts

@@ -1,3 +1,2 @@
 import { type ImagePartKind } from '../manifest/primitives.schema.js';
-export declare const PART_PORT = 3000;
 export declare const serverPartRecipe: (part: ImagePartKind) => string;

package/dist/tool/recipe.js

@@ -1,9 +1,9 @@
 import {} from '../manifest/primitives.schema.js';
-export const PART_PORT = 3000;
+const PART_PORT = 3000;
+// 503 passes: a restart cannot fix a dependency outage, so only a dead or 404 part is unhealthy.
 const HEALTH_PROBE = `fetch('http://127.0.0.1:${PART_PORT}/health')` +
     '.then((r) => process.exit(r.status === 200 || r.status === 503 ? 0 : 1), () => process.exit(1))';
-// The one recipe for a Node server part; the staged context holds deps/ (npm ci) and app/ (code).
-export const serverPartRecipe = (part) => [
+const RECIPE = [
     '# syntax=docker/dockerfile:1',
     '# Generated by @agentage/extension build. Extension authors never write a Dockerfile.',
     'FROM node:26-alpine AS deps',
@@ -27,6 +27,10 @@ export const serverPartRecipe = (part) => [
     'USER node',
     `EXPOSE ${PART_PORT}`,
     `HEALTHCHECK --interval=10s --timeout=3s --start-period=15s --retries=3 CMD ["node", "-e", "${HEALTH_PROBE}"]`,
+];
+// The one recipe for a Node server part; the staged context holds deps/ (npm ci) and app/ (code).
+export const serverPartRecipe = (part) => [
+    ...RECIPE,
     `CMD ["node", "node_modules/@agentage/extension/dist/runtime/main.js", "${part}"]`,
     '',
 ].join('\n');

package/dist/tool/record-extras.d.ts

@@ -0,0 +1,4 @@
+import { type RecordExtras } from '../discovery/discovery.js';
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+export declare const toolNames: (dir: string, pkg: ExtensionPackage) => Promise<string[]>;
+export declare const recordExtras: (dir: string, pkg: ExtensionPackage) => Promise<RecordExtras>;

package/dist/tool/record-extras.js

@@ -0,0 +1,60 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { createContext } from '../context/context.js';
+import {} from '../discovery/discovery.js';
+import { OPENAPI_PATH, readOpenapi } from '../discovery/openapi.js';
+import { createLog } from '../log/log.js';
+import { readJsonIfExists } from '../manifest/read-manifest.js';
+import {} from '../manifest/manifest.schema.js';
+import { entryOf, normalizeParts } from '../manifest/parts.js';
+import { createToolRegistry, prefixed } from '../mcp/tools.js';
+import { sqlFiles } from '../store/migrations.js';
+import {} from '../store/store.types.js';
+const WidgetsSchema = z
+    .array(z.strictObject({ name: z.string(), element: z.string(), module: z.string() }))
+    .min(1);
+const noStore = {
+    query: async () => {
+        throw new Error('the store is not open while the build lists tools');
+    },
+};
+const silent = createLog({ extension: 'build', part: 'mcp' }, () => undefined);
+// The tool names the mcp part registers, read by running its create(ctx) with a recording ctx.
+export const toolNames = async (dir, pkg) => {
+    const registry = createToolRegistry();
+    const base = createContext({
+        pkg,
+        part: 'mcp',
+        origin: 'http://127.0.0.1',
+        commit: '0'.repeat(40),
+        log: silent,
+        store: noStore,
+    });
+    const mod = (await import(pathToFileURL(join(dir, entryOf(pkg, 'mcp'))).href));
+    if (typeof mod.create !== 'function')
+        throw new Error('the mcp entry does not export create(ctx)');
+    await mod.create({ ...base, tool: registry.tool });
+    return registry.tools.map((tool) => prefixed(pkg.agentage.id, tool.name));
+};
+const widgetsOf = async (dir) => {
+    const value = await readJsonIfExists(join(dir, 'dist', 'ui', 'widgets.json'));
+    return value === undefined ? undefined : WidgetsSchema.parse(value);
+};
+// What the code serves, for the record: tools, widgets and the migration count.
+export const recordExtras = async (dir, pkg) => {
+    const { code, store } = normalizeParts(pkg.agentage.parts);
+    const extras = {};
+    if (code.mcp) {
+        const tools = await toolNames(dir, pkg);
+        if (tools.length > 0)
+            extras.tools = tools;
+    }
+    if (code.ui)
+        extras.widgets = await widgetsOf(dir);
+    if (code.api && (await readOpenapi(dir)))
+        extras.openapi = OPENAPI_PATH;
+    if (store === 'postgres')
+        extras.migrations = (await sqlFiles(join(dir, 'migrations'))).length;
+    return extras;
+};

package/dist/tool/stage.d.ts

@@ -1,5 +1,8 @@
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
 import { type ImagePartKind } from '../manifest/primitives.schema.js';
 export declare const RECORD_FILE = "agentage-extension.json";
+export declare const MIGRATE_SHIM = "// Generated by @agentage/extension build.\nimport '@agentage/extension/migrate';\n";
 export declare const localTarballs: (pkg: ExtensionPackage) => string[];
+export declare const appPaths: (dir: string, pkg: ExtensionPackage, part: ImagePartKind) => Promise<string[]>;
+export declare const assertBuilt: (dir: string, pkg: ExtensionPackage, part: ImagePartKind) => Promise<void>;
 export declare const stageContext: (dir: string, pkg: ExtensionPackage, part: ImagePartKind, tmpRoot?: string) => Promise<string>;

package/dist/tool/stage.js

@@ -1,10 +1,14 @@
 import { access, cp, mkdir, mkdtemp, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { basename, dirname, isAbsolute, join, normalize } from 'node:path';
+import { dirname, isAbsolute, join, normalize, sep } from 'node:path';
 import {} from '../manifest/manifest.schema.js';
+import { entryOf, normalizeParts } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
+import { OPENAPI_FILE } from '../discovery/openapi.js';
 import { serverPartRecipe } from './recipe.js';
 export const RECORD_FILE = 'agentage-extension.json';
+// The api image's migrate entry: `node dist/store/migrate.js` in /app runs the kit's migration runner.
+export const MIGRATE_SHIM = "// Generated by @agentage/extension build.\nimport '@agentage/extension/migrate';\n";
 const dependencySpecs = (pkg) => {
     const deps = pkg.dependencies;
     if (typeof deps !== 'object' || deps === null)
@@ -21,32 +25,61 @@ export const localTarballs = (pkg) => dependencySpecs(pkg)
     }
     return path;
 });
+const exists = (path) => access(path).then(() => true, () => false);
 const copyInto = async (from, to) => {
     await mkdir(dirname(to), { recursive: true });
     await cp(from, to, { recursive: true });
 };
 const copyDeps = async (dir, root, pkg) => {
-    await access(join(dir, 'package-lock.json')).catch(() => {
+    if (!(await exists(join(dir, 'package-lock.json')))) {
         throw new Error('package-lock.json is missing: the image installs with npm ci');
-    });
+    }
     await copyInto(join(dir, 'package.json'), join(root, 'deps', 'package.json'));
     await copyInto(join(dir, 'package-lock.json'), join(root, 'deps', 'package-lock.json'));
     for (const path of localTarballs(pkg))
         await copyInto(join(dir, path), join(root, 'deps', path));
 };
-const copyApp = async (dir, root) => {
-    await copyInto(join(dir, 'package.json'), join(root, 'app', 'package.json'));
-    await mkdir(join(root, 'app'), { recursive: true });
-    await cp(join(dir, 'dist'), join(root, 'app', 'dist'), {
-        recursive: true,
-        filter: (source) => basename(source) !== RECORD_FILE,
-    });
+// What a part image carries: its own dist/{part}, the shared dist/lib, and for api the store files.
+export const appPaths = async (dir, pkg, part) => {
+    const paths = ['package.json', join('dist', part)];
+    if (part === 'api' && (await exists(join(dir, OPENAPI_FILE))))
+        paths.push(OPENAPI_FILE);
+    if (await exists(join(dir, 'dist', 'lib')))
+        paths.push(join('dist', 'lib'));
+    const postgres = normalizeParts(pkg.agentage.parts).store === 'postgres';
+    if (part === 'api' && postgres) {
+        for (const folder of ['migrations', 'seeds'])
+            if (await exists(join(dir, folder)))
+                paths.push(folder);
+    }
+    return paths;
+};
+const copyApp = async (dir, root, pkg, part) => {
+    for (const path of await appPaths(dir, pkg, part))
+        await copyInto(join(dir, path), join(root, 'app', path));
+    if (part === 'api' && normalizeParts(pkg.agentage.parts).store === 'postgres') {
+        await mkdir(join(root, 'app', 'dist', 'store'), { recursive: true });
+        await writeFile(join(root, 'app', 'dist', 'store', 'migrate.js'), MIGRATE_SHIM);
+    }
+};
+// ui is a bundle, not an entry: the widget bundler writes dist/ui/widgets.json beside it.
+const builtFile = (pkg, part) => normalize(part === 'ui' ? './dist/ui/widgets.json' : entryOf(pkg, part));
+// The image carries dist/ only, so an entry outside it, or never built, would not start.
+export const assertBuilt = async (dir, pkg, part) => {
+    const file = builtFile(pkg, part);
+    if (!file.startsWith(`dist${sep}${part}${sep}`)) {
+        throw new Error(`the ${part} entry ${file} is not in dist/${part}/`);
+    }
+    if (!(await exists(join(dir, file)))) {
+        throw new Error(`${file} not found: the package build must write the ${part} part there`);
+    }
 };
-// A clean build context per part: only the manifest, the lockfile, local tarballs and dist/.
+// A clean build context per part: the manifest, the lockfile, local tarballs and the part's files.
 export const stageContext = async (dir, pkg, part, tmpRoot = tmpdir()) => {
+    await assertBuilt(dir, pkg, part);
     const root = await mkdtemp(join(tmpRoot, `agentage-${pkg.agentage.id}-${part}-`));
     await copyDeps(dir, root, pkg);
-    await copyApp(dir, root);
+    await copyApp(dir, root, pkg, part);
     await writeFile(join(root, 'Dockerfile'), serverPartRecipe(part));
     return root;
 };

package/dist/tool/up/compose-run.d.ts

@@ -0,0 +1,14 @@
+import { type Run } from '../exec.js';
+export interface ComposeTarget {
+    file?: string;
+    project: string;
+}
+export interface ServiceState {
+    service: string;
+    state: string;
+    health: string;
+    exitCode: number;
+}
+export declare const compose: (run: Run, target: ComposeTarget, args: string[]) => Promise<string>;
+export declare const parsePs: (stdout: string) => ServiceState[];
+export declare const states: (run: Run, target: ComposeTarget) => Promise<ServiceState[]>;

package/dist/tool/up/compose-run.js

@@ -0,0 +1,24 @@
+import { mustRun } from '../exec.js';
+export const compose = (run, target, args) => mustRun(run, 'docker', [
+    'compose',
+    ...(target.file ? ['-f', target.file] : []),
+    '-p',
+    target.project,
+    ...args,
+]);
+// `compose ps --format json` prints one object per line (older releases: one array).
+export const parsePs = (stdout) => {
+    const text = stdout.trim();
+    if (text === '')
+        return [];
+    const rows = text.startsWith('[')
+        ? JSON.parse(text)
+        : text.split('\n').map((line) => JSON.parse(line));
+    return rows.map((row) => ({
+        service: row.Service ?? '',
+        state: row.State ?? '',
+        health: row.Health ?? '',
+        exitCode: row.ExitCode ?? 0,
+    }));
+};
+export const states = async (run, target) => parsePs(await compose(run, target, ['ps', '-a', '--format', 'json']));

package/dist/tool/up/compose.d.ts

@@ -0,0 +1,18 @@
+import { type ExtensionPackage } from '../../manifest/manifest.schema.js';
+export declare const STORE_IMAGE = "postgres:18-alpine";
+export interface ComposeInput {
+    pkg: ExtensionPackage;
+    tags: Record<string, string>;
+    recordFile: string;
+    gatewayFile: string;
+}
+export declare const projectName: (pkg: ExtensionPackage) => string;
+export declare const composeFile: (input: ComposeInput) => {
+    name: string;
+    services: Record<string, unknown>;
+    volumes: {
+        store: {};
+    } | {
+        store?: undefined;
+    };
+};

package/dist/tool/up/compose.js

@@ -0,0 +1,77 @@
+import {} from '../../manifest/manifest.schema.js';
+import { imageParts, normalizeParts } from '../../manifest/parts.js';
+import {} from '../../manifest/primitives.schema.js';
+import { GATEWAY_PORT, ISSUER_PORT, PART_PORT, TRAEFIK_COMMAND, TRAEFIK_IMAGE } from './gateway.js';
+export const STORE_IMAGE = 'postgres:18-alpine';
+const RECORD_TARGET = '/run/agentage/agentage-extension.json';
+const ISSUER_ENTRY = 'node_modules/@agentage/extension/dist/tool/up/dev-issuer.js';
+export const projectName = (pkg) => `agentage-${pkg.agentage.id}`;
+// A local-only credential: the store has no published port, only the parts' network reaches it.
+const storeUrl = (id) => `postgres://${id}:agentage-local@store:5432/${id}`;
+const hasStore = (pkg) => normalizeParts(pkg.agentage.parts).store === 'postgres';
+const partEnv = (pkg, part) => ({
+    AGENTAGE_ORIGIN: `http://localhost:${GATEWAY_PORT}`,
+    AGENTAGE_RECORD_FILE: RECORD_TARGET,
+    ...(hasStore(pkg) && part !== 'ui' ? { AGENTAGE_STORE_URL: storeUrl(pkg.agentage.id) } : {}),
+});
+const storeService = (id) => ({
+    image: STORE_IMAGE,
+    environment: { POSTGRES_USER: id, POSTGRES_PASSWORD: 'agentage-local', POSTGRES_DB: id },
+    volumes: ['store:/var/lib/postgresql'],
+    healthcheck: {
+        test: ['CMD-SHELL', `pg_isready -U ${id} -d ${id}`],
+        interval: '2s',
+        timeout: '3s',
+        retries: 30,
+    },
+});
+const partService = (input, part) => ({
+    image: input.tags[part],
+    environment: partEnv(input.pkg, part),
+    volumes: [`${input.recordFile}:${RECORD_TARGET}:ro`],
+    ...(hasStore(input.pkg) && part !== 'ui'
+        ? { depends_on: { store: { condition: 'service_healthy' } } }
+        : {}),
+});
+const fixedServices = (input, anyImage) => ({
+    gateway: {
+        image: TRAEFIK_IMAGE,
+        command: TRAEFIK_COMMAND,
+        ports: [`127.0.0.1:${GATEWAY_PORT}:80`],
+        volumes: [`${input.gatewayFile}:/etc/traefik/dynamic.yml:ro`],
+        healthcheck: {
+            test: ['CMD', 'wget', '-qO-', 'http://127.0.0.1:8082/ping'],
+            interval: '2s',
+            timeout: '3s',
+            retries: 30,
+        },
+    },
+    issuer: {
+        image: anyImage,
+        command: ['node', ISSUER_ENTRY],
+        ports: [`127.0.0.1:${ISSUER_PORT}:${PART_PORT}`],
+    },
+});
+const migrateService = (input) => ({
+    image: input.tags['api'],
+    command: ['node', 'dist/store/migrate.js'],
+    environment: partEnv(input.pkg, 'migrate'),
+    depends_on: { store: { condition: 'service_healthy' } },
+    profiles: ['jobs'],
+    restart: 'no',
+});
+// One compose file: gateway, dev issuer, the store and its migrate job, one service per part.
+export const composeFile = (input) => {
+    const parts = imageParts(input.pkg);
+    const services = {};
+    for (const part of parts)
+        services[part] = partService(input, part);
+    Object.assign(services, fixedServices(input, input.tags[parts[0] ?? 'api'] ?? ''));
+    if (hasStore(input.pkg)) {
+        services['store'] = storeService(input.pkg.agentage.id);
+        if (input.tags['api'])
+            services['migrate'] = migrateService(input);
+    }
+    const volumes = hasStore(input.pkg) ? { store: {} } : {};
+    return { name: projectName(input.pkg), services, volumes };
+};

package/dist/tool/up/dev-issuer-app.d.ts

@@ -0,0 +1,22 @@
+import { type KeyObject } from 'node:crypto';
+import { type Server } from 'node:http';
+import { z } from 'zod';
+export declare const DEV_ISSUER = "http://localhost:4281";
+export declare const DEV_AUDIENCE = "*.agentage.io";
+declare const TokenRequestSchema: z.ZodObject<{
+    scope: z.ZodString;
+    sub: z.ZodOptional<z.ZodString>;
+    ttlSeconds: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+interface Keys {
+    kid: string;
+    privateKey: KeyObject;
+    jwk: Record<string, unknown>;
+}
+export declare const newKeys: () => Keys;
+export declare const mint: (keys: Keys, request: z.infer<typeof TokenRequestSchema>, now?: number) => {
+    token: string;
+    expiresAt: string;
+};
+export declare const createIssuer: (keys?: Keys) => Server;
+export {};

package/dist/tool/up/dev-issuer-app.js

@@ -0,0 +1,80 @@
+import { generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { createServer } from 'node:http';
+import { z } from 'zod';
+export const DEV_ISSUER = 'http://localhost:4281';
+export const DEV_AUDIENCE = '*.agentage.io';
+const TokenRequestSchema = z.strictObject({
+    scope: z
+        .string()
+        .max(512)
+        .regex(/^[a-z][a-z0-9-]*:(read|write|admin)( [a-z][a-z0-9-]*:(read|write|admin))*$/),
+    sub: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{1,64}$/)
+        .optional(),
+    ttlSeconds: z.int().min(60).max(86_400).optional(),
+});
+export const newKeys = () => {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    const kid = `dev-${randomUUID().slice(0, 8)}`;
+    return {
+        kid,
+        privateKey,
+        jwk: { ...publicKey.export({ format: 'jwk' }), kid, alg: 'EdDSA', use: 'sig' },
+    };
+};
+const b64 = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+// The api-standards token shape: aga_<jwt>, typ at+jwt, EdDSA, scope {id}:{verb}, a jti.
+export const mint = (keys, request, now = Date.now()) => {
+    const iat = Math.floor(now / 1000);
+    const exp = iat + (request.ttlSeconds ?? 3600);
+    const claims = {
+        iss: DEV_ISSUER,
+        sub: request.sub ?? 'usr_dev',
+        aud: DEV_AUDIENCE,
+        scope: request.scope,
+        iat,
+        exp,
+        jti: `tok_${randomUUID()}`,
+    };
+    const input = `${b64({ alg: 'EdDSA', typ: 'at+jwt', kid: keys.kid })}.${b64(claims)}`;
+    const signature = sign(null, Buffer.from(input), keys.privateKey).toString('base64url');
+    return { token: `aga_${input}.${signature}`, expiresAt: new Date(exp * 1000).toISOString() };
+};
+const reply = (res, status, body) => {
+    res.writeHead(status, {
+        'content-type': 'application/json',
+        'cache-control': 'no-store',
+        'access-control-allow-origin': '*',
+        'access-control-allow-headers': 'content-type',
+        'access-control-allow-methods': 'GET, POST, OPTIONS',
+    });
+    res.end(body === undefined ? undefined : JSON.stringify(body));
+};
+const readBody = async (req) => {
+    let text = '';
+    for await (const chunk of req)
+        text += String(chunk);
+    if (text.length > 4096)
+        throw new Error('body too large');
+    return JSON.parse(text || '{}');
+};
+const tokenRoute = async (keys, req, res) => {
+    const parsed = TokenRequestSchema.safeParse(await readBody(req).catch(() => null));
+    if (!parsed.success)
+        return reply(res, 400, { error: 'scope must be {id}:{read|write|admin}, space-separated' });
+    reply(res, 200, mint(keys, parsed.data));
+};
+// Mints only: the kit does not verify tokens yet. Never part of a deployed estate.
+export const createIssuer = (keys = newKeys()) => createServer((req, res) => {
+    const path = (req.url ?? '/').split('?')[0];
+    if (req.method === 'OPTIONS')
+        return reply(res, 204, undefined);
+    if (req.method === 'GET' && path === '/health')
+        return reply(res, 200, { status: 'ok' });
+    if (req.method === 'GET' && path === '/.well-known/jwks.json')
+        return reply(res, 200, { keys: [keys.jwk] });
+    if (req.method === 'POST' && path === '/token')
+        return void tokenRoute(keys, req, res);
+    reply(res, 404, { error: 'not found' });
+});

package/dist/tool/up/dev-issuer.d.ts

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

package/dist/tool/up/dev-issuer.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { createIssuer } from './dev-issuer-app.js';
+// The dev issuer of `up`: run from a part image, on the image's port so its HEALTHCHECK answers.
+const port = Number(process.env['PORT'] ?? 3000);
+createIssuer().listen(port, () => process.stderr.write(`dev issuer on :${port}\n`));

package/dist/tool/up/down.d.ts

@@ -0,0 +1,12 @@
+import { type Run } from '../exec.js';
+export interface DownOptions {
+    dir?: string;
+    keepData?: boolean;
+    onLine?: (line: string) => void;
+}
+export interface DownResult {
+    containers: number;
+    networks: number;
+    volumes: number;
+}
+export declare const down: (options?: DownOptions, run?: Run) => Promise<DownResult>;

package/dist/tool/up/down.js

@@ -0,0 +1,38 @@
+import { access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { readManifest } from '../../manifest/read-manifest.js';
+import { quietly, runCommand } from '../exec.js';
+import { projectName } from './compose.js';
+import { plural, stepLine } from './lines.js';
+import { LOCAL_DIR } from './local-record.js';
+const count = (log, kind) => log.split('\n').filter((line) => new RegExp(`\\b${kind}\\b.*\\bRemoved\\b`).test(line)).length;
+// Everything `up` started goes; --keep-data keeps the store volume for the next `up`.
+export const down = async (options = {}, run = runCommand) => {
+    const dir = resolve(options.dir ?? '.');
+    const pkg = await readManifest(dir);
+    const file = join(dir, LOCAL_DIR, 'compose.json');
+    const withFile = await access(file).then(() => ['-f', file], () => []);
+    const args = [
+        'compose',
+        ...withFile,
+        '-p',
+        projectName(pkg),
+        '--profile',
+        'jobs',
+        'down',
+        '--remove-orphans',
+    ];
+    const result = await quietly(run)('docker', options.keepData ? args : [...args, '--volumes']);
+    if (result.code !== 0)
+        throw new Error(`docker compose down failed: ${(result.stderr ?? '').trim()}`);
+    const log = result.stderr ?? '';
+    const removed = {
+        containers: count(log, 'Container'),
+        networks: count(log, 'Network'),
+        volumes: count(log, 'Volume'),
+    };
+    const kept = options.keepData ? ' (the store volume kept)' : '';
+    const what = `${plural(removed.containers, 'container')} · ${plural(removed.networks, 'network')} · ${plural(removed.volumes, 'volume')}${kept}`;
+    options.onLine?.(stepLine('removed', what));
+    return removed;
+};

package/dist/tool/up/gateway.d.ts

@@ -0,0 +1,27 @@
+import { type ImagePartKind } from '../../manifest/primitives.schema.js';
+export declare const GATEWAY_PORT = 4280;
+export declare const ISSUER_PORT = 4281;
+export declare const PART_PORT = 3000;
+export declare const TRAEFIK_IMAGE = "traefik:v3.7.17@sha256:68ae5fe5b64ca166704b746a9e8afcd385e36b3f569a5691401bf652d57b3748";
+export declare const gatewayConfig: (parts: ImagePartKind[], version: string) => {
+    http: {
+        middlewares: {
+            'gateway-headers': {
+                headers: {
+                    contentTypeNosniff: boolean;
+                    referrerPolicy: string;
+                    frameDeny: boolean;
+                };
+            };
+        };
+        services: Record<string, unknown>;
+        routers: Record<string, {
+            rule: string;
+            priority: number;
+            service: string;
+            entryPoints: string[];
+            middlewares: string[];
+        }>;
+    };
+};
+export declare const TRAEFIK_COMMAND: string[];