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

package/src/modules/plugins/plugins.routes.ts

@@ -13,6 +13,8 @@ import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { pluginsWorkspaceId } from './plugins.service.js';
 import { PluginProvisionError, type PluginProvisionService } from './plugin-provision.service.js';
+import { PluginLinkError, type PluginLinksService } from './plugin-links.service.js';
+import { PluginRenameError, type PluginRenameService } from './plugin-rename.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
 import type {
   PluginCatalogEntry,
@@ -61,13 +63,121 @@ export function createPluginsRoutes(
   provision: PluginProvisionService,
   kbDirName: string,
   resolveUser: (req: express.Request) => Promise<AuthUser | null>,
+  /** Optional: a host without the link machinery simply has no link routes. */
+  links?: PluginLinksService,
+  /** Optional: a host without it has no rename route. */
+  rename?: PluginRenameService,
 ): express.Router {
   const router = express.Router();
 
+  /**
+   * Rename a plugin — its identifier, its display name, or both. The
+   * MANAGER's verb (write on the folder's access.md, the gate linking uses).
+   * An identifier change rewrites every grant naming the old identifier in
+   * the same commit; see `PluginRenameService`.
+   *
+   *   PATCH /api/plugins/:name  { name?, displayName? }  → { name, displayName, rewritten }
+   */
+  if (rename) {
+    router.patch('/plugins/:name', async (req, res) => {
+      if (!req.userEmail) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const user = await resolveUser(req);
+      if (!user) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const body = (req.body ?? {}) as { name?: unknown; displayName?: unknown };
+      try {
+        res.json(await rename.rename(user, String(req.params.name), { name: body.name, displayName: body.displayName }));
+      } catch (err) {
+        if (err instanceof PluginRenameError) {
+          res.status(err.status).json({ error: err.message, ...err.payload });
+          return;
+        }
+        if (err instanceof WorkflowDomainError) {
+          res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+          return;
+        }
+        console.error('[plugins] rename failed:', err);
+        res.status(500).json({ error: 'Failed to rename the plugin' });
+      }
+    });
+  }
+
+  /**
+   * Linking shared skills — see `PluginLinksService` for the two-sided write.
+   *
+   *   POST   /api/plugins/:name/links          { skillPath }  → { root, skills }
+   *   DELETE /api/plugins/:name/links?skillPath=              → { root, revoked }
+   *   POST   /api/plugins/:name/links/repair   { skillPath }  → { root }
+   *
+   * Refusals carry a `kind` the UI branches on — `needs-skill-write` (409) is
+   * the one that becomes "request write access".
+   */
+  if (links) {
+    const linkOp = async (
+      req: express.Request,
+      res: express.Response,
+      op: (user: AuthUser, plugin: string, skillPath: string) => Promise<unknown>,
+      skillPathOf: (req: express.Request) => unknown,
+    ) => {
+      if (!req.userEmail) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const user = await resolveUser(req);
+      if (!user) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const skillPath = skillPathOf(req);
+      if (typeof skillPath !== 'string' || !skillPath.trim()) {
+        res.status(400).json({ error: 'skillPath is required' });
+        return;
+      }
+      try {
+        res.json(await op(user, String(req.params.name), skillPath));
+      } catch (err) {
+        if (err instanceof PluginLinkError) {
+          res.status(err.status).json({ error: err.message, ...err.payload });
+          return;
+        }
+        if (err instanceof WorkflowDomainError) {
+          res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+          return;
+        }
+        console.error('[plugins] link operation failed:', err);
+        res.status(500).json({ error: 'Failed to update the plugin\'s links' });
+      }
+    };
+    const bodyPath = (req: express.Request) => ((req.body ?? {}) as { skillPath?: unknown }).skillPath;
+    router.post('/plugins/:name/links', (req, res) => linkOp(req, res, (u, p, s) => links.link(u, p, s), bodyPath));
+    router.post('/plugins/:name/links/repair', (req, res) =>
+      linkOp(req, res, (u, p, s) => links.repair(u, p, s), bodyPath),
+    );
+    router.delete('/plugins/:name/links', (req, res) =>
+      linkOp(req, res, (u, p, s) => links.unlink(u, p, s), (r) => r.query.skillPath),
+    );
+  }
+
   /** The folder-chain probe for MEMBERSHIP — the folder itself. */
   const memberProbe = (folder: string) => folder;
   /** The FILE probe for discovery/management — the folder's access.md. */
   const accessMdOf = (folder: string) => `${folder}/access.md`;
+  /** A plugin folder's path BELOW the plugins root: `GTM`, or `teams/deep`. */
+  const folderBelowRoot = (folder: string) => folder.slice(folder.indexOf('/') + 1);
+  /**
+   * What a join request is keyed by: the plugin's primary FOLDER path below
+   * the root, not its identity. The request writes into that folder's rules;
+   * a top-level folder keys exactly as every join branch already on a remote
+   * was cut (its name), a nested one by its whole path, so two plugins whose
+   * folders share a basename never share a branch; and a rename of the
+   * identity moves no folder, so it orphans no open request.
+   */
+  const joinKeyOf = (g: PluginCatalogEntry) => folderBelowRoot(g.folders[0]);
 
   const probesFor = (plugins: PluginCatalogEntry[]): string[] => [
     ...new Set(plugins.flatMap((g) => g.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]))),
@@ -122,15 +232,18 @@ export function createPluginsRoutes(
         const owner = any(owned, g, memberProbe);
         const discoverable = member || any(readable, g, accessMdOf);
         if (!member && !manager && !discoverable) continue; // absent — fail closed
-        const joinCr = member ? null : openJoinCr(mine, email, g.name);
+        const joinCr = member ? null : openJoinCr(mine, email, joinKeyOf(g));
         plugins.push({
           name: g.name,
+          displayName: g.displayName,
           folders: g.folders,
           canRead: member,
           canWrite: manager,
           isOwner: owner,
+          linksAreManaged: g.linksAreManaged,
           skillCount: g.skillCount,
           toolCount: g.toolCount,
+          brokenLinks: g.brokenLinks,
           owners: g.owners,
           writers: g.writers,
           readers: g.readers,
@@ -230,7 +343,7 @@ export function createPluginsRoutes(
         res.status(401).json({ error: 'Unauthenticated' });
         return;
       }
-      // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+      // By identity — the manifest name the catalog keys on.
       const plugin = (await pluginIndex.catalog()).find((g) => g.name === req.params.name);
       const wsId = pluginsWorkspaceId();
       const ownerVerdicts = plugin
@@ -242,7 +355,10 @@ export function createPluginsRoutes(
         res.status(404).json({ error: 'Unknown plugin', kind: 'unknown-plugin' });
         return;
       }
-      await provision.deletePlugin(user, plugin.name);
+      // Provisioning works on FOLDERS (it created one); the identity only
+      // found the plugin. The whole path below the root, so a nested plugin
+      // is deleted where it is.
+      await provision.deletePlugin(user, folderBelowRoot(plugin.folders[0]));
       pluginIndex.invalidate();
       res.json({ ok: true });
     } catch (err) {
@@ -268,7 +384,7 @@ export function createPluginsRoutes(
         return;
       }
       const catalog = await pluginIndex.catalog();
-      // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+      // By identity — the manifest name the catalog keys on.
       const plugin = catalog.find((g) => g.name === req.params.name);
       const wsId = pluginsWorkspaceId();
       // Same ANY-folder shape `GET /plugins` resolves with, so a plugin can
@@ -298,8 +414,8 @@ export function createPluginsRoutes(
       // expects.
       const folder = plugin.folders[0];
 
-      const branch = joinBranchFor(email, plugin.name);
-      const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, plugin.name);
+      const branch = joinBranchFor(email, joinKeyOf(plugin));
+      const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, joinKeyOf(plugin));
       if (existing) {
         res.json({ ok: true, number: existing.number });
         return;
@@ -323,14 +439,15 @@ export function createPluginsRoutes(
       );
       if (spliced.changed) {
         await workspaceService.writeFile(ws.id, accessPath, spliced.text);
-        await workflow.commitChanges(ws.id, user, `Request access to ${plugin.name}`);
+        await workflow.commitChanges(ws.id, user, `Request access to ${plugin.displayName}`);
       }
       const detail = await workflow.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
         targetBranch: DEFAULT_BRANCH,
-        title: `Join request: ${plugin.name}`,
+        // People read these: the display name, not the identifier.
+        title: `Join request: ${plugin.displayName}`,
         description:
-          `${user.name} asked to join ${plugin.name}. A manager of the plugin accepts by ` +
+          `${user.name} asked to join ${plugin.displayName}. A manager of the plugin accepts by ` +
           `granting the access this branch proposes; the request closes itself once ` +
           `every proposal has landed.`,
       });
@@ -392,7 +509,7 @@ export function createPluginsRoutes(
       if (!ctx) return;
       const crs = await workflow.listChangeRequests();
       res.json({
-        requests: await joinRequests.list(ctx.plugin.name, ctx.folder, crs, ctx.user),
+        requests: await joinRequests.list(joinKeyOf(ctx.plugin), ctx.folder, crs, ctx.user),
       });
     } catch (err) {
       console.error('[plugins] failed to list join requests:', err);
@@ -422,7 +539,7 @@ export function createPluginsRoutes(
         res.status(404).json({ error: 'Not found' });
         return;
       }
-      res.json({ closed: await joinRequests.reconcile(ctx.plugin.name, ctx.folder, cr, ctx.user) });
+      res.json({ closed: await joinRequests.reconcile(joinKeyOf(ctx.plugin), ctx.folder, cr, ctx.user) });
     } catch (err) {
       console.error('[plugins] failed to reconcile a join request:', err);
       res.status(500).json({ error: 'Failed to update the request' });

package/src/modules/plugins/plugins.service.ts

@@ -1,11 +1,6 @@
 import path from 'node:path';
-import fs from 'node:fs/promises';
-import type { Dirent } from 'node:fs';
 import {
   DEFAULT_BRANCH,
-  PLUGINS_DIR,
-  pluginOfPath,
-  isPersonalPluginFolder,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
@@ -14,6 +9,9 @@ import type { ISkillService } from '../skills/skills.contract.js';
 import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
 import type { PluginCatalogEntry, IPluginIndexService } from './plugins.contract.js';
+import type { PluginLinkIndex } from './plugin-links.js';
+import type { PluginSource } from './discovery/plugin-source.js';
+import { KbPluginSource } from './discovery/kb-plugin-source.js';
 
 const CACHE_TTL_MS = 60_000;
 
@@ -52,6 +50,14 @@ export class PluginIndexService implements IPluginIndexService {
     private readonly toolManualService: IToolManualService,
     private readonly kbDirName: string,
     now: () => number = Date.now,
+    /**
+     * The link index, when the deployment has one: a plugin's skill count is
+     * then inline PLUS linked. Optional so hosts composing their own service
+     * set (and older tests) keep the inline-only count.
+     */
+    private readonly links?: PluginLinkIndex,
+    /** Where plugins come from — native manifests unless a dialect is configured. */
+    private readonly source: PluginSource = new KbPluginSource(),
   ) {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
@@ -63,6 +69,9 @@ export class PluginIndexService implements IPluginIndexService {
   async catalog(): Promise<PluginCatalogEntry[]> {
     const cached = this.cache.get();
     if (cached) return cached;
+    // See `TtlCache.begin`: taken before the read so an `invalidate()` that
+    // lands mid-build discards this result instead of being overwritten by it.
+    const token = this.cache.begin();
     const entries = await this.build();
     // A failed scan and a KB with genuinely no plugin folders both serve `[]`,
     // but only the second is a fact worth holding for the TTL. Caching the
@@ -72,7 +81,7 @@ export class PluginIndexService implements IPluginIndexService {
     // never arrive in that window. So a degraded read is served, not stored,
     // and the next caller retries.
     if (entries === null) return [];
-    this.cache.set(entries);
+    this.cache.set(entries, token);
     return entries;
   }
 
@@ -94,12 +103,13 @@ export class PluginIndexService implements IPluginIndexService {
       const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
       const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
-      const folders = await this.scanFolders(kbRoot);
-      if (folders.size === 0) return [];
+      const scanned = await this.scanFolders(kbRoot);
+      if (scanned.size === 0) return [];
+      const folders = new Map([...scanned].map(([name, p]) => [name, p.folders]));
 
-      const [skillCounts, toolCounts] = await Promise.all([
-        this.countSkills(),
-        this.countTools(),
+      const [{ skillCounts, brokenLinkCounts }, toolCounts] = await Promise.all([
+        this.countThroughLinks(folders),
+        this.countTools(folders),
       ]);
 
       const entries: PluginCatalogEntry[] = [];
@@ -113,9 +123,12 @@ export class PluginIndexService implements IPluginIndexService {
         ]);
         entries.push({
           name,
+          displayName: scanned.get(name)?.displayName ?? name,
           folders: pluginFolders,
+          linksAreManaged: scanned.get(name)?.linksAreManaged ?? false,
           skillCount: skillCounts.get(name) ?? 0,
           toolCount: toolCounts.get(name) ?? 0,
+          brokenLinks: brokenLinkCounts.get(name) ?? 0,
           owners,
           writers,
           readers,
@@ -130,59 +143,99 @@ export class PluginIndexService implements IPluginIndexService {
     }
   }
 
-  /** name → repo-relative plugin folder (always a single-element list). */
-  private async scanFolders(kbRoot: string): Promise<Map<string, string[]>> {
-    const byName = new Map<string, string[]>();
-    let children: Dirent[];
-    try {
-      children = await fs.readdir(path.join(kbRoot, PLUGINS_DIR), { withFileTypes: true });
-    } catch {
-      return byName; // a KB without a `Plugins/` root simply has no plugins
+  /**
+   * name → repo-relative plugin folder (always a single-element list), from
+   * the configured source. Personal folders live under Plugins/ but are not
+   * plugins: one exists per person, private by construction, and listing them
+   * would put a locked row per employee in everyone's index. `exists` is the
+   * source's existence rule (see `DiscoveredPlugin`) — for native plugins,
+   * the `access.md` the class doc describes.
+   */
+  private async scanFolders(
+    kbRoot: string,
+  ): Promise<Map<string, { folders: string[]; linksAreManaged: boolean; displayName: string }>> {
+    const byName = new Map<string, { folders: string[]; linksAreManaged: boolean; displayName: string }>();
+    const discovered = await this.source.discover(kbRoot);
+    for (const w of discovered.warnings) console.warn(`[plugins] ${w}`);
+    for (const plugin of discovered.plugins) {
+      if (plugin.personal || !plugin.exists) continue;
+      byName.set(plugin.name, {
+        folders: [plugin.folder],
+        linksAreManaged: plugin.linksAreManaged,
+        displayName: plugin.displayName,
+      });
     }
-    const candidates = children.filter(
-      (child) =>
-        child.isDirectory() &&
-        !child.name.startsWith('.') &&
-        // Personal folders live under Plugins/ but are not plugins: one exists
-        // per person, private by construction, and listing them would put a
-        // locked row per employee in everyone's index.
-        !isPersonalPluginFolder(child.name),
-    );
-    // A plugin exists exactly when its folder carries an `access.md` (see the
-    // class doc) — stat that file, don't trust the directory.
-    const verdicts = await Promise.all(
-      candidates.map(async (child) => {
-        try {
-          return (await fs.stat(path.join(kbRoot, PLUGINS_DIR, child.name, 'access.md'))).isFile();
-        } catch {
-          return false;
-        }
-      }),
-    );
-    candidates.forEach((child, i) => {
-      if (verdicts[i]) byName.set(child.name, [`${PLUGINS_DIR}/${child.name}`]);
-    });
     return byName;
   }
 
-  private async countSkills(): Promise<Map<string, number>> {
-    // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
-    // property of the plugin, not of who is asking.
-    return bucketByPlugin(await this.skillService.listSkills(undefined));
+  /**
+   * Two counts from ONE read of the link index — the membership is built
+   * once per cold catalog, not once per count: `TtlCache` has no
+   * single-flight, so two concurrent readers of an empty cache would each
+   * discover the tree and resolve every linked skill's access.
+   *
+   *  - `skillCounts`: with links, a skill counts for EVERY plugin that holds
+   *    it — inline in its folder, or linked from a manifest. Personal folders
+   *    are already absent from the membership (they are places, not plugins).
+   *  - `brokenLinkCounts`: how many linked skills each plugin's members
+   *    cannot read — memberships reported as linked but not granted. From the
+   *    UNFILTERED index, so the count reaches the plugin's managers even when
+   *    the missing grant locks them out of the skill too.
+   *
+   * Without a link index: skills bucket by folder, and no link can be broken.
+   */
+  private async countThroughLinks(
+    folders: Map<string, string[]>,
+  ): Promise<{ skillCounts: Map<string, number>; brokenLinkCounts: Map<string, number> }> {
+    const skillCounts = new Map<string, number>();
+    const brokenLinkCounts = new Map<string, number>();
+    if (!this.links) {
+      // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
+      // property of the plugin, not of who is asking.
+      return {
+        skillCounts: bucketByFolder(await this.skillService.listSkills(undefined), folders),
+        brokenLinkCounts,
+      };
+    }
+    for (const memberships of (await this.links.membership()).bySkill.values()) {
+      for (const m of memberships) {
+        skillCounts.set(m.name, (skillCounts.get(m.name) ?? 0) + 1);
+        if (m.linked && !m.granted) brokenLinkCounts.set(m.name, (brokenLinkCounts.get(m.name) ?? 0) + 1);
+      }
+    }
+    return { skillCounts, brokenLinkCounts };
   }
 
-  private async countTools(): Promise<Map<string, number>> {
-    return bucketByPlugin(await this.toolManualService.listAllSummaries());
+  /**
+   * Tools belong to the plugin whose FOLDER holds them — matched by path
+   * prefix against the discovered folders, not by `pluginOfPath`'s
+   * second-segment rule, so a dialect plugin nested three folders deep still
+   * counts the servers its bundle expands.
+   */
+  private async countTools(folders: Map<string, string[]>): Promise<Map<string, number>> {
+    const counts = new Map<string, number>();
+    const byFolder = [...folders.entries()].map(([name, [folder]]) => ({ name, prefix: `${folder}/` }));
+    for (const tool of await this.toolManualService.listAllSummaries()) {
+      const owner = byFolder.find((f) => tool.path.startsWith(f.prefix));
+      if (!owner) continue;
+      counts.set(owner.name, (counts.get(owner.name) ?? 0) + 1);
+    }
+    return counts;
   }
 }
 
-/** Count items per plugin folder name; ungrouped items (`null`) count nowhere. */
-function bucketByPlugin(items: { path: string }[]): Map<string, number> {
+/**
+ * Count items per plugin by FOLDER PREFIX against the discovered folders —
+ * not by `pluginOfPath`'s second-segment rule, which would file a nested
+ * plugin's skills under its grouping folder. Items in no plugin count nowhere.
+ */
+function bucketByFolder(items: { path: string }[], folders: Map<string, string[]>): Map<string, number> {
   const counts = new Map<string, number>();
+  const byFolder = [...folders.entries()].map(([name, [folder]]) => ({ name, prefix: `${folder}/` }));
   for (const item of items) {
-    const plugin = pluginOfPath(item.path);
-    if (plugin === null) continue;
-    counts.set(plugin, (counts.get(plugin) ?? 0) + 1);
+    const owner = byFolder.find((f) => item.path.startsWith(f.prefix));
+    if (!owner) continue;
+    counts.set(owner.name, (counts.get(owner.name) ?? 0) + 1);
   }
   return counts;
 }

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

@@ -150,6 +150,63 @@ describe('DeploymentSettingsService — secrets', () => {
   });
 });
 
+describe('DeploymentSettingsService — KB layout', () => {
+  it('resolves the three roots 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',
+    });
+  });
+
+  it('takes a renamed root from the environment first, then the store', 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' });
+    process.env.KB_SKILLS_DIR = 'capabilities';
+    expect(settings.resolveKbLayout().skillsDir).toBe('capabilities');
+  });
+
+  /**
+   * The trio rule is judged on the layout the save WOULD produce: a plugins
+   * folder renamed to collide with the skills folder already in effect is a
+   * collision even though the batch names only one of them.
+   */
+  it('refuses two roots that share a name, case-insensitively', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(settings.save({ pluginsDir: 'skills' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    await expect(settings.save({ pluginsDir: 'SKILLS' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    await expect(
+      settings.save({ knowledgeBaseDir: 'Content', skillsDir: 'content' }, null),
+    ).rejects.toBeInstanceOf(SettingsValidationError);
+  });
+
+  it('refuses a root that is not a single plain folder name', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    for (const bad of ['a/b', '..', '.hidden', 'x\\y']) {
+      await expect(settings.save({ skillsDir: bad }, null)).rejects.toBeInstanceOf(
+        SettingsValidationError,
+      );
+    }
+  });
+
+  it('marks a layout change as restart-to-apply', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const { restartRequired } = await settings.save({ pluginsDir: 'Bundles' }, null);
+    expect(restartRequired).toBe(true);
+  });
+});
+
 describe('DeploymentSettingsService — validation', () => {
   it('rejects the whole batch when one field is wrong', async () => {
     const { db, rows } = makeDb();

package/src/modules/settings/__tests__/setup.routes.sync-status.test.ts

@@ -0,0 +1,77 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createSetupRoutes, type LastSyncStatus } from '../setup.routes.js';
+import { DeploymentSettingsService } from '../deployment-settings.service.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { Database } from '../../database/connection.js';
+
+/**
+ * The remote-sync facts on `GET /setup/status`: the address a hook calls and
+ * what the last sync did. Admin-only like the rest of the settings — a
+ * non-admin learns nothing about the deployment's endpoints.
+ */
+const ENC_KEY = randomBytes(32).toString('base64');
+
+let server: HttpServer | null = null;
+afterEach(() => {
+  server?.close();
+  server = null;
+});
+
+function listen(isAdmin: boolean, last: LastSyncStatus | null) {
+  const db = {
+    select: () => ({ from: () => Promise.resolve([]) }),
+    insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+    delete: () => ({ where: () => Promise.resolve() }),
+  } as unknown as Database;
+  const settings = new DeploymentSettingsService(db, ENC_KEY);
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userEmail = 'root@example.com';
+    req.userId = 'user-1';
+    next();
+  });
+  app.use(
+    '/api',
+    createSetupRoutes(
+      settings,
+      { isAdmin: async () => isAdmin } as IAdminAccessService,
+      { runAll: async () => {} },
+      { url: 'https://hexis.example.test/api/sync', lastSync: () => last },
+    ),
+  );
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  return `http://127.0.0.1:${port}`;
+}
+
+describe('GET /setup/status — remote sync', () => {
+  it('tells an admin the address and the last sync', async () => {
+    const last: LastSyncStatus = {
+      at: 1_700_000_000_000,
+      by: 'bearer',
+      status: 'synced',
+      results: [{ branch: 'main', outcome: 'updated' }],
+    };
+    const res = await fetch(`${listen(true, last)}/api/setup/status`);
+    const body = (await res.json()) as { sync?: unknown };
+    expect(body.sync).toEqual({ url: 'https://hexis.example.test/api/sync', last });
+  });
+
+  it('says null before the first sync', async () => {
+    const res = await fetch(`${listen(true, null)}/api/setup/status`);
+    const body = (await res.json()) as { sync?: { last: unknown } };
+    expect(body.sync?.last).toBeNull();
+  });
+
+  it('tells a non-admin nothing', async () => {
+    const res = await fetch(`${listen(false, null)}/api/setup/status`);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.sync).toBeUndefined();
+    expect(body.settings).toBeUndefined();
+  });
+});