@codemcp/ade 0.4.0 → 0.6.0

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/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.4.0"
+  "version": "0.6.0"
 }

package/packages/core/src/catalog/facets/process.ts

@@ -16,7 +16,16 @@ export const processFacet: Facet = {
           writer: "workflows",
           config: {
             package: "@codemcp/workflows-server@latest",
-            ref: "workflows"
+            ref: "workflows",
+            env: {
+              VIBE_WORKFLOW_DOMAINS: "skilled"
+            },
+            allowedTools: [
+              "whats_next",
+              "conduct_review",
+              "list_workflows",
+              "get_tool_info"
+            ]
           }
         },
         {

package/packages/core/src/catalog/index.ts

@@ -1,4 +1,4 @@
-import type { Catalog, Facet, Option } from "../types.js";
+import type { Catalog, Facet, Option, AdeExtensions } from "../types.js";
 import { processFacet } from "./facets/process.js";
 import { architectureFacet } from "./facets/architecture.js";
 import { practicesFacet } from "./facets/practices.js";
@@ -91,3 +91,40 @@ export function getVisibleOptions(
     return option.available(deps);
   });
 }
+
+/**
+ * Merges extension contributions into a catalog, returning a new catalog
+ * without mutating the original.
+ *
+ * - `extensions.facetContributions`: appends new options to existing facets
+ *   (silently ignores contributions for unknown facet ids)
+ * - `extensions.facets`: appends entirely new facets
+ */
+export function mergeExtensions(
+  catalog: Catalog,
+  extensions: AdeExtensions
+): Catalog {
+  // Deep-clone the facets array (shallow-clone each facet with a new options array)
+  let facets: Facet[] = catalog.facets.map((f) => ({
+    ...f,
+    options: [...f.options]
+  }));
+
+  // Append contributed options to existing facets
+  for (const [facetId, newOptions] of Object.entries(
+    extensions.facetContributions ?? {}
+  )) {
+    const facet = facets.find((f) => f.id === facetId);
+    if (facet) {
+      facet.options = [...facet.options, ...newOptions];
+    }
+    // Unknown facet ids are silently ignored
+  }
+
+  // Append entirely new facets
+  if (extensions.facets && extensions.facets.length > 0) {
+    facets = [...facets, ...extensions.facets];
+  }
+
+  return { facets };
+}

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

@@ -0,0 +1,169 @@
+import { describe, it, expect } from "vitest";
+import type { AdeExtensions } from "./types.js";
+import { AdeExtensionsSchema } from "./types.js";
+import { mergeExtensions } from "./catalog/index.js";
+import { getDefaultCatalog, getFacet, getOption } from "./catalog/index.js";
+
+// ─── AdeExtensionsSchema (Zod validation) ──────────────────────────────────
+
+describe("AdeExtensionsSchema", () => {
+  it("accepts an empty object (all fields optional)", () => {
+    const result = AdeExtensionsSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid facetContributions map", () => {
+    const ext: AdeExtensions = {
+      facetContributions: {
+        architecture: [
+          {
+            id: "sap",
+            label: "SAP",
+            description: "SAP BTP ABAP development",
+            recipe: [{ writer: "skills", config: { skills: [] } }]
+          }
+        ]
+      }
+    };
+    const result = AdeExtensionsSchema.safeParse(ext);
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid facets array (new facets)", () => {
+    const ext: AdeExtensions = {
+      facets: [
+        {
+          id: "custom-facet",
+          label: "Custom",
+          description: "A custom facet",
+          required: false,
+          options: []
+        }
+      ]
+    };
+    const result = AdeExtensionsSchema.safeParse(ext);
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts harnessWriters", () => {
+    const ext: AdeExtensions = {
+      harnessWriters: [
+        {
+          id: "my-harness",
+          label: "My Harness",
+          description: "Custom harness",
+          install: async () => {}
+        }
+      ]
+    };
+    const result = AdeExtensionsSchema.safeParse(ext);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects an invalid facetContributions value (wrong type)", () => {
+    const result = AdeExtensionsSchema.safeParse({
+      facetContributions: "not-an-object"
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a facetContributions option missing required fields", () => {
+    const result = AdeExtensionsSchema.safeParse({
+      facetContributions: {
+        architecture: [
+          { id: "sap" } // missing label, description, recipe
+        ]
+      }
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─── mergeExtensions ────────────────────────────────────────────────────────
+
+describe("mergeExtensions", () => {
+  it("returns the original catalog unchanged when extensions is empty", () => {
+    const original = getDefaultCatalog();
+    const merged = mergeExtensions(original, {});
+    expect(merged.facets).toHaveLength(original.facets.length);
+    expect(merged.facets.map((f) => f.id)).toEqual(
+      original.facets.map((f) => f.id)
+    );
+  });
+
+  it("adds new options to an existing facet via facetContributions", () => {
+    const catalog = getDefaultCatalog();
+    const sapOption = {
+      id: "sap",
+      label: "SAP BTP / ABAP",
+      description: "SAP BTP ABAP development",
+      recipe: [{ writer: "skills" as const, config: { skills: [] } }]
+    };
+
+    const merged = mergeExtensions(catalog, {
+      facetContributions: { architecture: [sapOption] }
+    });
+
+    const arch = getFacet(merged, "architecture")!;
+    expect(arch).toBeDefined();
+    const sap = getOption(arch, "sap");
+    expect(sap).toBeDefined();
+    expect(sap!.label).toBe("SAP BTP / ABAP");
+  });
+
+  it("does not mutate the original catalog", () => {
+    const catalog = getDefaultCatalog();
+    const originalArchOptionCount = getFacet(catalog, "architecture")!.options
+      .length;
+
+    mergeExtensions(catalog, {
+      facetContributions: {
+        architecture: [
+          {
+            id: "sap",
+            label: "SAP",
+            description: "SAP",
+            recipe: [{ writer: "skills" as const, config: { skills: [] } }]
+          }
+        ]
+      }
+    });
+
+    expect(getFacet(catalog, "architecture")!.options).toHaveLength(
+      originalArchOptionCount
+    );
+  });
+
+  it("appends entirely new facets from extensions.facets", () => {
+    const catalog = getDefaultCatalog();
+    const newFacet = {
+      id: "sap-specific",
+      label: "SAP Specific",
+      description: "SAP-specific choices",
+      required: false,
+      options: []
+    };
+
+    const merged = mergeExtensions(catalog, { facets: [newFacet] });
+    expect(merged.facets.map((f) => f.id)).toContain("sap-specific");
+    expect(merged.facets).toHaveLength(catalog.facets.length + 1);
+  });
+
+  it("ignores facetContributions for unknown facet ids (no crash)", () => {
+    const catalog = getDefaultCatalog();
+    const merged = mergeExtensions(catalog, {
+      facetContributions: {
+        "totally-unknown-facet": [
+          {
+            id: "x",
+            label: "X",
+            description: "X",
+            recipe: [{ writer: "skills" as const, config: { skills: [] } }]
+          }
+        ]
+      }
+    });
+    // Should not throw; catalog unchanged
+    expect(merged.facets).toHaveLength(catalog.facets.length);
+  });
+});

package/packages/core/src/index.ts

@@ -45,8 +45,10 @@ export {
   getFacet,
   getOption,
   sortFacets,
-  getVisibleOptions
+  getVisibleOptions,
+  mergeExtensions
 } from "./catalog/index.js";
+export { type AdeExtensions, AdeExtensionsSchema } from "./types.js";
 export { skillsWriter } from "./writers/skills.js";
 export { knowledgeWriter } from "./writers/knowledge.js";
 export { permissionPolicyWriter } from "./writers/permission-policy.js";

package/packages/core/src/registry.ts

@@ -5,6 +5,7 @@ import type {
 } from "./types.js";
 import { instructionWriter } from "./writers/instruction.js";
 import { workflowsWriter } from "./writers/workflows.js";
+import { mcpServerWriter } from "./writers/mcp-server.js";
 import { skillsWriter } from "./writers/skills.js";
 import { knowledgeWriter } from "./writers/knowledge.js";
 import { gitHooksWriter } from "./writers/git-hooks.js";
@@ -51,15 +52,15 @@ export function createDefaultRegistry(): WriterRegistry {
 
   registerProvisionWriter(registry, instructionWriter);
   registerProvisionWriter(registry, workflowsWriter);
+  registerProvisionWriter(registry, mcpServerWriter);
   registerProvisionWriter(registry, skillsWriter);
-
   registerProvisionWriter(registry, knowledgeWriter);
   registerProvisionWriter(registry, gitHooksWriter);
   registerProvisionWriter(registry, setupNoteWriter);
   registerProvisionWriter(registry, permissionPolicyWriter);
 
   // Stub writers for types not yet implemented
-  for (const id of ["mcp-server", "installable"]) {
+  for (const id of ["installable"]) {
     registerProvisionWriter(registry, {
       id,
       write: async () => ({})

package/packages/core/src/resolver.spec.ts

@@ -120,6 +120,35 @@ describe("resolve", () => {
       expect(result.mcp_servers.length).toBeGreaterThanOrEqual(1);
       expect(result.instructions).toContain("Extra instruction");
     });
+
+    it("env set in the catalog option config is forwarded to the resolved mcp_server entry", async () => {
+      const userConfig: UserConfig = {
+        choices: { process: "codemcp-workflows" }
+      };
+
+      // Patch the catalog option's provision config to include env
+      const processFacet = catalog.facets.find((f) => f.id === "process")!;
+      const option = processFacet.options.find(
+        (o) => o.id === "codemcp-workflows"
+      )!;
+      const workflowsProvision = option.recipe.find(
+        (p) => p.writer === "workflows"
+      )!;
+      workflowsProvision.config = {
+        ...workflowsProvision.config,
+        env: { VIBE_WORKFLOWS_DOMAIN: "skilled" }
+      };
+
+      const result = await resolve(userConfig, catalog, registry);
+
+      const workflowsServer = result.mcp_servers.find(
+        (s) => s.ref === "workflows"
+      );
+      expect(workflowsServer).toBeDefined();
+      expect(workflowsServer!.env).toEqual({
+        VIBE_WORKFLOWS_DOMAIN: "skilled"
+      });
+    });
   });
 
   describe("unknown facet in choices", () => {

package/packages/core/src/types.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 // --- Catalog types ---
 
 export interface Catalog {
@@ -157,3 +159,72 @@ export interface WriterRegistry {
   provisions: Map<string, ProvisionWriterDef>;
   agents: Map<string, AgentWriterDef>;
 }
+
+// --- Extension types ---
+
+/**
+ * Runtime validation helpers for extension file loading.
+ *
+ * We use z.custom<T>() for Option, Facet, HarnessWriter and ProvisionWriterDef
+ * because their TypeScript interfaces contain function types that Zod cannot
+ * faithfully represent without losing the concrete signature. z.custom<T>
+ * gives us the correct TS type while still letting us write a runtime check.
+ */
+const OptionSchema = z.custom<Option>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).label === "string" &&
+    typeof (val as Record<string, unknown>).description === "string" &&
+    Array.isArray((val as Record<string, unknown>).recipe),
+  { message: "Option must have id, label, description and recipe fields" }
+);
+
+const FacetSchema = z.custom<Facet>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).label === "string" &&
+    typeof (val as Record<string, unknown>).description === "string" &&
+    typeof (val as Record<string, unknown>).required === "boolean" &&
+    Array.isArray((val as Record<string, unknown>).options),
+  { message: "Facet must have id, label, description, required and options" }
+);
+
+const HarnessWriterSchema = z.custom<
+  AgentWriterDef & { label: string; description: string }
+>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).label === "string" &&
+    typeof (val as Record<string, unknown>).description === "string" &&
+    typeof (val as Record<string, unknown>).install === "function",
+  { message: "HarnessWriter must have id, label, description and install()" }
+);
+
+const ProvisionWriterDefSchema = z.custom<ProvisionWriterDef>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).write === "function",
+  { message: "ProvisionWriterDef must have id and write()" }
+);
+
+export const AdeExtensionsSchema = z.object({
+  /** Add new options to existing facets, keyed by facet id */
+  facetContributions: z.record(z.string(), z.array(OptionSchema)).optional(),
+  /** Add entirely new facets */
+  facets: z.array(FacetSchema).optional(),
+  /** Add new provision writers */
+  provisionWriters: z.array(ProvisionWriterDefSchema).optional(),
+  /** Add new harness writers */
+  harnessWriters: z.array(HarnessWriterSchema).optional()
+});
+
+/** The shape of a consumer's `ade.extensions.mjs` default export. */
+export type AdeExtensions = z.infer<typeof AdeExtensionsSchema>;