@staix/agent-console 0.0.0-stage → 0.1.0

package/shell/visual-frame.css

@@ -0,0 +1,5 @@
+/* acon visual frame (#29): the frame's own styles, selected by the light/dark class on <html>. No inline styles. */
+html.light { color-scheme: light; background: #ffffff; }
+html.dark { color-scheme: dark; background: #16181d; }
+body { margin: 0; padding: 8px; background: inherit; }
+#diagram img { display: block; max-width: 100%; height: auto; margin: 0 auto; }

package/shell/visual-frame.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Diagram</title>
+<link rel="stylesheet" href="/visual/frame.css">
+<script src="/visual/mermaid.js" defer></script>
+<script src="/visual/frame.js" defer></script>
+</head>
+<body>
+<div id="diagram" role="img" aria-label="Diagram"></div>
+</body>
+</html>

package/shell/visual-frame.js

@@ -0,0 +1,54 @@
+// acon visual frame (#29). Runs in a sandbox="allow-scripts" iframe: opaque origin, no cookies, no storage and,
+// by its own CSP, no network. It renders one Mermaid source per message and reports only {ok, height} or an error.
+"use strict";
+(() => {
+  const MAX_SOURCE = 20 * 1024;
+  const root = document.getElementById("diagram");
+  let seq = 0;
+  const reply = (msg) => parent.postMessage({ acon: "visual", ...msg }, "*");
+  // The vendored IIFE build assigns globalThis.mermaid.
+  const mermaid = typeof globalThis.mermaid?.render === "function" ? globalThis.mermaid : null;
+  const ready = mermaid !== null;
+  // The page's own content height: body padding plus the image box.
+  const height = () => Math.ceil(document.body.getBoundingClientRect().height) + 2;
+  /** Width and height from the SVG's viewBox (Mermaid always sets one), read without parsing it into this page. */
+  function size(svg) {
+    const box = /viewBox="\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)\s*"/.exec(svg);
+    return box ? { w: Number(box[1]), h: Number(box[2]) } : null;
+  }
+  async function render(data) {
+    const id = Number(data.id);
+    const source = typeof data.source === "string" ? data.source : "";
+    if (!mermaid) return reply({ id, ok: false, error: "renderer unavailable" });
+    if (!source || source.length > MAX_SOURCE) return reply({ id, ok: false, error: "source is empty or over 20 KB" });
+    const dark = data.theme === "dark";
+    try {
+      // Colors, margins and image sizing come from /visual/frame.css by this class; the frame sets no inline styles.
+      document.documentElement.className = dark ? "dark" : "light";
+      mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: dark ? "dark" : "default", darkMode: dark,
+        // Edge labels sit on a box that matches the canvas, so they stay readable in dark mode.
+        themeVariables: dark ? { edgeLabelBackground: "#16181d", textColor: "#e6e8ee" } : { edgeLabelBackground: "#ffffff" }, htmlLabels: false, flowchart: { htmlLabels: false }, fontFamily: "system-ui, sans-serif" });
+      // Mermaid lays out in its own temporary element during render(); this page assigns no markup. The result is
+      // shown as an image of the SVG, which runs no script and loads nothing (FRAME_CSP allows img-src data: only).
+      const { svg } = await mermaid.render(`acon-visual-${++seq}`, source);
+      const img = document.createElement("img");
+      img.alt = typeof data.title === "string" && data.title ? data.title : "Diagram";
+      const dims = size(svg);
+      if (dims) { img.width = Math.round(dims.w); img.height = Math.round(dims.h); }
+      await new Promise((done) => { img.onload = done; img.onerror = done; img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`; });
+      root.replaceChildren(img);
+      root.setAttribute("aria-label", img.alt);
+      requestAnimationFrame(() => reply({ id, ok: true, height: height() }));
+    } catch (error) {
+      root.replaceChildren();
+      reply({ id, ok: false, error: String(error && error.message ? error.message : error).split("\n")[0].slice(0, 200) });
+    }
+  }
+  window.addEventListener("message", (event) => {
+    if (event.source !== parent) return;
+    const data = event.data;
+    if (!data || typeof data !== "object" || data.acon !== "visual-render") return;
+    void render(data);
+  });
+  reply({ ready: true, ok: ready });
+})();

package/src/assets.ts

@@ -0,0 +1,200 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export type ImageType = "image/webp" | "image/png";
+export interface AssetImage { file: string; type: ImageType }
+export interface AssetModel { file: string; type: "model/gltf-binary" }
+export interface AssetPack {
+  id: string;
+  name: string;
+  version: 1;
+  tile: [number, number];
+  images: Record<string, AssetImage>;
+  models?: Record<string, AssetModel>;
+}
+
+const ASSET_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const IMAGE_FILE = /^[A-Za-z0-9._-]+\.(webp|png)$/;
+const MODEL_FILE = /^[A-Za-z0-9._-]+\.glb$/;
+const MANIFEST_MAX = 16 * 1024;
+const IMAGE_MAX = 4 * 1024 * 1024;
+const codeOf = (error: unknown) => (error as NodeJS.ErrnoException | null)?.code ?? "error";
+const unreadable = (error: unknown) => `could not be read (${codeOf(error)})`;
+const limitText = (bytes: number) => bytes % (1024 * 1024) === 0 ? `${bytes / (1024 * 1024)} MB` : bytes % 1024 === 0 ? `${bytes / 1024} KB` : `${bytes} bytes`;
+
+/** Opens once without following a leaf symlink; all checks and bounded reads use that descriptor. */
+function readRegularFile(file: string, maxBytes: number, label: string): Buffer | string {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) return `${label} size limit must be a positive safe integer`;
+  let fd: number | undefined;
+  try {
+    if (lstatSync(dirname(file), { throwIfNoEntry: false })?.isSymbolicLink()) return `${label} package directory is not a regular directory`;
+    const entry = lstatSync(file, { throwIfNoEntry: false });
+    if (!entry?.isFile()) return `${label} is missing or not a regular file`;
+    if (entry.size > maxBytes) return `${label} is larger than ${limitText(maxBytes)}`;
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const before = fstatSync(fd);
+    if (!before.isFile()) return `${label} is missing or not a regular file`;
+    if (before.size > maxBytes) return `${label} is larger than ${limitText(maxBytes)}`;
+    // One extra byte detects growth, without reading an unbounded stream or reopening the path.
+    const bytes = Buffer.alloc(before.size + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(fd, bytes, length, bytes.length - length, null);
+      if (count === 0) break;
+      length += count;
+    }
+    const after = fstatSync(fd);
+    if (length > maxBytes || after.size > maxBytes) return `${label} is larger than ${limitText(maxBytes)}`;
+    if (length !== before.size || after.size !== before.size) return `${label} changed while being read`;
+    return bytes.subarray(0, length);
+  } catch (error) {
+    return unreadable(error);
+  } finally {
+    if (fd !== undefined) try { closeSync(fd); } catch { /* a failed close must not hide the validation result */ }
+  }
+}
+
+function imageType(bytes: Uint8Array): ImageType | undefined {
+  const head = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (head.length >= 12 && head.toString("latin1", 0, 4) === "RIFF" && head.toString("latin1", 8, 12) === "WEBP") return "image/webp";
+  if (head.length >= 8 && head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
+}
+
+/** Returns the bytes that were checked, suitable for an HTTP response without a later path lookup. */
+export function readValidatedImage(file: string, maxBytes: number, label = "image"): { bytes: Uint8Array; type: ImageType } | string {
+  const bytes = readRegularFile(file, maxBytes, label);
+  if (typeof bytes === "string") return bytes;
+  const type = imageType(bytes);
+  return type ? { bytes, type } : `${label} is not a WebP or PNG image`;
+}
+
+/** Shared by local asset packs, pet packages and the separate installer. */
+export function validateImage(file: string, maxBytes: number, label = "image"): AssetImage | string {
+  const result = readValidatedImage(file, maxBytes, label);
+  return typeof result === "string" ? result : { file, type: result.type };
+}
+
+/** GLB 2 files are self-contained: the browser never follows a model's resource URLs. */
+function modelProblem(bytes: Buffer): string | undefined {
+  if (bytes.length < 20 || bytes.toString("latin1", 0, 4) !== "glTF" || bytes.readUInt32LE(4) !== 2 || bytes.readUInt32LE(8) !== bytes.length) return "must be a GLB 2 model with a valid glTF header and length";
+  let offset = 12, json: unknown, binaryLength = 0, binarySeen = false;
+  while (offset < bytes.length) {
+    if (offset + 8 > bytes.length) return "has a truncated chunk header";
+    const length = bytes.readUInt32LE(offset), type = bytes.readUInt32LE(offset + 4);
+    const start = offset + 8;
+    if (length % 4 !== 0 || start + length > bytes.length) return "has an invalid chunk length";
+    if (offset === 12) {
+      if (type !== 0x4e4f534a || length === 0) return "must start with a JSON chunk";
+      try { json = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start, start + length))); }
+      catch { return "has an invalid JSON chunk"; }
+    } else if (type === 0x004e4942 && !binarySeen) { binaryLength = length; binarySeen = true; }
+    else return "has an unsupported or duplicate chunk";
+    offset = start + length;
+  }
+  const object = (value: unknown): value is Record<string, unknown> => Boolean(value && typeof value === "object" && !Array.isArray(value));
+  if (!object(json) || !object(json.asset) || json.asset.version !== "2.0") return "must declare glTF asset version 2.0";
+  if (json.buffers !== undefined) {
+    if (!Array.isArray(json.buffers) || json.buffers.length > 1) return "must use a single embedded buffer";
+    for (const buffer of json.buffers) {
+      if (!object(buffer) || buffer.uri !== undefined) return "must use embedded buffers without resource URLs";
+      if (!Number.isSafeInteger(buffer.byteLength) || (buffer.byteLength as number) < 0 || (buffer.byteLength as number) > binaryLength || binaryLength - (buffer.byteLength as number) > 3) return "has an invalid embedded buffer length";
+    }
+  }
+  if (json.bufferViews !== undefined) {
+    if (!Array.isArray(json.bufferViews)) return "bufferViews must be an array";
+    const bufferLength = Array.isArray(json.buffers) && object(json.buffers[0]) ? json.buffers[0].byteLength as number : 0;
+    for (const view of json.bufferViews) {
+      if (!object(view) || view.buffer !== 0) return "has an invalid embedded buffer view";
+      const start = view.byteOffset ?? 0, length = view.byteLength;
+      if (typeof start !== "number" || typeof length !== "number" || !Number.isSafeInteger(start) || !Number.isSafeInteger(length) || start < 0 || length < 0 || start + length > bufferLength) return "has an invalid embedded buffer view";
+    }
+  }
+  if (json.images !== undefined) {
+    if (!Array.isArray(json.images)) return "images must be an array";
+    for (const image of json.images) {
+      if (!object(image) || image.uri !== undefined) return "must use embedded images without resource URLs";
+      if (!Number.isSafeInteger(image.bufferView) || (image.bufferView as number) < 0 || !Array.isArray(json.bufferViews) || (image.bufferView as number) >= json.bufferViews.length || !["image/png", "image/jpeg", "image/webp"].includes(String(image.mimeType))) return "has an invalid embedded image";
+    }
+  }
+}
+
+/** Returns exactly the descriptor-checked bytes, with the same 4 MB cap used at serve time. */
+export function readValidatedModel(file: string, maxBytes = IMAGE_MAX, label = "model"): { bytes: Uint8Array; type: "model/gltf-binary" } | string {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) return `${label} size limit must be a positive safe integer`;
+  const bytes = readRegularFile(file, Math.min(maxBytes, IMAGE_MAX), label);
+  if (typeof bytes === "string") return bytes;
+  const problem = modelProblem(bytes);
+  return problem ? `${label} ${problem}` : { bytes, type: "model/gltf-binary" };
+}
+
+/** Shared with local installation; model paths are never sent to the page. */
+export function validateModel(file: string, maxBytes = IMAGE_MAX, label = "model"): AssetModel | string {
+  const result = readValidatedModel(file, maxBytes, label);
+  return typeof result === "string" ? result : { file, type: result.type };
+}
+
+/** Validates one local pack. No package, manifest, image or model leaf may be a symlink. */
+export function validateAssetPack(dir: string): AssetPack | string {
+  try {
+    const directory = resolve(dir);
+    if (!lstatSync(directory, { throwIfNoEntry: false })?.isDirectory()) return "pack path is missing or not a directory";
+    const manifest = readRegularFile(join(directory, "pack.json"), MANIFEST_MAX, "pack.json");
+    if (typeof manifest === "string") return manifest;
+    let value: unknown;
+    try { value = JSON.parse(manifest.toString("utf8")); } catch { return "pack.json is not valid JSON"; }
+    if (!value || typeof value !== "object" || Array.isArray(value)) return "pack.json must be an object";
+    const row = value as Record<string, unknown>;
+    if (typeof row.id !== "string" || !ASSET_ID.test(row.id)) return "id must match [a-z0-9][a-z0-9-]{0,31}";
+    if (typeof row.name !== "string" || !row.name.trim() || row.name.length > 64) return "name must be a string of 1-64 characters";
+    if (row.version !== 1) return "version must be 1";
+    if (!Array.isArray(row.tile) || row.tile.length !== 2 || row.tile.some((size) => !Number.isSafeInteger(size) || size <= 0)) return "tile must be a pair of positive safe integers";
+    if (!row.images || typeof row.images !== "object" || Array.isArray(row.images)) return "images must be an object";
+    const images: Record<string, AssetImage> = Object.create(null) as Record<string, AssetImage>;
+    for (const [name, file] of Object.entries(row.images)) {
+      if (!ASSET_ID.test(name)) return `image ${name}: logical name must match [a-z0-9][a-z0-9-]{0,31}`;
+      if (typeof file !== "string" || !IMAGE_FILE.test(file)) return `image ${name}: file must be a .webp or .png file name in the package`;
+      const image = validateImage(join(directory, file), IMAGE_MAX, `image ${name}`);
+      if (typeof image === "string") return `image ${name}: ${image}`;
+      images[name] = image;
+    }
+    const models: Record<string, AssetModel> = Object.create(null) as Record<string, AssetModel>;
+    if (row.models !== undefined) {
+      if (!row.models || typeof row.models !== "object" || Array.isArray(row.models)) return "models must be an object";
+      for (const [name, file] of Object.entries(row.models)) {
+        if (!ASSET_ID.test(name)) return `model ${name}: logical name must match [a-z0-9][a-z0-9-]{0,31}`;
+        if (typeof file !== "string" || !MODEL_FILE.test(file)) return `model ${name}: file must be a .glb file name in the package`;
+        const model = validateModel(join(directory, file), IMAGE_MAX, `model ${name}`);
+        if (typeof model === "string") return `model ${name}: ${model}`;
+        models[name] = model;
+      }
+    }
+    return { id: row.id, name: row.name.trim(), version: 1, tile: [row.tile[0] as number, row.tile[1] as number], images, ...(row.models !== undefined ? { models } : {}) };
+  } catch (error) {
+    return unreadable(error);
+  }
+}
+
+/** Console asset directories in priority order; the first valid occurrence of each id wins. */
+export function loadAssetPacks(dirs: string[]): { packs: AssetPack[]; problems: string[] } {
+  const packs: AssetPack[] = [];
+  const problems: string[] = [];
+  const ids = new Set<string>();
+  for (const dir of dirs) {
+    let names: string[];
+    try { names = readdirSync(dir).sort(); } catch (error) {
+      if (codeOf(error) !== "ENOENT") problems.push(`${dir}: ${unreadable(error)}`);
+      continue;
+    }
+    for (const name of names) {
+      const file = join(dir, name);
+      try {
+        const entry = lstatSync(file, { throwIfNoEntry: false });
+        if (entry && !entry.isDirectory() && !entry.isSymbolicLink()) continue;
+        const pack = validateAssetPack(file);
+        if (typeof pack === "string") problems.push(`${file}: ${pack}`);
+        else if (!ids.has(pack.id)) { ids.add(pack.id); packs.push(pack); }
+      } catch (error) { problems.push(`${file}: ${unreadable(error)}`); }
+    }
+  }
+  return { packs, problems };
+}

package/src/canonical.ts

@@ -0,0 +1,16 @@
+/**
+ * Key-sorted JSON, so the same input always binds to the same confirm token.
+ * Two different inputs never share a form: -0 is kept apart from 0, and non-finite numbers (JSON "1e400" parses to
+ * Infinity, which JSON.stringify would print as null) throw instead of colliding.
+ */
+export function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new RangeError("numbers must be finite");
+    return Object.is(value, -0) ? "-0" : JSON.stringify(value);
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical((value as Record<string, unknown>)[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}

package/src/cli.ts

@@ -0,0 +1,155 @@
+import pkg from "../package.json" with { type: "json" };
+import { familyHome, loadPlugins, scanPlugins, type PluginEntry } from "./plugins.ts";
+import { startServer } from "./server.ts";
+import { loadPets, petDirs } from "./pets.ts";
+import { loadAssetPacks } from "./assets.ts";
+import { join } from "node:path";
+import { DEFAULT_INDEX, fetchIndex, installPackage, InstallError, printable } from "./install.ts";
+import { serveConfig, type ServeOptions } from "./serve.ts";
+
+const USAGE = `acon ${pkg.version}: local console for agent-hub, agent-mem and vault-mem
+
+Usage:
+  acon ui [--no-open] [--json]   serve the console on 127.0.0.1 and print a one-time link
+  acon serve [--host H] [--port P] [--origin https://host]... [--json]
+                                 resident console behind Cloudflare Access or a bearer token
+  acon plugins [--json]          list registered plugins and verify their module hashes
+  acon install <name|https URL|dir> [--force]
+                                 install a pet or asset package
+  acon install --list [--json]   list the packages in the index
+  acon --version | help
+
+Plugins register a manifest under $AGENTHUB_HOME/console/plugins (default ~/.agenthub).
+Packages install to $AGENTHUB_HOME/console/pets/<id> or console/assets/<id>; ACON_ASSETS_INDEX overrides the index URL.
+serve auth: ACON_ACCESS_TEAM + ACON_ACCESS_AUD (Cloudflare Access) or ACON_TOKEN_FILE (bearer); required off loopback.
+The ui server exits 5 minutes after the last request; serve stays up.`;
+
+const COMMANDS: Record<string, string[]> = { ui: ["--no-open", "--json"], plugins: ["--json"], install: ["--list", "--force", "--json"], serve: ["--json"] };
+const VALUED: Record<string, string[]> = { serve: ["--host", "--port", "--origin"] };
+
+function parse(argv: string[]): { command: string; flags: Set<string>; args: string[]; values: Record<string, string[]> } | string {
+  const [command = "help", ...all] = argv;
+  if (["help", "--help", "-h", "--version", "-v", "version"].includes(command)) return { command, flags: new Set(), args: [], values: {} };
+  const allowed = COMMANDS[command];
+  if (!allowed) return `unknown command: ${command}`;
+  const values: Record<string, string[]> = {};
+  const rest: string[] = [];
+  for (let i = 0; i < all.length; i += 1) {
+    const arg = all[i]!;
+    const [name, inline] = arg.startsWith("--") && arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+    if (VALUED[command]?.includes(name)) {
+      const value = inline ?? all[++i];
+      if (value === undefined || value === "") return `${name} needs a value`;
+      (values[name] ??= []).push(value);
+    } else rest.push(arg);
+  }
+  for (const name of ["--host", "--port"]) if ((values[name]?.length ?? 0) > 1) return `${name} may be given once`;
+  const args = command === "install" ? rest.filter((arg) => !arg.startsWith("--")) : [];
+  const unknown = rest.find((arg) => !args.includes(arg) && !allowed.includes(arg));
+  if (unknown) return `unknown option for ${command}: ${unknown}`;
+  const flags = new Set(rest.filter((arg) => !args.includes(arg)));
+  if (command === "install") {
+    if (flags.has("--list") ? args.length > 0 || flags.has("--force") : args.length !== 1) return "install takes one package name, https URL or directory, or --list";
+  }
+  return { command, flags, args, values };
+}
+
+const summary = (p: PluginEntry) => ({ tool: p.tool, ...(p.version ? { version: p.version } : {}), status: p.status, ...(p.reason ? { reason: p.reason } : {}), file: p.file });
+
+function openBrowser(url: string): void {
+  const argv = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
+  try { Bun.spawn(argv, { stdio: ["ignore", "ignore", "ignore"] }).unref(); }
+  catch { console.error("acon: could not open a browser; open the link above yourself"); }
+}
+
+async function install(home: string, source: string | undefined, flags: Set<string>): Promise<number> {
+  const index = process.env.ACON_ASSETS_INDEX || DEFAULT_INDEX;
+  try {
+    if (flags.has("--list")) {
+      const { packages } = await fetchIndex(index);
+      if (flags.has("--json")) console.log(JSON.stringify({ index, packages }));
+      else {
+        console.log(`Packages in ${printable(index, 500)}:`);
+        for (const p of packages) console.log(`${p.kind.padEnd(5)} ${p.id.padEnd(16)} ${`${Math.ceil(p.size / 1024)} KB`.padStart(8)}  ${printable(p.name, 64)}${p.description ? `: ${printable(p.description)}` : ""}`);
+        console.log("Install one with acon install <id>.");
+      }
+      return 0;
+    }
+    const r = await installPackage(source!, { home, index, force: flags.has("--force") });
+    if (flags.has("--json")) console.log(JSON.stringify(r));
+    else {
+      console.log(`acon: ${r.replaced ? "replaced" : "installed"} ${r.kind} ${r.id} in ${r.dir} (${r.files.length} files)`);
+      console.log(r.verified ? "acon: every file matched its sha256 in the index." : "acon: not hash-verified (installed by URL or directory); the package passed the same checks the console runs.");
+      console.log("acon: run acon ui again to see it.");
+    }
+    return 0;
+  } catch (error) {
+    console.error(`acon: ${error instanceof InstallError ? error.message : `install failed (${printable(String((error as NodeJS.ErrnoException).code ?? (error as Error).message), 500)})`}`);
+    return 1;
+  }
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const parsed = parse(argv);
+  if (typeof parsed === "string") { console.error(`acon: ${parsed}\n\n${USAGE}`); return 2; }
+  const { command, flags, args, values } = parsed;
+  if (["--version", "-v", "version"].includes(command)) { console.log(pkg.version); return 0; }
+  if (["help", "--help", "-h"].includes(command)) { console.log(USAGE); return 0; }
+  const home = familyHome();
+  if (command === "install") return await install(home, args[0], flags);
+  let serve: ServeOptions | undefined;
+  if (command === "serve") {
+    const config = serveConfig({ host: values["--host"]?.[0], port: values["--port"]?.[0], origins: values["--origin"] ?? [] }, process.env);
+    if (typeof config === "string") { console.error(`acon: ${config}`); return 2; }
+    serve = config;
+  }
+  const scan = scanPlugins(home);
+  if (command === "plugins") {
+    if (flags.has("--json")) console.log(JSON.stringify({ dir: scan.dir, ...(scan.error ? { error: scan.error } : {}), plugins: scan.entries.map(summary) }));
+    else {
+      if (scan.error) console.error(`acon: ${scan.error}`);
+      if (!scan.entries.length) console.log(`No plugins registered in ${scan.dir}.`);
+      for (const p of scan.entries) console.log(`${`${p.tool}${p.version ? `@${p.version}` : ""}`.padEnd(24)} ${p.status.padEnd(9)} ${p.reason ?? p.module ?? ""}`);
+    }
+    return scan.error || scan.entries.some((p) => p.status !== "verified") ? 1 : 0;
+  }
+  const log = (line: string) => console.error(`acon: ${line}`);
+  const plugins = await loadPlugins(scan, { home, log });
+  const { pets, problems: petProblems } = loadPets(petDirs(home));
+  const { packs: assetPacks, problems: assetProblems } = loadAssetPacks([join(home, "console", "assets")]);
+  const server = startServer({
+    plugins,
+    reload: (previous) => loadPlugins(scanPlugins(home), { home, log }, previous),
+    pets,
+    petProblems,
+    assetPacks,
+    assetProblems,
+    version: pkg.version,
+    pluginsDir: scan.dir,
+    pluginsError: scan.error,
+    log,
+    ...(serve ? { serve } : { onIdle: () => { log("no requests for 5 minutes; exiting"); process.exit(0); } }),
+  });
+  const shutdown = () => { void server.stop().finally(() => process.exit(0)); };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  if (serve) {
+    const info = { origin: server.origin, port: server.port, mode: serve.mode, origins: serve.origins, pid: process.pid, plugins: plugins.map(summary) };
+    if (flags.has("--json")) console.log(JSON.stringify(info));
+    else {
+      console.log(`acon: serving on ${serve.hostname}:${server.port} (${serve.mode === "access" ? "Cloudflare Access" : serve.mode === "bearer" ? "bearer token" : "loopback, no auth"}); allowed origins: ${serve.origins.join(", ")}`);
+      if (scan.error) log(scan.error);
+      for (const p of plugins) if (p.status !== "ready") log(`${p.tool} not loaded (${p.status}): ${p.reason}`);
+    }
+    return await new Promise<number>(() => {});
+  }
+  const url = server.issue();
+  if (flags.has("--json")) console.log(JSON.stringify({ url, origin: server.origin, pid: process.pid, plugins: plugins.map(summary) }));
+  else {
+    console.log(`acon: console at ${url}\nacon: the link works once and expires in 60 s; run acon ui again for a new one.`);
+    if (scan.error) log(scan.error);
+    for (const p of plugins) if (p.status !== "ready") log(`${p.tool} not loaded (${p.status}): ${p.reason}`);
+  }
+  if (!flags.has("--no-open")) openBrowser(url);
+  return await new Promise<number>(() => {});
+}