@codemcp/ade 0.5.0 → 0.6.1

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.1"
 }

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>
+  >;
+}

package/packages/cli/src/index.ts

@@ -3,18 +3,23 @@
 import { version } from "./version.js";
 import { runSetup } from "./commands/setup.js";
 import { runInstall } from "./commands/install.js";
-import { getDefaultCatalog } from "@codemcp/ade-core";
-import { getHarnessIds } from "@codemcp/ade-harnesses";
+import { getDefaultCatalog, mergeExtensions } from "@codemcp/ade-core";
+import { getHarnessIds, buildHarnessWriters } from "@codemcp/ade-harnesses";
+import { loadExtensions } from "./extensions.js";
 
 const args = process.argv.slice(2);
 const 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: string[] | undefined;
 
@@ -26,7 +31,7 @@ if (command === "setup") {
     }
   }
 
-  await runInstall(projectRoot, harnessIds);
+  await runInstall(projectRoot, harnessIds, harnessWriters);
 } else if (command === "--version" || command === "-v") {
   console.log(version);
 } else {

package/packages/cli/tsup.config.ts

@@ -7,7 +7,13 @@ export default defineConfig({
   tsconfig: "tsconfig.build.json",
   target: "node22",
   clean: true,
-  noExternal: ["@clack/prompts", "@codemcp/ade-core", "@codemcp/ade-harnesses"],
+  noExternal: [
+    "@clack/prompts",
+    "@codemcp/ade-core",
+    "@codemcp/ade-harnesses",
+    "yaml",
+    "zod"
+  ],
   esbuildOptions(options) {
     options.banner = {
       js: `import { createRequire } from 'module'; const require = createRequire(import.meta.url);`

package/packages/core/package.json

@@ -28,7 +28,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.2",
+    "zod": "catalog:"
   },
   "devDependencies": {
     "oxlint": "catalog:",
@@ -38,5 +39,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "version": "0.5.0"
+  "version": "0.6.1"
 }