@agentage/cli 0.44.0 → 0.45.0

package/README.md

@@ -66,8 +66,9 @@ For extensions (see below):
 | `agentage extension list`                    | One row per extension: state, version, commands, last run        |
 | `agentage extension doctor`                  | Load every extension once and refresh the states                 |
 | `agentage extension create <id> [part...]`   | New `./extension-<id>` from the template, only the parts named   |
-| `agentage extension check [dir]`             | Check that an extension package conforms (the six kit rules)     |
+| `agentage extension check [dir] [--write]`   | Check that an extension package conforms (the six kit rules)     |
 | `agentage extension build [--push]`          | Build the part images of a committed tree; push with digests     |
+| `agentage extension release`                 | Release from a tag in CI: guard, images, record, npm package     |
 | `agentage extension up` / `down`             | Run an extension package on this machine with Docker, then stop  |
 | `agentage extension token --scope <scope>`   | Print a token from the dev issuer `extension up` started         |
 | `agentage <command>`                         | Run a command an installed extension contributes                 |

package/dist/commands/extension/build.d.ts

@@ -5,8 +5,10 @@ export type ExtensionBuildOptions = Pick<BuildOptions, 'push' | 'dir' | 'registr
 export type ExtensionCheckOptions = {
     dir?: string;
     json?: boolean;
+    write?: boolean;
 };
-export declare const runExtensionCheck: ({ dir, json }?: ExtensionCheckOptions, tool?: LoadKitTool) => Promise<void>;
+export type LoadWriter = () => Promise<Record<string, unknown>>;
+export declare const runExtensionCheck: ({ dir, json, write }?: ExtensionCheckOptions, tool?: LoadKitTool, writer?: LoadWriter) => Promise<void>;
 export type Committed = (dir: string) => Promise<void>;
 export declare const assertCommitted: Committed;
 export declare const runExtensionBuild: (opts?: ExtensionBuildOptions, tool?: LoadKitTool, committed?: Committed) => Promise<void>;

package/dist/commands/extension/build.js

@@ -2,8 +2,20 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import {} from 'commander';
 import { loadKitTool } from './kit-tool.js';
+// Not in the 0.5.0 types yet: the kit lane adds it in 0.5.1.
+const loadWriter = () => import('@agentage/extension/tool');
+// With --json the written paths go to stderr, so stdout stays one JSON document.
+const writeContracts = async (dir, writer, json) => {
+    const write = (await writer())['writeContracts'];
+    if (typeof write !== 'function')
+        throw new Error('check --write needs @agentage/extension >= 0.5.1');
+    for (const file of await write(dir))
+        (json ? console.error : console.log)(`wrote ${file}`);
+};
 // The kit's lines, or its report as JSON, on stdout; a package that does not conform exits 1.
-export const runExtensionCheck = async ({ dir = '.', json } = {}, tool = loadKitTool) => {
+export const runExtensionCheck = async ({ dir = '.', json, write } = {}, tool = loadKitTool, writer = loadWriter) => {
+    if (write)
+        await writeContracts(dir, writer, json);
     const { check, checkLines } = await tool();
     const report = await check(dir);
     const lines = checkLines(report);
@@ -42,6 +54,7 @@ export const addBuild = (group, { check, build }) => {
         .description('Check that an extension package conforms, as every build does first')
         .argument('[dir]', 'the extension package folder (default: the current folder)')
         .option('--json', 'machine-readable report')
+        .option('--write', 'write the committed contracts (such as {id}.mcpc.json) first, then check')
         .action((dir, opts) => check({ dir, ...opts }));
     group
         .command('build')

package/dist/commands/extension/kit-tool.d.ts

@@ -1,6 +1,6 @@
 import type * as Kit from '@agentage/extension/tool';
 import { type KitCheck } from '../../core/loader/load.js';
-export type KitTool = Pick<typeof Kit, 'check' | 'checkLines' | 'build' | 'buildLines' | 'runCommand' | 'checkCli' | 'up' | 'down' | 'token'>;
+export type KitTool = Pick<typeof Kit, 'check' | 'checkLines' | 'build' | 'buildLines' | 'runCommand' | 'checkCli' | 'up' | 'down' | 'token' | 'readManifest'>;
 export type LoadKitTool = () => Promise<KitTool>;
 export declare const loadKitTool: LoadKitTool;
 export declare const kitCheck: (tool?: LoadKitTool) => KitCheck;

package/dist/commands/extension/list.d.ts

@@ -1,5 +1,6 @@
 import { type Command } from 'commander';
 import { type BuildActions } from './build.js';
+import { type ExtensionReleaseOptions } from './release.js';
 import { type ExtensionCreateOptions } from './create.js';
 import { type ExtensionDoctorOptions } from './doctor.js';
 import { type ExtensionInstallOptions } from './install.js';
@@ -18,5 +19,6 @@ export interface ExtensionActions extends KitActions, BuildActions {
     list: (opts: ExtensionListOptions) => Promise<void>;
     doctor: (opts: ExtensionDoctorOptions) => Promise<void>;
     create: (opts: ExtensionCreateOptions) => Promise<void>;
+    release: (opts: ExtensionReleaseOptions) => Promise<void>;
 }
 export declare const registerExtension: (program: Command, actions: ExtensionActions) => void;

package/dist/commands/extension/list.js

@@ -1,5 +1,6 @@
 import {} from 'commander';
 import { addBuild } from './build.js';
+import { addRelease } from './release.js';
 import { addCreate } from './create.js';
 import {} from './doctor.js';
 import {} from './install.js';
@@ -98,7 +99,7 @@ const addReports = (group, { list, doctor }) => {
         .addHelpText('after', DOCTOR_HELP)
         .action(doctor);
 };
-// Help lists the subcommands in this order: install, remove, list, doctor, create, check, build, up, down, token.
+// Help lists the subcommands in this order: install, remove, list, doctor, create, check, build, release, up, down, token.
 export const registerExtension = (program, actions) => {
     const group = program
         .command('extension')
@@ -109,5 +110,6 @@ export const registerExtension = (program, actions) => {
     addReports(group, actions);
     addCreate(group, actions.create);
     addBuild(group, actions);
+    addRelease(group, actions.release);
     addKitTools(group, actions);
 };

package/dist/commands/extension/release-guard.d.ts

@@ -0,0 +1,14 @@
+import type { BuiltImage } from '@agentage/extension/tool';
+export type Ran = {
+    ok: boolean;
+    out: string;
+    err: string;
+};
+export type Exec = (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => Promise<Ran>;
+export declare const execIn: (cwd: string, seconds?: number) => Exec;
+export declare const RECORD = "agentage-extension.json";
+export declare const IMAGE_PARTS: readonly BuiltImage['part'][];
+export type GuardInput = Record<'dir' | 'tag' | 'sha' | 'repo' | 'id' | 'version', string> & {
+    parts: readonly BuiltImage['part'][];
+};
+export declare const releaseGuard: (g: GuardInput, exec: Exec) => Promise<"build" | "reuse">;

package/dist/commands/extension/release-guard.js

@@ -0,0 +1,64 @@
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const ran = (error, out, err) => ({ ok: !error, out, err });
+// Bounded by SIGKILL after `seconds` (0 = unbounded); a kill reads as "cannot tell".
+export const execIn = (cwd, seconds = 0) => (cmd, args, env) => new Promise((resolve) => {
+    const limits = {
+        timeout: seconds * 1000,
+        killSignal: 'SIGKILL',
+        maxBuffer: 1 << 26,
+    };
+    const opts = { cwd, env: { ...process.env, ...env }, ...limits };
+    const child = execFile(cmd, args, opts, (e, out, err) => {
+        const why = e?.killed ? `timed out after ${seconds} s` : err ? '' : e?.message;
+        resolve(ran(e, out, [err.trim(), why].filter(Boolean).join('\n')));
+    });
+    child.stdin?.end();
+});
+export const RECORD = 'agentage-extension.json';
+export const IMAGE_PARTS = ['pages', 'ui', 'api', 'mcp', 'worker'];
+// Only "not found" means "not released"; any other failure stops the release, never rebuilds it.
+const notFound = (ran, pattern, what) => {
+    if (!pattern.test(ran.err))
+        throw new Error(`cannot tell whether ${what} exists: ${ran.err}`);
+};
+const reuse = async ({ dir, tag, sha }, json) => {
+    const { commit } = JSON.parse(json);
+    if (commit !== sha) {
+        const moved = `${tag} was released from ${String(commit)}, not ${sha}`;
+        throw new Error(`${moved}; a version's images never change: release a new version`);
+    }
+    await mkdir(join(dir, 'dist'), { recursive: true });
+    await writeFile(join(dir, 'dist', RECORD), `${json.trimEnd()}\n`);
+    return 'reuse';
+};
+const ensureNoImages = async (g, exec) => {
+    for (const part of g.parts) {
+        const image = `ghcr.io/agentage/${g.id}-${part}:${g.version}`;
+        const ran = await exec('docker', ['manifest', 'inspect', image]);
+        if (ran.ok)
+            throw new Error(`${image} is already pushed but ${g.tag} has no record; release a new version`);
+        // denied too: GHCR may answer it for a package that does not exist yet (a new part).
+        notFound(ran, /manifest unknown|no such manifest|denied/, image);
+    }
+};
+// A released version is never rebuilt: its images and record stay as first pushed.
+export const releaseGuard = async (g, exec) => {
+    const record = await exec('gh', [
+        'release',
+        'download',
+        g.tag,
+        '-R',
+        g.repo,
+        '-p',
+        RECORD,
+        '-O',
+        '-',
+    ]);
+    if (record.ok)
+        return reuse(g, record.out);
+    notFound(record, /release not found|no assets match|no assets to download/, `the ${g.tag} release record`);
+    await ensureNoImages(g, exec);
+    return 'build';
+};

package/dist/commands/extension/release.d.ts

@@ -0,0 +1,14 @@
+import { type Command } from 'commander';
+import { type LoadKitTool } from './kit-tool.js';
+import { type Exec } from './release-guard.js';
+export type ExtensionReleaseOptions = {
+    dir?: string;
+    timeout?: number;
+};
+export interface ReleaseDeps {
+    exec: (cwd: string, seconds?: number) => Exec;
+    tool: LoadKitTool;
+    env: NodeJS.ProcessEnv;
+}
+export declare const runExtensionRelease: ({ dir, timeout }?: ExtensionReleaseOptions, deps?: ReleaseDeps) => Promise<void>;
+export declare const addRelease: (group: Command, release: (opts: ExtensionReleaseOptions) => Promise<void>) => void;

package/dist/commands/extension/release.js

@@ -0,0 +1,110 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {} from 'commander';
+import { runExtensionBuild } from './build.js';
+import { loadKitTool } from './kit-tool.js';
+import { execIn, IMAGE_PARTS, RECORD, releaseGuard } from './release-guard.js';
+const defaultDeps = { exec: execIn, tool: loadKitTool, env: process.env };
+const step = (line) => console.log(`PASS ${line}`);
+const fail = (line) => {
+    throw new Error(`FAIL ${line}`);
+};
+// Tokens leave the environment, so docker build and npm lifecycle scripts never see them.
+const takeSecrets = (env) => {
+    const { GH_TOKEN, GITHUB_TOKEN, NPM_TOKEN } = env;
+    for (const name of ['GH_TOKEN', 'GITHUB_TOKEN', 'NPM_TOKEN'])
+        delete env[name];
+    const gh = GH_TOKEN ?? GITHUB_TOKEN;
+    return { gh: gh ? { GH_TOKEN: gh } : {}, npm: NPM_TOKEN ? { NPM_TOKEN } : {} };
+};
+const scoped = (exec, secrets) => (cmd, args) => exec(cmd, args, secrets[cmd]);
+const imageParts = (pkg) => IMAGE_PARTS.filter((part) => (pkg.agentage.parts[part] ?? false) !== false);
+// The record by digest on the tag's release; the release is created when the tag has none.
+const attach = async (run, tag, repo) => {
+    const file = join('dist', RECORD);
+    const exists = (await run('gh', ['release', 'view', tag, '-R', repo])).ok;
+    const notes = ['--title', tag, '--notes', `Images by digest: ${RECORD}`];
+    const args = exists ? ['upload', tag, file] : ['create', tag, file, ...notes];
+    const ran = await run('gh', ['release', ...args, '-R', repo]);
+    if (!ran.ok)
+        fail(`record: ${ran.err}`);
+    step(`record: ${RECORD} attached to release ${tag}`);
+};
+// Single quotes on purpose: npm expands ${NPM_TOKEN} itself, the token never lands on disk.
+const tokenConfig = async (token) => {
+    if (!token)
+        return [];
+    const file = join(await mkdtemp(join(tmpdir(), 'agentage-npm-')), '.npmrc');
+    await writeFile(file, '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
+    return ['--userconfig', file];
+};
+// OIDC trusted publishing; a new name (NPM_TOKEN set) or an unauthorized direct publish is staged.
+const publish = async (run, { name, version }, token) => {
+    const cfg = await tokenConfig(token);
+    const spec = `${name}@${version}`;
+    if ((await run('npm', ['view', spec, 'version', ...cfg])).out.trim())
+        return step(`npm: ${spec} is already on npm`);
+    const flags = ['--access', 'public', '--provenance', '--ignore-scripts', ...cfg];
+    const fresh = token !== undefined && !(await run('npm', ['view', name, 'name', ...cfg])).ok;
+    if (!fresh && (await run('npm', ['publish', ...flags])).ok)
+        return step(`npm: ${spec} published`);
+    const staged = await run('npm', ['stage', 'publish', ...flags]);
+    if (!staged.ok)
+        fail(`npm: ${staged.err}`);
+    const why = fresh
+        ? 'a new name has no trusted publisher'
+        : 'direct publish not authorized: no validated trusted publisher';
+    step(`npm: ${spec} staged for approval (${why})`);
+};
+const npmVersion = async (run) => {
+    const v = (await run('npm', ['--version'])).out.trim();
+    const [major = 0, minor = 0, patch = 0] = v.split('.').map(Number);
+    if (major * 1e6 + minor * 1e3 + patch < 11_005_001)
+        fail(`npm: npm ${v} cannot publish with OIDC: needs npm >= 11.5.1`);
+    step(`npm: npm ${v}`);
+};
+const preflight = async (run, pkg, tag, sha) => {
+    if (pkg.agentage.id === 'template')
+        fail('id: this repo is the starting point for extensions: create one, release that');
+    step(`id: ${pkg.agentage.id} is not the template`);
+    const fetched = await run('git', ['fetch', '-q', 'origin', 'master']);
+    if (!fetched.ok || !(await run('git', ['merge-base', '--is-ancestor', sha, 'origin/master'])).ok)
+        fail(`master: ${sha} is not on master${fetched.err ? `: ${fetched.err}` : ''}`);
+    step(`master: ${sha} is on master`);
+    const v = `v${pkg.version}`;
+    if (tag !== v)
+        fail(`tag: ${tag} is not ${v}, the package.json version; tag the commit that sets it`);
+    step(`tag: ${tag} is the package.json version`);
+    await npmVersion(run);
+};
+// One line per step, PASS or FAIL; any refusal exits 1 before anything is pushed or published.
+export const runExtensionRelease = async ({ dir = '.', timeout = 60 } = {}, deps = defaultDeps) => {
+    const { GITHUB_REF_NAME: tag, GITHUB_SHA: sha, GITHUB_REPOSITORY: repo } = deps.env;
+    const missing = ['GITHUB_REF_NAME', 'GITHUB_SHA', 'GITHUB_REPOSITORY'].find((n) => !deps.env[n]);
+    if (!tag || !sha || !repo)
+        return fail(`inputs: ${missing} is not set; run it on a tag push`);
+    const secrets = takeSecrets(deps.env);
+    const pkg = await (await deps.tool()).readManifest(dir);
+    const run = scoped(deps.exec(dir), secrets);
+    await preflight(run, pkg, tag, sha);
+    const { id } = pkg.agentage;
+    const g = { dir, tag, sha, repo, id, version: pkg.version, parts: imageParts(pkg) };
+    const bounded = scoped(deps.exec(dir, timeout), secrets);
+    const decision = await releaseGuard(g, bounded).catch((e) => fail(`guard: ${e.message}`));
+    const build = decision === 'build';
+    step(`guard: ${tag} ${build ? 'has no record and no image: build' : 'is released: npm only'}`);
+    if (build) {
+        await runExtensionBuild({ push: true, dir }, deps.tool);
+        await attach(run, tag, repo);
+    }
+    await publish(run, pkg, secrets['npm']?.['NPM_TOKEN']);
+};
+export const addRelease = (group, release) => {
+    group
+        .command('release')
+        .description('Release an extension from its v* tag in CI: guard, images, record, npm package')
+        .option('--dir <path>', 'the extension package folder (default: the current folder)')
+        .option('--timeout <seconds>', 'bound on each GitHub and registry check (default: 60)', Number)
+        .action(release);
+};

package/dist/program.d.ts

@@ -7,6 +7,7 @@ import { type ExtensionInstallOptions } from './commands/extension/install.js';
 import { type ExtensionListOptions } from './commands/extension/list.js';
 import { type ExtensionRemoveOptions } from './commands/extension/remove.js';
 import { type LoadKitTool } from './commands/extension/kit-tool.js';
+import { type ExtensionReleaseOptions } from './commands/extension/release.js';
 import { type ExtensionDownOptions, type ExtensionTokenOptions, type ExtensionUpOptions } from './commands/extension/up.js';
 import { type StatusOptions } from './commands/status/status.js';
 import { type UpdateOptions } from './commands/update/update.js';
@@ -21,6 +22,7 @@ export interface ProgramDeps {
     extensionCreate: (opts: ExtensionCreateOptions) => Promise<void>;
     extensionCheck: (opts: ExtensionCheckOptions) => Promise<void>;
     extensionBuild: (opts: ExtensionBuildOptions) => Promise<void>;
+    extensionRelease: (opts: ExtensionReleaseOptions) => Promise<void>;
     extensionUp: (opts: ExtensionUpOptions) => Promise<void>;
     extensionDown: (opts: ExtensionDownOptions) => Promise<void>;
     extensionToken: (opts: ExtensionTokenOptions) => Promise<void>;

package/dist/program.js

@@ -11,6 +11,7 @@ import { runExtensionRemove, terminalIo, } from './commands/extension/remove.js'
 import { signedInAccount } from './commands/extension/account.js';
 import { KIT_EXIT } from './commands/extension/kit-commands.js';
 import { loadKitTool } from './commands/extension/kit-tool.js';
+import { runExtensionRelease } from './commands/extension/release.js';
 import { runExtensionSetup } from './commands/extension/setup.js';
 import { runExtensionDown, runExtensionToken, runExtensionUp, } from './commands/extension/up.js';
 import { registerStatus, runStatus, statusDeps, } from './commands/status/status.js';
@@ -37,6 +38,7 @@ const defaultDeps = {
     extensionCreate: (opts) => runExtensionCreate(opts),
     extensionCheck: (opts) => runExtensionCheck(opts),
     extensionBuild: (opts) => runExtensionBuild(opts),
+    extensionRelease: (opts) => runExtensionRelease(opts),
     extensionUp: (opts) => runExtensionUp(opts),
     extensionDown: (opts) => runExtensionDown(opts),
     extensionToken: (opts) => runExtensionToken(opts),
@@ -82,6 +84,7 @@ const addExtensions = (program, deps, argv) => {
         create: withAction(deps, deps.extensionCreate),
         check: withAction(deps, deps.extensionCheck),
         build: withAction(deps, deps.extensionBuild),
+        release: withAction(deps, deps.extensionRelease),
         up: withAction(deps, deps.extensionUp),
         down: withAction(deps, deps.extensionDown),
         token: withAction(deps, deps.extensionToken),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/cli",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "The agentage CLI - connect this machine to agentage from the terminal",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,7 +55,7 @@
     "prepublishOnly": "npm run verify"
   },
   "dependencies": {
-    "@agentage/extension": "^0.5.0",
+    "@agentage/extension": "^0.5.1",
     "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "open": "^11.0.0"