@codemcp/ade 0.5.0 → 0.6.0

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

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/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>;

package/packages/harnesses/package.json

@@ -40,5 +40,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "version": "0.5.0"
+  "version": "0.6.0"
 }

package/packages/harnesses/src/index.spec.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from "vitest";
-import { allHarnessWriters, getHarnessWriter, getHarnessIds } from "./index.js";
+import {
+  allHarnessWriters,
+  getHarnessWriter,
+  getHarnessIds,
+  buildHarnessWriters
+} from "./index.js";
+import type { HarnessWriter } from "./types.js";
 
 describe("harness registry", () => {
   it("exports all harness writers", () => {
@@ -43,3 +49,44 @@ describe("harness registry", () => {
     }
   });
 });
+
+describe("buildHarnessWriters", () => {
+  it("returns all built-in writers when no extensions provided", () => {
+    const writers = buildHarnessWriters({});
+    expect(writers).toHaveLength(allHarnessWriters.length);
+    expect(writers.map((w) => w.id)).toEqual(
+      allHarnessWriters.map((w) => w.id)
+    );
+  });
+
+  it("appends extension harness writers after built-ins", () => {
+    const customWriter: HarnessWriter = {
+      id: "sap-copilot",
+      label: "SAP Copilot",
+      description: "SAP internal Copilot harness",
+      install: async () => {}
+    };
+
+    const writers = buildHarnessWriters({ harnessWriters: [customWriter] });
+    expect(writers).toHaveLength(allHarnessWriters.length + 1);
+    expect(writers.map((w) => w.id)).toContain("sap-copilot");
+    // built-ins come first
+    expect(writers[0].id).toBe("universal");
+    expect(writers[writers.length - 1].id).toBe("sap-copilot");
+  });
+
+  it("does not mutate allHarnessWriters", () => {
+    const originalLength = allHarnessWriters.length;
+    buildHarnessWriters({
+      harnessWriters: [
+        {
+          id: "ephemeral",
+          label: "Ephemeral",
+          description: "Should not persist",
+          install: async () => {}
+        }
+      ]
+    });
+    expect(allHarnessWriters).toHaveLength(originalLength);
+  });
+});

package/packages/harnesses/src/index.ts

@@ -45,3 +45,13 @@ export function getHarnessWriter(id: string): HarnessWriter | undefined {
 export function getHarnessIds(): string[] {
   return allHarnessWriters.map((w) => w.id);
 }
+
+/**
+ * Returns the full list of harness writers: built-ins first, then any
+ * additional writers contributed via extensions. Does not mutate allHarnessWriters.
+ */
+export function buildHarnessWriters(extensions: {
+  harnessWriters?: HarnessWriter[];
+}): HarnessWriter[] {
+  return [...allHarnessWriters, ...(extensions.harnessWriters ?? [])];
+}

package/pnpm-workspace.yaml

@@ -17,3 +17,5 @@ catalog:
   rimraf: "^6.1.3"
   tsx: "^4.19.0"
   tsup: "^8.3.0"
+  # Runtime
+  zod: "4.3.6"