@cursor/july 0.1.101 → 0.1.103

package/src/internal/discovery/extensions.ts

@@ -0,0 +1,573 @@
+/**
+ * `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,
+  DiscoveredAB,
+  DiscoveredChannel,
+  DiscoveredConnection,
+  DiscoveredExtension,
+  DiscoveredHook,
+  DiscoveredSchedule,
+  DiscoveredSkill,
+  DiscoveredTool,
+  ExtensionMount,
+  ResolvedAgent,
+  SeedFile,
+  ToolDefinition,
+} from "../../types.js";
+import { buildIdentityPreamble, withIdentityPreamble } from "../workspace.js";
+import { loadABs } from "./ab.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 {
+  overlayAbs,
+  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[];
+  abs: DiscoveredAB[];
+  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[];
+  abs: DiscoveredAB[];
+  artifacts?: ArtifactsDefinition;
+}
+
+function emptyDiscovered(
+  ns: string,
+  description?: string
+): DiscoveredExtension {
+  return {
+    name: ns,
+    description,
+    tools: [],
+    skills: [],
+    connections: [],
+    hostConnections: [],
+    subagents: [],
+    hooks: [],
+    channels: [],
+    schedules: [],
+    instructions: false,
+    seedFiles: [],
+    abs: [],
+    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])
+  );
+  const abs = byAbSource(tree.abs);
+  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);
+    }
+    await overlayAbs(ctx, site, abs, site.overlayDir);
+    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);
+  }
+  for (const experiment of abs.values()) {
+    const composed = `${site.ns}__${experiment.name}`;
+    into.abs.push({
+      name: composed,
+      definition: experiment.definition,
+    });
+    mounted.abs.push(composed);
+  }
+  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: [],
+      abs: [],
+    };
+  }
+  return readNativeTree(ctx, root);
+}
+
+async function readNativeTree(
+  ctx: DiscoveryContext,
+  root: string
+): Promise<ExtensionTree> {
+  await warnAgentRootOnlySlots(ctx, root);
+  const connections = await loadConnections(ctx, join(root, "mcp-connections"));
+  return {
+    tools: await loadTools(ctx, join(root, "tools")),
+    skills: 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),
+    abs: await loadABs(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 byAbSource(items: DiscoveredAB[]): Map<string, DiscoveredAB> {
+  return new Map(items.map((item) => [item.source ?? 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, one A/B platform config. 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"],
+    ["ab.config.ts", "A/B config"],
+  ] 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

@@ -0,0 +1,108 @@
+/**
+ * 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;
+}