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

package/src/modules/workspace/startup/steps/personal-spaces.step.ts

@@ -0,0 +1,191 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PLUGINS_DIR, isPersonalPluginFolder } from '@bevel-software/platform-shared';
+import {
+  EVERYONE_CANONICAL,
+  KNOWN_VERBS,
+  accessMdDeclaresBodyRules,
+  parseAccessFile,
+  parseOwnAccessEntries,
+  sourceVerbsFor,
+  type ParsedEntry,
+  type Verb,
+} from '../../../access-model/access-grammar.js';
+import { spliceGrant } from '../../../access-model/access-splice.js';
+import { isAbsence, type IFsProbe } from '../../../../shared/fs.contract.js';
+import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+
+/**
+ * Keep every personal space closed to everyone but its owner — Admin
+ * included — and let its access.md say so in both blocks.
+ *
+ * A personal folder's access.md used to be seeded with the owner's grants
+ * alone. That is private only while nothing above it grants read — and the
+ * usual way an administrator opens a knowledge base up is `read: everyone`
+ * at the repository root, which then reached into every person's private
+ * space. Personal folders seeded since deny `everyone` read outright; this
+ * step gives the ones seeded before the same rule, on every branch, on the
+ * next start. The file's own block gets the same statement (`deny
+ * everyone` and the people the folder admits) where it used to say nothing
+ * (`read: []`), so the file reads as what it is — see `isPrivateAccessMd`.
+ *
+ * A SPLICE, not a rewrite: the denial is added to the folder's read rules
+ * (and, for the old seed's shape, the owner's grants are carried into
+ * the folder's rules — see {@link closePersonalSpaceRules}); every other
+ * byte — anyone the owner added, comments — stays. Idempotent: a folder
+ * whose rules already deny `everyone` is left alone, so a person who removed
+ * the denial on purpose would get it back once, on the upgrade that
+ * introduces it, and not again.
+ * Files that do not parse are the operator's to fix and are skipped.
+ */
+export class PersonalSpacesStep implements OnServerStart {
+  readonly name = 'personal-spaces';
+
+  constructor(private readonly disk: IFsProbe) {}
+
+  async run(ctx: ServerStartContext): Promise<StepResult> {
+    for (const branch of await ctx.allBranches()) {
+      await this.closePersonalSpaces(branch);
+    }
+    return { outcome: 'ok' };
+  }
+
+  private async closePersonalSpaces(branch: KbBranch): Promise<void> {
+    const repoDir = await branch.repoDir();
+    const entries = await this.disk.listDir(path.join(repoDir, PLUGINS_DIR));
+    if (entries === null) return;
+    const closed: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !isPersonalPluginFolder(entry.name)) continue;
+      const rel = `${PLUGINS_DIR}/${entry.name}/access.md`;
+      let text: string;
+      try {
+        text = await fs.readFile(path.join(repoDir, rel), 'utf8');
+      } catch (err) {
+        if (isAbsence(err)) continue; // a folder with no rules is not a provisioned space
+        throw err;
+      }
+      const next = closePersonalSpaceRules(text, rel);
+      if (next === null) continue;
+      branch.write(rel, next);
+      closed.push(entry.name);
+    }
+    if (closed.length === 0) return;
+    branch.note(`Keep ${closed.length === 1 ? 'a personal space' : `${closed.length} personal spaces`} private`);
+    for (const name of closed) branch.note(`${PLUGINS_DIR}/${name}/access.md: read denies everyone`);
+  }
+}
+
+/**
+ * The access.md text with `deny everyone` under the folder's `read:`, and
+ * the same statement in the file's own block — or null when nothing needed
+ * closing or the file cannot be parsed. Exported so a resolver test can
+ * prove what the reconciled file means, not only what it says.
+ *
+ * The previous template put the owner's grants in the frontmatter over a
+ * body of `read: []`. A body that declares a verb governs the folder, so
+ * that file's folder rules were the empty body: the owner could see the
+ * file and nothing beneath it. Closing such a file therefore also carries
+ * every person the frontmatter grants into the folder block, so the owner
+ * (and anyone they added) keeps what the frontmatter was meant to give
+ * them.
+ */
+export function closePersonalSpaceRules(text: string, relativePath: string): string | null {
+  const parsed = parseAccessFile(text, relativePath);
+  if (!parsed.ok) return null;
+  const folderClosed = closeFolderRules(text, parsed.file.entries);
+  const next = closeFileRules(folderClosed, relativePath);
+  return next === text ? null : next;
+}
+
+const everyone = (e: ParsedEntry) => e.kind === 'role' && e.role === EVERYONE_CANONICAL;
+
+/** The body — the folder's rules — with `deny everyone` under `read:`; unchanged when already settled. */
+function closeFolderRules(text: string, folder: Record<Verb, ParsedEntry[]>): string {
+  // A file whose folder rules already settle `everyone`'s READ is left as it
+  // is: an entry under `read` itself (a denial means the space is closed; a
+  // grant means someone opened it on purpose), or a GRANT under a verb that
+  // folds into read (`write`, `download`, `owner` — the grammar's own list,
+  // which it reads rather than restates). A denial written beside such a
+  // grant would change nothing (a same-scope grant wins) while making the
+  // file read as a contradiction. Anything else — `deny everyone` under
+  // write alone — says nothing about read, and the space is still open to
+  // an inherited `read: everyone`.
+  const settled = sourceVerbsFor('read').some((verb) =>
+    folder[verb].some((e) => everyone(e) && (verb === 'read' || !e.deny)),
+  );
+  if (settled) return text;
+  let next = text;
+  for (const { verb, entry } of strandedFrontmatterGrants(text, folder)) {
+    next = spliceGrant(next, verb, { kind: 'user', email: entry.email, displayName: entry.displayName }, { target: 'folder' }).text;
+  }
+  return spliceGrant(next, 'read', { kind: 'role', role: 'everyone' }, { deny: true, target: 'folder' }).text;
+}
+
+/**
+ * The frontmatter — the FILE's rules — saying what the folder's say: `deny
+ * everyone`, then the people the folder admits (its user grants under every
+ * verb that folds into read). Only for a file whose folder rules settle
+ * `everyone`'s read as DENIED — a denial under `read` with no grant under
+ * any verb that folds into read (`write: everyone` or `download: everyone`
+ * opens the folder to all despite the denial, a same-scope grant winning):
+ * a space its owner opened on purpose, either way, keeps the file open too.
+ * A frontmatter that already mentions `everyone` under `read` — a denial, or
+ * a grant that lists the file for all — is left as written; so is a legacy
+ * single-block file, whose frontmatter IS the folder's rules and was closed
+ * above.
+ */
+function closeFileRules(text: string, relativePath: string): string {
+  if (!accessMdDeclaresBodyRules(text)) return text;
+  const own = parseOwnAccessEntries(text);
+  if (own?.read.some(everyone)) return text;
+  const parsed = parseAccessFile(text, relativePath);
+  if (!parsed.ok) return text;
+  const folder = parsed.file.entries;
+  const folderReadIsDenied =
+    folder.read.some((e) => everyone(e) && e.deny) &&
+    !sourceVerbsFor('read').some((verb) => folder[verb].some((e) => everyone(e) && !e.deny));
+  if (!folderReadIsDenied) return text;
+  let next = spliceGrant(text, 'read', { kind: 'role', role: 'everyone' }, { deny: true, target: 'node', allowScalar: false }).text;
+  const named = new Set<string>();
+  for (const verb of sourceVerbsFor('read')) {
+    for (const entry of folder[verb]) {
+      if (entry.kind !== 'user' || entry.deny || named.has(entry.email)) continue;
+      named.add(entry.email);
+      next = spliceGrant(
+        next,
+        'read',
+        { kind: 'user', email: entry.email, displayName: entry.displayName },
+        { target: 'node', allowScalar: false },
+      ).text;
+    }
+  }
+  return next;
+}
+
+/**
+ * People the frontmatter grants that the folder rules do not — non-empty only
+ * for a body-governed file whose frontmatter still carries the old seed's
+ * owner grants. A legacy file (no body rules) has nothing stranded: its
+ * frontmatter IS the folder's rules.
+ */
+function strandedFrontmatterGrants(
+  text: string,
+  folder: Record<Verb, ParsedEntry[]>,
+): { verb: Verb; entry: Extract<ParsedEntry, { kind: 'user' }> }[] {
+  if (!accessMdDeclaresBodyRules(text)) return [];
+  const own = parseOwnAccessEntries(text);
+  if (!own) return [];
+  const out: { verb: Verb; entry: Extract<ParsedEntry, { kind: 'user' }> }[] = [];
+  for (const verb of KNOWN_VERBS) {
+    for (const entry of own[verb]) {
+      if (entry.kind !== 'user' || entry.deny) continue;
+      // Any entry for that person under that verb — a grant OR a denial — is
+      // the folder's own word on them; a denial someone wrote there on
+      // purpose must not be overridden by the frontmatter's older grant.
+      const held = folder[verb].some((e) => e.kind === 'user' && e.email === entry.email);
+      if (!held) out.push({ verb, entry });
+    }
+  }
+  return out;
+}

package/src/modules/workspace/startup/steps/plugin-display-names.step.ts

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import {
+  PLUGINS_DIR,
+  PLUGIN_MANIFEST_FILE,
+  pluginDisplayNameOf,
+} from '@bevel-software/platform-shared';
+import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
+import { hasManifestEntry } from './plugin-layout.js';
+import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+
+/**
+ * Write down what each existing plugin is already CALLED, as an
+ * {@link OnServerStart} step.
+ *
+ * The display name is now the manifest's `displayName`, else its `name`, and
+ * nothing else — the folder's spelling is no longer consulted by any reader
+ * (see `pluginDisplayNameOf`). Before that rule, a manifest carried the field
+ * only when the folder was spelled differently from the identifier, and every
+ * reader fell back to the folder. So a knowledge base written under the old
+ * rule holds manifests that say `{"name": "sales-team"}` inside a folder
+ * called `Sales Team`: under the new rule alone they would start showing
+ * `sales-team`, and the plugin would appear to have renamed itself on an
+ * upgrade nobody asked for.
+ *
+ * This step is the one-time repair: for every manifest that does not already
+ * SAY what it is called, and whose folder is spelled differently from what
+ * the manifest alone would show, the folder's spelling is written into
+ * `displayName` — which is exactly what that plugin was called the moment
+ * before the boot. Nothing else in the manifest moves.
+ *
+ * What it does NOT touch:
+ *   - a manifest whose `displayName` says something — the field is the
+ *     author's answer, and a migration that overwrote it would be renaming
+ *     plugins rather than preserving names. A field present but BLANK says
+ *     nothing and is repaired like an absent one: the new reader falls
+ *     through it to `name` where the old reader fell through to the folder,
+ *     so leaving it would be leaving the rename this step exists to prevent;
+ *   - a manifest that already shows the folder's spelling — `{"name":
+ *     "gtm"}` in `gtm/`, or `{"name": "My Plugin"}` in `My Plugin/` — under
+ *     both rules it is called the same thing, so there is nothing to record,
+ *     and writing the field would churn every plugin in the tree for no
+ *     change anyone can see;
+ *   - a bundle (`plugin.bundle.json`), or a `plugin.json` that is not a
+ *     regular file — a foreign repository's files this platform reads and
+ *     never writes.
+ *
+ * Every branch, drafts included, like the manifests step beside it and for
+ * the same reason: a draft migrated alongside its target diffs by the user's
+ * own changes only. Idempotent by construction — after a run, every manifest
+ * it would touch carries the field, so the next boot finds nothing.
+ */
+export class PluginDisplayNamesStep implements OnServerStart {
+  readonly name = 'plugin-display-names';
+
+  constructor(private readonly disk: IFsProbe & ITreeWalker) {}
+
+  async run(ctx: ServerStartContext): Promise<StepResult> {
+    for (const branch of await ctx.allBranches()) {
+      await this.backfill(branch);
+    }
+    return { outcome: 'ok' };
+  }
+
+  private async backfill(branch: KbBranch): Promise<void> {
+    const repoDir = await branch.repoDir();
+    const root = path.join(repoDir, PLUGINS_DIR);
+
+    // Plugin folders by the judgement discovery makes, entry for entry: a
+    // manifest as a REGULAR file, and nothing beneath a plugin is a plugin.
+    // Absence is the plugins root not existing yet; any other hole stops the
+    // boot rather than quietly leaving part of the tree unmigrated — a
+    // plugin this step misses is one that renames itself the moment it is
+    // read, which is the whole failure it exists to prevent.
+    const plugins: string[] = [];
+    await this.disk.walkKb(
+      root,
+      [
+        {
+          onDir(rel, entries) {
+            if (rel && hasManifestEntry(entries)) plugins.push(rel);
+          },
+        },
+      ],
+      { leaf: (dir, entries) => dir.rel !== '' && hasManifestEntry(entries), unreadable: 'throw' },
+    );
+
+    const filled: string[] = [];
+    for (const rel of plugins) {
+      const manifestPath = path.join(root, ...rel.split('/'), PLUGIN_MANIFEST_FILE);
+      // A NATIVE manifest is a regular file — a `plugin.json` that is a
+      // symlink is none, exactly as discovery judges it. A folder carrying a
+      // bundle beside a symlinked `plugin.json` is a bundle-only folder to
+      // every reader, and a write queued for its link is a write into a
+      // foreign repository's file that the runner refuses — one read-only
+      // bundle in the tree would stop the boot.
+      const manifestEntry = await this.disk.lstatOrNull(manifestPath);
+      if (!manifestEntry?.isFile()) continue;
+      // Null is "no native manifest here, or none this step can reason
+      // about": a `plugin.json` that is not a JSON object. Discovery already
+      // says so out loud; rewriting it blind would be this step inventing a
+      // manifest for a file it could not read.
+      const manifest = await this.disk.readJsonObject(manifestPath);
+      if (manifest === null) continue;
+      // The author's own answer — when they gave one. A field present but
+      // BLANK says nothing: the shared reader falls through it to `name`,
+      // where the old reader fell through to the folder, so a blank field in
+      // a folder spelled differently is exactly the manifest that renames
+      // itself on upgrade. Absent for this step's purposes, and repaired.
+      if (isNonBlankString(manifest.displayName)) continue;
+      const folderName = path.posix.basename(rel);
+      // What the manifest ALONE already shows — `displayName`, else `name`.
+      // When the folder is spelled the same, it is called the same thing
+      // under both rules and there is nothing the folder knows that the
+      // manifest does not. This covers the plain case (folder `gtm`,
+      // identifier `gtm`) and the one the identifier alone misses: a manifest
+      // naming something that is not an identifier but IS the folder's
+      // spelling (`{"name":"My Plugin"}` in `My Plugin/`), where the
+      // identity is the slug `my-plugin` and writing the field would churn
+      // the file for no change anyone can see.
+      if (folderName === pluginDisplayNameOf(manifest)) continue;
+      branch.write(
+        `${PLUGINS_DIR}/${rel}/${PLUGIN_MANIFEST_FILE}`,
+        `${JSON.stringify(withDisplayName(manifest, folderName), null, 2)}\n`,
+      );
+      filled.push(rel);
+    }
+
+    if (filled.length === 0) return;
+    branch.note(
+      filled.length === 1
+        ? "Record a plugin's display name in its manifest"
+        : `Record the display names of ${filled.length} plugins in their manifests`,
+    );
+    for (const rel of filled) branch.note(`${PLUGINS_DIR}/${rel}: displayName "${path.posix.basename(rel)}"`);
+  }
+}
+
+/** A string a reader would show — the shared rule's test for "says something". */
+function isNonBlankString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+/**
+ * The manifest with `displayName` set, placed directly after `name` — where
+ * the renderer writes it — so a backfilled manifest and a freshly created one
+ * read the same. Every other key keeps its place and its value.
+ *
+ * Copied with `defineProperty`, not assignment: `JSON.parse` gives a manifest
+ * naming `__proto__` an OWN key, and `next[key] = value` for that key would
+ * set the object's prototype instead — silently dropping the field and, with
+ * a `displayName` on the prototype, hiding the very field this writes.
+ */
+function withDisplayName(manifest: Record<string, unknown>, displayName: string): Record<string, unknown> {
+  const next: Record<string, unknown> = {};
+  const put = (key: string, value: unknown) =>
+    Object.defineProperty(next, key, { value, enumerable: true, configurable: true, writable: true });
+  for (const [key, value] of Object.entries(manifest)) {
+    // The field being replaced: a blank one this step treats as absent. It is
+    // re-placed after `name`, so the key never lands twice or out of order.
+    if (key === 'displayName') continue;
+    put(key, value);
+    if (key === 'name') put('displayName', displayName);
+  }
+  // A manifest with no `name` at all: the field still belongs in it — the
+  // folder's spelling is what the plugin was called — and discovery stands
+  // the folder in as the identity, so the two agree.
+  if (!Object.hasOwn(next, 'displayName')) put('displayName', displayName);
+  return next;
+}

package/src/modules/workspace/startup/steps/plugin-layout.ts

@@ -0,0 +1,110 @@
+import {
+  HEXIS_EXTENSION_NS,
+  PLUGIN_MANIFEST_FILE,
+  PLUGIN_MCP_FILE,
+  PLUGIN_SKILLS_DIR,
+} from '@bevel-software/platform-shared';
+import { BUNDLE_FILE } from '../../../plugins/discovery/bundle-dialect/bundle.source.js';
+import { isSkippedEntry, type ITreeWalker, type WalkedEntry } from '../../../../shared/fs.contract.js';
+
+/**
+ * Whether a folder's listing carries a plugin manifest or a bundle as a
+ * regular file — THE "has a manifest" judgement, shared by the manifest step
+ * and the migration. Pure: it reads the entries it is given and touches no
+ * disk, so it stays a function.
+ */
+export function hasManifestEntry(entries: readonly WalkedEntry[]): boolean {
+  return entries.some((e) => e.isFile() && (e.name === PLUGIN_MANIFEST_FILE || e.name === BUNDLE_FILE));
+}
+
+/**
+ * The questions BOTH plugin-shaped startup steps ask of the tree: is this
+ * folder a plugin from before manifests existed, and does a real plugin live
+ * beneath it?
+ *
+ * Two steps need these answers — the manifest back-fill and the
+ * Groups→Plugins migration — and they must never disagree, or one would write
+ * a manifest into a folder the other treats as a grouping folder. They used
+ * to share the answers as free functions taking the walker, which put the
+ * port in every signature and every call. Injected once instead: the walker
+ * is a constructor dependency, as an INTERFACE, and the questions read as
+ * questions.
+ */
+export class PluginLayout {
+  constructor(private readonly disk: ITreeWalker) {}
+
+  /**
+   * Whether a folder's own content is what the legacy layout put in a plugin
+   * — THE rule for "this folder was a plugin before manifests existed". A
+   * folder with nothing of the kind (a `.gitkeep`, a grouping folder someone
+   * made in the tree) is not.
+   *
+   * Entries the walk SKIPS are not content. The two callers reach this with
+   * listings of different provenance — the manifest step's come from a walk
+   * that has already dropped dot-entries and `node_modules`, the migration's
+   * come raw from `listDir` — and judging the raw ones as they arrived made
+   * a folder holding nothing but `.hidden.tool` a plugin: the migration wrote
+   * it a manifest and then moved nothing into it, because its own sweep skips
+   * exactly what this had counted. Filtered HERE rather than at that call
+   * site, so the answer cannot depend on which door it came through.
+   */
+  async looksLikeLegacyPlugin(dir: string, entries: readonly WalkedEntry[]): Promise<boolean> {
+    for (const entry of entries) {
+      if (isSkippedEntry(entry.name)) continue;
+      if (
+        entry.isFile() &&
+        (entry.name === 'access.md' || entry.name === PLUGIN_MCP_FILE || entry.name.toLowerCase().endsWith('.tool'))
+      ) {
+        return true;
+      }
+      if (entry.isDirectory() && (entry.name === PLUGIN_SKILLS_DIR || entry.name === HEXIS_EXTENSION_NS)) return true;
+    }
+    return this.hasSkillBeneath(dir);
+  }
+
+  /**
+   * Whether a plugin (a folder carrying `plugin.json` or a bundle) sits
+   * anywhere BELOW `dir` — which makes `dir` a grouping folder, never a
+   * plugin itself.
+   *
+   * Judged the way discovery judges it: a manifest is a REGULAR file entry
+   * (`Dirent.isFile()` — a symlink so named is not one, exactly as the walk
+   * behind the catalog sees it), and the entries the walk skips (dot-folders,
+   * `node_modules`) hold nothing here either. Anything looser would let an
+   * ignored or unsupported entry hide a legacy plugin from its manifest.
+   */
+  async hasPluginBeneath(dir: string): Promise<boolean> {
+    return this.anyFolderIn(dir, (rel, entries) => rel !== '' && hasManifestEntry(entries));
+  }
+
+  /** The pre-`skills/` shape: `Plugins/<Plugin>/<skill>/SKILL.md`, at any depth (`dir` itself included). */
+  private async hasSkillBeneath(dir: string): Promise<boolean> {
+    return this.anyFolderIn(dir, (_rel, entries) => entries.some((e) => e.isFile() && e.name === 'SKILL.md'));
+  }
+
+  /**
+   * Whether any folder at or under `dir` — walked as the catalog walks it, so
+   * a SKILL.md vendored under `node_modules` is nobody's skill and makes no
+   * folder a plugin — has a listing that satisfies `test`. Stops at the
+   * first. A missing `dir` has none; a folder that cannot be listed is the
+   * error.
+   */
+  private async anyFolderIn(
+    dir: string,
+    test: (rel: string, entries: readonly WalkedEntry[]) => boolean,
+  ): Promise<boolean> {
+    let found = false;
+    await this.disk.walkKb(
+      dir,
+      [
+        {
+          onDir(rel, entries) {
+            if (test(rel, entries)) found = true;
+          },
+        },
+      ],
+      { until: () => found, unreadable: 'throw' },
+    );
+    return found;
+  }
+}

package/src/modules/workspace/startup/steps/plugin-manifests.step.ts

@@ -1,15 +1,7 @@
-import fs from 'node:fs/promises';
 import path from 'node:path';
-import {
-  HEXIS_EXTENSION_NS,
-  PLUGINS_DIR,
-  PLUGIN_MANIFEST_FILE,
-  PLUGIN_MCP_FILE,
-  PLUGIN_SKILLS_DIR,
-  renderPluginManifest,
-} from '@bevel-software/platform-shared';
-import { BUNDLE_FILE } from '../../../plugins/discovery/bundle-dialect/bundle.source.js';
-import { isAbsence } from '../../../../shared/fs-errors.js';
+import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, renderPluginManifest } from '@bevel-software/platform-shared';
+import type { ITreeWalker, WalkedEntry } from '../../../../shared/fs.contract.js';
+import { PluginLayout, hasManifestEntry } from './plugin-layout.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 /**
@@ -35,7 +27,8 @@ import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '..
  * plugin of its own. "Legacy content" is the set of things provisioning and
  * the old migration ever put in a plugin folder: `access.md`, `mcp.json`,
  * `skills/`, the hexis extension directory, a `.tool` file, or a `SKILL.md`
- * anywhere beneath (the pre-`skills/` shape).
+ * anywhere beneath (the pre-`skills/` shape) — see {@link PluginLayout},
+ * which the Groups→Plugins migration reads the same answers from.
  *
  * Every branch, drafts included, like the Groups→Plugins migration and for
  * the same reason: a draft migrated alongside its target diffs by the user's
@@ -44,86 +37,54 @@ import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '..
 export class PluginManifestsStep implements OnServerStart {
   readonly name = 'plugin-manifests';
 
+  private readonly layout: PluginLayout;
+
+  constructor(private readonly disk: ITreeWalker) {
+    this.layout = new PluginLayout(disk);
+  }
+
   async run(ctx: ServerStartContext): Promise<StepResult> {
     for (const branch of await ctx.allBranches()) {
-      await addManifests(branch);
+      await this.addManifests(branch);
     }
     return { outcome: 'ok' };
   }
-}
-
-async function addManifests(branch: KbBranch): Promise<void> {
-  const repoDir = await branch.repoDir();
-  const root = path.join(repoDir, PLUGINS_DIR);
-  const added: string[] = [];
-
-  /** Resolves to how many plugins sit at or beneath `dir`. */
-  const visit = async (dir: string, rel: string): Promise<number> => {
-    if (rel && ((await isFile(path.join(dir, PLUGIN_MANIFEST_FILE))) || (await isFile(path.join(dir, BUNDLE_FILE))))) {
-      return 1;
-    }
-    let entries: import('node:fs').Dirent[];
-    try {
-      entries = await fs.readdir(dir, { withFileTypes: true });
-    } catch (err) {
-      // Absence is the plugins root not existing yet; anything else must stop
-      // the boot rather than quietly leave legacy plugins without manifests.
-      if (isAbsence(err)) return 0;
-      throw err;
-    }
-    let beneath = 0;
-    for (const entry of entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'))) {
-      beneath += await visit(path.join(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
-    }
-    if (beneath > 0 || !rel || rel.includes('/')) return beneath;
-    if (!(await looksLikeLegacyPlugin(dir, entries))) return 0;
-    const manifestRel = `${PLUGINS_DIR}/${rel}/${PLUGIN_MANIFEST_FILE}`;
-    branch.write(manifestRel, renderPluginManifest(path.posix.basename(rel)));
-    added.push(rel);
-    return 1;
-  };
 
-  await visit(root, '');
-  if (added.length === 0) return;
-  branch.note(`Add plugin manifests to ${added.length === 1 ? 'a legacy plugin folder' : `${added.length} legacy plugin folders`}`);
-  for (const rel of added) branch.note(`${PLUGINS_DIR}/${rel}: ${PLUGIN_MANIFEST_FILE} written`);
-}
+  private async addManifests(branch: KbBranch): Promise<void> {
+    const repoDir = await branch.repoDir();
+    const root = path.join(repoDir, PLUGINS_DIR);
+    const added: string[] = [];
 
-async function looksLikeLegacyPlugin(dir: string, entries: import('node:fs').Dirent[]): Promise<boolean> {
-  for (const entry of entries) {
-    if (entry.isFile() && (entry.name === 'access.md' || entry.name === PLUGIN_MCP_FILE || entry.name.toLowerCase().endsWith('.tool'))) {
-      return true;
+    // A plugin is a folder whose OWN listing holds a manifest as a regular
+    // file — the judgement discovery makes, entry for entry (a symlink so
+    // named is none) — and a leaf: nothing beneath it is a plugin. Absence is
+    // the plugins root not existing yet; any other hole must stop the boot
+    // rather than quietly leave legacy plugins without manifests.
+    const plugins: string[] = [];
+    const topLevel: { rel: string; entries: readonly WalkedEntry[] }[] = [];
+    await this.disk.walkKb(
+      root,
+      [
+        {
+          onDir(rel, entries) {
+            if (rel && hasManifestEntry(entries)) plugins.push(rel);
+            else if (rel && !rel.includes('/')) topLevel.push({ rel, entries });
+          },
+        },
+      ],
+      { leaf: (dir, entries) => dir.rel !== '' && hasManifestEntry(entries), unreadable: 'throw' },
+    );
+    for (const { rel, entries } of topLevel) {
+      // A grouping folder — plugins beneath it — is never a plugin itself.
+      if (plugins.some((p) => p.startsWith(`${rel}/`))) continue;
+      if (!(await this.layout.looksLikeLegacyPlugin(path.join(root, rel), entries))) continue;
+      branch.write(`${PLUGINS_DIR}/${rel}/${PLUGIN_MANIFEST_FILE}`, renderPluginManifest(rel));
+      added.push(rel);
     }
-    if (entry.isDirectory() && (entry.name === PLUGIN_SKILLS_DIR || entry.name === HEXIS_EXTENSION_NS)) return true;
+    if (added.length === 0) return;
+    branch.note(
+      `Add plugin manifests to ${added.length === 1 ? 'a legacy plugin folder' : `${added.length} legacy plugin folders`}`,
+    );
+    for (const rel of added) branch.note(`${PLUGINS_DIR}/${rel}: ${PLUGIN_MANIFEST_FILE} written`);
   }
-  return hasSkillBeneath(dir);
 }
-
-/** The pre-`skills/` shape: `Plugins/<Plugin>/<skill>/SKILL.md`, at any depth. */
-async function hasSkillBeneath(dir: string): Promise<boolean> {
-  let entries: import('node:fs').Dirent[];
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch (err) {
-    if (isAbsence(err)) return false;
-    throw err;
-  }
-  if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) return true;
-  for (const entry of entries) {
-    if (entry.isDirectory() && !entry.name.startsWith('.') && (await hasSkillBeneath(path.join(dir, entry.name)))) {
-      return true;
-    }
-  }
-  return false;
-}
-
-async function isFile(abs: string): Promise<boolean> {
-  return fs.stat(abs).then(
-    (s) => s.isFile(),
-    (err: unknown) => {
-      if (isAbsence(err)) return false;
-      throw err; // a probe that fails for another reason is not "no manifest"
-    },
-  );
-}
-

package/src/modules/workspace/startup/steps/roles-yaml.step.ts

@@ -1,5 +1,5 @@
-import fs from 'node:fs/promises';
 import path from 'node:path';
+import type { IFsProbe } from '../../../../shared/fs.contract.js';
 import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
@@ -21,7 +21,10 @@ import type { OnServerStart, ServerStartContext, StepResult } from '../on-server
 export class RolesYamlStep implements OnServerStart {
   readonly name = 'roles-yaml';
 
-  constructor(private readonly seedAdminEmails: readonly string[]) {}
+  constructor(
+    private readonly disk: IFsProbe,
+    private readonly seedAdminEmails: readonly string[],
+  ) {}
 
   async run(ctx: ServerStartContext): Promise<StepResult> {
     const adminless: string[] = [];
@@ -31,7 +34,7 @@ export class RolesYamlStep implements OnServerStart {
       // read as "present" and be skipped over — reporting success over a
       // knowledge base whose access roster cannot be read. Fail closed, same
       // as template-files' squatter checks: this is a state a human must fix.
-      const found = await lstatOrNull(path.join(repoDir, 'roles.yaml'));
+      const found = await this.disk.lstatOrNull(path.join(repoDir, 'roles.yaml'));
       if (found) {
         if (found.isFile()) continue; // the operator's file — leave it alone
         throw new Error(
@@ -60,12 +63,3 @@ export class RolesYamlStep implements OnServerStart {
     return { outcome: 'ok' };
   }
 }
-
-/** `lstat` without the throw — null when nothing is at `p`. */
-async function lstatOrNull(p: string): Promise<import('node:fs').Stats | null> {
-  try {
-    return await fs.lstat(p);
-  } catch {
-    return null;
-  }
-}