@agentage/cli 0.42.1 → 0.43.0

package/README.md

@@ -65,8 +65,9 @@ For extensions (see below):
 | `agentage extension remove <name> [--purge]` | Take it out of the profile and reinstall the rest                |
 | `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 build [--push]`          | Build the part images of an extension package; push with digests |
+| `agentage extension build [--push]`          | Build the part images of a committed tree; push with digests     |
 | `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

@@ -7,7 +7,9 @@ export type ExtensionCheckOptions = {
     json?: boolean;
 };
 export declare const runExtensionCheck: ({ dir, json }?: ExtensionCheckOptions, tool?: LoadKitTool) => Promise<void>;
-export declare const runExtensionBuild: (opts?: ExtensionBuildOptions, tool?: LoadKitTool) => 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>;
 export interface BuildActions {
     check: (opts: ExtensionCheckOptions) => Promise<void>;
     build: (opts: ExtensionBuildOptions) => Promise<void>;

package/dist/commands/extension/build.js

@@ -1,3 +1,5 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import {} from 'commander';
 import { loadKitTool } from './kit-tool.js';
 // The kit's lines, or its report as JSON, on stdout; a package that does not conform exits 1.
@@ -11,8 +13,18 @@ export const runExtensionCheck = async ({ dir = '.', json } = {}, tool = loadKit
     if (!report.conforms)
         throw new Error(fail);
 };
+// The build record names HEAD, so the tree it builds must be HEAD.
+export const assertCommitted = async (dir) => {
+    const status = promisify(execFile)('git', ['status', '--porcelain'], { cwd: dir });
+    const { stdout } = await status.catch(() => {
+        throw new Error(`${dir} is not a git checkout: commit first`);
+    });
+    if (stdout.trim())
+        throw new Error(`${dir} has uncommitted changes: commit first`);
+};
 // One line per image on stdout (part, tag, digest when pushed), then the record path.
-export const runExtensionBuild = async (opts = {}, tool = loadKitTool) => {
+export const runExtensionBuild = async (opts = {}, tool = loadKitTool, committed = assertCommitted) => {
+    await committed(opts.dir ?? '.');
     const { build, buildLines } = await tool();
     for (const line of buildLines(await build(opts)))
         console.log(line);

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

@@ -0,0 +1,10 @@
+import { type Command } from 'commander';
+export declare const TEMPLATE = "agentage/extension-template";
+export declare const PARTS: string[];
+export interface ExtensionCreateOptions {
+    id: string;
+    parts: string[];
+    from?: string;
+}
+export declare const runExtensionCreate: (opts: ExtensionCreateOptions, url?: (from: string) => string) => Promise<void>;
+export declare const addCreate: (group: Command, create: (o: ExtensionCreateOptions) => Promise<void>) => Command;

package/dist/commands/extension/create.js

@@ -0,0 +1,109 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import {} from 'commander';
+const run = promisify(execFile);
+export const TEMPLATE = 'agentage/extension-template';
+export const PARTS = ['pages', 'ui', 'api', 'mcp', 'worker', 'store', 'cli'];
+const ROUTED = ['pages', 'ui', 'api', 'mcp'];
+// `_` is a separator here, so `template__echo` is the id too.
+const WORD = /(?<![A-Za-z0-9])template(?![A-Za-z0-9])/g;
+const LOCK = 'package-lock.json';
+// What else goes with a dropped part: manifest keys the kit refuses without it, the store's SQL.
+const PRUNE = {
+    cli: { keys: [['agentage', 'commands']] },
+    mcp: { keys: [['agentage', 'settings', 'mcp.listing']] },
+    store: { dirs: ['migrations', 'seeds'] },
+};
+const refusal = ({ id, parts, from = TEMPLATE }, kept) => {
+    const unknown = parts.find((part) => !PARTS.includes(part));
+    if (unknown)
+        return `unknown part ${unknown}: one of ${PARTS.join(', ')}`;
+    if (!/^[a-z][a-z0-9-]*$/.test(id))
+        return `id ${id}: lowercase letters, digits and -, starting with a letter`;
+    if (PARTS.includes(id))
+        return `id ${id} is a part name: pick another id`;
+    if (!kept.some((part) => ROUTED.includes(part)))
+        return `an extension needs at least one of ${ROUTED.join(', ')}`;
+    if (!/^[\w.-]+\/[\w.-]+$/.test(from))
+        return `--from ${from}: owner/repo`;
+    return existsSync(`extension-${id}`)
+        ? `extension-${id} exists: pick another id or remove it`
+        : '';
+};
+const json = (file) => JSON.parse(readFileSync(file, 'utf8'));
+const save = (file, value) => writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+// A dropped part goes with its folder (its tests beside it) and what PRUNE names.
+const drop = (dir, kept) => {
+    const pkg = json(join(dir, 'package.json'));
+    for (const part of PARTS.filter((part) => !kept.includes(part))) {
+        delete pkg['agentage']?.parts?.[part];
+        for (const sub of [join('src', part), ...(PRUNE[part]?.dirs ?? [])])
+            rmSync(join(dir, sub), { recursive: true, force: true });
+        for (const path of PRUNE[part]?.keys ?? []) {
+            const parent = path.slice(0, -1).reduce((at, key) => at?.[key], pkg);
+            if (parent)
+                delete parent[path.at(-1) ?? ''];
+        }
+    }
+    save(join(dir, 'package.json'), pkg);
+};
+// Every word `template` in a text file or a file name is the id: package name, host, contract.
+const rewrite = (dir, id) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            rewrite(path, id);
+        const text = entry.isFile() && entry.name !== LOCK ? readFileSync(path, 'utf8') : '\0';
+        const next = text.replace(WORD, id);
+        if (!text.includes('\0') && next !== text)
+            writeFileSync(path, next);
+        const name = entry.name.replace(WORD, id);
+        if (name !== entry.name)
+            renameSync(path, join(dir, name));
+    }
+};
+// The lock names many packages called template (`@babel/template`): only its own name changes.
+const renameLock = (dir, id) => {
+    if (!existsSync(join(dir, LOCK)))
+        return;
+    const lock = json(join(dir, LOCK));
+    const name = `@agentage/extension-${id}`;
+    for (const at of [lock, lock['packages']?.['']])
+        if (at)
+            Object.assign(at, { name });
+    save(join(dir, LOCK), lock);
+};
+const clone = async (url, from, dir) => {
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+    await run('git', ['clone', '-q', '--depth', '1', url, dir], { env }).catch(() => {
+        throw new Error(`template ${from} not found`);
+    });
+    rmSync(join(dir, '.git'), { recursive: true, force: true });
+};
+// Clones the template's default branch into ./extension-<id> as a new working copy, no history.
+export const runExtensionCreate = async (opts, url = (from) => `https://github.com/${from}`) => {
+    const { id, from = TEMPLATE } = opts;
+    const kept = opts.parts.length > 0 ? [...new Set(opts.parts)] : PARTS;
+    const refused = refusal(opts, kept);
+    if (refused)
+        throw new Error(refused);
+    const dir = `extension-${id}`;
+    await clone(url(from), from, dir);
+    drop(dir, kept);
+    rewrite(dir, id);
+    renameLock(dir, id);
+    const kit = String(json(join(dir, 'package.json'))['dependencies']?.['@agentage/extension'] ?? '?');
+    console.log(` template  ${from} (default branch, kit ${kit.replace(/^[\^~]/, '')})`);
+    console.log(` kept      ${kept.join(', ')}`);
+    console.log(` id        ${id}  ·  host ${id}.next.agentage.io  ·  contract ${id}.mcpc.json`);
+    console.log(` next      cd ${dir} && npm ci && npm run build && agentage extension check`);
+};
+export const addCreate = (group, create) => group
+    .command('create')
+    .description('Create ./extension-<id> from the extension template with the parts named')
+    .argument('<id>', 'the extension id, also its host and contract name')
+    .argument('[parts...]', `parts to keep (default: all seven): ${PARTS.join(', ')}`)
+    .option('--from <owner/repo>', `the template repo (default: ${TEMPLATE})`)
+    .action((id, parts, o) => create({ id, parts, ...o }));

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

@@ -1,5 +1,6 @@
 import { type Command } from 'commander';
 import { type BuildActions } from './build.js';
+import { type ExtensionCreateOptions } from './create.js';
 import { type ExtensionDoctorOptions } from './doctor.js';
 import { type ExtensionInstallOptions } from './install.js';
 import { type ExtensionRemoveOptions } from './remove.js';
@@ -16,5 +17,6 @@ export interface ExtensionActions extends KitActions, BuildActions {
     remove: (opts: ExtensionRemoveOptions) => Promise<void>;
     list: (opts: ExtensionListOptions) => Promise<void>;
     doctor: (opts: ExtensionDoctorOptions) => Promise<void>;
+    create: (opts: ExtensionCreateOptions) => 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 { addCreate } from './create.js';
 import {} from './doctor.js';
 import {} from './install.js';
 import {} from './remove.js';
@@ -97,7 +98,7 @@ const addReports = (group, { list, doctor }) => {
         .addHelpText('after', DOCTOR_HELP)
         .action(doctor);
 };
-// Help lists the subcommands in this order: install, remove, list, doctor, check, build, up, down, token.
+// Help lists the subcommands in this order: install, remove, list, doctor, create, check, build, up, down, token.
 export const registerExtension = (program, actions) => {
     const group = program
         .command('extension')
@@ -106,6 +107,7 @@ export const registerExtension = (program, actions) => {
         .action(helpOrUnknown);
     addChanges(group, actions);
     addReports(group, actions);
+    addCreate(group, actions.create);
     addBuild(group, actions);
     addKitTools(group, actions);
 };

package/dist/program.d.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { type SetupOptions } from './commands/auth/setup.js';
 import { type ExtensionBuildOptions, type ExtensionCheckOptions } from './commands/extension/build.js';
+import { type ExtensionCreateOptions } from './commands/extension/create.js';
 import { type ExtensionDoctorOptions } from './commands/extension/doctor.js';
 import { type ExtensionInstallOptions } from './commands/extension/install.js';
 import { type ExtensionListOptions } from './commands/extension/list.js';
@@ -17,6 +18,7 @@ export interface ProgramDeps {
     extensionRemove: (opts: ExtensionRemoveOptions) => Promise<void>;
     extensionList: (opts: ExtensionListOptions) => Promise<void>;
     extensionDoctor: (opts: ExtensionDoctorOptions) => Promise<void>;
+    extensionCreate: (opts: ExtensionCreateOptions) => Promise<void>;
     extensionCheck: (opts: ExtensionCheckOptions) => Promise<void>;
     extensionBuild: (opts: ExtensionBuildOptions) => Promise<void>;
     extensionUp: (opts: ExtensionUpOptions) => Promise<void>;

package/dist/program.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { Command, CommanderError } from 'commander';
 import { registerSetup } from './commands/auth/setup.js';
 import { runExtensionBuild, runExtensionCheck, } from './commands/extension/build.js';
+import { runExtensionCreate } from './commands/extension/create.js';
 import { registerDelegates } from './commands/extension/delegate.js';
 import { runExtensionDoctor } from './commands/extension/doctor.js';
 import { runExtensionInstall } from './commands/extension/install.js';
@@ -33,6 +34,7 @@ const defaultDeps = {
     extensionRemove: (opts) => runExtensionRemove(opts, { ...editDeps, io: terminalIo() }),
     extensionList: (opts) => runExtensionList(opts),
     extensionDoctor: (opts) => runExtensionDoctor(opts),
+    extensionCreate: (opts) => runExtensionCreate(opts),
     extensionCheck: (opts) => runExtensionCheck(opts),
     extensionBuild: (opts) => runExtensionBuild(opts),
     extensionUp: (opts) => runExtensionUp(opts),
@@ -77,6 +79,7 @@ const addExtensions = (program, deps, argv) => {
         remove: withAction(deps, deps.extensionRemove),
         list: withAction(deps, deps.extensionList),
         doctor: withAction(deps, deps.extensionDoctor),
+        create: withAction(deps, deps.extensionCreate),
         check: withAction(deps, deps.extensionCheck),
         build: withAction(deps, deps.extensionBuild),
         up: withAction(deps, deps.extensionUp),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/cli",
-  "version": "0.42.1",
+  "version": "0.43.0",
   "description": "The agentage CLI - connect this machine to agentage from the terminal",
   "type": "module",
   "main": "./dist/index.js",