@agentage/extension 0.3.1 → 0.4.1

package/README.md

@@ -9,5 +9,21 @@ correlation id, the response envelope, the store pool, the scheduler and argumen
 npm install @agentage/extension express zod
 ```
 
+`agentage extension check [dir] --json` prints the conformance report (exit 1 when `conforms` is
+false); `file` and `line` are there only when a problem has them:
+
+```json
+{
+  "id": "probe",
+  "version": "0.4.0",
+  "conforms": false,
+  "rules": ["manifest", "entries", "surface", "stack", "store", "sealing"],
+  "problems": [
+    { "rule": "sealing", "file": "src/api/index.ts", "line": 7, "problem": "reads process.env" }
+  ],
+  "skipped": {}
+}
+```
+
 See the [platform README](https://github.com/agentage/platform#readme) for every part kind, the
 manifest, the tool and how a part image runs.

package/dist/tool/build.js

@@ -68,7 +68,7 @@ export const build = async (options = {}, deps = { run: runCommand }) => {
     const pkg = await readManifest(dir);
     const info = await resolveBuildInfo(dir, options.env ?? process.env, deps.run);
     await compile(dir, pkg, deps.run);
-    await assertConforms({ dir, pkg });
+    await assertConforms(dir, { run: deps.run });
     const images = await buildParts({ dir, pkg, info }, options, deps);
     const result = { id: pkg.agentage.id, version: pkg.version, ...info, images };
     if (!options.push)

package/dist/tool/check.d.ts

@@ -1,16 +1,37 @@
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
-export interface CheckInput {
+import { type Run } from './exec.js';
+export interface CheckOptions {
+    run?: Run;
+    requireDocker?: boolean;
+    rules?: readonly CheckRule[];
+}
+export type CheckInput = CheckOptions & {
     dir: string;
     pkg: ExtensionPackage;
-}
+    run: Run;
+};
+export type Finding = {
+    file?: string;
+    line?: number;
+    problem: string;
+};
+export type CheckProblem = Finding & {
+    rule: string;
+};
 export interface CheckRule {
     name: string;
-    run(input: CheckInput): Promise<string[]>;
+    run(input: CheckInput): Promise<Finding[] | {
+        skipped: string;
+    }>;
 }
-export interface CheckProblem {
-    rule: string;
-    problem: string;
+export interface CheckReport {
+    id: string;
+    version: string;
+    conforms: boolean;
+    rules: string[];
+    problems: CheckProblem[];
+    skipped: Record<string, string>;
 }
 export declare const RULES: readonly CheckRule[];
-export declare const check: (input: CheckInput, rules?: readonly CheckRule[]) => Promise<CheckProblem[]>;
-export declare const assertConforms: (input: CheckInput, rules?: readonly CheckRule[]) => Promise<void>;
+export declare const check: (at: string, options?: CheckOptions) => Promise<CheckReport>;
+export declare const assertConforms: (dir: string, options?: CheckOptions) => Promise<void>;

package/dist/tool/check.js

@@ -1,30 +1,122 @@
+import { readdir } from 'node:fs/promises';
+import { join, normalize, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import semver from 'semver';
 import { checkCli } from '../command/check-cli.js';
-import {} from '../manifest/manifest.schema.js';
-import { imageParts, normalizeParts } from '../manifest/parts.js';
-import { assertBuilt } from './stage.js';
-const problemsOf = (work) => work.then(() => [], (err) => [err.message]);
-// Every image part built where its image looks for it; the cli handlers are exactly the commands.
+import { messageOf } from '../log/log.js';
+import { PackageSchema } from '../manifest/manifest.schema.js';
+import { entryOf, normalizeParts } from '../manifest/parts.js';
+import {} from '../manifest/primitives.schema.js';
+import { formatIssues, readJsonIfExists } from '../manifest/read-manifest.js';
+import { runCommand } from './exec.js';
+import { problemLines } from './format.js';
+import { sealing } from './rules/sealing.js';
+import { store } from './rules/store.js';
+import { surface } from './rules/surface.js';
+import { KIT_VERSION } from './kit-version.js';
+import { assertBuilt, exists } from './stage.js';
+const RECIPE = /^(?:dockerfile|containerfile)(?:\..+)?$|^(?:docker-)?compose(?:\.[\w-]+)?\.ya?ml$/i;
+const NO_PACKAGE = 'is missing: run it in an extension package folder';
+const manifest = {
+    name: 'manifest',
+    run: async ({ dir }) => {
+        const value = await readJsonIfExists(join(dir, 'package.json'));
+        if (value === undefined)
+            return [{ file: 'package.json', problem: NO_PACKAGE }];
+        const issues = PackageSchema.safeParse(value).error?.issues ?? [];
+        const recipes = (await readdir(dir)).filter((file) => RECIPE.test(file)).sort();
+        const recipe = 'is not allowed: the kit writes every image recipe';
+        return [
+            ...issues.map((issue) => ({ problem: formatIssues([issue]) })),
+            ...recipes.map((file) => ({ file, problem: recipe })),
+        ];
+    },
+};
+const exportProblem = async (dir, pkg, part) => {
+    const href = pathToFileURL(join(dir, entryOf(pkg, part))).href;
+    const mod = (await import(href).catch((err) => {
+        throw new Error(`part ${part} fails at import: ${messageOf(err)}`);
+    }));
+    const others = Object.keys(mod).filter((name) => name !== 'create');
+    if (typeof mod.create !== 'function')
+        return `part ${part} does not export create${'create' in mod ? ' as a function' : ''}`;
+    if (others.length > 0)
+        return `part ${part} exports ${others.join(', ')} beside create`;
+    const cli = part === 'cli' ? await checkCli(dir) : null;
+    return cli && `cli part: ${cli}`;
+};
+const partProblem = async ({ dir, pkg }, part) => {
+    if (part !== 'cli')
+        await assertBuilt(dir, pkg, part);
+    else if (!(await exists(join(dir, entryOf(pkg, part)))))
+        return `${normalize(entryOf(pkg, part))} not found: the package build must write the cli part there`;
+    return part === 'ui' ? null : exportProblem(dir, pkg, part);
+};
+// Every part built where its image looks, exporting create and nothing else; cli handlers = commands.
 const entries = {
     name: 'entries',
-    run: async ({ dir, pkg }) => {
-        const built = imageParts(pkg).map((part) => problemsOf(assertBuilt(dir, pkg, part)));
-        const cli = normalizeParts(pkg.agentage.parts).code.cli ? await checkCli(dir) : null;
-        return [...(await Promise.all(built)).flat(), ...(cli ? [`cli part: ${cli}`] : [])];
+    run: async (input) => {
+        if (!(await exists(join(input.dir, 'dist'))))
+            return [{ file: 'dist', problem: 'is missing: build the package first (npm run build)' }];
+        const parts = Object.keys(normalizeParts(input.pkg.agentage.parts).code);
+        const found = parts.map((part) => partProblem(input, part).catch(messageOf));
+        return (await Promise.all(found)).flatMap((problem) => (problem ? [{ problem }] : []));
     },
 };
-// Kit 0.2 has the entries rule; M4 adds manifest, surface, stack, store and sealing beside it.
-export const RULES = [entries];
-export const check = async (input, rules = RULES) => {
-    const found = [];
-    for (const rule of rules)
-        for (const problem of await rule.run(input))
-            found.push({ rule: rule.name, problem });
-    return found;
-};
-// What build runs after the compile and before any image: one failure stops everything.
-export const assertConforms = async (input, rules = RULES) => {
-    const problems = await check(input, rules);
-    if (problems.length === 0)
-        return;
-    throw new Error(`check failed: ${problems.map((p) => `${p.rule}: ${p.problem}`).join('; ')}`);
+const MAJORS = { express: '^5', zod: '^4', '@modelcontextprotocol/server': '^2' };
+const KIT = '@agentage/extension';
+const specProblem = (name, spec, needed) => {
+    if (!spec.trim() || !semver.validRange(spec))
+        return [`${name} ${spec || '""'} needs a version range`];
+    return semver.subset(spec, needed) ? [] : [`${name} ${spec}, needs ${needed}`];
+};
+const stack = {
+    name: 'stack',
+    run: async ({ pkg }) => {
+        const deps = pkg.dependencies ?? {};
+        const range = pkg.engines.agentage;
+        const found = Object.entries({ ...MAJORS, [KIT]: range }).flatMap(([name, needed]) => {
+            const spec = deps[name];
+            // This repo's CI installs the packed kit into a probe clone as a file: tarball.
+            if (spec === undefined || (name === KIT && spec.startsWith('file:')))
+                return [];
+            return specProblem(name, spec, needed);
+        });
+        if ('@modelcontextprotocol/sdk' in deps)
+            found.push('@modelcontextprotocol/sdk is MCP SDK 1: use @modelcontextprotocol/server ^2');
+        if (!semver.satisfies(KIT_VERSION, range))
+            found.push(`kit ${KIT_VERSION} is outside engines.agentage ${range}`);
+        return found.map((problem) => ({ problem }));
+    },
+};
+// The closed list of extension-kit section 7, in its order; build runs it before any image.
+export const RULES = [manifest, entries, surface, stack, store, sealing];
+// A thrown message names its file relative to the package, as every problem line does.
+const runRule = (rule, input) => rule.run(input).catch((err) => [{ problem: messageOf(err).replace(`${input.dir}/`, '') }]);
+export const check = async (at, options = {}) => {
+    const { rules = RULES, run = runCommand } = options;
+    const dir = resolve(at);
+    const read = readJsonIfExists(join(dir, 'package.json')).catch(() => ({}));
+    const pkg = ((await read) ?? {});
+    const problems = [];
+    const skipped = {};
+    for (const rule of rules) {
+        const result = await runRule(rule, { ...options, dir, pkg, run });
+        if ('skipped' in result)
+            skipped[rule.name] = result.skipped;
+        else
+            problems.push(...result.map((found) => ({ rule: rule.name, ...found })));
+        if (rule.name === 'manifest' && problems.length > 0)
+            break;
+    }
+    const names = rules.map((rule) => rule.name);
+    const conforms = problems.length === 0;
+    return { id: pkg.agentage?.id, version: pkg.version, conforms, rules: names, problems, skipped };
+};
+// What build runs after the compile and before any image: any problem stops everything.
+export const assertConforms = async (dir, options = {}) => {
+    const report = await check(dir, { ...options, requireDocker: true });
+    const lines = problemLines(report).map((line) => `check failed: ${line}`);
+    if (!report.conforms)
+        throw new Error(lines.join('\n'));
 };

package/dist/tool/format.d.ts

@@ -1,2 +1,5 @@
 import { type BuildResult } from './build.js';
+import { type CheckReport } from './check.js';
 export declare const buildLines: (result: BuildResult, cwd?: string) => string[];
+export declare const problemLines: (report: CheckReport) => string[];
+export declare const checkLines: (report: CheckReport) => string[];

package/dist/tool/format.js

@@ -1,5 +1,7 @@
 import { relative } from 'node:path';
 import {} from './build.js';
+import {} from './check.js';
+import { plural } from './up/lines.js';
 const shortDigest = (digest) => digest.slice(0, 'sha256:'.length + 8);
 // One line per image, the record path last: what `agentage extension build` prints.
 export const buildLines = (result, cwd = process.cwd()) => {
@@ -12,3 +14,17 @@ export const buildLines = (result, cwd = process.cwd()) => {
         lines.push(`${'record'.padEnd(8)}${relative(cwd, result.recordFile)}`);
     return lines;
 };
+const where = ({ file, line }) => file ? `${file}${line ? `:${line}` : ''} ` : '';
+export const problemLines = (report) => report.problems.map((found) => `${found.rule}: ${where(found)}${found.problem}`);
+// What `agentage extension check` prints (sheet C2): the rules line and PASS, or each problem and FAIL.
+export const checkLines = (report) => {
+    const { rules, skipped, problems } = report;
+    if (report.conforms) {
+        const states = rules.map((name) => `${name} ${skipped[name] ? `skipped: ${skipped[name]}` : 'ok'}`);
+        const pass = `PASS ${report.id} ${report.version} conforms (${plural(rules.length, 'rule')})`;
+        return [states.join(' · '), pass];
+    }
+    const failed = new Set(problems.map((found) => found.rule)).size;
+    const fail = `FAIL ${plural(problems.length, 'problem')} in ${plural(failed, 'rule')}`;
+    return [...problemLines(report), fail];
+};

package/dist/tool/index.d.ts

@@ -3,7 +3,8 @@ 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 { check, type CheckProblem, type CheckReport } from './check.js';
+export { buildLines, checkLines } 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';

package/dist/tool/index.js

@@ -3,7 +3,8 @@ export { runCommand } from '../command/run-command.js';
 export {} from '../manifest/manifest.schema.js';
 export { readManifest, validateManifest } from '../manifest/read-manifest.js';
 export { build, } from './build.js';
-export { buildLines } from './format.js';
+export { check } from './check.js';
+export { buildLines, checkLines } from './format.js';
 export { KIT_VERSION } from './kit-version.js';
 export { down } from './up/down.js';
 export { token } from './up/token.js';

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

@@ -1,5 +1,8 @@
 import { type RecordExtras } from '../discovery/discovery.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type McpContext } from '../mcp/tools.js';
+export declare const recordingContext: (pkg: ExtensionPackage, part: "api" | "mcp") => import("../context/context.js").PartContext;
+export declare const registeredTools: (create: (ctx: McpContext) => unknown, pkg: ExtensionPackage) => Promise<import("../mcp/tools.js").ToolEntry[]>;
 export declare const toolsOf: (dir: string, pkg: ExtensionPackage) => Promise<{
     name: string;
     scope: string;

package/dist/tool/record-extras.js

@@ -16,24 +16,28 @@ import {} from '../store/store.types.js';
 const WidgetsSchema = z.array(WidgetSchema).min(1);
 const noStore = {
     query: async () => {
-        throw new Error('the store is not open while the build lists tools');
+        throw new Error('the store is not open while the tool reads a part');
     },
 };
-const silent = createLog({ extension: 'build', part: 'mcp' }, () => undefined);
-// The tools the mcp part registers and their scopes, read by running its create(ctx) on a recorder.
-export const toolsOf = async (dir, pkg) => {
+const silent = createLog({ extension: 'build', part: 'check' }, () => undefined);
+// The ctx part code gets when the tool runs its create(ctx) to read what it registers or routes.
+export const recordingContext = (pkg, part) => createContext({
+    pkg,
+    part,
+    origin: 'http://127.0.0.1',
+    commit: '0'.repeat(40),
+    log: silent,
+    store: noStore,
+});
+export const registeredTools = async (create, pkg) => {
     const registry = createToolRegistry();
-    const base = createContext({
-        pkg,
-        part: 'mcp',
-        origin: 'http://127.0.0.1',
-        commit: '0'.repeat(40),
-        log: silent,
-        store: noStore,
-    });
-    await (await loadCreate(dir, pkg, 'mcp'))({ ...base, tool: registry.tool });
+    await create({ ...recordingContext(pkg, 'mcp'), tool: registry.tool });
+    return registry.tools;
+};
+export const toolsOf = async (dir, pkg) => {
+    const tools = await registeredTools(await loadCreate(dir, pkg, 'mcp'), pkg);
     const { id } = pkg.agentage;
-    return registry.tools.map((tool) => ({
+    return tools.map((tool) => ({
         name: prefixed(id, tool.name),
         scope: scopeOf(id, tool.spec.scope),
     }));

package/dist/tool/rules/sealing.d.ts

@@ -0,0 +1,2 @@
+import { type CheckRule } from '../check.js';
+export declare const sealing: CheckRule;

package/dist/tool/rules/sealing.js

@@ -0,0 +1,71 @@
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { readJsonIfExists } from '../../manifest/read-manifest.js';
+import {} from '../check.js';
+const CODE = /\.[cm]?[jt]sx?$/;
+const TEST = /\.(test|spec)\.[cm]?[jt]sx?$/;
+// Strings first, so a // inside one is no comment; a comment keeps its newlines for the line count.
+const TOKENS = /'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
+const QUOTED = /'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"/g;
+const QUOTE = '[\'"`]';
+const GLOBAL = String.raw `\b(?:globalThis|global|self)\s*`;
+// A value: read, passed, assigned or listed; not a key, a parameter or a name being declared.
+const VALUE = String.raw `(?=[ \t]*(?:[.[),;\]}]|\?\.|\n|$))(?![ \t]*\}?\s*\)\s*(?:=>|\{|:)|\s*\}\s*[:=](?![=>]))`;
+const PROCESS = String.raw `(?:${GLOBAL}\??\.\s*|(?<![.\w$:/-]|${QUOTE}))process\b${VALUE}`;
+// extension-model section 9: ctx gives a part all it may read, so part code never uses process.
+const ON_CODE = [
+    [
+        new RegExp(String.raw `${PROCESS}(?:\s*(?:\?\.|\.|\[\s*${QUOTE})\s*(env|argv)\b)?`, 'g'),
+        (m) => (m[1] ? `reads process.${m[1]}` : 'names process'),
+    ],
+    [
+        new RegExp(String.raw `${GLOBAL}(?:\?\.)?\s*\[\s*${QUOTE}process${QUOTE}`, 'g'),
+        () => 'names process',
+    ],
+    [/\blisten\s*(?:\?\.\s*)?\(|\[\s*['"`]listen['"`]\s*\]/g, () => 'calls listen()'],
+];
+const ON_STRINGS = [
+    [/(?:from|import|require)\s*\(?\s*['"`](?:node:)?process['"`]/g, () => 'imports process'],
+    [/(?:https?:)?\/\/[^'"`\s]*agentage\.io/gi, () => 'names an absolute agentage URL'],
+];
+const matches = (file, text, patterns) => patterns.flatMap(([pattern, problem]) => [...text.matchAll(pattern)].map((m) => {
+    const line = text.slice(0, m.index).split('\n').length;
+    return { file, line, problem: problem(m) };
+}));
+// Prose strings (with a space) are blanked; a name such as 'env' stays, as dynamic access spells it.
+const fileFindings = (file, text) => {
+    const kept = text.replace(TOKENS, (t) => (t.startsWith('/') ? t.replace(/[^\n]/g, '') : t));
+    const code = kept.replace(QUOTED, (s) => (/\s/.test(s) ? "''" : s));
+    return [...matches(file, code, ON_CODE), ...matches(file, kept, ON_STRINGS)];
+};
+const LINKED = 'is a symlink: part code is plain files';
+// Every non-test source under src/; any symlink met is refused, since it could point anywhere.
+const sourceFindings = async (dir) => {
+    const src = join(dir, 'src');
+    const top = await lstat(src).catch(() => null);
+    if (top?.isSymbolicLink())
+        return [{ file: 'src', problem: LINKED }];
+    const found = top ? await readdir(src, { recursive: true, withFileTypes: true }) : [];
+    const scanned = found.map(async (entry) => {
+        const file = relative(dir, join(entry.parentPath, entry.name));
+        if (entry.isSymbolicLink())
+            return [{ file, problem: LINKED }];
+        if (!entry.isFile() || !CODE.test(entry.name) || TEST.test(entry.name))
+            return [];
+        return fileFindings(file, await readFile(join(dir, file), 'utf8'));
+    });
+    return (await Promise.all(scanned)).flat();
+};
+const extensionDeps = async (dir, pkg) => {
+    const { dependencies, optionalDependencies, peerDependencies } = pkg;
+    const names = Object.keys({ ...dependencies, ...optionalDependencies, ...peerDependencies });
+    const read = (name) => readJsonIfExists(join(dir, 'node_modules', name, 'package.json'));
+    const manifests = await Promise.all(names.map(read));
+    return names
+        .filter((_, i) => Object.hasOwn(Object(manifests[i]), 'agentage'))
+        .map((name) => ({ problem: `depends on another extension, ${name}` }));
+};
+export const sealing = {
+    name: 'sealing',
+    run: async ({ dir, pkg }) => [...(await sourceFindings(dir)), ...(await extensionDeps(dir, pkg))],
+};

package/dist/tool/rules/store.d.ts

@@ -0,0 +1,2 @@
+import { type CheckRule } from '../check.js';
+export declare const store: CheckRule;

package/dist/tool/rules/store.js

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { hasPostgres } from '../../manifest/parts.js';
+import { sqlFiles } from '../../store/migrations.js';
+import {} from '../check.js';
+import {} from '../exec.js';
+import { TIMEOUTS } from '../timeouts.js';
+import { STORE_IMAGE } from '../up/compose.js';
+const PSQL = 'psql -v ON_ERROR_STOP=1 -1 -q -U postgres -f "/tmp/m/$f" || exit 1';
+const AS_POSTGRES = `initdb -D /tmp/pg -U postgres -A trust >/dev/null && pg_ctl -D /tmp/pg -w -l /tmp/pg.log start >/dev/null && for f in "$@"; do ${PSQL}; done`;
+// Root copies the files where postgres can read them (a 0600 checkout); the names, held to NNN-name.sql, are its arguments.
+const SCRIPT = `cp -r /migrations /tmp/m && chmod -R a+rX /tmp/m && exec su postgres -s /bin/sh -c '${AS_POSTGRES}' sh "$@"`;
+// Attached with --rm and --init: the container goes with this process, Ctrl-C included.
+const runArgs = (dir, files) => [
+    ...['run', '--rm', '--init', '-e', 'TINI_KILL_PROCESS_GROUP=1', '--network', 'none'],
+    ...['-v', `${resolve(dir, 'migrations')}:/migrations:ro`, '--entrypoint', 'sh'],
+    ...[STORE_IMAGE, '-c', SCRIPT, 'sh', ...files],
+];
+const failure = (stderr = '') => {
+    const daemon = /^docker: (.*)$/m.exec(stderr)?.[1];
+    if (daemon)
+        return { problem: `${STORE_IMAGE} does not run: ${daemon}` };
+    const [, file, line, why] = /^psql:\/tmp\/m\/([^:]+):(\d+): (?:ERROR:\s+)?(.*)$/m.exec(stderr) ?? [];
+    const problem = `fails on ${STORE_IMAGE}: ${why ? `ERROR: ${why}` : stderr.trim().split('\n').pop()}`;
+    return file ? { file: `migrations/${file}`, line: Number(line), problem } : { problem };
+};
+// Quoted text, dollar-quoted bodies and comments, blanked to their newlines before looking for a backslash.
+const SQL_TEXT = /'(?:[^']|'')*'|"(?:[^"]|"")*"|\$(\w*)\$[\s\S]*?\$\1\$|--[^\n]*|\/\*[\s\S]*?\*\//g;
+// The migrate job sends each file through pg as plain SQL, so a psql meta-command would fail there.
+const metaCommands = async (dir, files) => {
+    const texts = await Promise.all(files.map((f) => readFile(join(dir, 'migrations', f), 'utf8')));
+    return files.flatMap((f, i) => {
+        const code = (texts[i] ?? '').replace(SQL_TEXT, (t) => t.replace(/[^\n]/g, ''));
+        const at = code.indexOf('\\');
+        const problem = 'has a psql meta-command: the migrate job sends plain SQL';
+        const line = code.slice(0, at).split('\n').length;
+        return at < 0 ? [] : [{ file: `migrations/${f}`, line, problem }];
+    });
+};
+const dockerAnswers = (run) => run('docker', ['version'], { quiet: true }).then(({ code }) => code === 0, () => false);
+export const store = {
+    name: 'store',
+    run: async ({ dir, pkg, run, requireDocker }) => {
+        if (!hasPostgres(pkg))
+            return { skipped: 'no store' };
+        const files = await sqlFiles(join(dir, 'migrations'));
+        const meta = await metaCommands(dir, files);
+        if (files.length === 0 || meta.length > 0)
+            return meta;
+        if (!(await dockerAnswers(run)))
+            return requireDocker
+                ? [{ problem: 'docker does not answer: build needs it' }]
+                : { skipped: 'no docker' };
+        const result = await run('docker', runArgs(dir, files), {
+            quiet: true,
+            timeoutMs: TIMEOUTS.start,
+        });
+        return result.code === 0 ? [] : [failure(result.stderr)];
+    },
+};

package/dist/tool/rules/surface.d.ts

@@ -0,0 +1,2 @@
+import { type CheckRule } from '../check.js';
+export declare const surface: CheckRule;

package/dist/tool/rules/surface.js

@@ -0,0 +1,89 @@
+import { join } from 'node:path';
+import {} from '../../context/context.js';
+import { OPENAPI_FILE, readOpenapi } from '../../discovery/openapi.js';
+import { loadCreate } from '../../manifest/entry.js';
+import { normalizeParts } from '../../manifest/parts.js';
+import { readJsonIfExists } from '../../manifest/read-manifest.js';
+import { canonical } from '../../mcp/snapshot.js';
+import { prefixed } from '../../mcp/tools.js';
+import {} from '../check.js';
+import { recordingContext, registeredTools } from '../record-extras.js';
+const differing = (generated, committed) => [...new Set([...Object.keys(generated), ...Object.keys(committed)])].filter((key) => JSON.stringify(canonical(generated[key])) !== JSON.stringify(canonical(committed[key])));
+const routeKeys = ({ path, stack }) => [path].flat().flatMap((one) => {
+    const at = `/api/v1${String(one).replace(/:(\w+)/g, '{$1}')}`;
+    // router.all names no method, so it has no operation to compare.
+    return stack.flatMap(({ method }) => (method ? [`${method.toUpperCase()} ${at}`] : []));
+});
+// Express routes (of a Router or an express() app) as OpenAPI keys; a sub-router hides its routes, so it never matches one.
+const servedRoutes = (app) => {
+    const { stack, router } = (app ?? {});
+    return (stack ?? router?.stack ?? []).flatMap(({ name, route, handle }) => {
+        if (route)
+            return routeKeys(route);
+        return handle?.stack ? [`${name} sub-router`] : [];
+    });
+};
+const METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+const operations = (doc) => Object.entries((doc['paths'] ?? {})).flatMap(([path, ops]) => Object.entries(ops ?? {})
+    .filter(([method]) => METHODS.has(method))
+    .map(([method, op]) => [`${method.toUpperCase()} ${path}`, op]));
+const declaresAccess = (security) => Array.isArray(security) &&
+    (security.length === 0 ||
+        security.some((need) => Object.values(need ?? {}).some((s) => s.length > 0)));
+const apiProblems = (doc, routes, version) => {
+    const ops = operations(doc);
+    const served = new Set([`info.version ${version}`, ...routes]);
+    const info = doc['info']?.['version'];
+    const documented = new Set([`info.version ${String(info)}`, ...ops.map(([key]) => key)]);
+    const diff = [...served, ...documented].filter((k) => !served.has(k) || !documented.has(k));
+    const open = ops.filter(([, op]) => !declaresAccess(op['security'] ?? doc['security']));
+    return [
+        ...(diff.length > 0 ? [`differs from the generated contract (${diff.join(', ')})`] : []),
+        ...open.map(([key]) => `${key} declares neither a scope nor security: []`),
+    ];
+};
+const apiSurface = async ({ dir, pkg }) => {
+    const create = await loadCreate(dir, pkg, 'api').catch(() => null);
+    if (!create)
+        return [];
+    const doc = await readOpenapi(dir);
+    const found = doc
+        ? apiProblems(doc, servedRoutes(await create(recordingContext(pkg, 'api'))), pkg.version)
+        : ['is missing: the api part commits its contract'];
+    return found.map((problem) => ({ file: OPENAPI_FILE, problem }));
+};
+const schemaOf = (zod, io) => zod['~standard'].jsonSchema[io]({ target: 'draft-2020-12' });
+const listed = (id, { name, spec }) => ({
+    name: prefixed(id, name),
+    description: spec.description,
+    inputSchema: schemaOf(spec.input, 'input'),
+    outputSchema: schemaOf(spec.output, 'output'),
+});
+const byName = ({ serverInfo, tools }) => ({
+    serverInfo,
+    ...Object.fromEntries(tools.map((tool) => [String(tool['name']), tool])),
+});
+const mcpSurface = async ({ dir, pkg }) => {
+    const create = await loadCreate(dir, pkg, 'mcp').catch(() => null);
+    if (!create)
+        return [];
+    const { id } = pkg.agentage;
+    const file = `${id}.mcpc.json`;
+    const committed = (await readJsonIfExists(join(dir, file)));
+    if (!committed)
+        return [{ file, problem: 'is missing: the mcp part commits its tool list' }];
+    const tools = (await registeredTools(create, pkg)).map((tool) => listed(id, tool));
+    const serverInfo = { name: `agentage-${id}`, version: pkg.version };
+    const diff = differing(byName({ serverInfo, tools }), byName(committed));
+    const problem = `differs from the generated tool list (${diff.join(', ')})`;
+    return diff.length > 0 ? [{ file, problem }] : [];
+};
+// The committed contracts equal what the code serves; entries names a part that does not load.
+export const surface = {
+    name: 'surface',
+    run: async (input) => {
+        const { code } = normalizeParts(input.pkg.agentage.parts);
+        const api = code.api ? await apiSurface(input) : [];
+        return [...api, ...(code.mcp ? await mcpSurface(input) : [])];
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/extension",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "The agentage extension kit: create(ctx) per part (pages, ui, api, mcp, worker, cli), the store, /health, discovery, the envelope, and the build tool with up and token",
   "type": "module",
   "license": "MIT",
@@ -44,7 +44,8 @@
     "build": "tsc -b",
     "schemas": "node dist/schemas/write-schemas.js schemas",
     "verify": "npm run verify --prefix ../..",
-    "prepublishOnly": "npm run verify"
+    "prepublishOnly": "npm run verify",
+    "check:fixtures": "vitest run --root ../.. --reporter=tree packages/extension/src/tool/check.fixtures.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.4.0",
@@ -52,6 +53,7 @@
     "helmet": "^8.1.0",
     "jose": "^6.2.15",
     "pg": "^8.23.1",
+    "semver": "^7.8.6",
     "zod": "^4.2.0"
   },
   "peerDependencies": {