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

package/src/modules/plugins/compile/compile-marketplace.ts

@@ -0,0 +1,500 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  HEXIS_EXTENSION_NS,
+  PLUGIN_MANIFEST_FILE,
+  PLUGIN_MCP_FILE,
+  PLUGIN_MANIFEST_SCHEMA,
+  PLUGIN_MCP_SCHEMA,
+  pluginManifestName,
+} from '@bevel-software/platform-shared';
+import { BUNDLE_FILE as BUNDLE_MANIFEST_FILE } from '../discovery/bundle-dialect/bundle.source.js';
+import type { ITreeWalker } from '../../../shared/fs.contract.js';
+import { containsVariableReference } from '../../../shared/variable-refs.js';
+import { judgeMcpServerEntry } from '../../tool-manuals/mcp-json-discovery.js';
+import type { SkillSummary } from '../../skills/skills.contract.js';
+import type { LinkMembership } from '../plugin-links.js';
+import type { DiscoveredPlugin } from '../discovery/plugin-source.js';
+
+/**
+ * The compiler: SOURCE layout in, DISTRIBUTION layout out.
+ *
+ * Source is what lives in the knowledge base — shared skills under
+ * `Skills/`, plugin folders under `Plugins/` whose manifests LINK to them.
+ * Distribution is what an agent installs: a marketplace of self-contained
+ * plugins, each physically holding its skills (Claude Code refuses paths
+ * that escape a plugin's directory, and symlinks are out), in the vendor
+ * layouts the clients read today — `.claude-plugin/plugin.json`,
+ * `.codex-plugin/plugin.json`, `.mcp.json` — beside the Agent Plugins
+ * `plugin.json` and `mcp.json`.
+ *
+ * What comes out, for one caller:
+ *
+ *   .claude-plugin/marketplace.json      Claude Code's catalogue (and Cowork's,
+ *                                        claude.ai's): every plugin below
+ *   .agents/plugins/marketplace.json     Codex's catalogue, every entry
+ *                                        INSTALLED_BY_DEFAULT — without the
+ *                                        bundle, which would install it all twice
+ *   plugins/<slug>/…                     one per plugin the caller may read
+ *                                        anything of: inline + linked skills,
+ *                                        the portable half of mcp.json
+ *   plugins/skills-and-knowledge/…       every readable skill no plugin above
+ *                                        ships — how a standalone skill, or one
+ *                                        only in plugins the caller cannot see,
+ *                                        is still one install away — plus the
+ *                                        knowledge base's own MCP endpoint
+ *   plugins/hexis-all/…                  the one-install bundle: a plugin of
+ *                                        its own holding every readable skill
+ *                                        once and the knowledge base's MCP
+ *                                        endpoint — content, not a dependency
+ *                                        list, because only Claude Code
+ *                                        resolves one
+ *   skills/<name>/…                      every readable skill once, flat, for
+ *                                        `npx skills add <url> --all`
+ *   README.md                            names the source commit
+ *
+ * FAIL CLOSED, per file: a skill is copied only when `readable` says yes for
+ * its SKILL.md — the same per-path verdict the catalog filters on — so the
+ * compiled tree for a caller holds exactly what that caller may read, and
+ * nothing about a skill they may not. Plugins with nothing readable are
+ * left out entirely. `access.md` and `.bevelignore` never ship; neither do
+ * the hexis-only `.tool` manuals (no other client can run them), nor an
+ * `mcp.json` header carrying a `${VAR}` vault reference (the extension block
+ * that resolves it is ours, and a header a client would send verbatim must
+ * not name a secret it cannot expand).
+ *
+ * A pure function of its inputs — it reads the KB tree it is pointed at and
+ * returns a virtual tree; writing it somewhere (a git namespace, a folder, a
+ * remote) is the sink's business.
+ */
+
+export interface MarketplaceOptions {
+  /** The marketplace's name — a slug the clients key it on. */
+  name: string;
+  /** Shown as the marketplace owner. */
+  owner: string;
+  description?: string;
+  /** The default-branch commit the tree was compiled from; also the bundle's version. */
+  sourceCommit: string;
+  /** The name of the one-install bundle plugin. */
+  bundleName?: string;
+  /** The name of the leftovers plugin holding skills no other plugin ships. */
+  skillsPluginName?: string;
+  /**
+   * This deployment's hosted MCP endpoint — the knowledge base as a tool.
+   * Shipped in the leftovers plugin's `mcp.json` so an agent that installs
+   * from the marketplace can read the knowledge its skills refer to. URL only,
+   * never a credential: the endpoint challenges with OAuth metadata, and the
+   * client signs the person in on first use.
+   */
+  knowledgeBaseMcp?: { name: string; url: string };
+}
+
+export interface CompileInput {
+  /** The walk that lists a skill folder's files. */
+  disk: ITreeWalker;
+  /** Absolute path of the KB checkout (the folder holding `Plugins/`, `Skills/`, …). */
+  kbRoot: string;
+  /** The released catalog, UNFILTERED — `readable` does the filtering. */
+  skills: SkillSummary[];
+  /** The plugins as the configured source discovered them (manifests and servers already parsed). */
+  plugins: DiscoveredPlugin[];
+  /** Which plugins hold which skills, from the link index. */
+  membership: LinkMembership;
+  /** The caller's read verdict on a repo-relative path (`<skillFolder>/SKILL.md`). */
+  readable: (repoPath: string) => Promise<boolean>;
+  options: MarketplaceOptions;
+}
+
+export interface VirtualTree {
+  /** repo-relative POSIX path → file bytes. */
+  files: Map<string, Buffer>;
+  /** What was left out and why — name clashes, unparsable manifests. */
+  warnings: string[];
+  /** The plugin slugs the tree carries, in marketplace order. */
+  plugins: string[];
+}
+
+const BUNDLE_NAME = 'hexis-all';
+const SKILLS_PLUGIN_NAME = 'skills-and-knowledge';
+/** Slugs the compiler emits itself; a real plugin may not take them. */
+const RESERVED_SLUGS = new Set([BUNDLE_NAME, SKILLS_PLUGIN_NAME]);
+const NEVER_SHIPPED = new Set(['access.md', '.bevelignore']);
+
+export async function compileMarketplace(input: CompileInput): Promise<VirtualTree> {
+  const { disk, kbRoot, skills, plugins, membership, readable, options } = input;
+  const files = new Map<string, Buffer>();
+  const warnings: string[] = [];
+  const put = (rel: string, content: string | Buffer) =>
+    files.set(rel, typeof content === 'string' ? Buffer.from(content, 'utf-8') : content);
+
+  // One verdict per skill, resolved once: every plugin below reads from it.
+  // Readability is the only gate — every skill the caller may read ships.
+  const readableSkills = new Map<string, SkillSummary>();
+  for (const s of skills) {
+    if (await readable(`${s.path}/SKILL.md`)) readableSkills.set(s.path, s);
+  }
+
+  interface PluginOut {
+    slug: string;
+    displayName: string;
+    description?: string;
+    version?: string;
+    /** Who wrote it, as the source manifest says — an object or a string. */
+    author?: unknown;
+    keywords?: string[];
+    /** The presentation block a catalogue shows (Codex's `interface`), as the source manifest says. */
+    ui?: Record<string, unknown>;
+    skills: SkillSummary[];
+    /** Source folder (real plugins only). */
+    folder?: string;
+    /** The portable `mcpServers` map to ship, when the plugin has servers. */
+    mcp?: Record<string, Record<string, unknown>>;
+  }
+  const out: PluginOut[] = [];
+
+  // 1. Real plugins: inline skills (in the folder) + linked skills (from the
+  //    manifest), each only if readable. Personal folders are places, not
+  //    plugins; a plugin the index does not count as existing is not shipped.
+  const byName = new Map(plugins.map((p) => [p.name, p]));
+  for (const [name, links] of [...membership.byPlugin.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const plugin = byName.get(name);
+    if (!plugin || plugin.personal || !plugin.exists) continue;
+    const manifest = plugin.manifest;
+    const inline = [...readableSkills.values()].filter((s) => s.path.startsWith(`${plugin.folder}/`));
+    const linked = links.linkedSkills
+      .map((p) => readableSkills.get(p))
+      .filter((s): s is SkillSummary => s !== undefined);
+    const dedup = dedupeByName([...inline, ...linked], (s, other) =>
+      warnings.push(
+        `${name}: skill "${s.name}" at ${s.path} shares its name with ${other.path} — the second is left out`,
+      ),
+    );
+    const mcp = portableMcp(plugin.mcpServers, (name, reason) =>
+      warnings.push(`${plugin.folder}: mcp server "${name}" not shipped — ${reason}`),
+    );
+    if (dedup.length === 0 && mcp === null) continue; // nothing this caller may see
+    // The plugin's identity IS the marketplace slug. Folded once more here
+    // all the same: it becomes a path segment in the compiled tree, and a
+    // checked-in manifest is repository content, not trusted input — the
+    // folding (`[a-z0-9.-]`, no runs, no leading dots) leaves nothing that
+    // can be a separator or a parent reference.
+    const slug = pluginManifestName(name);
+    if (RESERVED_SLUGS.has(slug)) {
+      warnings.push(`${plugin.folder}: manifest name "${slug}" is reserved by the marketplace and cannot be a plugin — plugin skipped`);
+      continue;
+    }
+    if (out.some((p) => p.slug === slug)) {
+      warnings.push(`${plugin.folder}: manifest name "${slug}" is already taken in this marketplace — plugin skipped`);
+      continue;
+    }
+    const ui = isRecord(manifest?.interface) ? manifest.interface : undefined;
+    out.push({
+      slug,
+      displayName: plugin.displayName,
+      description: typeof manifest?.description === 'string' ? manifest.description : undefined,
+      version: typeof manifest?.version === 'string' ? manifest.version : undefined,
+      author: isRecord(manifest?.author) || typeof manifest?.author === 'string' ? manifest.author : undefined,
+      keywords:
+        Array.isArray(manifest?.keywords) && manifest.keywords.every((k) => typeof k === 'string')
+          ? (manifest.keywords as string[])
+          : undefined,
+      ui,
+      skills: dedup,
+      folder: plugin.folder,
+      mcp: mcp ?? undefined,
+    });
+  }
+
+  // 2. The leftovers plugin: every readable skill that no plugin above ships.
+  //    Agents install plugins, not loose skills, so a skill in no plugin — or
+  //    only in plugins this caller cannot see anything of — still has to be one
+  //    install away. ONE plugin per caller, not one per scope: there is nothing
+  //    to choose between (the caller may read all of it) and the bundle installs
+  //    it regardless, so scope plugins would only add names and duplicate what
+  //    the real plugins already carry.
+  //    It also carries the knowledge base's own MCP endpoint (URL only — the
+  //    client's OAuth flow signs the person in), so an agent installing from
+  //    the marketplace can read the knowledge its skills point at. With the
+  //    endpoint configured the plugin exists even for a caller with no
+  //    leftover skill: the knowledge is the point.
+  const covered = new Set(out.flatMap((p) => p.skills.map((s) => s.path)));
+  const leftovers = [...readableSkills.values()].filter((s) => !covered.has(s.path));
+  const kbMcp = options.knowledgeBaseMcp
+    ? { [options.knowledgeBaseMcp.name]: { type: 'streamable-http', url: options.knowledgeBaseMcp.url } }
+    : undefined;
+  if (leftovers.length > 0 || kbMcp) {
+    const slug = pluginManifestName(options.skillsPluginName ?? SKILLS_PLUGIN_NAME);
+    if (out.some((p) => p.slug === slug)) {
+      warnings.push(`the skills plugin "${slug}" collides with a plugin's manifest name — standalone skills not shipped`);
+    } else {
+      out.push({
+        slug,
+        displayName: 'Skills and knowledge',
+        description: kbMcp
+          ? 'Every skill you may read that no other plugin here ships, and the knowledge base as an MCP server'
+          : 'Every skill you may read that no other plugin here ships',
+        skills: dedupeByName(leftovers, (s, other) =>
+          warnings.push(`${slug}: "${s.name}" at ${s.path} shares its name with ${other.path} — left out`),
+        ),
+        mcp: kbMcp,
+      });
+    }
+  }
+
+  // 3. Materialise every plugin: the plugin folder's own files, the copied
+  //    skill folders, then the three manifests — in that order, so what the
+  //    platform writes wins over a checked-in file of the same name.
+  for (const p of out) {
+    const base = `plugins/${p.slug}`;
+    // The folder's own files — a CONVENTIONS.md the skills refer to, a
+    // README, reference material — ship beside the skills. What does not:
+    // the platform's own files (rules, the source manifests, `mcp.json`, all
+    // rewritten below), the inline skills (copied by name below), and the
+    // hexis-only `.tool` manuals under their extension folder.
+    if (p.folder) await copyPluginFiles(disk, kbRoot, p.folder, base, put);
+    for (const s of p.skills) {
+      await copySkill(disk, kbRoot, s,`${base}/skills/${s.name}`, put);
+    }
+    const spec: Record<string, unknown> = { $schema: PLUGIN_MANIFEST_SCHEMA, name: p.slug };
+    if (p.version) spec.version = p.version;
+    if (p.description) spec.description = p.description;
+    if (p.author !== undefined) spec.author = p.author;
+    if (p.keywords) spec.keywords = p.keywords;
+    put(`${base}/${PLUGIN_MANIFEST_FILE}`, `${JSON.stringify(spec, null, 2)}\n`);
+    const vendor: Record<string, unknown> = { name: p.slug };
+    if (p.version) vendor.version = p.version;
+    vendor.description = p.description ?? p.displayName;
+    if (p.author !== undefined) vendor.author = p.author;
+    if (p.keywords) vendor.keywords = p.keywords;
+    put(`${base}/.claude-plugin/plugin.json`, `${JSON.stringify(vendor, null, 2)}\n`);
+    // Codex's manifest carries the presentation block: the source's own,
+    // completed with the one thing every plugin can say about itself when
+    // the block does not say it — a partial block is a block, not a reason
+    // to lose the name.
+    const ui: Record<string, unknown> = { ...(p.ui ?? {}) };
+    if (typeof ui.displayName !== 'string' || !ui.displayName.trim()) ui.displayName = p.displayName;
+    const codex: Record<string, unknown> = { ...vendor, interface: ui };
+    put(`${base}/.codex-plugin/plugin.json`, `${JSON.stringify(codex, null, 2)}\n`);
+    if (p.mcp) {
+      put(`${base}/${PLUGIN_MCP_FILE}`, `${JSON.stringify({ $schema: PLUGIN_MCP_SCHEMA, mcpServers: p.mcp }, null, 2)}\n`);
+      put(`${base}/.mcp.json`, `${JSON.stringify({ mcpServers: p.mcp }, null, 2)}\n`);
+    }
+  }
+
+  // 4. Every readable skill once, by name — ONE set, carried twice: the flat
+  //    root skills/ folder, and the one-install bundle below.
+  const flat = dedupeByName(
+    [...readableSkills.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    (s, other) =>
+      warnings.push(`"${s.name}" at ${s.path} shares its name with ${other.path} — left out of skills/ and the bundle`),
+  );
+  for (const s of flat) await copySkill(disk, kbRoot, s,`skills/${s.name}`, put);
+
+  // 5. The one-install bundle: a plugin of its own that IS everything the
+  //    caller may read — every skill once, plus the knowledge base's MCP
+  //    endpoint — not a manifest naming the plugins above as dependencies.
+  //    Only Claude Code resolves a dependency list; Cowork and claude.ai
+  //    install a plugin's content and nothing more, so for one install to
+  //    mean the same thing on every surface, the content has to be there.
+  //    Its version is the source commit, so an auto-update sees every change.
+  const bundle = pluginManifestName(options.bundleName ?? BUNDLE_NAME);
+  const bundleTaken = out.some((p) => p.slug === bundle);
+  if (bundleTaken) {
+    // Only reachable with a non-default bundle name that folds to a real
+    // plugin's slug: the default is reserved above. Skipping the bundle
+    // beats overwriting that plugin's tree with everything.
+    warnings.push(`the bundle name "${bundle}" collides with a plugin's manifest name — no bundle plugin emitted`);
+  }
+  const bundleEmitted = !bundleTaken && (flat.length > 0 || kbMcp !== undefined);
+  if (bundleEmitted) {
+    const base = `plugins/${bundle}`;
+    const shortSha = options.sourceCommit.slice(0, 12) || '0';
+    const description = `Everything in ${options.owner}'s marketplace you may read, in one install.`;
+    put(
+      `${base}/.claude-plugin/plugin.json`,
+      `${JSON.stringify({ name: bundle, version: `0.0.0-${shortSha}`, description }, null, 2)}\n`,
+    );
+    put(
+      `${base}/${PLUGIN_MANIFEST_FILE}`,
+      `${JSON.stringify({ $schema: PLUGIN_MANIFEST_SCHEMA, name: bundle, description }, null, 2)}\n`,
+    );
+    if (kbMcp) {
+      put(`${base}/${PLUGIN_MCP_FILE}`, `${JSON.stringify({ $schema: PLUGIN_MCP_SCHEMA, mcpServers: kbMcp }, null, 2)}\n`);
+      put(`${base}/.mcp.json`, `${JSON.stringify({ mcpServers: kbMcp }, null, 2)}\n`);
+    }
+    for (const s of flat) await copySkill(disk, kbRoot, s,`${base}/skills/${s.name}`, put);
+  }
+
+  // 6. The two catalogues + a README naming the source. The bundle is listed
+  //    for Claude's surfaces only: Codex installs every catalogue entry on
+  //    add, and the bundle repeats what the other entries already carry.
+  const entries = out.map((p) => ({ slug: p.slug, description: p.description ?? p.displayName }));
+  const claudeEntries = [...entries, ...(bundleEmitted ? [{ slug: bundle, description: 'Everything you may read, one install' }] : [])];
+  put(
+    '.claude-plugin/marketplace.json',
+    `${JSON.stringify(
+      {
+        name: options.name,
+        owner: { name: options.owner },
+        ...(options.description ? { description: options.description } : {}),
+        plugins: claudeEntries.map((e) => ({ name: e.slug, source: `./plugins/${e.slug}`, description: e.description })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  put(
+    '.agents/plugins/marketplace.json',
+    `${JSON.stringify(
+      {
+        name: options.name,
+        plugins: entries.map((e) => ({
+          name: e.slug,
+          source: { source: 'local', path: `./plugins/${e.slug}` },
+          policy: { installation: 'INSTALLED_BY_DEFAULT' },
+          description: e.description,
+        })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  put(
+    'README.md',
+    [
+      `# ${options.name}`,
+      '',
+      `Compiled from ${options.owner}'s knowledge base at commit \`${options.sourceCommit}\`.`,
+      'This tree is generated: edit the knowledge base, not these files.',
+      '',
+      `Plugins: ${claudeEntries.map((e) => e.slug).join(', ') || 'none'}.`,
+      '',
+    ].join('\n'),
+  );
+
+  return { files, warnings, plugins: claudeEntries.map((e) => e.slug) };
+}
+
+// --- helpers ------------------------------------------------------------------
+
+/** The files of a plugin's own folder that are the platform's or another step's to write, never copied as they are. */
+const REWRITTEN_AT_ROOT = new Set([PLUGIN_MANIFEST_FILE, BUNDLE_MANIFEST_FILE, PLUGIN_MCP_FILE]);
+
+/**
+ * Copy a plugin folder's own files under `dest`: everything except the
+ * platform's files (rules, the manifests and `mcp.json` at the root — all
+ * rewritten by the compiler), the inline skills under `skills/` (copied by
+ * name, so a clash resolves the same way everywhere), the hexis extension
+ * folder (`.tool` manuals no other client runs) and `.tool` files anywhere.
+ */
+async function copyPluginFiles(
+  disk: ITreeWalker,
+  kbRoot: string,
+  folder: string,
+  dest: string,
+  put: (rel: string, content: Buffer) => void,
+): Promise<void> {
+  const abs = path.join(kbRoot, folder);
+  for (const rel of await disk.walkFiles(abs, (name) => !NEVER_SHIPPED.has(name) && !name.endsWith('.tool'))) {
+    const top = rel.split('/')[0];
+    if (top === 'skills' || top === HEXIS_EXTENSION_NS) continue;
+    if (!rel.includes('/') && REWRITTEN_AT_ROOT.has(rel)) continue;
+    put(`${dest}/${rel}`, await fs.readFile(path.join(abs, rel)));
+  }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Copy a skill folder (minus what never ships) under `dest`. */
+async function copySkill(
+  disk: ITreeWalker,
+  kbRoot: string,
+  skill: SkillSummary,
+  dest: string,
+  put: (rel: string, content: Buffer) => void,
+): Promise<void> {
+  const abs = path.join(kbRoot, skill.path);
+  for (const rel of await disk.walkFiles(abs, (name) => !NEVER_SHIPPED.has(name))) {
+    put(`${dest}/${rel}`, await fs.readFile(path.join(abs, rel)));
+  }
+}
+
+/** First by (name, path) order wins; the loser is reported to `onClash`. */
+function dedupeByName(
+  list: SkillSummary[],
+  onClash: (loser: SkillSummary, winner: SkillSummary) => void,
+): SkillSummary[] {
+  const sorted = [...list].sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+  const seen = new Map<string, SkillSummary>();
+  const out: SkillSummary[] = [];
+  for (const s of sorted) {
+    const winner = seen.get(s.name);
+    if (winner) {
+      if (winner.path !== s.path) onClash(s, winner);
+      continue;
+    }
+    seen.set(s.name, s);
+    out.push(s);
+  }
+  return out;
+}
+
+/**
+ * The portable half of a plugin's `mcpServers`: every entry the ONE
+ * judgement accepts (a name a client can key on, a transport it speaks, the
+ * field that transport needs), normalised, minus what a client cannot use —
+ * `${VAR}` vault references in a url or a header. Null when there is no
+ * server to ship; each server left out is reported with the judgement's
+ * reason, so an omission is diagnosable.
+ */
+function portableMcp(
+  servers: Record<string, unknown> | null,
+  leftOut: (name: string, reason: string) => void,
+): Record<string, Record<string, unknown>> | null {
+  if (!servers) return null;
+  const out: Record<string, Record<string, unknown>> = {};
+  for (const [name, raw] of Object.entries(servers)) {
+    const verdict = judgeMcpServerEntry(name, raw);
+    if (!verdict.ok) {
+      leftOut(name, verdict.reason);
+      continue;
+    }
+    // Fields the judgement does not read (`startup_timeout_sec`, say) ride
+    // along as declared — a client that knows one uses it, one that does
+    // not ignores it — unless they hold a vault reference, which no client
+    // can expand.
+    // Built without a prototype, so a field spelled `__proto__` is a field
+    // that survives to the serialised entry, not a prototype assignment.
+    const extras: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    if (isRecord(raw)) {
+      for (const [key, value] of Object.entries(raw)) {
+        if (JUDGED_KEYS.has(key) || containsVariableReference(JSON.stringify(value))) continue;
+        extras[key] = value;
+      }
+    }
+    if (verdict.transport === 'stdio') {
+      out[name] = { ...verdict.entry, ...extras };
+      continue;
+    }
+    const entry: Record<string, unknown> = { type: verdict.entry.type, url: verdict.entry.url };
+    if (containsVariableReference(verdict.entry.url)) {
+      leftOut(name, 'its url is expanded from the vault, which a client cannot do');
+      continue;
+    }
+    if (verdict.entry.headers) {
+      const headers: Record<string, string> = {};
+      for (const [h, v] of Object.entries(verdict.entry.headers)) {
+        if (!containsVariableReference(v)) headers[h] = v;
+      }
+      if (Object.keys(headers).length > 0) entry.headers = headers;
+    }
+    out[name] = { ...entry, ...extras };
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/** The server fields the judgement reads and normalises; every other field passes through. */
+const JUDGED_KEYS = new Set(['type', 'url', 'command', 'args', 'env', 'cwd', 'headers']);

package/src/modules/plugins/compile/marketplace-compiler.service.ts

@@ -0,0 +1,151 @@
+import path from 'node:path';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ISkillService } from '../../skills/skills.contract.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import type { PluginLinkIndex } from '../plugin-links.js';
+import type { PluginSource } from '../discovery/plugin-source.js';
+import type { ITreeWalker } from '../../../shared/fs.contract.js';
+import type { IGitRunner } from '../../../shared/git.contract.js';
+import { compileMarketplace, type VirtualTree } from './compile-marketplace.js';
+
+/** Whose view of the knowledge base to compile. */
+export type CompileAudience = { userEmail: string } | { everyone: true };
+
+/**
+ * The compiler wired to the live deployment: the default-branch checkout,
+ * the released catalog, the link index, and the access resolver as the read
+ * verdict. Every sink — the per-user git endpoint, a public mirror, a local
+ * export — asks this for a tree and writes it somewhere.
+ *
+ * Two audiences: a PERSON (their `canRead` per skill, exactly the catalog's
+ * filter) or EVERYONE (only what `read: everyone` reaches cleanly — the
+ * public subset a shared mirror may carry). Nothing in between: an audience
+ * that is "these three people" would need a union of verdicts nobody has
+ * asked for yet.
+ */
+export class MarketplaceCompilerService {
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly accessControl: IAccessControl,
+    private readonly skillService: ISkillService,
+    private readonly links: PluginLinkIndex,
+    private readonly kbDirName: string,
+    private readonly marketplace: {
+      name: string;
+      owner: string;
+      description?: string;
+      /** The hosted MCP endpoint to ship in the skills plugin (URL only). */
+      knowledgeBaseMcp?: { name: string; url: string };
+    },
+    private readonly source: PluginSource,
+    private readonly disk: ITreeWalker,
+    /** How git is run — see `shared/git.contract.ts`. */
+    private readonly gitRunner: IGitRunner,
+  ) {}
+
+  /**
+   * The default-branch commit the next compile would read. Throws when git
+   * cannot say: the repo service keys freshness on this value, and a stable
+   * placeholder would make every later compile look unnecessary — source
+   * changes and access revocations would never reach that caller again.
+   */
+  async sourceCommit(): Promise<string> {
+    const { kbRoot } = await this.checkout();
+    const { stdout } = await this.gitRunner.run(kbRoot, ['rev-parse', 'HEAD']);
+    const sha = stdout.trim();
+    // SHA-1 or SHA-256 object format: any hex object id is a commit.
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha)) {
+      throw new Error(`could not read the default branch's commit (${sha || 'empty'})`);
+    }
+    return sha;
+  }
+
+  async compileFor(
+    audience: CompileAudience,
+    /** The commit to stamp the tree with, when the caller already read it (the freshness check does). */
+    knownCommit?: string,
+  ): Promise<VirtualTree & { sourceCommit: string }> {
+    const { wsId, kbRoot } = await this.checkout();
+    // Strictness about the commit belongs to the FRESHNESS check (the repo
+    // service calls `sourceCommit()` itself and refuses to serve without
+    // one). A compile of a checkout git cannot describe still yields a
+    // correct tree; only its README and bundle version lose the sha.
+    const sourceCommit = knownCommit ?? (await this.sourceCommit().catch(() => 'unknown'));
+    // The tree is stamped with the checkout's commit, so every input must be
+    // read from that checkout NOW — not from a catalog scanned before the
+    // commit landed. The skill catalog, the link index and the access memo
+    // are TTL caches that nothing drops on an ordinary write (an MCP
+    // `write_files` moves HEAD and invalidates none of them), and the repo
+    // service keys freshness on the stamped commit: a tree compiled from a
+    // stale catalog under a fresh sha would be "current" until the NEXT
+    // commit, with the caller's marketplace frozen on content the knowledge
+    // base no longer has. Compiles run once per moved commit per caller, so
+    // the rescan is cheap where it matters.
+    this.skillService.invalidate();
+    this.links.invalidate();
+    this.accessControl.invalidate(wsId);
+    const skills = await this.skillService.listSkills(undefined);
+    const membership = await this.links.membership();
+    const { plugins, warnings: discoveryWarnings } = await this.source.discover(kbRoot);
+    const readable = await this.readPredicate(wsId, audience, skills.map((s) => `${s.path}/SKILL.md`));
+    const tree = await compileMarketplace({
+      disk: this.disk,
+      kbRoot,
+      skills,
+      plugins,
+      membership,
+      readable,
+      options: { ...this.marketplace, sourceCommit },
+    });
+    // Discovery's warnings ride with the compile's: a plugin left out for a
+    // malformed manifest or an unresolved MCP profile is otherwise an
+    // omission nobody can diagnose from the tree alone.
+    return { ...tree, warnings: [...discoveryWarnings, ...tree.warnings], sourceCommit };
+  }
+
+  // --- internal --------------------------------------------------------------
+
+  private async checkout(): Promise<{ wsId: string; kbRoot: string }> {
+    const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+    return { wsId, kbRoot: path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName) };
+  }
+
+  /**
+   * One batch verdict per compile, then a lookup. Fail closed both ways: a
+   * path the batch skipped is unreadable, and for the everyone audience a
+   * skill is public only when the resolver says `read: everyone` applies
+   * cleanly (`restricted: false`).
+   */
+  private async readPredicate(
+    wsId: string,
+    audience: CompileAudience,
+    docPaths: string[],
+  ): Promise<(repoPath: string) => Promise<boolean>> {
+    if ('userEmail' in audience) {
+      const verdicts = docPaths.length
+        ? await this.accessControl.canReadBatch(wsId, audience.userEmail, docPaths)
+        : new Map<string, boolean>();
+      return async (p) => verdicts.get(p) === true;
+    }
+    const cache = new Map<string, boolean>();
+    return async (p) => {
+      const hit = cache.get(p);
+      if (hit !== undefined) return hit;
+      let verdict = false;
+      try {
+        verdict = !(await this.accessControl.eligibleReaders(wsId, p)).restricted;
+      } catch {
+        verdict = false;
+      }
+      cache.set(p, verdict);
+      return verdict;
+    };
+  }
+}
+
+/** The default-branch workspace id compiles run against. */
+export function compileWorkspaceId(): string {
+  return workspaceIdForBranch(DEFAULT_BRANCH);
+}