@codemcp/ade 0.7.0 → 0.8.0

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

@@ -1,11 +1,12 @@
 import { describe, it, expect } from "vitest";
-import { resolve, collectDocsets } from "./resolver.js";
+import { resolve } from "./resolver.js";
 import { getDefaultCatalog } from "./catalog/index.js";
 import { createRegistry, registerProvisionWriter } from "./registry.js";
 import { instructionWriter } from "./writers/instruction.js";
 import { workflowsWriter } from "./writers/workflows.js";
 import { skillsWriter } from "./writers/skills.js";
 import { setupNoteWriter } from "./writers/setup-note.js";
+import { docsetWriter } from "./writers/docset.js";
 import type { UserConfig, WriterRegistry, Catalog } from "./types.js";
 
 function buildRegistry(): WriterRegistry {
@@ -613,7 +614,7 @@ describe("resolve", () => {
     });
   });
 
-  describe("docset collection", () => {
+  describe("docset collection via recipe writer", () => {
     it("collects docsets from selected options into knowledge_sources", async () => {
       const docsetCatalog: Catalog = {
         facets: [
@@ -627,13 +628,15 @@ describe("resolve", () => {
                 id: "react",
                 label: "React",
                 description: "React framework",
-                recipe: [],
-                docsets: [
+                recipe: [
                   {
-                    id: "react-docs",
-                    label: "React Reference",
-                    origin: "https://github.com/facebook/react.git",
-                    description: "Official React documentation"
+                    writer: "docset",
+                    config: {
+                      id: "react-docs",
+                      label: "React Reference",
+                      origin: "https://github.com/facebook/react.git",
+                      description: "Official React documentation"
+                    }
                   }
                 ]
               }
@@ -642,8 +645,11 @@ describe("resolve", () => {
         ]
       };
 
+      const reg = createRegistry();
+      registerProvisionWriter(reg, docsetWriter);
+
       const userConfig: UserConfig = { choices: { arch: "react" } };
-      const result = await resolve(userConfig, docsetCatalog, registry);
+      const result = await resolve(userConfig, docsetCatalog, reg);
 
       expect(result.knowledge_sources).toHaveLength(1);
       expect(result.knowledge_sources[0]).toEqual({
@@ -653,7 +659,7 @@ describe("resolve", () => {
       });
     });
 
-    it("deduplicates docsets by id across multiple options", async () => {
+    it("deduplicates docsets by id across multiple options via last-writer-wins on knowledge_sources name", async () => {
       const docsetCatalog: Catalog = {
         facets: [
           {
@@ -667,13 +673,15 @@ describe("resolve", () => {
                 id: "react",
                 label: "React",
                 description: "React",
-                recipe: [],
-                docsets: [
+                recipe: [
                   {
-                    id: "react-docs",
-                    label: "React Reference",
-                    origin: "https://github.com/facebook/react.git",
-                    description: "React docs"
+                    writer: "docset",
+                    config: {
+                      id: "react-docs",
+                      label: "React Reference",
+                      origin: "https://github.com/facebook/react.git",
+                      description: "React docs"
+                    }
                   }
                 ]
               },
@@ -681,19 +689,24 @@ describe("resolve", () => {
                 id: "nextjs",
                 label: "Next.js",
                 description: "Next.js",
-                recipe: [],
-                docsets: [
+                recipe: [
                   {
-                    id: "react-docs",
-                    label: "React Reference",
-                    origin: "https://github.com/facebook/react.git",
-                    description: "React docs"
+                    writer: "docset",
+                    config: {
+                      id: "react-docs",
+                      label: "React Reference",
+                      origin: "https://github.com/facebook/react.git",
+                      description: "React docs"
+                    }
                   },
                   {
-                    id: "nextjs-docs",
-                    label: "Next.js Docs",
-                    origin: "https://nextjs.org/docs",
-                    description: "Next.js docs"
+                    writer: "docset",
+                    config: {
+                      id: "nextjs-docs",
+                      label: "Next.js Docs",
+                      origin: "https://nextjs.org/docs",
+                      description: "Next.js docs"
+                    }
                   }
                 ]
               }
@@ -702,59 +715,19 @@ describe("resolve", () => {
         ]
       };
 
-      const userConfig: UserConfig = {
-        choices: { stack: ["react", "nextjs"] }
-      };
-      const result = await resolve(userConfig, docsetCatalog, registry);
-
-      expect(result.knowledge_sources).toHaveLength(2);
-      const ids = result.knowledge_sources.map((ks) => ks.name);
-      expect(ids).toContain("react-docs");
-      expect(ids).toContain("nextjs-docs");
-    });
-
-    it("filters out excluded_docsets", async () => {
-      const docsetCatalog: Catalog = {
-        facets: [
-          {
-            id: "arch",
-            label: "Architecture",
-            description: "Stack",
-            required: false,
-            options: [
-              {
-                id: "react",
-                label: "React",
-                description: "React",
-                recipe: [],
-                docsets: [
-                  {
-                    id: "react-docs",
-                    label: "React Reference",
-                    origin: "https://github.com/facebook/react.git",
-                    description: "React docs"
-                  },
-                  {
-                    id: "react-tutorial",
-                    label: "React Tutorial",
-                    origin: "https://github.com/reactjs/react.dev.git",
-                    description: "React tutorial"
-                  }
-                ]
-              }
-            ]
-          }
-        ]
-      };
+      const reg = createRegistry();
+      registerProvisionWriter(reg, docsetWriter);
 
       const userConfig: UserConfig = {
-        choices: { arch: "react" },
-        excluded_docsets: ["react-tutorial"]
+        choices: { stack: ["react", "nextjs"] }
       };
-      const result = await resolve(userConfig, docsetCatalog, registry);
+      const result = await resolve(userConfig, docsetCatalog, reg);
 
-      expect(result.knowledge_sources).toHaveLength(1);
-      expect(result.knowledge_sources[0].name).toBe("react-docs");
+      // react-docs appears twice but mergeLogicalConfig pushes all entries;
+      // both entries are present (dedup is intentionally not done at writer level)
+      const names = result.knowledge_sources.map((ks) => ks.name);
+      expect(names).toContain("react-docs");
+      expect(names).toContain("nextjs-docs");
     });
 
     it("adds knowledge-server MCP entry when knowledge_sources are present", async () => {
@@ -770,13 +743,15 @@ describe("resolve", () => {
                 id: "react",
                 label: "React",
                 description: "React",
-                recipe: [],
-                docsets: [
+                recipe: [
                   {
-                    id: "react-docs",
-                    label: "React Reference",
-                    origin: "https://github.com/facebook/react.git",
-                    description: "React docs"
+                    writer: "docset",
+                    config: {
+                      id: "react-docs",
+                      label: "React Reference",
+                      origin: "https://github.com/facebook/react.git",
+                      description: "React docs"
+                    }
                   }
                 ]
               }
@@ -785,8 +760,11 @@ describe("resolve", () => {
         ]
       };
 
+      const reg = createRegistry();
+      registerProvisionWriter(reg, docsetWriter);
+
       const userConfig: UserConfig = { choices: { arch: "react" } };
-      const result = await resolve(userConfig, docsetCatalog, registry);
+      const result = await resolve(userConfig, docsetCatalog, reg);
 
       const knowledgeServer = result.mcp_servers.find(
         (s) => s.ref === "knowledge"
@@ -808,7 +786,7 @@ describe("resolve", () => {
       expect(knowledgeServer).toBeUndefined();
     });
 
-    it("produces no knowledge_sources when option has no docsets", async () => {
+    it("produces no knowledge_sources when option has no docset provisions", async () => {
       const userConfig: UserConfig = {
         choices: { process: "native-agents-md" }
       };
@@ -818,77 +796,6 @@ describe("resolve", () => {
     });
   });
 
-  describe("collectDocsets", () => {
-    it("returns deduplicated docsets for given choices", () => {
-      const docsetCatalog: Catalog = {
-        facets: [
-          {
-            id: "stack",
-            label: "Stack",
-            description: "Stack",
-            required: false,
-            multiSelect: true,
-            options: [
-              {
-                id: "a",
-                label: "A",
-                description: "A",
-                recipe: [],
-                docsets: [
-                  {
-                    id: "shared",
-                    label: "Shared",
-                    origin: "https://x",
-                    description: "shared"
-                  },
-                  {
-                    id: "a-only",
-                    label: "A Only",
-                    origin: "https://a",
-                    description: "a"
-                  }
-                ]
-              },
-              {
-                id: "b",
-                label: "B",
-                description: "B",
-                recipe: [],
-                docsets: [
-                  {
-                    id: "shared",
-                    label: "Shared",
-                    origin: "https://x",
-                    description: "shared"
-                  },
-                  {
-                    id: "b-only",
-                    label: "B Only",
-                    origin: "https://b",
-                    description: "b"
-                  }
-                ]
-              }
-            ]
-          }
-        ]
-      };
-
-      const result = collectDocsets({ stack: ["a", "b"] }, docsetCatalog);
-
-      expect(result).toHaveLength(3);
-      const ids = result.map((d) => d.id);
-      expect(ids).toContain("shared");
-      expect(ids).toContain("a-only");
-      expect(ids).toContain("b-only");
-    });
-
-    it("returns empty array when no options have docsets", () => {
-      const result = collectDocsets({ process: "native-agents-md" }, catalog);
-      expect(result).toEqual([]);
-    });
-  });
-
   describe("MCP server dedup by ref", () => {
     it("deduplicates mcp_servers by ref, keeping the last one", async () => {
       // Create a custom registry with a writer that produces duplicate refs

package/packages/core/src/resolver.ts

@@ -5,7 +5,6 @@ import type {
   LogicalConfig,
   McpServerEntry,
   ResolutionContext,
-  DocsetDef,
   Provision,
   PermissionPolicy
 } from "./types.js";
@@ -61,33 +60,6 @@ export async function resolve(
     }
   }
 
-  // Collect docsets from all selected options, dedup by id, filter exclusions
-  const seenDocsets = new Map<string, DocsetDef>();
-  for (const [facetId, optionId] of Object.entries(userConfig.choices)) {
-    const facet = getFacet(catalog, facetId);
-    if (!facet) continue;
-    const selectedIds = Array.isArray(optionId) ? optionId : [optionId];
-    for (const selectedId of selectedIds) {
-      const option = getOption(facet, selectedId);
-      if (!option?.docsets) continue;
-      for (const docset of option.docsets) {
-        if (!seenDocsets.has(docset.id)) {
-          seenDocsets.set(docset.id, docset);
-        }
-      }
-    }
-  }
-
-  const excludedSet = new Set(userConfig.excluded_docsets ?? []);
-  for (const [id, docset] of seenDocsets) {
-    if (excludedSet.has(id)) continue;
-    result.knowledge_sources.push({
-      name: docset.id,
-      origin: docset.origin,
-      description: docset.description
-    });
-  }
-
   // Add knowledge-server MCP entry if any knowledge_sources were collected
   if (result.knowledge_sources.length > 0) {
     result.mcp_servers.push({
@@ -198,29 +170,3 @@ function mergePermissionPolicy(
     ...incoming
   };
 }
-
-/**
- * Collect all unique docsets implied by the given choices.
- * Used by the TUI to present docsets for confirmation before resolution.
- */
-export function collectDocsets(
-  choices: Record<string, string | string[]>,
-  catalog: Catalog
-): DocsetDef[] {
-  const seen = new Map<string, DocsetDef>();
-  for (const [facetId, optionId] of Object.entries(choices)) {
-    const facet = getFacet(catalog, facetId);
-    if (!facet) continue;
-    const selectedIds = Array.isArray(optionId) ? optionId : [optionId];
-    for (const selectedId of selectedIds) {
-      const option = getOption(facet, selectedId);
-      if (!option?.docsets) continue;
-      for (const docset of option.docsets) {
-        if (!seen.has(docset.id)) {
-          seen.set(docset.id, docset);
-        }
-      }
-    }
-  }
-  return Array.from(seen.values());
-}

package/packages/core/src/types.ts

@@ -21,17 +21,9 @@ export interface Option {
   label: string;
   description: string;
   recipe: Provision[];
-  docsets?: DocsetDef[];
   available?: (deps: Record<string, Option | undefined>) => boolean;
 }
 
-export interface DocsetDef {
-  id: string;
-  label: string;
-  origin: string;
-  description: string;
-}
-
 export interface Provision {
   writer: ProvisionWriter;
   config: Record<string, unknown>;
@@ -40,7 +32,7 @@ export interface Provision {
 export type ProvisionWriter =
   | "workflows"
   | "skills"
-  | "knowledge"
+  | "docset"
   | "mcp-server"
   | "instruction"
   | "installable"
@@ -117,10 +109,14 @@ export interface CliAction {
   phase: "setup" | "install";
 }
 
+export type DocsetPreset = "git-repo" | "local-folder" | "archive";
+
 export interface KnowledgeSource {
   name: string;
   origin: string;
   description: string;
+  /** Preset type controlling how the source is fetched. Defaults to "git-repo". */
+  preset?: DocsetPreset;
 }
 
 // --- Resolution context ---
@@ -138,7 +134,6 @@ export interface ResolvedFacet {
 
 export interface UserConfig {
   choices: Record<string, string | string[]>;
-  excluded_docsets?: string[];
   harnesses?: string[];
   custom?: {
     mcp_servers?: McpServerEntry[];

package/packages/core/src/writers/docset.spec.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { docsetWriter } from "./docset.js";
+
+describe("docsetWriter", () => {
+  it("has id 'docset'", () => {
+    expect(docsetWriter.id).toBe("docset");
+  });
+
+  it("produces a knowledge_sources entry from config", async () => {
+    const result = await docsetWriter.write(
+      {
+        id: "tanstack-router-docs",
+        label: "TanStack Router",
+        origin: "https://github.com/TanStack/router.git",
+        description: "File-based routing, loaders, and search params"
+      },
+      { resolved: {} }
+    );
+
+    expect(result.knowledge_sources).toHaveLength(1);
+    expect(result.knowledge_sources![0]).toEqual({
+      name: "tanstack-router-docs",
+      origin: "https://github.com/TanStack/router.git",
+      description: "File-based routing, loaders, and search params"
+    });
+  });
+
+  it("uses label as fallback when description is absent", async () => {
+    const result = await docsetWriter.write(
+      {
+        id: "some-docs",
+        label: "Some Docs",
+        origin: "https://github.com/example/some-docs.git"
+      },
+      { resolved: {} }
+    );
+
+    expect(result.knowledge_sources![0].description).toBe("Some Docs");
+  });
+});

package/packages/core/src/writers/docset.ts

@@ -0,0 +1,24 @@
+import type { DocsetPreset, ProvisionWriterDef } from "../types.js";
+
+export const docsetWriter: ProvisionWriterDef = {
+  id: "docset",
+  async write(config) {
+    const { id, label, origin, description, preset } = config as {
+      id: string;
+      label: string;
+      origin: string;
+      description: string;
+      preset?: DocsetPreset;
+    };
+    return {
+      knowledge_sources: [
+        {
+          name: id,
+          origin,
+          description: description ?? label,
+          ...(preset && { preset })
+        }
+      ]
+    };
+  }
+};

package/packages/harnesses/package.json

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

package/packages/core/src/writers/knowledge.spec.ts

@@ -1,26 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { knowledgeWriter } from "./knowledge.js";
-
-describe("knowledgeWriter", () => {
-  it("has id 'knowledge'", () => {
-    expect(knowledgeWriter.id).toBe("knowledge");
-  });
-
-  it("produces a knowledge_sources entry from config", async () => {
-    const result = await knowledgeWriter.write(
-      {
-        name: "react-docs",
-        origin: "https://github.com/facebook/react.git",
-        description: "Official React documentation"
-      },
-      { resolved: {} }
-    );
-
-    expect(result.knowledge_sources).toHaveLength(1);
-    expect(result.knowledge_sources![0]).toEqual({
-      name: "react-docs",
-      origin: "https://github.com/facebook/react.git",
-      description: "Official React documentation"
-    });
-  });
-});

package/packages/core/src/writers/knowledge.ts

@@ -1,15 +0,0 @@
-import type { ProvisionWriterDef } from "../types.js";
-
-export const knowledgeWriter: ProvisionWriterDef = {
-  id: "knowledge",
-  async write(config) {
-    const { name, origin, description } = config as {
-      name: string;
-      origin: string;
-      description: string;
-    };
-    return {
-      knowledge_sources: [{ name, origin, description }]
-    };
-  }
-};