@codemcp/ade 0.5.0 → 0.6.0

package/packages/cli/dist/index.js

@@ -12793,6 +12793,22 @@ function getVisibleOptions(facet, choices, catalog) {
     return option.available(deps);
   });
 }
+function mergeExtensions(catalog, extensions) {
+  let facets = catalog.facets.map((f) => ({
+    ...f,
+    options: [...f.options]
+  }));
+  for (const [facetId, newOptions] of Object.entries(extensions.facetContributions ?? {})) {
+    const facet = facets.find((f) => f.id === facetId);
+    if (facet) {
+      facet.options = [...facet.options, ...newOptions];
+    }
+  }
+  if (extensions.facets && extensions.facets.length > 0) {
+    facets = [...facets, ...extensions.facets];
+  }
+  return { facets };
+}
 
 // ../core/dist/resolver.js
 async function resolve(userConfig, catalog, registry2) {
@@ -12948,6 +12964,23 @@ function collectDocsets(choices, catalog) {
   return Array.from(seen.values());
 }
 
+// ../core/dist/types.js
+import { z as z3 } from "zod";
+var OptionSchema = z3.custom((val) => typeof val === "object" && val !== null && typeof val.id === "string" && typeof val.label === "string" && typeof val.description === "string" && Array.isArray(val.recipe), { message: "Option must have id, label, description and recipe fields" });
+var FacetSchema = z3.custom((val) => typeof val === "object" && val !== null && typeof val.id === "string" && typeof val.label === "string" && typeof val.description === "string" && typeof val.required === "boolean" && Array.isArray(val.options), { message: "Facet must have id, label, description, required and options" });
+var HarnessWriterSchema = z3.custom((val) => typeof val === "object" && val !== null && typeof val.id === "string" && typeof val.label === "string" && typeof val.description === "string" && typeof val.install === "function", { message: "HarnessWriter must have id, label, description and install()" });
+var ProvisionWriterDefSchema = z3.custom((val) => typeof val === "object" && val !== null && typeof val.id === "string" && typeof val.write === "function", { message: "ProvisionWriterDef must have id and write()" });
+var AdeExtensionsSchema = z3.object({
+  /** Add new options to existing facets, keyed by facet id */
+  facetContributions: z3.record(z3.string(), z3.array(OptionSchema)).optional(),
+  /** Add entirely new facets */
+  facets: z3.array(FacetSchema).optional(),
+  /** Add new provision writers */
+  provisionWriters: z3.array(ProvisionWriterDefSchema).optional(),
+  /** Add new harness writers */
+  harnessWriters: z3.array(HarnessWriterSchema).optional()
+});
+
 // ../harnesses/dist/skills-installer.js
 import { join as join8 } from "path";
 
@@ -18080,7 +18113,7 @@ var V2 = "[";
 var nD = "]";
 var G2 = "m";
 var _2 = `${nD}8;;`;
-var z3 = (e2) => `${d.values().next().value}${V2}${e2}${G2}`;
+var z4 = (e2) => `${d.values().next().value}${V2}${e2}${G2}`;
 var K2 = (e2) => `${d.values().next().value}${_2}${e2}${y3}`;
 var aD = (e2) => e2.split(" ").map((u2) => p(u2));
 var k2 = (e2, u2, t2) => {
@@ -18141,8 +18174,8 @@ var lD = (e2, u2, t2 = {}) => {
     }
     const o2 = ED.codes.get(Number(s));
     n[E + 1] === `
-` ? (i && (F2 += K2("")), s && o2 && (F2 += z3(o2))) : a === `
-` && (s && o2 && (F2 += z3(s)), i && (F2 += K2(i)));
+` ? (i && (F2 += K2("")), s && o2 && (F2 += z4(o2))) : a === `
+` && (s && o2 && (F2 += z4(s)), i && (F2 += K2(i)));
   }
   return F2;
 };
@@ -22747,9 +22780,12 @@ function getHarnessWriter(id) {
 function getHarnessIds() {
   return allHarnessWriters.map((w2) => w2.id);
 }
+function buildHarnessWriters(extensions) {
+  return [...allHarnessWriters, ...extensions.harnessWriters ?? []];
+}
 
 // src/commands/setup.ts
-async function runSetup(projectRoot, catalog) {
+async function runSetup(projectRoot, catalog, harnessWriters = allHarnessWriters) {
   let lineIndex = 0;
   const LOGO_LINES = [
     "\n",
@@ -22843,13 +22879,13 @@ async function runSetup(projectRoot, catalog) {
     }
   }
   const existingHarnesses = existingConfig?.harnesses;
-  const harnessOptions = allHarnessWriters.map((w2) => ({
+  const harnessOptions = harnessWriters.map((w2) => ({
     value: w2.id,
     label: w2.label,
     hint: w2.description
   }));
   const validExistingHarnesses = existingHarnesses?.filter(
-    (h3) => allHarnessWriters.some((w2) => w2.id === h3)
+    (h3) => harnessWriters.some((w2) => w2.id === h3)
   );
   const selectedHarnesses = await Lt2({
     message: "Which coding agents should receive config?\nADE generates config files for each agent you select.\n",
@@ -22879,7 +22915,7 @@ async function runSetup(projectRoot, catalog) {
   };
   await writeLockFile(projectRoot, lockFile);
   for (const harnessId of harnesses) {
-    const writer = getHarnessWriter(harnessId);
+    const writer = harnessWriters.find((w2) => w2.id === harnessId) ?? getHarnessWriter(harnessId);
     if (writer) {
       await writer.install(logicalConfig, projectRoot);
     }
@@ -22967,24 +23003,25 @@ function promptMultiSelect(facet, existingChoices) {
 }
 
 // src/commands/install.ts
-async function runInstall(projectRoot, harnessIds) {
+async function runInstall(projectRoot, harnessIds, harnessWriters = allHarnessWriters) {
   Wt2("ade install");
   const lockFile = await readLockFile(projectRoot);
   if (!lockFile) {
     throw new Error("config.lock.yaml not found. Run `ade setup` first.");
   }
   const ids = harnessIds ?? lockFile.harnesses ?? ["universal"];
-  const validIds = getHarnessIds();
+  const validIds = [...getHarnessIds(), ...harnessWriters.map((w2) => w2.id)];
+  const uniqueValidIds = [...new Set(validIds)];
   for (const id of ids) {
-    if (!validIds.includes(id)) {
+    if (!uniqueValidIds.includes(id)) {
       throw new Error(
-        `Unknown harness "${id}". Available: ${validIds.join(", ")}`
+        `Unknown harness "${id}". Available: ${uniqueValidIds.join(", ")}`
       );
     }
   }
   const logicalConfig = lockFile.logical_config;
   for (const id of ids) {
-    const writer = getHarnessWriter(id);
+    const writer = harnessWriters.find((w2) => w2.id === id) ?? getHarnessWriter(id);
     if (writer) {
       await writer.install(logicalConfig, projectRoot);
     }
@@ -23023,15 +23060,62 @@ To use the latest defaults, remove .ade/skills/ and re-run install.`
   Gt("Install complete!");
 }
 
+// src/extensions.ts
+import { access as access3 } from "fs/promises";
+import { join as join19 } from "path";
+import { pathToFileURL } from "url";
+var SEARCH_ORDER = [
+  "ade.extensions.ts",
+  "ade.extensions.mjs",
+  "ade.extensions.js"
+];
+async function loadExtensions(projectRoot) {
+  for (const filename of SEARCH_ORDER) {
+    const filePath = join19(projectRoot, filename);
+    if (!await fileExists(filePath)) continue;
+    const mod = await loadModule(filePath, filename);
+    const raw = mod?.default ?? mod;
+    const result = AdeExtensionsSchema.safeParse(raw);
+    if (!result.success) {
+      throw new Error(
+        `Invalid ade.extensions file at ${filePath}:
+${result.error.message}`
+      );
+    }
+    return result.data;
+  }
+  return {};
+}
+async function fileExists(filePath) {
+  try {
+    await access3(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadModule(filePath, filename) {
+  if (filename.endsWith(".ts")) {
+    const { createJiti } = await import("jiti");
+    const jiti = createJiti(import.meta.url);
+    return jiti.import(filePath);
+  }
+  return import(pathToFileURL(filePath).href);
+}
+
 // src/index.ts
 var args = process.argv.slice(2);
 var command = args[0];
 if (command === "setup") {
   const projectRoot = args[1] ?? process.cwd();
-  const catalog = getDefaultCatalog();
-  await runSetup(projectRoot, catalog);
+  const extensions = await loadExtensions(projectRoot);
+  const catalog = mergeExtensions(getDefaultCatalog(), extensions);
+  const harnessWriters = buildHarnessWriters(extensions);
+  await runSetup(projectRoot, catalog, harnessWriters);
 } else if (command === "install") {
   const projectRoot = args[1] ?? process.cwd();
+  const extensions = await loadExtensions(projectRoot);
+  const harnessWriters = buildHarnessWriters(extensions);
   let harnessIds;
   if (args.includes("--harness")) {
     const val = args[args.indexOf("--harness") + 1];
@@ -23039,7 +23123,7 @@ if (command === "setup") {
       harnessIds = val.split(",").map((s) => s.trim());
     }
   }
-  await runInstall(projectRoot, harnessIds);
+  await runInstall(projectRoot, harnessIds, harnessWriters);
 } else if (command === "--version" || command === "-v") {
   console.log(version);
 } else {

package/packages/cli/package.json

@@ -28,7 +28,9 @@
     "@clack/prompts": "^1.1.0",
     "@codemcp/ade-core": "workspace:*",
     "@codemcp/ade-harnesses": "workspace:*",
-    "yaml": "^2.8.2"
+    "jiti": "2.6.1",
+    "yaml": "^2.8.2",
+    "zod": "catalog:"
   },
   "devDependencies": {
     "@codemcp/knowledge": "2.1.0",
@@ -39,5 +41,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "version": "0.5.0"
+  "version": "0.6.0"
 }

package/packages/cli/src/commands/extensions.integration.spec.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Mock only the TUI — everything else (catalog, registry, resolver, config I/O, writers) is real
+vi.mock("@clack/prompts", () => ({
+  intro: vi.fn(),
+  outro: vi.fn(),
+  note: vi.fn(),
+  select: vi.fn(),
+  multiselect: vi.fn(),
+  confirm: vi.fn().mockResolvedValue(false), // decline skill install prompt
+  isCancel: vi.fn().mockReturnValue(false),
+  cancel: vi.fn(),
+  log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), success: vi.fn() },
+  spinner: vi.fn().mockReturnValue({ start: vi.fn(), stop: vi.fn() })
+}));
+
+import * as clack from "@clack/prompts";
+import { runSetup } from "./setup.js";
+import {
+  readLockFile,
+  getDefaultCatalog,
+  mergeExtensions
+} from "@codemcp/ade-core";
+import type { AdeExtensions } from "@codemcp/ade-core";
+
+describe("extension e2e — option contributes skills and knowledge to setup output", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    vi.mocked(clack.confirm).mockResolvedValue(false); // don't install skills
+    dir = await mkdtemp(join(tmpdir(), "ade-ext-e2e-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it(
+    "extension-contributed architecture option writes inline skill and knowledge source",
+    { timeout: 60_000 },
+    async () => {
+      // Build an extension with a SAP option that has an inline skill + knowledge
+      const extensions: AdeExtensions = {
+        facetContributions: {
+          architecture: [
+            {
+              id: "sap-abap",
+              label: "SAP BTP / ABAP",
+              description: "SAP BTP ABAP Cloud development",
+              recipe: [
+                {
+                  writer: "skills",
+                  config: {
+                    skills: [
+                      {
+                        name: "sap-abap-code",
+                        description: "SAP ABAP coding guidelines",
+                        body: "# SAP ABAP Code\nUse ABAP Cloud APIs only."
+                      }
+                    ]
+                  }
+                },
+                {
+                  writer: "knowledge",
+                  config: {
+                    name: "sap-abap-docs",
+                    origin: "https://help.sap.com/docs/abap-cloud",
+                    description: "SAP ABAP Cloud documentation"
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      };
+
+      const catalog = mergeExtensions(getDefaultCatalog(), extensions);
+
+      // Facet order from sortFacets: process → architecture → practices → backpressure → autonomy
+      vi.mocked(clack.select)
+        .mockResolvedValueOnce("native-agents-md") // process
+        .mockResolvedValueOnce("sap-abap"); // architecture — the extended option
+      vi.mocked(clack.multiselect)
+        .mockResolvedValueOnce([]) // practices: none
+        // backpressure: sap-abap has no matching options so skipped
+        .mockResolvedValueOnce([]); // harnesses
+
+      await runSetup(dir, catalog);
+
+      // ── Skill should be staged to .ade/skills/sap-abap-code/SKILL.md ────
+      const skillMd = await readFile(
+        join(dir, ".ade", "skills", "sap-abap-code", "SKILL.md"),
+        "utf-8"
+      );
+      expect(skillMd).toContain("name: sap-abap-code");
+      expect(skillMd).toContain("SAP ABAP Code");
+      expect(skillMd).toContain("ABAP Cloud APIs only");
+
+      // ── Knowledge source should appear in the lock file ──────────────────
+      const lock = await readLockFile(dir);
+      expect(lock).not.toBeNull();
+      const knowledgeSources = lock!.logical_config.knowledge_sources;
+      expect(knowledgeSources).toHaveLength(1);
+      expect(knowledgeSources[0].name).toBe("sap-abap-docs");
+      expect(knowledgeSources[0].origin).toBe(
+        "https://help.sap.com/docs/abap-cloud"
+      );
+      expect(knowledgeSources[0].description).toBe(
+        "SAP ABAP Cloud documentation"
+      );
+
+      // ── config.yaml should record the extension option as the choice ──────
+      const { readUserConfig } = await import("@codemcp/ade-core");
+      const config = await readUserConfig(dir);
+      expect(config!.choices.architecture).toBe("sap-abap");
+    }
+  );
+});

package/packages/cli/src/commands/install.spec.ts

@@ -27,9 +27,29 @@ vi.mock("@codemcp/ade-core", async (importOriginal) => {
   };
 });
 
-const mockInstall = vi.fn().mockResolvedValue(undefined);
+const mockInstall = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
 
 vi.mock("@codemcp/ade-harnesses", () => ({
+  allHarnessWriters: [
+    {
+      id: "universal",
+      label: "Universal",
+      description: "Universal",
+      install: mockInstall
+    },
+    {
+      id: "claude-code",
+      label: "Claude Code",
+      description: "Claude Code",
+      install: mockInstall
+    },
+    {
+      id: "cursor",
+      label: "Cursor",
+      description: "Cursor",
+      install: mockInstall
+    }
+  ],
   getHarnessWriter: vi.fn().mockImplementation((id: string) => {
     if (id === "universal" || id === "claude-code" || id === "cursor") {
       return { id, install: mockInstall };

package/packages/cli/src/commands/install.ts

@@ -1,6 +1,8 @@
 import * as clack from "@clack/prompts";
 import { readLockFile } from "@codemcp/ade-core";
 import {
+  type HarnessWriter,
+  allHarnessWriters,
   getHarnessWriter,
   getHarnessIds,
   installSkills,
@@ -9,7 +11,8 @@ import {
 
 export async function runInstall(
   projectRoot: string,
-  harnessIds?: string[]
+  harnessIds?: string[],
+  harnessWriters: HarnessWriter[] = allHarnessWriters
 ): Promise<void> {
   clack.intro("ade install");
 
@@ -24,11 +27,12 @@ export async function runInstall(
   // 3. default: universal
   const ids = harnessIds ?? lockFile.harnesses ?? ["universal"];
 
-  const validIds = getHarnessIds();
+  const validIds = [...getHarnessIds(), ...harnessWriters.map((w) => w.id)];
+  const uniqueValidIds = [...new Set(validIds)];
   for (const id of ids) {
-    if (!validIds.includes(id)) {
+    if (!uniqueValidIds.includes(id)) {
       throw new Error(
-        `Unknown harness "${id}". Available: ${validIds.join(", ")}`
+        `Unknown harness "${id}". Available: ${uniqueValidIds.join(", ")}`
       );
     }
   }
@@ -36,7 +40,8 @@ export async function runInstall(
   const logicalConfig = lockFile.logical_config;
 
   for (const id of ids) {
-    const writer = getHarnessWriter(id);
+    const writer =
+      harnessWriters.find((w) => w.id === id) ?? getHarnessWriter(id);
     if (writer) {
       await writer.install(logicalConfig, projectRoot);
     }

package/packages/cli/src/commands/setup.ts

@@ -16,6 +16,7 @@ import {
   getVisibleOptions
 } from "@codemcp/ade-core";
 import {
+  type HarnessWriter,
   allHarnessWriters,
   getHarnessWriter,
   installSkills,
@@ -24,7 +25,8 @@ import {
 
 export async function runSetup(
   projectRoot: string,
-  catalog: Catalog
+  catalog: Catalog,
+  harnessWriters: HarnessWriter[] = allHarnessWriters
 ): Promise<void> {
   let lineIndex = 0;
   const LOGO_LINES = [
@@ -138,14 +140,14 @@ export async function runSetup(
 
   // Harness selection — multi-select from all available harnesses
   const existingHarnesses = existingConfig?.harnesses;
-  const harnessOptions = allHarnessWriters.map((w) => ({
+  const harnessOptions = harnessWriters.map((w) => ({
     value: w.id,
     label: w.label,
     hint: w.description
   }));
 
   const validExistingHarnesses = existingHarnesses?.filter((h) =>
-    allHarnessWriters.some((w) => w.id === h)
+    harnessWriters.some((w) => w.id === h)
   );
 
   const selectedHarnesses = await clack.multiselect({
@@ -188,7 +190,9 @@ export async function runSetup(
 
   // Install to all selected harnesses
   for (const harnessId of harnesses) {
-    const writer = getHarnessWriter(harnessId);
+    const writer =
+      harnessWriters.find((w) => w.id === harnessId) ??
+      getHarnessWriter(harnessId);
     if (writer) {
       await writer.install(logicalConfig, projectRoot);
     }

package/packages/cli/src/extensions.spec.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { loadExtensions } from "./extensions.js";
+import { tmpdir } from "node:os";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("loadExtensions", () => {
+  it("returns an empty object when no extensions file exists", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "ade-ext-test-"));
+    try {
+      const result = await loadExtensions(dir);
+      expect(result).toEqual({});
+    } finally {
+      await rm(dir, { recursive: true });
+    }
+  });
+
+  it("loads and validates a valid .mjs extensions file", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "ade-ext-test-"));
+    try {
+      await writeFile(
+        join(dir, "ade.extensions.mjs"),
+        `export default {
+          facetContributions: {
+            architecture: [
+              {
+                id: "sap",
+                label: "SAP BTP / ABAP",
+                description: "SAP BTP ABAP development",
+                recipe: [{ writer: "skills", config: { skills: [] } }]
+              }
+            ]
+          }
+        };`
+      );
+      const result = await loadExtensions(dir);
+      expect(result.facetContributions?.architecture).toHaveLength(1);
+      expect(result.facetContributions?.architecture?.[0].id).toBe("sap");
+    } finally {
+      await rm(dir, { recursive: true });
+    }
+  });
+
+  it("throws a descriptive error when the extensions file exports an invalid shape", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "ade-ext-test-"));
+    try {
+      await writeFile(
+        join(dir, "ade.extensions.mjs"),
+        `export default { facetContributions: "not-an-object" };`
+      );
+      await expect(loadExtensions(dir)).rejects.toThrow(/invalid/i);
+    } finally {
+      await rm(dir, { recursive: true });
+    }
+  });
+
+  it("loads a .js file when only .js exists", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "ade-ext-test-"));
+    try {
+      await writeFile(
+        join(dir, "ade.extensions.js"),
+        `export default {
+          facets: [
+            {
+              id: "js-only-facet",
+              label: "JS Only",
+              description: "From .js fallback",
+              required: false,
+              options: []
+            }
+          ]
+        };`
+      );
+      const result = await loadExtensions(dir);
+      expect(result.facets).toHaveLength(1);
+      expect(result.facets?.[0].id).toBe("js-only-facet");
+    } finally {
+      await rm(dir, { recursive: true });
+    }
+  });
+
+  it("prefers .mjs over .js when both exist", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "ade-ext-test-"));
+    try {
+      await writeFile(
+        join(dir, "ade.extensions.mjs"),
+        `export default { facets: [{ id: "from-mjs", label: "MJS", description: "MJS wins", required: false, options: [] }] };`
+      );
+      await writeFile(
+        join(dir, "ade.extensions.js"),
+        `export default { facets: [{ id: "from-js", label: "JS", description: "JS loses", required: false, options: [] }] };`
+      );
+      const result = await loadExtensions(dir);
+      expect(result.facets?.[0].id).toBe("from-mjs");
+    } finally {
+      await rm(dir, { recursive: true });
+    }
+  });
+
+  it("loads from an absolute path — simulating npx run from a different cwd", async () => {
+    // This is the published-package scenario:
+    // The CLI binary lives in ~/.npm/_npx/... but projectRoot is the user's cwd.
+    // loadExtensions(projectRoot) must look in projectRoot, not in the CLI package dir.
+    const userProjectDir = await mkdtemp(join(tmpdir(), "ade-user-project-"));
+    const cliPackageDir = await mkdtemp(join(tmpdir(), "ade-cli-package-"));
+    try {
+      // Simulate: user project has ade.extensions.mjs
+      await writeFile(
+        join(userProjectDir, "ade.extensions.mjs"),
+        `export default {
+          facets: [{ id: "user-project-facet", label: "User", description: "From user project", required: false, options: [] }]
+        };`
+      );
+      // CLI package dir has no extension file (it shouldn't be used)
+
+      // loadExtensions is called with the user's project dir as projectRoot
+      const result = await loadExtensions(userProjectDir);
+      expect(result.facets?.[0].id).toBe("user-project-facet");
+
+      // CLI package dir produces empty extensions — it is never consulted
+      const cliResult = await loadExtensions(cliPackageDir);
+      expect(cliResult).toEqual({});
+    } finally {
+      await rm(userProjectDir, { recursive: true });
+      await rm(cliPackageDir, { recursive: true });
+    }
+  });
+});

package/packages/cli/src/extensions.ts

@@ -0,0 +1,71 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { AdeExtensionsSchema, type AdeExtensions } from "@codemcp/ade-core";
+
+const SEARCH_ORDER = [
+  "ade.extensions.ts",
+  "ade.extensions.mjs",
+  "ade.extensions.js"
+] as const;
+
+/**
+ * Loads and validates the project's `ade.extensions` file (if any).
+ *
+ * Search order: ade.extensions.ts → ade.extensions.mjs → ade.extensions.js
+ *
+ * - `.ts` files are loaded via `jiti` for TypeScript support.
+ * - `.mjs` / `.js` files are loaded via native dynamic `import()`.
+ * - Returns `{}` when no extensions file exists.
+ * - Throws with a descriptive message when the file exports an invalid shape.
+ */
+export async function loadExtensions(
+  projectRoot: string
+): Promise<AdeExtensions> {
+  for (const filename of SEARCH_ORDER) {
+    const filePath = join(projectRoot, filename);
+
+    if (!(await fileExists(filePath))) continue;
+
+    // eslint-disable-next-line no-await-in-loop
+    const mod = await loadModule(filePath, filename);
+    const raw = mod?.default ?? mod;
+
+    const result = AdeExtensionsSchema.safeParse(raw);
+    if (!result.success) {
+      throw new Error(
+        `Invalid ade.extensions file at ${filePath}:\n${result.error.message}`
+      );
+    }
+
+    return result.data;
+  }
+
+  return {};
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadModule(
+  filePath: string,
+  filename: string
+): Promise<Record<string, unknown>> {
+  if (filename.endsWith(".ts")) {
+    // Use jiti for TypeScript support
+    const { createJiti } = await import("jiti");
+    const jiti = createJiti(import.meta.url);
+    return jiti.import(filePath) as Promise<Record<string, unknown>>;
+  }
+
+  // Native ESM for .mjs / .js
+  return import(pathToFileURL(filePath).href) as Promise<
+    Record<string, unknown>
+  >;
+}