@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/dist/modules/workspace/startup/steps/groups-to-plugins.step.js

@@ -0,0 +1,492 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { HEXIS_EXTENSION_NS, HEXIS_TOOLS_DIR, LEGACY_GROUPS_DIR, PLUGINS_DIR, PLUGIN_MANIFEST_FILE, PLUGIN_MCP_FILE, PLUGIN_MCP_SCHEMA, PLUGIN_SKILLS_DIR, renderPluginManifest, } from '@bevel-software/platform-shared';
+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';
+/**
+ * One-way migration of a knowledge base from `Groups/` to the Agent Plugins
+ * 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()`.
+ *
+ * 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:
+ *
+ *   Groups/GTM/access.md            → Plugins/GTM/access.md            (stays put)
+ *   Groups/GTM/deploy/SKILL.md      → Plugins/GTM/skills/deploy/SKILL.md
+ *   Groups/GTM/web-search.tool      → Plugins/GTM/software.bevel.hexis/tools/web-search.tool
+ *   Groups/GTM/notion.tool (mcp)    → an entry in Plugins/GTM/mcp.json, and the
+ *                                     `.tool` file is DELETED — mcp.json is
+ *                                     authoritative for MCP servers now.
+ *                                     Plugins/GTM/plugin.json           (written)
+ *
+ * The mcp.json entry is keyed by the `.tool`'s manual id: that id is the
+ * namespace vault secrets bind to (`<id>_<VAR>`), so keeping it is what keeps
+ * every configured secret and completed OAuth grant bound. What mcp.json
+ * cannot carry — auth headers with `${VAR}` references, variable declarations,
+ * the local-only flag — moves into `plugin.json`'s
+ * `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 {
+    name = 'groups-to-plugins';
+    async run(ctx) {
+        const refusals = [];
+        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
+// link never counts as the thing it points at — following one here would let
+// a symlinked directory pull files from outside the plugin into the sweep
+// (and delete them from wherever they really live).
+async function exists(p) {
+    try {
+        await fs.lstat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isDir(p) {
+    try {
+        return (await fs.lstat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A header value referencing a vault variable rather than carrying a literal.
+ * The substitutor's own grammar decides (shared/variable-refs.ts): both
+ * spellings it expands — `${VAR}` and bare `$VAR`, digit-leading names
+ * included — count, because either one copied into mcp.json would be
+ * transmitted verbatim by a conformant client. That means a prose `$5` in a
+ * header routes to the non-portable half too: over-classifying costs a header
+ * its portability, under-classifying leaks whatever `$5TOKEN` expands to.
+ */
+const isCredentialReference = containsVariableReference;
+/** Split a manual's headers into what mcp.json may carry and what may not. */
+function splitHeaders(headers) {
+    const literal = {};
+    const credential = {};
+    for (const [k, v] of Object.entries(headers ?? {})) {
+        (isCredentialReference(v) ? credential : literal)[k] = v;
+    }
+    return { literal, credential };
+}
+/** Read+parse a JSON file, or `null` when absent or unparsable. */
+async function readJson(p) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(p, 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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)
+ * is `null` and moves as a plain `.tool`; an MCP manual REFUSED conversion
+ * comes back as the reason string, so the migration log distinguishes a
+ * deliberately-retained integration from one that silently failed — the
+ * same courtesy the manifest-missing refusal already extends.
+ */
+async function asMcpManual(abs, repoRel) {
+    try {
+        const content = await fs.readFile(abs, 'utf-8');
+        const d = normalizeToolManual(path.basename(abs).replace(/\.tool$/i, ''), repoRel, content);
+        // The mcp.json loader accepts only names it can serve as a namespace and
+        // route slug — converting a manual whose id fails that shape would DELETE
+        // a working integration and write an entry discovery then skips. Such a
+        // manual stays a `.tool`.
+        if (d.type !== 'mcp' || !d.url)
+            return null;
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(d.name)) {
+            return `its id "${d.name}" is not a valid mcp.json server name`;
+        }
+        // Same refusal for the url: the mcp.json loader accepts only a directly
+        // parseable http(s) url, so a templated one (`${BASE}/mcp` — legal in a
+        // `.tool`, where the substitutor expands it) would convert into an entry
+        // discovery then skips, with the source already deleted. And a parseable
+        // url carrying `user:pass@` may not land in the PORTABLE file at all —
+        // stripping it would break the server, so the manual keeps its `.tool`
+        // form, where the credential stays platform-internal.
+        let url;
+        try {
+            url = new URL(d.url);
+        }
+        catch {
+            return 'its url is not directly parseable (a templated url only a .tool can carry)';
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return `its url scheme "${url.protocol}" cannot land in mcp.json (http(s) only)`;
+        }
+        if (url.username || url.password) {
+            return 'its url embeds credentials, which may not land in the portable mcp.json';
+        }
+        // A `.tool` can gate ITSELF with frontmatter access verbs, read by the
+        // access resolver from the file's own path. An mcp.json entry has no
+        // per-server home for those — the file's ACL governs every server in it —
+        // so converting would silently widen who may configure and run the
+        // server. Such a manual stays a `.tool`, verbs and all.
+        if (parseOwnAccessEntries(content) !== null) {
+            return 'it gates itself with frontmatter access verbs, which mcp.json cannot carry';
+        }
+        return d;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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, refusals) {
+    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 = [];
+    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, branch, details) {
+    let current;
+    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(branch, folderDir, folderName, details, refusals) {
+    const relPlugin = `${PLUGINS_DIR}/${folderName}`;
+    let changed = false;
+    // 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 = 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(folderDir, { withFileTypes: true });
+    const converted = [];
+    const convertOrMove = async (abs, rel, note) => {
+        const manual = await asMcpManual(abs, rel);
+        if (manual !== null && typeof manual !== 'string') {
+            // 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 —
+            // 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 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;
+        }
+    };
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (entry.name === PLUGIN_SKILLS_DIR || entry.name === PLUGIN_MANIFEST_FILE)
+            continue;
+        if (entry.name === PLUGIN_MCP_FILE || entry.name === 'access.md')
+            continue;
+        if (entry.name === HEXIS_TOOLS_DIR.split('/')[0])
+            continue;
+        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')))) {
+            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, `${relPlugin}/${entry.name}`, entry.name);
+        }
+    }
+    // Second sweep: mcp `.tool`s an EARLIER run moved into the extension dir
+    // (when mcp.json was a projection, not the authority). Converting them here
+    // is what makes the migration complete itself rather than strand a twin.
+    // `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.
+    //
+    // 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 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-raising it would be log spam. Only a convertible manual queues.
+            if (manual !== null && typeof manual !== 'string') {
+                converted.push({ manual, rel, note: `${HEXIS_TOOLS_DIR}/${entry.name}` });
+            }
+        }
+    }
+    changed =
+        (await foldIntoPluginFiles(branch, folderDir, relPlugin, folderName, renderedManifest, converted, details, refusals)) ||
+            changed;
+    return changed;
+}
+/**
+ * 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.
+ */
+async function foldIntoPluginFiles(branch, folderDir, relPlugin, folderName, renderedManifest, manuals, details, refusals) {
+    if (manuals.length === 0)
+        return false;
+    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;
+    // 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)
+        : await readJson(path.join(folderDir, PLUGIN_MANIFEST_FILE));
+    if (manifest === null) {
+        console.warn(`[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.');
+    }
+    let wroteMcp = false;
+    let wroteManifest = false;
+    const folded = [];
+    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}`);
+        }
+        // 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;
+            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];
+            if (typeof ns.mcpServers !== 'object' || ns.mcpServers === null || Array.isArray(ns.mcpServers)) {
+                ns.mcpServers = {};
+            }
+            const extServers = ns.mcpServers;
+            if (!Object.prototype.hasOwnProperty.call(extServers, m.name)) {
+                extServers[m.name] = extEntry;
+                wroteManifest = true;
+            }
+        }
+    }
+    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;
+}
+//# sourceMappingURL=groups-to-plugins.step.js.map

package/dist/modules/workspace/startup/steps/groups-to-plugins.step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-to-plugins.step.js","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/groups-to-plugins.step.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,23 @@
+import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+/**
+ * Write `roles.yaml` on any protected branch missing it, generated from the
+ * configured seed admins (`ADMIN_EMAIL`) via the shared validated renderer
+ * (../../../access/render-roles-yaml.ts — a malformed email stops the boot
+ * with a message naming the fix). Never part of the template: a template copy
+ * would seed repos with a stale hard-coded Admin list.
+ *
+ * An existing regular file — whatever it says — is the operator's and is left
+ * alone.
+ *
+ * A missing file with NO admins configured is a declared `skipped`: the lazy
+ * top-up warned and left the file absent, and under the startup contract that
+ * survivable-but-incomplete state is the step's to declare, not to bury in a
+ * log. Access resolution will fail until an Admin roles.yaml exists.
+ */
+export declare class RolesYamlStep implements OnServerStart {
+    private readonly seedAdminEmails;
+    readonly name = "roles-yaml";
+    constructor(seedAdminEmails: readonly string[]);
+    run(ctx: ServerStartContext): Promise<StepResult>;
+}
+//# sourceMappingURL=roles-yaml.step.d.ts.map

package/dist/modules/workspace/startup/steps/roles-yaml.step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-yaml.step.d.ts","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/roles-yaml.step.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE3F;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,YAAW,aAAa;IAGrC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAF5C,QAAQ,CAAC,IAAI,gBAAgB;gBAEA,eAAe,EAAE,SAAS,MAAM,EAAE;IAEzD,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;CAoCxD"}

package/dist/modules/workspace/startup/steps/roles-yaml.step.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { renderRolesYaml } from '../../../access/render-roles-yaml.js';
+/**
+ * Write `roles.yaml` on any protected branch missing it, generated from the
+ * configured seed admins (`ADMIN_EMAIL`) via the shared validated renderer
+ * (../../../access/render-roles-yaml.ts — a malformed email stops the boot
+ * with a message naming the fix). Never part of the template: a template copy
+ * would seed repos with a stale hard-coded Admin list.
+ *
+ * An existing regular file — whatever it says — is the operator's and is left
+ * alone.
+ *
+ * A missing file with NO admins configured is a declared `skipped`: the lazy
+ * top-up warned and left the file absent, and under the startup contract that
+ * survivable-but-incomplete state is the step's to declare, not to bury in a
+ * log. Access resolution will fail until an Admin roles.yaml exists.
+ */
+export class RolesYamlStep {
+    seedAdminEmails;
+    name = 'roles-yaml';
+    constructor(seedAdminEmails) {
+        this.seedAdminEmails = seedAdminEmails;
+    }
+    async run(ctx) {
+        const adminless = [];
+        for (const branch of await ctx.protectedBranches()) {
+            const repoDir = await branch.repoDir();
+            // `lstat`, not `exists`: a DIRECTORY or SYMLINK squatting the name would
+            // 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'));
+            if (found) {
+                if (found.isFile())
+                    continue; // the operator's file — leave it alone
+                throw new Error(`"roles.yaml" on branch "${branch.name}" exists but is not a regular file ` +
+                    `(${found.isSymbolicLink() ? 'symlink' : found.isDirectory() ? 'directory' : 'special file'}). ` +
+                    'Remove or rename it — access loading requires this name to be a readable file at the repository root.');
+            }
+            if (this.seedAdminEmails.length === 0) {
+                adminless.push(branch.name);
+                continue;
+            }
+            branch.write('roles.yaml', renderRolesYaml(this.seedAdminEmails));
+            branch.note('Add roles.yaml granting Admin to the configured seed admins');
+        }
+        if (adminless.length > 0) {
+            // With an empty admin list nothing was declared for ANY branch, so the
+            // skip discards nothing another branch needed.
+            return {
+                outcome: 'skipped',
+                reason: `roles.yaml is missing on ${adminless.join(', ')} and ADMIN_EMAIL is unset — leaving it absent. ` +
+                    'Access resolution will fail until an Admin roles.yaml exists; set ADMIN_EMAIL or add roles.yaml manually.',
+            };
+        }
+        return { outcome: 'ok' };
+    }
+}
+/** `lstat` without the throw — null when nothing is at `p`. */
+async function lstatOrNull(p) {
+    try {
+        return await fs.lstat(p);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=roles-yaml.step.js.map

package/dist/modules/workspace/startup/steps/roles-yaml.step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-yaml.step.js","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/roles-yaml.step.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAGvE;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,aAAa;IAGK;IAFpB,IAAI,GAAG,YAAY,CAAC;IAE7B,YAA6B,eAAkC;QAAlC,oBAAe,GAAf,eAAe,CAAmB;IAAG,CAAC;IAEnE,KAAK,CAAC,GAAG,CAAC,GAAuB;QAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,MAAM,IAAI,MAAM,GAAG,CAAC,iBAAiB,EAAE,EAAE,CAAC;YACnD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;YACvC,yEAAyE;YACzE,mEAAmE;YACnE,uEAAuE;YACvE,wEAAwE;YACxE,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;YAClE,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,KAAK,CAAC,MAAM,EAAE;oBAAE,SAAS,CAAC,uCAAuC;gBACrE,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,CAAC,IAAI,qCAAqC;oBACzE,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc,KAAK;oBAChG,uGAAuG,CAC1G,CAAC;YACJ,CAAC;YACD,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC5B,SAAS;YACX,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,eAAe,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;YAClE,MAAM,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,uEAAuE;YACvE,+CAA+C;YAC/C,OAAO;gBACL,OAAO,EAAE,SAAS;gBAClB,MAAM,EACJ,4BAA4B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,iDAAiD;oBACjG,2GAA2G;aAC9G,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;CACF;AAED,+DAA+D;AAC/D,KAAK,UAAU,WAAW,CAAC,CAAS;IAClC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/modules/workspace/startup/steps/seed-tree.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The empty-remote seed builder the runner takes as `buildSeedTree`: the full
+ * template tree, every reserved root, and a generated roles.yaml. DIRECT fs
+ * writes are correct here — the target is a temp directory the runner inits,
+ * commits and pushes itself, not a branch handle with buffered ops.
+ *
+ * Resolves to the repo-relative paths it GENERATED (roles.yaml plus each
+ * reserved root's .gitkeep): a template `.gitignore` rule could match any of
+ * them, and the runner force-adds them after `git add -A` so a required seed
+ * file can never be silently dropped from the seed commit.
+ *
+ * `extraRootDirs` is validated eagerly, at composition time: a bad value
+ * should fail at boot beside the rest of the wiring, not mid-seed of
+ * somebody's knowledge base.
+ */
+export declare function buildSeedTree(templateDir: string, extraRootDirs: readonly string[], seedAdminEmails: readonly string[]): (dir: string) => Promise<string[]>;
+//# sourceMappingURL=seed-tree.d.ts.map

package/dist/modules/workspace/startup/steps/seed-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-tree.d.ts","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/seed-tree.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CA8BpC"}