@cursor/july 0.1.102 → 0.1.104

package/src/internal/discovery/extension-overlay.ts

@@ -0,0 +1,274 @@
+/**
+ * Directory-mount overlays: a same-named file replaces, disable() removes.
+ * Slot loaders do the walk; this file only applies replace/disable.
+ */
+
+import { join } from "node:path";
+import type {
+  ArtifactsDefinition,
+  DiscoveredAB,
+  DiscoveredChannel,
+  DiscoveredHook,
+  DiscoveredSchedule,
+  DiscoveredSkill,
+  ResolvedAgent,
+} from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { loadABs } from "./ab.js";
+import { loadChannels } from "./channels.js";
+import { type DiscoveryContext, displayPath, errorMessage } from "./context.js";
+import {
+  findModuleFile,
+  isDirectory,
+  isFile,
+  isModuleFile,
+  moduleStem,
+  sortedEntries,
+} from "./fs.js";
+import { loadHooks } from "./hooks.js";
+import { loadInstructions } from "./instructions.js";
+import { importDefault } from "./modules.js";
+import { loadSchedules } from "./schedules.js";
+import { loadSkills } from "./skills.js";
+import { loadSubagents } from "./subagent.js";
+
+export interface OverlaySite {
+  ns: string;
+}
+
+interface OverlaySlot<T> {
+  kind: "tool" | "connection";
+  disabledKind: "disabled-tool" | "disabled-connection";
+  disableHelper: string;
+  declared: ReadonlySet<string>;
+  compile: (
+    ctx: DiscoveryContext,
+    path: string,
+    name: string,
+    definition: unknown
+  ) => Promise<T | undefined> | T | undefined;
+}
+
+export async function overlaySlot<T extends { name: string }>(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, T>,
+  entries: Array<{ name: string; path: string }>,
+  slot: OverlaySlot<T>
+): Promise<void> {
+  for (const { name, path } of entries) {
+    const definition = await importDefault(ctx, path, [
+      slot.kind,
+      slot.disabledKind,
+      "disabled",
+    ]);
+    if (definition === undefined) {
+      continue;
+    }
+    const kind = getDefinitionKind(definition);
+    if (kind === slot.disabledKind || kind === "disabled") {
+      contributed.delete(name);
+      if (!slot.declared.has(name)) {
+        unknownContribution(ctx, path, slot.disableHelper, name, site.ns);
+      }
+      continue;
+    }
+    const item = await slot.compile(ctx, path, name, definition);
+    if (item !== undefined) {
+      contributed.set(name, item);
+    }
+  }
+}
+
+export async function overlaySkills(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, DiscoveredSkill>,
+  dir: string
+): Promise<void> {
+  await overlayNamed(ctx, site, contributed, dir, "disableSkill", (onDisable) =>
+    loadSkills(ctx, dir, onDisable)
+  );
+}
+
+export async function overlayHooks(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, DiscoveredHook>,
+  dir: string
+): Promise<void> {
+  await overlayNamed(ctx, site, contributed, dir, "disableHook", (onDisable) =>
+    loadHooks(ctx, dir, onDisable)
+  );
+}
+
+export async function overlaySchedules(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, DiscoveredSchedule>,
+  dir: string
+): Promise<void> {
+  await overlayNamed(
+    ctx,
+    site,
+    contributed,
+    dir,
+    "disableSchedule",
+    (onDisable) => loadSchedules(ctx, dir, onDisable)
+  );
+}
+
+export async function overlayChannels(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, DiscoveredChannel>,
+  dir: string
+): Promise<void> {
+  if (!(await isDirectory(dir))) {
+    return;
+  }
+  const declared = new Set(contributed.keys());
+  const { channels } = await loadChannels(ctx, dir, "extension", (id, path) => {
+    contributed.delete(id);
+    if (!declared.has(id)) {
+      unknownContribution(ctx, path, "disableChannel", id, site.ns);
+    }
+  });
+  for (const channel of channels) {
+    contributed.set(channel.id, channel);
+  }
+}
+
+export async function overlaySubagents(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, ResolvedAgent>,
+  dir: string
+): Promise<void> {
+  if (!(await isDirectory(dir))) {
+    return;
+  }
+  const declared = new Set(contributed.keys());
+  for (const child of await loadSubagents(ctx, dir)) {
+    contributed.set(child.name, child);
+  }
+  for (const entry of await sortedEntries(dir)) {
+    const path = join(dir, entry.name);
+    if (!entry.isFile() || !isModuleFile(entry.name)) {
+      continue;
+    }
+    const name = moduleStem(entry.name);
+    const definition = await importDefault(ctx, path, ["disabled"]);
+    if (definition === undefined) {
+      continue;
+    }
+    contributed.delete(name);
+    if (!declared.has(name)) {
+      unknownContribution(ctx, path, "disableSubagent", name, site.ns);
+    }
+  }
+}
+
+export async function overlayInstructionsFragment(
+  ctx: DiscoveryContext,
+  overlayDir: string
+): Promise<string | undefined | "keep"> {
+  const markdownPath = join(overlayDir, "instructions.md");
+  const modulePath = await findModuleFile(overlayDir, "instructions");
+  const instructionsDir = join(overlayDir, "instructions");
+  if (
+    !(await isFile(markdownPath)) &&
+    modulePath === undefined &&
+    !(await isDirectory(instructionsDir))
+  ) {
+    return "keep";
+  }
+  if (modulePath !== undefined) {
+    let mod: Record<string, unknown>;
+    try {
+      mod = await ctx.importModule(modulePath);
+    } catch (error) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, modulePath),
+        message: `Failed to load module: ${errorMessage(error)}`,
+      });
+      return "keep";
+    }
+    if (getDefinitionKind(mod.default) === "disabled") {
+      return undefined;
+    }
+  }
+  return loadInstructions(ctx, overlayDir, undefined, false);
+}
+
+export async function overlayAbs(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, DiscoveredAB>,
+  overlayDir: string
+): Promise<void> {
+  const loaded = await loadABs(ctx, overlayDir, (source, path) => {
+    if (!contributed.delete(source)) {
+      unknownContribution(ctx, path, "disableAB", source, site.ns);
+    }
+  });
+  for (const experiment of loaded) {
+    contributed.set(experiment.source ?? experiment.name, experiment);
+  }
+}
+
+export async function overlayArtifacts(
+  ctx: DiscoveryContext,
+  overlayDir: string,
+  current: ArtifactsDefinition | undefined
+): Promise<ArtifactsDefinition | undefined> {
+  const path = await findModuleFile(overlayDir, "artifacts");
+  if (path === undefined) {
+    return current;
+  }
+  const definition = await importDefault(ctx, path, ["artifacts", "disabled"]);
+  if (definition === undefined) {
+    return current;
+  }
+  if (getDefinitionKind(definition) === "disabled") {
+    return undefined;
+  }
+  return definition as ArtifactsDefinition;
+}
+
+async function overlayNamed<T extends { name: string }>(
+  ctx: DiscoveryContext,
+  site: OverlaySite,
+  contributed: Map<string, T>,
+  dir: string,
+  helper: string,
+  load: (onDisable: (name: string, path: string) => void) => Promise<T[]>
+): Promise<void> {
+  if (!(await isDirectory(dir))) {
+    return;
+  }
+  const declared = new Set(contributed.keys());
+  for (const item of await load((name, path) => {
+    contributed.delete(name);
+    if (!declared.has(name)) {
+      unknownContribution(ctx, path, helper, name, site.ns);
+    }
+  })) {
+    contributed.set(item.name, item);
+  }
+}
+
+function unknownContribution(
+  ctx: DiscoveryContext,
+  path: string,
+  helper: string,
+  name: string,
+  ns: string
+): void {
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, path),
+    message: `${helper}() targets "${name}", which extension "${ns}" does not contribute.`,
+  });
+}