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

package/src/modules/workspace/__tests__/workspace.service.test.ts

@@ -435,6 +435,122 @@ describe('WorkspaceService — clone bootstrap & sibling reference', () => {
     await svc.getOrCreateForBranch('alice/draft');
     expect(cloned).toEqual([workspaceIdForBranch('alice/draft')]);
   });
+
+  // An upgraded deployment REUSES the persistent clone, so a top-up bound to
+  // fresh clones alone never runs a new build's scaffolding or migrations —
+  // the Groups→Plugins rename sat out an upgrade exactly this way. Every boot
+  // must offer the top-up to an existing clone once.
+  it('offers the scaffolding top-up to an existing clone once per process', async () => {
+    const seed = {
+      ensureRemoteSeeded: vi.fn(async () => {}),
+      topUpWorkspace: vi.fn(async () => {}),
+    };
+    const firstBoot = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base');
+    firstBoot.setSeedService(seed);
+    await firstBoot.getOrCreateForBranch('target-company-state');
+    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1); // the fresh clone
+
+    // A new process over the same workspaces dir — the deployed-upgrade case:
+    // the clone exists, and the top-up must still run, once, not per access.
+    const nextBoot = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base');
+    nextBoot.setSeedService(seed);
+    await nextBoot.getOrCreateForBranch('target-company-state');
+    await nextBoot.getOrCreateForBranch('target-company-state');
+    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('WorkspaceService — scaffolding top-up on restart-survivor clones', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+    // The fake `.git` in seedBranchWorkspace makes normalizeCloneTracking's
+    // git calls fail; that path only warns, which is noise here.
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  // The top-up MOVES files (the Groups→Plugins migration runs inside it), so a
+  // caller handed the workspace mid-run reads a tree with both halves missing.
+  it('makes a concurrent opener wait out the in-flight top-up instead of returning mid-migration', async () => {
+    await seedBranchWorkspace(root, 'target-company-state');
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');
+    let release!: () => void;
+    const gate = new Promise<void>((r) => { release = r; });
+    const seed = {
+      ensureRemoteSeeded: vi.fn(async () => {}),
+      topUpWorkspace: vi.fn(() => gate),
+    };
+    svc.setSeedService(seed);
+
+    let aDone = false;
+    let bDone = false;
+    const a = svc.getOrCreateForBranch('target-company-state').then((v) => { aDone = true; return v; });
+    const b = svc.getOrCreateForBranch('target-company-state').then((v) => { bDone = true; return v; });
+    // Wait until the top-up has started (the fake clone makes the preceding
+    // git-config repair fail slowly, so poll rather than sleep), then give
+    // both callers time to settle against the gate.
+    await vi.waitFor(() => expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1));
+    await new Promise((r) => setTimeout(r, 30));
+    // Neither caller has been handed the workspace while the top-up runs —
+    // and the second did not start a rival run.
+    expect(aDone).toBe(false);
+    expect(bDone).toBe(false);
+    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1);
+
+    release();
+    const [infoA, infoB] = await Promise.all([a, b]);
+    expect(infoA.id).toBe(infoB.id);
+  });
+
+  it('re-offers the top-up after deleteWorkspace — the claim died with the clone', async () => {
+    await seedBranchWorkspace(root, 'target-company-state');
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');
+    const seed = {
+      ensureRemoteSeeded: vi.fn(async () => {}),
+      topUpWorkspace: vi.fn(async () => {}),
+    };
+    svc.setSeedService(seed);
+
+    await svc.getOrCreateForBranch('target-company-state');
+    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1);
+
+    await svc.deleteWorkspace(workspaceIdForBranch('target-company-state'));
+    // A later bootstrap re-creates the clone (seeded by hand here); it must
+    // be offered the top-up afresh — the old claim was about a clone that no
+    // longer exists.
+    await seedBranchWorkspace(root, 'target-company-state');
+    await svc.getOrCreateForBranch('target-company-state');
+    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(2);
+  });
+
+  it('re-offers the top-up after the orphan sweep removes the clone — same eviction rule', async () => {
+    await seedBranchWorkspace(root, 'target-company-state');
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');
+    const seed = {
+      ensureRemoteSeeded: vi.fn(async () => {}),
+      topUpWorkspace: vi.fn(async () => {}),
+    };
+    svc.setSeedService(seed);
+
+    await svc.getOrCreateForBranch('target-company-state');
+    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1);
+
+    // The branch vanishes from the known set; the sweep reclaims its clone.
+    const { removed } = await svc.sweepOrphanedWorkspaces([]);
+    expect(removed).toContain(workspaceIdForBranch('target-company-state'));
+
+    // Re-created before any restart: the fresh clone must still get its one
+    // top-up — the claim died with the directory the sweep removed.
+    await seedBranchWorkspace(root, 'target-company-state');
+    await svc.getOrCreateForBranch('target-company-state');
+    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(2);
+  });
 });
 
 describe('WorkspaceService.readAllKbFiles', () => {

package/src/modules/workspace/bevel-ignore.ts

@@ -1,66 +1,66 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import ignore, { type Ignore } from 'ignore';
-
-/**
- * The ignore file's own name. Exported because the file-tree filter hides it
- * from non-admins, and both places must agree on the spelling.
- */
-export const IGNORE_FILENAME = '.bevelignore';
-
-/** One .bevelignore file's rules, scoped to the directory it lives in. */
-interface IgnoreLayer {
-  /** Absolute path of the directory where the .bevelignore lives. */
-  readonly root: string;
-  readonly matcher: Ignore;
-}
-
-/**
- * A hierarchical stack of `.bevelignore` rule sets.
- *
- * Each `.bevelignore` file applies to paths beneath the directory it lives in,
- * using standard gitignore syntax (negations, `**`, directory-only patterns, anchoring).
- * Deeper files combine with — and can override — rules from shallower files,
- * mirroring how git layers `.gitignore` files.
- */
-export class BevelIgnoreStack {
-  private constructor(private readonly layers: readonly IgnoreLayer[]) {}
-
-  static empty(): BevelIgnoreStack {
-    return new BevelIgnoreStack([]);
-  }
-
-  /**
-   * Return a new stack that additionally includes a `.bevelignore` from `dir`
-   * (if present). If no `.bevelignore` exists in `dir`, returns this stack unchanged.
-   */
-  async extendedWith(dir: string): Promise<BevelIgnoreStack> {
-    const file = path.join(dir, IGNORE_FILENAME);
-    let contents: string;
-    try {
-      contents = await fs.readFile(file, 'utf-8');
-    } catch {
-      return this;
-    }
-    const matcher = ignore().add(contents);
-    return new BevelIgnoreStack([...this.layers, { root: dir, matcher }]);
-  }
-
-  /**
-   * Whether the given entry should be hidden from the file tree.
-   * @param absolutePath absolute path of the entry
-   * @param isDirectory needed because gitignore patterns ending in `/` match directories only
-   */
-  isIgnored(absolutePath: string, isDirectory: boolean): boolean {
-    for (const layer of this.layers) {
-      const rel = path.relative(layer.root, absolutePath).replace(/\\/g, '/');
-      // Skip entries that aren't under this layer's root (shouldn't happen in normal
-      // recursion, but guards against absolute-path quirks on Windows).
-      if (!rel || rel.startsWith('..')) continue;
-      // Append trailing slash for directories so `foo/`-style rules match correctly.
-      const probe = isDirectory ? `${rel}/` : rel;
-      if (layer.matcher.ignores(probe)) return true;
-    }
-    return false;
-  }
-}
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import ignore, { type Ignore } from 'ignore';
+
+/**
+ * The ignore file's own name. Exported because the file-tree filter hides it
+ * from non-admins, and both places must agree on the spelling.
+ */
+export const IGNORE_FILENAME = '.bevelignore';
+
+/** One .bevelignore file's rules, scoped to the directory it lives in. */
+interface IgnoreLayer {
+  /** Absolute path of the directory where the .bevelignore lives. */
+  readonly root: string;
+  readonly matcher: Ignore;
+}
+
+/**
+ * A hierarchical stack of `.bevelignore` rule sets.
+ *
+ * Each `.bevelignore` file applies to paths beneath the directory it lives in,
+ * using standard gitignore syntax (negations, `**`, directory-only patterns, anchoring).
+ * Deeper files combine with — and can override — rules from shallower files,
+ * mirroring how git layers `.gitignore` files.
+ */
+export class BevelIgnoreStack {
+  private constructor(private readonly layers: readonly IgnoreLayer[]) {}
+
+  static empty(): BevelIgnoreStack {
+    return new BevelIgnoreStack([]);
+  }
+
+  /**
+   * Return a new stack that additionally includes a `.bevelignore` from `dir`
+   * (if present). If no `.bevelignore` exists in `dir`, returns this stack unchanged.
+   */
+  async extendedWith(dir: string): Promise<BevelIgnoreStack> {
+    const file = path.join(dir, IGNORE_FILENAME);
+    let contents: string;
+    try {
+      contents = await fs.readFile(file, 'utf-8');
+    } catch {
+      return this;
+    }
+    const matcher = ignore().add(contents);
+    return new BevelIgnoreStack([...this.layers, { root: dir, matcher }]);
+  }
+
+  /**
+   * Whether the given entry should be hidden from the file tree.
+   * @param absolutePath absolute path of the entry
+   * @param isDirectory needed because gitignore patterns ending in `/` match directories only
+   */
+  isIgnored(absolutePath: string, isDirectory: boolean): boolean {
+    for (const layer of this.layers) {
+      const rel = path.relative(layer.root, absolutePath).replace(/\\/g, '/');
+      // Skip entries that aren't under this layer's root (shouldn't happen in normal
+      // recursion, but guards against absolute-path quirks on Windows).
+      if (!rel || rel.startsWith('..')) continue;
+      // Append trailing slash for directories so `foo/`-style rules match correctly.
+      const probe = isDirectory ? `${rel}/` : rel;
+      if (layer.matcher.ignores(probe)) return true;
+    }
+    return false;
+  }
+}

package/src/modules/workspace/kb-seed.service.ts

@@ -3,8 +3,9 @@ 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, GROUPS_DIR } from '@bevel-software/platform-shared';
+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';
 import type { IKbSeedService } from './kb-seed.interface.js';
 
 const execFileAsync = promisify(execFile);
@@ -36,7 +37,7 @@ const BOT_EMAIL = 'bevel-workflow@bevel.software';
 const REQUIRED_FILES: readonly string[] = ['access.md', 'AGENTS.md', '.bevelignore', '.gitignore'];
 
 /**
- * The two roots CORE gives a knowledge base: the ontologies, and the groups
+ * 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
@@ -47,7 +48,7 @@ const REQUIRED_FILES: readonly string[] = ['access.md', 'AGENTS.md', '.beveligno
  * 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: readonly string[] = [KNOWLEDGE_BASE_DIR, GROUPS_DIR];
+export const CORE_REQUIRED_DIRS: readonly string[] = [KNOWLEDGE_BASE_DIR, PLUGINS_DIR];
 
 /**
  * A reserved root must be ONE path segment — `Data`, not `Data/x`, `../x` or
@@ -234,6 +235,29 @@ export class KbSeedService implements IKbSeedService {
     if (!this.protectedBranches().includes(branch)) return;
     try {
       const added: string[] = [];
+      // 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);
@@ -284,9 +308,14 @@ export class KbSeedService implements IKbSeedService {
       // 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);
-      await this.git(repoDir, ['add', '--', ...added]);
-      const message =
-        agentsRefreshed && added.length === 1
+      // `-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]);
@@ -427,7 +456,7 @@ export class KbSeedService implements IKbSeedService {
    * 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 `Groups/AGENTS.md`
+   * 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.
    */
@@ -467,10 +496,10 @@ export class KbSeedService implements IKbSeedService {
     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 `Groups` — and the old skip-if-present
+      // 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 `Groups` is not a KB
+      // `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);