@matthesketh/fleet 1.8.1 → 1.11.1

package/dist/mcp/registry-bridge.js

@@ -0,0 +1,65 @@
+import { loadRegistry } from '../registry/index.js';
+import { allCommands } from '../registry/registry.js';
+import { makeMcpContext } from '../registry/context.js';
+/**
+ * the mcp tool name for a registry command. ':' namespacing is not legal in
+ * tool names, so subcommands collapse to underscores. this string is the
+ * cross-surface contract, so both bridge functions derive it the same way.
+ */
+function toMcpToolName(commandName) {
+    return 'fleet_' + commandName.replace(/:/g, '_');
+}
+/** registry commands as flat tool descriptors, for inspection and tests. */
+export function collectRegistryTools() {
+    loadRegistry();
+    return allCommands()
+        .filter(def => !def.cliOnly)
+        .map(def => ({ toolName: toMcpToolName(def.name), summary: def.summary }));
+}
+/** registers every non-cliOnly registry command as an mcp tool. */
+export function registerRegistryTools(server) {
+    loadRegistry();
+    for (const def of allCommands()) {
+        if (def.cliOnly)
+            continue;
+        server.tool(toMcpToolName(def.name), def.summary, def.args.shape, async (args) => {
+            // `confirm` is mcp surface plumbing, not a command arg — read it from the
+            // raw input before the schema parse below strips unknown keys.
+            const ctx = makeMcpContext(args.confirm === true);
+            try {
+                // validate, coerce and default args against the command schema — the
+                // same safeParse the cli dispatcher runs via parseArgs, so both
+                // surfaces invoke `run` with an identically-validated args shape.
+                const parsed = def.args.safeParse(args);
+                if (!parsed.success) {
+                    const detail = parsed.error.issues
+                        .map(iss => `${iss.path.join('.')}: ${iss.message}`)
+                        .join('; ');
+                    return {
+                        content: [{ type: 'text', text: `invalid arguments: ${detail}` }],
+                        isError: true,
+                    };
+                }
+                const result = await def.run(parsed.data, ctx);
+                return {
+                    content: [{ type: 'text', text: result.summary }],
+                    // structuredContent must be an object — only attach it when the
+                    // command actually returned one, otherwise the sdk rejects the shape.
+                    ...(result.data && typeof result.data === 'object'
+                        ? { structuredContent: result.data }
+                        : {}),
+                    isError: !result.ok,
+                };
+            }
+            catch (err) {
+                // the bridge is the single funnel for every migrated command — a
+                // thrown handler must still surface as a structured tool failure,
+                // not an opaque transport-level rejection.
+                return {
+                    content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+                    isError: true,
+                };
+            }
+        });
+    }
+}

package/dist/mcp/secrets-tools.js

@@ -19,7 +19,7 @@ export function registerSecretsTools(server) {
         value: z.string().describe('Secret value'),
     }, async ({ app, key, value }) => {
         requireVault();
-        setSecret(app, key, value);
+        await setSecret(app, key, value);
         return text(`Set ${key} for ${app} in vault. Run fleet_secrets_unseal + restart the app to apply at runtime.`);
     });
     server.tool('fleet_secrets_get', 'Get a single decrypted secret value from the vault. ' +
@@ -41,7 +41,7 @@ export function registerSecretsTools(server) {
         app: z.string().optional().describe('App name (omit to seal all apps)'),
     }, async ({ app }) => {
         requireVault();
-        const sealed = sealFromRuntime(app);
+        const sealed = await sealFromRuntime(app);
         return text(`Sealed ${sealed.length} app(s): ${sealed.join(', ')}. Changes will now persist across reboots.`);
     });
     server.tool('fleet_secrets_drift', 'Detect drift between vault (encrypted, survives reboot) and runtime (/run/fleet-secrets/, lost on reboot). ' +

package/dist/mcp/server.js

@@ -4,26 +4,25 @@ import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { getStatusData } from '../commands/status.js';
-import { load, findApp, save, addApp } from '../core/registry.js';
-import { startService, stopService, restartService } from '../core/systemd.js';
+import { load, findApp, addApp, withRegistry } from '../core/registry.js';
+import { restartService } from '../core/systemd.js';
 import { getContainerLogs, getContainersByCompose } from '../core/docker.js';
-import { checkHealth, checkAllHealth } from '../core/health.js';
 import { listSites, installConfig, testConfig, reload, removeConfig } from '../core/nginx.js';
 import { generateNginxConfig } from '../templates/nginx.js';
 import { composeBuild } from '../core/docker.js';
-import { execSafe } from '../core/exec.js';
 import { AppNotFoundError } from '../core/errors.js';
-import { assertAppName, assertServiceName, assertFilePath, assertDomain } from '../core/validate.js';
+import { assertAppName, assertServiceName, assertFilePath, assertDomain, assertComposeFile } from '../core/validate.js';
 import { loadManifest, listSecrets, isInitialized } from '../core/secrets.js';
 import { unsealAll, getStatus as getSecretsStatus } from '../core/secrets-ops.js';
 import { validateApp, validateAll } from '../core/secrets-validate.js';
-import { freezeApp, unfreezeApp } from '../commands/freeze.js';
 import { registerGitTools } from './git-tools.js';
 import { registerSecretsTools } from './secrets-tools.js';
+import { registerRegistryTools } from './registry-bridge.js';
 import { readContainerLogs, getLogStatus, effectivePolicy } from '../core/logs-policy.js';
 import { snapshotEgress } from '../core/egress.js';
 import { registerDepsTools } from './deps-tools.js';
+import { registerAuditTools } from './audit-tools.js';
+import { registerTestflightTools } from './testflight-tools.js';
 function requireApp(name) {
     const reg = load();
     const app = findApp(reg, name);
@@ -41,29 +40,7 @@ export async function startMcpServer() {
         name: 'fleet',
         version: pkg.version,
     });
-    server.tool('fleet_status', 'Dashboard data for all apps: systemd state, containers, health', async () => {
-        const data = getStatusData();
-        return text(JSON.stringify(data, null, 2));
-    });
-    server.tool('fleet_list', 'List all registered apps with their configuration', async () => {
-        const reg = load();
-        return text(JSON.stringify(reg.apps, null, 2));
-    });
-    server.tool('fleet_start', 'Start an app via systemctl', { app: z.string().describe('App name') }, async ({ app }) => {
-        const entry = requireApp(app);
-        const ok = startService(entry.serviceName);
-        return text(ok ? `Started ${entry.name}` : `Failed to start ${entry.name}`);
-    });
-    server.tool('fleet_stop', 'Stop an app via systemctl', { app: z.string().describe('App name') }, async ({ app }) => {
-        const entry = requireApp(app);
-        const ok = stopService(entry.serviceName);
-        return text(ok ? `Stopped ${entry.name}` : `Failed to stop ${entry.name}`);
-    });
-    server.tool('fleet_restart', 'Restart an app via systemctl', { app: z.string().describe('App name') }, async ({ app }) => {
-        const entry = requireApp(app);
-        const ok = restartService(entry.serviceName);
-        return text(ok ? `Restarted ${entry.name}` : `Failed to restart ${entry.name}`);
-    });
+    registerRegistryTools(server);
     server.tool('fleet_logs', 'DEPRECATED — prefer fleet_logs_recent (token-conservative defaults) or fleet_logs_summary. Get recent container logs for an app.', {
         app: z.string().describe('App name'),
         container: z.string().optional().describe('Container name (omit to list available containers, or get logs from first)'),
@@ -196,18 +173,6 @@ export async function startMcpServer() {
         }
         return text(JSON.stringify(out, null, 2));
     });
-    server.tool('fleet_health', 'Run health checks for one or all apps', { app: z.string().optional().describe('App name (omit for all apps)') }, async ({ app }) => {
-        const reg = load();
-        if (app) {
-            const entry = findApp(reg, app);
-            if (!entry)
-                throw new AppNotFoundError(app);
-            const result = checkHealth(entry);
-            return text(JSON.stringify(result, null, 2));
-        }
-        const results = checkAllHealth(reg.apps);
-        return text(JSON.stringify(results, null, 2));
-    });
     server.tool('fleet_deploy', 'Deploy an app: build and restart', { app: z.string().describe('App name') }, async ({ app }) => {
         const entry = requireApp(app);
         const buildOk = composeBuild(entry.composePath, entry.composeFile, entry.name);
@@ -287,7 +252,7 @@ export async function startMcpServer() {
             if (params.serviceName)
                 assertServiceName(params.serviceName);
             if (params.composeFile)
-                assertFilePath(params.composeFile);
+                assertComposeFile(params.composeFile);
             for (const d of (params.domains ?? []))
                 assertDomain(d);
         }
@@ -297,8 +262,6 @@ export async function startMcpServer() {
         if (!existsSync(params.composePath)) {
             return text(`Error: composePath does not exist: ${params.composePath}`);
         }
-        const reg = load();
-        const existing = findApp(reg, params.name);
         let containers = params.containers;
         if (!containers || containers.length === 0) {
             containers = getContainersByCompose(params.composePath, params.composeFile ?? null);
@@ -319,48 +282,19 @@ export async function startMcpServer() {
             dependsOnDatabases: params.dependsOnDatabases,
             registeredAt: new Date().toISOString(),
         };
-        save(addApp(reg, entry));
-        const action = existing ? 'Updated' : 'Registered';
+        let existed = false;
+        await withRegistry(reg => {
+            existed = !!findApp(reg, params.name);
+            return addApp(reg, entry);
+        });
+        const action = existed ? 'Updated' : 'Registered';
         return text(`${action} app "${params.name}":\n${JSON.stringify(entry, null, 2)}`);
     });
-    server.tool('fleet_freeze', 'Freeze a crash-looping service: stop it, disable it, and mark it frozen in the registry. Requires manual unfreezing.', {
-        app: z.string().describe('App name'),
-        reason: z.string().optional().describe('Reason for freezing'),
-    }, async ({ app, reason }) => {
-        freezeApp(app, reason);
-        return text(`Frozen ${app}${reason ? `: ${reason}` : ''}`);
-    });
-    server.tool('fleet_unfreeze', 'Unfreeze a frozen service: clear frozen state, enable and start the service.', { app: z.string().describe('App name') }, async ({ app }) => {
-        unfreezeApp(app);
-        return text(`Unfrozen ${app} — service enabled and started`);
-    });
-    server.tool('fleet_rollback', 'Roll back an app to its previous image (tagged <repo>:fleet-previous before the last build) and restart the service. Use this when a recent deploy or boot-refresh produced a broken image.', { app: z.string().describe('App name') }, async ({ app }) => {
-        const entry = requireApp(app);
-        // Resolve current image name via compose config
-        const config = execSafe('docker', ['compose', ...(entry.composeFile ? ['-f', entry.composeFile] : []), 'config', '--images'], { cwd: entry.composePath, timeout: 15_000 });
-        if (!config.ok)
-            return text(`Could not resolve image name for ${entry.name}: ${config.stderr}`);
-        const latest = config.stdout.split('\n').filter(Boolean)[0];
-        if (!latest)
-            return text(`Could not resolve image name for ${entry.name}`);
-        // Compute previous tag via lastIndexOf (handles registry:port/repo:tag)
-        const lastColon = latest.lastIndexOf(':');
-        const base = lastColon > 0 ? latest.slice(0, lastColon) : latest;
-        const previous = `${base}:fleet-previous`;
-        if (!execSafe('docker', ['image', 'inspect', previous], { timeout: 10_000 }).ok) {
-            return text(`No previous image found (${previous}) — nothing to roll back to`);
-        }
-        const tag = execSafe('docker', ['tag', previous, latest], { timeout: 10_000 });
-        if (!tag.ok)
-            return text(`docker tag failed: ${tag.stderr}`);
-        const ok = restartService(entry.serviceName);
-        return text(ok
-            ? `Rolled back ${entry.name} to ${previous}`
-            : `Tag flipped but service restart failed for ${entry.serviceName}`);
-    });
     registerGitTools(server);
     registerSecretsTools(server);
     registerDepsTools(server);
+    registerAuditTools(server);
+    registerTestflightTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/mcp/testflight-tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTestflightTools(server: McpServer): void;

package/dist/mcp/testflight-tools.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { resolveTestflightTarget, appSecretsEnv } from '../core/testflight/resolve.js';
+import { resolveAscCredentials, hasAscCredentials } from '../core/testflight/credentials.js';
+import { listBuilds, verifyApp } from '../core/testflight/asc.js';
+import { ghVersion, resolveRepo } from '../core/testflight/workflow.js';
+function text(msg) {
+    return { content: [{ type: 'text', text: msg }] };
+}
+export function registerTestflightTools(server) {
+    server.tool('fleet_testflight_builds', "List an app's TestFlight builds via the App Store Connect API — build number, " +
+        'version, processing state and expiry. Requires the app\'s ASC credentials and ' +
+        'ASC_APP_ID in its fleet secrets.', { app: z.string().describe('Registered fleet app name') }, async ({ app }) => {
+        const { app: name } = resolveTestflightTarget(app);
+        const env = appSecretsEnv(name);
+        if (!hasAscCredentials(env)) {
+            return text(`App Store Connect credentials missing for ${name}.`);
+        }
+        const ascAppId = env.ASC_APP_ID;
+        if (!ascAppId)
+            return text(`ASC_APP_ID not set for ${name}.`);
+        const builds = await listBuilds(resolveAscCredentials(env), ascAppId);
+        return text(JSON.stringify(builds, null, 2));
+    });
+    server.tool('fleet_testflight_doctor', 'Check TestFlight publishing readiness for an app: GitHub CLI availability, the ' +
+        'GitHub repo backing the build workflow, App Store Connect credentials, and — when ' +
+        'ASC_APP_ID is set — that the ASC API is reachable.', { app: z.string().describe('Registered fleet app name') }, async ({ app }) => {
+        const { app: name, projectPath } = resolveTestflightTarget(app);
+        const env = appSecretsEnv(name);
+        const lines = [
+            `gh cli: ${ghVersion() ?? 'not found'}`,
+            `github repo: ${resolveRepo(projectPath) ?? 'not resolved'}`,
+        ];
+        if (!hasAscCredentials(env)) {
+            lines.push('asc credentials: missing — need ASC_API_KEY_ID, ASC_API_KEY_ISSUER_ID, ASC_API_KEY_B64');
+            return text(lines.join('\n'));
+        }
+        lines.push('asc credentials: present');
+        if (env.ASC_APP_ID) {
+            try {
+                const appName = await verifyApp(resolveAscCredentials(env), env.ASC_APP_ID);
+                lines.push(`asc api: reachable — app "${appName}"`);
+            }
+            catch (err) {
+                lines.push(`asc api: check failed — ${err.message}`);
+            }
+        }
+        else {
+            lines.push('asc app id: not set');
+        }
+        return text(lines.join('\n'));
+    });
+}

package/dist/registry/context.d.ts

@@ -0,0 +1,7 @@
+import type { CommandContext } from './types.js';
+/** cli context: confirm prompts on stdin, log writes to stderr. */
+export declare function makeCliContext(): CommandContext;
+/** mcp context: confirm is pre-resolved from the tool's `confirm` argument.
+ *  per-event logs are silently dropped — the command result's `summary` is
+ *  the sole output channel on the mcp surface. */
+export declare function makeMcpContext(confirmGranted: boolean): CommandContext;

package/dist/registry/context.js

@@ -0,0 +1,37 @@
+import { createInterface } from 'node:readline';
+/** cli context: confirm prompts on stdin, log writes to stderr. */
+export function makeCliContext() {
+    return {
+        env: process.env,
+        log(event) {
+            process.stderr.write(`[${event.level}] ${event.message}\n`);
+        },
+        confirm(prompt) {
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            return new Promise(resolve => {
+                // stdin EOF / SIGINT closes the interface — treat that as a "no".
+                rl.on('close', () => resolve(false));
+                rl.question(`${prompt} [y/N] `, answer => {
+                    // resolve before close: the first resolve wins, so the close
+                    // handler firing afterwards is a harmless no-op.
+                    resolve(/^y(es)?$/i.test(answer.trim()));
+                    rl.close();
+                });
+            });
+        },
+    };
+}
+/** mcp context: confirm is pre-resolved from the tool's `confirm` argument.
+ *  per-event logs are silently dropped — the command result's `summary` is
+ *  the sole output channel on the mcp surface. */
+export function makeMcpContext(confirmGranted) {
+    return {
+        env: process.env,
+        log() {
+            // mcp surfaces collect output via the result; per-event logs are dropped.
+        },
+        async confirm() {
+            return confirmGranted;
+        },
+    };
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,5 @@
+/** registers every CommandDef. idempotent — safe to call from each surface. */
+export declare function loadRegistry(): void;
+/** test-only: resets the loaded flag and clears the registry, so a test can
+ *  re-run loadRegistry from a clean state. */
+export declare function _resetLoader(): void;

package/dist/registry/index.js

@@ -0,0 +1,44 @@
+import { register, _resetRegistry } from './registry.js';
+import { addCommand } from '../commands/add.js';
+import { listCommand } from '../commands/list.js';
+import { statusCommand } from '../commands/status.js';
+import { startCommand } from '../commands/start.js';
+import { stopCommand } from '../commands/stop.js';
+import { restartCommand } from '../commands/restart.js';
+import { healthCommand } from '../commands/health.js';
+import { freezeCommand, unfreezeCommand } from '../commands/freeze.js';
+import { rollbackCommand } from '../commands/rollback.js';
+import { removeCommand } from '../commands/remove.js';
+import { initCommand } from '../commands/init.js';
+import { patchSystemdCommand } from '../commands/patch-systemd.js';
+import { bootStartCommand } from '../commands/boot-start.js';
+import { installMcpCommand } from '../commands/install-mcp.js';
+import { updateCommand } from '../commands/update.js';
+import { doctorCommand } from '../commands/doctor.js';
+import { configCommand, whoamiCommand } from '../commands/config.js';
+import { completionsCommand } from '../commands/completions.js';
+/** every command definition. commands are added here as they are migrated
+ *  onto the registry. */
+const ALL = [
+    addCommand, statusCommand, listCommand, startCommand, stopCommand, restartCommand,
+    healthCommand, freezeCommand, unfreezeCommand, rollbackCommand, removeCommand,
+    initCommand, patchSystemdCommand, bootStartCommand, installMcpCommand,
+    updateCommand, doctorCommand, configCommand, whoamiCommand, completionsCommand,
+];
+let loaded = false;
+/** registers every CommandDef. idempotent — safe to call from each surface. */
+export function loadRegistry() {
+    if (loaded)
+        return;
+    _resetRegistry();
+    for (const def of ALL) {
+        register(def);
+    }
+    loaded = true;
+}
+/** test-only: resets the loaded flag and clears the registry, so a test can
+ *  re-run loadRegistry from a clean state. */
+export function _resetLoader() {
+    loaded = false;
+    _resetRegistry();
+}

package/dist/registry/parse-args.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export type ParseResult = {
+    help: true;
+} | {
+    help: false;
+    ok: true;
+    values: Record<string, unknown>;
+} | {
+    help: false;
+    ok: false;
+    error: string;
+};
+export declare function parseArgs(schema: z.ZodObject<z.ZodRawShape>, argv: string[]): ParseResult;

package/dist/registry/parse-args.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+/** single-dash short flags, mapped to the long-form (schema) field they set.
+ *  short flags only ever set a boolean field true. */
+const SHORT_FLAGS = { y: 'yes' };
+/** true when a schema field (unwrapping optional/default) is a boolean. */
+function isBooleanField(schema) {
+    let s = schema;
+    while (s instanceof z.ZodOptional || s instanceof z.ZodDefault) {
+        s = s._def.innerType;
+    }
+    return s instanceof z.ZodBoolean;
+}
+export function parseArgs(schema, argv) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        return { help: true };
+    }
+    const shape = schema.shape;
+    const fieldNames = Object.keys(shape);
+    const booleanFields = new Set(fieldNames.filter(n => isBooleanField(shape[n])));
+    const values = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith('--')) {
+            const body = token.slice(2);
+            const eq = body.indexOf('=');
+            if (eq !== -1) {
+                // --key=value form
+                values[body.slice(0, eq)] = body.slice(eq + 1);
+                continue;
+            }
+            if (booleanFields.has(body)) {
+                values[body] = true;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                return { help: false, ok: false, error: `flag --${body} requires a value` };
+            }
+            values[body] = next;
+            i++;
+        }
+        else if (/^-[A-Za-z]$/.test(token)) {
+            // single-dash short flag (e.g. -y) — resolve via the alias table
+            const long = SHORT_FLAGS[token.slice(1)];
+            if (long === undefined || !(long in shape)) {
+                return { help: false, ok: false, error: `unknown flag: ${token}` };
+            }
+            values[long] = true;
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    // reject flags that aren't in the schema — a mistyped flag must not be dropped silently
+    const unknownFlags = Object.keys(values).filter(k => !(k in shape));
+    if (unknownFlags.length > 0) {
+        return { help: false, ok: false, error: `unknown flag(s): ${unknownFlags.join(', ')}` };
+    }
+    // assign leftover positionals to non-boolean fields in declaration order
+    const positionalFields = fieldNames.filter(n => !booleanFields.has(n) && !(n in values));
+    for (let i = 0; i < positionals.length && i < positionalFields.length; i++) {
+        values[positionalFields[i]] = positionals[i];
+    }
+    const parsed = schema.safeParse(values);
+    if (!parsed.success) {
+        return {
+            help: false,
+            ok: false,
+            error: parsed.error.issues.map(iss => `${iss.path.join('.')}: ${iss.message}`).join('; '),
+        };
+    }
+    return { help: false, ok: true, values: parsed.data };
+}

package/dist/registry/registry.d.ts

@@ -0,0 +1,24 @@
+import type { z } from 'zod';
+import type { CommandContext, CommandDef, CommandResult } from './types.js';
+export declare function register(def: CommandDef): void;
+/**
+ * defines a command with full argument-type inference: the `args` schema and
+ * the `run` handler's first parameter are tied through the shape generic `S`.
+ * returns the erased `CommandDef` the registry stores.
+ */
+export declare function defineCommand<S extends z.ZodRawShape, D>(def: {
+    name: string;
+    summary: string;
+    args: z.ZodObject<S>;
+    destructive?: boolean;
+    cliOnly?: boolean;
+    tui?: 'palette' | {
+        view: string;
+    };
+    run(args: z.infer<z.ZodObject<S>>, ctx: CommandContext): Promise<CommandResult<D>>;
+}): CommandDef<D>;
+export declare function getCommand(name: string): CommandDef | undefined;
+export declare function allCommands(): CommandDef[];
+/** test-only: clears the registry between tests. prefer _resetLoader() from
+ *  registry/index.ts if you also need to reset the loadRegistry guard. */
+export declare function _resetRegistry(): void;

package/dist/registry/registry.js

@@ -0,0 +1,26 @@
+const registry = new Map();
+export function register(def) {
+    if (registry.has(def.name)) {
+        throw new Error(`duplicate command registration: ${def.name}`);
+    }
+    registry.set(def.name, def);
+}
+/**
+ * defines a command with full argument-type inference: the `args` schema and
+ * the `run` handler's first parameter are tied through the shape generic `S`.
+ * returns the erased `CommandDef` the registry stores.
+ */
+export function defineCommand(def) {
+    return def;
+}
+export function getCommand(name) {
+    return registry.get(name);
+}
+export function allCommands() {
+    return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** test-only: clears the registry between tests. prefer _resetLoader() from
+ *  registry/index.ts if you also need to reset the loadRegistry guard. */
+export function _resetRegistry() {
+    registry.clear();
+}

package/dist/registry/render.d.ts

@@ -0,0 +1,3 @@
+import type { RenderModel } from './types.js';
+/** turns a RenderModel into a plain-text block for cli output. */
+export declare function renderToText(model: RenderModel): string;

package/dist/registry/render.js

@@ -0,0 +1,29 @@
+/** turns a RenderModel into a plain-text block for cli output. */
+export function renderToText(model) {
+    switch (model.kind) {
+        case 'lines':
+            return model.lines.join('\n');
+        case 'keyValue': {
+            const width = Math.max(0, ...model.pairs.map(([k]) => k.length));
+            return model.pairs.map(([k, v]) => `${k.padEnd(width + 2)}${v}`).join('\n');
+        }
+        case 'table': {
+            const all = [model.columns, ...model.rows];
+            const widths = model.columns.map((_, i) => Math.max(...all.map(row => (row[i] ?? '').length)));
+            const fmt = (row) => row
+                .slice(0, model.columns.length)
+                .map((cell, i) => (i === model.columns.length - 1 ? cell : cell.padEnd(widths[i] + 2)))
+                .join('');
+            return all.map(fmt).join('\n');
+        }
+        case 'tree':
+            return treeLines(model.root, 0).join('\n');
+    }
+}
+function treeLines(node, depth) {
+    const out = ['  '.repeat(depth) + node.label];
+    for (const child of node.children ?? []) {
+        out.push(...treeLines(child, depth + 1));
+    }
+    return out;
+}

package/dist/registry/types.d.ts

@@ -0,0 +1,50 @@
+import type { z } from 'zod';
+/** a renderable model each surface turns into text (cli) or components (tui). */
+export type RenderModel = {
+    kind: 'lines';
+    lines: string[];
+} | {
+    kind: 'keyValue';
+    pairs: Array<[string, string]>;
+} | {
+    kind: 'table';
+    columns: string[];
+    rows: string[][];
+} | {
+    kind: 'tree';
+    root: TreeNode;
+};
+export interface TreeNode {
+    label: string;
+    children?: TreeNode[];
+}
+/** the surface-agnostic result every command handler returns. */
+export interface CommandResult<D = unknown> {
+    ok: boolean;
+    summary: string;
+    data: D;
+    render?: RenderModel;
+}
+/** surface-neutral services passed to every handler. */
+export interface CommandContext {
+    confirm(prompt: string): Promise<boolean>;
+    log(event: {
+        level: 'info' | 'warn' | 'error';
+        message: string;
+    }): void;
+    env: NodeJS.ProcessEnv;
+}
+/** a command defined once; all three surfaces are derived from this. the
+ *  registry stores the erased form — `run` receives the already-parsed args
+ *  as a plain record. use `defineCommand` for inference at definition sites. */
+export interface CommandDef<D = unknown> {
+    name: string;
+    summary: string;
+    args: z.ZodObject<z.ZodRawShape>;
+    destructive?: boolean;
+    cliOnly?: boolean;
+    tui?: 'palette' | {
+        view: string;
+    };
+    run(args: Record<string, unknown>, ctx: CommandContext): Promise<CommandResult<D>>;
+}

package/dist/registry/types.js

@@ -0,0 +1 @@
+export {};

package/dist/templates/agent-unit.d.ts

@@ -0,0 +1,5 @@
+/** build the templated systemd unit for fleet-secrets-agent@%i.service.
+ *  the vault path comes from the caller — production code passes whatever
+ *  FLEET_VAULT_DIR or the repo-local default resolves to, so this template
+ *  never carries an operator-specific assumption. */
+export declare function generateAgentUnit(vaultPath: string): string;