@agentage/extension 0.2.0 → 0.2.1

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

@@ -1,11 +1,12 @@
 import { mustRun } from '../exec.js';
-export const compose = (run, target, args) => mustRun(run, 'docker', [
+export const composeArgs = (target, args) => [
     'compose',
     ...(target.file ? ['-f', target.file] : []),
     '-p',
     target.project,
     ...args,
-]);
+];
+export const compose = (run, target, args, timeoutMs) => mustRun(run, 'docker', composeArgs(target, args), { timeoutMs });
 // `compose ps --format json` prints one object per line (older releases: one array).
 export const parsePs = (stdout) => {
     const text = stdout.trim();

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

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

package/dist/tool/up/compose.js

@@ -1,22 +1,24 @@
 import {} from '../../manifest/manifest.schema.js';
-import { imageParts, normalizeParts } from '../../manifest/parts.js';
+import { hasPostgres, imageParts } from '../../manifest/parts.js';
 import {} from '../../manifest/primitives.schema.js';
+import { DEV_ISSUER } from './dev-issuer-app.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 STORE_PASSWORD = 'agentage-local';
+const storeUrl = (id) => `postgres://${id}:${STORE_PASSWORD}@store:5432/${id}`;
+// Only the ui under `up` names the dev issuer: its CSP then lets the harness ask it for a token.
 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) } : {}),
+    ...(hasPostgres(pkg) && part !== 'ui' ? { AGENTAGE_STORE_URL: storeUrl(pkg.agentage.id) } : {}),
+    ...(part === 'ui' ? { AGENTAGE_DEV_ISSUER: DEV_ISSUER } : {}),
 });
 const storeService = (id) => ({
     image: STORE_IMAGE,
-    environment: { POSTGRES_USER: id, POSTGRES_PASSWORD: 'agentage-local', POSTGRES_DB: id },
+    environment: { POSTGRES_USER: id, POSTGRES_PASSWORD: STORE_PASSWORD, POSTGRES_DB: id },
     volumes: ['store:/var/lib/postgresql'],
     healthcheck: {
         test: ['CMD-SHELL', `pg_isready -U ${id} -d ${id}`],
@@ -29,7 +31,7 @@ const partService = (input, part) => ({
     image: input.tags[part],
     environment: partEnv(input.pkg, part),
     volumes: [`${input.recordFile}:${RECORD_TARGET}:ro`],
-    ...(hasStore(input.pkg) && part !== 'ui'
+    ...(hasPostgres(input.pkg) && part !== 'ui'
         ? { depends_on: { store: { condition: 'service_healthy' } } }
         : {}),
 });
@@ -56,6 +58,7 @@ const migrateService = (input) => ({
     image: input.tags['api'],
     command: ['node', 'dist/store/migrate.js'],
     environment: partEnv(input.pkg, 'migrate'),
+    ...(input.seedsDir ? { volumes: [`${input.seedsDir}:/app/seeds:ro`] } : {}),
     depends_on: { store: { condition: 'service_healthy' } },
     profiles: ['jobs'],
     restart: 'no',
@@ -67,11 +70,11 @@ export const composeFile = (input) => {
     for (const part of parts)
         services[part] = partService(input, part);
     Object.assign(services, fixedServices(input, input.tags[parts[0] ?? 'api'] ?? ''));
-    if (hasStore(input.pkg)) {
+    if (hasPostgres(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 };
+    const volumes = hasPostgres(input.pkg) ? { store: {} } : {};
+    return { name: input.project, services, volumes };
 };

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/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;