@agentage/extension 0.2.0 → 0.3.0

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

@@ -1,8 +1,12 @@
 import { generateKeyPairSync, randomUUID, sign } from 'node:crypto';
 import { createServer } from 'node:http';
 import { z } from 'zod';
+import { GATEWAY_PORT, PART_PORT } from './gateway.js';
+// Where the host reaches the dev issuer; the parts of `up` reach it, and tokens name it, by service.
 export const DEV_ISSUER = 'http://localhost:4281';
-export const DEV_AUDIENCE = '*.agentage.io';
+export const UP_ISSUER = `http://issuer:${PART_PORT}`;
+// The host of `up` (http://localhost:4280): the one host this audience covers.
+export const DEV_AUDIENCE = 'localhost';
 const TokenRequestSchema = z.strictObject({
     scope: z
         .string()
@@ -12,8 +16,10 @@ const TokenRequestSchema = z.strictObject({
         .string()
         .regex(/^[A-Za-z0-9_-]{1,64}$/)
         .optional(),
-    ttlSeconds: z.int().min(60).max(86_400).optional(),
+    ttlSeconds: z.int().min(1).max(86_400).optional(),
+    aud: z.string().min(1).max(253).optional(),
 });
+const RevokeSchema = z.strictObject({ jti: z.string().regex(/^tok_[0-9a-f-]{36}$/) });
 export const newKeys = () => {
     const { privateKey, publicKey } = generateKeyPairSync('ed25519');
     const kid = `dev-${randomUUID().slice(0, 8)}`;
@@ -25,18 +31,11 @@ export const newKeys = () => {
 };
 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()) => {
+export const mint = (keys, request, settings, 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 { scope, sub = 'usr_dev', aud = settings.audience } = request;
+    const claims = { iss: settings.issuer, sub, aud, 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() };
@@ -46,7 +45,7 @@ const reply = (res, status, body) => {
         'content-type': 'application/json',
         'cache-control': 'no-store',
         'access-control-allow-origin': '*',
-        'access-control-allow-headers': 'content-type',
+        'access-control-allow-headers': 'content-type, x-client-type',
         'access-control-allow-methods': 'GET, POST, OPTIONS',
     });
     res.end(body === undefined ? undefined : JSON.stringify(body));
@@ -59,22 +58,52 @@ const readBody = async (req) => {
         throw new Error('body too large');
     return JSON.parse(text || '{}');
 };
-const tokenRoute = async (keys, req, res) => {
+const tokenRoute = async (issuer, 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));
+    reply(res, 200, mint(issuer.keys, parsed.data, issuer.settings));
+};
+// Kept for a day, the longest a dev token lives, so an entry never outlasts its token by more.
+const revokeRoute = async (issuer, req, res) => {
+    const parsed = RevokeSchema.safeParse(await readBody(req).catch(() => null));
+    if (!parsed.success)
+        return reply(res, 400, { error: 'jti must be a tok_ id' });
+    issuer.revoked.set(parsed.data.jti, Math.floor(Date.now() / 1000) + 86_400);
+    reply(res, 200, { jti: parsed.data.jti, revoked: true });
+};
+const revokedList = ({ revoked }) => {
+    const now = Date.now() / 1000;
+    const live = [...revoked].filter(([, exp]) => exp > now).map(([jti, exp]) => ({ jti, exp }));
+    return { revoked: live, generatedAt: new Date().toISOString() };
 };
-// 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];
+// security.md, local daemons: its tokens open the parts of `up`, so no other site may mint one.
+const ORIGINS = ['localhost', '127.0.0.1'].map((host) => `http://${host}:${GATEWAY_PORT}`);
+const allowed = ({ settings }, req) => {
+    const host = (req.headers.host ?? '').replace(/:[0-9]+$/, '');
+    const origin = req.headers.origin;
+    const hosts = ['localhost', '127.0.0.1', new URL(settings.issuer).hostname];
+    return hosts.includes(host) && (origin === undefined || ORIGINS.includes(origin));
+};
+const route = (issuer, req, res) => {
+    const at = `${req.method ?? ''} ${(req.url ?? '/').split('?')[0] ?? ''}`;
+    if (!allowed(issuer, req))
+        return reply(res, 403, { error: 'host or origin not allowed' });
     if (req.method === 'OPTIONS')
         return reply(res, 204, undefined);
-    if (req.method === 'GET' && path === '/health')
+    if (at === 'GET /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);
+    if (at === 'GET /.well-known/jwks.json')
+        return reply(res, 200, { keys: [issuer.keys.jwk] });
+    if (at === 'GET /.well-known/agentage-revoked')
+        return reply(res, 200, revokedList(issuer));
+    if (at === 'POST /token')
+        return void tokenRoute(issuer, req, res);
+    if (at === 'POST /revoke')
+        return void revokeRoute(issuer, req, res);
     reply(res, 404, { error: 'not found' });
-});
+};
+export const createIssuer = (settings = { issuer: UP_ISSUER, audience: DEV_AUDIENCE }, keys = newKeys()) => {
+    const issuer = { settings, keys, revoked: new Map() };
+    return createServer((req, res) => route(issuer, req, res));
+};

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
+import { portFromEnv } from '../../runtime/build-info.js';
 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);
+const port = portFromEnv(process.env);
 createIssuer().listen(port, () => process.stderr.write(`dev issuer on :${port}\n`));

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

@@ -5,6 +5,7 @@ export interface DownOptions {
     onLine?: (line: string) => void;
 }
 export interface DownResult {
+    project: string;
     containers: number;
     networks: number;
     volumes: number;

package/dist/tool/up/down.js

@@ -1,38 +1,47 @@
-import { access } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { readManifest } from '../../manifest/read-manifest.js';
 import { quietly, runCommand } from '../exec.js';
-import { projectName } from './compose.js';
+import { composeArgs } from './compose-run.js';
 import { plural, stepLine } from './lines.js';
 import { LOCAL_DIR } from './local-record.js';
+import { legacyProject, projectName, renderedProject, workingCopy } from './project.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 removedOf = (log) => ({
+    containers: count(log, 'Container'),
+    networks: count(log, 'Network'),
+    volumes: count(log, 'Volume'),
+});
+const summary = (removed, keepData) => {
+    if (removed.containers + removed.networks + removed.volumes === 0)
+        return 'nothing was running';
+    const counts = [
+        plural(removed.containers, 'container'),
+        plural(removed.networks, 'network'),
+        plural(removed.volumes, 'volume'),
     ];
-    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()}`);
+    return counts.join(' · ') + (keepData ? ' (the store volume kept)' : '');
+};
+// This folder's own project; a copied compose.json naming another copy's project is ignored.
+const targetOf = async (dir) => {
+    const { id } = (await readManifest(dir)).agentage;
+    const file = join(dir, LOCAL_DIR, 'compose.json');
+    const rendered = await renderedProject(file);
+    const project = projectName(id, dir);
+    if (rendered === project)
+        return { file, project };
+    return { project: rendered === legacyProject(id) ? rendered : project };
+};
+// Everything `up` started in this working copy goes, and only that; --keep-data keeps the store.
+export const down = async (options = {}, run = runCommand) => {
+    const dir = await workingCopy(options.dir);
+    const target = await targetOf(dir);
+    const volumes = options.keepData ? [] : ['--volumes'];
+    const args = composeArgs(target, ['--profile', 'jobs', 'down', '--remove-orphans', ...volumes]);
+    const result = await quietly(run)('docker', args);
     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;
+    if (result.code !== 0)
+        throw new Error(`docker compose down failed: ${log.trim()}`);
+    const removed = removedOf(log);
+    options.onLine?.(stepLine('removed', summary(removed, options.keepData), target.project));
+    return { project: target.project, ...removed };
 };

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

@@ -3,6 +3,14 @@ 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 PART_PATHS: {
+    pages: string;
+    ui: string;
+    api: string;
+    mcp: string;
+};
+type RoutedPart = keyof typeof PART_PATHS;
+export declare const partPath: (part: RoutedPart, version: string) => string;
 export declare const gatewayConfig: (parts: ImagePartKind[], version: string) => {
     http: {
         middlewares: {
@@ -25,3 +33,4 @@ export declare const gatewayConfig: (parts: ImagePartKind[], version: string) =>
     };
 };
 export declare const TRAEFIK_COMMAND: string[];
+export {};

package/dist/tool/up/gateway.js

@@ -5,14 +5,12 @@ export const PART_PORT = 3000;
 export const TRAEFIK_IMAGE = 'traefik:v3.7.17@sha256:68ae5fe5b64ca166704b746a9e8afcd385e36b3f569a5691401bf652d57b3748';
 // The URL layout of api-standards section 1, as the estate's gateway renders it.
 const RESERVED = 'PathPrefix(`/api/`) || Path(`/mcp`) || PathPrefix(`/mcp/`) || PathPrefix(`/ui/`) || PathPrefix(`/.well-known/`) || PathPrefix(`/git/`) || Path(`/health`)';
+// Each routed part's path, in the order `up` prints them; /mcp is exact, the rest are prefixes.
+export const PART_PATHS = { pages: '/', ui: '/ui/{version}/', api: '/api/v1/', mcp: '/mcp' };
+// In this order, so the first present serves /.well-known/ (api-standards section 1).
 const ROUTED = ['api', 'mcp', 'pages', 'ui'];
-const ruleOf = (part, version) => ({
-    api: 'PathPrefix(`/api/v1/`)',
-    mcp: 'Path(`/mcp`)',
-    ui: `PathPrefix(\`/ui/${version}/\`)`,
-    pages: 'PathPrefix(`/`)',
-    worker: undefined,
-})[part];
+export const partPath = (part, version) => PART_PATHS[part].replace('{version}', version);
+const ruleOf = (part, version) => part === 'mcp' ? 'Path(`/mcp`)' : `PathPrefix(\`${partPath(part, version)}\`)`;
 const router = (rule, priority, service) => ({
     rule,
     priority,
@@ -20,21 +18,17 @@ const router = (rule, priority, service) => ({
     entryPoints: ['web'],
     middlewares: ['gateway-headers'],
 });
-const partRouters = (parts, version) => {
+const partRouters = (routed, version) => {
     const routers = {};
-    for (const part of parts) {
-        const rule = ruleOf(part, version);
-        if (rule)
-            routers[part] = router(rule, part === 'pages' ? 1 : 100, part);
-    }
-    const owner = ROUTED.find((part) => parts.includes(part));
-    if (owner)
-        routers['well-known'] = router('PathPrefix(`/.well-known/`)', 100, owner);
+    for (const part of routed)
+        routers[part] = router(ruleOf(part, version), part === 'pages' ? 1 : 100, part);
+    if (routed[0])
+        routers['well-known'] = router('PathPrefix(`/.well-known/`)', 100, routed[0]);
     return routers;
 };
 // Traefik's file provider: a reserved-prefix miss is Traefik's own 404, like the estate gateway.
 export const gatewayConfig = (parts, version) => {
-    const routed = parts.filter((part) => ROUTED.includes(part));
+    const routed = ROUTED.filter((part) => parts.includes(part));
     const services = {
         'gateway-miss': { loadBalancer: { servers: [{ url: 'http://127.0.0.1:8081' }] } },
     };

package/dist/tool/up/lines.js

@@ -1,3 +1,3 @@
 // What `up` and `down` print: a label, what it is, the detail; the columns line up as in a terminal.
-export const stepLine = (label, what, detail = '') => `${label.padEnd(9)}${what.padEnd(45)}${detail}`.trimEnd();
+export const stepLine = (label, what, detail = '') => `${label.padEnd(9)}${what.padEnd(Math.max(45, what.length + 2))}${detail}`.trimEnd();
 export const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;

package/dist/tool/up/local-record.d.ts

@@ -33,7 +33,10 @@ export declare const writeLocalRecord: (dir: string, pkg: ExtensionPackage, buil
             } | undefined;
         };
         openapi?: string | undefined;
-        tools?: string[] | undefined;
+        tools?: {
+            name: string;
+            scope: string;
+        }[] | undefined;
         widgets?: {
             name: string;
             element: string;

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

@@ -0,0 +1,2 @@
+import { type Run } from '../exec.js';
+export declare const assertPortsFree: (run: Run, project: string) => Promise<void>;

package/dist/tool/up/ports.js

@@ -0,0 +1,22 @@
+import { mustRun } from '../exec.js';
+import { GATEWAY_PORT, ISSUER_PORT } from './gateway.js';
+const FORMAT = '{{.Names}}\t{{.Label "com.docker.compose.project"}}\t{{.Ports}}';
+const runningContainers = async (run) => (await mustRun(run, 'docker', ['ps', '--format', FORMAT]))
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => {
+    const [name = '', project = '', ports = ''] = line.split('\t');
+    return { name, project, ports };
+});
+const heldPort = (holder) => [GATEWAY_PORT, ISSUER_PORT].find((port) => holder.ports.includes(`:${port}->`));
+const refusal = (holder, port) => new Error(holder.project
+    ? `localhost:${port} is held by compose project ${holder.project}: run agentage extension down in the working copy that started it, then up again`
+    : `localhost:${port} is held by container ${holder.name}: stop it, then up again`);
+// Before anything starts: the gateway and issuer ports are free, or this working copy's own.
+export const assertPortsFree = async (run, project) => {
+    for (const holder of await runningContainers(run)) {
+        const port = heldPort(holder);
+        if (port !== undefined && holder.project !== project)
+            throw refusal(holder, port);
+    }
+};

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

@@ -0,0 +1,4 @@
+export declare const projectName: (id: string, dir: string) => string;
+export declare const legacyProject: (id: string) => string;
+export declare const workingCopy: (dir?: string) => Promise<string>;
+export declare const renderedProject: (file: string) => Promise<string | undefined>;

package/dist/tool/up/project.js

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { readJsonIfExists } from '../../manifest/read-manifest.js';
+// One compose project per working copy: two checkouts of one extension never share containers or data.
+export const projectName = (id, dir) => `agentage-${id}-${createHash('sha256').update(dir).digest('hex').slice(0, 8)}`;
+// Kit 0.2.0 named one project per id, shared by every copy; down still removes it.
+export const legacyProject = (id) => `agentage-${id}`;
+// Absolute, symlinks resolved, so one working copy always gets the same project name.
+export const workingCopy = async (dir = '.') => {
+    const absolute = resolve(dir);
+    return realpath(absolute).catch(() => absolute);
+};
+const RenderedSchema = z.object({ name: z.string().regex(/^[a-z0-9][a-z0-9_-]*$/) });
+// The project a rendered compose file names; down trusts it only when it is this folder's own.
+export const renderedProject = async (file) => {
+    const parsed = RenderedSchema.safeParse(await readJsonIfExists(file).catch(() => undefined));
+    return parsed.success ? parsed.data.name : undefined;
+};

package/dist/tool/up/store-line.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+declare const MigrateSummarySchema: z.ZodObject<{
+    migrations: z.ZodInt;
+    applied: z.ZodInt;
+    seeds: z.ZodInt;
+    seedsBefore: z.ZodDefault<z.ZodInt>;
+}, z.core.$strip>;
+export type MigrateSummary = z.infer<typeof MigrateSummarySchema>;
+export declare const summaryOf: (out: string) => MigrateSummary;
+export declare const storePhrase: (summary: MigrateSummary) => string;
+export {};

package/dist/tool/up/store-line.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { plural } from './lines.js';
+// The migrate entry's last stdout line (migrate.ts); an image on kit 0.2.0 prints no seedsBefore.
+const MigrateSummarySchema = z.object({
+    migrations: z.int().min(0),
+    applied: z.int().min(0),
+    seeds: z.int().min(0),
+    seedsBefore: z.int().min(0).default(0),
+});
+const lastJson = (out) => {
+    try {
+        return JSON.parse(out.trim().split('\n').at(-1) ?? '');
+    }
+    catch {
+        return undefined;
+    }
+};
+export const summaryOf = (out) => {
+    const parsed = MigrateSummarySchema.safeParse(lastJson(out));
+    if (!parsed.success)
+        throw new Error(`the migrate job printed no summary: ${out.slice(-200)}`);
+    return parsed.data;
+};
+const migrationsPhrase = ({ migrations, applied }) => {
+    const already = migrations - applied;
+    if (already === 0)
+        return `${plural(applied, 'migration')} applied`;
+    if (applied === 0)
+        return `${plural(already, 'migration')} already applied`;
+    return `${plural(applied, 'migration')} applied, ${already} already applied`;
+};
+const seedsPhrase = ({ seeds, seedsBefore }) => seeds === 0 && seedsBefore > 0
+    ? `${plural(seedsBefore, 'seed')} already applied`
+    : plural(seeds, 'seed');
+// A kept volume says so: what this run applied, and what an earlier run already had.
+export const storePhrase = (summary) => `${migrationsPhrase(summary)} · ${seedsPhrase(summary)}`;

package/dist/tool/up/token.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { TIMEOUTS } from '../timeouts.js';
 import { DEV_ISSUER } from './dev-issuer-app.js';
 const AnswerSchema = z.object({ token: z.string().startsWith('aga_') });
 // A token from the dev issuer of `up`, for calling /api/v1/ and /mcp by hand or from tests.
@@ -8,11 +9,17 @@ export const token = async (options) => {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ scope: options.scope }),
-    }).catch(() => {
+        signal: AbortSignal.timeout(TIMEOUTS.issuer),
+    }).catch((err) => {
+        if (err.name === 'TimeoutError')
+            throw new Error(`the dev issuer at ${issuer} did not answer in ${TIMEOUTS.issuer / 1000} s`);
         throw new Error(`no dev issuer at ${issuer}: run agentage extension up first`);
     });
     const body = await res.json().catch(() => null);
     if (!res.ok)
         throw new Error(`the dev issuer refused: ${JSON.stringify(body)}`);
-    return AnswerSchema.parse(body).token;
+    const answer = AnswerSchema.safeParse(body);
+    if (!answer.success)
+        throw new Error('the dev issuer answered without an aga_ token');
+    return answer.data.token;
 };

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

@@ -1,19 +1,16 @@
 import { type ExtensionPackage } from '../../manifest/manifest.schema.js';
 import { type Env } from '../../runtime/build-info.js';
-import { type Run } from '../exec.js';
+import { type WaitDeps } from './wait.js';
 export interface UpOptions {
     dir?: string;
     env?: Env;
     onLine?: (line: string) => void;
 }
-export interface UpDeps {
-    run: Run;
-    sleep?: (ms: number) => Promise<void>;
-    timeoutMs?: number;
-}
+export type UpDeps = WaitDeps;
 export interface UpResult {
     parts: number;
     seconds: number;
+    project: string;
 }
 export declare const routesOf: (pkg: ExtensionPackage) => string[];
 export declare const up: (options?: UpOptions, deps?: UpDeps) => Promise<UpResult>;

package/dist/tool/up/up.js

@@ -1,81 +1,84 @@
 import { writeFile } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
-import { checkCli } from '../../command/check-cli.js';
+import { join } from 'node:path';
 import {} from '../../manifest/manifest.schema.js';
-import { imageParts, normalizeParts } from '../../manifest/parts.js';
+import { hasPostgres, imageParts, normalizeParts } from '../../manifest/parts.js';
 import { readManifest } from '../../manifest/read-manifest.js';
 import {} from '../../runtime/build-info.js';
 import { build } from '../build.js';
 import { quietly, runCommand } from '../exec.js';
+import { exists } from '../stage.js';
+import { TIMEOUTS } from '../timeouts.js';
 import { compose } from './compose-run.js';
-import { composeFile, projectName, STORE_IMAGE } from './compose.js';
-import { GATEWAY_PORT, gatewayConfig, ISSUER_PORT } from './gateway.js';
+import { composeFile, STORE_IMAGE } from './compose.js';
+import { GATEWAY_PORT, gatewayConfig, ISSUER_PORT, PART_PATHS, partPath } from './gateway.js';
 import { plural, stepLine } from './lines.js';
 import { assertDiscoverable, LOCAL_DIR, writeLocalRecord } from './local-record.js';
+import { assertPortsFree } from './ports.js';
+import { projectName, workingCopy } from './project.js';
+import { storePhrase, summaryOf } from './store-line.js';
 import { waitHealthy } from './wait.js';
 const GATEWAY = `http://localhost:${GATEWAY_PORT}`;
+const jsonFile = (file, value) => writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
 const renderFiles = async (s, recordFile, tags) => {
     const gatewayFile = join(s.dir, LOCAL_DIR, 'gateway.yml');
-    await writeFile(gatewayFile, `${JSON.stringify(gatewayConfig(imageParts(s.pkg), s.pkg.version), null, 2)}\n`);
-    await writeFile(s.target.file ?? '', `${JSON.stringify(composeFile({ pkg: s.pkg, tags, recordFile, gatewayFile }), null, 2)}\n`);
+    const seeds = join(s.dir, 'seeds');
+    const seedsDir = (await exists(seeds)) ? seeds : undefined;
+    await jsonFile(gatewayFile, gatewayConfig(imageParts(s.pkg), s.pkg.version));
+    const project = s.target.project;
+    await jsonFile(s.target.file, composeFile({ pkg: s.pkg, project, tags, recordFile, gatewayFile, seedsDir }));
 };
 const buildStep = async (s, env) => {
-    const built = await build({ dir: s.dir, env }, { run: s.run });
-    s.line('build', `${plural(built.images.length, 'image')} from the release recipes`, 'same recipe and tags as a release');
-    const { file, record } = await writeLocalRecord(s.dir, s.pkg, built, s.run);
+    const built = await build({ dir: s.dir, env }, { run: s.deps.run });
+    const images = plural(built.images.length, 'image');
+    s.line('build', `${images} from the release recipes`, 'same recipe and tags as a release');
+    const { file, record } = await writeLocalRecord(s.dir, s.pkg, built, s.deps.run);
     assertDiscoverable(record, GATEWAY);
     s.line('record', `${LOCAL_DIR}/record.json`, 'discovery valid');
-    await renderFiles(s, file, Object.fromEntries(built.images.map((image) => [image.part, image.tag])));
+    await renderFiles(s, file, Object.fromEntries(built.images.map((i) => [i.part, i.tag])));
 };
-// The migrate job runs before any part starts; its last stdout line is the summary.
+// The migrate job runs before any part starts; a kept volume reports what it already had.
 const storeStep = async (s) => {
-    await compose(s.run, s.target, ['up', '-d', 'store']);
+    await compose(s.deps.run, s.target, ['up', '-d', 'store'], TIMEOUTS.start);
     await waitHealthy(s.target, ['store'], s.deps);
-    const out = await compose(s.run, s.target, ['run', '--rm', '--no-deps', 'migrate']);
-    const summary = JSON.parse(out.trim().split('\n').at(-1) ?? '{}');
-    s.line('store', STORE_IMAGE, `${plural(summary.applied ?? 0, 'migration')} applied · ${plural(summary.seeds ?? 0, 'seed')}`);
+    const run = ['run', '--rm', '--no-deps', 'migrate'];
+    const out = await compose(s.deps.run, s.target, run, TIMEOUTS.migrate).catch((err) => {
+        throw new Error(`the migrate job failed, no part was started: ${err.message}`);
+    });
+    const summary = summaryOf(out);
+    s.line('store', STORE_IMAGE, storePhrase(summary));
 };
-const ROUTES = { pages: '/', ui: '/ui/{version}/', api: '/api/v1/', mcp: '/mcp' };
-export const routesOf = (pkg) => Object.keys(ROUTES)
+export const routesOf = (pkg) => Object.keys(PART_PATHS)
     .filter((part) => imageParts(pkg).includes(part))
-    .map((part) => ROUTES[part].replace('{version}', pkg.version));
+    .map((part) => partPath(part, pkg.version));
 const partsStep = async (s) => {
-    await compose(s.run, s.target, ['up', '-d', '--remove-orphans']);
-    const services = [...imageParts(s.pkg), 'gateway', 'issuer'];
-    await waitHealthy(s.target, services, s.deps);
+    await compose(s.deps.run, s.target, ['up', '-d', '--remove-orphans'], TIMEOUTS.start);
+    await waitHealthy(s.target, [...imageParts(s.pkg), 'gateway', 'issuer'], s.deps);
     s.line('issuer', 'dev tokens', `http://localhost:${ISSUER_PORT}`);
     s.line('gateway', GATEWAY, routesOf(s.pkg).join(' · '));
 };
-const cliStep = async (s) => {
-    if (!normalizeParts(s.pkg.agentage.parts).code.cli)
-        return 0;
-    const problem = await checkCli(s.dir);
-    if (problem)
-        throw new Error(`cli part: ${problem}`);
-    return 1;
+// The cli part has no container: build's check already proved its handlers match the commands.
+const cliParts = (pkg) => normalizeParts(pkg.agentage.parts).code.cli ? 1 : 0;
+const sessionOf = async (options, deps) => {
+    const dir = await workingCopy(options.dir);
+    const pkg = await readManifest(dir);
+    const file = join(dir, LOCAL_DIR, 'compose.json');
+    const target = { file, project: projectName(pkg.agentage.id, dir) };
+    const line = (label, what, detail) => options.onLine?.(stepLine(label, what, detail));
+    return { dir, pkg, target, line, deps: { ...deps, run: quietly(deps.run) } };
 };
 // The laptop shape of a deployment: the release images, a local record, store, issuer, gateway.
 export const up = async (options = {}, deps = { run: runCommand }) => {
     const started = Date.now();
-    const dir = resolve(options.dir ?? '.');
-    const pkg = await readManifest(dir);
-    const target = { file: join(dir, LOCAL_DIR, 'compose.json'), project: projectName(pkg) };
-    const line = (label, what, detail) => options.onLine?.(stepLine(label, what, detail));
-    const s = {
-        dir,
-        pkg,
-        run: quietly(deps.run),
-        target,
-        line,
-        deps: { ...deps, run: quietly(deps.run) },
-    };
+    const s = await sessionOf(options, deps);
+    await assertPortsFree(s.deps.run, s.target.project);
     await buildStep(s, options.env ?? process.env);
-    const store = normalizeParts(pkg.agentage.parts).store === 'postgres';
-    if (store)
+    // Again after the build: another up may have started meanwhile, and the store comes next.
+    await assertPortsFree(s.deps.run, s.target.project);
+    if (hasPostgres(s.pkg))
         await storeStep(s);
     await partsStep(s);
-    const parts = imageParts(pkg).length + (store ? 1 : 0) + (await cliStep(s));
+    const parts = imageParts(s.pkg).length + (hasPostgres(s.pkg) ? 1 : 0) + cliParts(s.pkg);
     const seconds = Math.round((Date.now() - started) / 1000);
-    line('ready', `${plural(parts, 'part')} healthy`, `${seconds} s`);
-    return { parts, seconds };
+    s.line('ready', `${plural(parts, 'part')} healthy`, `${seconds} s`);
+    return { parts, seconds, project: s.target.project };
 };

package/dist/tool/up/wait.js

@@ -1,5 +1,6 @@
 import {} from '../exec.js';
 import { compose, states } from './compose-run.js';
+const DEFAULT_TIMEOUT_MS = 180_000;
 const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const broken = (state) => state !== undefined &&
     (state.health === 'unhealthy' || state.state === 'exited' || state.state === 'dead');
@@ -7,7 +8,8 @@ const logsOf = async (run, target, service) => compose(run, target, ['logs', '--
 const failure = async (run, target, state, why) => new Error(`${state.service} ${why}\n${(await logsOf(run, target, state.service)).trim()}`);
 // Every named service healthy (its HEALTHCHECK on 127.0.0.1), or the first broken one with its log.
 export const waitHealthy = async (target, services, deps) => {
-    const deadline = Date.now() + (deps.timeoutMs ?? 180_000);
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
     for (;;) {
         const byService = new Map((await states(deps.run, target)).map((s) => [s.service, s]));
         const bad = services.map((name) => byService.get(name)).find(broken);
@@ -17,7 +19,7 @@ export const waitHealthy = async (target, services, deps) => {
             return;
         if (Date.now() > deadline) {
             const waiting = services.filter((name) => byService.get(name)?.health !== 'healthy');
-            throw new Error(`not healthy after ${Math.round((deps.timeoutMs ?? 180_000) / 1000)} s: ${waiting.join(', ')}`);
+            throw new Error(`not healthy after ${Math.round(timeoutMs / 1000)} s: ${waiting.join(', ')}`);
         }
         await (deps.sleep ?? pause)(1000);
     }

package/dist/ui/ui-app.d.ts

@@ -2,5 +2,7 @@ import { type Express } from 'express';
 import { type PartAppBase } from '../server/app.js';
 export interface UiAppOptions extends PartAppBase {
     dir: string;
+    devIssuer?: string;
 }
+export declare const devIssuerOrigin: (value: string | undefined) => string | undefined;
 export declare const createUiApp: (options: UiAppOptions) => Express;