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

package/src/modules/workflow/workflow-hooks.ts

@@ -1,101 +1,101 @@
-import type { ValidationReport } from '@bevel-software/platform-shared';
-
-/**
- * Workflow lifecycle hooks — the generic seam that replaced the
- * constructor-injected KB validator (and the core-owned ontology write block).
- * Core code invokes the hooks at fixed lifecycle points; the modules that OWN
- * the behavior (the enterprise kb/kb-graph modules today) register handlers in
- * the composition root, right after `createCoreServices` returns. Core
- * registers none, so a core-only deployment runs every hook point as a no-op.
- *
- * Two hook kinds with deliberately different failure semantics:
- *
- *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
- *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
- *     used to run. A returned report with `mustFix` entries is logged/surfaced
- *     but NEVER blocks the commit, and a hook that throws is caught and logged
- *     (see CLAUDE.md "Validation is advisory"). The signature mirrors the old
- *     `runValidation(workspaceId)` shape so `KbValidatorService` registers
- *     with a one-line adapter.
- *
- *   - `preWrite` — BLOCKING. Runs before a gated agent write (file-write
- *     tools) or a write-capable shell command; a hook that throws REJECTS the
- *     operation (the error propagates to the tool caller). This is where the
- *     enterprise ontology-session block registers; core registers nothing, so
- *     core never blocks (touch TRACKING stays core — see
- *     `session-ontology.gate.ts`).
- */
-
-/** What `GitService` knows at the advisory commit-validation point. */
-export interface CommitValidationContext {
-  workspaceId: string;
-  branch: string;
-  /**
-   * Repo-relative paths the commit will include — the full touched set for
-   * `commit()`, a single element for the one-file `commitFile()` path.
-   */
-  paths: string[];
-}
-
-/**
- * Advisory commit-time validation. Return a report to have the caller log /
- * surface it (or `void` for "nothing to say"). Throwing is tolerated — the
- * caller catches and logs, never blocks the commit.
- */
-export type CommitValidationHook = (
-  ctx: CommitValidationContext,
-) => Promise<ValidationReport | void>;
-
-/**
- * What the pre-write gate knows when it consults the blocking hooks. The core
- * gate has already resolved all skip conditions (boundary flag off, neutral
- * path, non-agent caller, recovery bot, missing session id — see
- * `resolveGatedSession`), so by hook time there is always a session id.
- */
-export type PreWriteContext =
-  /** A path-addressed content write (write_file/edit_file/mkdir/move/copy/unzip…). */
-  | { kind: 'file-write'; sessionId: string; wsPath: string }
-  /** A write-capable operation with no resolvable target path (execute_command). */
-  | { kind: 'shell'; sessionId: string };
-
-/** Blocking pre-write hook: throw to reject the write; return to allow. */
-export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
-
-/**
- * The registry instance. ONE per composition (created in
- * `createCoreServices`, shared by `GitService` and exposed as
- * `WorkflowService.hooks` for the composition root to register against).
- */
-export class WorkflowHooks {
-  private readonly commitValidation: CommitValidationHook[] = [];
-  private readonly preWrite: PreWriteHook[] = [];
-
-  /** Register an advisory commit-time validation hook. */
-  onCommitValidation(hook: CommitValidationHook): void {
-    this.commitValidation.push(hook);
-  }
-
-  /** Register a blocking pre-write hook. */
-  onPreWrite(hook: PreWriteHook): void {
-    this.preWrite.push(hook);
-  }
-
-  /**
-   * The registered commit-validation hooks, for the caller (`GitService`) to
-   * iterate with its own advisory catch-and-log semantics.
-   */
-  commitValidationHooks(): readonly CommitValidationHook[] {
-    return this.commitValidation;
-  }
-
-  /**
-   * Run every blocking pre-write hook in registration order. The first throw
-   * propagates and rejects the write; with no hooks registered (core-only)
-   * this resolves immediately.
-   */
-  async runPreWrite(ctx: PreWriteContext): Promise<void> {
-    for (const hook of this.preWrite) {
-      await hook(ctx);
-    }
-  }
-}
+import type { ValidationReport } from '@bevel-software/platform-shared';
+
+/**
+ * Workflow lifecycle hooks — the generic seam that replaced the
+ * constructor-injected KB validator (and the core-owned ontology write block).
+ * Core code invokes the hooks at fixed lifecycle points; the modules that OWN
+ * the behavior (the enterprise kb/kb-graph modules today) register handlers in
+ * the composition root, right after `createCoreServices` returns. Core
+ * registers none, so a core-only deployment runs every hook point as a no-op.
+ *
+ * Two hook kinds with deliberately different failure semantics:
+ *
+ *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
+ *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
+ *     used to run. A returned report with `mustFix` entries is logged/surfaced
+ *     but NEVER blocks the commit, and a hook that throws is caught and logged
+ *     (see CLAUDE.md "Validation is advisory"). The signature mirrors the old
+ *     `runValidation(workspaceId)` shape so `KbValidatorService` registers
+ *     with a one-line adapter.
+ *
+ *   - `preWrite` — BLOCKING. Runs before a gated agent write (file-write
+ *     tools) or a write-capable shell command; a hook that throws REJECTS the
+ *     operation (the error propagates to the tool caller). This is where the
+ *     enterprise ontology-session block registers; core registers nothing, so
+ *     core never blocks (touch TRACKING stays core — see
+ *     `session-ontology.gate.ts`).
+ */
+
+/** What `GitService` knows at the advisory commit-validation point. */
+export interface CommitValidationContext {
+  workspaceId: string;
+  branch: string;
+  /**
+   * Repo-relative paths the commit will include — the full touched set for
+   * `commit()`, a single element for the one-file `commitFile()` path.
+   */
+  paths: string[];
+}
+
+/**
+ * Advisory commit-time validation. Return a report to have the caller log /
+ * surface it (or `void` for "nothing to say"). Throwing is tolerated — the
+ * caller catches and logs, never blocks the commit.
+ */
+export type CommitValidationHook = (
+  ctx: CommitValidationContext,
+) => Promise<ValidationReport | void>;
+
+/**
+ * What the pre-write gate knows when it consults the blocking hooks. The core
+ * gate has already resolved all skip conditions (boundary flag off, neutral
+ * path, non-agent caller, recovery bot, missing session id — see
+ * `resolveGatedSession`), so by hook time there is always a session id.
+ */
+export type PreWriteContext =
+  /** A path-addressed content write (write_file/edit_file/mkdir/move/copy/unzip…). */
+  | { kind: 'file-write'; sessionId: string; wsPath: string }
+  /** A write-capable operation with no resolvable target path (execute_command). */
+  | { kind: 'shell'; sessionId: string };
+
+/** Blocking pre-write hook: throw to reject the write; return to allow. */
+export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
+
+/**
+ * The registry instance. ONE per composition (created in
+ * `createCoreServices`, shared by `GitService` and exposed as
+ * `WorkflowService.hooks` for the composition root to register against).
+ */
+export class WorkflowHooks {
+  private readonly commitValidation: CommitValidationHook[] = [];
+  private readonly preWrite: PreWriteHook[] = [];
+
+  /** Register an advisory commit-time validation hook. */
+  onCommitValidation(hook: CommitValidationHook): void {
+    this.commitValidation.push(hook);
+  }
+
+  /** Register a blocking pre-write hook. */
+  onPreWrite(hook: PreWriteHook): void {
+    this.preWrite.push(hook);
+  }
+
+  /**
+   * The registered commit-validation hooks, for the caller (`GitService`) to
+   * iterate with its own advisory catch-and-log semantics.
+   */
+  commitValidationHooks(): readonly CommitValidationHook[] {
+    return this.commitValidation;
+  }
+
+  /**
+   * Run every blocking pre-write hook in registration order. The first throw
+   * propagates and rejects the write; with no hooks registered (core-only)
+   * this resolves immediately.
+   */
+  async runPreWrite(ctx: PreWriteContext): Promise<void> {
+    for (const hook of this.preWrite) {
+      await hook(ctx);
+    }
+  }
+}

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

@@ -119,7 +119,7 @@ describe('KbSeedService', () => {
         expect(await exists(path.join(dir, '.gitignore'))).toBe(true);
         // Core's two roots are seeded (kept present via their .gitkeep).
         expect(await exists(path.join(dir, 'KnowledgeBase/.gitkeep'))).toBe(true);
-        expect(await exists(path.join(dir, 'Groups/.gitkeep'))).toBe(true);
+        expect(await exists(path.join(dir, 'Plugins/.gitkeep'))).toBe(true);
         // …and only those two. `Data/`, `Agents/` and `Pipelines/` scaffold an
         // agentic execution layer this platform does not have, so seeding them
         // would hand every operator three empty folders nothing can fill.
@@ -156,7 +156,7 @@ describe('KbSeedService', () => {
         '.bevelignore': 'x',
         '.gitignore': 'x',
         'KnowledgeBase/Real/Knowledge/.gitkeep': '',
-        'Groups/.gitkeep': '',
+        'Plugins/.gitkeep': '',
       });
 
       await makeSeeder(upstream).ensureRemoteSeeded();
@@ -172,7 +172,7 @@ describe('KbSeedService', () => {
         'access.md': 'CUSTOM ACCESS RULES',
         // AGENTS.md / .bevelignore / .gitignore are absent → should be added.
         'KnowledgeBase/Real/Knowledge/.gitkeep': '',
-        'Groups/.gitkeep': '',
+        'Plugins/.gitkeep': '',
       });
 
       // Simulate the app loading the branch: a fresh clone, then top-up on it.
@@ -201,7 +201,7 @@ describe('KbSeedService', () => {
         '.gitignore': '',
         'access.md': 'CUSTOM ACCESS RULES',
         'KnowledgeBase/Real/Knowledge/.gitkeep': '',
-        'Groups/.gitkeep': '',
+        'Plugins/.gitkeep': '',
       });
 
       const repoDir = await checkout(root, upstream, DEFAULT_BRANCH);
@@ -240,7 +240,7 @@ describe('KbSeedService', () => {
         '.gitignore': '',
         'access.md': 'CUSTOM ACCESS RULES',
         'KnowledgeBase/Real/Knowledge/.gitkeep': '',
-        'Groups/.gitkeep': '',
+        'Plugins/.gitkeep': '',
       });
 
       const first = await checkout(root, upstream, DEFAULT_BRANCH);
@@ -254,7 +254,7 @@ describe('KbSeedService', () => {
       const upstream = await seededUpstream(PROTECTED, {
         'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
         'KnowledgeBase/Real/Knowledge/.gitkeep': '',
-        'Groups/.gitkeep': '',
+        'Plugins/.gitkeep': '',
       });
 
       const first = await checkout(root, upstream, DEFAULT_BRANCH);
@@ -270,6 +270,74 @@ describe('KbSeedService', () => {
       expect(after2).toBe(after1);
     });
 
+    it('a note-only migration outcome stages nothing and raises no top-up warning', async () => {
+      const template = await fs.readFile(
+        path.join(__dirname, '../../../../kb-template/AGENTS.md'),
+        'utf8',
+      );
+      const upstream = await seededUpstream(PROTECTED, {
+        'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
+        'access.md': 'x',
+        'AGENTS.md': template,
+        '.bevelignore': 'AGENTS.md\nPlugins/\n',
+        '.gitignore': '',
+        'KnowledgeBase/Real/Knowledge/.gitkeep': '',
+        'Plugins/GTM/access.md': 'write:\n  - Admin\n',
+        // An unparsable manifest keeps this manual a `.tool` — its variables
+        // have nowhere to go. The migration NOTES the refusal every run and
+        // changes nothing; staging on the note used to reach `git commit`
+        // with an empty index and warn about it on every boot.
+        'Plugins/GTM/plugin.json': '{ not json at all',
+        'Plugins/GTM/vendor.tool': JSON.stringify({
+          name: 'vendor',
+          type: 'mcp',
+          url: 'https://mcp.vendor.example/mcp',
+          variables: [{ name: 'VENDOR_KEY', scope: 'user' }],
+        }),
+      });
+      const repoDir = await checkout(root, upstream, DEFAULT_BRANCH);
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        await makeSeeder(upstream).topUpWorkspace(repoDir, DEFAULT_BRANCH);
+        expect(warn.mock.calls.flat().join(' ')).not.toMatch(/top-up/i);
+      } finally {
+        warn.mockRestore();
+      }
+      // Only the pre-seed commit — a note is not a change.
+      expect(await headCommitCount(root, upstream, DEFAULT_BRANCH)).toBe(1);
+    });
+
+    it('the root rename rewrites the stale .bevelignore rule and commits it along', async () => {
+      const template = await fs.readFile(
+        path.join(__dirname, '../../../../kb-template/AGENTS.md'),
+        'utf8',
+      );
+      const upstream = await seededUpstream(PROTECTED, {
+        'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
+        'access.md': 'x',
+        'AGENTS.md': template,
+        // The pre-rename rule: without the rewrite the migrated KB has a rule
+        // for a root that no longer exists and none for the one that does.
+        '.bevelignore': 'AGENTS.md\nGroups/\n',
+        '.gitignore': '',
+        'KnowledgeBase/Real/Knowledge/.gitkeep': '',
+        'Groups/GTM/access.md': 'write:\n  - Admin\n',
+      });
+      const repoDir = await checkout(root, upstream, DEFAULT_BRANCH);
+      await makeSeeder(upstream).topUpWorkspace(repoDir, DEFAULT_BRANCH);
+
+      // An independent clone proves the rewrite was STAGED (the ignore file
+      // is a repo-root path outside the two roots' pathspecs) and pushed.
+      const dir = await checkout(root, upstream, DEFAULT_BRANCH);
+      expect(await exists(path.join(dir, 'Plugins/GTM/access.md'))).toBe(true);
+      const ignore = await fs.readFile(path.join(dir, '.bevelignore'), 'utf8');
+      expect(ignore.split('\n').map((l) => l.trim())).toContain('Plugins/');
+      expect(ignore).not.toContain('Groups/');
+      expect(ignore).toContain('AGENTS.md');
+      const log = await git(dir, ['log', '-1', '--pretty=%s']);
+      expect(log.trim()).toBe('Move Groups/ to Plugins/ (Agent Plugins layout)');
+    });
+
   });
 
   /**
@@ -292,7 +360,7 @@ describe('KbSeedService', () => {
   describe('the pre-rename ignore file', () => {
     const legacy = (ignore: string): Record<string, string> => ({
       'KnowledgeBase/.gitkeep': '',
-      'Groups/.gitkeep': '',
+      'Plugins/.gitkeep': '',
       'access.md': '---\nwrite:\n  - Admin\n---\n',
       'roles.yaml': 'roles:\n  Admin:\n    - a@example.com\n',
       '.gitignore': '',
@@ -335,7 +403,7 @@ describe('KbSeedService', () => {
       const dir = await checkout(root, upstream, DEFAULT_BRANCH);
       // Core's two, still there.
       expect(await exists(path.join(dir, 'KnowledgeBase/.gitkeep'))).toBe(true);
-      expect(await exists(path.join(dir, 'Groups/.gitkeep'))).toBe(true);
+      expect(await exists(path.join(dir, 'Plugins/.gitkeep'))).toBe(true);
       // …and the three this distribution asked for.
       for (const claimed of ['Data', 'Agents', 'Pipelines']) {
         expect(await exists(path.join(dir, `${claimed}/.gitkeep`))).toBe(true);
@@ -379,7 +447,7 @@ describe('KbSeedService', () => {
     });
 
     /**
-     * A FILE named `Groups` used to satisfy the presence check — `fs.access`
+     * A FILE named `Plugins` used to satisfy the presence check — `fs.access`
      * answers "is there something here?" — so the seeder skipped it, said
      * nothing, and left a knowledge base permanently missing a root it claims
      * to guarantee. Now it says so.
@@ -396,18 +464,18 @@ describe('KbSeedService', () => {
         '.gitignore': '',
         'KnowledgeBase/.gitkeep': '',
         // Not a folder.
-        Groups: 'this is a file, not the groups root',
+        Plugins: 'this is a file, not the plugins root',
       });
       const repoDir = await checkout(root, upstream, DEFAULT_BRANCH);
       const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
       try {
         await makeSeeder(upstream).topUpWorkspace(repoDir, DEFAULT_BRANCH);
-        expect(warn.mock.calls.flat().join(' ')).toMatch(/Groups.*not a directory/);
+        expect(warn.mock.calls.flat().join(' ')).toMatch(/Plugins.*not a directory/);
       } finally {
         warn.mockRestore();
       }
       // …and it did not quietly replace the file either.
-      expect((await fs.lstat(path.join(repoDir, 'Groups'))).isFile()).toBe(true);
+      expect((await fs.lstat(path.join(repoDir, 'Plugins'))).isFile()).toBe(true);
     });
 
     /**
@@ -422,7 +490,7 @@ describe('KbSeedService', () => {
       const upstream = await seededUpstream(PROTECTED, {
         'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
         'KnowledgeBase/Real/Knowledge/.gitkeep': '',
-        'Groups/.gitkeep': '',
+        'Plugins/.gitkeep': '',
       });
       // Branch a suggestion off the default and load it.
       const seed = await checkout(root, upstream, DEFAULT_BRANCH);