@codemcp/ade 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/.ade/skills/adr-nygard/SKILL.md +45 -0
  2. package/.ade/skills/conventional-commits/SKILL.md +36 -0
  3. package/.ade/skills/tanstack-architecture/SKILL.md +25 -0
  4. package/.ade/skills/tanstack-code/SKILL.md +25 -0
  5. package/.ade/skills/tanstack-design/SKILL.md +24 -0
  6. package/.ade/skills/tanstack-testing/SKILL.md +24 -0
  7. package/.agentskills/skills/adr-nygard/SKILL.md +45 -0
  8. package/.agentskills/skills/commit/SKILL.md +20 -0
  9. package/.agentskills/skills/tdd/SKILL.md +10 -0
  10. package/.beads/README.md +85 -0
  11. package/.beads/config.yaml +63 -0
  12. package/.beads/interactions.jsonl +0 -0
  13. package/.beads/issues.jsonl +46 -0
  14. package/.beads/last-touched +1 -0
  15. package/.beads/metadata.json +4 -0
  16. package/.claude/settings.json +16 -0
  17. package/.claude/skills/extending-catalog/SKILL.md +41 -0
  18. package/.cursor/mcp.json +16 -0
  19. package/.cursor/rules/ade.mdc +10 -0
  20. package/.github/agents/ade.agent.md +28 -0
  21. package/.github/copilot-instructions.md +11 -0
  22. package/.github/workflows/pr.yml +38 -0
  23. package/.github/workflows/release.yml +124 -0
  24. package/.husky/post-checkout +2 -0
  25. package/.husky/post-merge +2 -0
  26. package/.husky/pre-commit +2 -0
  27. package/.husky/pre-push +8 -0
  28. package/.kiro/agents/ade.json +20 -0
  29. package/.kiro/settings/mcp.json +14 -0
  30. package/.knowledge/.prettierignore +1 -0
  31. package/.knowledge/config.yaml +9 -0
  32. package/.lintstagedrc.js +4 -0
  33. package/.mcp.json +20 -0
  34. package/.opencode/agents/ade.md +118 -0
  35. package/.prettierignore +2 -0
  36. package/.prettierrc.yaml +3 -0
  37. package/.vibe/beads-state-ade-autonomy-facet-46zodk.json +29 -0
  38. package/.vibe/beads-state-ade-fix-no-arch-selected-hvfiio.json +34 -0
  39. package/.vibe/development-plan-autonomy-facet.md +214 -0
  40. package/.vibe/development-plan-fix-no-arch-selected.md +103 -0
  41. package/.vscode/mcp.json +24 -0
  42. package/LICENSE +21 -0
  43. package/README.md +293 -0
  44. package/config.lock.yaml +118 -0
  45. package/config.yaml +10 -0
  46. package/docs/CLI-PRD.md +251 -0
  47. package/docs/CLI-design.md +646 -0
  48. package/docs/adrs/0001-tui-framework-selection.md +77 -0
  49. package/eslint.config.mjs +38 -0
  50. package/opencode.json +17 -0
  51. package/package.json +79 -0
  52. package/packages/cli/.prettierignore +1 -0
  53. package/packages/cli/dist/commands/install.js +39 -0
  54. package/packages/cli/dist/commands/setup.js +177 -0
  55. package/packages/cli/dist/index.js +43 -0
  56. package/packages/cli/dist/knowledge-installer.js +38 -0
  57. package/packages/cli/dist/version.js +1 -0
  58. package/packages/cli/eslint.config.mjs +40 -0
  59. package/packages/cli/nodemon.json +7 -0
  60. package/packages/cli/package.json +40 -0
  61. package/packages/cli/src/commands/conventions.integration.spec.ts +267 -0
  62. package/packages/cli/src/commands/install.integration.spec.ts +123 -0
  63. package/packages/cli/src/commands/install.spec.ts +169 -0
  64. package/packages/cli/src/commands/install.ts +63 -0
  65. package/packages/cli/src/commands/knowledge.integration.spec.ts +129 -0
  66. package/packages/cli/src/commands/setup.integration.spec.ts +148 -0
  67. package/packages/cli/src/commands/setup.spec.ts +442 -0
  68. package/packages/cli/src/commands/setup.ts +252 -0
  69. package/packages/cli/src/index.ts +52 -0
  70. package/packages/cli/src/knowledge-installer.spec.ts +111 -0
  71. package/packages/cli/src/knowledge-installer.ts +54 -0
  72. package/packages/cli/src/version.ts +1 -0
  73. package/packages/cli/tsconfig.build.json +8 -0
  74. package/packages/cli/tsconfig.json +10 -0
  75. package/packages/cli/tsconfig.vitest.json +7 -0
  76. package/packages/cli/vitest.config.ts +5 -0
  77. package/packages/core/.prettierignore +1 -0
  78. package/packages/core/eslint.config.mjs +40 -0
  79. package/packages/core/nodemon.json +7 -0
  80. package/packages/core/package.json +34 -0
  81. package/packages/core/src/catalog/catalog.spec.ts +570 -0
  82. package/packages/core/src/catalog/facets/architecture.ts +438 -0
  83. package/packages/core/src/catalog/facets/autonomy.ts +106 -0
  84. package/packages/core/src/catalog/facets/backpressure.ts +143 -0
  85. package/packages/core/src/catalog/facets/practices.ts +173 -0
  86. package/packages/core/src/catalog/facets/process.ts +50 -0
  87. package/packages/core/src/catalog/index.ts +93 -0
  88. package/packages/core/src/config.spec.ts +165 -0
  89. package/packages/core/src/config.ts +39 -0
  90. package/packages/core/src/index.ts +55 -0
  91. package/packages/core/src/registry.spec.ts +145 -0
  92. package/packages/core/src/registry.ts +70 -0
  93. package/packages/core/src/resolver.spec.ts +626 -0
  94. package/packages/core/src/resolver.ts +214 -0
  95. package/packages/core/src/types.ts +179 -0
  96. package/packages/core/src/writers/git-hooks.ts +9 -0
  97. package/packages/core/src/writers/instruction.spec.ts +42 -0
  98. package/packages/core/src/writers/instruction.ts +8 -0
  99. package/packages/core/src/writers/knowledge.spec.ts +26 -0
  100. package/packages/core/src/writers/knowledge.ts +15 -0
  101. package/packages/core/src/writers/permission-policy.ts +8 -0
  102. package/packages/core/src/writers/setup-note.ts +9 -0
  103. package/packages/core/src/writers/skills.spec.ts +109 -0
  104. package/packages/core/src/writers/skills.ts +9 -0
  105. package/packages/core/src/writers/workflows.spec.ts +72 -0
  106. package/packages/core/src/writers/workflows.ts +26 -0
  107. package/packages/core/tsconfig.build.json +8 -0
  108. package/packages/core/tsconfig.json +7 -0
  109. package/packages/core/tsconfig.vitest.json +7 -0
  110. package/packages/core/vitest.config.ts +5 -0
  111. package/packages/harnesses/.prettierignore +1 -0
  112. package/packages/harnesses/eslint.config.mjs +40 -0
  113. package/packages/harnesses/package.json +35 -0
  114. package/packages/harnesses/src/index.spec.ts +45 -0
  115. package/packages/harnesses/src/index.ts +47 -0
  116. package/packages/harnesses/src/permission-policy.ts +173 -0
  117. package/packages/harnesses/src/skills-installer.ts +54 -0
  118. package/packages/harnesses/src/types.ts +12 -0
  119. package/packages/harnesses/src/util.ts +221 -0
  120. package/packages/harnesses/src/writers/claude-code.spec.ts +320 -0
  121. package/packages/harnesses/src/writers/claude-code.ts +107 -0
  122. package/packages/harnesses/src/writers/cline.spec.ts +212 -0
  123. package/packages/harnesses/src/writers/cline.ts +24 -0
  124. package/packages/harnesses/src/writers/copilot.spec.ts +258 -0
  125. package/packages/harnesses/src/writers/copilot.ts +105 -0
  126. package/packages/harnesses/src/writers/cursor.spec.ts +219 -0
  127. package/packages/harnesses/src/writers/cursor.ts +95 -0
  128. package/packages/harnesses/src/writers/kiro.spec.ts +228 -0
  129. package/packages/harnesses/src/writers/kiro.ts +89 -0
  130. package/packages/harnesses/src/writers/opencode.spec.ts +258 -0
  131. package/packages/harnesses/src/writers/opencode.ts +67 -0
  132. package/packages/harnesses/src/writers/roo-code.spec.ts +197 -0
  133. package/packages/harnesses/src/writers/roo-code.ts +71 -0
  134. package/packages/harnesses/src/writers/universal.spec.ts +134 -0
  135. package/packages/harnesses/src/writers/universal.ts +84 -0
  136. package/packages/harnesses/src/writers/windsurf.spec.ts +178 -0
  137. package/packages/harnesses/src/writers/windsurf.ts +89 -0
  138. package/packages/harnesses/tsconfig.build.json +8 -0
  139. package/packages/harnesses/tsconfig.json +7 -0
  140. package/packages/harnesses/tsconfig.vitest.json +7 -0
  141. package/packages/harnesses/vitest.config.ts +5 -0
  142. package/pnpm-workspace.yaml +2 -0
  143. package/scripts/rename-packages.sh +23 -0
  144. package/skills-lock.json +20 -0
  145. package/tsconfig.base.json +25 -0
  146. package/tsconfig.build.json +7 -0
  147. package/tsconfig.json +13 -0
  148. package/turbo.json +47 -0
  149. package/vitest.config.ts +22 -0
  150. package/vitest.setup.ts +0 -0
@@ -0,0 +1,77 @@
1
+ # ADR 0001: TUI Framework Selection for ADE CLI
2
+
3
+ ## Status
4
+
5
+ Accepted
6
+
7
+ ## Context
8
+
9
+ ADE (Agentic Development Environment) is a CLI tool that guides users through setup and configuration via interactive terminal prompts. The CLI needs to:
10
+
11
+ - Present guided wizard-style flows (select, multiselect, confirm, text input)
12
+ - Display streaming output from LLM/agent processes
13
+ - Look visually polished and modern ("world-class-nerdy") while remaining enterprise-appropriate
14
+ - Terminate after completion (not a long-lived interactive TUI)
15
+ - Run in standard terminals including CI environments
16
+ - Be ESM-compatible (the project is `"type": "module"`)
17
+ - Integrate cleanly into a TypeScript monorepo (Node >= 22, pnpm)
18
+
19
+ We evaluated the actively-maintained Node.js TUI/prompt frameworks available as of March 2026. Legacy libraries (blessed, neo-blessed, enquirer, prompts by terkelg) were excluded upfront due to abandonment or CJS-only distribution.
20
+
21
+ ## Decision
22
+
23
+ We will use **@clack/prompts** as the TUI framework for the ADE CLI.
24
+
25
+ ## Evaluation: Weighted Pugh Matrix
26
+
27
+ Criteria were weighted on a 3-point scale (1 = nice-to-have, 2 = important, 3 = critical). Each candidate was scored relative to a baseline of 0 (meets expectations), with +1 (better) and -1 (worse).
28
+
29
+ | # | Criterion | Weight | @clack/prompts | @inquirer/prompts | Ink + @inkjs/ui |
30
+ | --- | ---------------------------------- | ------ | -------------- | ----------------- | --------------- |
31
+ | 1 | Visual polish out-of-the-box | 3 | +1 | -1 | +1 |
32
+ | 2 | Wizard/prompt flow suitability | 3 | +1 | +1 | 0 |
33
+ | 3 | ESM-native compatibility | 3 | +1 | 0 | 0 |
34
+ | 4 | LLM/streaming output support | 2 | +1 | -1 | +1 |
35
+ | 5 | Learning curve / simplicity | 2 | +1 | 0 | -1 |
36
+ | 6 | Bundle size / dependency footprint | 2 | +1 | 0 | -1 |
37
+ | 7 | Ecosystem / plugin breadth | 1 | -1 | +1 | 0 |
38
+ | 8 | Community size / adoption | 1 | 0 | +1 | +1 |
39
+ | 9 | Custom prompt authoring | 1 | 0 | +1 | +1 |
40
+
41
+ **Weighted totals:**
42
+
43
+ | Candidate | Calculation | Total |
44
+ | --------------------- | ------------------------------------------------------------------- | ------- |
45
+ | **@clack/prompts** | 3(+1) + 3(+1) + 3(+1) + 2(+1) + 2(+1) + 2(+1) + 1(-1) + 1(0) + 1(0) | **+14** |
46
+ | **@inquirer/prompts** | 3(-1) + 3(+1) + 3(0) + 2(-1) + 2(0) + 2(0) + 1(+1) + 1(+1) + 1(+1) | **+1** |
47
+ | **Ink + @inkjs/ui** | 3(+1) + 3(0) + 3(0) + 2(+1) + 2(-1) + 2(-1) + 1(0) + 1(+1) + 1(+1) | **+5** |
48
+
49
+ @clack/prompts scores highest by a significant margin.
50
+
51
+ ## Rationale
52
+
53
+ **@clack/prompts wins on the criteria that matter most to ADE:**
54
+
55
+ 1. **Visual polish (weight 3):** Clack's pre-styled prompts are the most visually striking of any Node.js prompt library. Unicode box-drawing, colored indicators, and thoughtful spacing produce a premium feel with zero configuration. @inquirer/prompts looks functional but plain; Ink can match Clack's aesthetics but requires manual styling.
56
+
57
+ 2. **Wizard suitability (weight 3):** ADE's CLI is a terminating wizard, not a persistent dashboard. Clack was purpose-built for sequential prompt flows with `intro()`, `outro()`, `group()`, and `spinner()`. Ink is designed for persistent, React-rendered UIs — architectural overkill for a flow that collects answers and exits.
58
+
59
+ 3. **ESM-native (weight 3):** Clack is ESM-only, aligning perfectly with ADE's `"type": "module"` configuration. No dual-format complications, no CJS shims.
60
+
61
+ 4. **LLM streaming (weight 2):** Clack includes native `stream` utilities designed for rendering LLM/agent output in the terminal — a direct match for ADE's agentic use case. Inquirer has no equivalent.
62
+
63
+ 5. **Simplicity (weight 2):** Clack's API is a flat set of async functions (`select()`, `text()`, `confirm()`, `spinner()`). No React knowledge required, no component tree to manage. This lowers the contribution barrier and reduces maintenance surface.
64
+
65
+ 6. **Footprint (weight 2):** Clack uses Node's built-in `styleText` instead of external color libraries. Minimal transitive dependencies. Ink pulls in React, Yoga (native binary), and a reconciler.
66
+
67
+ **Where Clack is weaker — and why it doesn't matter:**
68
+
69
+ - _Ecosystem breadth (weight 1):_ Inquirer has more community plugins (table prompts, file selectors, i18n). ADE's current scope doesn't require these, and `@clack/core` allows building custom prompts if needed.
70
+ - _Persistent UI:_ Clack can't render a dashboard or split-pane view. ADE doesn't need one — it's a wizard that terminates.
71
+
72
+ ## Consequences
73
+
74
+ - The `@ade/cli` package will add `@clack/prompts` as a production dependency.
75
+ - All interactive CLI flows (setup, configuration, MCP server management) will use Clack's prompt primitives.
76
+ - If a future requirement emerges for persistent/dashboard-style terminal UI (e.g., a live agent monitoring view), we can evaluate adding Ink as a complementary dependency at that time. The two libraries are not mutually exclusive.
77
+ - Custom prompts beyond Clack's built-in set will be authored using `@clack/core`.
@@ -0,0 +1,38 @@
1
+ import js from "@eslint/js";
2
+ import { parser, configs } from "typescript-eslint";
3
+ import prettier from "eslint-config-prettier";
4
+
5
+ export default [
6
+ js.configs.recommended,
7
+ ...configs.recommended,
8
+ prettier,
9
+ {
10
+ // Config for TypeScript files
11
+ files: ["**/*.{ts,tsx}"],
12
+ languageOptions: {
13
+ parser,
14
+ parserOptions: {
15
+ project: [
16
+ "./tsconfig.json",
17
+ "./docs/.vitepress/tsconfig.json",
18
+ "./packages/*/tsconfig.json"
19
+ ]
20
+ }
21
+ }
22
+ },
23
+ {
24
+ // Config for JavaScript files - no TypeScript parsing
25
+ files: ["**/*.{js,jsx}"],
26
+ ...js.configs.recommended
27
+ },
28
+ {
29
+ ignores: [
30
+ "**/node_modules/**",
31
+ "**/dist/**",
32
+ ".pnpm-store/**",
33
+ "pnpm-lock.yaml",
34
+ "/packages/**",
35
+ "docs/.vitepress/cache/**"
36
+ ]
37
+ }
38
+ ];
package/opencode.json ADDED
@@ -0,0 +1,17 @@
1
+ {
2
+ "$schema": "https://opencode.ai/config.json",
3
+ "mcp": {
4
+ "workflows": {
5
+ "type": "local",
6
+ "command": ["npx", "@codemcp/workflows-server@latest"]
7
+ },
8
+ "agentskills": {
9
+ "type": "local",
10
+ "command": ["npx", "-y", "@codemcp/skills-server"]
11
+ },
12
+ "knowledge": {
13
+ "type": "local",
14
+ "command": ["npx", "-y", "@codemcp/knowledge-server"]
15
+ }
16
+ }
17
+ }
package/package.json ADDED
@@ -0,0 +1,79 @@
1
+ {
2
+ "name": "@codemcp/ade",
3
+ "version": "0.2.0",
4
+ "description": "ADE CLI — Agentic Development Environment setup and configuration tool",
5
+ "license": "MIT",
6
+ "keywords": [
7
+ "ade",
8
+ "agentic",
9
+ "development",
10
+ "cli",
11
+ "mcp"
12
+ ],
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "https://github.com/codemcp/ade"
16
+ },
17
+ "engines": {
18
+ "node": ">=22",
19
+ "pnpm": ">=9.0.0"
20
+ },
21
+ "type": "module",
22
+ "bin": {
23
+ "ade": "packages/cli/dist/index.js"
24
+ },
25
+ "publishConfig": {
26
+ "access": "public"
27
+ },
28
+ "devDependencies": {
29
+ "@braintree/sanitize-url": "7.1.1",
30
+ "@eslint/js": "9.18.0",
31
+ "@swc/core": "^1.10.9",
32
+ "@tsconfig/node22": "22.0.0",
33
+ "@tsconfig/strictest": "2.0.5",
34
+ "@types/eslint-config-prettier": "6.11.3",
35
+ "@types/node": "^22.10.7",
36
+ "@typescript-eslint/eslint-plugin": "^8.21.0",
37
+ "@typescript-eslint/parser": "^8.21.0",
38
+ "@vitest/coverage-v8": "^3.0.3",
39
+ "cytoscape": "3.31.0",
40
+ "cytoscape-cose-bilkent": "4.1.0",
41
+ "dayjs": "1.11.13",
42
+ "debug": "4.4.0",
43
+ "eslint": "^9.18.0",
44
+ "eslint-config-prettier": "^10.0.1",
45
+ "husky": "^9.1.7",
46
+ "lint-staged": "^15.4.1",
47
+ "nodemon": "^3.1.9",
48
+ "prettier": "^3.4.2",
49
+ "rimraf": "^6.0.1",
50
+ "turbo": "^2.3.3",
51
+ "typescript": "^5.7.3",
52
+ "typescript-eslint": "8.21.0",
53
+ "vitepress": "1.6.2",
54
+ "vitepress-plugin-mermaid": "2.0.17",
55
+ "vitest": "^3.0.3"
56
+ },
57
+ "dependencies": {
58
+ "yaml": "^2.8.2"
59
+ },
60
+ "scripts": {
61
+ "build": "turbo run build",
62
+ "build:clean": "turbo run clean:build",
63
+ "dev": "turbo run dev",
64
+ "docs:dev": "vitepress dev docs",
65
+ "docs:build": "vitepress build docs",
66
+ "docs:preview": "vitepress preview docs",
67
+ "test": "turbo run --parallel test",
68
+ "test:watch": "turbo run --parallel test:watch",
69
+ "lint:all": "turbo run --parallel lint",
70
+ "lint:fix:all": "turbo run --parallel lint:fix",
71
+ "format:check:all": "turbo run --parallel format",
72
+ "format:all": "turbo run --parallel format:fix",
73
+ "typecheck:all": "turbo run --parallel typecheck",
74
+ "lint": "eslint",
75
+ "lint:fix": "eslint --fix",
76
+ "format": "prettier --check .",
77
+ "format:fix": "prettier --write ."
78
+ }
79
+ }
@@ -0,0 +1 @@
1
+ dist
@@ -0,0 +1,39 @@
1
+ import * as clack from "@clack/prompts";
2
+ import { readLockFile } from "@codemcp/ade-core";
3
+ import { getHarnessWriter, getHarnessIds, installSkills, writeInlineSkills } from "@codemcp/ade-harnesses";
4
+ export async function runInstall(projectRoot, harnessIds) {
5
+ clack.intro("ade install");
6
+ const lockFile = await readLockFile(projectRoot);
7
+ if (!lockFile) {
8
+ throw new Error("config.lock.yaml not found. Run `ade setup` first.");
9
+ }
10
+ // Determine which harnesses to install for:
11
+ // 1. --harness flag (comma-separated)
12
+ // 2. harnesses saved in the lock file
13
+ // 3. default: universal
14
+ const ids = harnessIds ?? lockFile.harnesses ?? ["universal"];
15
+ const validIds = getHarnessIds();
16
+ for (const id of ids) {
17
+ if (!validIds.includes(id)) {
18
+ throw new Error(`Unknown harness "${id}". Available: ${validIds.join(", ")}`);
19
+ }
20
+ }
21
+ const logicalConfig = lockFile.logical_config;
22
+ for (const id of ids) {
23
+ const writer = getHarnessWriter(id);
24
+ if (writer) {
25
+ await writer.install(logicalConfig, projectRoot);
26
+ }
27
+ }
28
+ const modifiedSkills = await writeInlineSkills(logicalConfig, projectRoot);
29
+ if (modifiedSkills.length > 0) {
30
+ clack.log.warn(`The following skills have been locally modified and will NOT be updated:\n` +
31
+ modifiedSkills.map((s) => ` - ${s}`).join("\n") +
32
+ `\n\nTo use the latest defaults, remove .ade/skills/ and re-run install.`);
33
+ }
34
+ await installSkills(logicalConfig.skills, projectRoot);
35
+ if (logicalConfig.knowledge_sources.length > 0) {
36
+ clack.log.info("Knowledge sources configured. Initialize them separately:\n npx @codemcp/knowledge init");
37
+ }
38
+ clack.outro("Install complete!");
39
+ }
@@ -0,0 +1,177 @@
1
+ import * as clack from "@clack/prompts";
2
+ import { readUserConfig, writeUserConfig, writeLockFile, resolve, collectDocsets, createDefaultRegistry, getFacet, getOption, sortFacets, getVisibleOptions } from "@codemcp/ade-core";
3
+ import { allHarnessWriters, getHarnessWriter, installSkills, writeInlineSkills } from "@codemcp/ade-harnesses";
4
+ export async function runSetup(projectRoot, catalog) {
5
+ clack.intro("ade setup");
6
+ const existingConfig = await readUserConfig(projectRoot);
7
+ const existingChoices = existingConfig?.choices ?? {};
8
+ // Warn about stale choices that reference options no longer in the catalog
9
+ for (const [facetId, value] of Object.entries(existingChoices)) {
10
+ const facet = getFacet(catalog, facetId);
11
+ if (!facet)
12
+ continue;
13
+ const ids = Array.isArray(value) ? value : [value];
14
+ for (const optionId of ids) {
15
+ if (!getOption(facet, optionId)) {
16
+ clack.log.warn(`Previously selected option "${optionId}" is no longer available in facet "${facet.label}".`);
17
+ }
18
+ }
19
+ }
20
+ const choices = {};
21
+ const sortedFacets = sortFacets(catalog);
22
+ for (const facet of sortedFacets) {
23
+ const visibleOptions = getVisibleOptions(facet, choices, catalog);
24
+ if (visibleOptions.length === 0)
25
+ continue;
26
+ const visibleFacet = { ...facet, options: visibleOptions };
27
+ if (facet.multiSelect) {
28
+ const selected = await promptMultiSelect(visibleFacet, existingChoices);
29
+ if (typeof selected === "symbol") {
30
+ clack.cancel("Setup cancelled.");
31
+ return;
32
+ }
33
+ if (selected.length > 0) {
34
+ choices[facet.id] = selected;
35
+ }
36
+ }
37
+ else {
38
+ const selected = await promptSelect(visibleFacet, existingChoices);
39
+ if (typeof selected === "symbol") {
40
+ clack.cancel("Setup cancelled.");
41
+ return;
42
+ }
43
+ if (typeof selected === "string" && selected !== "__skip__") {
44
+ choices[facet.id] = selected;
45
+ }
46
+ }
47
+ }
48
+ // Docset confirmation step: collect implied docsets, let user deselect
49
+ const impliedDocsets = collectDocsets(choices, catalog);
50
+ let excludedDocsets;
51
+ if (impliedDocsets.length > 0) {
52
+ const selected = await clack.multiselect({
53
+ message: "Documentation — deselect any you don't need",
54
+ options: impliedDocsets.map((d) => ({
55
+ value: d.id,
56
+ label: d.label,
57
+ hint: d.description
58
+ })),
59
+ initialValues: impliedDocsets.map((d) => d.id),
60
+ required: false
61
+ });
62
+ if (typeof selected === "symbol") {
63
+ clack.cancel("Setup cancelled.");
64
+ return;
65
+ }
66
+ const selectedSet = new Set(selected);
67
+ const excluded = impliedDocsets
68
+ .filter((d) => !selectedSet.has(d.id))
69
+ .map((d) => d.id);
70
+ if (excluded.length > 0) {
71
+ excludedDocsets = excluded;
72
+ }
73
+ }
74
+ // Harness selection — multi-select from all available harnesses
75
+ const existingHarnesses = existingConfig?.harnesses;
76
+ const harnessOptions = allHarnessWriters.map((w) => ({
77
+ value: w.id,
78
+ label: w.label,
79
+ hint: w.description
80
+ }));
81
+ const validExistingHarnesses = existingHarnesses?.filter((h) => allHarnessWriters.some((w) => w.id === h));
82
+ const selectedHarnesses = await clack.multiselect({
83
+ message: "Harnesses — which coding agents should receive config?",
84
+ options: harnessOptions,
85
+ initialValues: validExistingHarnesses && validExistingHarnesses.length > 0
86
+ ? validExistingHarnesses
87
+ : ["universal"],
88
+ required: false
89
+ });
90
+ if (typeof selectedHarnesses === "symbol") {
91
+ clack.cancel("Setup cancelled.");
92
+ return;
93
+ }
94
+ const harnesses = selectedHarnesses;
95
+ const userConfig = {
96
+ choices,
97
+ ...(excludedDocsets && { excluded_docsets: excludedDocsets }),
98
+ ...(harnesses.length > 0 && { harnesses })
99
+ };
100
+ const registry = createDefaultRegistry();
101
+ const logicalConfig = await resolve(userConfig, catalog, registry);
102
+ await writeUserConfig(projectRoot, userConfig);
103
+ const lockFile = {
104
+ version: 1,
105
+ generated_at: new Date().toISOString(),
106
+ choices: userConfig.choices,
107
+ ...(harnesses.length > 0 && { harnesses }),
108
+ logical_config: logicalConfig
109
+ };
110
+ await writeLockFile(projectRoot, lockFile);
111
+ // Install to all selected harnesses
112
+ for (const harnessId of harnesses) {
113
+ const writer = getHarnessWriter(harnessId);
114
+ if (writer) {
115
+ await writer.install(logicalConfig, projectRoot);
116
+ }
117
+ }
118
+ const modifiedSkills = await writeInlineSkills(logicalConfig, projectRoot);
119
+ if (modifiedSkills.length > 0) {
120
+ clack.log.warn(`The following skills have been locally modified and will NOT be updated:\n` +
121
+ modifiedSkills.map((s) => ` - ${s}`).join("\n") +
122
+ `\n\nTo use the latest defaults, remove .ade/skills/ and re-run setup.`);
123
+ }
124
+ await installSkills(logicalConfig.skills, projectRoot);
125
+ if (logicalConfig.knowledge_sources.length > 0) {
126
+ clack.log.info("Knowledge sources selected. Initialize them separately:\n npx @codemcp/knowledge init");
127
+ }
128
+ for (const note of logicalConfig.setup_notes) {
129
+ clack.log.info(note);
130
+ }
131
+ clack.outro("Setup complete!");
132
+ }
133
+ function getValidInitialValue(facet, existingChoices) {
134
+ const value = existingChoices[facet.id];
135
+ if (typeof value !== "string")
136
+ return undefined;
137
+ // Only set initialValue if the option still exists in the catalog
138
+ return facet.options.some((o) => o.id === value) ? value : undefined;
139
+ }
140
+ function getValidInitialValues(facet, existingChoices) {
141
+ const value = existingChoices[facet.id];
142
+ if (!Array.isArray(value))
143
+ return undefined;
144
+ // Only include options that still exist in the catalog
145
+ const valid = value.filter((v) => facet.options.some((o) => o.id === v));
146
+ return valid.length > 0 ? valid : undefined;
147
+ }
148
+ function promptSelect(facet, existingChoices) {
149
+ const options = facet.options.map((o) => ({
150
+ value: o.id,
151
+ label: o.label,
152
+ hint: o.description
153
+ }));
154
+ if (!facet.required) {
155
+ options.push({ value: "__skip__", label: "Skip", hint: "" });
156
+ }
157
+ const initialValue = getValidInitialValue(facet, existingChoices);
158
+ return clack.select({
159
+ message: facet.label,
160
+ options,
161
+ ...(initialValue !== undefined && { initialValue })
162
+ });
163
+ }
164
+ function promptMultiSelect(facet, existingChoices) {
165
+ const options = facet.options.map((o) => ({
166
+ value: o.id,
167
+ label: o.label,
168
+ hint: o.description
169
+ }));
170
+ const initialValues = getValidInitialValues(facet, existingChoices);
171
+ return clack.multiselect({
172
+ message: facet.label,
173
+ options,
174
+ required: false,
175
+ ...(initialValues !== undefined && { initialValues })
176
+ });
177
+ }
@@ -0,0 +1,43 @@
1
+ #!/usr/bin/env node
2
+ import { version } from "./version.js";
3
+ import { runSetup } from "./commands/setup.js";
4
+ import { runInstall } from "./commands/install.js";
5
+ import { getDefaultCatalog } from "@codemcp/ade-core";
6
+ import { getHarnessIds } from "@codemcp/ade-harnesses";
7
+ const args = process.argv.slice(2);
8
+ const command = args[0];
9
+ if (command === "setup") {
10
+ const projectRoot = args[1] ?? process.cwd();
11
+ const catalog = getDefaultCatalog();
12
+ await runSetup(projectRoot, catalog);
13
+ }
14
+ else if (command === "install") {
15
+ const projectRoot = args[1] ?? process.cwd();
16
+ let harnessIds;
17
+ // Support --harness flag (comma-separated)
18
+ if (args.includes("--harness")) {
19
+ const val = args[args.indexOf("--harness") + 1];
20
+ if (val) {
21
+ harnessIds = val.split(",").map((s) => s.trim());
22
+ }
23
+ }
24
+ await runInstall(projectRoot, harnessIds);
25
+ }
26
+ else if (command === "--version" || command === "-v") {
27
+ console.log(version);
28
+ }
29
+ else {
30
+ const allIds = getHarnessIds();
31
+ console.log(`ade v${version}`);
32
+ console.log();
33
+ console.log("Usage: ade <command> [options]");
34
+ console.log();
35
+ console.log("Commands:");
36
+ console.log(" setup [dir] Interactive setup wizard (re-run to change selections)");
37
+ console.log(" install [dir] Apply lock file to generate agent files (idempotent)");
38
+ console.log();
39
+ console.log("Options:");
40
+ console.log(` --harness <ids> Comma-separated harnesses (${allIds.join(", ")})`);
41
+ console.log(" -v, --version Show version");
42
+ process.exitCode = command ? 1 : 0;
43
+ }
@@ -0,0 +1,38 @@
1
+ import { createDocset, initDocset } from "@codemcp/knowledge/packages/cli/dist/exports.js";
2
+ /**
3
+ * Install knowledge sources using the @codemcp/knowledge programmatic API.
4
+ *
5
+ * For each knowledge source:
6
+ * 1. Creates a docset config entry via `createDocset`
7
+ * 2. Initializes (downloads) the docset via `initDocset`
8
+ *
9
+ * Errors on individual sources are logged and skipped so that one failure
10
+ * doesn't block the rest.
11
+ */
12
+ export async function installKnowledge(sources, projectRoot) {
13
+ if (sources.length === 0)
14
+ return;
15
+ for (const source of sources) {
16
+ try {
17
+ await createDocset({
18
+ id: source.name,
19
+ name: source.description,
20
+ preset: "git-repo",
21
+ url: source.origin
22
+ }, { cwd: projectRoot });
23
+ }
24
+ catch (err) {
25
+ console.warn(`Warning: failed to create docset "${source.name}":`, err instanceof Error ? err.message : err);
26
+ continue;
27
+ }
28
+ try {
29
+ await initDocset({
30
+ docsetId: source.name,
31
+ cwd: projectRoot
32
+ });
33
+ }
34
+ catch (err) {
35
+ console.warn(`Warning: failed to initialize docset "${source.name}":`, err instanceof Error ? err.message : err);
36
+ }
37
+ }
38
+ }
@@ -0,0 +1 @@
1
+ export const version = "0.0.0-development";
@@ -0,0 +1,40 @@
1
+ import js from "@eslint/js";
2
+ import { parser, configs } from "typescript-eslint";
3
+ import prettier from "eslint-config-prettier";
4
+
5
+ export default [
6
+ js.configs.recommended,
7
+ ...configs.recommended,
8
+ prettier,
9
+ {
10
+ // Config for TypeScript files
11
+ files: ["**/*.{ts,tsx}"],
12
+ languageOptions: {
13
+ parser,
14
+ parserOptions: {
15
+ project: ["./tsconfig.json", "./tsconfig.vitest.json"]
16
+ }
17
+ }
18
+ },
19
+ {
20
+ // Config for JavaScript files - no TypeScript parsing
21
+ files: ["**/*.{js,jsx}"],
22
+ ...js.configs.recommended
23
+ },
24
+ {
25
+ // Relaxed rules for test files
26
+ files: ["**/*.test.ts", "**/*.spec.ts"],
27
+ rules: {
28
+ "@typescript-eslint/no-explicit-any": "off",
29
+ "@typescript-eslint/no-unused-vars": "off"
30
+ }
31
+ },
32
+ {
33
+ ignores: [
34
+ "**/node_modules/**",
35
+ "**/dist/**",
36
+ ".pnpm-store/**",
37
+ "pnpm-lock.yaml"
38
+ ]
39
+ }
40
+ ];
@@ -0,0 +1,7 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/nodemon.json",
3
+ "watch": ["./src/**", "./node_modules/@mme/**/dist/**"],
4
+ "ignoreRoot": [],
5
+ "ext": "ts,js",
6
+ "exec": "pnpm typecheck && pnpm build"
7
+ }
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "@codemcp/ade-cli",
3
+ "main": "dist/index.js",
4
+ "types": "dist/index.d.ts",
5
+ "type": "module",
6
+ "bin": {
7
+ "ade": "dist/index.js"
8
+ },
9
+ "publishConfig": {
10
+ "access": "public"
11
+ },
12
+ "scripts": {
13
+ "build": "tsc -p tsconfig.build.json",
14
+ "clean:build": "rimraf ./dist",
15
+ "dev": "nodemon",
16
+ "lint": "eslint .",
17
+ "lint:fix": "eslint --fix .",
18
+ "format": "prettier --check .",
19
+ "format:fix": "prettier --write .",
20
+ "test": "vitest --run",
21
+ "test:watch": "vitest",
22
+ "typecheck": "tsc"
23
+ },
24
+ "dependencies": {
25
+ "@codemcp/ade-core": "workspace:*",
26
+ "@codemcp/ade-harnesses": "workspace:*",
27
+ "@clack/prompts": "^1.1.0"
28
+ },
29
+ "devDependencies": {
30
+ "@codemcp/knowledge": "2.1.0",
31
+ "@typescript-eslint/eslint-plugin": "^8.21.0",
32
+ "@typescript-eslint/parser": "^8.21.0",
33
+ "eslint": "^9.18.0",
34
+ "eslint-config-prettier": "^10.0.1",
35
+ "prettier": "^3.4.2",
36
+ "rimraf": "^6.0.1",
37
+ "typescript": "^5.7.3"
38
+ },
39
+ "version": "0.2.0"
40
+ }