@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/plugins/discovery/bundle-dialect/registry.ts

@@ -0,0 +1,250 @@
+/**
+ * The customer's MCP registry — `configs/mcp/registry.json` — and how a
+ * bundle's `mcpProfile` expands through it into an `mcpServers` map of the
+ * shape `mcp.json` carries.
+ *
+ * The file holds two lists:
+ *
+ *   servers   each with an `id`, a `name`, and the real config — either a
+ *             stdio launch (`command`, `args`, `env`) or `type: http` + `url`;
+ *             the config may sit under a `config` key or flat on the entry.
+ *   profiles  each with an `id`, the server ids it selects, and an optional
+ *             `extends` naming another profile (a chain, never a cycle).
+ *
+ * Pure: parse once, expand many. Unknown ids and cycles are warnings, never
+ * throws — a registry typo must not take every plugin down.
+ */
+import {
+  judgeMcpServerEntry,
+  type PortableHttpEntry,
+  type PortableStdioEntry,
+} from '../../../tool-manuals/mcp-json-discovery.js';
+
+export interface RegistryServer {
+  /** The registry's own key: what a profile lists, unique across the file. */
+  id: string;
+  /**
+   * What the server is CALLED once it runs — the `mcp.json` key, the
+   * `mcp__<name>__*` tool namespace a skill is written against. Several
+   * entries may share one (two transports of one server); a profile picks
+   * one of them. Absent, the id is the name.
+   */
+  name: string;
+  /**
+   * The server as one `mcp.json` entry — judged, and therefore usable, at
+   * parse time — plus every field of the config the judgement does not
+   * know (`startup_timeout_sec`, say), carried through untouched: a field a
+   * client understands must reach it, and one it does not it ignores.
+   */
+  entry: (PortableStdioEntry | PortableHttpEntry) & Record<string, unknown>;
+}
+
+export interface RegistryProfile {
+  id: string;
+  servers: string[];
+  extends?: string;
+}
+
+export interface McpRegistry {
+  servers: Map<string, RegistryServer>;
+  profiles: Map<string, RegistryProfile>;
+  /** Servers the registry declared but could not keep, by id, with the reason — so a profile selecting one can say why it is missing. */
+  rejected: Map<string, string>;
+  warnings: string[];
+}
+
+export function parseRegistry(text: string): McpRegistry {
+  const warnings: string[] = [];
+  const servers = new Map<string, RegistryServer>();
+  const profiles = new Map<string, RegistryProfile>();
+  const rejected = new Map<string, string>();
+  let root: unknown;
+  try {
+    root = JSON.parse(text);
+  } catch {
+    return { servers, profiles, rejected, warnings: ['registry.json is not valid JSON'] };
+  }
+  if (!isRecord(root)) return { servers, profiles, rejected, warnings: ['registry.json must be a JSON object'] };
+
+  for (const raw of asArray(root.servers)) {
+    if (!isRecord(raw) || typeof raw.id !== 'string' || !raw.id) {
+      warnings.push('registry.json: a server without an id was skipped');
+      continue;
+    }
+    if (servers.has(raw.id) || rejected.has(raw.id)) {
+      warnings.push(`registry.json: server "${raw.id}" is declared twice — the second declaration is ignored`);
+      continue;
+    }
+    // Converting IS the validation: a server the registry keeps is one whose
+    // entry a client can run — judged by the ONE rule every mcp.json entry
+    // meets (name, transport, required fields), after the customer's shape
+    // is translated into that of mcp.json.
+    const config = isRecord(raw.config) ? raw.config : raw;
+    const converted = mcpEntryOf(raw.id, config);
+    if ('reason' in converted) {
+      warnings.push(`registry.json: server "${raw.id}" ${converted.reason} — skipped`);
+      rejected.set(raw.id, converted.reason);
+      continue;
+    }
+    // The running name is the key a client sees, so it meets the same
+    // spelling rule the id just did. One that does not is not a reason to
+    // lose the server: it runs under its id, and the registry's author is
+    // told which skills will not find it.
+    let name = raw.id;
+    if (raw.name !== undefined) {
+      const declared = typeof raw.name === 'string' ? raw.name.trim() : '';
+      if (declared === raw.id) {
+        // Named as it is keyed: nothing to say.
+      } else if (declared && judgeMcpServerEntry(declared, { ...config, ...converted.entry }).ok) {
+        name = declared;
+      } else {
+        // Every name that is present and unusable is said, blank or not a
+        // string included: a skill written against it will not find the server.
+        warnings.push(
+          declared
+            ? `registry.json: server "${raw.id}" is named "${declared}", which cannot be a server name (lowercase alphanumeric with \`_\`/\`-\`) — it runs as "${raw.id}"`
+            : `registry.json: server "${raw.id}" has a name that is blank or not a string — it runs as "${raw.id}"`,
+        );
+      }
+    }
+    servers.set(raw.id, { id: raw.id, name, entry: converted.entry });
+  }
+  for (const raw of asArray(root.profiles)) {
+    if (!isRecord(raw) || typeof raw.id !== 'string' || !raw.id) {
+      warnings.push('registry.json: a profile without an id was skipped');
+      continue;
+    }
+    if (profiles.has(raw.id)) {
+      warnings.push(`registry.json: profile "${raw.id}" is declared twice — the second declaration is ignored`);
+      continue;
+    }
+    profiles.set(raw.id, {
+      id: raw.id,
+      servers: asArray(raw.servers).filter((s): s is string => typeof s === 'string'),
+      extends: typeof raw.extends === 'string' ? raw.extends : undefined,
+    });
+  }
+  return { servers, profiles, rejected, warnings };
+}
+
+/**
+ * The `mcpServers` map a profile resolves to, in `mcp.json` terms. Keyed by
+ * the server's NAME, not its registry id: the name is what a client
+ * registers the server as and what a skill's `mcp__<name>__*` calls are
+ * written against, and it is the namespace vault secrets bind to — so the
+ * two transports of one server (`figma-stdio` and `figma-remote`, both
+ * named `figma`) present as one server whichever a profile picks, and share
+ * one credential. A profile may select only one of them: two servers of one
+ * name in one expansion is a conflict, reported, and the nearer profile's
+ * wins. A selected server the registry could not keep is reported with the
+ * reason it was rejected, so the plugin's page can say what is missing.
+ */
+export function expandProfile(
+  registry: McpRegistry,
+  profileId: string,
+): { mcpServers: Record<string, unknown>; warnings: string[] } {
+  const warnings: string[] = [];
+  const ids: string[] = [];
+  const seen = new Set<string>();
+  let current: string | undefined = profileId;
+  while (current !== undefined) {
+    if (seen.has(current)) {
+      warnings.push(`registry.json: profile "${current}" extends itself through a cycle — chain cut`);
+      break;
+    }
+    seen.add(current);
+    const profile = registry.profiles.get(current);
+    if (!profile) {
+      warnings.push(`registry.json: profile "${current}" does not exist`);
+      break;
+    }
+    // Nearest profile first, so a base profile's servers come after the
+    // extending one's; the map below keeps the first occurrence of an id.
+    for (const id of profile.servers) if (!ids.includes(id)) ids.push(id);
+    current = profile.extends;
+  }
+  const mcpServers: Record<string, unknown> = {};
+  const holder = new Map<string, string>();
+  for (const id of ids) {
+    const server = registry.servers.get(id);
+    if (!server) {
+      const reason = registry.rejected.get(id);
+      warnings.push(
+        reason
+          ? `registry.json: profile "${profileId}" selects server "${id}", which was left out — ${reason}`
+          : `registry.json: profile "${profileId}" selects unknown server "${id}"`,
+      );
+      continue;
+    }
+    const first = holder.get(server.name);
+    if (first !== undefined) {
+      warnings.push(
+        `registry.json: profile "${profileId}" selects both "${first}" and "${id}", which are both named "${server.name}" — "${id}" left out`,
+      );
+      continue;
+    }
+    holder.set(server.name, id);
+    mcpServers[server.name] = server.entry;
+  }
+  return { mcpServers, warnings };
+}
+
+/**
+ * A registry config → one `mcp.json` server entry, or why there is none.
+ *
+ * The registry's OWN knowledge is the customer's shape: a declared `type`
+ * names the transport (`http` is their spelling of `streamable-http`), an
+ * undeclared one is read off the fields — a `url` means http, else a
+ * `command` means stdio — and blank strings are absent. That translation
+ * done, whether the entry can work is the shared judgement's call, the same
+ * one every `mcp.json` entry meets: a name that can be a server name, a
+ * transport the client speaks (no `sse`), the field that transport needs.
+ */
+function mcpEntryOf(
+  name: string,
+  config: Record<string, unknown>,
+): { entry: RegistryServer['entry'] } | { reason: string } {
+  const declared = typeof config.type === 'string' ? config.type.trim().toLowerCase() : undefined;
+  const url = nonBlank(config.url);
+  const command = nonBlank(config.command);
+  const type =
+    declared === undefined ? (url ? 'streamable-http' : command ? 'stdio' : undefined) : declared === 'http' ? 'streamable-http' : declared;
+  if (type === undefined) return { reason: 'has neither a url nor a command' };
+  const candidate: Record<string, unknown> = { type };
+  if (url) candidate.url = url;
+  if (command) candidate.command = command;
+  for (const key of ['args', 'env', 'cwd', 'headers'] as const) {
+    if (config[key] !== undefined) candidate[key] = config[key];
+  }
+  const verdict = judgeMcpServerEntry(name, candidate);
+  if (!verdict.ok) return { reason: verdict.reason };
+  // Every field the judgement did not read rides along as written: a
+  // `startup_timeout_sec` is meaningful to the client that knows it and
+  // harmless to one that does not, and dropping it silently was the
+  // customer's first complaint. The registry's own keys (`id`, `name`, a
+  // flat entry's) are the record's, not the server's.
+  const entry: Record<string, unknown> = { ...verdict.entry };
+  for (const [key, value] of Object.entries(config)) {
+    // Defined, not assigned: a field spelled `__proto__` is a field to
+    // carry, and assignment would set the object's prototype instead.
+    if (!JUDGED_OR_RECORD_KEYS.has(key)) {
+      Object.defineProperty(entry, key, { value, enumerable: true, configurable: true, writable: true });
+    }
+  }
+  return { entry: entry as RegistryServer['entry'] };
+}
+
+/** The config keys the judgement reads, plus the record's own; everything else passes through. */
+const JUDGED_OR_RECORD_KEYS = new Set(['type', 'url', 'command', 'args', 'env', 'cwd', 'headers', 'id', 'name', 'config']);
+
+function nonBlank(v: unknown): string | undefined {
+  return typeof v === 'string' && v.trim() ? v : undefined;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function asArray(v: unknown): unknown[] {
+  return Array.isArray(v) ? v : [];
+}

package/src/modules/plugins/discovery/kb-plugin-source.ts

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, pluginManifestName } from '@bevel-software/platform-shared';
+import type { DiscoveredPlugin, Discovery, PluginSource, PluginSourceWalk } from './plugin-source.js';
+import type { IFsProbe, ITreeWalker, WalkListener } from '../../../shared/fs.contract.js';
+import { readNativePlugin } from './native.source.js';
+import { BUNDLE_FILE, loadRegistry, readBundlePlugin } from './bundle-dialect/bundle.source.js';
+import type { McpRegistry } from './bundle-dialect/registry.js';
+
+/**
+ * THE plugin source: a LISTENER on the one walk of the checkout
+ * (`walkKb`), reading every folder under the plugins root in whichever of
+ * the two file shapes it carries.
+ *
+ *   plugin.json          → a native plugin (this platform's layout)
+ *   plugin.bundle.json   → a bundle (the customer dialect, read-only)
+ *
+ * Nothing else is a plugin. A folder's POSITION means nothing: the legacy
+ * rule "everything directly under the root is a plugin" is retired by the
+ * `plugin-manifests` boot step, which writes the manifest into every such
+ * folder once, so discovery never has to guess.
+ *
+ * A folder that IS a plugin claims everything beneath it (its `skills/` are
+ * its own) — the walk still visits what lies beneath, for the other
+ * listeners; this one ignores it. When a folder carries both files the
+ * manifest wins, so a bundle migrated in place stops being read as a bundle
+ * the moment a `plugin.json` lands beside it. Two plugins with one name keep
+ * the first by path (the walk's order) and warn about the second — a name is
+ * an identity to people and URLs, and two folders answering to it would be
+ * two plugins with one key.
+ *
+ * Holes — a folder under the root that could not be listed, an identity
+ * file that could not be read — are counted in `unreadable`: nothing behind
+ * them is listed, and a writer refuses while they exist.
+ *
+ * No setting picks a dialect. Nothing to configure means nothing to document
+ * and nothing to remove but the `else if` that reads bundles.
+ */
+export class KbPluginSource implements PluginSource {
+  readonly dialect = 'kb';
+
+  constructor(private readonly disk: ITreeWalker & IFsProbe) {}
+
+  async discover(kbRoot: string): Promise<Discovery> {
+    return (await this.walkWith(kbRoot, [])).discovery;
+  }
+
+  async walkWith(kbRoot: string, listeners: readonly WalkListener[]): Promise<PluginSourceWalk> {
+    const warnings: string[] = [];
+    const registry = await loadRegistry(kbRoot, warnings);
+    const listener = pluginListener(this.disk, kbRoot, registry, warnings);
+    const { holes } = await this.disk.walkKb(kbRoot, [listener.listener, ...listeners]);
+    return { discovery: listener.result(), holes };
+  }
+}
+
+/** The discovery listener over one walk, and the `Discovery` it has built once the walk is done. */
+function pluginListener(
+  disk: IFsProbe,
+  kbRoot: string,
+  registry: McpRegistry | null,
+  warnings: string[],
+): { listener: WalkListener; result(): Discovery } {
+  const unreadable: string[] = [];
+  const plugins: DiscoveredPlugin[] = [];
+  const seen = new Map<string, string>();
+  /** Folders claimed as plugins (or as holes standing where a plugin may be): nothing beneath is looked at. */
+  const claimed: string[] = [];
+
+  const underRoot = (rel: string) => rel === PLUGINS_DIR || rel.startsWith(`${PLUGINS_DIR}/`);
+  const beneathClaimed = (rel: string) => claimed.some((c) => rel === c || rel.startsWith(`${c}/`));
+
+  // Uniqueness is judged on the MANIFEST SLUG, not the raw name: `Sales Team`
+  // and `sales-team` fold to one slug, and the slug is what the compiled
+  // marketplace keys a plugin on — two folders sharing it would be two
+  // plugins with one key and one of them silently overwritten.
+  const claim = (plugin: DiscoveredPlugin): void => {
+    const key = pluginManifestName(plugin.name);
+    const twin = seen.get(key);
+    if (twin) {
+      warnings.push(`${plugin.folder}: plugin name "${plugin.name}" is already used by ${twin} — plugin skipped`);
+      return;
+    }
+    seen.set(key, plugin.folder);
+    plugins.push(plugin);
+  };
+
+  return {
+    listener: {
+      async onDir(rel, entries) {
+        if (!underRoot(rel) || rel === PLUGINS_DIR || beneathClaimed(rel)) return;
+        const has = (name: string) => entries.some((e) => e.isFile() && e.name === name);
+        const dir = path.join(kbRoot, rel);
+        const relFolder = rel.slice(PLUGINS_DIR.length + 1);
+        if (has(PLUGIN_MANIFEST_FILE)) {
+          claimed.push(rel);
+          // A manifest that could not be read: a hole, and still claimed.
+          const native = await readNativePlugin(disk, dir, rel, relFolder, warnings, unreadable);
+          if (native) claim(native);
+        } else if (has(BUNDLE_FILE)) {
+          claimed.push(rel);
+          const bundle = await readBundlePlugin(dir, rel, relFolder, registry, warnings, unreadable);
+          if (bundle) claim(bundle);
+        }
+      },
+      onHole(rel, err) {
+        // A folder under the root that could not be listed hides every plugin
+        // beneath it; said out loud rather than letting the catalog shrink in
+        // silence, and COUNTED so a writer can tell an incomplete listing from
+        // a complete one. (Holes elsewhere in the tree are the walk's to report.)
+        if (!underRoot(rel) || beneathClaimed(rel)) return;
+        warnings.push(`${rel}: could not be read — ${err instanceof Error ? err.message : String(err)}`);
+        unreadable.push(rel);
+      },
+    },
+    result: () => ({ plugins, warnings, unreadable, claimed }),
+  };
+}

package/src/modules/plugins/discovery/native.source.ts

@@ -0,0 +1,140 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  PLUGIN_MANIFEST_FILE,
+  PLUGIN_MCP_FILE,
+  isPersonalPluginDir,
+  isPluginIdentifier,
+  linkedSkillRoots,
+  pluginDisplayNameOf,
+  pluginIdentityOf,
+} from '@bevel-software/platform-shared';
+import { isAbsence, type IFsProbe } from '../../../shared/fs.contract.js';
+import type { DiscoveredPlugin } from './plugin-source.js';
+
+/**
+ * A plugin in the layout this platform writes (see `kb-layout.ts`): a folder
+ * carrying `plugin.json`, optionally `mcp.json`, and the `access.md` that
+ * makes it exist to the index. Called by the walker for every folder it
+ * decides is a native plugin; reads the files, decides nothing else.
+ *
+ * Null when the manifest exists but could not be READ: the manifest is the
+ * identity, and a plugin whose identity nobody could see is not listed under
+ * a guessed one — it is a hole (`unreadable`), like a folder that could not
+ * be listed. The optional `mcp.json` carries no identity, so its read
+ * failure is a warning and nothing more.
+ */
+export async function readNativePlugin(
+  disk: IFsProbe,
+  dir: string,
+  folder: string,
+  relFolder: string,
+  warnings: string[],
+  unreadable: string[],
+): Promise<DiscoveredPlugin | null> {
+  const folderName = path.posix.basename(relFolder);
+  const manifestRead = await readText(path.join(dir, PLUGIN_MANIFEST_FILE), folder, warnings);
+  if (manifestRead.failed) {
+    unreadable.push(`${folder}/${PLUGIN_MANIFEST_FILE}`);
+    return null;
+  }
+  // The walker probed the manifest a moment ago; gone now means it vanished
+  // between probe and read — then this is no plugin, not one under a guessed name.
+  if (manifestRead.text === null) return null;
+  const manifestText = manifestRead.text;
+  const mcpJsonText = (await readText(path.join(dir, PLUGIN_MCP_FILE), folder, warnings)).text;
+  const manifest = parseObject(manifestText);
+  if (manifest === null) {
+    warnings.push(`${folder}/${PLUGIN_MANIFEST_FILE} is not a JSON object — treated as absent`);
+  }
+  // The manifest's `name` IS the identity — the grants, the URLs, the
+  // marketplace all spell it — when it is an identifier. One that is not
+  // (spaces, capitals) is never silently reinterpreted: the folder stands
+  // in, and the mismatch is said out loud so a grant written against the
+  // manifest's spelling is not a mystery.
+  const name = pluginIdentityOf(manifest, folderName);
+  // The display name comes from the MANIFEST alone — `displayName`, else
+  // `name` — never from the folder. `|| name` is not a folder fallback in
+  // disguise: it catches only the manifest that names nothing usable, the
+  // same shape `pluginIdentityOf` just stood the folder in for, so the
+  // display name follows the identity the reader resolved rather than
+  // arriving empty.
+  const displayName = pluginDisplayNameOf(manifest) || name;
+  // Any PRESENT name that is not an identifier is worth a word — a number or
+  // an object as much as a capitalised string. Only an absent name is silent.
+  if (manifest && manifest.name !== undefined && !isPluginIdentifier(manifest.name)) {
+    // A diagnostic must never be the thing that fails: a non-string name is
+    // described by its type, not serialised (a value nested deep enough
+    // would blow the stack on the way to a warning).
+    const spelled =
+      typeof manifest.name === 'string'
+        ? `"${manifest.name}"`
+        : `a value of type ${Array.isArray(manifest.name) ? 'array' : typeof manifest.name}`;
+    warnings.push(
+      `${folder}/${PLUGIN_MANIFEST_FILE} names ${spelled}, which is not a plugin identifier (lowercase kebab-case) — the folder stands in as "${name}"`,
+    );
+  }
+  const mcp = parseObject(mcpJsonText);
+  const mcpServers =
+    mcp && typeof mcp.mcpServers === 'object' && mcp.mcpServers !== null && !Array.isArray(mcp.mcpServers)
+      ? (mcp.mcpServers as Record<string, unknown>)
+      : null;
+  // The plugin EXISTS to the index when its folder carries an `access.md`
+  // (links followed). Absence is "no rules yet"; a probe that fails for any
+  // other reason is a hole like an unreadable manifest — the plugin is not
+  // listed under a guessed answer, and a writer can refuse.
+  let exists: boolean;
+  try {
+    exists = (await disk.statOrNull(path.join(dir, 'access.md')))?.isFile() ?? false;
+  } catch (err) {
+    warnings.push(`${folder}/access.md could not be read — ${err instanceof Error ? err.message : String(err)}`);
+    unreadable.push(`${folder}/access.md`);
+    return null;
+  }
+  return {
+    name,
+    displayName,
+    folder,
+    relFolder,
+    // The one structural rule: a direct child of the root with the prefix.
+    personal: isPersonalPluginDir(folder),
+    exists,
+    manifest,
+    manifestText,
+    linkedRoots: linkedSkillRoots(manifest),
+    mcpServers,
+    mcpJsonText,
+    linksAreManaged: true,
+  };
+}
+
+/**
+ * A file's text — null when there is no such file — and whether a file that
+ * IS there could not be read. Absence and failure are different answers;
+ * the caller decides what a failure means for the file in question.
+ */
+async function readText(
+  abs: string,
+  folder: string,
+  warnings: string[],
+): Promise<{ text: string | null; failed: boolean }> {
+  try {
+    return { text: await fs.readFile(abs, 'utf-8'), failed: false };
+  } catch (err) {
+    if (isAbsence(err)) return { text: null, failed: false };
+    warnings.push(`${folder}/${path.basename(abs)} could not be read — ${err instanceof Error ? err.message : String(err)}`);
+    return { text: null, failed: true };
+  }
+}
+
+function parseObject(text: string | null): Record<string, unknown> | null {
+  if (text === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}

package/src/modules/plugins/discovery/plugin-source.ts

@@ -0,0 +1,113 @@
+import type { WalkListener } from '../../../shared/fs.contract.js';
+
+/**
+ * Plugin DISCOVERY as an interface — the one seam between "what a plugin is
+ * on disk" and everything that consumes plugins (the plugin index, the link
+ * index, the tool-manual scanner, the compiler).
+ *
+ * Two providers implement it:
+ *
+ *   - `native.source.ts`  — the Agent Plugins layout this platform writes:
+ *                           `Plugins/<Name>/plugin.json` (+ `mcp.json`,
+ *                           `access.md`, the hexis extension block).
+ *   - `bundle-dialect/`   — a customer's source layout: `plugin.bundle.json`
+ *                           files at any depth, pointing at skill roots and at
+ *                           an MCP profile in a registry. Read-only, and
+ *                           deletable as a unit once that customer migrates.
+ *
+ * Consumers see only {@link DiscoveredPlugin}: parsed objects, never files.
+ * A provider that reads a different file shape changes nothing downstream.
+ */
+export interface DiscoveredPlugin {
+  /**
+   * The plugin's IDENTITY everywhere a URL, a grant or a marketplace names
+   * it: the manifest's `name` — an Agent Plugins identifier — or the folder
+   * name folded into one when the manifest declares none it can be. A bundle
+   * plugin's is the bundle's `name`. Unique per source.
+   */
+  name: string;
+  /**
+   * What a person sees it called: the manifest's `displayName`, else its
+   * `name`. The manifest is the only source — never the folder. (The bundle
+   * dialect's own folder rule is resolved INTO the manifest it synthesizes,
+   * so the shared reader still says what the source reports.)
+   */
+  displayName: string;
+  /** Repo-relative folder holding the plugin, e.g. `Plugins/GTM`. */
+  folder: string;
+  /** The same folder relative to the plugins root, e.g. `GTM` or `functional/x/y`. */
+  relFolder: string;
+  /** A personal folder (`Plugins/personal-<id>`): a place, not a plugin. */
+  personal: boolean;
+  /**
+   * Whether the plugin EXISTS by the index's rule. Native: its folder carries
+   * an `access.md` (a bare directory is a ghost git left behind). Dialect:
+   * always — the bundle file is the existence.
+   */
+  exists: boolean;
+  /** The Agent Plugins manifest, parsed (a dialect synthesises one). Null when absent or unparsable. */
+  manifest: Record<string, unknown> | null;
+  /** The manifest's raw text, for readers that want the extension block verbatim (native only). */
+  manifestText: string | null;
+  /** Repo-relative roots the plugin LINKS skills from — a skill folder or a folder of skills. */
+  linkedRoots: string[];
+  /** The `mcpServers` map of the plugin's `mcp.json`, parsed; null when it has none. */
+  mcpServers: Record<string, unknown> | null;
+  /** The raw `mcp.json` text, when it exists on disk (native only). */
+  mcpJsonText: string | null;
+  /**
+   * Whether hexis manages this plugin's links — writes them, grants the
+   * plugin's principal on the skill, reports a missing grant as needing
+   * repair. False for a dialect, whose links are plain references and whose
+   * skills' own scopes decide readability.
+   */
+  linksAreManaged: boolean;
+}
+
+export interface Discovery {
+  plugins: DiscoveredPlugin[];
+  /** What was skipped and why — unparsable files, unknown profiles. */
+  warnings: string[];
+  /**
+   * HOLES: identity-bearing things that exist but could NOT be read
+   * (permissions, I/O), repo-relative — a folder that could not be listed,
+   * a manifest or bundle that could not be opened. Nothing behind a hole is
+   * in `plugins`: not absent, unseen, and never listed under a guessed name.
+   * A file that carries no identity (an `mcp.json`) is never a hole; its
+   * failure is a warning. A reader that only shows what it can carries on
+   * (the catalog does); a WRITER that keys a change on the set of plugins
+   * (a rename claiming a name) must refuse while this is not empty, or it
+   * may take an identity it could not see.
+   */
+  unreadable: string[];
+  /**
+   * Every folder a plugin CLAIMS, repo-relative — in `plugins` or not: a
+   * twin skipped for sharing a slug, a manifest that could not be read.
+   * Nothing beneath a claimed folder is a plugin to discovery, so nothing
+   * may be CREATED beneath one either: a plugin made inside a skipped twin
+   * would be listed by no catalog. `plugins` answers "what is there";
+   * this answers "where may nothing new go".
+   */
+  claimed: string[];
+}
+
+/** What one walk yields when discovery shares it: the plugins, and every hole the walk met anywhere. */
+export interface PluginSourceWalk {
+  discovery: Discovery;
+  /** Every folder the walk could not list, repo-relative — under the plugins root or anywhere else. */
+  holes: string[];
+}
+
+export interface PluginSource {
+  /** A short name for logs and the settings screen. */
+  readonly dialect: string;
+  /** Enumerate the plugins in a KB checkout. Never throws: a broken tree yields warnings. */
+  discover(kbRoot: string): Promise<Discovery>;
+  /**
+   * Discover while driving other listeners from the SAME walk — a writer
+   * that needs plugins and grant files alike reads the tree once, and sees
+   * one set of holes. Optional: a source that cannot share its walk is
+   * discovered on its own and the caller walks separately.
+   */
+  walkWith?(kbRoot: string, listeners: readonly WalkListener[]): Promise<PluginSourceWalk>;
+}

package/src/modules/plugins/index.ts

@@ -1,4 +1,4 @@
-export { PluginIndexService, pluginsWorkspaceId } from './plugins.service.js';
+export { PluginIndexService, pluginsWorkspaceId, pluginFolderBelowRoot } from './plugins.service.js';
 export {
   PluginProvisionService,
   PluginProvisionError,
@@ -6,11 +6,34 @@ export {
   personalAccessMd,
 } from './plugin-provision.service.js';
 export { JoinRequestsService, type JoinRequest } from './join-requests.service.js';
+export {
+  PluginJoinRequestJobs,
+  JoinRequestNotReadyError,
+  type JoinRequestJobsDeps,
+  type JoinRequestTarget,
+} from './join-request-jobs.service.js';
+export {
+  DbJoinRequestStore,
+  type JoinRequestRecord,
+  type JoinRequestStatus,
+  type JoinRequestStore,
+} from './join-request-records.store.js';
+export { PluginLinkIndex, type LinkMembership, type PluginLinks } from './plugin-links.js';
+export { PluginLinksService, PluginLinkError } from './plugin-links.service.js';
+export { PluginRenameService, PluginRenameError, renamePluginPrincipalInText } from './plugin-rename.service.js';
+export { compileMarketplace, type VirtualTree, type CompileInput, type MarketplaceOptions } from './compile/compile-marketplace.js';
+export { MarketplaceCompilerService, type CompileAudience } from './compile/marketplace-compiler.service.js';
+export type { PluginSource, PluginSourceWalk, DiscoveredPlugin, Discovery } from './discovery/plugin-source.js';
+export { KbPluginSource } from './discovery/kb-plugin-source.js';
+export { DEFAULT_REGISTRY_PATH } from './discovery/bundle-dialect/bundle.source.js';
 export { pendingProposals, type JoinProposal } from './join-proposals.js';
-export { createPluginsRoutes } from './plugins.routes.js';
+export { createPluginsRoutes, createPluginCreationRoutes } from './plugins.routes.js';
+export { createTeamsRoutes, type TeamAccess } from './teams.routes.js';
+export { registerPluginsTools } from './plugins.tools.js';
 export type {
   IPluginIndexService,
   PluginCatalogEntry,
+  PluginMembership,
   PluginSummary,
   ResolvedPrincipals,
   ResolvedReaders,