@agentage/extension 0.4.0 → 0.4.2

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/command/args.js

@@ -2,7 +2,7 @@ import { parseArgs } from 'node:util';
 import {} from '../manifest/manifest.schema.js';
 export class UsageError extends Error {
 }
-export const isOptional = (arg) => arg.optional === true || arg.required === false;
+export const isOptional = (arg) => arg.required === false;
 const coerce = (arg, raw) => {
     if (arg.type === 'boolean')
         return raw === true || raw === 'true';

package/dist/manifest/manifest.schema.d.ts

@@ -44,7 +44,6 @@ declare const CommandSchema: z.ZodObject<{
             boolean: "boolean";
             integer: "integer";
         }>;
-        optional: z.ZodOptional<z.ZodBoolean>;
         required: z.ZodOptional<z.ZodBoolean>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
@@ -99,7 +98,6 @@ export declare const PackageSchema: z.ZodObject<{
                     boolean: "boolean";
                     integer: "integer";
                 }>;
-                optional: z.ZodOptional<z.ZodBoolean>;
                 required: z.ZodOptional<z.ZodBoolean>;
                 description: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;

package/dist/manifest/manifest.schema.js

@@ -27,7 +27,6 @@ const CommandSchema = z.strictObject({
         .array(z.strictObject({
         name: CommandNameSchema,
         type: ArgTypeSchema,
-        optional: z.boolean().optional(),
         required: z.boolean().optional(),
         description: z.string().min(1).max(200).optional(),
     }))

package/dist/mcp/mcp-app.js

@@ -39,10 +39,11 @@ const guard = async (options, req, body) => {
     if (!options.tokenCheck) {
         if (listing.length > 0)
             throw fail('UNAUTHORIZED', 'tools/list needs a token');
-        return;
+        return false;
     }
-    if (needed.length > 0)
-        await options.tokenCheck(req.get('authorization'), strongest(needed));
+    if (needed.length === 0)
+        return false;
+    return (await options.tokenCheck(req.get('authorization'), strongest(needed))) !== null;
 };
 const webRequest = (req, body) => {
     const headers = new Headers();
@@ -56,9 +57,12 @@ const webRequest = (req, body) => {
         body,
     });
 };
-const send = async (response, res) => {
+const send = async (response, res, auth) => {
     res.status(response.status);
     response.headers.forEach((value, key) => void res.setHeader(key, value));
+    // After the SDK headers: its SSE answer sets no-cache, which a token-checked answer overrides.
+    if (auth)
+        res.setHeader('Cache-Control', 'no-store');
     if (!response.body)
         return void res.end();
     await pipeline(Readable.fromWeb(response.body), res);
@@ -69,8 +73,8 @@ const handle = (handler, options) => async (req, res) => {
     // The SDK reads a body again when given none (a BOM, say): it must only run what guard read.
     if (message === undefined)
         return void res.status(400).json(PARSE_ERROR);
-    await guard(options, req, message);
-    await send(await handler.fetch(webRequest(req, body), { parsedBody: message }), res);
+    const auth = await guard(options, req, message);
+    await send(await handler.fetch(webRequest(req, body), { parsedBody: message }), res, auth);
 };
 const methodNotAllowed = (_req, res) => {
     res.setHeader('Allow', 'POST');

package/dist/server/app.js

@@ -57,11 +57,14 @@ export const createPartApp = (options) => {
 // The committed OpenAPI document, bare JSON and anonymous like discovery (api-standards section 1).
 const openapiHandler = (doc) => (_req, res) => void res.json(doc);
 // Before the body is read: each request checked for the access its OpenAPI operation declares.
-const routeGuard = (options) => async (req, _res, next) => {
+const routeGuard = (options) => async (req, res, next) => {
     if (!options.tokenCheck)
         return next();
     const access = routeAccess(options.openapi, req.method, `/api/v1${req.path}`);
-    setCaller(req, await options.tokenCheck(req.get('authorization'), access));
+    const caller = await options.tokenCheck(req.get('authorization'), access);
+    if (caller)
+        res.setHeader('Cache-Control', 'no-store');
+    setCaller(req, caller);
     next();
 };
 export const createApiApp = (options) => createPartApp({

package/dist/server/errors.js

@@ -19,7 +19,19 @@ const toFailure = (err) => {
 export const notFound = () => {
     throw fail('NOT_FOUND', 'Not found');
 };
+const GONE_CODES = ['ERR_STREAM_PREMATURE_CLOSE', 'ECONNABORTED'];
+// A client abort leaves the socket destroyed; the same code from an app-side stream does not.
+const clientGone = (err, res) => GONE_CODES.includes(err?.code) && res.socket?.destroyed !== false;
 export const errorHandler = (log) => (err, _req, res, _next) => {
+    // A gone client or a started answer cannot take an envelope: close it, never write twice.
+    const gone = clientGone(err, res);
+    if (gone || res.headersSent) {
+        if (gone)
+            log.warn('client closed early');
+        else
+            log.error(err);
+        return void res.destroy();
+    }
     const failure = toFailure(err);
     if (failure.status >= 500)
         log.error(err);

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/exec.js

@@ -51,7 +51,8 @@ const tail = (text) => text ? `\n${text.trim().split('\n').slice(-15).join('\n')
 export const mustRun = async (run, command, args, options) => {
     const result = await run(command, args, options);
     if (result.code !== 0) {
-        throw new Error(`${command} ${args[0] ?? ''} failed with exit code ${result.code}${tail(result.stderr)}`);
+        // tsc writes its diagnostics to stdout, so an empty stderr falls back to it.
+        throw new Error(`${command} ${args[0] ?? ''} failed with exit code ${result.code}${tail(result.stderr?.trim() ? result.stderr : result.stdout)}`);
     }
     return result.stdout;
 };

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.2",
   "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",

package/schemas/extension-package.schema.json

@@ -213,9 +213,6 @@
                         "boolean"
                       ]
                     },
-                    "optional": {
-                      "type": "boolean"
-                    },
                     "required": {
                       "type": "boolean"
                     },