Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

27.2 KB
Raw Blame
/**
 * Plugins: the library this build ships, the user plugin directory an operator installs into,
 * the registry a deployment lists, and what an Agent has installed.
 *   GET    /api/plugins                                   # the built-in library by category (any logged-in user)
 *   GET    /api/plugins/directory                         # the user plugin directory (any logged-in user)
 *   POST   /api/plugins/upload                            # install a plugin from an uploaded zip (admin)
 *   POST   /api/plugins/download                          # install a plugin fetched from a URL or npm (admin)
 *   GET    /api/plugins/:plugin/files                     # the files a library plugin ships, for the detail view's browser
 *   GET    /api/plugins/:plugin/archive                   # export a plugin as a zip (any logged-in user)
 *   DELETE /api/plugins/:plugin                           # uninstall a user plugin (admin)
 *   GET    /api/plugins/registry                          # the merged plugin index: the curated entries and one per package this build ships
 *   GET    /api/plugins/registry/readme?name=…            # one indexed entry's long-form readme
 *   POST   /api/projects/:p/agents/:a/plugins             # install plugins from the library (any member)
 *
 * The import and delete routes write inside the user plugin directory, which is part of the
 * installation rather than of a Project — that is what makes them admin-only (machines.ts is
 * the same call) and what makes them take no projectId. They need no restart and no
 * invalidation of anything: the library is read from disk on every request (core's plugin
 * loader caches nothing), so an imported plugin is in the listing and installable the moment
 * the request returns. A name the build already ships is refused rather than shadowed — the
 * loader would go on serving the built-in — and `overwrite` is what says a same-named *user*
 * plugin may be replaced.
 *
 * Installing a plugin writes each of its skills to agent_state/skills/<name>/ and its hook
 * package to agent_state/hooks/<plugin>/ (hooks.json + scripts); reinstalling overwrites with
 * library content (i.e. an update). Installed skills and hook packages keep their own routes
 * (skills.ts, hooks.ts).
 *
 * Library and registry are two views of one kind of thing — a package of skills and/or
 * hooks. The library is what this build carries; the registry is what the deployment can
 * fetch. Both are deployment-global (no Project check); only installing touches an Agent.
 */
import path from "node:path";
import { strToU8, unzipSync, zipSync } from "fflate";
import { Hono } from "hono";
import type { Context } from "hono";
import {
  PLUGIN_NAME_PATTERN,
  installPlugin,
  installUserPlugin,
  libraryPlugin,
  listInstalledHooks,
  listInstalledSkills,
  loadPluginGroups,
  removeUserPlugin,
  userPluginInstalled,
  userPluginRoots,
  userPluginsDir,
} from "@adelie/core";
import type {
  AgentPluginsInstallResponse,
  PluginDirectoryResponse,
  PluginFilesResponse,
  PluginImportResponse,
  PluginIndexEntry,
  PluginIndexResponse,
  PluginLibraryResponse,
  PluginReadmeResponse,
} from "../../api/types.js";
import type { AppEnv } from "../../auth/middleware.js";
import type { ServerConfig } from "../../config.js";
import type { Config, Hmr } from "../../hmr/capabilities.js";
import type { AgentConfig } from "../../mechanisms/agents.js";
import type { Access } from "../../mechanisms/projects.js";
import type { Sessions as ManagerIface } from "../../runtime/session-manager.js";
import { Bind, Component, Use } from "@adelie/core/kernel";
import { agentHooksRoutes } from "./hooks.js";
import {
  builtinPluginRegistry,
  configuredPluginMarket,
  shippedPluginNames,
} from "../../plugin/registry.js";
import type { PluginRegistry } from "../../plugin/registry.js";
import { pluginBases } from "../../plugin/loader.js";
import type { PluginBase } from "../../plugin/loader.js";

/** What these route groups reach — bound by their component below. */
export interface PluginsRouteDeps {
  config: ServerConfig;
  access: Access;
  agentConfigService: AgentConfig;
  manager: ManagerIface;
}
import { HttpError } from "../errors.js";
import {
  badRequest,
  optionalBoolean,
  optionalString,
  optionalStringArray,
  readJson,
  requireString,
  requireValidId,
} from "../validate.js";
import {
  pluginArchiveFiles,
  pluginFiles,
  resolveLibraryPlugins,
  toHookItem,
  toPluginItem,
  toSkillItem,
} from "../../services/plugin-library.js";
import {
  fetchPluginArchive,
  pluginArchiveTooLarge,
  resolvePluginSource,
} from "../../services/plugin-download.js";
import { gunzipBounded, isGzip, tarEntryNames, untarBounded } from "../../services/tar-archive.js";
import { assertSafeEntryPath, MAX_ARCHIVE_BYTES } from "./skills.js";
import { unzipBounded } from "../../services/skill-import-limits.js";

/** Library listing: the files are the source of truth — read fresh on every request (small files, infrequent requests, no caching). */
function libraryResponse(root: string): PluginLibraryResponse {
  return {
    groups: loadPluginGroups(root).map((group) => ({
      id: group.id,
      title: group.title,
      ...(group.titleZh !== undefined ? { titleZh: group.titleZh } : {}),
      plugins: group.plugins.map(toPluginItem),
    })),
  };
}

/**
 * The guard on everything that writes the user plugin directory. It is an installation-level
 * resource — every Project reads it, and an installed plugin's hook scripts run with the
 * server's own rights once an Agent runs them — so the capability is the admin's rather than a
 * Project owner's, the way installing to a machine is.
 */
function requireAdmin(c: Context<AppEnv>): void {
  if (!c.var.user.isAdmin) {
    throw new HttpError(403, "admin_required", "Only an admin can manage the plugin directory.");
  }
}

/** A plugin archive decoded and located: the name it installs under, and every file of the plugin root keyed by path relative to it. */
export interface ParsedPluginArchive {
  name: string;
  files: Record<string, Uint8Array>;
}

/**
 * Every entry name in an archive, in central-directory order, without inflating a byte: the
 * filter refuses each entry as it is offered, and fflate stops there. That is what makes the
 * two-pass read above cheap — locating the plugin root costs a directory scan, not an unpack.
 */
function entryNames(archive: Uint8Array): string[] {
  const names: string[] = [];
  unzipSync(archive, {
    filter: (entry) => {
      names.push(entry.name);
      return false;
    },
  });
  return names;
}

/** How deep a plugin root path is ("" is the archive root, i.e. depth 0). */
function pathDepth(dir: string): number {
  return dir === "" ? 0 : dir.split("/").length;
}

/**
 * The plugin root inside an archive: the shallowest directory carrying `plugin.json`, which has
 * to be the only directory at that depth — an archive holding two plugins is ambiguous and
 * refused rather than guessed at. `plugin.json` at the archive root is depth 0 and therefore
 * always wins, and everything outside the root is ignored (an archive may carry a README, a
 * LICENSE or a whole monorepo beside the plugin).
 *
 * `subdir` narrows the search to a directory at the end of that path, the way a GitHub tree URL
 * (`…/tree/<ref>/plugins/x`) names one: the archive's own top-level `<repo>-<ref>/` directory is
 * whatever the host wrapped it in, so the match is on the tail, not on the whole path.
 */
function pluginRootIn(paths: readonly string[], subdir: string): string {
  const dirs = new Set<string>();
  for (const filePath of paths) {
    if (filePath !== "plugin.json" && !filePath.endsWith("/plugin.json")) continue;
    const dir = filePath.slice(0, filePath.length - "plugin.json".length).replace(/\/$/, "");
    if (subdir !== "" && dir !== subdir && !dir.endsWith(`/${subdir}`)) continue;
    dirs.add(dir);
  }
  if (dirs.size === 0) {
    throw badRequest(
      subdir === ""
        ? "The archive carries no plugin.json — it is not a plugin."
        : `The archive carries no plugin.json under ${subdir}.`,
    );
  }
  const sorted = [...dirs].sort((a, b) => pathDepth(a) - pathDepth(b) || a.localeCompare(b));
  const root = sorted[0]!;
  if (sorted.length > 1 && pathDepth(sorted[1]!) === pathDepth(root)) {
    throw badRequest(
      `The archive carries more than one plugin (${sorted.filter((d) => pathDepth(d) === pathDepth(root)).join(", ")}).`,
    );
  }
  return root;
}

/**
 * Decodes an uploaded or downloaded archive into the files of one plugin. Everything a client
 * supplies is checked here, before a byte is written: the declared sizes through `unzipBounded` /
 * `untarBounded` (which is where the caps have to be enforced — see those modules), every entry
 * path against traversal, the plugin root's ambiguity, and the name against the plugin-name rule.
 * Directories the archive declares are skipped: the paths of the files recreate them.
 *
 * Two formats reach this function, and it does not care which: a zip (an operator's upload, a
 * GitHub archive, an exported plugin) and the gzipped tar npm publishes (see
 * services/plugin-download.ts). The signature bytes decide, and everything after that — the root,
 * the caps, the naming — is the same question about the same kind of content.
 */
export function parsePluginArchive(
  archive: Buffer,
  options: { name?: string; subdir?: string } = {},
): ParsedPluginArchive {
  // Two passes, because an archive is not necessarily a plugin: a GitHub tree download is a
  // whole repository with one plugin somewhere inside it. The first pass reads the entry names
  // alone — a zip's central directory, a tar's headers — to find the plugin root; the second
  // unpacks that root's files only. So the caps bound the PLUGIN (200 files, 5MB each, 20MB
  // total, the same numbers an upload of a single plugin gets) instead of failing on the
  // repository that happens to be wrapped around it, and a hundred-megabyte checkout is never
  // expanded to serve a thirty-file plugin.
  const bytes = new Uint8Array(archive);
  const tarball = isGzip(bytes);
  // A tarball is gunzipped first, and that happens before any of the above: its headers are only
  // reachable through the compression, so its own module bounds what one may inflate to.
  const opened = tarball ? gunzipBounded(bytes) : bytes;
  let names: string[];
  try {
    names = tarball ? tarEntryNames(opened) : entryNames(bytes);
  } catch (err) {
    if (err instanceof HttpError) throw err;
    throw badRequest(
      tarball ? "The archive is not a valid npm tarball." : "The archive is not a valid zip file.",
    );
  }
  if (names.length === 0) throw badRequest("The archive contains no files.");
  const root = pluginRootIn(names, options.subdir ?? "");
  const prefix = root === "" ? "" : `${root}/`;
  let entries: Record<string, Uint8Array>;
  try {
    entries = tarball
      ? untarBounded(opened, (name) => prefix === "" || name.startsWith(prefix))
      : unzipBounded(bytes, (name) => prefix === "" || name.startsWith(prefix));
  } catch (err) {
    // The caps arrive as 400s of their own; anything else means the bytes are not that format.
    if (err instanceof HttpError) throw err;
    throw badRequest(
      tarball ? "The archive is not a valid npm tarball." : "The archive is not a valid zip file.",
    );
  }
  const rootFiles: Record<string, Uint8Array> = {};
  for (const [entry, data] of Object.entries(entries)) {
    if (entry.endsWith("/")) continue;
    // The tar reader checked its own member paths as it walked them — the walk is what chooses the
    // root, so it cannot be deferred; a zip's central directory carries them unchecked, and this
    // is where they are checked.
    if (!tarball) assertSafeEntryPath(entry);
    rootFiles[entry.slice(prefix.length)] = data;
  }
  // The archive's own layout names the plugin unless the request says otherwise. Two layouts
  // cannot: plugin.json at the archive's root, and a tarball — which npm wraps in a `package/`
  // directory that names the publisher's package format rather than anybody's plugin.
  const named =
    tarball && root === "package" ? undefined : root === "" ? undefined : path.basename(root);
  const name = options.name ?? named;
  if (name === undefined) {
    throw badRequest(
      tarball
        ? "name is required for a tarball: npm wraps every package in a `package/` directory, which names the format rather than the plugin."
        : "name is required when the archive carries plugin.json at its root.",
    );
  }
  if (!PLUGIN_NAME_PATTERN.test(name)) {
    throw new HttpError(400, "invalid_plugin", `Not a valid plugin name: ${name}`);
  }
  return { name, files: rootFiles };
}

/**
 * Installs a parsed archive into the user plugin directory and answers what the library now
 * carries. The two refusals come first, before anything is written: a built-in name (the loader
 * would go on serving the built-in, so the import would be invisible), and an existing user
 * plugin without `overwrite` (409 — replacing is an explicit decision, the user's copy may
 * carry local edits).
 *
 * The directory is `<config.root>/plugins`, the same one the library reads: the server's data
 * root and the library's user plugin root are one directory, both defined by ADELIE_HOME.
 */
async function importPlugin(
  deps: PluginsRouteDeps,
  parsed: ParsedPluginArchive,
  overwrite: boolean,
): Promise<PluginImportResponse> {
  const root = deps.config.root;
  if (libraryPlugin(parsed.name, deps.config.root)?.source === "builtin") {
    throw new HttpError(
      409,
      "plugin_builtin",
      `${parsed.name} is a built-in plugin; it cannot be replaced (import it under another name).`,
    );
  }
  if (!overwrite && (await userPluginInstalled(root, parsed.name))) {
    throw new HttpError(
      409,
      "plugin_exists",
      `A user plugin named ${parsed.name} is already installed.`,
    );
  }
  let plugin;
  try {
    plugin = await installUserPlugin(root, parsed.name, parsed.files);
  } catch (err) {
    throw new HttpError(
      400,
      "invalid_plugin",
      `The plugin could not be installed: ${err instanceof Error ? err.message : String(err)}`,
    );
  }
  return {
    plugin: toPluginItem(plugin),
    path: path.join(userPluginsDir(root), parsed.name),
  };
}

/** GET /api/plugins (any logged-in user; no Project check). */
export function pluginLibraryRoutes(deps: PluginsRouteDeps): Hono<AppEnv> {
  const app = new Hono<AppEnv>();
  app.get("/", (c) => c.json(libraryResponse(deps.config.root)));

  // The user plugin directory itself: its absolute path and what is in it. Readable by anyone
  // logged in — the library listing shows the same plugins, and this only adds where they live
  // — because the management line on the plugins page is not an admin's screen.
  app.get("/directory", (c) =>
    c.json({
      path: userPluginsDir(deps.config.root),
      plugins: [...userPluginRoots(deps.config.root).keys()],
    } satisfies PluginDirectoryResponse),
  );

  // Install one plugin from an uploaded zip (admin). The body carries the archive base64 —
  // the same shape the skill and hook archive routes take — so the request stays JSON
  // throughout and needs no multipart handling.
  app.post("/upload", async (c) => {
    requireAdmin(c);
    const body = await readJson(c);
    const dataBase64 = requireString(body, "dataBase64", { minLen: 1, label: "dataBase64" });
    const archive = Buffer.from(dataBase64, "base64");
    if (archive.byteLength === 0) throw badRequest("The zip archive is empty.");
    // The same answer the download path gives (413 `plugin_too_large`), at the cap the transport
    // allows: this one arrives as base64 inside a JSON body, so it is the skill/hook archive
    // limit — which is exactly what keeps the encoded request inside the body cap.
    if (archive.byteLength > MAX_ARCHIVE_BYTES) {
      throw pluginArchiveTooLarge(MAX_ARCHIVE_BYTES);
    }
    const requestedName = optionalString(body, "name", { maxLen: 128 });
    const parsed = parsePluginArchive(archive, {
      ...(requestedName !== undefined ? { name: requestedName } : {}),
    });
    return c.json(
      await importPlugin(deps, parsed, optionalBoolean(body, "overwrite") ?? false),
      201,
    );
  });

  // Install one plugin from what the operator names (admin): an address, or an npm package
  // (`@scope/name[@version]`, or the `npm:` spelling — see resolvePluginSource). The whole
  // download runs server-side: the server is what has the network position to reach it, and the
  // archive is validated by the same parser the upload route uses, whichever way the bytes
  // arrived. An npm name costs two requests (the packument, then the tarball it points at); the
  // checksum the packument carries comes back with the source and is verified on the bytes.
  app.post("/download", async (c) => {
    requireAdmin(c);
    const body = await readJson(c);
    const url = requireString(body, "url", { minLen: 1, maxLen: 2048 });
    const requestedName = optionalString(body, "name", { maxLen: 128 });
    const requestedSubdir = optionalString(body, "subdir", { maxLen: 512 });
    const source = await resolvePluginSource(url);
    const archive = await fetchPluginArchive(source);
    if (archive.byteLength === 0) throw badRequest("The download is empty.");
    // What the request says wins over what the URL suggests: a name is what the operator asked
    // for, a suggestion is what the host happened to call it.
    const name = requestedName ?? source.name;
    const parsed = parsePluginArchive(archive, {
      ...(name !== undefined ? { name } : {}),
      subdir: requestedSubdir ?? source.subdir,
    });
    return c.json(
      await importPlugin(deps, parsed, optionalBoolean(body, "overwrite") ?? false),
      201,
    );
  });

  // Everything one plugin ships, as text keyed by path, for the library detail view's file
  // browser (the listing never carries bodies or scripts).
  app.get("/:plugin/files", (c) => {
    const pluginName = c.req.param("plugin");
    const plugin = libraryPlugin(pluginName, deps.config.root);
    if (!plugin) {
      throw new HttpError(404, "unknown_plugin", `Plugin is not in the library: ${pluginName}`);
    }
    return c.json({ files: pluginFiles(plugin) } satisfies PluginFilesResponse);
  });

  // Export one plugin as a zip (any logged-in user — it is the content the detail view already
  // shows, packed for a round trip out). Built-in and user plugins export the same way: the
  // archive is rebuilt from the library's own view of the plugin, so what comes back in is what
  // went out.
  app.get("/:plugin/archive", (c) => {
    const plugin = libraryPlugin(c.req.param("plugin"), deps.config.root);
    if (!plugin) {
      throw new HttpError(
        404,
        "unknown_plugin",
        `Plugin is not in the library: ${c.req.param("plugin")}`,
      );
    }
    const archiveFiles: Record<string, Uint8Array> = {};
    for (const [rel, text] of Object.entries(pluginArchiveFiles(plugin))) {
      archiveFiles[rel] = strToU8(text);
    }
    const zip = zipSync(archiveFiles);
    // The name is the plugin name (validated on the way in, [A-Za-z0-9_-]+), so it is itself
    // when encoded; scripts.ts reads the file name off Content-Disposition.
    const fileName =
      plugin.version === "" ? `${plugin.name}.zip` : `${plugin.name}-v${plugin.version}.zip`;
    return new Response(new Uint8Array(zip), {
      headers: {
        "Content-Type": "application/zip",
        "Content-Disposition": `attachment; filename*=UTF-8''${encodeURIComponent(fileName)}`,
        "X-Content-Type-Options": "nosniff",
      },
    });
  });

  // Uninstall one user plugin (admin): the directory is deleted from disk, so the library stops
  // listing it. A built-in is refused (409) — its files belong to the installation — and a name
  // that is not there at all is a 404 rather than a silent no-op.
  app.delete("/:plugin", async (c) => {
    requireAdmin(c);
    const pluginName = c.req.param("plugin");
    if (!PLUGIN_NAME_PATTERN.test(pluginName)) {
      throw new HttpError(404, "unknown_plugin", `No such plugin: ${pluginName}`);
    }
    if (libraryPlugin(pluginName, deps.config.root)?.source === "builtin") {
      throw new HttpError(409, "plugin_builtin", `${pluginName} is a built-in plugin.`);
    }
    if (!(await removeUserPlugin(deps.config.root, pluginName))) {
      throw new HttpError(404, "unknown_plugin", `No user plugin named ${pluginName}`);
    }
    return c.body(null, 204);
  });

  return app;
}

/** /api/projects/:p/agents/:a/plugins: install is a Project-member operation. */
export function agentPluginsRoutes(deps: PluginsRouteDeps): Hono<AppEnv> {
  const app = new Hono<AppEnv>();

  app.post("/", async (c) => {
    const projectId = requireValidId(c, "projectId");
    const agentId = requireValidId(c, "agentId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    await deps.agentConfigService.requireExists(projectId, agentId);
    const names = optionalStringArray(await readJson(c), "names") ?? [];
    if (names.length === 0) throw badRequest("names must be a non-empty array.");
    // Verify every name up front before writing anything: an unknown name rejects the whole
    // request rather than leaving a half-installed state.
    const plugins = resolveLibraryPlugins(names, deps.config.root);
    for (const plugin of plugins) {
      await installPlugin(deps.config.root, projectId, agentId, plugin);
    }
    // Core reads hook packages when a model context opens: a conversation that is running
    // would keep the old set — or none — until its next compaction. Rebuilding the runtime
    // re-reads them on its next idle access, so the plugin works from the next Task.
    deps.manager.invalidateAgentRuntimes(projectId, agentId);
    const [skills, hooks] = await Promise.all([
      listInstalledSkills(deps.config.root, projectId, agentId),
      listInstalledHooks(deps.config.root, projectId, agentId),
    ]);
    return c.json(
      {
        skills: skills.map(toSkillItem),
        hooks: hooks.map(toHookItem),
      } satisfies AgentPluginsInstallResponse,
      201,
    );
  });

  return app;
}

/** The plugin library and the Agent-scoped install/uninstall groups, as one route component. */
@Component({
  contributes: {
    "HttpModule.routes": [
      { id: "PluginRoutes.library", prefix: "/api/plugins", auth: "user", order: 70 },
      {
        id: "PluginRoutes.agent-plugins",
        prefix: "/api/projects/:projectId/agents/:agentId/plugins",
        auth: "user",
        order: 222,
      },
      {
        id: "PluginRoutes.agent-hooks",
        prefix: "/api/projects/:projectId/agents/:agentId/hooks",
        auth: "user",
        order: 224,
      },
    ],
  },
})
export class PluginRoutes {
  @Use() private readonly config!: Config;
  @Use() private readonly access!: Access;
  @Use() private readonly agentConfig!: AgentConfig;
  @Use() private readonly manager!: ManagerIface;
  @Bind("PluginRoutes.library") libraryRoutes!: Hono<AppEnv>;
  @Bind("PluginRoutes.agent-plugins") pluginRoutes!: Hono<AppEnv>;
  @Bind("PluginRoutes.agent-hooks") hookRoutes!: Hono<AppEnv>;
  setup() {
    const deps = {
      config: this.config,
      access: this.access,
      agentConfigService: this.agentConfig,
      manager: this.manager,
    };
    this.libraryRoutes = pluginLibraryRoutes(deps);
    this.pluginRoutes = agentPluginsRoutes(deps);
    this.hookRoutes = agentHooksRoutes(deps);
  }
}

export function pluginRegistryRoutes(
  bases: () => readonly PluginBase[],
  root: () => string,
  /** The published side of the shelf, or null when this deployment lists only what it carries. */
  published: PluginRegistry | null = null,
): Hono<AppEnv> {
  const app = new Hono<AppEnv>();
  const builtin = builtinPluginRegistry({
    bases,
    // The shelf is what this build ships: read per call, because a push moves both the
    // assets prefix the bases name and the library a deployment carries.
    shipped: () => shippedPluginNames(root(), bases()),
  });
  // The sources, in precedence order: what this build carries first, then the published side.
  // A package both of them list is ONE entry — the build's, whose version is the one installed
  // here — so a plugin that ships needs no entry written for it on the published side.
  const sources: readonly PluginRegistry[] = published === null ? [builtin] : [builtin, published];
  const index = async (): Promise<PluginIndexEntry[]> => {
    const seen = new Set<string>();
    const entries: PluginIndexEntry[] = [];
    for (const source of sources) {
      for (const entry of await source.index()) {
        if (seen.has(entry.name)) continue;
        seen.add(entry.name);
        entries.push(entry);
      }
    }
    return entries;
  };
  app.get("/", async (c) => {
    const body: PluginIndexResponse = { plugins: await index() };
    return c.json(body);
  });
  app.get("/readme", async (c) => {
    const name = c.req.query("name");
    if (name === undefined || name === "") {
      return c.json({ error: { code: "bad_request", message: "name is required" } }, 400);
    }
    // Only entries this deployment actually lists: the readme map is keyed by specifier,
    // and answering for an unlisted name would make the endpoint a probe of what exists.
    const listed = (await index()).some((e) => e.name === name);
    if (!listed) {
      return c.json({ error: { code: "not_found", message: "no such plugin" } }, 404);
    }
    // The first source that has one: a shipped package's README is the copy on this machine,
    // and only a package this build does not carry falls through to the published one.
    let readme: string | null = null;
    for (const source of sources) {
      readme = await source.readme(name);
      if (readme !== null) break;
    }
    const body: PluginReadmeResponse = { name, readme };
    return c.json(body);
  });
  return app;
}

/**
 * The registry the Plugins page reads beside the built-in library: deployment-global, and
 * nested under /api/plugins/registry so both views answer under one prefix. The specifier
 * is a query parameter on `readme`, not a path segment, because it is scoped
 * (`@scope/name`) and would otherwise have to survive two rounds of slash encoding.
 *
 * The shelf has two sides and only one of them is local: what this build carries, and what the
 * project has published (`npmPluginRegistry`). The published side is the server's second
 * automatic outbound call — the update check's is the first — and follows the same rules: one
 * cached lookup, a bounded timeout, never an error the page has to handle, and a switch
 * (`ADELIE_PLUGIN_MARKET=off`) for a deployment that must not dial out at all.
 */
@Component({
  contributes: {
    "HttpModule.routes": [
      {
        id: "PluginRegistryRoutes.routes",
        prefix: "/api/plugins/registry",
        auth: "user",
        order: 69,
      },
    ],
  },
})
export class PluginRegistryRoutes {
  @Use() private readonly config!: Config;
  @Use() private readonly hmr!: Hmr;
  /** Environment to read ADELIE_PLUGIN_MARKET from; a test wires its own. */
  private env: Record<string, string | undefined> = process.env;
  @Bind("PluginRegistryRoutes.routes") routes!: Hono<AppEnv>;
  setup() {
    // Read per request: a push moves the shipped prefix to a new assets directory.
    this.routes = pluginRegistryRoutes(
      () => pluginBases(this.config.root, this.hmr.assetsDir()),
      () => this.config.root,
      configuredPluginMarket(this.env),
    );
  }
}