@agentage/extension 0.1.1 → 0.2.0

package/dist/discovery/discovery.js

@@ -1,34 +1,33 @@
-import { readFile } from 'node:fs/promises';
-import { formatIssues } from '../manifest/read-manifest.js';
+import { formatIssues, readJsonIfExists } from '../manifest/read-manifest.js';
 import {} from '../manifest/manifest.schema.js';
 import { normalizeParts } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
 import { ExtensionRecordSchema } from './discovery.schema.js';
 export const DEFAULT_RECORD_FILE = '/run/agentage/agentage-extension.json';
-const commandNames = (pkg) => {
-    const names = (pkg.agentage.commands ?? []).map((command) => command.name);
-    return names.length > 0 ? names : undefined;
-};
-const partsOf = (pkg, images) => {
+const partsOf = (pkg, images, migrations) => {
     const parts = {};
     for (const [kind, image] of Object.entries(images))
         parts[kind] = { image };
     const store = normalizeParts(pkg.agentage.parts).store;
     if (store)
-        parts['store'] = { kind: store };
+        parts['store'] = migrations === undefined ? { kind: store } : { kind: store, migrations };
     return parts;
 };
-// From the manifest, the build and the pushed images by digest; OpenAPI, tools, widgets come later.
-export const recordOf = (pkg, build, images) => {
-    const record = {
-        id: pkg.agentage.id,
-        version: pkg.version,
-        commit: build.commit,
-        buildTime: build.buildTime,
-        parts: partsOf(pkg, images),
-        commands: commandNames(pkg),
-    };
-    return JSON.parse(JSON.stringify(record));
+// From the manifest, the build, the images by digest and what the code serves; OpenAPI comes later.
+export const recordOf = (pkg, build, images, extras = {}) => {
+    const { id, commands } = pkg.agentage;
+    const { commit, buildTime } = build;
+    const parts = partsOf(pkg, images, extras.migrations);
+    const record = { id, version: pkg.version, commit, buildTime, parts };
+    if (extras.openapi)
+        record.openapi = extras.openapi;
+    if (extras.tools)
+        record.tools = extras.tools;
+    if (commands)
+        record.commands = commands.map((command) => command.name);
+    if (extras.widgets)
+        record.widgets = extras.widgets;
+    return record;
 };
 export const validateRecord = (value) => {
     const result = ExtensionRecordSchema.safeParse(value);
@@ -36,15 +35,10 @@ export const validateRecord = (value) => {
         return result.data;
     throw new Error(`invalid extension record: ${formatIssues(result.error.issues)}`);
 };
+// No file means no record is mounted; any other read error stops the part from starting.
 export const loadRecord = async (file) => {
-    let text;
-    try {
-        text = await readFile(file, 'utf8');
-    }
-    catch {
-        return null; // no record mounted: discovery lists the part's own image by tag
-    }
-    return validateRecord(JSON.parse(text));
+    const record = await readJsonIfExists(file);
+    return record === undefined ? null : validateRecord(record);
 };
 export const discoveryDocument = (record, host) => {
     const { id, version, commit, buildTime, ...rest } = record;

package/dist/discovery/discovery.schema.d.ts

@@ -1,30 +1,4 @@
 import { z } from 'zod';
-export declare const ImageDigestRefSchema: z.ZodString;
-export declare const PartsRecordSchema: z.ZodObject<{
-    pages: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    ui: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    api: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    mcp: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    worker: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    store: z.ZodOptional<z.ZodObject<{
-        kind: z.ZodEnum<{
-            postgres: "postgres";
-            git: "git";
-            signoz: "signoz";
-        }>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export declare const OriginSchema: z.ZodString;
 export declare const ExtensionRecordSchema: z.ZodObject<{
     id: z.ZodString;
     version: z.ZodString;
@@ -52,6 +26,7 @@ export declare const ExtensionRecordSchema: z.ZodObject<{
                 git: "git";
                 signoz: "signoz";
             }>;
+            migrations: z.ZodOptional<z.ZodInt>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;
@@ -91,6 +66,7 @@ export declare const DiscoveryDocumentSchema: z.ZodObject<{
                 git: "git";
                 signoz: "signoz";
             }>;
+            migrations: z.ZodOptional<z.ZodInt>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;

package/dist/discovery/discovery.schema.js

@@ -1,24 +1,26 @@
 import { z } from 'zod';
 import { CommandNameSchema, CommitSchema, ExtensionIdSchema, IMAGE_PART_KINDS, PrefixedToolNameSchema, StoreKindSchema, VersionSchema, } from '../manifest/primitives.schema.js';
 // registry host[:port]/owner/{id}-{part}@sha256: deployed by digest, a version's images never change.
-export const ImageDigestRefSchema = z
+const ImageDigestRefSchema = z
     .string()
     .max(256)
     .regex(/^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?\/[a-z0-9][a-z0-9-]*\/[a-z][a-z0-9-]*-(pages|ui|api|mcp|worker)@sha256:[0-9a-f]{64}$/);
 const PartImageSchema = z.strictObject({ image: ImageDigestRefSchema });
-export const PartsRecordSchema = z
+const PartsRecordSchema = z
     .strictObject({
     pages: PartImageSchema.optional(),
     ui: PartImageSchema.optional(),
     api: PartImageSchema.optional(),
     mcp: PartImageSchema.optional(),
     worker: PartImageSchema.optional(),
-    store: z.strictObject({ kind: StoreKindSchema }).optional(),
+    store: z
+        .strictObject({ kind: StoreKindSchema, migrations: z.int().min(0).optional() })
+        .optional(),
 })
     .refine((parts) => IMAGE_PART_KINDS.some((kind) => parts[kind] !== undefined), {
     message: 'at least one part with an image',
 });
-export const OriginSchema = z
+const OriginSchema = z
     .string()
     .max(270)
     .regex(/^(https:\/\/[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+|http:\/\/(127\.0\.0\.1|localhost))(:[0-9]{1,5})?$/);

package/dist/discovery/openapi.d.ts

@@ -0,0 +1,3 @@
+export declare const OPENAPI_FILE = "openapi.json";
+export declare const OPENAPI_PATH = "/api/v1/openapi.json";
+export declare const readOpenapi: (dir: string) => Promise<Record<string, unknown> | null>;

package/dist/discovery/openapi.js

@@ -0,0 +1,19 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { readJsonIfExists } from '../manifest/read-manifest.js';
+export const OPENAPI_FILE = 'openapi.json';
+export const OPENAPI_PATH = '/api/v1/openapi.json';
+const OpenapiSchema = z.looseObject({
+    openapi: z.string().regex(/^3\.1\.[0-9]+$/, { message: 'OpenAPI 3.1' }),
+    paths: z.record(z.string(), z.unknown()),
+});
+// The api's contract, committed beside package.json (the repo diffs it against its Zod schemas).
+export const readOpenapi = async (dir) => {
+    const value = await readJsonIfExists(join(dir, OPENAPI_FILE));
+    if (value === undefined)
+        return null;
+    const result = OpenapiSchema.safeParse(value);
+    if (!result.success)
+        throw new Error(`${OPENAPI_FILE} is not an OpenAPI 3.1 document`);
+    return result.data;
+};

package/dist/envelope/envelope.js

@@ -1,4 +1,5 @@
 import { DEFAULT_RETRY_AFTER_SECONDS, ERROR_STATUS, RETRY_AFTER_CODES, } from './codes.js';
+// A registry symbol, so a failure thrown through a second copy of the kit is still recognised.
 const FAILURE = Symbol.for('agentage.extension.failure');
 export const ok = (data, meta) => meta === undefined ? { success: true, data } : { success: true, data, meta };
 const retryAfterOf = (code, given) => {

package/dist/envelope/envelope.schema.d.ts

@@ -1,8 +1,4 @@
 import { z } from 'zod';
-export declare const AgcidSchema: z.ZodString;
-export declare const ErrorCodeSchema: z.ZodEnum<{
-    [x: string]: string;
-}>;
 export declare const ErrorEnvelopeSchema: z.ZodObject<{
     success: z.ZodLiteral<false>;
     error: z.ZodObject<{

package/dist/envelope/envelope.schema.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+import { AGCID_PATTERN } from '../agcid/agcid.js';
 import { ERROR_CODES } from './codes.js';
-export const AgcidSchema = z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/);
-export const ErrorCodeSchema = z.enum(ERROR_CODES);
+const AgcidSchema = z.string().regex(AGCID_PATTERN);
+const ErrorCodeSchema = z.enum(ERROR_CODES);
 export const ErrorEnvelopeSchema = z.strictObject({
     success: z.literal(false),
     error: z.strictObject({

package/dist/health/health.d.ts

@@ -1,10 +1,11 @@
 import { type RequestHandler } from 'express';
 import { type BuildInfo } from '../discovery/discovery.js';
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type HealthBody, type HealthStatus } from './health.schema.js';
 export type HealthCheck = () => Promise<HealthStatus>;
 export interface HealthOptions {
     extension: string;
-    part: 'api' | 'mcp' | 'worker' | 'pages' | 'ui';
+    part: ImagePartKind;
     version: string;
     build: BuildInfo;
     checks?: Record<string, HealthCheck>;
@@ -13,6 +14,8 @@ export interface HealthOptions {
     now?: () => Date;
 }
 export declare const worstOf: (statuses: HealthStatus[]) => HealthStatus;
+export declare const CHECK_TIMEOUT_MS = 1000;
 export declare const isLoopback: (address: string | undefined) => boolean;
-export declare const healthBody: (options: HealthOptions) => Promise<HealthBody>;
+export type ResolvedHealth = HealthOptions & Required<Pick<HealthOptions, 'instance' | 'startedAt'>>;
+export declare const healthBody: (options: ResolvedHealth) => Promise<HealthBody>;
 export declare const createHealthHandler: (options: HealthOptions) => RequestHandler;

package/dist/health/health.js

@@ -2,25 +2,40 @@ import { randomBytes } from 'node:crypto';
 import {} from 'express';
 import {} from '../discovery/discovery.js';
 import { fail } from '../envelope/envelope.js';
+import {} from '../manifest/primitives.schema.js';
+import { isoSeconds } from '../runtime/build-info.js';
 import {} from './health.schema.js';
 const RANK = { ok: 0, degraded: 1, unavailable: 2 };
 export const worstOf = (statuses) => statuses.reduce((worst, s) => (RANK[s] > RANK[worst] ? s : worst), 'ok');
+// Under the recipe's HEALTHCHECK --timeout=3s: a hung check reads unavailable, never a hung probe.
+export const CHECK_TIMEOUT_MS = 1000;
+const settle = async (check) => {
+    let timer;
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('unavailable'), CHECK_TIMEOUT_MS).unref();
+    });
+    try {
+        return await Promise.race([check(), expiry]);
+    }
+    catch {
+        return 'unavailable';
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
 const runChecks = async (checks) => {
-    const entries = await Promise.all(Object.entries(checks).map(async ([name, check]) => {
-        const status = await check().catch(() => 'unavailable');
-        return [name, status];
-    }));
+    const entries = await Promise.all(Object.entries(checks).map(async ([name, check]) => [name, await settle(check)]));
     return Object.fromEntries(entries);
 };
-const isoSeconds = (date) => `${date.toISOString().slice(0, 19)}Z`;
 export const isLoopback = (address) => address !== undefined && /^(127\.|::1$|::ffff:127\.)/.test(address);
 export const healthBody = async (options) => {
     const now = (options.now ?? (() => new Date()))();
     const checks = await runChecks(options.checks ?? {});
     const status = worstOf(Object.values(checks));
-    const { extension, part, version, build } = options;
-    const uptimeSeconds = Math.max(0, Math.floor((now.getTime() - (options.startedAt ?? 0)) / 1000));
-    const data = { status, extension, part, version, ...build, instance: options.instance ?? '' };
+    const { extension, part, version, build, instance } = options;
+    const uptimeSeconds = Math.max(0, Math.floor((now.getTime() - options.startedAt) / 1000));
+    const data = { status, extension, part, version, ...build, instance };
     return {
         success: status !== 'unavailable',
         data: { ...data, uptimeSeconds, checkedAt: isoSeconds(now), checks },

package/dist/health/health.schema.d.ts

@@ -1,17 +1,9 @@
 import { z } from 'zod';
-export declare const HealthStatusSchema: z.ZodEnum<{
+declare const HealthStatusSchema: z.ZodEnum<{
     ok: "ok";
     degraded: "degraded";
     unavailable: "unavailable";
 }>;
-export declare const DeployedPartKindSchema: z.ZodEnum<{
-    pages: "pages";
-    ui: "ui";
-    api: "api";
-    mcp: "mcp";
-    worker: "worker";
-    store: "store";
-}>;
 export declare const HealthSchema: z.ZodObject<{
     success: z.ZodBoolean;
     data: z.ZodObject<{
@@ -44,3 +36,4 @@ export declare const HealthSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type HealthStatus = z.infer<typeof HealthStatusSchema>;
 export type HealthBody = z.infer<typeof HealthSchema>;
+export {};

package/dist/health/health.schema.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { ExtensionIdSchema, VersionSchema } from '../manifest/primitives.schema.js';
-export const HealthStatusSchema = z.enum(['ok', 'degraded', 'unavailable']);
-export const DeployedPartKindSchema = z.enum(['pages', 'ui', 'api', 'mcp', 'worker', 'store']);
+const HealthStatusSchema = z.enum(['ok', 'degraded', 'unavailable']);
+const DeployedPartKindSchema = z.enum(['pages', 'ui', 'api', 'mcp', 'worker', 'store']);
 // GET /health of every part container (api-standards section 7); never hostnames, IPs or env values.
 export const HealthSchema = z.strictObject({
     success: z.boolean(),
@@ -15,6 +15,6 @@ export const HealthSchema = z.strictObject({
         instance: z.string().regex(/^[0-9a-f]{8,32}$/),
         uptimeSeconds: z.int().min(0),
         checkedAt: z.iso.datetime(),
-        checks: z.record(z.string().regex(/^[a-z][a-z0-9-]*$/), HealthStatusSchema),
+        checks: z.record(z.string().regex(/^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$/), HealthStatusSchema),
     }),
 });

package/dist/index.d.ts

@@ -1,19 +1,26 @@
-export { AGCID_HEADER, agcidOf, isAgcid, uuidv7 } from './agcid/agcid.js';
-export { currentAgcid } from './agcid/scope.js';
-export { createContext, createTestContext, type ExtensionInfo, type LogEntry, type PartContext, type ServerPartKind, type SettingValue, type TestContext, type TestContextOptions, } from './context/context.js';
-export { DEFAULT_RECORD_FILE, discoveryDocument, loadRecord, recordOf, validateRecord, type BuildInfo, type PartImages, } from './discovery/discovery.js';
+export { type ArgValue } from './command/args.js';
+export { type CliContext, type CliCreate, type CommandExtension, type CommandHandler, } from './command/command.types.js';
+export { type Out } from './command/out.js';
+export { type ExtensionInfo, type PartContext, type ServerPartKind, type SettingValue, } from './context/context.js';
+export { createTestContext, type LogEntry, type TestCommandContext, type TestCommandOptions, type TestContext, type TestContextOptions, } from './context/test-context.js';
 export { DiscoveryDocumentSchema, ExtensionRecordSchema, type DiscoveryDocument, type ExtensionRecord, } from './discovery/discovery.schema.js';
+export { AGCID_HEADER, isAgcid } from './agcid/agcid.js';
 export { ERROR_CODES, ERROR_STATUS, type ErrorCode } from './envelope/codes.js';
-export { errorEnvelope, fail, isFailure, ok, type ErrorDetail, type ErrorEnvelope, type Failure, type FailOptions, type OkEnvelope, } from './envelope/envelope.js';
+export { fail, isFailure, ok, type ErrorDetail, type ErrorEnvelope, type Failure, type FailOptions, type OkEnvelope, } from './envelope/envelope.js';
 export { ErrorEnvelopeSchema, OkEnvelopeSchema } from './envelope/envelope.schema.js';
 export { parse, type ParseSchema } from './envelope/parse.js';
-export { createHealthHandler, type HealthCheck, type HealthOptions } from './health/health.js';
 export { HealthSchema, type HealthBody, type HealthStatus } from './health/health.schema.js';
-export { createLog, type Log, type LogFields } from './log/log.js';
-export { PackageSchema, type ExtensionPackage } from './manifest/manifest.schema.js';
-export { entryOf, imageParts, normalizeParts } from './manifest/parts.js';
+export { type Log, type LogFields } from './log/log.js';
+export { PackageSchema, type CommandSpec, type ExtensionPackage, } from './manifest/manifest.schema.js';
+export { imageParts } from './manifest/parts.js';
 export { readManifest, validateManifest } from './manifest/read-manifest.js';
-export { createApiApp, PUBLIC_CORS, type ApiAppOptions } from './server/app.js';
-export { serve, type ServeOptions } from './server/serve.js';
-export { startTestServer, type TestServer, type TestServerOptions } from './testing/test-server.js';
+export { canonical, mcpSnapshot, PROTOCOL_VERSIONS, type McpSnapshot, type ProtocolVersion, } from './mcp/snapshot.js';
+export { type McpContext, type ToolHandler, type ToolRegistrar, type ToolSpec, } from './mcp/tools.js';
+export { versionPage, type PagesContext, type PagesSite } from './pages/pages.js';
 export { type ApiCreate, type ApiHandler, type ApiPart } from './server/part.types.js';
+export { type QueryResult, type Row, type Store } from './store/store.types.js';
+export { startTestMcp, startTestServer, type TestMcpOptions, type TestServer, type TestServerOptions, } from './testing/test-server.js';
+export { type JobOptions } from './worker/job-options.js';
+export { type JobRun, type RunStatus } from './worker/runs.js';
+export { type Job, type Schedule } from './worker/scheduler.js';
+export { type WorkerContext } from './worker/worker.types.js';

package/dist/index.js

@@ -1,19 +1,26 @@
-export { AGCID_HEADER, agcidOf, isAgcid, uuidv7 } from './agcid/agcid.js';
-export { currentAgcid } from './agcid/scope.js';
-export { createContext, createTestContext, } from './context/context.js';
-export { DEFAULT_RECORD_FILE, discoveryDocument, loadRecord, recordOf, validateRecord, } from './discovery/discovery.js';
+export {} from './command/args.js';
+export {} from './command/command.types.js';
+export {} from './command/out.js';
+export {} from './context/context.js';
+export { createTestContext, } from './context/test-context.js';
 export { DiscoveryDocumentSchema, ExtensionRecordSchema, } from './discovery/discovery.schema.js';
+export { AGCID_HEADER, isAgcid } from './agcid/agcid.js';
 export { ERROR_CODES, ERROR_STATUS } from './envelope/codes.js';
-export { errorEnvelope, fail, isFailure, ok, } from './envelope/envelope.js';
+export { fail, isFailure, ok, } from './envelope/envelope.js';
 export { ErrorEnvelopeSchema, OkEnvelopeSchema } from './envelope/envelope.schema.js';
 export { parse } from './envelope/parse.js';
-export { createHealthHandler } from './health/health.js';
 export { HealthSchema } from './health/health.schema.js';
-export { createLog } from './log/log.js';
-export { PackageSchema } from './manifest/manifest.schema.js';
-export { entryOf, imageParts, normalizeParts } from './manifest/parts.js';
+export {} from './log/log.js';
+export { PackageSchema, } from './manifest/manifest.schema.js';
+export { imageParts } from './manifest/parts.js';
 export { readManifest, validateManifest } from './manifest/read-manifest.js';
-export { createApiApp, PUBLIC_CORS } from './server/app.js';
-export { serve } from './server/serve.js';
-export { startTestServer } from './testing/test-server.js';
+export { canonical, mcpSnapshot, PROTOCOL_VERSIONS, } from './mcp/snapshot.js';
+export {} from './mcp/tools.js';
+export { versionPage } from './pages/pages.js';
 export {} from './server/part.types.js';
+export {} from './store/store.types.js';
+export { startTestMcp, startTestServer, } from './testing/test-server.js';
+export {} from './worker/job-options.js';
+export {} from './worker/runs.js';
+export {} from './worker/scheduler.js';
+export {} from './worker/worker.types.js';

package/dist/log/log.d.ts

@@ -10,4 +10,5 @@ export interface LogTags {
     part: string;
 }
 export type LogWrite = (line: string) => void;
+export declare const messageOf: (error: unknown) => string;
 export declare const createLog: (tags: LogTags, write?: LogWrite) => Log;

package/dist/log/log.js

@@ -1,21 +1,20 @@
-import { currentAgcid } from '../agcid/scope.js';
+import { currentAgcid } from '../agcid/current.js';
+export const messageOf = (error) => error instanceof Error ? error.message : String(error);
 const errorFields = (error) => {
     if (!(error instanceof Error))
         return { err: { message: String(error) } };
     return { err: { type: error.name, message: error.message, stack: error.stack } };
 };
+// Spread twice: the key order stays, and a field never overwrites time, level, msg, tags or agcid.
 const line = (level, message, tags, fields) => {
     const agcid = currentAgcid();
-    const entry = { time: new Date().toISOString(), level, msg: message, ...tags, ...fields };
-    return `${JSON.stringify(agcid ? { ...entry, agcid } : entry)}\n`;
+    const own = { time: new Date().toISOString(), level, msg: message, ...tags };
+    const fixed = agcid ? { ...own, agcid } : own;
+    return `${JSON.stringify({ ...fixed, ...fields, ...fixed })}\n`;
 };
 const stderrWrite = (text) => void process.stderr.write(text);
-// JSON lines on stderr, tagged with extension, part and the request's agcid.
 export const createLog = (tags, write = stderrWrite) => ({
     info: (message, fields = {}) => write(line('info', message, tags, fields)),
     warn: (message, fields = {}) => write(line('warn', message, tags, fields)),
-    error: (error, fields = {}) => {
-        const message = error instanceof Error ? error.message : String(error);
-        write(line('error', message, tags, { ...errorFields(error), ...fields }));
-    },
+    error: (error, fields = {}) => write(line('error', messageOf(error), tags, { ...fields, ...errorFields(error) })),
 });

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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 declare const CodePartSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
     entry: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>]>;
-export declare const PartsSchema: z.ZodObject<{
+declare const PartsSchema: z.ZodObject<{
     pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         entry: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>>;
@@ -33,7 +33,7 @@ export declare const PartsSchema: z.ZodObject<{
         }>;
     }, z.core.$strict>]>>;
 }, z.core.$strict>;
-export declare const CommandSchema: z.ZodObject<{
+declare const CommandSchema: z.ZodObject<{
     name: z.ZodString;
     summary: z.ZodString;
     args: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -44,82 +44,11 @@ export 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>>>;
 }, z.core.$strict>;
-export declare const SettingSchema: z.ZodObject<{
-    type: z.ZodEnum<{
-        string: "string";
-        number: "number";
-        boolean: "boolean";
-        integer: "integer";
-    }>;
-    default: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
-    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    description: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export declare const AgentageSchema: z.ZodObject<{
-    id: z.ZodString;
-    parts: z.ZodObject<{
-        pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        ui: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        api: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        mcp: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        worker: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        cli: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        store: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            postgres: "postgres";
-            git: "git";
-            signoz: "signoz";
-        }>, z.ZodObject<{
-            kind: z.ZodEnum<{
-                postgres: "postgres";
-                git: "git";
-                signoz: "signoz";
-            }>;
-        }, z.core.$strict>]>>;
-    }, z.core.$strict>;
-    commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        summary: z.ZodString;
-        args: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            type: z.ZodEnum<{
-                string: "string";
-                number: "number";
-                boolean: "boolean";
-                integer: "integer";
-            }>;
-            required: z.ZodOptional<z.ZodBoolean>;
-            description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>;
-    }, z.core.$strict>>>;
-    settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            integer: "integer";
-        }>;
-        default: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
-        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>;
 export declare const PackageSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
@@ -170,6 +99,7 @@ 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>>>;
@@ -189,7 +119,7 @@ export declare const PackageSchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$loose>;
 export type CodePart = z.infer<typeof CodePartSchema>;
+export type CommandSpec = z.infer<typeof CommandSchema>;
 export type Parts = z.infer<typeof PartsSchema>;
-export type Agentage = z.infer<typeof AgentageSchema>;
 export type ExtensionPackage = z.infer<typeof PackageSchema>;
 export {};

package/dist/manifest/manifest.schema.js

@@ -6,7 +6,7 @@ const CodePartSchema = z.union([
 ]);
 const StorePartSchema = z.union([StoreKindSchema, z.strictObject({ kind: StoreKindSchema })]);
 const ROUTED = ['pages', 'ui', 'api', 'mcp'];
-export const PartsSchema = z
+const PartsSchema = z
     .strictObject({
     pages: CodePartSchema.optional(),
     ui: CodePartSchema.optional(),
@@ -20,19 +20,20 @@ export const PartsSchema = z
     message: 'at least one routed part (pages, ui, api or mcp)',
 });
 const ArgTypeSchema = z.enum(['string', 'integer', 'number', 'boolean']);
-export const CommandSchema = z.strictObject({
+const CommandSchema = z.strictObject({
     name: CommandNameSchema,
     summary: z.string().min(1).max(120),
     args: z
         .array(z.strictObject({
         name: CommandNameSchema,
         type: ArgTypeSchema,
+        optional: z.boolean().optional(),
         required: z.boolean().optional(),
         description: z.string().min(1).max(200).optional(),
     }))
         .optional(),
 });
-export const SettingSchema = z
+const SettingSchema = z
     .strictObject({
     type: ArgTypeSchema,
     default: z.union([z.string(), z.number(), z.boolean()]),
@@ -41,6 +42,9 @@ export const SettingSchema = z
 })
     .refine((setting) => defaultFits(setting.type, setting.default), {
     message: 'default does not match type',
+})
+    .refine((setting) => !setting.enum || setting.enum.includes(String(setting.default)), {
+    message: 'default is not one of enum',
 });
 const AgentageBaseSchema = z.strictObject({
     id: ExtensionIdSchema,
@@ -49,7 +53,7 @@ const AgentageBaseSchema = z.strictObject({
     settings: z.record(SettingKeySchema, SettingSchema).optional(),
     secrets: z.array(SecretNameSchema).optional(),
 });
-export const AgentageSchema = AgentageBaseSchema.superRefine(crossFieldRules);
+const AgentageSchema = AgentageBaseSchema.superRefine(crossFieldRules);
 export const PackageSchema = z
     .looseObject({
     name: PackageNameSchema,

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

@@ -13,6 +13,7 @@ export declare const StoreKindSchema: z.ZodEnum<{
     git: "git";
     signoz: "signoz";
 }>;
+export declare const FULL_SHA: RegExp;
 export declare const CommitSchema: z.ZodString;
 export declare const PrefixedToolNameSchema: z.ZodString;
 export declare const IMAGE_PART_KINDS: readonly ["pages", "ui", "api", "mcp", "worker"];

package/dist/manifest/primitives.schema.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+// Platform names and cli verbs, plus Windows device names: an id is a folder name on machines.
 const RESERVED_IDS = 'auth|www|api|sync|mail|mcp|ui|git|setup|status|update|extension|add|remove|help|con|prn|aux|nul|com[0-9]|lpt[0-9]';
 export const ExtensionIdSchema = z
     .string()
@@ -44,7 +45,8 @@ export const PackagePathSchema = z
     .max(256)
     .regex(/^\.\/[A-Za-z0-9._/-]+$/);
 export const StoreKindSchema = z.enum(['postgres', 'git', 'signoz']);
-export const CommitSchema = z.string().regex(/^[0-9a-f]{40}$/, { message: 'full 40-hex git sha' });
+export const FULL_SHA = /^[0-9a-f]{40}$/;
+export const CommitSchema = z.string().regex(FULL_SHA, { message: 'full 40-hex git sha' });
 export const PrefixedToolNameSchema = z
     .string()
     .max(64)

package/dist/manifest/read-manifest.d.ts

@@ -2,4 +2,5 @@ import { type z } from 'zod';
 import { type ExtensionPackage } from './manifest.schema.js';
 export declare const formatIssues: (issues: readonly z.core.$ZodIssue[]) => string;
 export declare const validateManifest: (value: unknown) => ExtensionPackage;
+export declare const readJsonIfExists: (file: string) => Promise<unknown>;
 export declare const readManifest: (dir: string) => Promise<ExtensionPackage>;