@codemcp/ade 0.7.0 → 0.8.0

package/packages/cli/src/knowledge-installer.spec.ts

@@ -56,6 +56,24 @@ describe("installKnowledge", () => {
     );
   });
 
+  it("uses source.preset when provided instead of defaulting to git-repo", async () => {
+    const sources: KnowledgeSource[] = [
+      {
+        name: "my-archive",
+        origin: "https://example.com/docs.tar.gz",
+        description: "Archive docs",
+        preset: "archive"
+      }
+    ];
+
+    await installKnowledge(sources, "/tmp/project");
+
+    expect(createDocset).toHaveBeenCalledWith(
+      expect.objectContaining({ preset: "archive" }),
+      expect.anything()
+    );
+  });
+
   it("calls initDocset for each knowledge source after creation", async () => {
     const sources: KnowledgeSource[] = [
       {
@@ -76,9 +94,9 @@ describe("installKnowledge", () => {
     );
   });
 
-  it("continues with remaining sources when one fails", async () => {
+  it("continues with remaining sources when createDocset fails with a real error", async () => {
     vi.mocked(createDocset)
-      .mockRejectedValueOnce(new Error("already exists"))
+      .mockRejectedValueOnce(new Error("network error"))
       .mockResolvedValueOnce({
         docset: {},
         configPath: ".knowledge/config.yaml",
@@ -102,10 +120,32 @@ describe("installKnowledge", () => {
 
     // Should have attempted both
     expect(createDocset).toHaveBeenCalledTimes(2);
-    // initDocset only called for the successful one
+    // initDocset only called for the successful one (real error skips it)
     expect(initDocset).toHaveBeenCalledTimes(1);
     expect(initDocset).toHaveBeenCalledWith(
       expect.objectContaining({ docsetId: "succeeding" })
     );
   });
+
+  it("proceeds to initDocset when createDocset reports docset already exists", async () => {
+    vi.mocked(createDocset).mockRejectedValueOnce(
+      new Error("Docset with ID 'react-docs' already exists")
+    );
+
+    const sources: KnowledgeSource[] = [
+      {
+        name: "react-docs",
+        origin: "https://github.com/facebook/react.git",
+        description: "React documentation"
+      }
+    ];
+
+    await installKnowledge(sources, "/tmp/project");
+
+    // createDocset failed with "already exists" — initDocset must still be called
+    expect(initDocset).toHaveBeenCalledTimes(1);
+    expect(initDocset).toHaveBeenCalledWith(
+      expect.objectContaining({ docsetId: "react-docs" })
+    );
+  });
 });

package/packages/cli/src/knowledge-installer.ts

@@ -8,7 +8,7 @@ import {
  * Install knowledge sources using the @codemcp/knowledge programmatic API.
  *
  * For each knowledge source:
- * 1. Creates a docset config entry via `createDocset`
+ * 1. Creates a docset config entry via `createDocset` (skips if already exists)
  * 2. Initializes (downloads) the docset via `initDocset`
  *
  * Errors on individual sources are logged and skipped so that one failure
@@ -16,7 +16,8 @@ import {
  */
 export async function installKnowledge(
   sources: KnowledgeSource[],
-  projectRoot: string
+  projectRoot: string,
+  options: { force?: boolean } = {}
 ): Promise<void> {
   if (sources.length === 0) return;
 
@@ -26,23 +27,25 @@ export async function installKnowledge(
         {
           id: source.name,
           name: source.description,
-          preset: "git-repo" as const,
+          preset: source.preset ?? "git-repo",
           url: source.origin
         },
         { cwd: projectRoot }
       );
     } catch (err) {
-      console.warn(
-        `Warning: failed to create docset "${source.name}":`,
-        err instanceof Error ? err.message : err
-      );
-      continue;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!msg.includes("already exists")) {
+        console.warn(`Warning: failed to create docset "${source.name}":`, msg);
+        continue;
+      }
+      // Docset already registered in config — proceed to (re-)initialize it
     }
 
     try {
       await initDocset({
         docsetId: source.name,
-        cwd: projectRoot
+        cwd: projectRoot,
+        ...(options.force && { force: true })
       });
     } catch (err) {
       console.warn(

package/packages/core/package.json

@@ -39,5 +39,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "version": "0.7.0"
+  "version": "0.8.0"
 }

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

@@ -118,29 +118,39 @@ describe("catalog", () => {
       expect(names).toContain("nodejs-backend-testing");
     });
 
-    it("nodejs-backend option declares docsets for tRPC, Drizzle, Express, and Zod", () => {
+    it("nodejs-backend option declares docset recipe entries for tRPC, Drizzle, Express, and Zod", () => {
       const catalog = getDefaultCatalog();
       const architecture = getFacet(catalog, "architecture")!;
       const nodejsBackend = getOption(architecture, "nodejs-backend")!;
 
-      expect(nodejsBackend.docsets).toBeDefined();
-      const ids = nodejsBackend.docsets!.map((d) => d.id);
-      expect(ids).toContain("trpc-docs");
-      expect(ids).toContain("drizzle-orm-docs");
-      expect(ids).toContain("express-docs");
-      expect(ids).toContain("zod-docs");
+      const docsetIds = nodejsBackend.recipe
+        .filter((p) => p.writer === "docset")
+        .map((p) => (p.config as { id: string }).id);
+      expect(docsetIds).toContain("trpc-docs");
+      expect(docsetIds).toContain("drizzle-orm-docs");
+      expect(docsetIds).toContain("express-docs");
+      expect(docsetIds).toContain("zod-docs");
     });
 
-    it("each nodejs-backend docset has required fields", () => {
+    it("each nodejs-backend docset recipe entry has required fields", () => {
       const catalog = getDefaultCatalog();
       const architecture = getFacet(catalog, "architecture")!;
       const nodejsBackend = getOption(architecture, "nodejs-backend")!;
 
-      for (const docset of nodejsBackend.docsets!) {
-        expect(docset.id).toBeTruthy();
-        expect(docset.label).toBeTruthy();
-        expect(docset.origin).toMatch(/^https:\/\//);
-        expect(docset.description).toBeTruthy();
+      const docsetProvisions = nodejsBackend.recipe.filter(
+        (p) => p.writer === "docset"
+      );
+      for (const provision of docsetProvisions) {
+        const config = provision.config as {
+          id: string;
+          label: string;
+          origin: string;
+          description: string;
+        };
+        expect(config.id).toBeTruthy();
+        expect(config.label).toBeTruthy();
+        expect(config.origin).toMatch(/^https:\/\//);
+        expect(config.description).toBeTruthy();
       }
     });
   });
@@ -167,57 +177,77 @@ describe("catalog", () => {
       expect(names).toContain("java-backend-testing");
     });
 
-    it("java-backend option declares docsets for Spring Boot, Spring Data JPA, Spring Security, and Lombok", () => {
+    it("java-backend option declares docset recipe entries for Spring Boot, Spring Data JPA, Spring Security, and Lombok", () => {
       const catalog = getDefaultCatalog();
       const architecture = getFacet(catalog, "architecture")!;
       const javaBackend = getOption(architecture, "java-backend")!;
 
-      expect(javaBackend.docsets).toBeDefined();
-      const ids = javaBackend.docsets!.map((d) => d.id);
-      expect(ids).toContain("spring-boot-docs");
-      expect(ids).toContain("spring-data-jpa-docs");
-      expect(ids).toContain("spring-security-docs");
-      expect(ids).toContain("lombok-docs");
+      const docsetIds = javaBackend.recipe
+        .filter((p) => p.writer === "docset")
+        .map((p) => (p.config as { id: string }).id);
+      expect(docsetIds).toContain("spring-boot-docs");
+      expect(docsetIds).toContain("spring-data-jpa-docs");
+      expect(docsetIds).toContain("spring-security-docs");
+      expect(docsetIds).toContain("lombok-docs");
     });
 
-    it("each java-backend docset has required fields", () => {
+    it("each java-backend docset recipe entry has required fields", () => {
       const catalog = getDefaultCatalog();
       const architecture = getFacet(catalog, "architecture")!;
       const javaBackend = getOption(architecture, "java-backend")!;
 
-      for (const docset of javaBackend.docsets!) {
-        expect(docset.id).toBeTruthy();
-        expect(docset.label).toBeTruthy();
-        expect(docset.origin).toMatch(/^https:\/\//);
-        expect(docset.description).toBeTruthy();
+      const docsetProvisions = javaBackend.recipe.filter(
+        (p) => p.writer === "docset"
+      );
+      for (const provision of docsetProvisions) {
+        const config = provision.config as {
+          id: string;
+          label: string;
+          origin: string;
+          description: string;
+        };
+        expect(config.id).toBeTruthy();
+        expect(config.label).toBeTruthy();
+        expect(config.origin).toMatch(/^https:\/\//);
+        expect(config.description).toBeTruthy();
       }
     });
   });
 
   describe("architecture facet docsets", () => {
-    it("tanstack option declares docsets for Router, Query, Form, and Table", () => {
+    it("tanstack option declares docset recipe entries for Router, Query, Form, and Table", () => {
       const catalog = getDefaultCatalog();
       const architecture = getFacet(catalog, "architecture")!;
       const tanstack = getOption(architecture, "tanstack")!;
 
-      expect(tanstack.docsets).toBeDefined();
-      const ids = tanstack.docsets!.map((d) => d.id);
-      expect(ids).toContain("tanstack-router-docs");
-      expect(ids).toContain("tanstack-query-docs");
-      expect(ids).toContain("tanstack-form-docs");
-      expect(ids).toContain("tanstack-table-docs");
+      const docsetIds = tanstack.recipe
+        .filter((p) => p.writer === "docset")
+        .map((p) => (p.config as { id: string }).id);
+      expect(docsetIds).toContain("tanstack-router-docs");
+      expect(docsetIds).toContain("tanstack-query-docs");
+      expect(docsetIds).toContain("tanstack-form-docs");
+      expect(docsetIds).toContain("tanstack-table-docs");
     });
 
-    it("each docset has required fields", () => {
+    it("each tanstack docset recipe entry has required fields", () => {
       const catalog = getDefaultCatalog();
       const architecture = getFacet(catalog, "architecture")!;
       const tanstack = getOption(architecture, "tanstack")!;
 
-      for (const docset of tanstack.docsets!) {
-        expect(docset.id).toBeTruthy();
-        expect(docset.label).toBeTruthy();
-        expect(docset.origin).toMatch(/^https:\/\//);
-        expect(docset.description).toBeTruthy();
+      const docsetProvisions = tanstack.recipe.filter(
+        (p) => p.writer === "docset"
+      );
+      for (const provision of docsetProvisions) {
+        const config = provision.config as {
+          id: string;
+          label: string;
+          origin: string;
+          description: string;
+        };
+        expect(config.id).toBeTruthy();
+        expect(config.label).toBeTruthy();
+        expect(config.origin).toMatch(/^https:\/\//);
+        expect(config.description).toBeTruthy();
       }
     });
   });
@@ -251,14 +281,16 @@ describe("catalog", () => {
       expect(skills[0].name).toBe("conventional-commits");
     });
 
-    it("conventional-commits option declares the spec docset", () => {
+    it("conventional-commits option declares the spec docset via a recipe entry", () => {
       const catalog = getDefaultCatalog();
       const practices = getFacet(catalog, "practices")!;
       const option = getOption(practices, "conventional-commits")!;
 
-      expect(option.docsets).toBeDefined();
-      expect(option.docsets).toHaveLength(1);
-      expect(option.docsets![0].id).toBe("conventional-commits-spec");
+      const docsetIds = option.recipe
+        .filter((p) => p.writer === "docset")
+        .map((p) => (p.config as { id: string }).id);
+      expect(docsetIds).toHaveLength(1);
+      expect(docsetIds[0]).toBe("conventional-commits-spec");
     });
 
     it("has tdd-london option with a single skill", () => {

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

@@ -115,32 +115,42 @@ export const architectureFacet: Facet = {
               }
             ]
           }
-        }
-      ],
-      docsets: [
+        },
         {
-          id: "tanstack-router-docs",
-          label: "TanStack Router",
-          origin: "https://github.com/TanStack/router.git",
-          description: "File-based routing, loaders, and search params"
+          writer: "docset",
+          config: {
+            id: "tanstack-router-docs",
+            label: "TanStack Router",
+            origin: "https://github.com/TanStack/router.git",
+            description: "File-based routing, loaders, and search params"
+          }
         },
         {
-          id: "tanstack-query-docs",
-          label: "TanStack Query",
-          origin: "https://github.com/TanStack/query.git",
-          description: "Server state management, caching, and mutations"
+          writer: "docset",
+          config: {
+            id: "tanstack-query-docs",
+            label: "TanStack Query",
+            origin: "https://github.com/TanStack/query.git",
+            description: "Server state management, caching, and mutations"
+          }
         },
         {
-          id: "tanstack-form-docs",
-          label: "TanStack Form",
-          origin: "https://github.com/TanStack/form.git",
-          description: "Type-safe form state and validation"
+          writer: "docset",
+          config: {
+            id: "tanstack-form-docs",
+            label: "TanStack Form",
+            origin: "https://github.com/TanStack/form.git",
+            description: "Type-safe form state and validation"
+          }
         },
         {
-          id: "tanstack-table-docs",
-          label: "TanStack Table",
-          origin: "https://github.com/TanStack/table.git",
-          description: "Headless table and datagrid utilities"
+          writer: "docset",
+          config: {
+            id: "tanstack-table-docs",
+            label: "TanStack Table",
+            origin: "https://github.com/TanStack/table.git",
+            description: "Headless table and datagrid utilities"
+          }
         }
       ]
     },
@@ -256,32 +266,42 @@ export const architectureFacet: Facet = {
               }
             ]
           }
-        }
-      ],
-      docsets: [
+        },
         {
-          id: "trpc-docs",
-          label: "tRPC",
-          origin: "https://github.com/trpc/trpc.git",
-          description: "End-to-end type-safe APIs, routers, and procedures"
+          writer: "docset",
+          config: {
+            id: "trpc-docs",
+            label: "tRPC",
+            origin: "https://github.com/trpc/trpc.git",
+            description: "End-to-end type-safe APIs, routers, and procedures"
+          }
         },
         {
-          id: "drizzle-orm-docs",
-          label: "Drizzle ORM",
-          origin: "https://github.com/drizzle-team/drizzle-orm.git",
-          description: "Type-safe SQL schema, queries, and migrations"
+          writer: "docset",
+          config: {
+            id: "drizzle-orm-docs",
+            label: "Drizzle ORM",
+            origin: "https://github.com/drizzle-team/drizzle-orm.git",
+            description: "Type-safe SQL schema, queries, and migrations"
+          }
         },
         {
-          id: "express-docs",
-          label: "Express",
-          origin: "https://github.com/expressjs/express.git",
-          description: "HTTP server, routing, and middleware"
+          writer: "docset",
+          config: {
+            id: "express-docs",
+            label: "Express",
+            origin: "https://github.com/expressjs/express.git",
+            description: "HTTP server, routing, and middleware"
+          }
         },
         {
-          id: "zod-docs",
-          label: "Zod",
-          origin: "https://github.com/colinhacks/zod.git",
-          description: "TypeScript-first schema validation"
+          writer: "docset",
+          config: {
+            id: "zod-docs",
+            label: "Zod",
+            origin: "https://github.com/colinhacks/zod.git",
+            description: "TypeScript-first schema validation"
+          }
         }
       ]
     },
@@ -404,33 +424,44 @@ export const architectureFacet: Facet = {
               }
             ]
           }
-        }
-      ],
-      docsets: [
+        },
         {
-          id: "spring-boot-docs",
-          label: "Spring Boot",
-          origin: "https://github.com/spring-projects/spring-boot.git",
-          description: "Spring Boot framework, auto-configuration, and actuator"
+          writer: "docset",
+          config: {
+            id: "spring-boot-docs",
+            label: "Spring Boot",
+            origin: "https://github.com/spring-projects/spring-boot.git",
+            description:
+              "Spring Boot framework, auto-configuration, and actuator"
+          }
         },
         {
-          id: "spring-data-jpa-docs",
-          label: "Spring Data JPA",
-          origin: "https://github.com/spring-projects/spring-data-jpa.git",
-          description: "JPA repositories, derived queries, and specifications"
+          writer: "docset",
+          config: {
+            id: "spring-data-jpa-docs",
+            label: "Spring Data JPA",
+            origin: "https://github.com/spring-projects/spring-data-jpa.git",
+            description: "JPA repositories, derived queries, and specifications"
+          }
         },
         {
-          id: "spring-security-docs",
-          label: "Spring Security",
-          origin: "https://github.com/spring-projects/spring-security.git",
-          description: "Authentication, authorization, and security filters"
+          writer: "docset",
+          config: {
+            id: "spring-security-docs",
+            label: "Spring Security",
+            origin: "https://github.com/spring-projects/spring-security.git",
+            description: "Authentication, authorization, and security filters"
+          }
         },
         {
-          id: "lombok-docs",
-          label: "Lombok",
-          origin: "https://github.com/projectlombok/lombok.git",
-          description:
-            "Boilerplate reduction with annotations for getters, builders, and constructors"
+          writer: "docset",
+          config: {
+            id: "lombok-docs",
+            label: "Lombok",
+            origin: "https://github.com/projectlombok/lombok.git",
+            description:
+              "Boilerplate reduction with annotations for getters, builders, and constructors"
+          }
         }
       ]
     }

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

@@ -54,15 +54,16 @@ export const practicesFacet: Facet = {
               }
             ]
           }
-        }
-      ],
-      docsets: [
+        },
         {
-          id: "conventional-commits-spec",
-          label: "Conventional Commits Spec",
-          origin:
-            "https://github.com/conventional-commits/conventionalcommits.org.git",
-          description: "The Conventional Commits specification"
+          writer: "docset",
+          config: {
+            id: "conventional-commits-spec",
+            label: "Conventional Commits Spec",
+            origin:
+              "https://github.com/conventional-commits/conventionalcommits.org.git",
+            description: "The Conventional Commits specification"
+          }
         }
       ]
     },

package/packages/core/src/index.ts

@@ -2,14 +2,14 @@ export {
   type Catalog,
   type Facet,
   type Option,
-  type Provision,
-  type DocsetDef
+  type Provision
 } from "./types.js";
 export {
   type LogicalConfig,
   type McpServerEntry,
   type CliAction,
   type KnowledgeSource,
+  type DocsetPreset,
   type SkillDefinition,
   type InlineSkill,
   type ExternalSkill,
@@ -39,7 +39,7 @@ export {
   getAgentWriter,
   createDefaultRegistry
 } from "./registry.js";
-export { resolve, collectDocsets } from "./resolver.js";
+export { resolve } from "./resolver.js";
 export {
   getDefaultCatalog,
   getFacet,
@@ -50,5 +50,5 @@ export {
 } from "./catalog/index.js";
 export { type AdeExtensions, AdeExtensionsSchema } from "./types.js";
 export { skillsWriter } from "./writers/skills.js";
-export { knowledgeWriter } from "./writers/knowledge.js";
+export { docsetWriter } from "./writers/docset.js";
 export { permissionPolicyWriter } from "./writers/permission-policy.js";

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

@@ -120,7 +120,7 @@ describe("registry", () => {
       const expectedIds = [
         "workflows",
         "skills",
-        "knowledge",
+        "docset",
         "mcp-server",
         "instruction",
         "installable",

package/packages/core/src/registry.ts

@@ -7,7 +7,7 @@ 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 { docsetWriter } from "./writers/docset.js";
 import { gitHooksWriter } from "./writers/git-hooks.js";
 import { setupNoteWriter } from "./writers/setup-note.js";
 import { permissionPolicyWriter } from "./writers/permission-policy.js";
@@ -54,7 +54,7 @@ export function createDefaultRegistry(): WriterRegistry {
   registerProvisionWriter(registry, workflowsWriter);
   registerProvisionWriter(registry, mcpServerWriter);
   registerProvisionWriter(registry, skillsWriter);
-  registerProvisionWriter(registry, knowledgeWriter);
+  registerProvisionWriter(registry, docsetWriter);
   registerProvisionWriter(registry, gitHooksWriter);
   registerProvisionWriter(registry, setupNoteWriter);
   registerProvisionWriter(registry, permissionPolicyWriter);