@bevel-software/platform-core-backend 0.11.1 → 0.12.0

package/dist/shared/workspace-id.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The branch ↔ workspace-directory naming convention. Workspaces are
+ * per-branch (one on-disk clone per branch name), and the workspace id IS the
+ * URL-encoded branch name — deterministic both ways, so every caller
+ * (backend, frontend, agent) can compute one from the other without a DB
+ * round-trip. Consumed by nearly every module that touches a workspace, so it
+ * lives in `backend/src/shared` rather than inside the workspace module.
+ *
+ * Pure string handling — no IO, no DB.
+ */
+/**
+ * Map a branch name to the directory that contains its workspace clone.
+ * `encodeURIComponent` handles `/` in branch names (e.g. `alice/foo`) by
+ * encoding it to `%2F` — single-segment-safe on every supported filesystem.
+ */
+export declare function workspaceIdForBranch(branch: string): string;
+/**
+ * Map a workspace id back to its branch name. Workspace ids come in from
+ * request paths and from directory names on disk, so malformed input (a lone
+ * `%`, `%` without two hex digits) must not throw — `decodeURIComponent`
+ * would raise a `URIError` that surfaces as an unhandled 500 in every route
+ * that resolves an id. A malformed id can never equal a valid encoding, so
+ * returning it unchanged is safe: it simply names a branch that does not
+ * exist, and the caller's own lookup fails with its normal not-found path.
+ */
+export declare function branchForWorkspaceId(workspaceId: string): string;
+//# sourceMappingURL=workspace-id.d.ts.map

package/dist/shared/workspace-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-id.d.ts","sourceRoot":"","sources":["../../src/shared/workspace-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMhE"}

package/dist/shared/workspace-id.js

@@ -0,0 +1,36 @@
+/**
+ * The branch ↔ workspace-directory naming convention. Workspaces are
+ * per-branch (one on-disk clone per branch name), and the workspace id IS the
+ * URL-encoded branch name — deterministic both ways, so every caller
+ * (backend, frontend, agent) can compute one from the other without a DB
+ * round-trip. Consumed by nearly every module that touches a workspace, so it
+ * lives in `backend/src/shared` rather than inside the workspace module.
+ *
+ * Pure string handling — no IO, no DB.
+ */
+/**
+ * Map a branch name to the directory that contains its workspace clone.
+ * `encodeURIComponent` handles `/` in branch names (e.g. `alice/foo`) by
+ * encoding it to `%2F` — single-segment-safe on every supported filesystem.
+ */
+export function workspaceIdForBranch(branch) {
+    return encodeURIComponent(branch);
+}
+/**
+ * Map a workspace id back to its branch name. Workspace ids come in from
+ * request paths and from directory names on disk, so malformed input (a lone
+ * `%`, `%` without two hex digits) must not throw — `decodeURIComponent`
+ * would raise a `URIError` that surfaces as an unhandled 500 in every route
+ * that resolves an id. A malformed id can never equal a valid encoding, so
+ * returning it unchanged is safe: it simply names a branch that does not
+ * exist, and the caller's own lookup fails with its normal not-found path.
+ */
+export function branchForWorkspaceId(workspaceId) {
+    try {
+        return decodeURIComponent(workspaceId);
+    }
+    catch {
+        return workspaceId;
+    }
+}
+//# sourceMappingURL=workspace-id.js.map

package/dist/shared/workspace-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-id.js","sourceRoot":"","sources":["../../src/shared/workspace-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,9 +26,10 @@
     "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
-    "node": ">=22 <23"
+    "node": ">=22.13 <23"
   },
   "dependencies": {
+    "@kenjiuno/msgreader": "^1.28.0",
     "@mastra/core": "1.35.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@utcp/code-mode": "^1.2.12",
@@ -41,13 +42,17 @@
     "dotenv": "^16.4.0",
     "drizzle-orm": "^0.45.2",
     "express": "^5.1.0",
+    "htmlparser2": "^12.0.0",
     "ignore": "^7.0.5",
     "jsonwebtoken": "^9.0.3",
+    "pdfjs-dist": "^5.4.624",
     "pg": "^8.20.0",
+    "postal-mime": "^3.0.0",
+    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.11.1",
-    "@bevel-software/platform-shared": "0.11.1"
+    "@bevel-software/platform-mcp-core": "0.12.0",
+    "@bevel-software/platform-shared": "0.12.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/create-core-server.ts

@@ -330,7 +330,7 @@ export async function createCoreServer(
     hooks: core.workflowService.hooks,
   };
   registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.accessControl, core.kbDirName, sessionOntologyGate, core.routineWritePolicy, core.sessionSink);
+  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kbDirName, sessionOntologyGate, core.routineWritePolicy, core.sessionSink);
   registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService);
   registerToolManualsTools(core.toolRegistry, toolsRouter, ta, th, core.toolManualService, {
     accessControl: core.accessControl,

package/src/core/create-core-services.ts

@@ -28,6 +28,7 @@ function parseDomainList(raw: string): string[] {
     .filter((d) => d.length > 0);
 }
 import { SpillStore } from '../modules/workspace/spill-store.js';
+import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
@@ -47,13 +48,13 @@ import {
 } from '../modules/secrets-vault/index.js';
 import { GitService } from '../modules/workflow/git/git.service.js';
 import { PullRequestService } from '../modules/workflow/git/pull-request.service.js';
-import { WorkspaceMutex } from '../modules/workflow/git/mutex.js';
+import { WorkspaceMutex } from '../modules/kb-fs/mutex.js';
 import { assertGitVersion } from '../modules/workflow/git/git-version.js';
 import { DiffService } from '../modules/diff/diff.service.js';
 import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
 import { FileLockService } from '../modules/workflow/file-lock.service.js';
 import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
-import { FileChangeNotifier } from '../modules/workflow/file-change-notifier.js';
+import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
 import { SessionOntologyService } from '../modules/workflow/session-ontology.service.js';
@@ -114,6 +115,7 @@ export interface CoreServices {
    */
   kbStartupRunner: KbStartupRunner;
   spillStore: SpillStore;
+  docExtractService: DocExtractService;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
   sessionOntologyService: SessionOntologyService;
@@ -289,6 +291,9 @@ export async function createCoreServices(
   // Shared, workspace-independent store for oversized `call_tool_chain` results,
   // read back via `read_file`. Sibling of `workspacesRoot`, never committed.
   const spillStore = new SpillStore(config.spillRoot);
+  // Office-document/PDF text extraction for `read_file`/`grep`, cached by
+  // content hash beside the workspaces root (see `DocExtractionCache`).
+  const docExtractService = new DocExtractService(config.docExtractCacheRoot);
   // The deployment owner counts as Admin for the two hardcoded `write`
   // rescues (`roles.yaml` and any `access.md`) — the SAME list
   // `AdminAccessService` below is given, so the admin surfaces and the write
@@ -799,6 +804,7 @@ export async function createCoreServices(
     settings,
     kbDirName,
     spillStore,
+    docExtractService,
     accessControl,
     creatorAccess,
     sessionOntologyService,

package/src/core-config.ts

@@ -71,6 +71,13 @@ export class CoreConfig {
    * never committed, best-effort GC'd on write.
    */
   readonly spillRoot: string;
+  /**
+   * Sibling-to-`workspacesRoot` location for the document-extraction cache —
+   * text extracted from office documents/PDFs (`read_file`/`grep`), keyed by
+   * git blob sha. Derived data only: safe to delete at any time, never
+   * committed, size-bounded by the cache itself.
+   */
+  readonly docExtractCacheRoot: string;
   readonly jwtSecret: string;
   /**
    * The deployment's owner. REQUIRED — three separate jobs rest on it, and a
@@ -244,6 +251,8 @@ export class CoreConfig {
     this.workspacesRoot = process.env.WORKSPACES_ROOT || path.resolve(process.cwd(), 'workspaces');
     this.backupsRoot = process.env.BACKUPS_ROOT || path.resolve(this.workspacesRoot, '..', 'backups');
     this.spillRoot = process.env.SPILL_ROOT || path.resolve(this.workspacesRoot, '..', 'tool-chain-spills');
+    this.docExtractCacheRoot =
+      process.env.DOC_EXTRACT_CACHE_ROOT || path.resolve(this.workspacesRoot, '..', 'doc-extract-cache');
     // Required, and checked BEFORE the auth routes it signs for are ever
     // mounted. Empty, the first login attempt fails deep inside the JWT library
     // with a message about a missing key — a boot error naming the variable is

package/src/modules/access/__tests__/access-control.service.test.ts

@@ -5,7 +5,7 @@ import os from 'node:os';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
-import { AccessConfigError } from '../access-errors.js';
+import { AccessConfigError } from '../../access-model/access-errors.js';
 
 const PROCESS_MAP_DIR = 'knowledge-base';
 

package/src/modules/access/__tests__/access-groups.test.ts

@@ -6,8 +6,9 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import { AccessControlService, parseRolesYaml } from '../access-control.service.js';
-import { AccessConfigError } from '../access-errors.js';
+import { AccessControlService } from '../access-control.service.js';
+import { parseRolesYaml } from '../../access-model/access-grammar.js';
+import { AccessConfigError } from '../../access-model/access-errors.js';
 import { addMember, parseRolesModel, emitRolesModel } from '../roles-edit.js';
 
 const execFileAsync = promisify(execFile);
@@ -102,7 +103,7 @@ describe('group files as access principals', () => {
   });
 
   it('validateGroupsFile (the WRITE gate) still refuses blank keys the reader forgives', async () => {
-    const { validateGroupsFile } = await import('../group-files.js');
+    const { validateGroupsFile } = await import('../../access-model/group-files.js');
     // Inside `groups:` — refused via the entry warning (strict gate).
     expect(validateGroupsFile('groups:\n  :\n    - a@x.io\n', 'groups.yaml').ok).toBe(false);
     // At the ROOT — the tolerant reader silently drops this without any
@@ -114,7 +115,7 @@ describe('group files as access principals', () => {
   });
 
   it('parseGroupsFile applies the shared name-safety predicate (warn-and-skip), and the write gate refuses', async () => {
-    const { parseGroupsFile, validateGroupsFile } = await import('../group-files.js');
+    const { parseGroupsFile, validateGroupsFile } = await import('../../access-model/group-files.js');
     // `<`/`>` and control characters pass the YAML subset as plain keys but
     // fail unsafeNameReason — the parser must skip them (other groups keep
     // resolving) and the strict write gate must refuse the whole candidate.
@@ -133,7 +134,7 @@ describe('group files as access principals', () => {
   });
 
   it("parseGroupsFile skips a 'group:'-prefixed member (shapes like an email, but is the ref token)", async () => {
-    const { parseGroupsFile, validateGroupsFile } = await import('../group-files.js');
+    const { parseGroupsFile, validateGroupsFile } = await import('../../access-model/group-files.js');
     // `group:lee@x.io` PASSES the email regex — without the explicit skip it
     // would land as a member "email" nothing can ever log in as.
     const text = 'groups:\n  Team:\n    - group:lee@x.io\n    - real@x.io\n';

package/src/modules/access/__tests__/access-md-format.test.ts

@@ -4,13 +4,13 @@ import path from 'node:path';
 import os from 'node:os';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
 import {
-  AccessControlService,
   accessMdDeclaresBodyRules,
   accessMdSelfEntries,
   parseAccessFile,
-} from '../access-control.service.js';
-import { spliceGrant, spliceRevoke } from '../access-splice.js';
+} from '../../access-model/access-grammar.js';
+import { spliceGrant, spliceRevoke } from '../../access-model/access-splice.js';
 
 /**
  * The two-format `access.md` story:

package/src/modules/access/__tests__/access-mutation.service.test.ts

@@ -6,7 +6,7 @@ import os from 'node:os';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
 import { AccessMutationService, AccessMutationError } from '../access-mutation.service.js';
-import type { Principal } from '../access-splice.js';
+import type { Principal } from '../../access-model/access-splice.js';
 
 const KB = 'knowledge-base';
 const WS = 'ws-mut-1';

package/src/modules/access/__tests__/admin-locked-commit.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 
 import { AdminLockedCommits } from '../admin-locked-commit.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../workflow/workflow.errors.js';
+import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../../shared/domain-errors.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 
 const KB = 'knowledge-base';

package/src/modules/access/__tests__/admin-route-helpers.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 
 import { toHttpError, requireNonEmptyString } from '../admin-route-helpers.js';
-import { WorkflowDomainError } from '../../workflow/workflow.errors.js';
+import { WorkflowDomainError } from '../../../shared/domain-errors.js';
 import { AccessMutationError } from '../access-mutation.service.js';
 
 describe('toHttpError — the shared access-family error shape', () => {

package/src/modules/access/__tests__/roles-admin.service.test.ts

@@ -7,11 +7,11 @@ import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { FileTreeEntry, WorkflowEventPayload } from '@bevel-software/platform-shared';
-import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { AccessControlService } from '../access-control.service.js';
 import { RolesAdminService } from '../roles-admin.service.js';
 import { rewriteRoleTokensInText, findRoleRefsInText } from '../reference-scan.js';
-import { PushNeedsAgentResolutionError } from '../../workflow/workflow.errors.js';
+import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 

package/src/modules/access/__tests__/roles-edit.test.ts

@@ -11,7 +11,7 @@ import {
   renameGroupRefs,
   RolesEditError,
 } from '../roles-edit.js';
-import { parseYamlSubset } from '../access-control.service.js';
+import { parseYamlSubset } from '../../access-model/access-grammar.js';
 
 const BASE = `roles:
   Admin:

package/src/modules/access/__tests__/synced-groups-committer.test.ts

@@ -8,7 +8,7 @@ import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AccessControlService } from '../access-control.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createSyncedGroupsCommitter } from '../synced-groups-committer.js';
-import { PushNeedsAgentResolutionError, WorkflowValidationError } from '../../workflow/workflow.errors.js';
+import { PushNeedsAgentResolutionError, WorkflowValidationError } from '../../../shared/domain-errors.js';
 
 const KB = 'knowledge-base';
 const BOT: AuthUser = { id: 'bot-1', email: 'directory-sync@bevel.local', name: 'Directory Sync Bot' };

package/src/modules/access/__tests__/synced-groups-writer.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { parseGroupsFile } from '../group-files.js';
+import { parseGroupsFile } from '../../access-model/group-files.js';
 import {
   SyncedGroupsWriter,
   renderSyncedGroupsYaml,