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

package/src/modules/access/access-declarations.ts

@@ -1,5 +1,5 @@
 import type { FileTreeEntry, IWorkspaceService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { accessMdPathForFolder } from './access-mutation.service.js';
 import {
   EVERYONE_CANONICAL,
@@ -9,7 +9,7 @@ import {
   parseOwnAccessEntries,
   type ParsedEntry,
   type Verb,
-} from './access-control.service.js';
+} from '../access-model/access-grammar.js';
 
 /**
  * WHERE access rules are DECLARED inside a folder — a read-only inventory, not

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

@@ -41,7 +41,7 @@ import {
   KNOWN_VERBS,
   ROLE_TOKEN_PREFIX,
   canonicalRoleName,
-} from './access-control.service.js';
+} from '../access-model/access-grammar.js';
 import {
   spliceRevoke,
   spliceGrant,
@@ -49,8 +49,8 @@ import {
   AccessSpliceError,
   type Principal,
   type TokenMatch,
-} from './access-splice.js';
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+} from '../access-model/access-splice.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 
 /** Whether the dialog target is a folder (edit folder access.md) or a file (edit node frontmatter). */
 export type TargetKind = 'folder' | 'file';

package/src/modules/access/access.routes.ts

@@ -7,12 +7,12 @@ import type {
   GrantSources,
 } from './access-control.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { branchForWorkspaceId, workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { branchForWorkspaceId, workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { WorkflowService } from '../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
-import { AccessDeniedError } from './access-errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { AccessDeniedError } from '../access-model/access-errors.js';
 import {
   AccessMutationService,
   AccessMutationError,
@@ -24,11 +24,11 @@ import {
   EVERYONE_CANONICAL,
   ROLE_TOKEN_PREFIX,
   type Verb,
-} from './access-control.service.js';
+} from '../access-model/access-grammar.js';
 import { listAccessDeclarationsUnder } from './access-declarations.js';
 import { toHttpError as sharedToHttpError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import { RolesAdminService } from './roles-admin.service.js';
-import type { Principal } from './access-splice.js';
+import type { Principal } from '../access-model/access-splice.js';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
 import '../auth/auth.middleware.js';

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

@@ -47,8 +47,8 @@
 
 import path from 'node:path';
 
-import { LockingFilesystem } from '../workflow/locking-filesystem.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 import type { FileContent } from '@mastra/core/workspace';
 

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

@@ -13,7 +13,7 @@
  */
 
 import type express from 'express';
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 
 /** One error shape for every access-family route. */
 export function toHttpError(

package/src/modules/access/capability-registry.ts

@@ -18,7 +18,7 @@
  * really a group; the roles admin surface flags it with a convert action.
  */
 
-import { ADMIN_CANONICAL, canonicalRoleName } from './access-control.service.js';
+import { ADMIN_CANONICAL, canonicalRoleName } from '../access-model/access-grammar.js';
 
 /** A capability an app surface gates on. Grow this union with the gates. */
 export type Capability =

package/src/modules/access/creator-access.ts

@@ -37,78 +37,15 @@ import path from 'node:path';
 
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { IAccessControl } from './access-control.interface.js';
-import { spliceGrant, type Principal } from './access-splice.js';
-import { isAccessMdPath } from './access-control.service.js';
-import { toKbRelative } from './kb-read-filter.js';
-
-/**
- * How a pending creation gets its creator read grant.
- *   - `seed-access-md`: merge the grant into `wsRelPath` (a new directory's
- *     own `access.md`, workspace-relative) — BEFORE or alongside the creation,
- *     via the caller's own lock+commit machinery. The caller MUST re-read the
- *     file's CURRENT text under its lock and write `apply(current)` ('' when
- *     absent), never a precomputed fresh file: two concurrent creators can
- *     both plan a seed for the same new directory, and a blind overwrite
- *     would silently revoke whichever grant landed first. Skip the write when
- *     `apply` returns the input unchanged, and call `noteAccessFileWritten`
- *     after a write so the resolver cache drops.
- *   - `frontmatter`: run the new file's content through `apply` before
- *     writing it, so the grant lands atomically inside the created file.
- */
-export type CreationGrantPlan =
-  | { kind: 'seed-access-md'; wsRelPath: string; apply: (current: string) => string }
-  | { kind: 'frontmatter'; apply: (content: string) => string };
-
-/** The creator identity a grant is written for. */
-export interface Creator {
-  name: string;
-  email: string;
-}
-
-/**
- * Injection seam for the creation surfaces (routes, lock-aware filesystem,
- * upload apply). Kept as an interface so callers depend on the contract, not
- * the class.
- */
-export interface ICreatorAccess {
-  planForCreate(
-    workspaceId: string,
-    creator: Creator,
-    wsRelPath: string,
-    kind: 'file' | 'dir',
-  ): Promise<CreationGrantPlan | null>;
-
-  grantInExtractedFile(
-    workspaceId: string,
-    creator: Creator,
-    wsRelPath: string,
-  ): Promise<string | null>;
-
-  noteAccessFileWritten(workspaceId: string): void;
-}
-
-/**
- * The splice-safe principal for a creator — exported because plugin
- * provisioning (`PluginProvisionService`) writes the same `Name <email>`
- * entries into the access.md files it seeds, and two spellings of the same
- * person would read as two people.
- */
-export function creatorPrincipal(creator: Creator): Principal {
-  return { kind: 'user', email: creator.email, displayName: safeDisplayName(creator) };
-}
-
-/**
- * `Name <email>`-safe display name: `validatePrincipal` rejects control
- * chars, `<`, `>`, and `#`, so strip those from the user's name and fall
- * back to the email local part (which the email regex already keeps free of
- * `<>`/whitespace) when nothing usable remains.
- */
-function safeDisplayName(creator: Creator): string {
-  const strip = (s: string) =>
-    // eslint-disable-next-line no-control-regex -- same intentional control-char guard as access-splice
-    s.replace(/[<>#\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim();
-  return strip(creator.name) || strip(creator.email.split('@')[0] ?? '') || 'KB user';
-}
+import { spliceGrant, type Principal } from '../access-model/access-splice.js';
+import { isAccessMdPath } from '../access-model/access-grammar.js';
+import { toKbRelative } from '../access-model/kb-read-filter.js';
+import {
+  creatorPrincipal,
+  type CreationGrantPlan,
+  type Creator,
+  type ICreatorAccess,
+} from '../access-model/creator.js';
 
 export class CreatorAccessService implements ICreatorAccess {
   constructor(

package/src/modules/access/groups-admin.routes.ts

@@ -1,7 +1,7 @@
 import express from 'express';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { IAdminAccessService } from '../admin/admin.interface.js';
-import { canonicalRoleName } from './access-control.service.js';
+import { canonicalRoleName } from '../access-model/access-grammar.js';
 import { sendError as sharedSendError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import type { GroupsAdminService } from './groups-admin.service.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation

package/src/modules/access/groups-admin.service.ts

@@ -25,21 +25,20 @@
  *     "repair" by re-creating groups over live bytes).
  */
 
-import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   GROUP_REF_PREFIX,
   canonicalRoleName,
   hasAccessFrontmatterExtension,
-  loadActiveGroups,
-  type GroupsHealth,
-} from './access-control.service.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from './group-files.js';
+} from '../access-model/access-grammar.js';
+import { loadActiveGroups, type GroupsHealth } from './access-control.service.js';
+import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
 import { parseRolesModel, removeGroupRefsEverywhere, renameGroupRefs, isGroupRefMember } from './roles-edit.js';
-import { makeRolesYamlWriteValidator } from './roles-yaml-guard.js';
+import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
 import {
   GroupsEditError,
   parseGroupsModel,

package/src/modules/access/groups-edit.ts

@@ -20,8 +20,8 @@ import {
   EMAIL_REGEX,
   GROUP_REF_PREFIX,
   RESERVED_ROLE_NAMES,
-} from './access-control.service.js';
-import { GROUPS_YAML, parseGroupsFile, unsafeNameReason } from './group-files.js';
+} from '../access-model/access-grammar.js';
+import { GROUPS_YAML, parseGroupsFile, unsafeNameReason } from '../access-model/group-files.js';
 
 /** Bad-input failure when editing groups.yaml. */
 export class GroupsEditError extends Error {

package/src/modules/access/reference-scan.ts

@@ -31,7 +31,7 @@ import {
   isAccessMdPath,
   parseAccessEntry,
   stripComment,
-} from './access-control.service.js';
+} from '../access-model/access-grammar.js';
 
 /**
  * Resolve the [start, end) line range that role rewrites may touch — the YAML

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

@@ -32,20 +32,20 @@
  * sweep the GET pays for).
  */
 
-import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   ADMIN_CANONICAL,
   ROLE_TOKEN_PREFIX,
   canonicalRoleName,
   canonicalEmail,
-  loadActiveGroups,
-} from './access-control.service.js';
-import { makeRolesYamlWriteValidator } from './roles-yaml-guard.js';
-import { renderRolesYaml } from './render-roles-yaml.js';
+} from '../access-model/access-grammar.js';
+import { loadActiveGroups } from './access-control.service.js';
+import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
+import { renderRolesYaml } from '../access-model/render-roles-yaml.js';
 import {
   parseRolesModel,
   deleteRole as editDeleteRole,
@@ -57,7 +57,7 @@ import {
   RolesEditError,
   type EditResult,
 } from './roles-edit.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from './group-files.js';
+import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
 import {
   GroupsEditError,
   assertSafeGroupDisplayName,
@@ -65,7 +65,7 @@ import {
   parseGroupsModel,
 } from './groups-edit.js';
 import { capabilityRoleFor, isLegacyPeopleSetRole } from './capability-registry.js';
-import { GROUP_REF_PREFIX, RESERVED_ROLE_NAMES } from './access-control.service.js';
+import { GROUP_REF_PREFIX, RESERVED_ROLE_NAMES } from '../access-model/access-grammar.js';
 import { AdminLockedCommits } from './admin-locked-commit.js';
 import { KbReferenceScanner } from './reference-scan.js';
 

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

@@ -39,7 +39,7 @@ import {
   canonicalEmail,
   EMAIL_REGEX,
   GROUP_REF_PREFIX,
-} from './access-control.service.js';
+} from '../access-model/access-grammar.js';
 
 /** Bad-input failure when editing roles.yaml (invalid name/email, unknown role). */
 export class RolesEditError extends Error {

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

@@ -1,12 +1,12 @@
 import path from 'node:path';
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { AccessControlService } from './access-control.service.js';
-import { SYNCED_GROUPS_YAML } from './group-files.js';
+import { SYNCED_GROUPS_YAML } from '../access-model/group-files.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
-import { LockingFilesystem } from '../workflow/locking-filesystem.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../workflow/workflow.errors.js';
+import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
 
 /**

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

@@ -4,8 +4,8 @@ import {
   canonicalEmail,
   canonicalRoleName,
   RESERVED_ROLE_NAMES,
-} from './access-control.service.js';
-import { unsafeNameReason } from './group-files.js';
+} from '../access-model/access-grammar.js';
+import { unsafeNameReason } from '../access-model/group-files.js';
 
 /**
  * Locale-independent code-unit comparator. `localeCompare` would make the

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { parseYamlSubset } from '../access-grammar.js';
+import { parseGroupsFile } from '../group-files.js';
+
+describe('parseYamlSubset — inline empty collections', () => {
+  it('reads `key: []` as an empty list, not the scalar "[]"', () => {
+    const res = parseYamlSubset('owner: []');
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value).toEqual({ owner: [] });
+  });
+
+  it('reads `key: {}` as an empty mapping, not the scalar "{}"', () => {
+    const res = parseYamlSubset('groups: {}');
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value).toEqual({ groups: {} });
+  });
+});
+
+describe('parseGroupsFile — empty group sources', () => {
+  it('accepts a bare `groups:` as a valid empty set', () => {
+    const res = parseGroupsFile('groups:\n', 'groups.yaml');
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.groups.size).toBe(0);
+  });
+
+  it('accepts the hand-written `groups: {}` as the same valid empty set', () => {
+    const res = parseGroupsFile('groups: {}\n', 'groups.yaml');
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.groups.size).toBe(0);
+  });
+});