@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/settings/__tests__/deployment-settings.service.test.ts

@@ -4,6 +4,7 @@ import {
   DeploymentSettingsService,
   SettingsValidationError,
   CORE_SETTINGS,
+  LEGACY_LAYOUT_ENV_VARS,
 } from '../deployment-settings.service.js';
 import type { Database } from '../../database/connection.js';
 
@@ -37,7 +38,10 @@ function makeDb() {
 let saved: NodeJS.ProcessEnv;
 beforeEach(() => {
   saved = { ...process.env };
-  for (const def of CORE_SETTINGS) delete process.env[def.envVar];
+  for (const def of CORE_SETTINGS) if (def.envVar) delete process.env[def.envVar];
+  // Retired, and so no longer in the catalogue — but a test about the import
+  // has to start from a process that is not already carrying one.
+  for (const envVar of Object.values(LEGACY_LAYOUT_ENV_VARS)) delete process.env[envVar];
   delete process.env.GITHUB_TOKEN;
 });
 afterEach(() => {
@@ -80,6 +84,41 @@ describe('DeploymentSettingsService — precedence', () => {
   });
 });
 
+describe('DeploymentSettingsService — a blank that means the default', () => {
+  /**
+   * The rule everywhere else: a blank field leaves a setting alone. The Audit
+   * log's retention window is the exception that declares itself — its
+   * readers already treat "unset" as the default, so clearing the field is
+   * the one way back to that default, and a blank saves as a clear.
+   */
+  it('clears a blank-means-default setting on a blank save and leaves every other blank alone', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ auditRetentionDays: '30', kbRepoUrl: 'https://example.com/stored.git' }, null);
+    expect(settings.resolve('auditRetentionDays')).toBe('30');
+
+    await settings.save({ auditRetentionDays: '', kbRepoUrl: '' }, null);
+
+    expect(settings.resolve('auditRetentionDays')).toBe('');
+    expect(settings.sourceOf('auditRetentionDays')).toBe('unset');
+    // The repository address was blank too, and blank still means "leave it".
+    expect(settings.resolve('kbRepoUrl')).toBe('https://example.com/stored.git');
+    expect(rows.some((r) => r.key === 'kbRepoUrl')).toBe(true);
+  });
+
+  it('holds the retention window to the same rule on save as the runtime reader does', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    for (const bad of ['1.5', 'lots', 'ten days']) {
+      await expect(settings.save({ auditRetentionDays: bad }, null)).rejects.toBeInstanceOf(SettingsValidationError);
+    }
+    // A number of days, or zero / negative for "forever" — the reader's rule.
+    for (const ok of ['3650', '0', '-1', '99999']) {
+      await expect(settings.save({ auditRetentionDays: ok }, null)).resolves.toBeDefined();
+    }
+  });
+});
+
 describe('DeploymentSettingsService — secrets', () => {
   it('stores the token as ciphertext and reads it back', async () => {
     const { db, rows } = makeDb();
@@ -151,23 +190,170 @@ describe('DeploymentSettingsService — secrets', () => {
 });
 
 describe('DeploymentSettingsService — KB layout', () => {
-  it('resolves the three roots to their defaults when nothing names them', () => {
+  it('resolves the four names to their defaults when nothing names them', () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);
     expect(settings.resolveKbLayout()).toEqual({
       knowledgeBaseDir: 'KnowledgeBase',
       skillsDir: 'Skills',
       pluginsDir: 'Plugins',
+      agentsFile: 'AGENTS.md',
     });
+    // The pointer is on until someone says otherwise.
+    expect(settings.resolveAgentsFileLink()).toBe(true);
   });
 
-  it('takes a renamed root from the environment first, then the store', async () => {
+  /**
+   * The checkout folder may not be named like a repository root: every path
+   * under that root would then read as the checkout itself. Setup applies a
+   * saved layout to the running process without a restart, so the collision
+   * has to be refused at save time, whichever side of it the operator typed.
+   */
+  it('refuses a layout root named like the checkout folder, and a checkout folder named like a root', async () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);
-    await settings.save({ skillsDir: 'skills', pluginsDir: 'plugins' }, null);
-    expect(settings.resolveKbLayout()).toMatchObject({ skillsDir: 'skills', pluginsDir: 'plugins' });
+    // The knowledge root renamed onto the checkout's default name.
+    await expect(settings.save({ knowledgeBaseDir: 'knowledge-base' }, null)).rejects.toMatchObject({
+      problems: { knowledgeBaseDir: expect.stringContaining('knowledgeBaseDir ("knowledge-base")') },
+    });
+    // The checkout renamed onto the knowledge root's name, in another case.
+    await expect(settings.save({ kbDirName: 'knowledgebase' }, null)).rejects.toMatchObject({
+      problems: { kbDirName: expect.stringContaining('knowledgeBaseDir ("KnowledgeBase")') },
+    });
+    // Nothing was written by either refusal, and an unrelated rename still lands.
+    expect(settings.resolveKbLayout().knowledgeBaseDir).toBe('KnowledgeBase');
+    await expect(settings.save({ kbDirName: 'checkout' }, null)).resolves.toBeTruthy();
+  });
+
+  /**
+   * The layout is entered in the app and nowhere else now. A variable still
+   * sitting in the environment cannot outrank the saved answer, and cannot
+   * lock the field the way an environment-backed setting does.
+   */
+  it('ignores the environment for the four layout names', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ skillsDir: 'skills', pluginsDir: 'plugins', agentsFile: 'HEXIS.md' }, null);
     process.env.KB_SKILLS_DIR = 'capabilities';
-    expect(settings.resolveKbLayout().skillsDir).toBe('capabilities');
+    expect(settings.resolveKbLayout()).toMatchObject({ skillsDir: 'skills', agentsFile: 'HEXIS.md' });
+    expect(settings.sourceOf('skillsDir')).toBe('stored');
+    // Not locked: the field stays editable in the app, and a save of it is
+    // accepted rather than refused as 'set by the environment'.
+    await expect(settings.save({ skillsDir: 'abilities' }, null)).resolves.toBeTruthy();
+    expect(settings.resolveKbLayout().skillsDir).toBe('abilities');
+    // The catalogue no longer advertises a variable for them at all.
+    const described = settings.describe().find((d) => d.key === 'skillsDir');
+    expect(described?.envVar).toBeUndefined();
+    expect(described?.source).toBe('stored');
+  });
+
+  /**
+   * The upgrade path for a deployment that set the roots in its environment:
+   * one import, then the environment is over.
+   */
+  describe('the one-time import of the retired layout variables', () => {
+    it('saves a still-set variable when nothing is saved, and says the variable can go', async () => {
+      const { db, rows } = makeDb();
+      const settings = new DeploymentSettingsService(db, ENC_KEY);
+      await settings.load();
+      process.env.KB_PLUGINS_DIR = 'plugins';
+      const noted = vi.spyOn(console, 'log').mockImplementation(() => {});
+      await settings.importLegacyLayoutEnv();
+      expect(rows).toContainEqual(expect.objectContaining({ key: 'pluginsDir', value: 'plugins' }));
+      // The layout is unchanged by the import — that is the whole point.
+      expect(settings.resolveKbLayout().pluginsDir).toBe('plugins');
+      expect(noted.mock.calls.flat().join(' ')).toMatch(/KB_PLUGINS_DIR[\s\S]*can be removed/);
+      noted.mockRestore();
+    });
+
+    it('keeps a differing saved value and warns that the variable is ignored', async () => {
+      const { db, rows } = makeDb();
+      const settings = new DeploymentSettingsService(db, ENC_KEY);
+      await settings.save({ pluginsDir: 'Plugins' }, null);
+      process.env.KB_PLUGINS_DIR = 'plugins';
+      const warned = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      await settings.importLegacyLayoutEnv();
+      expect(settings.resolveKbLayout().pluginsDir).toBe('Plugins');
+      expect(rows.filter((r) => r.key === 'pluginsDir')).toEqual([
+        expect.objectContaining({ value: 'Plugins' }),
+      ]);
+      expect(warned.mock.calls.flat().join(' ')).toMatch(/KB_PLUGINS_DIR is ignored/);
+      warned.mockRestore();
+    });
+
+    it('does nothing at all when no variable is set', async () => {
+      const { db, rows } = makeDb();
+      const settings = new DeploymentSettingsService(db, ENC_KEY);
+      await settings.load();
+      await settings.importLegacyLayoutEnv();
+      expect(rows).toHaveLength(0);
+      expect(settings.resolveKbLayout()).toMatchObject({ pluginsDir: 'Plugins', skillsDir: 'Skills' });
+    });
+  });
+
+  /**
+   * The guide's file name is saved beside the folders and judged with them:
+   * the four must differ, and a name that is not one markdown file is refused
+   * with the rule it broke.
+   */
+  it('refuses a guide name that is not one markdown file of its own', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    for (const bad of ['guides/HEXIS.md', 'HEXIS.txt', 'CLAUDE.md', 'access.md', 'roles.yaml']) {
+      await expect(settings.save({ agentsFile: bad }, null)).rejects.toBeInstanceOf(
+        SettingsValidationError,
+      );
+    }
+    await expect(settings.save({ agentsFile: 'HEXIS.md' }, null)).resolves.toBeTruthy();
+  });
+
+  it('refuses a guide named after a root folder, from either side of the pair', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    // The plugins folder already in effect, named by the guide alone.
+    await settings.save({ pluginsDir: 'Guide.md' }, null);
+    await expect(settings.save({ agentsFile: 'guide.md' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    // And the other way round, in one batch.
+    await expect(
+      settings.save({ agentsFile: 'HEXIS.md', skillsDir: 'hexis.md' }, null),
+    ).rejects.toBeInstanceOf(SettingsValidationError);
+  });
+
+  it('marks the guide name and its pointer setting as restart-to-apply', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    expect((await settings.save({ agentsFile: 'HEXIS.md' }, null)).restartKeys).toContain('agentsFile');
+    expect((await settings.save({ agentsFileLink: 'false' }, null)).restartKeys).toContain(
+      'agentsFileLink',
+    );
+    expect(settings.resolveAgentsFileLink()).toBe(false);
+  });
+
+  /**
+   * A restart is owed for a CHANGE, and saving what a deployment is already
+   * running on is not one. Both of these settings mean something while unset —
+   * the guide is `AGENTS.md`, the pointer is on — so the first save of that
+   * same answer changes nothing the process would pick up at a restart.
+   */
+  it('owes no restart for saving the value an unset setting already meant', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    // The checkbox arrives ticked, and ticked is what an unset one already is.
+    expect((await settings.save({ agentsFileLink: 'true' }, null)).restartKeys).not.toContain(
+      'agentsFileLink',
+    );
+    expect((await settings.save({ agentsFile: 'AGENTS.md' }, null)).restartKeys).not.toContain(
+      'agentsFile',
+    );
+    expect((await settings.save({ skillsDir: 'Skills' }, null)).restartKeys).not.toContain('skillsDir');
+    // And the setting still reads as it did.
+    expect(settings.resolveAgentsFileLink()).toBe(true);
+    // Turning it off from there IS a change, and still reports one.
+    expect((await settings.save({ agentsFileLink: 'false' }, null)).restartKeys).toContain(
+      'agentsFileLink',
+    );
   });
 
   /**
@@ -310,4 +496,35 @@ describe('DeploymentSettingsService — validation', () => {
     const staged = await settings.save({ kbDirName: 'company-brain' }, null);
     expect(staged.restartRequired).toBe(true);
   });
+
+  /** The OIDC provider reads these on every sign-in, so saving them owes no restart. */
+  it('never asks for a restart for the single sign-on settings', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const sso = await settings.save(
+      {
+        oidcIssuerUrl: 'https://idp.example.com',
+        oidcClientId: 'hexis',
+        oidcClientSecret: 'sso-very-secret',
+        oidcScopes: 'openid email',
+        oidcProviderLabel: 'Company SSO',
+      },
+      null,
+    );
+    expect(sso).toEqual({ restartRequired: false, restartKeys: [] });
+    const changed = await settings.save(
+      { oidcIssuerUrl: 'https://other-idp.example.com', oidcProviderLabel: 'Acme login' },
+      null,
+    );
+    expect(changed.restartRequired).toBe(false);
+    // …while one that genuinely needs it, saved alongside, still says so.
+    const mixed = await settings.save(
+      { oidcClientId: 'hexis-2', allowedEmailDomains: 'example.com' },
+      null,
+    );
+    expect(mixed.restartKeys).toEqual(['allowedEmailDomains']);
+    expect(
+      settings.describe().filter((s) => s.key.startsWith('oidc') && s.restartToApply),
+    ).toEqual([]);
+  });
 });

package/src/modules/settings/__tests__/git-root-folders.test.ts

@@ -0,0 +1,247 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  listRootFolders,
+  pickListingBranch,
+  rootFolderListerFor,
+  type GitRunner,
+} from '../git-root-folders.js';
+import type { IGitRunner } from '../../../shared/git.contract.js';
+
+const LISTING = {
+  url: 'https://example.com/acme/kb.git',
+  branch: 'main',
+  username: 'x-access-token',
+  token: 'ghp_listing_secret',
+};
+
+beforeEach(() => {
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+/** A runner that records every call and answers each with the next scripted outcome. */
+function scripted(outcomes: Array<string | Error>) {
+  const calls: Array<{ args: string[]; env: NodeJS.ProcessEnv; timeout: number }> = [];
+  const run: GitRunner = async (args, options) => {
+    calls.push({ args, ...options });
+    const next = outcomes.shift();
+    if (next instanceof Error) throw next;
+    return { stdout: next ?? '' };
+  };
+  return { run, calls };
+}
+
+function fakeDirs() {
+  const removed: string[] = [];
+  return {
+    removed,
+    makeTempDir: async () => '/scratch/hexis-root-folders-abc',
+    removeDir: async (dir: string) => {
+      removed.push(dir);
+    },
+  };
+}
+
+/**
+ * The listing has to stay cheap on a large repository — one commit, trees
+ * only, nothing checked out — and has to hand git nothing it could read as a
+ * flag or print back as a secret.
+ */
+describe('listRootFolders — the command git is given', () => {
+  it('clones one commit without blobs or a checkout, then lists the root trees', async () => {
+    const { run, calls } = scripted(['', 'KnowledgeBase\0Plugins\0skills\0']);
+    const dirs = fakeDirs();
+    const folders = await listRootFolders(LISTING, { run, ...dirs });
+
+    expect(folders).toEqual(['KnowledgeBase', 'Plugins', 'skills']);
+    expect(calls).toHaveLength(2);
+    const clone = calls[0]!.args;
+    const sub = clone.indexOf('clone');
+    expect(clone.slice(sub)).toEqual([
+      'clone',
+      '--quiet',
+      '--depth=1',
+      '--filter=blob:none',
+      '--no-checkout',
+      '--single-branch',
+      '--branch=main',
+      '--end-of-options',
+      LISTING.url,
+      '/scratch/hexis-root-folders-abc/repo',
+    ]);
+    // Authenticated through the helper, the token itself only in the environment.
+    expect(clone.slice(0, sub).join(' ')).toContain('credential.helper=');
+    expect(JSON.stringify(calls.map((c) => c.args))).not.toContain(LISTING.token);
+    expect(calls[0]!.env.BEVEL_PROBE_TOKEN).toBe(LISTING.token);
+    expect(calls[0]!.env.GIT_TERMINAL_PROMPT).toBe('0');
+
+    expect(calls[1]!.args).toEqual([
+      '-C',
+      '/scratch/hexis-root-folders-abc/repo',
+      'ls-tree',
+      '-d',
+      '-z',
+      '--name-only',
+      'HEAD',
+    ]);
+    expect(dirs.removed).toEqual(['/scratch/hexis-root-folders-abc']);
+  });
+
+  it('falls back to a plain shallow clone when the host cannot filter', async () => {
+    const { run, calls } = scripted([
+      new Error('fatal: server does not support filter'),
+      '',
+      'Skills\0',
+    ]);
+    const dirs = fakeDirs();
+    expect(await listRootFolders(LISTING, { run, ...dirs })).toEqual(['Skills']);
+    expect(calls).toHaveLength(3);
+    expect(calls[0]!.args).toContain('--filter=blob:none');
+    expect(calls[1]!.args).not.toContain('--filter=blob:none');
+    expect(calls[1]!.args).toContain('--depth=1');
+    // The refused attempt's leftovers first, then the whole scratch dir.
+    expect(dirs.removed).toEqual([
+      '/scratch/hexis-root-folders-abc/repo',
+      '/scratch/hexis-root-folders-abc',
+    ]);
+  });
+
+  it('answers null — never a failed connection — and still cleans up when the clone fails', async () => {
+    const { run, calls } = scripted([new Error('fatal: unable to access: ghp_listing_secret')]);
+    const dirs = fakeDirs();
+    expect(await listRootFolders(LISTING, { run, ...dirs })).toBeNull();
+    // Not a filter problem: no second clone.
+    expect(calls).toHaveLength(1);
+    expect(dirs.removed).toEqual(['/scratch/hexis-root-folders-abc']);
+    // What reaches the log has the token scrubbed.
+    expect(JSON.stringify(vi.mocked(console.warn).mock.calls)).not.toContain(LISTING.token);
+  });
+
+  it('logs the host-supplied error text escaped, so it cannot steer the terminal', async () => {
+    const { run } = scripted([new Error('fatal: remote said ›31mred')]);
+    expect(await listRootFolders(LISTING, { run, ...fakeDirs() })).toBeNull();
+    const logged = vi.mocked(console.warn).mock.calls.flat().join(' ');
+    expect(logged).not.toContain('');
+    expect(logged).not.toContain('›');
+    expect(logged).toContain('\\u009b31mred\\u001b[0m');
+  });
+
+  it('answers null and cleans up when the listing itself fails', async () => {
+    const { run } = scripted(['', new Error('fatal: not a tree object')]);
+    const dirs = fakeDirs();
+    expect(await listRootFolders(LISTING, { run, ...dirs })).toBeNull();
+    expect(dirs.removed).toEqual(['/scratch/hexis-root-folders-abc']);
+  });
+
+  it('answers null when there is nowhere to clone into', async () => {
+    const { run, calls } = scripted([]);
+    const folders = await listRootFolders(LISTING, {
+      run,
+      makeTempDir: async () => {
+        throw new Error('ENOSPC');
+      },
+    });
+    expect(folders).toBeNull();
+    expect(calls).toHaveLength(0);
+  });
+
+  it('removes the real scratch directory it made', async () => {
+    let target = '';
+    const run: GitRunner = async (args) => {
+      target = args[args.length - 1]!;
+      mkdirSync(target, { recursive: true });
+      writeFileSync(path.join(target, 'partial'), 'x');
+      throw new Error('fatal: timed out');
+    };
+    expect(await listRootFolders(LISTING, { run })).toBeNull();
+    expect(target).not.toBe('');
+    expect(existsSync(path.dirname(target))).toBe(false);
+  });
+});
+
+/**
+ * The mocked runner pins the argv; this pins that git ACCEPTS it and that
+ * `ls-tree` on a blob-less, checkout-less clone answers with folders only.
+ */
+describe('listRootFolders — against a real repository', () => {
+  let origin = '';
+  afterEach(() => {
+    if (origin) rmSync(origin, { recursive: true, force: true });
+    origin = '';
+  });
+
+  it('lists the top-level folders of the named branch, and not its files', async () => {
+    origin = mkdtempSync(path.join(tmpdir(), 'hexis-root-folders-origin-'));
+    const git = (...args: string[]) =>
+      execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@example.com', ...args], {
+        cwd: origin,
+        stdio: 'pipe',
+      });
+    git('init', '--quiet', '-b', 'main');
+    git('config', 'uploadpack.allowFilter', 'true');
+    for (const dir of ['KnowledgeBase/Team', 'skills/deploy', 'Plugins/GTM']) {
+      mkdirSync(path.join(origin, dir), { recursive: true });
+    }
+    writeFileSync(path.join(origin, 'KnowledgeBase/Team/a.md'), '# a\n');
+    writeFileSync(path.join(origin, 'skills/deploy/SKILL.md'), '# deploy\n');
+    writeFileSync(path.join(origin, 'Plugins/GTM/plugin.json'), '{}\n');
+    writeFileSync(path.join(origin, 'README.md'), '# kb\n');
+    git('add', '-A');
+    git('commit', '--quiet', '-m', 'seed');
+
+    const folders = await listRootFolders({
+      url: pathToFileURL(origin).href,
+      branch: 'main',
+      username: 'x-access-token',
+      token: '',
+    });
+    expect(folders).toEqual(['KnowledgeBase', 'Plugins', 'skills']);
+  });
+});
+
+describe('pickListingBranch', () => {
+  it('prefers what the remote calls its trunk', () => {
+    expect(pickListingBranch('trunk', 'main', ['main', 'trunk'])).toBe('trunk');
+  });
+  it('then the configured branch, when the remote has it', () => {
+    expect(pickListingBranch(null, 'release', ['main', 'release'])).toBe('release');
+    expect(pickListingBranch(null, 'gone', ['develop', 'master'])).toBe('master');
+  });
+  it('then the first branch, and nothing for an empty remote', () => {
+    expect(pickListingBranch(null, null, ['production', 'staging'])).toBe('production');
+    expect(pickListingBranch(null, null, [])).toBeNull();
+  });
+});
+
+describe('rootFolderListerFor — the listing runs through the deployment git port', () => {
+  it('hands every git call to the port with the listing deadline, the token only in the environment', async () => {
+    const calls: Array<{ cwd: string; args: string[]; opts: { env?: NodeJS.ProcessEnv; timeoutMs?: number } }> = [];
+    const outcomes = ['', 'KnowledgeBase\0Plugins\0'];
+    const port: IGitRunner = {
+      defaultTimeoutMs: 1000,
+      run: (async (cwd: string, args: string[], opts: { env?: NodeJS.ProcessEnv; timeoutMs?: number } = {}) => {
+        calls.push({ cwd, args, opts });
+        return { stdout: outcomes.shift() ?? '', stderr: '' };
+      }) as IGitRunner['run'],
+    };
+    const dirs = fakeDirs();
+
+    const folders = await rootFolderListerFor(port)(LISTING, dirs);
+
+    expect(folders).toEqual(['KnowledgeBase', 'Plugins']);
+    expect(calls.map((c) => c.args[c.args.indexOf('clone') === -1 ? 2 : c.args.indexOf('clone')])).toEqual(['clone', 'ls-tree']);
+    for (const c of calls) {
+      // The port's deadline, not a bare execFile timeout that kills git alone.
+      expect(c.opts.timeoutMs).toBe(30_000);
+      expect(c.opts.env?.BEVEL_PROBE_TOKEN).toBe(LISTING.token);
+      expect(JSON.stringify(c.args)).not.toContain(LISTING.token);
+    }
+  });
+});