@bevel-software/platform-core-backend 0.8.0 → 0.9.1

package/src/modules/workspace/{plugins-migration.ts → startup/steps/groups-to-plugins.step.ts}

@@ -11,19 +11,24 @@ import {
   PLUGIN_SKILLS_DIR,
   renderPluginManifest,
 } from '@bevel-software/platform-shared';
-import type { ToolManualDescriptor } from '../tool-manuals/tool-manuals.contract.js';
-import { normalizeToolManual } from '../tool-manuals/tool-manuals.service.js';
-import { parseOwnAccessEntries } from '../access/access-control.service.js';
-import { containsVariableReference } from '../../shared/variable-refs.js';
-import { IGNORE_FILENAME } from './bevel-ignore.js';
+import type { ToolManualDescriptor } from '../../../tool-manuals/tool-manuals.contract.js';
+import { normalizeToolManual } from '../../../tool-manuals/tool-manuals.service.js';
+import { parseOwnAccessEntries } from '../../../access/access-control.service.js';
+import { containsVariableReference } from '../../../../shared/variable-refs.js';
+import { IGNORE_FILENAME } from '../../bevel-ignore.js';
+import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 /**
  * One-way migration of a knowledge base from `Groups/` to the Agent Plugins
- * layout under `Plugins/` (https://agent-plugins.org, v1.0.0).
+ * layout under `Plugins/` (https://agent-plugins.org, v1.0.0), as an
+ * {@link OnServerStart} step. (It began life as an in-place module run from
+ * the lazy top-up; that path is gone, and this is the only form.) Steps
+ * never write: every change is DECLARED on the branch handle
+ * (`move`/`write`/`remove`) and the runner applies it, while every read goes
+ * against the real, pre-step tree via `repoDir()`.
  *
- * Runs from the seed top-up, so every deployment self-heals on the next load of
- * a protected branch. Idempotent: a KB already on the new layout is untouched,
- * and a half-finished run is completed by the next one.
+ * Idempotent: a KB already on the new layout is untouched, and a half-finished
+ * run is completed by the next one.
  *
  * What moves — and what CONVERTS:
  *
@@ -43,21 +48,26 @@ import { IGNORE_FILENAME } from './bevel-ignore.js';
  * `extensions["software.bevel.hexis"].mcpServers[<id>]` block, the reverse-DNS
  * namespace the spec reserves for client-specific data. `http`/`inline`
  * manuals still MOVE as `.tool` files: nothing but this platform can run them.
+ *
+ * Scope: EVERY branch, drafts included and writable (`ctx.allBranches()`) —
+ * maintenance applied uniformly at the quiet moment is what keeps a draft's
+ * change-request diff down to the user's own changes; a stale draft against a
+ * migrated target would diff by the whole rename.
+ *
+ * Outcomes: a per-manual NOT-converted refusal makes the step `partial` with
+ * the reasons (the declared ops for everything else still apply); a branch
+ * carrying BOTH roots contributes nothing but a note; everything else is `ok`.
  */
+export class GroupsToPluginsStep implements OnServerStart {
+  readonly name = 'groups-to-plugins';
 
-export interface PluginsMigrationResult {
-  /**
-   * Whether this run CHANGED FILES. Notes alone (a manual that could not be
-   * converted, say) do not set it — the caller stages and commits on this
-   * flag, and a note-only run has nothing to commit.
-   */
-  migrated: boolean;
-  /** Whether the `Groups/` → `Plugins/` root rename itself happened this run. */
-  renamed: boolean;
-  /** Whether the KB's own `.bevelignore` had its `Groups/` rule rewritten (a repo-root file, staged separately). */
-  ignoreRewritten: boolean;
-  /** Human-readable summary lines (plugin names, tool moves) for the seed log. */
-  notes: string[];
+  async run(ctx: ServerStartContext): Promise<StepResult> {
+    const refusals: string[] = [];
+    for (const branch of await ctx.allBranches()) {
+      await migrateBranch(branch, refusals);
+    }
+    return refusals.length > 0 ? { outcome: 'partial', reason: refusals.join('; ') } : { outcome: 'ok' };
+  }
 }
 
 // lstat, both helpers: SYMLINKS ARE NOT SUPPORTED IN PLUGINS, anywhere, so a
@@ -81,18 +91,6 @@ async function isDir(p: string): Promise<boolean> {
   }
 }
 
-/**
- * Move `from` to `to`, creating the parent. Never overwrites: a destination
- * that already exists means a previous run got there first (or a human did),
- * and clobbering it would destroy the newer copy.
- */
-async function moveIfAbsent(from: string, to: string): Promise<boolean> {
-  if (await exists(to)) return false;
-  await fs.mkdir(path.dirname(to), { recursive: true });
-  await fs.rename(from, to);
-  return true;
-}
-
 /**
  * A header value referencing a vault variable rather than carrying a literal.
  * The substitutor's own grammar decides (shared/variable-refs.ts): both
@@ -129,126 +127,6 @@ async function readJson(p: string): Promise<Record<string, unknown> | null> {
   }
 }
 
-/**
- * Fold converted mcp manuals into the plugin's mcp.json and plugin.json.
- *
- * MERGE, never clobber: an entry already present under a manual's key — hand
- * written or from a previous run — wins, because overwriting it would discard
- * the newer intent. The extension block merges the same way. A plugin.json
- * that does not parse costs the extension write (logged), not the migration.
- */
-interface ConvertedManual {
-  manual: ToolManualDescriptor;
-  /** The source `.tool`, deleted only once the fold has landed. */
-  abs: string;
-  note: string;
-}
-
-async function foldIntoPluginFiles(
-  pluginDir: string,
-  folderName: string,
-  manuals: ConvertedManual[],
-  notes: string[],
-): Promise<boolean> {
-  if (manuals.length === 0) return false;
-
-  const mcpPath = path.join(pluginDir, PLUGIN_MCP_FILE);
-  const mcp = (await readJson(mcpPath)) ?? { $schema: PLUGIN_MCP_SCHEMA, mcpServers: {} };
-  // An array (or any non-object) here would take property assignments and then
-  // drop them at stringify — normalize to an object before merging into it.
-  if (typeof mcp.mcpServers !== 'object' || mcp.mcpServers === null || Array.isArray(mcp.mcpServers)) {
-    mcp.mcpServers = {};
-  }
-  const servers = mcp.mcpServers as Record<string, unknown>;
-
-  const manifestPath = path.join(pluginDir, PLUGIN_MANIFEST_FILE);
-  const manifest = await readJson(manifestPath);
-  if (manifest === null) {
-    console.warn(
-      `[plugins-migration] ${folderName}/${PLUGIN_MANIFEST_FILE} is missing or unparsable — ` +
-        'mcp manuals convert only when they carry NOTHING for the extensions block; any ' +
-        'non-portable half (auth headers, variables, a description, or the local-only flag) ' +
-        'keeps the manual a `.tool` until the manifest is fixed.',
-    );
-  }
-
-  let wroteMcp = false;
-  let wroteManifest = false;
-  const folded: ConvertedManual[] = [];
-  for (const item of manuals.sort((a, b) => a.manual.name.localeCompare(b.manual.name))) {
-    const m = item.manual;
-    const { literal, credential } = splitHeaders(m.headers);
-    // A manual whose non-portable half (auth headers, variables, local flag)
-    // has nowhere to go — the manifest is missing or unparsable — is NOT
-    // converted at all: writing only its portable half and deleting the
-    // source would silently discard the credential wiring. It stays a
-    // `.tool` until the manifest is fixed.
-    const extEntryPreview = {
-      ...(Object.keys(credential).length > 0 ? { headers: credential } : {}),
-      ...(m.variables && m.variables.length > 0 ? { variables: m.variables } : {}),
-      ...(typeof m.description === 'string' ? { description: m.description } : {}),
-      ...(m.remote === false ? { local: true } : {}),
-    };
-    if (manifest === null && Object.keys(extEntryPreview).length > 0) {
-      notes.push(
-        `${folderName}: ${item.note} NOT converted — ${PLUGIN_MANIFEST_FILE} is missing/unparsable ` +
-          'and the manual carries declarations (auth headers, variables, a description, or the ' +
-          'local-only flag) that would be lost; fix the manifest first.',
-      );
-      continue;
-    }
-    folded.push(item);
-    // Own-property check: `in` sees `constructor` and friends on the prototype,
-    // which would silently skip a legitimately named server.
-    if (!Object.prototype.hasOwnProperty.call(servers, m.name)) {
-      servers[m.name] = {
-        type: 'streamable-http',
-        url: m.url,
-        ...(Object.keys(literal).length > 0 ? { headers: literal } : {}),
-      };
-      wroteMcp = true;
-      notes.push(`${folderName}: ${m.name} → ${PLUGIN_MCP_FILE}`);
-    }
-
-    // The non-portable half: auth headers, variable declarations, local-only.
-    const extEntry = extEntryPreview;
-    if (manifest !== null && Object.keys(extEntry).length > 0) {
-      // Normalize each level: a parseable manifest can still carry a string or
-      // array where an object belongs, and mutating that would throw mid-run.
-      if (typeof manifest.extensions !== 'object' || manifest.extensions === null || Array.isArray(manifest.extensions)) {
-        manifest.extensions = {};
-      }
-      const ext = manifest.extensions as Record<string, unknown>;
-      if (typeof ext[HEXIS_EXTENSION_NS] !== 'object' || ext[HEXIS_EXTENSION_NS] === null || Array.isArray(ext[HEXIS_EXTENSION_NS])) {
-        ext[HEXIS_EXTENSION_NS] = {};
-      }
-      const ns = ext[HEXIS_EXTENSION_NS] as Record<string, unknown>;
-      if (typeof ns.mcpServers !== 'object' || ns.mcpServers === null || Array.isArray(ns.mcpServers)) {
-        ns.mcpServers = {};
-      }
-      const extServers = ns.mcpServers as Record<string, unknown>;
-      if (!Object.prototype.hasOwnProperty.call(extServers, m.name)) {
-        extServers[m.name] = extEntry;
-        wroteManifest = true;
-      }
-    }
-  }
-
-  if (wroteMcp) await fs.writeFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`, 'utf8');
-  if (wroteManifest) {
-    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-    notes.push(`${folderName}: wrote mcp-server declarations into ${PLUGIN_MANIFEST_FILE}`);
-  }
-  // Sources go LAST, once everything they carried is on disk elsewhere. A
-  // failure anywhere above leaves every `.tool` in place for the next run —
-  // which re-converts idempotently, since the fold never clobbers a key.
-  for (const item of folded) {
-    await fs.rm(item.abs, { force: true });
-    notes.push(`${folderName}: ${item.note} converted to an ${PLUGIN_MCP_FILE} entry`);
-  }
-  return wroteMcp || wroteManifest || folded.length > 0;
-}
-
 /**
  * Parse a `.tool`; a convertible MCP manual (has a url) parses to a
  * descriptor. A non-candidate (other types, a file that will not parse)
@@ -302,46 +180,195 @@ async function asMcpManual(abs: string, repoRel: string): Promise<ToolManualDesc
   }
 }
 
-/** Reorganise ONE plugin folder in place. Returns notes + whether files changed. */
+interface ConvertedManual {
+  manual: ToolManualDescriptor;
+  /** Repo-relative path of the source `.tool`, removed only once the fold has been declared. */
+  rel: string;
+  note: string;
+}
+
+/**
+ * Migrate one branch. Declares ops only; a branch whose migration declares
+ * nothing stays clean, so a notes-only pass (advisory refusals) commits
+ * nothing — the same contract the in-place migration's `migrated` flag
+ * carried.
+ */
+async function migrateBranch(branch: KbBranch, refusals: string[]): Promise<void> {
+  const repoDir = await branch.repoDir();
+  const legacyDir = path.join(repoDir, LEGACY_GROUPS_DIR);
+  const pluginsDir = path.join(repoDir, PLUGINS_DIR);
+
+  const hasLegacy = await isDir(legacyDir);
+  const hasPlugins = await isDir(pluginsDir);
+
+  // `hasPlugins` is false for a FILE or SYMLINK squatting the `Plugins` name.
+  // Checked BEFORE the nothing-to-do early return below: a branch with a
+  // squatter and NO Groups/ would otherwise be silently skipped (and on a
+  // draft nothing later ever reports it), while a branch mid-migration would
+  // die in the applier with a bare ENOTDIR. Throw the actionable version
+  // either way: under the phase's fail-closed contract this stops the boot,
+  // which a squatted reserved root deserves (same stance as
+  // template-files.step.ts's reserved-dir check).
+  if (!hasPlugins && (await exists(pluginsDir))) {
+    throw new Error(
+      `Branch "${branch.name}": "${PLUGINS_DIR}" exists but is not a directory` +
+        (hasLegacy ? `, so ${LEGACY_GROUPS_DIR}/ cannot be renamed to ${PLUGINS_DIR}/` : '') +
+        `. Remove or rename the "${PLUGINS_DIR}" entry — the platform requires this name to be a folder.`,
+    );
+  }
+
+  if (hasLegacy && hasPlugins) {
+    // Both present: somebody is mid-migration by hand, or two branches merged
+    // badly. Merging them here would guess at which copy of a same-named
+    // plugin wins, so we refuse and say so — loudly, because the KB is in a
+    // state a human needs to look at. The branch contributes no ops, only a
+    // note (which surfaces in a commit only if a later step dirties it).
+    console.warn(
+      `[groups-to-plugins] ${branch.name}: both ${LEGACY_GROUPS_DIR}/ and ${PLUGINS_DIR}/ exist — leaving both alone. ` +
+        `Merge ${LEGACY_GROUPS_DIR}/ into ${PLUGINS_DIR}/ by hand; nothing is being migrated automatically.`,
+    );
+    branch.note(
+      `${LEGACY_GROUPS_DIR}/ and ${PLUGINS_DIR}/ both exist — merge by hand; nothing was migrated automatically`,
+    );
+    return;
+  }
+  if (!hasLegacy && !hasPlugins) return;
+
+  // Every read below goes against the PRE-STEP tree: when the root rename is
+  // declared this run it is NOT yet on disk, so the plugin folders are still
+  // read under their legacy root while every declared op speaks post-rename
+  // `Plugins/…` paths — the root move is declared FIRST, so by the time the
+  // per-folder ops apply, the tree is already under `Plugins/`.
+  const rootOnDisk = hasLegacy ? legacyDir : pluginsDir;
+  // Detail notes are held back until we know ops were declared: the subject
+  // line must describe a commit that will actually exist.
+  const details: string[] = [];
+  let changed = false;
+
+  if (hasLegacy) {
+    // The Groups→Plugins root rename is ONE declared op, directory and all.
+    branch.move(LEGACY_GROUPS_DIR, PLUGINS_DIR);
+    details.push(`${LEGACY_GROUPS_DIR}/ → ${PLUGINS_DIR}/`);
+    changed = true;
+    // Rides WITH the rename, not on every run: the rename is what turned the
+    // ignore rule stale, so the run that renames is the run that heals it.
+    changed = (await rewriteIgnoreRootRule(repoDir, branch, details)) || changed;
+  }
+
+  // Runs whether or not the rename just happened, so a KB already on
+  // `Plugins/` still gets missing manifests and any half-done reorganisation
+  // finished. That is what makes this idempotent rather than once-only.
+  for (const entry of await fs.readdir(rootOnDisk, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const folderChanged = await migratePluginFolder(
+      branch,
+      path.join(rootOnDisk, entry.name),
+      entry.name,
+      details,
+      refusals,
+    );
+    changed = changed || folderChanged;
+  }
+
+  if (!changed) return;
+  // First note becomes the commit subject — the same messages the lazy
+  // top-up committed under; the detail notes become its body.
+  branch.note(
+    hasLegacy
+      ? `Move ${LEGACY_GROUPS_DIR}/ to ${PLUGINS_DIR}/ (Agent Plugins layout)`
+      : `Reorganise ${PLUGINS_DIR}/ to the Agent Plugins layout`,
+  );
+  for (const line of details) branch.note(line);
+}
+
+/**
+ * Rewrite the KB's `.bevelignore` rule for the renamed root: the exact line
+ * `Groups/` becomes `Plugins/`. Without this a migrated KB is left with a
+ * stale rule for a folder that no longer exists and NO rule for the new one,
+ * so plugin internals start showing up in the file tree and agent view.
+ *
+ * The file is the operator's — this touches ONE line, the one the platform's
+ * own rename invalidated, and only when `Plugins/` is not already listed
+ * (in which case the stale line is harmlessly dead and left alone).
+ */
+async function rewriteIgnoreRootRule(repoDir: string, branch: KbBranch, details: string[]): Promise<boolean> {
+  let current: string;
+  try {
+    current = await fs.readFile(path.join(repoDir, IGNORE_FILENAME), 'utf-8');
+  } catch {
+    return false; // no ignore file — nothing went stale
+  }
+  const legacyRule = `${LEGACY_GROUPS_DIR}/`;
+  const newRule = `${PLUGINS_DIR}/`;
+  const lines = current.split('\n');
+  if (lines.some((l) => l.trim() === newRule)) return false;
+  const idx = lines.findIndex((l) => l.trim() === legacyRule);
+  if (idx === -1) return false;
+  // EVERY exact-match line follows the rename: the first becomes the new
+  // rule, any further duplicates are dropped — rewriting only the first would
+  // leave stale `Groups/` lines behind, and the already-has-Plugins guard
+  // above means a second pass would never touch them.
+  lines[idx] = newRule;
+  const rewritten = lines.filter((l, i) => i <= idx || l.trim() !== legacyRule);
+  branch.write(IGNORE_FILENAME, rewritten.join('\n'));
+  details.push(`${IGNORE_FILENAME}: ${legacyRule} → ${newRule}`);
+  return true;
+}
+
+/**
+ * Reorganise ONE plugin folder. `folderDir` is where the folder sits ON DISK
+ * (under the legacy root when the rename is buffered this run); declared op
+ * paths always speak `Plugins/<folder>/…`. Returns whether ops were declared.
+ */
 async function migratePluginFolder(
-  pluginDir: string,
+  branch: KbBranch,
+  folderDir: string,
   folderName: string,
-): Promise<{ notes: string[]; changed: boolean }> {
-  const notes: string[] = [];
+  details: string[],
+  refusals: string[],
+): Promise<boolean> {
+  const relPlugin = `${PLUGINS_DIR}/${folderName}`;
   let changed = false;
 
-  if (!(await exists(path.join(pluginDir, PLUGIN_MANIFEST_FILE)))) {
-    await fs.writeFile(
-      path.join(pluginDir, PLUGIN_MANIFEST_FILE),
-      renderPluginManifest(folderName),
-      'utf8',
-    );
-    notes.push(`${folderName}: wrote ${PLUGIN_MANIFEST_FILE}`);
+  // When the manifest is written this run its content is remembered: the
+  // buffered write is not on disk yet, and the fold below must see it.
+  let renderedManifest: string | null = null;
+  if (!(await exists(path.join(folderDir, PLUGIN_MANIFEST_FILE)))) {
+    renderedManifest = renderPluginManifest(folderName);
+    branch.write(`${relPlugin}/${PLUGIN_MANIFEST_FILE}`, renderedManifest);
+    details.push(`${folderName}: wrote ${PLUGIN_MANIFEST_FILE}`);
     changed = true;
   }
 
-  const entries = await fs.readdir(pluginDir, { withFileTypes: true });
+  const entries = await fs.readdir(folderDir, { withFileTypes: true });
   const converted: ConvertedManual[] = [];
 
-  const convertOrMove = async (abs: string, name: string, note: string): Promise<void> => {
-    const manual = await asMcpManual(abs, `${PLUGINS_DIR}/${folderName}/${name}`);
+  const convertOrMove = async (abs: string, rel: string, note: string): Promise<void> => {
+    const manual = await asMcpManual(abs, rel);
     if (manual !== null && typeof manual !== 'string') {
-      // QUEUED for conversion — the `.tool` is deleted only AFTER its entry
-      // has actually landed in the output files (see foldIntoPluginFiles).
-      // Deleting first left a window where a failed fold stranded the
-      // non-portable half (auth headers, variables) with no source to retry
-      // from: the file IS the recovery path until the fold succeeds.
-      converted.push({ manual, abs, note });
+      // QUEUED for conversion — the `.tool`'s removal is declared only AFTER
+      // its entry's writes (see foldIntoPluginFiles). Buffering makes the
+      // apply all-or-nothing anyway, but the declaration order keeps the old
+      // recovery reasoning legible: the file IS the recovery path until the
+      // fold has landed.
+      converted.push({ manual, rel, note });
       return;
     }
     if (typeof manual === 'string') {
       // The operator's answer to "why is this integration not in mcp.json":
-      // a refused conversion must read as the deliberate retention it is.
-      notes.push(`${folderName}: ${note} NOT converted — ${manual}; kept as a .tool`);
+      // a refused conversion must read as the deliberate retention it is —
+      // surfaced through the step's `partial` reason rather than a note, so
+      // it names what did NOT change instead of decorating a commit.
+      refusals.push(`${branch.name}: ${folderName}: ${note} NOT converted — ${manual}; kept as a .tool`);
     }
-    const dest = path.join(pluginDir, ...HEXIS_TOOLS_DIR.split('/'), path.basename(abs));
-    if (abs !== dest && (await moveIfAbsent(abs, dest))) {
-      notes.push(`${folderName}: ${note} → ${HEXIS_TOOLS_DIR}/${path.basename(abs)}`);
+    const destDisk = path.join(folderDir, ...HEXIS_TOOLS_DIR.split('/'), path.basename(abs));
+    // Never overwrite: a destination that already exists means a previous run
+    // got there first (or a human did), and clobbering it would destroy the
+    // newer copy. The check is against the pre-step tree — the only tree that
+    // exists while this step runs.
+    if (abs !== destDisk && !(await exists(destDisk))) {
+      branch.move(rel, `${relPlugin}/${HEXIS_TOOLS_DIR}/${path.basename(abs)}`);
+      details.push(`${folderName}: ${note} → ${HEXIS_TOOLS_DIR}/${path.basename(abs)}`);
       changed = true;
     }
   };
@@ -352,20 +379,20 @@ async function migratePluginFolder(
     if (entry.name === PLUGIN_MCP_FILE || entry.name === 'access.md') continue;
     if (entry.name === HEXIS_TOOLS_DIR.split('/')[0]) continue;
 
-    const abs = path.join(pluginDir, entry.name);
+    const abs = path.join(folderDir, entry.name);
 
     // A skill is a folder carrying SKILL.md — the same rule the catalog uses.
     if (entry.isDirectory() && (await exists(path.join(abs, 'SKILL.md')))) {
-      const dest = path.join(pluginDir, PLUGIN_SKILLS_DIR, entry.name);
-      if (await moveIfAbsent(abs, dest)) {
-        notes.push(`${folderName}: ${entry.name}/ → ${PLUGIN_SKILLS_DIR}/${entry.name}/`);
+      if (!(await exists(path.join(folderDir, PLUGIN_SKILLS_DIR, entry.name)))) {
+        branch.move(`${relPlugin}/${entry.name}`, `${relPlugin}/${PLUGIN_SKILLS_DIR}/${entry.name}`);
+        details.push(`${folderName}: ${entry.name}/ → ${PLUGIN_SKILLS_DIR}/${entry.name}/`);
         changed = true;
       }
       continue;
     }
 
     if (entry.isFile() && entry.name.toLowerCase().endsWith('.tool')) {
-      await convertOrMove(abs, entry.name, entry.name);
+      await convertOrMove(abs, `${relPlugin}/${entry.name}`, entry.name);
     }
   }
 
@@ -375,105 +402,160 @@ async function migratePluginFolder(
   // `isDir` is lstat-based, so a SYMLINK planted at this path is not swept:
   // this sweep DELETES what it converts, and following a link would delete
   // `.tool` files from wherever the link really points.
-  const extToolsDir = path.join(pluginDir, ...HEXIS_TOOLS_DIR.split('/'));
+  //
+  // Under buffered ops this sweep reads the PRE-STEP tree, so a `.tool` the
+  // first sweep just declared moved here is not visible — and does not need
+  // to be: same-run movables were already converted or refused by the same
+  // `asMcpManual` logic above. The sweep exists for files parked by EARLIER
+  // runs, which are on disk. (The old in-place code happened to re-see
+  // same-run moves and no-op on them; the buffered read makes that a
+  // non-event by construction.)
+  const extToolsDir = path.join(folderDir, ...HEXIS_TOOLS_DIR.split('/'));
   if (await isDir(extToolsDir)) {
     for (const entry of await fs.readdir(extToolsDir, { withFileTypes: true })) {
       if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.tool')) continue;
       const abs = path.join(extToolsDir, entry.name);
-      const manual = await asMcpManual(abs, `${PLUGINS_DIR}/${folderName}/${HEXIS_TOOLS_DIR}/${entry.name}`);
+      const rel = `${relPlugin}/${HEXIS_TOOLS_DIR}/${entry.name}`;
+      const manual = await asMcpManual(abs, rel);
       // A refusal reason here is a SETTLED resident of the tools dir — it
       // was named the run it moved in, and this sweep repeats every boot,
-      // so re-noting it would be log spam. Only a convertible manual queues.
+      // so re-raising it would be log spam. Only a convertible manual queues.
       if (manual !== null && typeof manual !== 'string') {
-        converted.push({ manual, abs, note: `${HEXIS_TOOLS_DIR}/${entry.name}` });
+        converted.push({ manual, rel, note: `${HEXIS_TOOLS_DIR}/${entry.name}` });
       }
     }
   }
 
-  changed = (await foldIntoPluginFiles(pluginDir, folderName, converted, notes)) || changed;
-  return { notes, changed };
-}
-
-/**
- * Rewrite the KB's `.bevelignore` rule for the renamed root: the exact line
- * `Groups/` becomes `Plugins/`. Without this a migrated KB is left with a
- * stale rule for a folder that no longer exists and NO rule for the new one,
- * so plugin internals start showing up in the file tree and agent view.
- *
- * The file is the operator's — this touches ONE line, the one the platform's
- * own rename invalidated, and only when `Plugins/` is not already listed
- * (in which case the stale line is harmlessly dead and left alone).
- */
-async function rewriteIgnoreRootRule(repoDir: string, notes: string[]): Promise<boolean> {
-  const ignorePath = path.join(repoDir, IGNORE_FILENAME);
-  let current: string;
-  try {
-    current = await fs.readFile(ignorePath, 'utf-8');
-  } catch {
-    return false; // no ignore file — nothing went stale
-  }
-  const legacyRule = `${LEGACY_GROUPS_DIR}/`;
-  const newRule = `${PLUGINS_DIR}/`;
-  const lines = current.split('\n');
-  if (lines.some((l) => l.trim() === newRule)) return false;
-  const idx = lines.findIndex((l) => l.trim() === legacyRule);
-  if (idx === -1) return false;
-  lines[idx] = newRule;
-  await fs.writeFile(ignorePath, lines.join('\n'), 'utf-8');
-  notes.push(`${IGNORE_FILENAME}: ${legacyRule} → ${newRule}`);
-  return true;
+  changed =
+    (await foldIntoPluginFiles(branch, folderDir, relPlugin, folderName, renderedManifest, converted, details, refusals)) ||
+    changed;
+  return changed;
 }
 
 /**
- * Migrate `repoDir` in place. Safe to call on every top-up.
+ * Fold converted mcp manuals into the plugin's mcp.json and plugin.json.
  *
- * Returns `migrated: false` when no FILE changed — which is the steady state,
- * so the caller commits nothing. Advisory `notes` may still be present (a
- * manual that refuses to convert reports itself every run) and set nothing.
+ * MERGE, never clobber: an entry already present under a manual's key — hand
+ * written or from a previous run — wins, because overwriting it would discard
+ * the newer intent. The extension block merges the same way. A plugin.json
+ * that does not parse costs the extension write (logged), not the migration.
  */
-export async function migrateGroupsToPlugins(repoDir: string): Promise<PluginsMigrationResult> {
-  const legacyDir = path.join(repoDir, LEGACY_GROUPS_DIR);
-  const pluginsDir = path.join(repoDir, PLUGINS_DIR);
-  const notes: string[] = [];
+async function foldIntoPluginFiles(
+  branch: KbBranch,
+  folderDir: string,
+  relPlugin: string,
+  folderName: string,
+  renderedManifest: string | null,
+  manuals: ConvertedManual[],
+  details: string[],
+  refusals: string[],
+): Promise<boolean> {
+  if (manuals.length === 0) return false;
 
-  const hasLegacy = await isDir(legacyDir);
-  const hasPlugins = await isDir(pluginsDir);
+  const mcp = (await readJson(path.join(folderDir, PLUGIN_MCP_FILE))) ?? {
+    $schema: PLUGIN_MCP_SCHEMA,
+    mcpServers: {},
+  };
+  // An array (or any non-object) here would take property assignments and then
+  // drop them at stringify — normalize to an object before merging into it.
+  if (typeof mcp.mcpServers !== 'object' || mcp.mcpServers === null || Array.isArray(mcp.mcpServers)) {
+    mcp.mcpServers = {};
+  }
+  const servers = mcp.mcpServers as Record<string, unknown>;
 
-  if (hasLegacy && hasPlugins) {
-    // Both present: somebody is mid-migration by hand, or two branches merged
-    // badly. Merging them here would guess at which copy of a same-named
-    // plugin wins, so we refuse and say so — loudly, because the KB is in a
-    // state a human needs to look at.
+  // The manifest may have been DECLARED this very run — a buffered write not
+  // yet on disk. Reading the disk then would see "missing" and refuse
+  // conversions the write-then-read in-place code performed, so the step's
+  // own rendered content stands in for the tree it is about to produce.
+  const manifest =
+    renderedManifest !== null
+      ? (JSON.parse(renderedManifest) as Record<string, unknown>)
+      : await readJson(path.join(folderDir, PLUGIN_MANIFEST_FILE));
+  if (manifest === null) {
     console.warn(
-      `[plugins-migration] both ${LEGACY_GROUPS_DIR}/ and ${PLUGINS_DIR}/ exist — leaving both alone. ` +
-        `Merge ${LEGACY_GROUPS_DIR}/ into ${PLUGINS_DIR}/ by hand; nothing is being migrated automatically.`,
+      `[groups-to-plugins] ${branch.name}: ${folderName}/${PLUGIN_MANIFEST_FILE} is missing or unparsable — ` +
+        'mcp manuals convert only when they carry NOTHING for the extensions block; any ' +
+        'non-portable half (auth headers, variables, a description, or the local-only flag) ' +
+        'keeps the manual a `.tool` until the manifest is fixed.',
     );
-    return { migrated: false, renamed: false, ignoreRewritten: false, notes };
   }
 
-  let renamed = false;
-  let ignoreRewritten = false;
-  if (hasLegacy) {
-    await fs.rename(legacyDir, pluginsDir);
-    renamed = true;
-    notes.push(`${LEGACY_GROUPS_DIR}/ → ${PLUGINS_DIR}/`);
-    // Rides WITH the rename, not on every run: the rename is what turned the
-    // ignore rule stale, so the run that renames is the run that heals it.
-    ignoreRewritten = await rewriteIgnoreRootRule(repoDir, notes);
-  } else if (!hasPlugins) {
-    return { migrated: false, renamed: false, ignoreRewritten: false, notes };
-  }
+  let wroteMcp = false;
+  let wroteManifest = false;
+  const folded: ConvertedManual[] = [];
+  for (const item of manuals.sort((a, b) => a.manual.name.localeCompare(b.manual.name))) {
+    const m = item.manual;
+    const { literal, credential } = splitHeaders(m.headers);
+    // A manual whose non-portable half (auth headers, variables, local flag)
+    // has nowhere to go — the manifest is missing or unparsable — is NOT
+    // converted at all: writing only its portable half and deleting the
+    // source would silently discard the credential wiring. It stays a
+    // `.tool` until the manifest is fixed.
+    const extEntry = {
+      ...(Object.keys(credential).length > 0 ? { headers: credential } : {}),
+      ...(m.variables && m.variables.length > 0 ? { variables: m.variables } : {}),
+      ...(typeof m.description === 'string' ? { description: m.description } : {}),
+      ...(m.remote === false ? { local: true } : {}),
+    };
+    if (manifest === null && Object.keys(extEntry).length > 0) {
+      refusals.push(
+        `${branch.name}: ${folderName}: ${item.note} NOT converted — ${PLUGIN_MANIFEST_FILE} is missing/unparsable ` +
+          'and the manual carries declarations (auth headers, variables, a description, or the ' +
+          'local-only flag) that would be lost; fix the manifest first',
+      );
+      continue;
+    }
+    folded.push(item);
+    // Own-property check: `in` sees `constructor` and friends on the prototype,
+    // which would silently skip a legitimately named server.
+    if (!Object.prototype.hasOwnProperty.call(servers, m.name)) {
+      servers[m.name] = {
+        type: 'streamable-http',
+        url: m.url,
+        ...(Object.keys(literal).length > 0 ? { headers: literal } : {}),
+      };
+      wroteMcp = true;
+      details.push(`${folderName}: ${m.name} → ${PLUGIN_MCP_FILE}`);
+    }
 
-  // Runs whether or not the rename just happened, so a KB already on
-  // `Plugins/` still gets missing manifests and any half-done reorganisation
-  // finished. That is what makes this idempotent rather than once-only.
-  let changed = renamed || ignoreRewritten;
-  for (const entry of await fs.readdir(pluginsDir, { withFileTypes: true })) {
-    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
-    const folder = await migratePluginFolder(path.join(pluginsDir, entry.name), entry.name);
-    notes.push(...folder.notes);
-    changed = changed || folder.changed;
+    // The non-portable half: auth headers, variable declarations, local-only.
+    if (manifest !== null && Object.keys(extEntry).length > 0) {
+      // Normalize each level: a parseable manifest can still carry a string or
+      // array where an object belongs, and mutating that would throw mid-run.
+      if (typeof manifest.extensions !== 'object' || manifest.extensions === null || Array.isArray(manifest.extensions)) {
+        manifest.extensions = {};
+      }
+      const ext = manifest.extensions as Record<string, unknown>;
+      if (typeof ext[HEXIS_EXTENSION_NS] !== 'object' || ext[HEXIS_EXTENSION_NS] === null || Array.isArray(ext[HEXIS_EXTENSION_NS])) {
+        ext[HEXIS_EXTENSION_NS] = {};
+      }
+      const ns = ext[HEXIS_EXTENSION_NS] as Record<string, unknown>;
+      if (typeof ns.mcpServers !== 'object' || ns.mcpServers === null || Array.isArray(ns.mcpServers)) {
+        ns.mcpServers = {};
+      }
+      const extServers = ns.mcpServers as Record<string, unknown>;
+      if (!Object.prototype.hasOwnProperty.call(extServers, m.name)) {
+        extServers[m.name] = extEntry;
+        wroteManifest = true;
+      }
+    }
   }
 
-  return { migrated: changed, renamed, ignoreRewritten, notes };
+  if (wroteMcp) {
+    branch.write(`${relPlugin}/${PLUGIN_MCP_FILE}`, `${JSON.stringify(mcp, null, 2)}\n`);
+  }
+  if (wroteManifest) {
+    // May supersede the bare manifest declared above — ops apply in order, so
+    // the extended content is what lands.
+    branch.write(`${relPlugin}/${PLUGIN_MANIFEST_FILE}`, `${JSON.stringify(manifest, null, 2)}\n`);
+    details.push(`${folderName}: wrote mcp-server declarations into ${PLUGIN_MANIFEST_FILE}`);
+  }
+  // Sources go LAST in declaration order, once everything they carried has
+  // been declared elsewhere — the same shape the in-place code used so a
+  // failure never stranded the non-portable half with no source to retry from.
+  for (const item of folded) {
+    branch.remove(item.rel);
+    details.push(`${folderName}: ${item.note} converted to an ${PLUGIN_MCP_FILE} entry`);
+  }
+  return wroteMcp || wroteManifest || folded.length > 0;
 }