@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/discovery/extensions.ts

@@ -1,490 +0,0 @@
-/**
- * `agent/extensions/<ns>.ts` | `agent/extensions/<ns>/extension.ts`:
- * agent-shaped trees and Cursor plugins mounted under a namespace.
- */
-
-import type { Dirent } from "node:fs";
-import { join, resolve } from "node:path";
-import type {
-  ArtifactsDefinition,
-  ConnectionDefinition,
-  DiscoveredChannel,
-  DiscoveredConnection,
-  DiscoveredExtension,
-  DiscoveredHook,
-  DiscoveredSchedule,
-  DiscoveredSkill,
-  DiscoveredTool,
-  ExtensionContributionSelection,
-  ExtensionMount,
-  ResolvedAgent,
-  SeedFile,
-  ToolDefinition,
-} from "../../types.js";
-import { buildIdentityPreamble, withIdentityPreamble } from "../workspace.js";
-import { loadChannels } from "./channels.js";
-import {
-  compileConnection,
-  compileHostConnection,
-  loadConnections,
-  loadHostConnections,
-} from "./connections.js";
-import { type DiscoveryContext, displayPath } from "./context.js";
-import { type CursorPluginAgent, readCursorPlugin } from "./cursor-plugin.js";
-import {
-  overlayArtifacts,
-  overlayChannels,
-  overlayHooks,
-  overlayInstructionsFragment,
-  overlaySchedules,
-  overlaySkills,
-  overlaySlot,
-  overlaySubagents,
-} from "./extension-overlay.js";
-import {
-  findModuleFile,
-  isDirectory,
-  isFile,
-  isModuleFile,
-  moduleStem,
-  sortedEntries,
-} from "./fs.js";
-import { loadHooks } from "./hooks.js";
-import { loadInstructions } from "./instructions.js";
-import { importDefault, moduleEntries } from "./modules.js";
-import { validateName } from "./names.js";
-import { loadSchedules } from "./schedules.js";
-import { loadSeedFiles } from "./seed-files.js";
-import { loadArtifacts, mergeArtifacts } from "./services.js";
-import { loadSkills } from "./skills.js";
-import { loadSubagents, subagent } from "./subagent.js";
-import { compileTool, loadTools } from "./tools.js";
-
-/** The agent's authored slot lists that mounted extensions append to. */
-export interface ExtensionContributions {
-  tools: DiscoveredTool[];
-  skills: DiscoveredSkill[];
-  connections: DiscoveredConnection[];
-  hostConnections: DiscoveredConnection[];
-  subagents: ResolvedAgent[];
-  hooks: DiscoveredHook[];
-  channels: DiscoveredChannel[];
-  schedules: DiscoveredSchedule[];
-  instructionParts: string[];
-  seedFiles: SeedFile[];
-  artifacts: ArtifactsDefinition | undefined;
-}
-
-/**
- * Mount every extension under `agent/extensions/` and append what it
- * contributes to the authored lists as `<ns>__<name>`, stamped with
- * `extension`. The namespace is the mount's filename stem or directory name.
- */
-export async function appendExtensions(
-  ctx: DiscoveryContext,
-  extensionsDir: string,
-  into: ExtensionContributions,
-): Promise<DiscoveredExtension[]> {
-  if (!(await isDirectory(extensionsDir))) {
-    return [];
-  }
-  const extensions: DiscoveredExtension[] = [];
-  for (const entry of await sortedEntries(extensionsDir)) {
-    const path = join(extensionsDir, entry.name);
-    const site = await resolveMountSite(ctx, path, entry);
-    if (site === undefined) {
-      continue;
-    }
-    if (extensions.some(extension => extension.name === site.ns)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, path),
-        message: `Extension "${site.ns}" is mounted twice (as a file and as a directory).`,
-      });
-      continue;
-    }
-    const mount = await importDefault(ctx, site.mountPath, "extension");
-    if (mount === undefined) {
-      continue;
-    }
-    extensions.push(await mountExtension(ctx, site, mount as ExtensionMount, into));
-  }
-  return extensions;
-}
-
-interface MountSite {
-  ns: string;
-  /** The module default-exporting the {@link ExtensionMount}. */
-  mountPath: string;
-  /** A directory mount; its slots overlay the extension's. */
-  overlayDir?: string;
-}
-
-async function resolveMountSite(
-  ctx: DiscoveryContext,
-  path: string,
-  entry: Dirent,
-): Promise<MountSite | undefined> {
-  if (entry.isDirectory()) {
-    if (!validateName(ctx, "extension", entry.name, path)) {
-      return undefined;
-    }
-    const mountPath = await findModuleFile(path, "extension");
-    if (mountPath === undefined) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, path),
-        message:
-          "A directory mount needs an extension.ts default-exporting the mount (`export default ci({ ... })`).",
-      });
-      return undefined;
-    }
-    return { ns: entry.name, mountPath, overlayDir: path };
-  }
-  if (!entry.isFile() || !isModuleFile(entry.name)) {
-    return undefined;
-  }
-  const ns = moduleStem(entry.name);
-  return validateName(ctx, "extension", ns, path) ? { ns, mountPath: path } : undefined;
-}
-
-/** What a mounted tree contributes, under the tree's own names. */
-interface ExtensionTree {
-  description?: string;
-  tools: DiscoveredTool[];
-  skills: DiscoveredSkill[];
-  connections: DiscoveredConnection[];
-  hostConnections: DiscoveredConnection[];
-  /** Connection names the tree declares but left to the mount's overlay. */
-  overlaidServers: string[];
-  agents: CursorPluginAgent[];
-  subagents: ResolvedAgent[];
-  hooks: DiscoveredHook[];
-  channels: DiscoveredChannel[];
-  schedules: DiscoveredSchedule[];
-  instructions?: string;
-  seedFiles: SeedFile[];
-  artifacts?: ArtifactsDefinition;
-}
-
-function emptyDiscovered(ns: string, description?: string): DiscoveredExtension {
-  return {
-    name: ns,
-    description,
-    tools: [],
-    skills: [],
-    connections: [],
-    hostConnections: [],
-    subagents: [],
-    hooks: [],
-    channels: [],
-    schedules: [],
-    instructions: false,
-    seedFiles: [],
-    artifactKinds: [],
-  };
-}
-
-/**
- * Read the extension's tree, lay the mount's overlay on top (a same-named
- * file replaces, `disable()` / `disableTool()` removes), then namespace
- * what is left.
- */
-async function mountExtension(
-  ctx: DiscoveryContext,
-  site: MountSite,
-  mount: ExtensionMount,
-  into: ExtensionContributions,
-): Promise<DiscoveredExtension> {
-  const mounted = emptyDiscovered(site.ns, mount.extension.description);
-  const root = resolve(ctx.rootDir, mount.extension.root);
-  if (!(await isDirectory(root))) {
-    const hint =
-      "layout" in mount.extension
-        ? "Point `path` at the plugin directory."
-        : "Pass `import.meta.dirname` from extension.ts.";
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, site.mountPath),
-      message: `Extension "${site.ns}" declares root ${root}, which is not a directory. ${hint}`,
-    });
-    return mounted;
-  }
-  const tree = await readExtensionTree(ctx, site, mount, root);
-  if (tree === undefined) {
-    return mounted;
-  }
-  mounted.description = mount.extension.description ?? tree.description;
-
-  const tools = byName(tree.tools);
-  const skills = byName(tree.skills);
-  const connections = byName(tree.connections);
-  const hostConnections = byName(tree.hostConnections);
-  const hooks = byName(tree.hooks);
-  const channels = byId(tree.channels);
-  const schedules = byName(tree.schedules);
-  const subagents = byName(tree.subagents);
-  for (const agent of tree.agents) {
-    subagents.set(agent.name, subagent(agent.name, agent));
-  }
-  const seedFiles = new Map(tree.seedFiles.map(seed => [seed.relativePath, seed]));
-  let artifacts = tree.artifacts;
-  let instructions = tree.instructions;
-
-  if (site.overlayDir !== undefined) {
-    const connectionOverlay = await moduleEntries(
-      ctx,
-      join(site.overlayDir, "mcp-connections"),
-      "connection",
-    );
-    await overlaySlot(
-      ctx,
-      site,
-      tools,
-      await moduleEntries(ctx, join(site.overlayDir, "tools"), "tool"),
-      {
-        kind: "tool",
-        disabledKind: "disabled-tool",
-        disableHelper: "disableTool",
-        declared: new Set(tools.keys()),
-        compile: (ctx, path, name, definition) =>
-          compileTool(ctx, path, name, definition as ToolDefinition),
-      },
-    );
-    await overlaySlot(ctx, site, connections, connectionOverlay, {
-      kind: "connection",
-      disabledKind: "disabled-connection",
-      disableHelper: "disableConnection",
-      declared: new Set([...connections.keys(), ...tree.overlaidServers]),
-      compile: (ctx, path, name, definition) =>
-        compileConnection(ctx, path, name, definition as ConnectionDefinition, "model"),
-    });
-    await overlaySlot(
-      ctx,
-      site,
-      hostConnections,
-      await moduleEntries(ctx, join(site.overlayDir, "host-connections"), "connection"),
-      {
-        kind: "connection",
-        disabledKind: "disabled-connection",
-        disableHelper: "disableConnection",
-        declared: new Set(hostConnections.keys()),
-        compile: (ctx, path, name, definition) =>
-          compileHostConnection(ctx, path, name, definition as ConnectionDefinition),
-      },
-    );
-    await overlaySkills(ctx, site, skills, join(site.overlayDir, "skills"));
-    await overlayHooks(ctx, site, hooks, join(site.overlayDir, "hooks"));
-    await overlayChannels(ctx, site, channels, join(site.overlayDir, "channels"));
-    await overlaySchedules(ctx, site, schedules, join(site.overlayDir, "schedules"));
-    await overlaySubagents(ctx, site, subagents, join(site.overlayDir, "subagents"));
-    const overlayInstructions = await overlayInstructionsFragment(ctx, site.overlayDir);
-    if (overlayInstructions !== "keep") {
-      instructions = overlayInstructions;
-    }
-    for (const seed of await loadSeedFiles(ctx, site.overlayDir)) {
-      seedFiles.set(seed.relativePath, seed);
-    }
-    artifacts = await overlayArtifacts(ctx, site.overlayDir, artifacts);
-  }
-
-  for (const [name, tool] of tools) {
-    const composed = `${site.ns}__${name}`;
-    into.tools.push({ ...tool, name: composed, extension: site.ns });
-    mounted.tools.push(composed);
-  }
-  for (const [name, skill] of skills) {
-    const composed = `${site.ns}__${name}`;
-    into.skills.push({ ...skill, name: composed, extension: site.ns });
-    mounted.skills.push(composed);
-  }
-  const modelNames = new Set<string>();
-  for (const [name, connection] of connections) {
-    const composed = `${site.ns}__${name}`;
-    modelNames.add(composed);
-    into.connections.push({ ...connection, name: composed });
-    mounted.connections.push(composed);
-  }
-  for (const [name, connection] of hostConnections) {
-    const composed = `${site.ns}__${name}`;
-    if (modelNames.has(composed)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, join(root, "host-connections", `${name}.ts`)),
-        message: `Host connection "${composed}" collides with MCP connection "${composed}". Rename one of them.`,
-      });
-      continue;
-    }
-    into.hostConnections.push({ ...connection, name: composed });
-    mounted.hostConnections.push(composed);
-  }
-  for (const [name, child] of subagents) {
-    const composed = `${site.ns}__${name}`;
-    into.subagents.push(namespaceSubagent(composed, child));
-    mounted.subagents.push(composed);
-  }
-  for (const [name, hook] of hooks) {
-    const composed = `${site.ns}__${name}`;
-    into.hooks.push({ ...hook, name: composed });
-    mounted.hooks.push(composed);
-  }
-  for (const [id, channel] of channels) {
-    const composed = `${site.ns}__${id}`;
-    into.channels.push({ ...channel, id: composed });
-    mounted.channels.push(composed);
-  }
-  for (const [name, schedule] of schedules) {
-    const composed = `${site.ns}__${name}`;
-    into.schedules.push({ ...schedule, name: composed });
-    mounted.schedules.push(composed);
-  }
-  if (instructions !== undefined && instructions !== "") {
-    into.instructionParts.push(instructions);
-    mounted.instructions = true;
-  }
-  for (const seed of seedFiles.values()) {
-    if (into.seedFiles.some(existing => existing.relativePath === seed.relativePath)) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, seed.sourcePath),
-        message: `Extension seed "${seed.relativePath}" collides with an existing workspace seed; keeping the first.`,
-      });
-      continue;
-    }
-    into.seedFiles.push(seed);
-    mounted.seedFiles.push(seed.relativePath);
-  }
-  if (artifacts !== undefined) {
-    const kinds: NonNullable<ArtifactsDefinition["kinds"]> = {};
-    for (const [kind, config] of Object.entries(artifacts.kinds ?? {})) {
-      const composed = `${site.ns}__${kind}`;
-      kinds[composed] = config;
-      mounted.artifactKinds.push(composed);
-    }
-    into.artifacts = mergeArtifacts(into.artifacts, {
-      ...artifacts,
-      kinds,
-    });
-  }
-  return mounted;
-}
-
-async function readExtensionTree(
-  ctx: DiscoveryContext,
-  site: MountSite,
-  mount: ExtensionMount,
-  root: string,
-): Promise<ExtensionTree | undefined> {
-  if ("layout" in mount.extension) {
-    const connectionOverlay =
-      site.overlayDir === undefined
-        ? []
-        : await moduleEntries(ctx, join(site.overlayDir, "mcp-connections"), "connection");
-    const plugin = await readCursorPlugin(
-      ctx,
-      root,
-      site.mountPath,
-      mount.extension.variables,
-      new Set(connectionOverlay.map(entry => entry.name)),
-    );
-    if (plugin === undefined) {
-      return undefined;
-    }
-    return {
-      ...plugin,
-      tools: [],
-      hostConnections: [],
-      subagents: [],
-      hooks: [],
-      channels: [],
-      schedules: [],
-      seedFiles: [],
-    };
-  }
-  return readNativeTree(ctx, root, mount.contributions);
-}
-
-async function readNativeTree(
-  ctx: DiscoveryContext,
-  root: string,
-  contributions?: ExtensionContributionSelection,
-): Promise<ExtensionTree> {
-  await warnAgentRootOnlySlots(ctx, root);
-  const connections = await loadConnections(ctx, join(root, "mcp-connections"));
-  return {
-    tools: contributions?.tools === false ? [] : await loadTools(ctx, join(root, "tools")),
-    skills: contributions?.skills === false ? [] : await loadSkills(ctx, join(root, "skills")),
-    connections,
-    hostConnections: await loadHostConnections(ctx, root, connections),
-    overlaidServers: [],
-    agents: [],
-    subagents: await loadSubagents(ctx, join(root, "subagents")),
-    hooks: await loadHooks(ctx, join(root, "hooks")),
-    channels: (await loadChannels(ctx, join(root, "channels"), "extension")).channels,
-    schedules: await loadSchedules(ctx, join(root, "schedules")),
-    instructions: await loadInstructions(ctx, root, undefined, false),
-    seedFiles: await loadSeedFiles(ctx, root),
-    artifacts: await loadArtifacts(ctx, root),
-  };
-}
-
-function namespaceSubagent(composed: string, child: ResolvedAgent): ResolvedAgent {
-  const oldPreamble = buildIdentityPreamble(child.name);
-  let body = child.instructions;
-  if (body !== undefined && oldPreamble !== "" && body.startsWith(oldPreamble)) {
-    body = body.slice(oldPreamble.length).replace(/^\n+/, "");
-  }
-  return {
-    ...child,
-    name: composed,
-    instructions: withIdentityPreamble(composed, body),
-  };
-}
-
-function byName<T extends { name: string }>(items: T[]): Map<string, T> {
-  return new Map(items.map(item => [item.name, item]));
-}
-
-function byId<T extends { id: string }>(items: T[]): Map<string, T> {
-  return new Map(items.map(item => [item.id, item]));
-}
-
-/**
- * Agent-singleton slots: one runtime (`agent.ts`), one storage backend,
- * one OTLP exporter. Playground chips are a Vite glob of the agent tree,
- * not a discovery walk. Nested `extensions/` are not mounted.
- */
-async function warnAgentRootOnlySlots(ctx: DiscoveryContext, root: string): Promise<void> {
-  const files = [
-    ["agent.ts", "agent.ts"],
-    ["storage.ts", "storage"],
-    ["otel.ts", "otel"],
-  ] as const;
-  for (const [file, label] of files) {
-    const path = join(root, file);
-    if (await isFile(path)) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, path),
-        message: `The agent that mounts this extension owns ${label}; ignoring.`,
-      });
-    }
-  }
-  const dirs = [
-    [
-      "playground",
-      "Playground chips are a Vite glob of the agent tree, not an extension slot; ignoring.",
-    ],
-    ["extensions", "Nested extensions are not mounted; ignoring."],
-  ] as const;
-  for (const [slot, message] of dirs) {
-    const path = join(root, slot);
-    if (await isDirectory(path)) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, path),
-        message,
-      });
-    }
-  }
-}

package/src/internal/discovery/fs.ts

@@ -1,103 +0,0 @@
-/**
- * Filesystem primitives discovery walks with: module-file detection, directory listing, and project-root markers.
- */
-
-import type { Dirent } from "node:fs";
-import { readdir, readFile, stat } from "node:fs/promises";
-import { extname, join } from "node:path";
-
-const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
-
-export async function findModuleFile(dir: string, stem: string): Promise<string | undefined> {
-  for (const extension of [".ts", ".mts", ".js", ".mjs"]) {
-    const candidate = join(dir, `${stem}${extension}`);
-    if (await isFile(candidate)) {
-      return candidate;
-    }
-  }
-  return undefined;
-}
-
-export function isModuleFile(fileName: string): boolean {
-  if (fileName.endsWith(".d.ts") || fileName.startsWith(".")) {
-    return false;
-  }
-  if (!MODULE_EXTENSIONS.has(extname(fileName))) {
-    return false;
-  }
-  // Colocated unit tests (Vitest/Jest convention) are not definitions.
-  // Without this, `channels/slack.test.ts` is scanned as a channel named
-  // "slack.test", fails NAME_PATTERN, and the whole agent refuses to serve.
-  const stem = moduleStem(fileName);
-  return !stem.endsWith(".test") && !stem.endsWith(".spec");
-}
-
-export function moduleStem(fileName: string): string {
-  return fileName.slice(0, -extname(fileName).length);
-}
-
-export async function sortedEntries(dir: string): Promise<Dirent[]> {
-  const entries = await readdir(dir, { withFileTypes: true });
-  return entries.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-export async function walkFiles(dir: string): Promise<string[]> {
-  const files: string[] = [];
-  for (const entry of await sortedEntries(dir)) {
-    if (entry.name.startsWith(".")) {
-      continue;
-    }
-    const entryPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...(await walkFiles(entryPath)));
-    } else if (entry.isFile()) {
-      files.push(entryPath);
-    }
-  }
-  return files;
-}
-
-export async function isDirectory(path: string): Promise<boolean> {
-  try {
-    return (await stat(path)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-export async function isFile(path: string): Promise<boolean> {
-  try {
-    return (await stat(path)).isFile();
-  } catch {
-    return false;
-  }
-}
-
-export function toPosix(path: string): string {
-  return path.split("\\").join("/");
-}
-
-export async function hasFlatLayoutMarkers(rootDir: string): Promise<boolean> {
-  if (await isFile(join(rootDir, "instructions.md"))) {
-    return true;
-  }
-  return (await findModuleFile(rootDir, "agent")) !== undefined;
-}
-
-export async function readPackageName(rootDir: string): Promise<string | undefined> {
-  const packageJsonPath = join(rootDir, "package.json");
-  if (!(await isFile(packageJsonPath))) {
-    return undefined;
-  }
-  try {
-    const parsed = JSON.parse(await readFile(packageJsonPath, "utf8")) as {
-      name?: unknown;
-    };
-    if (typeof parsed.name === "string" && parsed.name !== "") {
-      return parsed.name;
-    }
-  } catch {
-    // Malformed package.json falls back to the directory name.
-  }
-  return undefined;
-}

package/src/internal/discovery/hooks.ts

@@ -1,63 +0,0 @@
-/**
- * `agent/hooks/*.ts`: observe-only event subscribers.
- */
-
-import { basename, extname, relative } from "node:path";
-import type { DiscoveredHook, HookDefinition } from "../../types.js";
-import { getDefinitionKind } from "../brand.js";
-import { type DiscoveryContext, displayPath } from "./context.js";
-import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
-import { importDefault } from "./modules.js";
-
-export async function loadHooks(
-  ctx: DiscoveryContext,
-  hooksDir: string,
-  onDisable?: (name: string, path: string) => void,
-): Promise<DiscoveredHook[]> {
-  if (!(await isDirectory(hooksDir))) {
-    return [];
-  }
-  const hooks: DiscoveredHook[] = [];
-  for (const filePath of await walkFiles(hooksDir)) {
-    if (!isModuleFile(basename(filePath))) {
-      continue;
-    }
-    const rel = toPosix(relative(hooksDir, filePath));
-    const name = rel.slice(0, -extname(rel).length);
-    if (name.includes("__")) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, filePath),
-        message: `Hook name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
-      });
-      continue;
-    }
-    const definition = await importDefault(
-      ctx,
-      filePath,
-      onDisable === undefined ? "hook" : ["hook", "disabled"],
-    );
-    if (definition === undefined) {
-      continue;
-    }
-    if (getDefinitionKind(definition) === "disabled") {
-      onDisable?.(name, filePath);
-      continue;
-    }
-    const hook = definition as HookDefinition;
-    if (
-      typeof hook.events !== "object" ||
-      hook.events === null ||
-      Object.keys(hook.events).length === 0
-    ) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, filePath),
-        message: "Hook declares no event handlers.",
-      });
-      continue;
-    }
-    hooks.push({ name, definition: hook });
-  }
-  return hooks;
-}