@codemcp/ade-core 0.0.2

package/src/resolver.ts

@@ -0,0 +1,170 @@
+import type {
+  UserConfig,
+  Catalog,
+  WriterRegistry,
+  LogicalConfig,
+  McpServerEntry,
+  ResolutionContext,
+  DocsetDef
+} from "./types.js";
+import { getFacet, getOption } from "./catalog/index.js";
+import { getProvisionWriter } from "./registry.js";
+
+export async function resolve(
+  userConfig: UserConfig,
+  catalog: Catalog,
+  registry: WriterRegistry
+): Promise<LogicalConfig> {
+  const result: LogicalConfig = {
+    mcp_servers: [],
+    instructions: [],
+    cli_actions: [],
+    knowledge_sources: [],
+    skills: [],
+    git_hooks: [],
+    setup_notes: []
+  };
+
+  const context: ResolutionContext = { resolved: {} };
+
+  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) {
+        throw new Error(
+          `Unknown option "${selectedId}" for facet "${facetId}"`
+        );
+      }
+
+      context.resolved[facetId] = { optionId: selectedId, option };
+
+      for (const provision of option.recipe) {
+        const writer = getProvisionWriter(registry, provision.writer);
+        if (!writer) {
+          continue;
+        }
+        const partial = await writer.write(provision.config, context);
+        if (partial.mcp_servers) {
+          result.mcp_servers.push(...partial.mcp_servers);
+        }
+        if (partial.instructions) {
+          result.instructions.push(...partial.instructions);
+        }
+        if (partial.cli_actions) {
+          result.cli_actions.push(...partial.cli_actions);
+        }
+        if (partial.knowledge_sources) {
+          result.knowledge_sources.push(...partial.knowledge_sources);
+        }
+        if (partial.skills) {
+          result.skills.push(...partial.skills);
+        }
+        if (partial.git_hooks) {
+          result.git_hooks.push(...partial.git_hooks);
+        }
+        if (partial.setup_notes) {
+          result.setup_notes.push(...partial.setup_notes);
+        }
+      }
+    }
+  }
+
+  // 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({
+      ref: "knowledge",
+      command: "npx",
+      args: ["-y", "@codemcp/knowledge-server"],
+      env: {}
+    });
+  }
+
+  // Add skills-server MCP entry if any skills were collected
+  if (result.skills.length > 0) {
+    result.mcp_servers.push({
+      ref: "agentskills",
+      command: "npx",
+      args: ["-y", "@codemcp/skills-server"],
+      env: {}
+    });
+  }
+
+  // Merge custom section
+  if (userConfig.custom) {
+    if (userConfig.custom.instructions) {
+      result.instructions.push(...userConfig.custom.instructions);
+    }
+    if (userConfig.custom.mcp_servers) {
+      result.mcp_servers.push(...userConfig.custom.mcp_servers);
+    }
+  }
+
+  // Dedup mcp_servers by ref (last wins)
+  const serversByRef = new Map<string, McpServerEntry>();
+  for (const server of result.mcp_servers) {
+    serversByRef.set(server.ref, server);
+  }
+  result.mcp_servers = Array.from(serversByRef.values());
+
+  return result;
+}
+
+/**
+ * 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/src/types.ts

@@ -0,0 +1,151 @@
+// --- Catalog types ---
+
+export interface Catalog {
+  facets: Facet[];
+}
+
+export interface Facet {
+  id: string;
+  label: string;
+  description: string;
+  required: boolean;
+  multiSelect?: boolean;
+  dependsOn?: string[];
+  options: Option[];
+}
+
+export interface Option {
+  id: string;
+  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>;
+}
+
+export type ProvisionWriter =
+  | "workflows"
+  | "skills"
+  | "knowledge"
+  | "mcp-server"
+  | "instruction"
+  | "installable"
+  | "git-hooks"
+  | "setup-note";
+
+// --- LogicalConfig types ---
+
+export interface InlineSkill {
+  name: string;
+  description: string;
+  body: string;
+}
+
+export interface ExternalSkill {
+  name: string;
+  source: string;
+}
+
+export type SkillDefinition = InlineSkill | ExternalSkill;
+
+export interface GitHook {
+  phase: "pre-commit" | "pre-push";
+  script: string;
+}
+
+export interface LogicalConfig {
+  mcp_servers: McpServerEntry[];
+  instructions: string[];
+  cli_actions: CliAction[];
+  knowledge_sources: KnowledgeSource[];
+  skills: SkillDefinition[];
+  git_hooks: GitHook[];
+  setup_notes: string[];
+}
+
+export interface McpServerEntry {
+  ref: string;
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+  /**
+   * Tool names the agent is pre-approved to use from this server.
+   * Defaults to `["*"]` (all tools) when not specified.
+   */
+  allowedTools?: string[];
+}
+
+export interface CliAction {
+  command: string;
+  args: string[];
+  phase: "setup" | "install";
+}
+
+export interface KnowledgeSource {
+  name: string;
+  origin: string;
+  description: string;
+}
+
+// --- Resolution context ---
+
+export interface ResolutionContext {
+  resolved: Record<string, ResolvedFacet>;
+}
+
+export interface ResolvedFacet {
+  optionId: string;
+  option: Option;
+}
+
+// --- Config file types ---
+
+export interface UserConfig {
+  choices: Record<string, string | string[]>;
+  excluded_docsets?: string[];
+  harnesses?: string[];
+  custom?: {
+    mcp_servers?: McpServerEntry[];
+    instructions?: string[];
+  };
+}
+
+export interface LockFile {
+  version: 1;
+  generated_at: string;
+  choices: Record<string, string | string[]>;
+  harnesses?: string[];
+  logical_config: LogicalConfig;
+}
+
+// --- Writer contracts (open, any package can implement) ---
+
+export interface ProvisionWriterDef {
+  id: string;
+  write(
+    config: Record<string, unknown>,
+    context: ResolutionContext
+  ): Promise<Partial<LogicalConfig>>;
+}
+
+export interface AgentWriterDef {
+  id: string;
+  install(config: LogicalConfig, projectRoot: string): Promise<void>;
+}
+
+export interface WriterRegistry {
+  provisions: Map<string, ProvisionWriterDef>;
+  agents: Map<string, AgentWriterDef>;
+}

package/src/writers/git-hooks.ts

@@ -0,0 +1,9 @@
+import type { ProvisionWriterDef, GitHook } from "../types.js";
+
+export const gitHooksWriter: ProvisionWriterDef = {
+  id: "git-hooks",
+  async write(config) {
+    const { hooks } = config as { hooks: GitHook[] };
+    return { git_hooks: hooks };
+  }
+};

package/src/writers/instruction.spec.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { instructionWriter } from "./instruction.js";
+import type { ResolutionContext } from "../types.js";
+
+describe("instructionWriter", () => {
+  const context: ResolutionContext = { resolved: {} };
+
+  it("has id 'instruction'", () => {
+    expect(instructionWriter.id).toBe("instruction");
+  });
+
+  it("returns the text wrapped in an instructions array", async () => {
+    const result = await instructionWriter.write(
+      { text: "Always use strict mode" },
+      context
+    );
+    expect(result).toEqual({ instructions: ["Always use strict mode"] });
+  });
+
+  it("passes through the exact text without modification", async () => {
+    const verbatim = "  leading spaces and trailing spaces  ";
+    const result = await instructionWriter.write({ text: verbatim }, context);
+    expect(result).toEqual({ instructions: [verbatim] });
+  });
+
+  it("only returns instructions, not other LogicalConfig keys", async () => {
+    const result = await instructionWriter.write(
+      { text: "some instruction" },
+      context
+    );
+    expect(Object.keys(result)).toEqual(["instructions"]);
+    expect(result).not.toHaveProperty("mcp_servers");
+    expect(result).not.toHaveProperty("cli_actions");
+    expect(result).not.toHaveProperty("knowledge_sources");
+  });
+
+  it("handles multi-line text correctly", async () => {
+    const multiLine = "Line one\nLine two\nLine three";
+    const result = await instructionWriter.write({ text: multiLine }, context);
+    expect(result).toEqual({ instructions: [multiLine] });
+  });
+});

package/src/writers/instruction.ts

@@ -0,0 +1,8 @@
+import type { ProvisionWriterDef } from "../types.js";
+
+export const instructionWriter: ProvisionWriterDef = {
+  id: "instruction",
+  async write(config) {
+    return { instructions: [(config as { text: string }).text] };
+  }
+};

package/src/writers/knowledge.spec.ts

@@ -0,0 +1,26 @@
+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/src/writers/knowledge.ts

@@ -0,0 +1,15 @@
+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 }]
+    };
+  }
+};

package/src/writers/setup-note.ts

@@ -0,0 +1,9 @@
+import type { ProvisionWriterDef } from "../types.js";
+
+export const setupNoteWriter: ProvisionWriterDef = {
+  id: "setup-note",
+  async write(config) {
+    const { text } = config as { text: string };
+    return { setup_notes: [text] };
+  }
+};

package/src/writers/skills.spec.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect } from "vitest";
+import { skillsWriter } from "./skills.js";
+
+describe("skillsWriter", () => {
+  const emptyContext = { resolved: {} };
+
+  it("returns skills from config", async () => {
+    const result = await skillsWriter.write(
+      {
+        skills: [
+          {
+            name: "my-skill",
+            description: "A test skill",
+            body: "Do the thing."
+          }
+        ]
+      },
+      emptyContext
+    );
+
+    expect(result.skills).toHaveLength(1);
+    expect(result.skills![0]).toEqual({
+      name: "my-skill",
+      description: "A test skill",
+      body: "Do the thing."
+    });
+  });
+
+  it("returns multiple skills", async () => {
+    const result = await skillsWriter.write(
+      {
+        skills: [
+          { name: "skill-a", description: "First", body: "Body A" },
+          { name: "skill-b", description: "Second", body: "Body B" }
+        ]
+      },
+      emptyContext
+    );
+
+    expect(result.skills).toHaveLength(2);
+    expect(result.skills!.map((s) => s.name)).toEqual(["skill-a", "skill-b"]);
+  });
+
+  it("returns only the skills key", async () => {
+    const result = await skillsWriter.write(
+      {
+        skills: [{ name: "x", description: "desc", body: "body" }]
+      },
+      emptyContext
+    );
+
+    expect(Object.keys(result)).toEqual(["skills"]);
+  });
+
+  it("preserves multi-line body content", async () => {
+    const body =
+      "# Architecture\n\nUse layered architecture.\n\n## Rules\n- Rule 1\n- Rule 2";
+    const result = await skillsWriter.write(
+      {
+        skills: [{ name: "arch", description: "Architecture", body }]
+      },
+      emptyContext
+    );
+
+    expect(result.skills![0]).toMatchObject({ body });
+  });
+
+  it("returns external skills with source reference", async () => {
+    const result = await skillsWriter.write(
+      {
+        skills: [
+          {
+            name: "playwright-cli",
+            source: "microsoft/playwright-cli/skills/playwright-cli"
+          }
+        ]
+      },
+      emptyContext
+    );
+
+    expect(result.skills).toHaveLength(1);
+    expect(result.skills![0]).toEqual({
+      name: "playwright-cli",
+      source: "microsoft/playwright-cli/skills/playwright-cli"
+    });
+  });
+
+  it("handles mixed inline and external skills", async () => {
+    const result = await skillsWriter.write(
+      {
+        skills: [
+          { name: "my-skill", description: "Inline", body: "Do stuff." },
+          { name: "ext-skill", source: "org/repo/skills/ext" }
+        ]
+      },
+      emptyContext
+    );
+
+    expect(result.skills).toHaveLength(2);
+    expect(result.skills![0]).toMatchObject({
+      name: "my-skill",
+      body: "Do stuff."
+    });
+    expect(result.skills![1]).toMatchObject({
+      name: "ext-skill",
+      source: "org/repo/skills/ext"
+    });
+  });
+});

package/src/writers/skills.ts

@@ -0,0 +1,9 @@
+import type { ProvisionWriterDef, SkillDefinition } from "../types.js";
+
+export const skillsWriter: ProvisionWriterDef = {
+  id: "skills",
+  async write(config) {
+    const { skills } = config as { skills: SkillDefinition[] };
+    return { skills };
+  }
+};

package/src/writers/workflows.spec.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { workflowsWriter } from "./workflows.js";
+import type { ResolutionContext } from "../types.js";
+
+describe("workflowsWriter", () => {
+  const context: ResolutionContext = { resolved: {} };
+
+  it("has id 'workflows'", () => {
+    expect(workflowsWriter.id).toBe("workflows");
+  });
+
+  it("returns mcp_servers with correct ref, command, and args for a given package", async () => {
+    const result = await workflowsWriter.write(
+      { package: "@codemcp/workflows-server" },
+      context
+    );
+    expect(result).toEqual({
+      mcp_servers: [
+        {
+          ref: "@codemcp/workflows-server",
+          command: "npx",
+          args: ["@codemcp/workflows-server"],
+          env: {}
+        }
+      ]
+    });
+  });
+
+  it("uses ref override when provided", async () => {
+    const result = await workflowsWriter.write(
+      { package: "@codemcp/workflows-server@latest", ref: "workflows" },
+      context
+    );
+    expect(result.mcp_servers![0].ref).toBe("workflows");
+    expect(result.mcp_servers![0].args).toEqual([
+      "@codemcp/workflows-server@latest"
+    ]);
+  });
+
+  it("includes env in the entry when env is specified", async () => {
+    const result = await workflowsWriter.write(
+      {
+        package: "@codemcp/workflows-server",
+        env: { API_KEY: "secret", NODE_ENV: "production" }
+      },
+      context
+    );
+    expect(result.mcp_servers![0].env).toEqual({
+      API_KEY: "secret",
+      NODE_ENV: "production"
+    });
+  });
+
+  it("defaults env to an empty object when not specified", async () => {
+    const result = await workflowsWriter.write(
+      { package: "@codemcp/workflows-server" },
+      context
+    );
+    expect(result.mcp_servers![0].env).toEqual({});
+  });
+
+  it("only returns mcp_servers, not other LogicalConfig keys", async () => {
+    const result = await workflowsWriter.write(
+      { package: "@codemcp/workflows-server" },
+      context
+    );
+    expect(Object.keys(result)).toEqual(["mcp_servers"]);
+    expect(result).not.toHaveProperty("instructions");
+    expect(result).not.toHaveProperty("cli_actions");
+    expect(result).not.toHaveProperty("knowledge_sources");
+  });
+});

package/src/writers/workflows.ts

@@ -0,0 +1,26 @@
+import type { ProvisionWriterDef } from "../types.js";
+
+export const workflowsWriter: ProvisionWriterDef = {
+  id: "workflows",
+  async write(config) {
+    const {
+      package: pkg,
+      ref,
+      env
+    } = config as {
+      package: string;
+      ref?: string;
+      env?: Record<string, string>;
+    };
+    return {
+      mcp_servers: [
+        {
+          ref: ref ?? pkg,
+          command: "npx",
+          args: [pkg],
+          env: env ?? {}
+        }
+      ]
+    };
+  }
+};

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["**/*.spec.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "include": ["src/**/*"]
+}