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

package/src/modules/marketplace/marketplace-repo.service.ts

@@ -0,0 +1,337 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile, spawn, type ChildProcess } from 'node:child_process';
+import { promisify } from 'node:util';
+import { WorkspaceMutex } from '../kb-fs/mutex.js';
+import type { VirtualTree } from '../plugins/compile/compile-marketplace.js';
+
+const execFileAsync = promisify(execFile);
+
+/** What the repo service asks the compiler for — the one seam it has. */
+export interface MarketplaceCompiler {
+  sourceCommit(): Promise<string>;
+  compileFor(
+    audience: { userEmail: string },
+    /** The commit the tree is compiled from, when the caller already read it. */
+    sourceCommit?: string,
+  ): Promise<VirtualTree & { sourceCommit: string }>;
+}
+
+export interface EnsureResult {
+  /** The git namespace the caller's tree lives in. */
+  namespace: string;
+  /** True when a new commit was written this call. */
+  compiled: boolean;
+  sourceCommit: string;
+}
+
+/**
+ * ONE bare repository, ONE git namespace per caller.
+ *
+ * Every person's compiled marketplace is a branch in its own namespace
+ * (`refs/namespaces/<ns>/refs/heads/main`), which is exactly what git
+ * namespaces exist for (gitnamespaces(7)): `git http-backend` run with
+ * `GIT_NAMESPACE=<ns>` advertises only that namespace's refs, so a clone sees
+ * a repository whose `main` is their tree and nothing else — while every
+ * identical skill across callers is one blob in one object store.
+ *
+ * Freshness is LAZY and keyed on the knowledge base's default-branch commit:
+ * every input to a compile (skills, manifests, access rules, roles, groups)
+ * lives in that repository, so "same source commit" means "same answer".
+ * The last compiled source per namespace sits in a sidecar file rather than
+ * a commit trailer, so an unchanged tree costs no commit and no re-check.
+ *
+ * Each recompile appends a commit whose parent is the namespace's current
+ * head, so a client's `git pull` is always a fast-forward — including when
+ * access was withdrawn and files vanish. Writes go through git plumbing
+ * against a temporary index: no working tree of the bare repo, no checkout.
+ *
+ * Read-only by construction: `http.receivepack` is pinned off (http-backend
+ * would otherwise enable pushes for an authenticated REMOTE_USER), and the
+ * route refuses the receive-pack service before git ever sees it.
+ */
+export class MarketplaceRepoService {
+  private readonly locks = new WorkspaceMutex();
+  private initialised: Promise<void> | null = null;
+
+  constructor(
+    /** Absolute path of the bare repository (created on first use). */
+    readonly repoDir: string,
+    private readonly compiler: MarketplaceCompiler,
+    private readonly committer: { name: string; email: string } = {
+      name: 'Hexis',
+      email: 'hexis@localhost',
+    },
+  ) {}
+
+  /** The directory `GIT_PROJECT_ROOT` points at, and the repo's name under it. */
+  get projectRoot(): string {
+    return path.dirname(this.repoDir);
+  }
+  get repoName(): string {
+    return path.basename(this.repoDir);
+  }
+
+  /** The namespace for a user id — one path segment, stable, opaque. */
+  static namespaceFor(userId: string): string {
+    return `u-${userId.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 120)}`;
+  }
+
+  async ensureRepo(): Promise<void> {
+    this.initialised ??= (async () => {
+      await fs.mkdir(this.projectRoot, { recursive: true });
+      const isRepo = await fs
+        .access(path.join(this.repoDir, 'HEAD'))
+        .then(() => true, () => false);
+      if (!isRepo) await this.git(['init', '--bare', '--quiet', this.repoDir]);
+      await this.git(['-C', this.repoDir, 'config', 'http.receivepack', 'false']);
+      await this.git(['-C', this.repoDir, 'config', 'http.uploadpack', 'true']);
+      await fs.mkdir(this.sidecarDir(), { recursive: true });
+    })().catch((err: unknown) => {
+      // A failed initialisation is retried by the next request, not
+      // remembered until restart: a volume that was briefly unavailable must
+      // not turn every later fetch into a 500.
+      this.initialised = null;
+      throw err;
+    });
+    await this.initialised;
+  }
+
+  /**
+   * Bring the caller's namespace up to the knowledge base's current commit,
+   * compiling only when it moved. Serialised per namespace: two fetches
+   * arriving together compile once.
+   */
+  async ensureCompiled(user: { id: string; email: string }): Promise<EnsureResult> {
+    await this.ensureRepo();
+    const namespace = MarketplaceRepoService.namespaceFor(user.id);
+    return this.locks.run(`ns:${namespace}`, async () => {
+      const last = await this.readSidecar(namespace);
+      const head = await this.headOf(namespace);
+      let current = await this.compiler.sourceCommit();
+      if (last === current && head !== null) {
+        // Unchanged source is still a served namespace: its HEAD is checked
+        // on every fetch (a read) and written only when it is missing, so a
+        // crash after an earlier branch update cannot leave a clone that sees
+        // no default branch — and the cache hit stays a read on a healthy repo.
+        await this.ensureHead(namespace);
+        return { namespace, compiled: false, sourceCommit: current };
+      }
+
+      // The commit just read is the one the tree is stamped with: a second
+      // read that failed would otherwise record a placeholder as the compiled
+      // source and make every later fetch recompile. And the checkout can
+      // move WHILE we compile from it (a merge landing mid-read), so the
+      // commit is re-read afterwards: a tree stamped with a commit it was
+      // not compiled from would freeze that caller on a stale tree until the
+      // next change. Bounded — a checkout that moves on every attempt is
+      // served the latest attempt rather than never.
+      let tree = await this.compiler.compileFor({ userEmail: user.email }, current);
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const after = await this.compiler.sourceCommit();
+        if (after === current) break;
+        current = after;
+        tree = await this.compiler.compileFor({ userEmail: user.email }, current);
+      }
+      const sha = await this.commitTree(namespace, tree, head);
+      await this.writeSidecar(namespace, tree.sourceCommit);
+      return { namespace, compiled: sha !== head, sourceCommit: tree.sourceCommit };
+    });
+  }
+
+  /**
+   * The caller's namespace and its head commit, compiled if stale — what the
+   * GitHub-shaped REST surface (the Cowork path) reads instead of cloning.
+   */
+  async headFor(user: { id: string; email: string }): Promise<{ namespace: string; sha: string }> {
+    const { namespace } = await this.ensureCompiled(user);
+    const sha = await this.headOf(namespace);
+    if (!sha) throw new Error(`namespace ${namespace} has no head after compiling`);
+    return { namespace, sha };
+  }
+
+  /** One commit as the REST surface describes it. */
+  async describeCommit(sha: string): Promise<{
+    sha: string;
+    tree: string;
+    message: string;
+    authorName: string;
+    authorEmail: string;
+    date: string;
+  }> {
+    assertObjectId(sha);
+    const { stdout } = await this.git(['-C', this.repoDir, 'log', '-1', '--format=%H%n%T%n%an%n%ae%n%aI%n%B', sha]);
+    const [full, tree, authorName, authorEmail, date, ...rest] = stdout.split('\n');
+    return {
+      sha: full ?? sha,
+      tree: tree ?? '',
+      message: rest.join('\n').trim(),
+      authorName: authorName ?? '',
+      authorEmail: authorEmail ?? '',
+      date: date ?? '',
+    };
+  }
+
+  /**
+   * Whether `sha` is the namespace's head or one of its ancestors — the only
+   * commits a caller may read as that namespace. The object store is shared
+   * across everyone, so a sha alone is never enough.
+   */
+  async contains(namespace: string, sha: string): Promise<boolean> {
+    if (!looksLikeObjectId(sha)) return false;
+    const head = await this.headOf(namespace);
+    if (!head) return false;
+    // Two questions with two answers each, and only "no" is ever silent:
+    // a commit git does not have is simply not contained; a commit it has
+    // is an ancestor (exit 0) or not (exit 1); anything else — a corrupt
+    // store, a lock, a bad ref — is a failure the caller must hear about,
+    // not a 404 wearing its clothes.
+    try {
+      await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', `${sha}^{commit}`]);
+    } catch (err) {
+      if (exitCodeOf(err) === 1) return false;
+      throw err;
+    }
+    try {
+      await this.git(['-C', this.repoDir, 'merge-base', '--is-ancestor', sha, head]);
+      return true;
+    } catch (err) {
+      if (exitCodeOf(err) === 1) return false;
+      throw err;
+    }
+  }
+
+  /** The tree at `sha` as a zip stream, every path under `prefix/`. Check {@link contains} first. */
+  archiveZip(sha: string, prefix: string): ChildProcess {
+    assertObjectId(sha);
+    return spawn('git', ['-C', this.repoDir, 'archive', '--format=zip', `--prefix=${prefix}/`, sha], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  }
+
+  // --- internal --------------------------------------------------------------
+
+  private refOf(namespace: string): string {
+    return `refs/namespaces/${namespace}/refs/heads/main`;
+  }
+
+  private async headOf(namespace: string): Promise<string | null> {
+    try {
+      const { stdout } = await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', this.refOf(namespace)]);
+      return stdout.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Write `tree` as a commit on the namespace's branch. Materialises the
+   * virtual tree into a scratch directory, stages it into a throwaway index
+   * against the bare object store, and commits — no working tree involved.
+   * When the tree hash equals the head's, nothing is committed.
+   */
+  private async commitTree(
+    namespace: string,
+    tree: VirtualTree & { sourceCommit: string },
+    parent: string | null,
+  ): Promise<string> {
+    const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-marketplace-'));
+    // The throwaway index lives BESIDE the scratch worktree, never inside it:
+    // `git add -A` would otherwise stage the index (and its lock) into every
+    // compiled tree.
+    const indexDir = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-marketplace-index-'));
+    try {
+      for (const [rel, bytes] of tree.files) {
+        // The compiler sanitises every segment it invents, but the tree is
+        // built from repository content, so the sink checks containment
+        // itself: nothing is written outside the scratch directory.
+        const abs = path.resolve(scratch, rel);
+        if (!abs.startsWith(scratch + path.sep)) {
+          throw new Error(`refusing to materialise "${rel}": escapes the scratch tree`);
+        }
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, bytes);
+      }
+      const index = path.join(indexDir, 'index');
+      const env = { ...process.env, GIT_INDEX_FILE: index, GIT_DIR: this.repoDir, GIT_WORK_TREE: scratch };
+      await this.git(['add', '-A', '--', '.'], { cwd: scratch, env });
+      const treeSha = (await this.git(['write-tree'], { env })).stdout.trim();
+      if (parent) {
+        const parentTree = (await this.git(['-C', this.repoDir, 'rev-parse', `${parent}^{tree}`])).stdout.trim();
+        if (parentTree === treeSha) return parent;
+      }
+      const message = `Compile marketplace from ${tree.sourceCommit}\n\nHexis-Source-Commit: ${tree.sourceCommit}\n`;
+      const commitEnv = {
+        ...process.env,
+        GIT_AUTHOR_NAME: this.committer.name,
+        GIT_AUTHOR_EMAIL: this.committer.email,
+        GIT_COMMITTER_NAME: this.committer.name,
+        GIT_COMMITTER_EMAIL: this.committer.email,
+      };
+      const args = ['-C', this.repoDir, 'commit-tree', treeSha, '-m', message, ...(parent ? ['-p', parent] : [])];
+      const sha = (await this.git(args, { env: commitEnv })).stdout.trim();
+      // HEAD FIRST, then the branch: a symbolic ref may dangle, a branch
+      // without a HEAD is a clone that checks out nothing. Ordered so that a
+      // crash between the two leaves the recoverable state.
+      await this.ensureHead(namespace);
+      await this.git(['-C', this.repoDir, 'update-ref', this.refOf(namespace), sha, ...(parent ? [parent] : [])]);
+      return sha;
+    } finally {
+      await fs.rm(scratch, { recursive: true, force: true });
+      await fs.rm(indexDir, { recursive: true, force: true });
+    }
+  }
+
+  /**
+   * Point the namespace's HEAD at its branch — valid before the branch
+   * exists. A read first: the symref is written only when absent or wrong,
+   * so the common path touches nothing.
+   */
+  private async ensureHead(namespace: string): Promise<void> {
+    const head = `refs/namespaces/${namespace}/HEAD`;
+    const current = await this.git(['-C', this.repoDir, 'symbolic-ref', '--quiet', head]).then(
+      (r) => r.stdout.trim(),
+      () => null,
+    );
+    if (current === this.refOf(namespace)) return;
+    await this.git(['-C', this.repoDir, 'symbolic-ref', head, this.refOf(namespace)]);
+  }
+
+  private sidecarDir(): string {
+    return path.join(this.repoDir, 'hexis-namespaces');
+  }
+
+  private async readSidecar(namespace: string): Promise<string | null> {
+    try {
+      return (await fs.readFile(path.join(this.sidecarDir(), `${namespace}.json`), 'utf-8')).trim() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async writeSidecar(namespace: string, sourceCommit: string): Promise<void> {
+    await fs.writeFile(path.join(this.sidecarDir(), `${namespace}.json`), sourceCommit);
+  }
+
+  private git(args: string[], opts: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) {
+    return execFileAsync('git', args, { cwd: opts.cwd, env: opts.env ?? process.env, maxBuffer: 64 * 1024 * 1024 });
+  }
+}
+
+/** The exit code an execFile failure carries, or null when the process never ran. */
+function exitCodeOf(err: unknown): number | null {
+  const code = (err as { code?: unknown } | null)?.code;
+  return typeof code === 'number' ? code : null;
+}
+
+function looksLikeObjectId(sha: string): boolean {
+  return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha);
+}
+
+function assertObjectId(sha: string): void {
+  // An object id is the only thing these commands accept as a revision — a
+  // ref name, an option, anything git would interpret, is refused before it
+  // reaches the argument list.
+  if (!looksLikeObjectId(sha)) throw new Error(`not an object id: ${sha}`);
+}

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -167,6 +167,9 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     userId: string,
     st: McpAuthRequestState,
   ): Promise<{ redirectTo: string }> {
+    // A state without a PKCE challenge is a Claude-link request, which the
+    // marketplace bridge finishes; it must never reach the SDK's code store.
+    if (!st.cc) throw new InvalidGrantError('Authorization request carries no PKCE challenge');
     const code = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     await this.deps.db.insert(oauthAuthCodes).values({
       codeHash: hashToken(code),

package/src/modules/mcp/oauth/oauth-consent.routes.ts

@@ -1,12 +1,23 @@
 import express from 'express';
 import type { BevelOAuthProvider } from './bevel-oauth-provider.js';
-import { verifyAuthRequest } from './oauth-state.js';
+import { verifyAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 import '../../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface OAuthConsentRoutesDeps {
   provider: BevelOAuthProvider;
   /** Same HMAC secret the provider signs the authorize state with. */
   stateSecret: string;
+  /**
+   * The GitHub facade, when the deployment has one: a state it signed
+   * (`gh`) is a person connecting an account on a product that speaks to
+   * this deployment as a GitHub Enterprise host (claude.ai), and the code
+   * that flow needs is the facade's, not the SDK's.
+   */
+  facade?: {
+    isFacadeRequest(st: McpAuthRequestState): boolean;
+    clientNameFor(st: McpAuthRequestState): string;
+    completeConsent(userId: string, st: McpAuthRequestState): Promise<{ redirectTo: string }>;
+  };
 }
 
 /**
@@ -17,6 +28,9 @@ export interface OAuthConsentRoutesDeps {
  * landing from the redirect chain authenticates via the HttpOnly bevel_token
  * cookie fallback, so THIS is where a Bevel user attaches to the flow.
  */
+/** A facade state reaching a deployment whose routes were built without the facade. */
+const NO_FACADE = 'Connecting an external account this way is not enabled on this deployment.';
+
 export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.Router {
   const router = express.Router();
 
@@ -26,6 +40,11 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
     const raw = typeof req.query.state === 'string' ? req.query.state : '';
     const st = raw ? verifyAuthRequest(deps.stateSecret, raw) : null;
     if (!st) return void res.status(400).json({ error: 'Invalid or expired authorization request. Restart the connection from your agent.' });
+    if (st.gh) {
+      if (!deps.facade) return void res.status(400).json({ error: NO_FACADE });
+      res.json({ clientName: deps.facade.clientNameFor(st), scope: null, resource: null });
+      return;
+    }
     const client = await deps.provider.clientsStore.getClient(st.c);
     res.json({
       clientName: client?.client_name ?? null,
@@ -42,8 +61,11 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
     const raw = typeof (req.body ?? {}).state === 'string' ? req.body.state : '';
     const st = raw ? verifyAuthRequest(deps.stateSecret, raw) : null;
     if (!st) return void res.status(400).json({ error: 'Invalid or expired authorization request. Restart the connection from your agent.' });
+    if (st.gh && !deps.facade) return void res.status(400).json({ error: NO_FACADE });
     try {
-      const { redirectTo } = await deps.provider.issueAuthCode(userId, st);
+      const { redirectTo } = st.gh && deps.facade
+        ? await deps.facade.completeConsent(userId, st)
+        : await deps.provider.issueAuthCode(userId, st);
       res.json({ redirectTo });
     } catch (err) {
       // Message only — the raw error object can carry sensitive context

package/src/modules/mcp/oauth/oauth-state.ts

@@ -18,8 +18,19 @@ export interface McpAuthRequestState {
   c: string;
   /** redirect_uri (already validated against the client's registration). */
   r: string;
-  /** PKCE code_challenge (S256 — the SDK authorize handler enforces it). */
-  cc: string;
+  /**
+   * PKCE code_challenge (S256 — the SDK authorize handler enforces it).
+   * Absent only on a GitHub-facade request (`gh`), whose client is a
+   * confidential one that proves itself with a secret at the token exchange.
+   */
+  cc?: string;
+  /**
+   * A GitHub-shaped authorize request from a product that treats this
+   * deployment as a GitHub Enterprise host (the marketplace facade), not an
+   * MCP client: the consent routes hand it to the facade, which mints a code
+   * of its own instead of the SDK's.
+   */
+  gh?: true;
   /** The client's own `state` parameter, echoed back on the code redirect. */
   s?: string;
   /** Requested scope (space-joined). */
@@ -51,7 +62,8 @@ export function verifyAuthRequest(secret: string, token: string): McpAuthRequest
   if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
   try {
     const parsed = JSON.parse(Buffer.from(body, 'base64url').toString()) as McpAuthRequestState;
-    if (typeof parsed.iat !== 'number' || !parsed.c || !parsed.r || !parsed.cc) return null;
+    if (typeof parsed.iat !== 'number' || !parsed.c || !parsed.r) return null;
+    if (!parsed.cc && parsed.gh !== true) return null;
     const age = Date.now() - parsed.iat;
     if (age > STATE_MAX_AGE_MS || age < -STATE_SKEW_MS) return null;
     return parsed;

package/src/modules/plugins/__tests__/bundle-dialect.e2e.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_BRANCH, DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../../access/access-control.service.js';
+import { SkillService } from '../../skills/skills.service.js';
+import { ToolManualService } from '../../tool-manuals/tool-manuals.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { PluginIndexService } from '../plugins.service.js';
+import { PluginLinkIndex } from '../plugin-links.js';
+import { PluginLinksService } from '../plugin-links.service.js';
+import { KbPluginSource } from '../discovery/kb-plugin-source.js';
+import { MarketplaceCompilerService } from '../compile/marketplace-compiler.service.js';
+
+/**
+ * A customer's repository, read as-is: lowercase `skills/` and `plugins/`
+ * roots, bundles at the depths their org uses, a registry with a profile
+ * chain, and a committed `dist/` beside the source. Every consumer — catalog,
+ * plugin index, link index, tool manuals, compiler — must read the SOURCE
+ * trees and agree on what a plugin holds, with nothing written back.
+ */
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+
+describe('bundle dialect, end to end', () => {
+  let root: string;
+  let repo: string;
+  let access: AccessControlService;
+  let skills: SkillService;
+  let tools: ToolManualService;
+  let links: PluginLinkIndex;
+  let index: PluginIndexService;
+  let compiler: MarketplaceCompilerService;
+  let linkService: PluginLinksService;
+
+  const write = async (rel: string, text: string) => {
+    const abs = path.join(repo, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text);
+  };
+
+  beforeEach(async () => {
+    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-dialect-'));
+    repo = path.join(root, wsId, KB_DIR);
+    const workspaceService = {
+      getOrCreateForBranch: async () => ({ id: wsId }),
+      getWorkspacePath: async (id: string) => path.join(root, id),
+      readFile: async (id: string, rel: string) => fs.readFile(path.join(root, id, rel), 'utf-8'),
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+
+    await write('roles.yaml', 'roles:\n  Admin:\n    - admin@x.io\n');
+    // Their scopes decide readability; everything here is open to signed-in people.
+    await write('access.md', '---\nwrite:\n  - Admin\n---\nread:\n  - everyone\n');
+    await write(
+      'configs/mcp/registry.json',
+      JSON.stringify({
+        servers: [
+          { id: 'jira', config: { command: 'npx', args: ['-y', 'jira-mcp'] } },
+          { id: 'confluence', config: { type: 'http', url: 'https://mcp.confluence.example' } },
+        ],
+        profiles: [{ id: 'base', servers: ['jira'] }, { id: 'global', servers: ['confluence'], extends: 'base' }],
+      }),
+    );
+    // Skills at their four depths; a build output that must be ignored.
+    await write('skills/functional/cluster-a/one-skill/SKILL.md', '---\nname: one-skill\ndescription: One.\nmetadata:\n  version: "1.4.0"\n  author: "acme"\n---\n');
+    await write('skills/departments/business/finance/close-books/SKILL.md', '---\ndescription: Close.\n---\n');
+    await write('skills/departments/engineering/shared/cluster-a/deploy/SKILL.md', '---\ndescription: Deploy.\n---\n');
+    await write('skills/departments/engineering/shared/cluster-a/rollback/SKILL.md', '---\ndescription: Undo.\n---\n');
+    await write('skills/departments/engineering/team-x/team-only/SKILL.md', '---\ndescription: Ours.\n---\n');
+    await write('dist/docs/plugins/functional/example/skills/deploy/SKILL.md', '---\ndescription: compiled copy\n---\n');
+    // Plugins: one links a cluster + a single skill; one links a department.
+    await write(
+      'plugins/functional/cluster-a/example-plugin/plugin.bundle.json',
+      JSON.stringify({
+        name: 'example-plugin',
+        version: '1.3.1',
+        description: 'Example',
+        mcpProfile: 'global',
+        interface: { displayName: 'Example Plugin' },
+        sourceSkillRoots: ['skills/departments/engineering/shared/cluster-a', 'skills/functional/cluster-a/one-skill'],
+      }),
+    );
+    await write(
+      'plugins/departments/business/finance/finance-kit/plugin.bundle.json',
+      JSON.stringify({ name: 'finance-kit', sourceSkillRoots: ['skills/departments/business/finance'] }),
+    );
+
+    const source = new KbPluginSource();
+    access = new AccessControlService(workspaceService, KB_DIR);
+    skills = new SkillService(workspaceService, access, KB_DIR);
+    tools = new ToolManualService(workspaceService, access, KB_DIR, Date.now, source);
+    links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, Date.now, source);
+    index = new PluginIndexService(workspaceService, access, skills, tools, KB_DIR, Date.now, links, source);
+    compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, KB_DIR, { name: 'acme', owner: 'Acme' }, source);
+    linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, skills, links, KB_DIR);
+  });
+  afterEach(async () => {
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT });
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('reads the source trees: skills at any depth, plugins as skill lists, servers from the registry', async () => {
+    const catalog = await skills.listSkills();
+    expect(catalog.map((s) => s.name).sort()).toEqual(['close-books', 'deploy', 'one-skill', 'rollback', 'team-only']);
+    expect(catalog.find((s) => s.name === 'one-skill')?.version).toBe('1.4.0');
+    expect(catalog.some((s) => s.path.startsWith('dist/'))).toBe(false);
+
+    const membership = await links.membership();
+    expect(membership.byPlugin.get('example-plugin')?.linkedSkills.sort()).toEqual([
+      'skills/departments/engineering/shared/cluster-a/deploy',
+      'skills/departments/engineering/shared/cluster-a/rollback',
+      'skills/functional/cluster-a/one-skill',
+    ]);
+    expect(membership.byPlugin.get('example-plugin')?.linksAreManaged).toBe(false);
+    expect(membership.bySkill.get('skills/departments/business/finance/close-books')).toEqual([
+      { name: 'finance-kit', linked: true, granted: true },
+    ]);
+    // A standalone skill is in no plugin, and that is a normal state.
+    expect(membership.bySkill.get('skills/departments/engineering/team-x/team-only')).toBeUndefined();
+
+    const plugins = await index.catalog();
+    expect(plugins.map((p) => [p.name, p.skillCount, p.toolCount])).toEqual([
+      ['example-plugin', 3, 2],
+      ['finance-kit', 1, 0],
+    ]);
+    expect(plugins[0].folders).toEqual(['plugins/functional/cluster-a/example-plugin']);
+
+    const manuals = await tools.listAllSummaries();
+    expect(manuals.map((m) => m.name).sort()).toEqual(['confluence', 'jira']);
+  });
+
+  it('compiles a marketplace from the source trees, per caller', async () => {
+    const tree = await compiler.compileFor({ userEmail: 'someone@x.io' });
+    const paths = [...tree.files.keys()];
+    expect(paths).toContain('plugins/example-plugin/skills/deploy/SKILL.md');
+    expect(paths).toContain('plugins/example-plugin/skills/one-skill/SKILL.md');
+    expect(paths).toContain('plugins/finance-kit/skills/close-books/SKILL.md');
+    // The standalone team skill rides in the leftovers plugin; linked ones do not repeat there.
+    expect(paths).toContain('plugins/skills-and-knowledge/skills/team-only/SKILL.md');
+    expect(paths).not.toContain('plugins/skills-and-knowledge/skills/deploy/SKILL.md');
+    const manifest = JSON.parse(tree.files.get('plugins/example-plugin/plugin.json')!.toString());
+    expect(manifest).toMatchObject({ name: 'example-plugin', version: '1.3.1', description: 'Example' });
+    const mcp = JSON.parse(tree.files.get('plugins/example-plugin/.mcp.json')!.toString());
+    expect(Object.keys(mcp.mcpServers).sort()).toEqual(['confluence', 'jira']);
+    expect(paths.some((p) => p.includes('dist/'))).toBe(false);
+  });
+
+  it('never writes into the dialect: linking through hexis is refused as read-only', async () => {
+    const user = { id: 'u1', email: 'admin@x.io', name: 'Admin' };
+    await expect(linkService.link(user, 'example-plugin', 'skills/departments/engineering/team-x/team-only')).rejects.toMatchObject({
+      status: 409,
+      payload: { kind: 'read-only-links' },
+    });
+    const before = await fs.readFile(path.join(repo, 'plugins/functional/cluster-a/example-plugin/plugin.bundle.json'), 'utf-8');
+    expect(JSON.parse(before).sourceSkillRoots).toHaveLength(2);
+  });
+});