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

package/dist/modules/workspace/startup/steps/seed-tree.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { renderRolesYaml } from '../../../access/render-roles-yaml.js';
+import { TEMPLATE_SOURCE_FALLBACKS, reservedRootDirs, templateSource } from './template-files.step.js';
+/**
+ * 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 function buildSeedTree(templateDir, extraRootDirs, seedAdminEmails) {
+    const requiredDirs = reservedRootDirs(extraRootDirs);
+    return async (dir) => {
+        const generated = [];
+        await copyTemplateTree(templateDir, 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 startup phase tops them up —
+        // the same folders, arriving in a second commit for no reason. Keyed on
+        // the DIRECTORY's existence: a template already carrying content under a
+        // root never gets a pointless placeholder beside it.
+        for (const rootDir of requiredDirs) {
+            const abs = path.join(dir, rootDir);
+            const found = await lstatOrNull(abs);
+            if (found) {
+                if (found.isDirectory())
+                    continue;
+                // Only a template shipping a FILE under a reserved name reaches this —
+                // a broken build, not a broken knowledge base.
+                throw new Error(`KB root "${rootDir}" exists in the template but is not a directory.`);
+            }
+            await fs.mkdir(abs, { recursive: true });
+            await fs.writeFile(path.join(abs, '.gitkeep'), '', 'utf8');
+            generated.push(`${rootDir}/.gitkeep`);
+        }
+        // Generated, never templated — see roles-yaml.step.ts. The runner refuses
+        // to seed an empty remote with no admins, so the list is non-empty here.
+        await fs.writeFile(path.join(dir, 'roles.yaml'), renderRolesYaml(seedAdminEmails), 'utf8');
+        generated.push('roles.yaml');
+        return generated;
+    };
+}
+/** Copy the entire template tree into `dest` (roles.yaml isn't in it — it's generated). */
+async function copyTemplateTree(templateDir, dest) {
+    const packableToReal = new Map(Object.entries(TEMPLATE_SOURCE_FALLBACKS).map(([real, packable]) => [packable, real]));
+    const walk = async (relDir) => {
+        const abs = path.join(templateDir, relDir);
+        const entries = await fs.readdir(abs, { withFileTypes: true });
+        for (const entry of entries) {
+            // Never copy a git dir: a KB_TEMPLATE_DIR that is itself a working tree
+            // (this repo in a Docker build) must not seed its history into the KB.
+            if (entry.name === '.git')
+                continue;
+            const rel = relDir ? path.join(relDir, entry.name) : entry.name;
+            if (entry.isDirectory()) {
+                await walk(rel);
+                continue;
+            }
+            // A packable spelling at the template root seeds under its REAL name
+            // — unless the template also carries the literal file (a
+            // distribution's own template), which wins and is copied by its own
+            // walk entry; copying the packable twin too would clobber it.
+            const realName = relDir === '' ? packableToReal.get(entry.name) : undefined;
+            if (realName !== undefined) {
+                if (!(await exists(path.join(templateDir, realName)))) {
+                    await copyTemplateFile(templateDir, realName, dest);
+                }
+                continue;
+            }
+            await copyTemplateFile(templateDir, rel, dest);
+        }
+    };
+    await walk('');
+}
+/** Copy one template file (by repo-relative path) into `dest`, creating parents. */
+async function copyTemplateFile(templateDir, relPath, dest) {
+    const from = await templateSource(templateDir, relPath);
+    const to = path.join(dest, relPath);
+    await fs.mkdir(path.dirname(to), { recursive: true });
+    await fs.copyFile(from, to);
+}
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `lstat` without the throw — null when nothing is at `p`. */
+async function lstatOrNull(p) {
+    try {
+        return await fs.lstat(p);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=seed-tree.js.map

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

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

package/dist/modules/workspace/startup/steps/template-files.step.d.ts

@@ -0,0 +1,103 @@
+import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+/**
+ * The **required scaffolding** — the minimum an operational KB needs. Any of
+ * these missing from a protected branch are added at the startup phase; the
+ * sample ontology is NOT (it only seeds a fully-empty repo, see seed-tree.ts).
+ *
+ * Two kinds:
+ *  - {@link REQUIRED_FILES}: repo-root files added when the file is missing.
+ *  - Reserved root dirs (core's two plus a distribution's `extraRootDirs`):
+ *    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 roles-yaml.step.ts), so a repo can't be
+ * seeded with a stale hard-coded Admin list.
+ */
+export declare const REQUIRED_FILES: readonly string[];
+/**
+ * Repo-root files the startup phase GENERATES rather than copies — today just
+ * `roles.yaml`, rendered from `ADMIN_EMAIL` (see roles-yaml.step.ts and
+ * seed-tree.ts). Reserved-root validation must treat these exactly like
+ * {@link REQUIRED_FILES}: a root claiming a generated name is the same silent
+ * typo with the same silent outcome.
+ */
+export declare const GENERATED_FILES: readonly string[];
+/**
+ * Destination name → the packable spelling the template may carry instead.
+ * npm strips every file named `.gitignore` from a published tarball, so the
+ * packaged template cannot ship one under its real name (see
+ * {@link templateSource}).
+ */
+export declare const TEMPLATE_SOURCE_FALLBACKS: Readonly<Record<string, string>>;
+/**
+ * Core's guaranteed roots plus a distribution's extras, validated once at
+ * composition time: every entry is joined onto the repo root and onto
+ * `<dir>/.gitkeep`, so a separator or a `..` would write outside the repo
+ * being maintained, and a bad value should fail at boot beside the rest of
+ * the wiring rather than part-way through maintaining somebody's knowledge
+ * base. Shared with the empty-remote seed builder (seed-tree.ts) so the two
+ * paths can never disagree about what a deployment guarantees.
+ */
+export declare function reservedRootDirs(extraRootDirs: readonly string[]): readonly string[];
+/**
+ * Where `relPath`'s template content actually lives. npm refuses to pack
+ * files named `.gitignore` — every such file is silently stripped from the
+ * published tarball — so the packaged template ships the KB's gitignore
+ * under a packable name and the seeder writes it to its real one. A
+ * template carrying the literal file (a distribution's own
+ * KB_TEMPLATE_DIR, or this repo's tree in a Docker build) wins outright:
+ * the mapping is a fallback, never a rename.
+ */
+export declare function templateSource(templateDir: string, relPath: string): Promise<string>;
+/**
+ * The template top-up as an {@link OnServerStart} step: add any missing base
+ * scaffolding to every PROTECTED branch, and keep the managed AGENTS.md
+ * current. Drafts are deliberately out of scope — whatever the protected
+ * branches gain, drafts fork from; a scaffolding addition on a draft would
+ * surface as noise in its change request's diff. (Unlike the Groups→Plugins
+ * rename, a missing file diffs as one file, not the whole tree — so the
+ * uniform-application argument does not bite here.)
+ *
+ * Everything is DECLARED on the branch handle; reads go against the pre-step
+ * tree via `repoDir()`. Fail-open behavior from the lazy top-up (best-effort,
+ * never throws) is deliberately gone: an unexpected state — a file squatting
+ * a reserved root name — now throws and stops the boot, which is the phase's
+ * contract for states a human must look at.
+ */
+export declare class TemplateFilesStep implements OnServerStart {
+    readonly name = "template-files";
+    private readonly requiredDirs;
+    /**
+     * @param extraRootDirs Additional root folders this distribution reserves,
+     *                      on top of core's two. Their `.gitkeep` is written
+     *                      directly rather than copied, so a distribution can
+     *                      claim a root without also shipping a template entry
+     *                      for it.
+     */
+    constructor(extraRootDirs?: readonly string[]);
+    run(ctx: ServerStartContext): Promise<StepResult>;
+    private topUp;
+    /**
+     * Which reserved roots are absent — and which are SQUATTED. `lstat`, not
+     * `exists`: `fs.access` answers "is there something here?", which is true of
+     * a FILE named `Plugins` — and a skip-if-present check would then do nothing
+     * and report 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. A squatter THROWS — under this phase's fail-closed contract that
+     * stops the boot, which such a state deserves.
+     */
+    private missingDirs;
+    /**
+     * Declare each missing reserved root as an empty `<dir>/.gitkeep`.
+     * 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.
+     */
+    private ensureRequiredDirs;
+}
+//# sourceMappingURL=template-files.step.d.ts.map

package/dist/modules/workspace/startup/steps/template-files.step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-files.step.d.ts","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/template-files.step.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAErG;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA6D,CAAC;AAE1G;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAmB,CAAC;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEtE,CAAC;AAwCF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAcpF;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS1F;AAoBD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,oBAAoB;IAEjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IAEjD;;;;;;OAMG;gBACS,aAAa,GAAE,SAAS,MAAM,EAAO;IAI3C,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;YAOzC,KAAK;IAoEnB;;;;;;;;;;OAUG;YACW,WAAW;IAiBzB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;CAQ3B"}

package/dist/modules/workspace/startup/steps/template-files.step.js

@@ -0,0 +1,337 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { KNOWLEDGE_BASE_DIR, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import { IGNORE_FILENAME } from '../../bevel-ignore.js';
+/**
+ * The **required scaffolding** — the minimum an operational KB needs. Any of
+ * these missing from a protected branch are added at the startup phase; the
+ * sample ontology is NOT (it only seeds a fully-empty repo, see seed-tree.ts).
+ *
+ * Two kinds:
+ *  - {@link REQUIRED_FILES}: repo-root files added when the file is missing.
+ *  - Reserved root dirs (core's two plus a distribution's `extraRootDirs`):
+ *    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 roles-yaml.step.ts), so a repo can't be
+ * seeded with a stale hard-coded Admin list.
+ */
+export const REQUIRED_FILES = ['access.md', 'AGENTS.md', '.bevelignore', '.gitignore'];
+/**
+ * Repo-root files the startup phase GENERATES rather than copies — today just
+ * `roles.yaml`, rendered from `ADMIN_EMAIL` (see roles-yaml.step.ts and
+ * seed-tree.ts). Reserved-root validation must treat these exactly like
+ * {@link REQUIRED_FILES}: a root claiming a generated name is the same silent
+ * typo with the same silent outcome.
+ */
+export const GENERATED_FILES = ['roles.yaml'];
+/**
+ * Destination name → the packable spelling the template may carry instead.
+ * npm strips every file named `.gitignore` from a published tarball, so the
+ * packaged template cannot ship one under its real name (see
+ * {@link templateSource}).
+ */
+export const TEMPLATE_SOURCE_FALLBACKS = {
+    '.gitignore': 'gitignore.template',
+};
+/**
+ * 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 `extraRootDirs` (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.
+ */
+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 maintained.
+ *
+ * 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}"`);
+    }
+    // `.git` can never be a KB root: writing `<dir>/.gitkeep` under it would
+    // corrupt the clone's own metadata. Any case — Windows filesystems treat
+    // `.GIT` as the same directory.
+    if (dir.toLowerCase() === '.git') {
+        throw new Error(`Reserved KB root must not be ".git" (any case); got "${dir}"`);
+    }
+}
+/**
+ * Core's guaranteed roots plus a distribution's extras, validated once at
+ * composition time: every entry is joined onto the repo root and onto
+ * `<dir>/.gitkeep`, so a separator or a `..` would write outside the repo
+ * being maintained, and a bad value should fail at boot beside the rest of
+ * the wiring rather than part-way through maintaining somebody's knowledge
+ * base. Shared with the empty-remote seed builder (seed-tree.ts) so the two
+ * paths can never disagree about what a deployment guarantees.
+ */
+export function reservedRootDirs(extraRootDirs) {
+    for (const dir of extraRootDirs) {
+        assertRootSegment(dir);
+        // A root named after a required OR generated FILE is a typo with a silent
+        // outcome: the file is laid down first, so the dir check 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) || GENERATED_FILES.includes(dir)) {
+            throw new Error(`Reserved KB root "${dir}" collides with a required or generated file of the same name`);
+        }
+    }
+    return [...CORE_REQUIRED_DIRS, ...extraRootDirs];
+}
+/**
+ * Where `relPath`'s template content actually lives. npm refuses to pack
+ * files named `.gitignore` — every such file is silently stripped from the
+ * published tarball — so the packaged template ships the KB's gitignore
+ * under a packable name and the seeder writes it to its real one. A
+ * template carrying the literal file (a distribution's own
+ * KB_TEMPLATE_DIR, or this repo's tree in a Docker build) wins outright:
+ * the mapping is a fallback, never a rename.
+ */
+export async function templateSource(templateDir, relPath) {
+    const direct = path.join(templateDir, relPath);
+    if (await exists(direct))
+        return direct;
+    const packable = TEMPLATE_SOURCE_FALLBACKS[relPath];
+    if (packable !== undefined) {
+        const fallback = path.join(templateDir, packable);
+        if (await exists(fallback))
+            return fallback;
+    }
+    return direct; // let the ENOENT surface under the name the caller asked for
+}
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `lstat` without the throw — null when nothing is at `p`. */
+async function lstatOrNull(p) {
+    try {
+        return await fs.lstat(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The template top-up as an {@link OnServerStart} step: add any missing base
+ * scaffolding to every PROTECTED branch, and keep the managed AGENTS.md
+ * current. Drafts are deliberately out of scope — whatever the protected
+ * branches gain, drafts fork from; a scaffolding addition on a draft would
+ * surface as noise in its change request's diff. (Unlike the Groups→Plugins
+ * rename, a missing file diffs as one file, not the whole tree — so the
+ * uniform-application argument does not bite here.)
+ *
+ * Everything is DECLARED on the branch handle; reads go against the pre-step
+ * tree via `repoDir()`. Fail-open behavior from the lazy top-up (best-effort,
+ * never throws) is deliberately gone: an unexpected state — a file squatting
+ * a reserved root name — now throws and stops the boot, which is the phase's
+ * contract for states a human must look at.
+ */
+export class TemplateFilesStep {
+    name = 'template-files';
+    requiredDirs;
+    /**
+     * @param extraRootDirs Additional root folders this distribution reserves,
+     *                      on top of core's two. Their `.gitkeep` is written
+     *                      directly rather than copied, so a distribution can
+     *                      claim a root without also shipping a template entry
+     *                      for it.
+     */
+    constructor(extraRootDirs = []) {
+        this.requiredDirs = reservedRootDirs(extraRootDirs);
+    }
+    async run(ctx) {
+        for (const branch of await ctx.protectedBranches()) {
+            await this.topUp(ctx.templateDir, branch);
+        }
+        return { outcome: 'ok' };
+    }
+    async topUp(templateDir, branch) {
+        const repoDir = await branch.repoDir();
+        const added = [];
+        for (const rel of REQUIRED_FILES) {
+            // `lstat`, not `exists`: a DIRECTORY or SYMLINK squatting a required
+            // file's name would read as "present", and a skip-if-present check
+            // would then report success over a knowledge base whose root access
+            // policy (say) cannot be read. Fail-closed, same as the reserved-root
+            // squatting check below: this is a state a human must fix.
+            const found = await lstatOrNull(path.join(repoDir, rel));
+            if (found) {
+                if (found.isFile())
+                    continue;
+                throw new Error(`Required KB file "${rel}" on branch "${branch.name}" exists but is not a regular file ` +
+                    `(${found.isSymbolicLink() ? 'symlink' : found.isDirectory() ? 'directory' : 'special file'}). ` +
+                    'Remove or rename it — the platform requires this name to be a readable file.');
+            }
+            let content = await readTemplate(templateDir, rel);
+            // The on-disk merge below only runs against an EXISTING ignore file; a
+            // freshly-declared one was merely assumed to carry the AGENTS.md rule —
+            // true of the packaged template, not necessarily of a distribution's
+            // custom one. Make it true here, so the managed conventions doc is
+            // hidden from the file tree from the first boot either way.
+            if (rel === IGNORE_FILENAME) {
+                content = withIgnorePattern(new TextDecoder().decode(content), 'AGENTS.md');
+            }
+            branch.write(rel, content);
+            added.push(rel);
+        }
+        // AGENTS.md left VISIBLE by a stale `.bevelignore` is closed here — and
+        // UNCONDITIONALLY, not only when the file was just added: a KB whose
+        // AGENTS.md predates the CLAUDE.md→AGENTS.md rename has an ignore file
+        // that lists the old name and knows nothing of the new one, so the
+        // conventions doc shows up in the file tree and the agent view.
+        // Idempotent: an ignore file already carrying the rule — or absent, in
+        // which case the template's copy declared above arrives with the rule in
+        // it — changes nothing and produces no note. Deliberately checked by
+        // LINE PRESENCE, not effective outcome: a later `!AGENTS.md` negation is
+        // the operator explicitly choosing to SHOW the file, and hiding it is a
+        // default this step provides, not a mandate it re-imposes every boot.
+        added.push(...(await mergeIgnorePattern(repoDir, branch, 'AGENTS.md')));
+        // AGENTS.md is MANAGED, not merely seeded: the platform owns its content,
+        // and a stale copy is replaced with the packaged template's every startup
+        // phase. 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 templateDiffers(templateDir, repoDir, 'AGENTS.md'))) {
+            branch.write('AGENTS.md', await readTemplate(templateDir, 'AGENTS.md'));
+            added.push('AGENTS.md');
+            agentsRefreshed = true;
+        }
+        added.push(...this.ensureRequiredDirs(repoDir, branch, await this.missingDirs(repoDir)));
+        if (added.length === 0)
+            return;
+        // One honest line; it becomes the commit subject when this step is the
+        // first to dirty the branch.
+        branch.note(agentsRefreshed && added.length === 1
+            ? 'Update AGENTS.md to the current platform template'
+            : `Add missing KB scaffolding: ${added.join(', ')}`);
+    }
+    /**
+     * Which reserved roots are absent — and which are SQUATTED. `lstat`, not
+     * `exists`: `fs.access` answers "is there something here?", which is true of
+     * a FILE named `Plugins` — and a skip-if-present check would then do nothing
+     * and report 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. A squatter THROWS — under this phase's fail-closed contract that
+     * stops the boot, which such a state deserves.
+     */
+    async missingDirs(repoDir) {
+        const missing = [];
+        for (const rootDir of this.requiredDirs) {
+            const found = await lstatOrNull(path.join(repoDir, rootDir));
+            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.');
+            }
+            missing.push(rootDir);
+        }
+        return missing;
+    }
+    /**
+     * Declare each missing reserved root as an empty `<dir>/.gitkeep`.
+     * 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.
+     */
+    ensureRequiredDirs(repoDir, branch, missing) {
+        const added = [];
+        for (const rootDir of missing) {
+            branch.write(`${rootDir}/.gitkeep`, '');
+            added.push(`${rootDir}/.gitkeep`);
+        }
+        return added;
+    }
+}
+/** The template's content for `relPath`, bytes as shipped. */
+async function readTemplate(templateDir, relPath) {
+    return fs.readFile(await templateSource(templateDir, relPath));
+}
+/**
+ * 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 function templateDiffers(templateDir, repoDir, relPath) {
+    const norm = (text) => text.replace(/\r\n?/g, '\n');
+    const [current, template] = await Promise.all([
+        fs.readFile(path.join(repoDir, relPath), 'utf8'),
+        templateSource(templateDir, relPath).then((from) => fs.readFile(from, 'utf8')),
+    ]);
+    return norm(current) !== norm(template);
+}
+/**
+ * Ensure `.bevelignore` carries `pattern`, declaring the appended content when
+ * absent. Returns the paths changed, for the note.
+ *
+ * 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 — an absent file means the template's copy (declared in the same
+ * step) arrives with the pattern in it.
+ *
+ * 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 function mergeIgnorePattern(repoDir, branch, pattern) {
+    let current;
+    try {
+        current = await fs.readFile(path.join(repoDir, IGNORE_FILENAME), 'utf8');
+    }
+    catch {
+        // No ignore file — the copy declared from the template arrives with the
+        // pattern in it (guaranteed at declaration time, see the required-files
+        // loop above).
+        return [];
+    }
+    const merged = withIgnorePattern(current, pattern);
+    if (merged === current)
+        return [];
+    branch.write(IGNORE_FILENAME, merged);
+    return [IGNORE_FILENAME];
+}
+/**
+ * `text` with `pattern` guaranteed present as a LINE — appended under a
+ * comment naming its origin when absent, returned unchanged when present.
+ * Line-wise match, same rationale as {@link mergeIgnorePattern}.
+ *
+ * An explicit `!pattern` line also returns the text unchanged: that is the
+ * operator choosing to SHOW the file, and ordered matching means a positive
+ * line appended after it would win and silently defeat the choice. Hiding
+ * the conventions doc is a default this provides, never a mandate.
+ */
+function withIgnorePattern(text, pattern) {
+    const lines = text.split('\n').map((l) => l.trim());
+    if (lines.includes(pattern) || lines.includes(`!${pattern}`))
+        return text;
+    const separator = text.endsWith('\n') ? '' : '\n';
+    return `${text}${separator}\n# Added by the platform: the conventions doc is not node content.\n${pattern}\n`;
+}
+//# sourceMappingURL=template-files.step.js.map

package/dist/modules/workspace/startup/steps/template-files.step.js.map

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

package/dist/modules/workspace/workspace.service.d.ts

@@ -1,6 +1,5 @@
 import type { AuthUser, IWorkspaceService, WorkspaceInfo, FileTreeEntry } from '@bevel-software/platform-shared';
 import type { IDiffService } from '../diff/diff.interface.js';
-import type { IKbSeedService } from './kb-seed.interface.js';
 /**
  * Workspaces are per-branch, not per-user (PLAN §3). One on-disk clone per
  * branch name, shared by every user editing that branch — coordination of
@@ -67,21 +66,6 @@ export declare class WorkspaceService implements IWorkspaceService {
      * each other's working tree.
      */
     private readonly inFlightBootstraps;
-    /**
-     * Branches whose clone already got this process's scaffolding top-up.
-     * Per-process on purpose: each boot of a new build re-offers the top-up
-     * once, which is exactly when an upgrade's migrations must run. Cleared
-     * wherever `branchDirs` forgets a branch (delete, failed bootstrap), so a
-     * re-created clone is offered the top-up again rather than judged by the
-     * fate of one that no longer exists.
-     *
-     * `inFlightTopUps` is the concurrency half: membership in the Set is
-     * claimed BEFORE the (slow, file-moving) top-up finishes, so a concurrent
-     * caller that finds the branch claimed must still await the in-flight run
-     * — returning early would hand out a workspace mid-migration.
-     */
-    private readonly toppedUpBranches;
-    private readonly inFlightTopUps;
     /** Per-workspace-dir `git fetch origin` timestamp + in-flight tracker. */
     private readonly lastFetchAt;
     private readonly inFlightFetches;
@@ -90,13 +74,6 @@ export declare class WorkspaceService implements IWorkspaceService {
      * WorkspaceService for path resolution.
      */
     private diffService;
-    /**
-     * Late-bound by the composition root. Awaited once before the first per-branch
-     * clone so the KB remote is guaranteed to carry the protected branches + base
-     * scaffolding — a fresh (or partially-populated) remote is seeded rather than
-     * assumed. Null in tests / setups that pre-provision the remote themselves.
-     */
-    private seedService;
     /**
      * Late-bound by the composition root: notified with the workspace id
      * right after a branch's clone is created. The git layer uses this to
@@ -118,7 +95,6 @@ export declare class WorkspaceService implements IWorkspaceService {
     private readonly kbRepoUrl;
     private readonly gitUsername;
     setDiffService(diffService: IDiffService): void;
-    setSeedService(seedService: IKbSeedService): void;
     setWorkspaceClonedListener(listener: (workspaceId: string) => void): void;
     /** Build git clone args that inject credentials via -c headers so the token never appears in the repo URL. */
     private gitCloneArgs;
@@ -182,17 +158,6 @@ export declare class WorkspaceService implements IWorkspaceService {
      * same keys before it pulls.
      */
     private normalizeCloneTracking;
-    /**
-     * The ONE spelling of the best-effort scaffolding top-up (three call sites:
-     * the restart-survivor path in `getOrCreateForBranch`, and the
-     * already-cloned / fresh-clone paths in `cloneProcessMapForBranch`). Once
-     * per branch per process, and SINGLE-FLIGHT: the branch is claimed in
-     * `toppedUpBranches` before the run starts, so a concurrent caller that
-     * finds it claimed awaits the in-flight run instead of returning a
-     * workspace the migration is still moving files under. Never throws — a
-     * failed top-up costs the upgrade, not the clone.
-     */
-    private topUpScaffolding;
     private cloneProcessMapForBranch;
     getMetadata(workspaceId: string): Promise<WorkspaceInfo | null>;
     /**