@agentage/extension 0.4.0 → 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/check.d.ts

@@ -5,16 +5,16 @@ export interface CheckOptions {
     requireDocker?: boolean;
     rules?: readonly CheckRule[];
 }
-export interface CheckInput extends CheckOptions {
+export type CheckInput = CheckOptions & {
     dir: string;
     pkg: ExtensionPackage;
     run: Run;
-}
-export interface Finding {
+};
+export type Finding = {
     file?: string;
     line?: number;
     problem: string;
-}
+};
 export type CheckProblem = Finding & {
     rule: string;
 };
@@ -33,5 +33,5 @@ export interface CheckReport {
     skipped: Record<string, string>;
 }
 export declare const RULES: readonly CheckRule[];
-export declare const check: (dir: string, options?: CheckOptions) => Promise<CheckReport>;
+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,5 +1,5 @@
 import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, normalize, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import semver from 'semver';
 import { checkCli } from '../command/check-cli.js';
@@ -14,14 +14,15 @@ 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 } from './stage.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')).catch((err) => {
-            throw new Error(messageOf(err).replace(`${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';
@@ -31,32 +32,35 @@ const manifest = {
         ];
     },
 };
-const problemsOf = (work) => work.then((found) => (Array.isArray(found) ? found : []), (err) => [messageOf(err)]);
-const exportProblems = async (dir, pkg, part) => {
-    const mod = (await import(pathToFileURL(join(dir, entryOf(pkg, part))).href));
-    const names = Object.keys(mod);
-    if (!names.includes('create'))
-        return [`part ${part} does not export create`];
+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} create is not a function`];
-    const others = names.filter((name) => name !== 'create');
-    return others.length > 0 ? [`part ${part} exports ${others.join(', ')} beside create`] : [];
+        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 partProblems = async ({ dir, pkg }, part) => {
-    const built = part === 'cli' ? [] : await problemsOf(assertBuilt(dir, pkg, part));
-    if (built.length > 0 || part === 'ui')
-        return built;
-    const own = await problemsOf(exportProblems(dir, pkg, part));
-    const cli = own.length === 0 && part === 'cli' ? await checkCli(dir) : null;
-    return cli ? [`cli part: ${cli}`] : own;
+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 (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 = await Promise.all(parts.map((part) => partProblems(input, part)));
-        return found.flat().map((problem) => ({ problem }));
+        const found = parts.map((part) => partProblem(input, part).catch(messageOf));
+        return (await Promise.all(found)).flatMap((problem) => (problem ? [{ problem }] : []));
     },
 };
 const MAJORS = { express: '^5', zod: '^4', '@modelcontextprotocol/server': '^2' };
@@ -87,9 +91,11 @@ const stack = {
 };
 // 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];
-const runRule = (rule, input) => rule.run(input).catch((err) => [{ problem: messageOf(err) }]);
-export const check = async (dir, options = {}) => {
+// 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 = [];

package/dist/tool/rules/store.js

@@ -1,6 +1,5 @@
 import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { messageOf } from '../../log/log.js';
 import { hasPostgres } from '../../manifest/parts.js';
 import { sqlFiles } from '../../store/migrations.js';
 import {} from '../check.js';
@@ -18,6 +17,9 @@ const runArgs = (dir, files) => [
     ...[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 };
@@ -36,15 +38,12 @@ const metaCommands = async (dir, files) => {
     });
 };
 const dockerAnswers = (run) => run('docker', ['version'], { quiet: true }).then(({ code }) => code === 0, () => false);
-const migrationFiles = (dir) => sqlFiles(join(dir, 'migrations')).catch((err) => {
-    throw new Error(messageOf(err).replace(join(dir, 'migrations'), 'migrations'));
-});
 export const store = {
     name: 'store',
     run: async ({ dir, pkg, run, requireDocker }) => {
         if (!hasPostgres(pkg))
             return { skipped: 'no store' };
-        const files = await migrationFiles(dir);
+        const files = await sqlFiles(join(dir, 'migrations'));
         const meta = await metaCommands(dir, files);
         if (files.length === 0 || meta.length > 0)
             return meta;

package/dist/tool/rules/surface.js

@@ -14,13 +14,15 @@ const routeKeys = ({ path, stack }) => [path].flat().flatMap((one) => {
     // router.all names no method, so it has no operation to compare.
     return stack.flatMap(({ method }) => (method ? [`${method.toUpperCase()} ${at}`] : []));
 });
-const stackOf = (router) => router?.stack;
 // 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 = (router) => (stackOf(router) ?? stackOf(router?.router) ?? []).flatMap(({ name, route, handle }) => {
-    if (route)
-        return routeKeys(route);
-    return handle?.stack ? [`${name} sub-router`] : [];
-});
+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))
@@ -33,8 +35,7 @@ const apiProblems = (doc, routes, version) => {
     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].filter((k) => !documented.has(k));
-    diff.push(...[...documented].filter((k) => !served.has(k)));
+    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(', ')})`] : []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/extension",
-  "version": "0.4.0",
+  "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",