@bevel-software/platform-core-backend 0.4.1 → 0.5.1

package/migrations/meta/_journal.json

@@ -15,6 +15,20 @@
       "when": 1785534603355,
       "tag": "0001_user_password_hash",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1785934874039,
+      "tag": "0002_user_onboarding_done",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1785943322636,
+      "tag": "0003_deployment_settings",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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",
@@ -22,7 +22,8 @@
     "dist",
     "src",
     "migrations",
-    "kb-template"
+    "kb-template",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
     "node": ">=22 <23"
@@ -45,7 +46,7 @@
     "pg": "^8.20.0",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-shared": "0.4.1"
+    "@bevel-software/platform-shared": "0.5.1"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",
@@ -64,7 +65,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Bevel-Software/skill-and-tool-management.git",
+    "url": "git+https://github.com/Bevel-Software/Hexis.git",
     "directory": "packages/core-backend"
   },
   "publishConfig": {

package/src/__tests__/branch-model.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import {
+  configureBranchModel,
+  isBranchModelConfigured,
+  isProtectedBranch,
+  protectedBranchDisplayName,
+  DEFAULT_BRANCH,
+  PROTECTED_BRANCHES,
+} from '@bevel-software/platform-shared';
+
+const PAIR = {
+  defaultBranch: 'target-company-state',
+  protectedBranches: ['current-company-state', 'target-company-state'],
+};
+
+beforeEach(() => configureBranchModel(PAIR));
+// The model is module-global by design (that is what lets every call site keep
+// importing a binding). Restore it so a suite that runs after this one in the
+// same worker is not left with whatever the last case configured.
+afterEach(() => configureBranchModel(PAIR));
+
+describe('configureBranchModel', () => {
+  it('applies the model to every export', () => {
+    expect(isBranchModelConfigured()).toBe(true);
+    expect(DEFAULT_BRANCH).toBe('target-company-state');
+    expect([...PROTECTED_BRANCHES].sort()).toEqual([
+      'current-company-state',
+      'target-company-state',
+    ]);
+    expect(isProtectedBranch('current-company-state')).toBe(true);
+    expect(isProtectedBranch('someone/draft')).toBe(false);
+  });
+
+  it('accepts the comma/space list the environment supplies', () => {
+    configureBranchModel({ defaultBranch: 'main', protectedBranches: 'main, release' });
+    expect([...PROTECTED_BRANCHES].sort()).toEqual(['main', 'release']);
+  });
+
+  it('derives display names from the slug', () => {
+    expect(protectedBranchDisplayName('target-company-state')).toBe('Target company state');
+    // Unknown names return null so the caller decides between the raw slug and
+    // hiding the affordance — it must not invent a name for a feature branch.
+    expect(protectedBranchDisplayName('someone/draft')).toBeNull();
+  });
+
+  /**
+   * The default branch is where users land and the default propose target. If
+   * it is not itself protected, `isProtectedBranch(DEFAULT_BRANCH)` is false and
+   * every protected-branch guard silently stops applying to the one branch that
+   * needs them most. Refused rather than shipped.
+   */
+  it('refuses a default branch that is not protected', () => {
+    expect(() =>
+      configureBranchModel({ defaultBranch: 'main', protectedBranches: ['release'] }),
+    ).toThrow(/must be one of the protected branches/);
+  });
+
+  it('refuses an empty model rather than defaulting to something plausible', () => {
+    expect(() => configureBranchModel({ defaultBranch: '', protectedBranches: ['main'] })).toThrow(
+      /default branch is required/,
+    );
+    expect(() => configureBranchModel({ defaultBranch: 'main', protectedBranches: [] })).toThrow(
+      /At least one protected branch/,
+    );
+  });
+
+  /**
+   * A rejected model must not half-apply. The previous one stays in force, so a
+   * bad `/api/config` payload cannot leave the app pointing at a branch that is
+   * neither the old value nor the new one.
+   */
+  it('leaves the previous model intact when it refuses a new one', () => {
+    expect(() =>
+      configureBranchModel({ defaultBranch: 'nope', protectedBranches: ['other'] }),
+    ).toThrow();
+    expect(DEFAULT_BRANCH).toBe('target-company-state');
+    expect(isProtectedBranch('target-company-state')).toBe(true);
+  });
+});

package/src/__tests__/core-config.admin.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { CoreConfig } from '../core-config.js';
+
+/**
+ * The boot contract around the deployment owner.
+ *
+ * `ADMIN_EMAIL` is required outright — it is the always-admin, the initial
+ * Admin written into a freshly seeded `roles.yaml`, and half the bootstrap
+ * credential. A deployment without one cannot be administered at all, so
+ * refusing to boot beats booting into something nobody can get into.
+ *
+ * `ADMIN_PASSWORD` is required only while password login is ENABLED. An
+ * SSO-only deployment would otherwise have to hold a shared password the
+ * server is configured to reject — an unused credential someone still has to
+ * store and rotate.
+ */
+const REQUIRED = {
+  KB_REPO_URL: 'https://example.com/org/kb.git',
+  ADMIN_EMAIL: 'root@example.com',
+  ADMIN_PASSWORD: 'sup3r-secret',
+  // The other two boot requirements, so a case about the admin pair fails for
+  // the reason it is testing rather than for a missing neighbour.
+  JWT_SECRET: 'test-jwt-secret',
+  SECRETS_ENC_KEY: 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=',
+};
+
+let saved: NodeJS.ProcessEnv;
+
+beforeEach(() => {
+  saved = { ...process.env };
+  // A clean slate for the keys under test; anything else the constructor reads
+  // has a default or is supplied by REQUIRED.
+  for (const key of [
+    'ADMIN_EMAIL',
+    'ADMIN_PASSWORD',
+    'LOGIN_PASSWORD',
+    'SEED_ADMIN_EMAILS',
+    'JWT_SECRET',
+    'SECRETS_ENC_KEY',
+    'CONNECTOR_CONFIG_ENC_KEY',
+    'SHAREPOINT_TOKEN_ENC_KEY',
+  ]) {
+    delete process.env[key];
+  }
+  Object.assign(process.env, REQUIRED);
+});
+
+afterEach(() => {
+  process.env = saved;
+});
+
+describe('CoreConfig — the deployment owner', () => {
+  it('refuses to boot without ADMIN_EMAIL', () => {
+    delete process.env.ADMIN_EMAIL;
+    expect(() => new CoreConfig()).toThrow(/ADMIN_EMAIL is required/);
+  });
+
+  it('refuses a malformed ADMIN_EMAIL rather than seeding a broken roles.yaml', () => {
+    process.env.ADMIN_EMAIL = 'not-an-email';
+    expect(() => new CoreConfig()).toThrow(/not a valid email/);
+  });
+
+  it('requires ADMIN_PASSWORD while password login is enabled', () => {
+    delete process.env.ADMIN_PASSWORD;
+    expect(() => new CoreConfig()).toThrow(/ADMIN_PASSWORD is required/);
+  });
+
+  it('does NOT require ADMIN_PASSWORD on an SSO-only deployment', () => {
+    delete process.env.ADMIN_PASSWORD;
+    process.env.LOGIN_PASSWORD = 'false';
+    const config = new CoreConfig();
+    expect(config.loginPasswordEnabled).toBe(false);
+    expect(config.adminPassword).toBe('');
+    // The identity is still there — "there is always an identifiable admin"
+    // holds whether or not a password exists.
+    expect(config.adminEmail).toBe('root@example.com');
+  });
+
+  it('normalizes the owner address, since it is matched against sign-in emails', () => {
+    process.env.ADMIN_EMAIL = '  Root@Example.COM  ';
+    expect(new CoreConfig().adminEmail).toBe('root@example.com');
+  });
+
+  /**
+   * Both sign what the deployment hands out — sessions, and the git credential
+   * the setup screen stores. Unset, the failure used to surface at the first
+   * login or the last step of first-run setup; a boot error naming the variable
+   * is the same information, much earlier.
+   */
+  it('refuses to boot without JWT_SECRET', () => {
+    delete process.env.JWT_SECRET;
+    expect(() => new CoreConfig()).toThrow(/JWT_SECRET is required/);
+  });
+
+  it('refuses to boot without SECRETS_ENC_KEY', () => {
+    delete process.env.SECRETS_ENC_KEY;
+    expect(() => new CoreConfig()).toThrow(/SECRETS_ENC_KEY is required/);
+  });
+
+  it('still accepts the legacy encryption-key names', () => {
+    delete process.env.SECRETS_ENC_KEY;
+    process.env.CONNECTOR_CONFIG_ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
+    // Not just "does not throw": the legacy name has to actually supply the
+    // key, or an existing deployment boots and then cannot decrypt anything.
+    expect(new CoreConfig().secretsEncKey).toBe('kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=');
+  });
+
+  it('ignores a leftover SEED_ADMIN_EMAILS instead of failing on it', () => {
+    // The variable is gone, not renamed. An operator upgrading with a stale
+    // value in their env should boot, not hit an unknown-key error.
+    process.env.SEED_ADMIN_EMAILS = 'someone-else@example.com';
+    expect(() => new CoreConfig()).not.toThrow();
+  });
+});

package/src/__tests__/database-url.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { resolveDatabaseUrl } from '../core-config.js';
+
+/**
+ * The connection string is composed HERE rather than in docker-compose, where
+ * it needed a nested interpolated default that deployment UIs mis-parse. Two
+ * things follow that are worth pinning.
+ */
+describe('resolveDatabaseUrl', () => {
+  it('uses an explicit DATABASE_URL over the parts', () => {
+    expect(
+      resolveDatabaseUrl({
+        DATABASE_URL: 'postgresql://me:pw@managed.example.com:5432/prod',
+        POSTGRES_USER: 'ignored',
+        POSTGRES_HOST: 'db',
+      } as NodeJS.ProcessEnv),
+    ).toBe('postgresql://me:pw@managed.example.com:5432/prod');
+  });
+
+  it('builds from the parts when none is given', () => {
+    expect(
+      resolveDatabaseUrl({
+        POSTGRES_USER: 'alice',
+        POSTGRES_PASSWORD: 's3cret',
+        POSTGRES_DB: 'kb',
+        POSTGRES_HOST: 'db',
+      } as NodeJS.ProcessEnv),
+    ).toBe('postgresql://alice:s3cret@db:5432/kb');
+  });
+
+  /** `localhost` suits `pnpm dev`; compose passes the service name instead. */
+  it('defaults to a local Postgres', () => {
+    expect(resolveDatabaseUrl({} as NodeJS.ProcessEnv)).toBe(
+      'postgresql://bevel:bevel@localhost:5432/bevel',
+    );
+  });
+
+  /**
+   * The reason code beats shell interpolation for this. A password with `@`,
+   * `/` or `:` in it produced an unparseable URL — and the resulting failure
+   * named the host or the database, never the password that broke it.
+   */
+  it('encodes credentials that would otherwise break the URL', () => {
+    const url = resolveDatabaseUrl({
+      POSTGRES_USER: 'user@corp',
+      POSTGRES_PASSWORD: 'p@ss:w/rd',
+      POSTGRES_DB: 'kb',
+      POSTGRES_HOST: 'db',
+    } as NodeJS.ProcessEnv);
+    // Parseable, and every part survives the round trip intact.
+    const parsed = new URL(url);
+    expect(parsed.hostname).toBe('db');
+    expect(decodeURIComponent(parsed.username)).toBe('user@corp');
+    expect(decodeURIComponent(parsed.password)).toBe('p@ss:w/rd');
+    expect(decodeURIComponent(parsed.pathname.slice(1))).toBe('kb');
+  });
+
+  it('honours a non-default port', () => {
+    expect(
+      resolveDatabaseUrl({ POSTGRES_HOST: 'db', POSTGRES_PORT: '6432' } as NodeJS.ProcessEnv),
+    ).toBe('postgresql://bevel:bevel@db:6432/bevel');
+  });
+
+  /** Blank is not a value — an empty variable must not win over the parts. */
+  it('treats a blank DATABASE_URL as absent', () => {
+    expect(
+      resolveDatabaseUrl({ DATABASE_URL: '   ', POSTGRES_HOST: 'db' } as NodeJS.ProcessEnv),
+    ).toBe('postgresql://bevel:bevel@db:5432/bevel');
+  });
+});

package/src/core/core-ports.ts

@@ -76,6 +76,21 @@ export interface CorePorts {
    * construction (participants are only iterated at erasure time).
    */
   erasureParticipants?: IErasureParticipant[];
+  /**
+   * Root folders THIS distribution reserves in the knowledge base, on top of
+   * core's `KnowledgeBase/` + `Groups/`. Core default: `[]`.
+   *
+   * A name here does two things: the seeder guarantees the folder exists on
+   * every branch it tops up, and — because the names are already reserved in
+   * `kb-layout.ts` — the file tree keeps rendering it as its own root instead
+   * of folding it into Knowledge as stray content.
+   *
+   * The folder is created as an empty `<dir>/.gitkeep`, written rather than
+   * copied, so reserving a root does not oblige a distribution to fork the
+   * packaged template. Ship a `KB_TEMPLATE_DIR` of your own when those folders
+   * should arrive carrying READMEs.
+   */
+  kbExtraRootDirs?: readonly string[];
 }
 
 /**

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

@@ -21,6 +21,7 @@ import { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.
 import { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
 import { RECOVERY_BOT_EMAIL } from '../modules/workflow/recovery-bot.js';
 import { registerSkillsTools, createSkillsRoutes } from '../modules/skills/index.js';
+import { createGroupsRoutes } from '../modules/groups/index.js';
 import type { SessionOntologyGate } from '../modules/workspace/session-ontology.gate.js';
 import {
   createSecretsVaultRoutes,
@@ -28,6 +29,8 @@ import {
 } from '../modules/secrets-vault/index.js';
 import { createAdminAccessRoutes } from '../modules/admin/admin-access.routes.js';
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
+import { createSetupRoutes } from '../modules/settings/setup.routes.js';
+import { DEFAULT_BRANCH, PROTECTED_BRANCHES } from '@bevel-software/platform-shared';
 import { GIT_SHA } from '../version.js';
 import type { CoreServices } from './create-core-services.js';
 
@@ -147,6 +150,29 @@ export async function createCoreServer(
     res.json({ status: 'ok', sha: GIT_SHA, timestamp: Date.now() });
   });
 
+  /**
+   * The handful of facts the browser needs BEFORE it can render anything, and
+   * therefore before it can authenticate: the branch model.
+   *
+   * Unauthenticated on purpose. The login screen, the router and every module
+   * that reads `DEFAULT_BRANCH` are loaded before a session exists, so a gated
+   * endpoint could not answer in time. What it discloses is two branch names —
+   * which every change request and every URL already shows to anyone who does
+   * get in — and nothing about the repository they live in.
+   *
+   * This replaces baking the values into the frontend bundle at build time.
+   * One artifact now serves any deployment, and renaming a branch no longer
+   * means a rebuild.
+   */
+  app.get('/api/config', (_req, res) => {
+    res.json({
+      branchModel: {
+        defaultBranch: DEFAULT_BRANCH,
+        protectedBranches: [...PROTECTED_BRANCHES],
+      },
+    });
+  });
+
   // Overlay boot-time side effects (startup reconciles, periodic sweeps).
   await ext.onBoot?.(core);
 
@@ -225,12 +251,12 @@ export async function createCoreServer(
   const sessionOntologyGate = {
     service: core.sessionOntologyService,
     enabled: core.config.ontologySessionBlock,
-    kbDirName: core.config.kbDirName,
+    kbDirName: core.kbDirName,
     recoveryBotEmail: RECOVERY_BOT_EMAIL,
     hooks: core.workflowService.hooks,
   };
   registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.accessControl, core.config.kbDirName, sessionOntologyGate, core.routineWritePolicy, core.sessionSink);
+  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, 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,
@@ -274,8 +300,9 @@ export async function createCoreServer(
     core.workflowService,
     core.eventBus,
     core.accessControl,
-    core.config.kbDirName,
+    core.kbDirName,
     core.creatorAccess,
+    core.adminAccess,
   ));
   // Workflow is the only branches / changes / change-request surface. The
   // former /git/*, /pr/*, /pr/:n/* routes are gone — every consumer goes
@@ -297,7 +324,7 @@ export async function createCoreServer(
     core.authService,
     core.workflowService,
     core.accessControl,
-    core.config.kbDirName,
+    core.kbDirName,
   ));
   app.use('/api', core.authMiddleware, createAccessRoutes(
     core.accessControl,
@@ -306,9 +333,27 @@ export async function createCoreServer(
     core.workflowService,
     core.eventBus,
     core.db,
-    core.config.kbDirName,
+    core.kbDirName,
+  ));
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createSkillsRoutes(core.skillService, core.pendingSkillsService),
+  );
+  // Group enumeration + join requests. Browser-only (JWT), and fail-closed
+  // like every other read surface: groups the caller cannot access (member,
+  // manager, or discoverable via the access.md file's own read grant) are
+  // absent from the list. A join request is a plain change request.
+  app.use('/api', core.authMiddleware, createGroupsRoutes(
+    core.groupIndexService,
+    core.accessControl,
+    core.workflowService,
+    core.workspaceService,
+    core.joinRequestsService,
+    core.groupProvisionService,
+    core.kbDirName,
+    async (req) => (req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null),
   ));
-  app.use('/api', core.authMiddleware, createSkillsRoutes(core.skillService));
   // Admin-status resolver (CORE — see the note in admin-access.routes.ts;
   // the full admin router is an enterprise `ext.authed` extension).
   app.use('/api', core.authMiddleware, createAdminAccessRoutes(core.adminAccess));
@@ -319,6 +364,10 @@ export async function createCoreServer(
     core.adminAccess,
     core.accountErasureService,
   ));
+  // First-run setup. Mounted with the other authed routes but touching NO
+  // workspace — it has to work on a deployment that has no knowledge base yet,
+  // which is the whole reason it exists.
+  app.use('/api', core.authMiddleware, createSetupRoutes(core.settings, core.adminAccess));
   app.use('/api', core.authMiddleware, createToolManualsBrowserRoutes(core.toolManualService));
   app.use('/api', core.authMiddleware, createSecretsVaultRoutes(secretsVaultRoutesDeps));
   // The authed tail of the MCP OAuth flow: /connect calls these to describe