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

package/dist/modules/workspace/kb-seed.interface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"kb-seed.interface.js","sourceRoot":"","sources":["../../../src/modules/workspace/kb-seed.interface.ts"],"names":[],"mappings":""}

package/dist/modules/workspace/kb-seed.service.d.ts

@@ -1,125 +0,0 @@
-import type { IKbSeedService } from './kb-seed.interface.js';
-/**
- * The two roots CORE gives a knowledge base: the ontologies, and the plugins
- * that hold skills and tools.
- *
- * `Data/`, `Agents/` and `Pipelines/` are deliberately absent. They scaffold
- * the agentic execution layer, which is not part of this platform — a core
- * deployment that created them would be handing every operator three empty
- * folders it has no feature to fill. A distribution that DOES own that layer
- * passes them as `extraDirs` (and ships a template carrying their READMEs);
- * the names stay reserved in `kb-layout.ts` either way, so a KB that has them
- * still renders them as roots rather than folding them into Knowledge.
- */
-export declare const CORE_REQUIRED_DIRS: readonly string[];
-/**
- * Seeds/tops-up the KB *remote* so the rest of the app's assumption — that the
- * repo it clones already carries the protected branches and base scaffolding —
- * holds even for a brand-new or partially-populated GitHub repo. The template
- * ships inside the platform (`kb-template/`); this reads from it.
- *
- * Split into two moments so the file-level top-up rides along with the clone the
- * app already performs, rather than doing its own extra clones:
- *  - {@link ensureRemoteSeeded} runs once before the first clone (an empty remote
- *    can't be `clone -b`'d): it seeds an empty repo and makes sure every
- *    protected branch *exists* as a ref.
- *  - {@link topUpWorkspace} runs on the freshly-cloned workspace of whatever
- *    branch a user loads: it fills in any missing base files on that branch.
- */
-export declare class KbSeedService implements IKbSeedService {
-    private readonly kbTemplateDir;
-    private readonly seedAdminEmails;
-    /** Single-flight: the first caller runs the remote pass; the rest await its result. */
-    private inFlight;
-    /**
-     * @param kbRepoUrl        Clone/push URL of the KB remote.
-     * @param kbTemplateDir    Filesystem path to the `kb-template/` seed source.
-     * @param protectedBranches Branch names that must exist (e.g. current/target-company-state).
-     * @param defaultBranch    The branch new checkouts land on — used as the init
-     *                         branch of the empty-seed commit and the preferred
-     *                         base when creating a missing protected branch.
-     * @param seedAdminEmails  Admins written into the generated `roles.yaml`.
-     * @param gitUsername      Basic-auth username for git-over-HTTPS (provider-specific).
-     * @param extraDirs        Additional root folders this distribution reserves,
-     *                         on top of {@link CORE_REQUIRED_DIRS}. Their
-     *                         `.gitkeep` is written directly rather than copied,
-     *                         so a distribution can claim a root without also
-     *                         shipping a template entry for it.
-     */
-    constructor(kbRepoUrl: string | (() => string), kbTemplateDir: string, protectedBranches: readonly string[] | (() => readonly string[]), defaultBranch: string | (() => string), seedAdminEmails: readonly string[], gitUsername?: string | (() => string), extraDirs?: readonly string[]);
-    private readonly kbRepoUrl;
-    private readonly protectedBranches;
-    private readonly defaultBranch;
-    private readonly gitUsername;
-    /** Root folders this deployment guarantees — core's two plus any extras. */
-    private readonly requiredDirs;
-    ensureRemoteSeeded(): Promise<void>;
-    private run;
-    /**
-     * Add any missing base scaffolding to an already-cloned workspace of `branch`,
-     * then commit + push it. Called once per fresh clone (any branch a user loads),
-     * so the check reuses the clone the app already made instead of a dedicated one.
-     *
-     * Best-effort: never throws. If the push is rejected (e.g. a concurrent update
-     * to the branch), the local scaffolding commit is rolled back so the workspace
-     * stays consistent with origin, and the top-up is retried on a future clone.
-     */
-    topUpWorkspace(repoDir: string, branch: string): Promise<void>;
-    /** Prefer the default branch as a base, else the first protected branch present, else any head. */
-    private pickBase;
-    /** `-c` args that inject credentials + longpaths, mirroring the workspace clone. */
-    private credArgs;
-    private git;
-    /** Set of branch names on the remote (empty ⇒ uninitialised repo). */
-    private lsRemoteHeads;
-    /** Run a block against a throwaway temp dir, always cleaned up. */
-    private withTempDir;
-    private stampIdentity;
-    /** Copy the entire template tree into `dest` (roles.yaml isn't in it — it's generated). */
-    private copyTemplateTree;
-    /** Copy one template file (by repo-relative path) into `dest`, creating parents. */
-    /**
-     * Whether the repo's copy of `relPath` differs from the template's, modulo
-     * line endings — a CRLF checkout of identical content must read as "same",
-     * or the managed-file refresh would commit churn on every boot forever.
-     */
-    private templateDiffers;
-    private copyTemplateFile;
-    /**
-     * Ensure `.bevelignore` carries `pattern`, appending it when absent. Returns
-     * the paths changed, for the commit.
-     *
-     * APPENDS — never rewrites. The file is the operator's, and every rule
-     * already in it is theirs to keep; this adds one line under a comment saying
-     * where it came from. Absent file, or a file that already lists the pattern,
-     * is a no-op, so running it on every clone changes nothing after the first.
-     *
-     * Matched line-wise rather than by substring: a rule for `Plugins/AGENTS.md`
-     * is not a rule for the root `AGENTS.md`, and treating it as one would leave
-     * the mismatch this exists to close.
-     */
-    private mergeIgnorePattern;
-    /**
-     * Create any reserved root folder this repo is missing, as an empty
-     * `<dir>/.gitkeep`. Returns the paths added, for the commit message.
-     *
-     * WRITTEN, not copied from the template. A `.gitkeep` is empty by definition,
-     * and requiring a template entry per root would mean a distribution could not
-     * reserve one without forking the packaged template.
-     *
-     * Keyed on the DIRECTORY's existence, not the `.gitkeep` file — a branch that
-     * already has content under `KnowledgeBase/` never gets a pointless
-     * placeholder alongside it.
-     */
-    private ensureRequiredDirs;
-    /** `lstat` without the throw — null when nothing is at `p`. */
-    private lstatOrNull;
-    /** `git init` a temp repo, lay down the full template + generated roles.yaml, commit. */
-    private buildSeedCommit;
-    /** Empty remote → one seed commit pushed to every protected branch. */
-    private seedEmptyRemote;
-    /** Create a missing protected branch on the remote, pointed at `base`'s tip. */
-    private createBranchOnRemote;
-    private exists;
-}
-//# sourceMappingURL=kb-seed.service.d.ts.map

package/dist/modules/workspace/kb-seed.service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"kb-seed.service.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/kb-seed.service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA8B7D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAsC,CAAC;AAiDvF;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,cAAc;IAqBhD,OAAO,CAAC,QAAQ,CAAC,aAAa;IAG9B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAvBlC,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAA8B;IAE9C;;;;;;;;;;;;;;OAcG;gBAED,SAAS,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EACjB,aAAa,EAAE,MAAM,EACtC,iBAAiB,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,MAAM,SAAS,MAAM,EAAE,CAAC,EAChE,aAAa,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EACrB,eAAe,EAAE,SAAS,MAAM,EAAE,EACnD,WAAW,GAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAoB,EACvD,SAAS,GAAE,SAAS,MAAM,EAAO;IA+BnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IAEjD,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;YAarB,GAAG;IA4BjB;;;;;;;;OAQG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqHpE,mGAAmG;IACnG,OAAO,CAAC,QAAQ;IAQhB,oFAAoF;IACpF,OAAO,CAAC,QAAQ;YAcF,GAAG;IAgBjB,sEAAsE;YACxD,aAAa;IAU3B,mEAAmE;YACrD,WAAW;YASX,aAAa;IAK3B,2FAA2F;YAC7E,gBAAgB;IAgB9B,oFAAoF;IACpF;;;;OAIG;YACW,eAAe;YASf,gBAAgB;IAO9B;;;;;;;;;;;;OAYG;YACW,kBAAkB;IAmBhC;;;;;;;;;;;OAWG;YACW,kBAAkB;IA2BhC,+DAA+D;YACjD,WAAW;IAQzB,yFAAyF;YAC3E,eAAe;IAc7B,uEAAuE;YACzD,eAAe;IAoB7B,gFAAgF;YAClE,oBAAoB;YASpB,MAAM;CAQrB"}

package/dist/modules/workspace/kb-seed.service.js

@@ -1,535 +0,0 @@
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { KNOWLEDGE_BASE_DIR, LEGACY_GROUPS_DIR, PLUGINS_DIR } from '@bevel-software/platform-shared';
-import { IGNORE_FILENAME } from './bevel-ignore.js';
-import { migrateGroupsToPlugins } from './plugins-migration.js';
-const execFileAsync = promisify(execFile);
-/**
- * Fallback committer identity for seed commits. Mirrors the workspace clone's
- * bot identity so seed commits attribute to the same bot in `git log`.
- */
-const BOT_NAME = 'Bevel Workflow';
-const BOT_EMAIL = 'bevel-workflow@bevel.software';
-/**
- * The **required scaffolding** — the minimum an operational KB needs. When a
- * branch is loaded, any of these that are missing are added to it; the sample
- * ontology is NOT (it only seeds a fully-empty repo).
- *
- * Two kinds:
- *  - {@link REQUIRED_FILES}: repo-root files added when the file is missing.
- *  - {@link CORE_REQUIRED_DIRS} (plus any `extraDirs`): well-known root dirs the
- *    app expects to exist; when a dir is entirely absent it's created by adding
- *    its `<dir>/.gitkeep`. Keyed on the *directory's* existence, not the
- *    `.gitkeep` file — so a branch that already has content under
- *    `KnowledgeBase/` never gets a pointless placeholder.
- *
- * `roles.yaml` is in neither, and is not part of the template at all: it is
- * generated from `ADMIN_EMAIL` (see {@link renderRolesYaml}) and written
- * directly, so a repo can't be seeded with a stale hard-coded Admin list.
- */
-const REQUIRED_FILES = ['access.md', 'AGENTS.md', '.bevelignore', '.gitignore'];
-/**
- * The two roots CORE gives a knowledge base: the ontologies, and the plugins
- * that hold skills and tools.
- *
- * `Data/`, `Agents/` and `Pipelines/` are deliberately absent. They scaffold
- * the agentic execution layer, which is not part of this platform — a core
- * deployment that created them would be handing every operator three empty
- * folders it has no feature to fill. A distribution that DOES own that layer
- * passes them as `extraDirs` (and ships a template carrying their READMEs);
- * the names stay reserved in `kb-layout.ts` either way, so a KB that has them
- * still renders them as roots rather than folding them into Knowledge.
- */
-export const CORE_REQUIRED_DIRS = [KNOWLEDGE_BASE_DIR, PLUGINS_DIR];
-/**
- * A reserved root must be ONE path segment — `Data`, not `Data/x`, `../x` or
- * `/x`. The name is joined onto the repo root, so anything else writes outside
- * the repo being seeded.
- *
- * Deliberately NOT a check against the reserved-root set in `kb-layout.ts`:
- * `Data`, `Agents` and `Pipelines` are all in that set, and they are precisely
- * what a distribution passes here. Being reserved is what makes a name worth
- * claiming — the file tree renders it as its own root instead of folding it
- * into Knowledge — so rejecting reserved names would reject the only real use.
- */
-function assertRootSegment(dir) {
-    if (!dir ||
-        dir === '.' ||
-        dir === '..' ||
-        dir.includes('/') ||
-        dir.includes('\\') ||
-        path.isAbsolute(dir)) {
-        throw new Error(`Reserved KB root must be a single path segment (no separators, no ".."); got "${dir}"`);
-    }
-}
-/** Redact the token from any string that might surface in a log or error. */
-function redact(s) {
-    const token = process.env.GITHUB_TOKEN;
-    return token ? s.replaceAll(token, '***') : s;
-}
-/** Generate `roles.yaml` granting Admin to each seed email. */
-function renderRolesYaml(adminEmails) {
-    const lines = adminEmails.map((e) => `    - ${e}`).join('\n');
-    return ('# Identity → role mapping for access control.\n' +
-        '# Role names are case- and whitespace-insensitive. The `Admin` role is special:\n' +
-        '# only Admins may edit this file, and at least one Admin must always exist.\n' +
-        '#\n' +
-        '# Generated by the Bevel platform at KB-seed time from ADMIN_EMAIL.\n' +
-        'roles:\n' +
-        '  Admin:\n' +
-        `${lines}\n`);
-}
-/**
- * Seeds/tops-up the KB *remote* so the rest of the app's assumption — that the
- * repo it clones already carries the protected branches and base scaffolding —
- * holds even for a brand-new or partially-populated GitHub repo. The template
- * ships inside the platform (`kb-template/`); this reads from it.
- *
- * Split into two moments so the file-level top-up rides along with the clone the
- * app already performs, rather than doing its own extra clones:
- *  - {@link ensureRemoteSeeded} runs once before the first clone (an empty remote
- *    can't be `clone -b`'d): it seeds an empty repo and makes sure every
- *    protected branch *exists* as a ref.
- *  - {@link topUpWorkspace} runs on the freshly-cloned workspace of whatever
- *    branch a user loads: it fills in any missing base files on that branch.
- */
-export class KbSeedService {
-    kbTemplateDir;
-    seedAdminEmails;
-    /** Single-flight: the first caller runs the remote pass; the rest await its result. */
-    inFlight = null;
-    /**
-     * @param kbRepoUrl        Clone/push URL of the KB remote.
-     * @param kbTemplateDir    Filesystem path to the `kb-template/` seed source.
-     * @param protectedBranches Branch names that must exist (e.g. current/target-company-state).
-     * @param defaultBranch    The branch new checkouts land on — used as the init
-     *                         branch of the empty-seed commit and the preferred
-     *                         base when creating a missing protected branch.
-     * @param seedAdminEmails  Admins written into the generated `roles.yaml`.
-     * @param gitUsername      Basic-auth username for git-over-HTTPS (provider-specific).
-     * @param extraDirs        Additional root folders this distribution reserves,
-     *                         on top of {@link CORE_REQUIRED_DIRS}. Their
-     *                         `.gitkeep` is written directly rather than copied,
-     *                         so a distribution can claim a root without also
-     *                         shipping a template entry for it.
-     */
-    constructor(kbRepoUrl, kbTemplateDir, protectedBranches, defaultBranch, seedAdminEmails, gitUsername = 'x-access-token', extraDirs = []) {
-        this.kbTemplateDir = kbTemplateDir;
-        this.seedAdminEmails = seedAdminEmails;
-        // A getter is read per-operation, so a remote supplied through the setup
-        // screen is seeded against without restarting; a string is still accepted.
-        this.kbRepoUrl = typeof kbRepoUrl === 'function' ? kbRepoUrl : () => kbRepoUrl;
-        // Read when seeding, not at construction: the branch model can be supplied
-        // through the setup screen, which happens after this object exists.
-        this.protectedBranches =
-            typeof protectedBranches === 'function' ? protectedBranches : () => protectedBranches;
-        this.defaultBranch = typeof defaultBranch === 'function' ? defaultBranch : () => defaultBranch;
-        this.gitUsername = typeof gitUsername === 'function' ? gitUsername : () => gitUsername;
-        // NOT a getter, unlike its neighbours above: the reserved roots are named
-        // by the composition root in code, not collected on the setup screen, so
-        // there is nothing to re-read. Validated once, here — every entry is joined
-        // onto the repo root and onto `<dir>/.gitkeep`, so a separator or a `..`
-        // would write outside the repo being seeded, and a bad value should fail at
-        // boot beside the rest of the wiring rather than part-way through seeding
-        // somebody's knowledge base. Same contract as `KB_DIR_NAME` in `CoreConfig`.
-        for (const dir of extraDirs) {
-            assertRootSegment(dir);
-            // A root named after a required FILE is a typo with a silent outcome:
-            // the file is laid down first in both seed paths, so `ensureRequiredDirs`
-            // finds the path taken and skips it, and the directory the caller asked
-            // for never appears with nothing said about why.
-            if (REQUIRED_FILES.includes(dir)) {
-                throw new Error(`Reserved KB root "${dir}" collides with a required file of the same name`);
-            }
-        }
-        this.requiredDirs = [...CORE_REQUIRED_DIRS, ...extraDirs];
-    }
-    kbRepoUrl;
-    protectedBranches;
-    defaultBranch;
-    gitUsername;
-    /** Root folders this deployment guarantees — core's two plus any extras. */
-    requiredDirs;
-    ensureRemoteSeeded() {
-        // Cache the promise, not just a boolean, so concurrent first-callers share
-        // one run. On failure we clear it so a later call can retry (a transient
-        // network blip on ls-remote shouldn't wedge seeding for the whole process).
-        if (!this.inFlight) {
-            this.inFlight = this.run().catch((err) => {
-                this.inFlight = null;
-                throw err;
-            });
-        }
-        return this.inFlight;
-    }
-    async run() {
-        const heads = await this.lsRemoteHeads();
-        if (heads.size === 0) {
-            if (this.seedAdminEmails.length === 0) {
-                throw new Error(`KB remote ${redact(this.kbRepoUrl())} is empty and cannot be seeded: ` +
-                    'no initial Admin was supplied. A seeded KB with no Admin is unusable ' +
-                    '(access resolution requires at least one Admin). Unreachable in ' +
-                    'normal operation — ADMIN_EMAIL is required at boot — so this guards ' +
-                    'a caller that constructed the seeder with an empty list.');
-            }
-            await this.seedEmptyRemote();
-            return;
-        }
-        // Non-empty remote: make sure every protected branch exists as a ref so a
-        // later `clone -b <branch>` succeeds. This creates the branch pointer only;
-        // per-branch file top-up happens in `topUpWorkspace` when the branch loads.
-        const base = this.pickBase(heads);
-        for (const branch of this.protectedBranches()) {
-            if (!heads.has(branch)) {
-                await this.createBranchOnRemote(branch, base);
-            }
-        }
-    }
-    /**
-     * Add any missing base scaffolding to an already-cloned workspace of `branch`,
-     * then commit + push it. Called once per fresh clone (any branch a user loads),
-     * so the check reuses the clone the app already made instead of a dedicated one.
-     *
-     * Best-effort: never throws. If the push is rejected (e.g. a concurrent update
-     * to the branch), the local scaffolding commit is rolled back so the workspace
-     * stays consistent with origin, and the top-up is retried on a future clone.
-     */
-    async topUpWorkspace(repoDir, branch) {
-        // Scaffolding lands on PROTECTED branches only. A draft or suggestions
-        // branch is somebody's change-in-waiting, and a seeder commit there
-        // surfaces as noise in their change request's diff against the default
-        // branch (a stray scaffolding file riding along in a skill proposal was
-        // exactly this). Whatever the protected branches are missing, they get
-        // when THEY load — and drafts fork from them.
-        if (!this.protectedBranches().includes(branch))
-            return;
-        try {
-            const added = [];
-            // BEFORE the dir top-up: `ensureRequiredDirs` would otherwise create an
-            // empty `Plugins/` next to the `Plugins/` that is about to become it, and
-            // the migration refuses a destination that already exists — so the
-            // scaffolding would quietly block the very migration it precedes.
-            const migration = await migrateGroupsToPlugins(repoDir);
-            // Notes are logged unconditionally: an advisory note (a manual that
-            // refuses to convert) is exactly the run where the operator needs to
-            // hear about it, and such a run changes no files.
-            for (const note of migration.notes)
-                console.log(`[plugins-migration] ${note}`);
-            // `migrated` means FILES CHANGED — a note-only run stages nothing, or
-            // the commit below would fail empty on every boot with a warning about
-            // a migration that did nothing.
-            if (migration.migrated) {
-                // Stage the legacy root ONLY when the rename happened this run: `git
-                // add -A -- Groups Plugins` fails outright on a pathspec that matches
-                // nothing, and a reorganisation inside an existing Plugins/ tree has
-                // no Groups/ to stage.
-                if (migration.renamed)
-                    added.push(LEGACY_GROUPS_DIR);
-                added.push(PLUGINS_DIR);
-                // The rename's companion edit to the repo-root ignore file — outside
-                // the two roots, so it needs its own pathspec to land in the commit.
-                if (migration.ignoreRewritten)
-                    added.push(IGNORE_FILENAME);
-            }
-            for (const rel of REQUIRED_FILES) {
-                if (!(await this.exists(path.join(repoDir, rel)))) {
-                    await this.copyTemplateFile(rel, repoDir);
-                    added.push(rel);
-                    // Adding AGENTS.md to a knowledge base seeded before the rename
-                    // leaves it VISIBLE: that repo's `.bevelignore` lists CLAUDE.md and
-                    // knows nothing of the new name, so the conventions doc starts
-                    // showing up in the file tree and the agent view. We created the
-                    // mismatch by adding the file, so we close it here.
-                    if (rel === 'AGENTS.md')
-                        added.push(...(await this.mergeIgnorePattern(repoDir, rel)));
-                }
-            }
-            // AGENTS.md is MANAGED, not merely seeded: the platform owns its
-            // content, and a stale copy is replaced with the packaged template's on
-            // every top-up (each fresh clone of a protected branch — in practice,
-            // every server restart). The file's own header says so, which is what
-            // makes overwriting edits a stated contract instead of a surprise.
-            let agentsRefreshed = false;
-            if (!added.includes('AGENTS.md') &&
-                (await this.templateDiffers(repoDir, 'AGENTS.md'))) {
-                await this.copyTemplateFile('AGENTS.md', repoDir);
-                added.push('AGENTS.md');
-                agentsRefreshed = true;
-            }
-            added.push(...(await this.ensureRequiredDirs(repoDir)));
-            if (!(await this.exists(path.join(repoDir, 'roles.yaml')))) {
-                if (this.seedAdminEmails.length > 0) {
-                    await fs.writeFile(path.join(repoDir, 'roles.yaml'), renderRolesYaml(this.seedAdminEmails), 'utf8');
-                    added.push('roles.yaml');
-                }
-                else {
-                    console.warn(`[kb-seed] Branch "${branch}" is missing roles.yaml 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.');
-                }
-            }
-            if (added.length === 0)
-                return; // already fully scaffolded → no-op
-            // Stamp the bot identity so the commit has an author even if the clone
-            // wasn't configured with one (the workspace clone already sets the same
-            // values, so this is a harmless no-op there).
-            await this.stampIdentity(repoDir);
-            // `-A` so the migration's renames stage their DELETIONS as well; a plain
-            // `add` would commit the new tree while leaving `Plugins/` in the index.
-            await this.git(repoDir, ['add', '-A', '--', ...added]);
-            const message = migration.migrated
-                ? migration.renamed
-                    ? `Move ${LEGACY_GROUPS_DIR}/ to ${PLUGINS_DIR}/ (Agent Plugins layout)`
-                    : `Reorganise ${PLUGINS_DIR}/ to the Agent Plugins layout`
-                : agentsRefreshed && added.length === 1
-                    ? 'Update AGENTS.md to the current platform template'
-                    : `Add missing KB scaffolding: ${added.join(', ')}`;
-            await this.git(repoDir, ['commit', '-m', message]);
-            try {
-                await this.git(repoDir, ['push', 'origin', `HEAD:refs/heads/${branch}`]);
-                console.log(`[kb-seed] Topped up "${branch}" with: ${added.join(', ')}`);
-            }
-            catch (err) {
-                // Roll the local branch back to origin so the workspace never sits ahead
-                // of the remote (which would confuse the workflow git layer). The files
-                // simply aren't present this session; a later fresh clone retries.
-                console.warn(`[kb-seed] Could not push scaffolding to "${branch}", rolling back local commit:`, err instanceof Error ? redact(err.message) : String(err));
-                await this.git(repoDir, ['reset', '--hard', `origin/${branch}`]).catch(() => { });
-            }
-        }
-        catch (err) {
-            // Top-up is best-effort infrastructure — a failure here must not block the
-            // user from loading the branch.
-            console.warn(`[kb-seed] Scaffolding top-up for "${branch}" failed (non-fatal):`, err instanceof Error ? redact(err.message) : String(err));
-        }
-    }
-    /** Prefer the default branch as a base, else the first protected branch present, else any head. */
-    pickBase(heads) {
-        if (heads.has(this.defaultBranch()))
-            return this.defaultBranch();
-        const protectedPresent = this.protectedBranches().find((b) => heads.has(b));
-        if (protectedPresent)
-            return protectedPresent;
-        // Deterministic pick so repeated runs behave identically.
-        return [...heads].sort()[0];
-    }
-    /** `-c` args that inject credentials + longpaths, mirroring the workspace clone. */
-    credArgs() {
-        const args = ['-c', 'core.longpaths=true'];
-        const token = process.env.GITHUB_TOKEN;
-        if (token) {
-            // The helper reads GITHUB_TOKEN at runtime, so the value never appears in argv.
-            // Username is provider-specific; the token is always the Basic-auth password.
-            args.push('-c', `credential.helper=!f() { echo "username=${this.gitUsername()}"; echo "password=$GITHUB_TOKEN"; }; f`);
-        }
-        return args;
-    }
-    async git(cwd, args) {
-        try {
-            const { stdout } = await execFileAsync('git', args, {
-                cwd: cwd ?? undefined,
-                env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
-                maxBuffer: 32 * 1024 * 1024,
-            });
-            return stdout.toString();
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            let i = 0;
-            while (i < args.length && args[i] === '-c')
-                i += 2;
-            throw new Error(`git ${args[i] ?? args[0]} failed: ${redact(msg)}`);
-        }
-    }
-    /** Set of branch names on the remote (empty ⇒ uninitialised repo). */
-    async lsRemoteHeads() {
-        const out = await this.git(null, [...this.credArgs(), 'ls-remote', '--heads', this.kbRepoUrl()]);
-        const heads = new Set();
-        for (const line of out.split('\n')) {
-            const m = line.match(/\srefs\/heads\/(.+)$/);
-            if (m)
-                heads.add(m[1].trim());
-        }
-        return heads;
-    }
-    /** Run a block against a throwaway temp dir, always cleaned up. */
-    async withTempDir(fn) {
-        const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-seed-'));
-        try {
-            return await fn(dir);
-        }
-        finally {
-            await fs.rm(dir, { recursive: true, force: true }).catch(() => { });
-        }
-    }
-    async stampIdentity(repo) {
-        await this.git(repo, ['config', 'user.name', BOT_NAME]);
-        await this.git(repo, ['config', 'user.email', BOT_EMAIL]);
-    }
-    /** Copy the entire template tree into `dest` (roles.yaml isn't in it — it's generated). */
-    async copyTemplateTree(dest) {
-        const walk = async (relDir) => {
-            const abs = path.join(this.kbTemplateDir, relDir);
-            const entries = await fs.readdir(abs, { withFileTypes: true });
-            for (const entry of entries) {
-                const rel = relDir ? path.join(relDir, entry.name) : entry.name;
-                if (entry.isDirectory()) {
-                    await walk(rel);
-                }
-                else {
-                    await this.copyTemplateFile(rel, dest);
-                }
-            }
-        };
-        await walk('');
-    }
-    /** Copy one template file (by repo-relative path) into `dest`, creating parents. */
-    /**
-     * Whether the repo's copy of `relPath` differs from the template's, modulo
-     * line endings — a CRLF checkout of identical content must read as "same",
-     * or the managed-file refresh would commit churn on every boot forever.
-     */
-    async templateDiffers(repoDir, relPath) {
-        const norm = (text) => text.replace(/\r\n?/g, '\n');
-        const [current, template] = await Promise.all([
-            fs.readFile(path.join(repoDir, relPath), 'utf8'),
-            fs.readFile(path.join(this.kbTemplateDir, relPath), 'utf8'),
-        ]);
-        return norm(current) !== norm(template);
-    }
-    async copyTemplateFile(relPath, dest) {
-        const from = path.join(this.kbTemplateDir, relPath);
-        const to = path.join(dest, relPath);
-        await fs.mkdir(path.dirname(to), { recursive: true });
-        await fs.copyFile(from, to);
-    }
-    /**
-     * Ensure `.bevelignore` carries `pattern`, appending it when absent. Returns
-     * the paths changed, for the commit.
-     *
-     * APPENDS — never rewrites. The file is the operator's, and every rule
-     * already in it is theirs to keep; this adds one line under a comment saying
-     * where it came from. Absent file, or a file that already lists the pattern,
-     * is a no-op, so running it on every clone changes nothing after the first.
-     *
-     * Matched line-wise rather than by substring: a rule for `Plugins/AGENTS.md`
-     * is not a rule for the root `AGENTS.md`, and treating it as one would leave
-     * the mismatch this exists to close.
-     */
-    async mergeIgnorePattern(repoDir, pattern) {
-        const ignorePath = path.join(repoDir, IGNORE_FILENAME);
-        let current;
-        try {
-            current = await fs.readFile(ignorePath, 'utf8');
-        }
-        catch {
-            return []; // No ignore file — the template's copy arrives with the pattern in it.
-        }
-        const lines = current.split('\n').map((l) => l.trim());
-        if (lines.includes(pattern))
-            return [];
-        const separator = current.endsWith('\n') ? '' : '\n';
-        await fs.appendFile(ignorePath, `${separator}\n# Added by the platform: the conventions doc is not node content.\n${pattern}\n`, 'utf8');
-        return [IGNORE_FILENAME];
-    }
-    /**
-     * Create any reserved root folder this repo is missing, as an empty
-     * `<dir>/.gitkeep`. Returns the paths added, for the commit message.
-     *
-     * WRITTEN, not copied from the template. A `.gitkeep` is empty by definition,
-     * and requiring a template entry per root would mean a distribution could not
-     * reserve one without forking the packaged template.
-     *
-     * Keyed on the DIRECTORY's existence, not the `.gitkeep` file — a branch that
-     * already has content under `KnowledgeBase/` never gets a pointless
-     * placeholder alongside it.
-     */
-    async ensureRequiredDirs(repoDir) {
-        const added = [];
-        for (const rootDir of this.requiredDirs) {
-            const abs = path.join(repoDir, rootDir);
-            // `lstat`, not `exists`: `fs.access` answers "is there something here?",
-            // which is true of a FILE named `Plugins` — and the old skip-if-present
-            // check then did nothing and reported success, leaving a knowledge base
-            // permanently missing a root it claims to guarantee. `lstat` rather than
-            // `stat` so a SYMLINK is rejected too: a link named `Plugins` is not a KB
-            // layout, and one pointing outside the repo would make every later write
-            // into it land somewhere nobody asked for.
-            const found = await this.lstatOrNull(abs);
-            if (found) {
-                if (found.isDirectory())
-                    continue;
-                throw new Error(`KB root "${rootDir}" exists but is not a directory ` +
-                    `(${found.isSymbolicLink() ? 'symlink' : 'file'}). Remove or rename it — ` +
-                    'the platform requires this name to be a folder.');
-            }
-            await fs.mkdir(abs, { recursive: true });
-            await fs.writeFile(path.join(abs, '.gitkeep'), '', 'utf8');
-            added.push(`${rootDir}/.gitkeep`);
-        }
-        return added;
-    }
-    /** `lstat` without the throw — null when nothing is at `p`. */
-    async lstatOrNull(p) {
-        try {
-            return await fs.lstat(p);
-        }
-        catch {
-            return null;
-        }
-    }
-    /** `git init` a temp repo, lay down the full template + generated roles.yaml, commit. */
-    async buildSeedCommit(dir) {
-        await this.git(dir, ['init', '-b', this.defaultBranch()]);
-        await this.stampIdentity(dir);
-        await this.copyTemplateTree(dir);
-        // Reserved roots the template does not carry. Without this the seed commit
-        // would hold only what the template has, and a distribution's own roots
-        // would appear a step later, when the first clone gets topped up — the same
-        // folders, arriving in a second commit for no reason.
-        await this.ensureRequiredDirs(dir);
-        await fs.writeFile(path.join(dir, 'roles.yaml'), renderRolesYaml(this.seedAdminEmails), 'utf8');
-        await this.git(dir, ['add', '-A']);
-        await this.git(dir, ['commit', '-m', 'Seed knowledge base from Bevel template']);
-    }
-    /** Empty remote → one seed commit pushed to every protected branch. */
-    async seedEmptyRemote() {
-        await this.withTempDir(async (dir) => {
-            await this.buildSeedCommit(dir);
-            // Point every protected branch at the seed commit. The init branch is
-            // already `defaultBranch`; create the rest as refs to HEAD.
-            for (const branch of this.protectedBranches()) {
-                if (branch !== this.defaultBranch()) {
-                    await this.git(dir, ['branch', branch]);
-                }
-            }
-            await this.git(dir, ['remote', 'add', 'origin', this.kbRepoUrl()]);
-            // Push only the protected branches — never the stray init branch if it
-            // isn't itself protected.
-            await this.git(dir, [...this.credArgs(), 'push', '-u', 'origin', ...this.protectedBranches()]);
-            console.log(`[kb-seed] Seeded empty KB remote with branches: ${this.protectedBranches().join(', ')}`);
-        });
-    }
-    /** Create a missing protected branch on the remote, pointed at `base`'s tip. */
-    async createBranchOnRemote(branch, base) {
-        await this.withTempDir(async (dir) => {
-            await this.git(dir, [...this.credArgs(), 'clone', '--depth', '1', '-b', base, this.kbRepoUrl(), dir]);
-            // Push base's fetched tip up under the new branch name.
-            await this.git(dir, [...this.credArgs(), 'push', 'origin', `HEAD:refs/heads/${branch}`]);
-            console.log(`[kb-seed] Created missing protected branch "${branch}" from "${base}"`);
-        });
-    }
-    async exists(p) {
-        try {
-            await fs.access(p);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-}
-//# sourceMappingURL=kb-seed.service.js.map