@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/utils/index.js

@@ -5,14 +5,31 @@
  * Utils barrel export
  * Re-exports helper functions and constants from the utils layer.
  */
-// Export cache utilities
-export { CACHE_CONFIG, ContextCache, clearGlobalCache, getCache, } from './cache.js';
+import { ITEM_TYPE_PREFIXES, itemIdPattern } from '../schemas/item-id.js';
+// Export trace logger
+// Export agent-file payload helpers
+export { listPayloadFiles } from './agent-files-payload.js';
+// Export atomic write helpers
+export { ATOMIC_TEMP_NAME, renameWithRetry, renameWithRetrySync, writeBytesAtomic, writeFileAtomic, writeJsonAtomic, } from './atomic-write.js';
 // Export backup utilities
 export { backupGithubFiles, } from './backup-github-files.js';
+// Export cache utilities
+export { CACHE_CONFIG, ContextCache, clearGlobalCache, getCache, } from './cache.js';
+// Export Claude Code host helpers
+export { renderClaudeContractPreamble, writeClaudeContractBlock, } from './claude-host.js';
+// Export contract-block helpers shared by both agent hosts
+export { extractManagedBlock, readPackagedContractBlock, writeContractBlock, } from './contract-block.js';
+export { CONTRACT_REFRESH_HINT, checkContractStaleness, contractStalenessCheck, } from './contract-staleness.js';
 // Export init helpers
-export { copyDevstepsDocs, copyGithubFiles, injectDevstepsComment, writeSetupMd, } from './init-helpers.js';
+export { copyGithubFiles, injectDevstepsComment, writeSetupMd, } from './init-helpers.js';
+// Export MCP tool group helpers
+export { activeToolGroups, MCP_DEFAULT_TOOL_GROUPS, MCP_OPT_IN_TOOL_GROUPS, MCP_TOOL_GROUP_ENV_VAR, MCP_TOOL_GROUP_NAMES, mergeToolGroupEnv, parseToolGroupSelection, selectToolGroups, toolGroupEnv, } from './mcp-tool-groups.js';
+// Export packaged payload resolution
+export { resolvePackagedGithubDir } from './packaged-github.js';
+// Export BOM-tolerant text reading
+export { readTextFile, stripBom } from './text-file.js';
 // Export update helpers
-export { updateCopilotFiles, } from './update-copilot-files.js';
+export { updateAgentFiles, updateCopilotFiles, } from './update-agent-files.js';
 /**
  * Type to plural directory mapping
  * Uses items/ subdirectory for git-inspired object store (SPIKE-008)
@@ -26,100 +43,54 @@ export const TYPE_TO_DIRECTORY = {
     bug: 'items/bugs',
     spike: 'items/spikes',
     test: 'items/tests',
+    doc: 'items/docs',
+    decision: 'items/decisions',
+    question: 'items/questions',
+};
+/** The types each methodology offers; doc, decision and question are cross-cutting (EPIC-059). */
+const METHODOLOGY_TYPES = {
+    scrum: ['epic', 'story', 'task', 'bug', 'spike', 'test', 'doc', 'decision', 'question'],
+    waterfall: [
+        'requirement',
+        'feature',
+        'task',
+        'bug',
+        'spike',
+        'test',
+        'doc',
+        'decision',
+        'question',
+    ],
+    hybrid: [
+        'epic',
+        'story',
+        'requirement',
+        'feature',
+        'task',
+        'bug',
+        'spike',
+        'test',
+        'doc',
+        'decision',
+        'question',
+    ],
 };
 /**
- * Get methodology configuration
+ * Get methodology configuration: the item types, their ID prefixes and their directories
  */
 export function getMethodologyConfig(methodology) {
-    const configs = {
-        scrum: {
-            item_types: ['epic', 'story', 'task', 'bug', 'spike', 'test'],
-            item_prefixes: {
-                epic: 'EPIC',
-                story: 'STORY',
-                task: 'TASK',
-                bug: 'BUG',
-                spike: 'SPIKE',
-                test: 'TEST',
-            },
-            directories: [
-                'items/epics',
-                'items/stories',
-                'items/tasks',
-                'items/bugs',
-                'items/spikes',
-                'items/tests',
-            ],
-        },
-        waterfall: {
-            item_types: ['requirement', 'feature', 'task', 'bug', 'spike', 'test'],
-            item_prefixes: {
-                requirement: 'REQ',
-                feature: 'FEAT',
-                task: 'TASK',
-                bug: 'BUG',
-                spike: 'SPIKE',
-                test: 'TEST',
-            },
-            directories: [
-                'items/requirements',
-                'items/features',
-                'items/tasks',
-                'items/bugs',
-                'items/spikes',
-                'items/tests',
-            ],
-        },
-        hybrid: {
-            item_types: [
-                'epic',
-                'story',
-                'requirement',
-                'feature',
-                'task',
-                'bug',
-                'spike',
-                'test',
-            ],
-            item_prefixes: {
-                epic: 'EPIC',
-                story: 'STORY',
-                requirement: 'REQ',
-                feature: 'FEAT',
-                task: 'TASK',
-                bug: 'BUG',
-                spike: 'SPIKE',
-                test: 'TEST',
-            },
-            directories: [
-                'items/epics',
-                'items/stories',
-                'items/requirements',
-                'items/features',
-                'items/tasks',
-                'items/bugs',
-                'items/spikes',
-                'items/tests',
-            ],
-        },
+    const item_types = [...METHODOLOGY_TYPES[methodology]];
+    return {
+        item_types,
+        item_prefixes: Object.fromEntries(item_types.map((type) => [type, ITEM_TYPE_PREFIXES[type]])),
+        directories: item_types.map((type) => TYPE_TO_DIRECTORY[type]),
     };
-    return configs[methodology];
 }
 /**
  * Generates a new item ID with proper prefix and number
  */
 export function generateItemId(type, counter, prefixes) {
-    const defaultPrefixes = {
-        epic: 'EPIC',
-        story: 'STORY',
-        task: 'TASK',
-        requirement: 'REQ',
-        feature: 'FEAT',
-        bug: 'BUG',
-        spike: 'SPIKE',
-        test: 'TEST',
-    };
-    const prefixMap = prefixes || defaultPrefixes;
+    const prefixMap = prefixes || ITEM_TYPE_PREFIXES;
     const prefix = prefixMap[type] || 'ITEM';
     const paddedNumber = counter.toString().padStart(3, '0');
     return `${prefix}-${paddedNumber}`;
@@ -129,39 +100,19 @@ export function generateItemId(type, counter, prefixes) {
  * Used for consistent counter key generation
  */
 export function getTypePrefix(type) {
-    const prefixMap = {
-        epic: 'EPIC',
-        story: 'STORY',
-        task: 'TASK',
-        requirement: 'REQ',
-        feature: 'FEAT',
-        bug: 'BUG',
-        spike: 'SPIKE',
-        test: 'TEST',
-    };
-    return prefixMap[type] || 'ITEM';
+    return ITEM_TYPE_PREFIXES[type] || 'ITEM';
 }
+const ITEM_ID = itemIdPattern();
+const TYPE_BY_PREFIX = new Map(Object.entries(ITEM_TYPE_PREFIXES).map(([type, prefix]) => [prefix, type]));
 /**
  * Parses an item ID into type and number
  */
 export function parseItemId(id) {
-    const match = id.match(/^(EPIC|STORY|TASK|REQ|FEAT|BUG|SPIKE|TEST)-(\d+)$/);
-    if (!match)
+    const match = id.match(ITEM_ID);
+    const type = match ? TYPE_BY_PREFIX.get(match[1]) : undefined;
+    if (!match || !type)
         return null;
-    const typeMap = {
-        EPIC: 'epic',
-        STORY: 'story',
-        TASK: 'task',
-        REQ: 'requirement',
-        FEAT: 'feature',
-        BUG: 'bug',
-        SPIKE: 'spike',
-        TEST: 'test',
-    };
-    return {
-        type: typeMap[match[1]],
-        number: Number.parseInt(match[2], 10),
-    };
+    return { type, number: Number.parseInt(match[2], 10) };
 }
 /**
  * Formats a date for display
@@ -194,7 +145,7 @@ export function sanitizeFilename(name) {
 /**
  * Normalizes escape sequences in description strings received from MCP tool calls.
  *
- * **Problem:** MCP clients (GitHub Copilot ≥ v1.0.0, Claude Code, etc.) transmit
+ * **Problem:** GitHub Copilot MCP clients transmit
  * multiline strings with literal two-character sequences `\n`, `\t` instead of
  * actual Unicode control characters. `JSON.parse` delivers these sequences unchanged,
  * so `writeFileSync` writes them verbatim — producing unreadable `.md` files.
@@ -217,9 +168,6 @@ export function normalizeMarkdown(value) {
     if (value.includes('\n'))
         return value;
     // Slow path: convert MCP-style escape sequences to real control characters
-    return value
-        .replace(/\\n/g, '\n')
-        .replace(/\\t/g, '\t')
-        .replace(/\\r/g, '');
+    return value.replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\r/g, '');
 }
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/init-helpers.d.ts

@@ -14,12 +14,19 @@
  *   <!-- devsteps-managed: true | version: <ver> | hash: sha256:<hex> -->
  *
  * If the file has no frontmatter the comment is prepended to the top.
+ *
+ * Only the whole-file marker above is replaced. The `devsteps-managed:begin` /
+ * `devsteps-managed:end` pair that delimits the contract block is a different
+ * scheme and must survive, or the block-level updater loses the boundary it
+ * replaces (BUG-121).
  */
 export declare function injectDevstepsComment(rawContent: string, hash: string, version: string): string;
 export interface CopiedGithubFiles {
     agents: string[];
     instructions: string[];
     prompts: string[];
+    skills: string[];
+    copilotInstructions: boolean;
 }
 /**
  * Dynamically copy all devsteps-prefixed agent/instruction/prompt files
@@ -29,12 +36,7 @@ export interface CopiedGithubFiles {
  * so that the canonical content hash is stored without touching the YAML block.
  * Returns lists of copied filenames for output/reporting.
  */
-export declare function copyGithubFiles(sourceGithubDir: string, githubAgentsDir: string, githubInstructionsDir: string, githubPromptsDir: string, packageVersion?: string): CopiedGithubFiles;
-/**
- * Copy HIERARCHY.md and AI-GUIDE.md from the package root .devsteps/ dir
- * into the target project's .devsteps/ directory.
- */
-export declare function copyDevstepsDocs(packageRoot: string, devstepsDir: string): void;
+export declare function copyGithubFiles(sourceGithubDir: string, githubAgentsDir: string, githubInstructionsDir: string, githubPromptsDir: string, githubSkillsDir?: string, targetCopilotInstructionsPath?: string, packageVersion?: string): CopiedGithubFiles;
 /**
  * Write SETUP.md into the project's .devsteps/ directory.
  * Contains quick-start instructions, command reference, and troubleshooting.

package/dist/utils/init-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/init-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAc/F;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,qBAAqB,EAAE,MAAM,EAC7B,gBAAgB,EAAE,MAAM,EACxB,cAAc,SAAY,GACzB,iBAAiB,CAsCnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAO/E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAkF3E"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/init-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA0BH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAc/F;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,qBAAqB,EAAE,MAAM,EAC7B,gBAAgB,EAAE,MAAM,EACxB,eAAe,CAAC,EAAE,MAAM,EACxB,6BAA6B,CAAC,EAAE,MAAM,EACtC,cAAc,SAAY,GACzB,iBAAiB,CAqEnB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAE3E"}

package/dist/utils/init-helpers.js

@@ -7,7 +7,19 @@
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { listSkillFiles } from './agent-files-payload.js';
+import { readPackagedContractBlock, writeContractBlock } from './contract-block.js';
+import { renderSetupMd } from './setup-guide.js';
+/**
+ * Written above the contract block when `init` creates the file. It belongs to
+ * the consuming project from that moment on and is never rewritten.
+ */
+const COPILOT_PREAMBLE = `# Copilot instructions
+
+Describe this project here — what it is, how it is built, how it is tested.
+Everything above the DevSteps marker belongs to this project and is never
+rewritten. The marked block below is written by DevSteps and replaced on update.`;
 /**
  * Compute sha256 hex digest of content (UTF-8).
  */
@@ -23,19 +35,24 @@ function sha256(content) {
  *   <!-- devsteps-managed: true | version: <ver> | hash: sha256:<hex> -->
  *
  * If the file has no frontmatter the comment is prepended to the top.
+ *
+ * Only the whole-file marker above is replaced. The `devsteps-managed:begin` /
+ * `devsteps-managed:end` pair that delimits the contract block is a different
+ * scheme and must survive, or the block-level updater loses the boundary it
+ * replaces (BUG-121).
  */
 export function injectDevstepsComment(rawContent, hash, version) {
     const marker = `<!-- devsteps-managed: true | version: ${version} | hash: sha256:${hash} -->`;
-    // Remove old marker if present
-    const withoutOld = rawContent.replace(/<!--\s*devsteps-managed:.*?-->\n?/g, '');
+    // Remove a previous whole-file marker, leaving block delimiters untouched.
+    const withoutOld = rawContent.replace(/<!--\s*devsteps-managed:\s*true\b.*?-->\n?/g, '');
     // Find YAML frontmatter (starts and ends with ---)
     const frontmatterEnd = withoutOld.match(/^---\n[\s\S]*?\n---\n/);
     if (frontmatterEnd) {
         const endIdx = (frontmatterEnd.index ?? 0) + frontmatterEnd[0].length;
-        return withoutOld.slice(0, endIdx) + marker + '\n' + withoutOld.slice(endIdx);
+        return `${withoutOld.slice(0, endIdx) + marker}\n${withoutOld.slice(endIdx)}`;
     }
     // No frontmatter — prepend
-    return marker + '\n' + withoutOld;
+    return `${marker}\n${withoutOld}`;
 }
 /**
  * Dynamically copy all devsteps-prefixed agent/instruction/prompt files
@@ -45,10 +62,12 @@ export function injectDevstepsComment(rawContent, hash, version) {
  * so that the canonical content hash is stored without touching the YAML block.
  * Returns lists of copied filenames for output/reporting.
  */
-export function copyGithubFiles(sourceGithubDir, githubAgentsDir, githubInstructionsDir, githubPromptsDir, packageVersion = 'unknown') {
+export function copyGithubFiles(sourceGithubDir, githubAgentsDir, githubInstructionsDir, githubPromptsDir, githubSkillsDir, targetCopilotInstructionsPath, packageVersion = 'unknown') {
     mkdirSync(githubAgentsDir, { recursive: true });
     mkdirSync(githubInstructionsDir, { recursive: true });
     mkdirSync(githubPromptsDir, { recursive: true });
+    if (githubSkillsDir)
+        mkdirSync(githubSkillsDir, { recursive: true });
     const copyDir = (sourceDir, targetDir, filter) => {
         if (!existsSync(sourceDir))
             return [];
@@ -61,109 +80,42 @@ export function copyGithubFiles(sourceGithubDir, githubAgentsDir, githubInstruct
         }
         return files;
     };
-    return {
-        agents: copyDir(join(sourceGithubDir, 'agents'), githubAgentsDir, (f) => f.startsWith('devsteps') && f.endsWith('.agent.md')),
-        instructions: copyDir(join(sourceGithubDir, 'instructions'), githubInstructionsDir, (f) => f.startsWith('devsteps') && f.endsWith('.instructions.md')),
-        prompts: copyDir(join(sourceGithubDir, 'prompts'), githubPromptsDir, (f) => f.startsWith('devsteps') && f.endsWith('.prompt.md')),
-    };
-}
-/**
- * Copy HIERARCHY.md and AI-GUIDE.md from the package root .devsteps/ dir
- * into the target project's .devsteps/ directory.
- */
-export function copyDevstepsDocs(packageRoot, devstepsDir) {
-    for (const file of ['HIERARCHY.md', 'AI-GUIDE.md']) {
-        const source = join(packageRoot, '.devsteps', file);
-        if (existsSync(source)) {
-            writeFileSync(join(devstepsDir, file), readFileSync(source, 'utf8'));
+    // Skills carry the same whole-file marker as the other payloads, so a later
+    // `updateAgentFiles` run can tell an upstream change from a local edit
+    // instead of treating every installed skill as user-modified.
+    const skills = githubSkillsDir && existsSync(join(sourceGithubDir, 'skills'))
+        ? readdirSync(join(sourceGithubDir, 'skills')).filter((entry) => !entry.startsWith('.'))
+        : [];
+    if (githubSkillsDir) {
+        for (const relativePath of listSkillFiles(sourceGithubDir)) {
+            const target = join(githubSkillsDir, ...relativePath.split('/'));
+            const rawContent = readFileSync(join(sourceGithubDir, 'skills', ...relativePath.split('/')), 'utf8');
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, injectDevstepsComment(rawContent, sha256(rawContent), packageVersion));
         }
     }
+    // Only the managed block is portable: the part above it in the packaged file
+    // describes the DevSteps repository, not the project being initialised.
+    const contractBlock = readPackagedContractBlock(sourceGithubDir);
+    const copilotInstructions = Boolean(targetCopilotInstructionsPath && contractBlock);
+    if (targetCopilotInstructionsPath && contractBlock) {
+        writeContractBlock(targetCopilotInstructionsPath, contractBlock, {
+            preamble: COPILOT_PREAMBLE,
+        });
+    }
+    return {
+        agents: copyDir(join(sourceGithubDir, 'agents'), githubAgentsDir, (f) => f.toLowerCase().startsWith('devsteps-') && f.endsWith('.agent.md')),
+        instructions: copyDir(join(sourceGithubDir, 'instructions'), githubInstructionsDir, (f) => f.toLowerCase().startsWith('devsteps-') && f.endsWith('.instructions.md')),
+        prompts: copyDir(join(sourceGithubDir, 'prompts'), githubPromptsDir, (f) => f.toLowerCase().startsWith('devsteps-') && f.endsWith('.prompt.md')),
+        skills,
+        copilotInstructions,
+    };
 }
 /**
  * Write SETUP.md into the project's .devsteps/ directory.
  * Contains quick-start instructions, command reference, and troubleshooting.
  */
 export function writeSetupMd(projectName, devstepsDir) {
-    const content = `# ${projectName} - Setup Guide
-
-## Prerequisites
-
-- Node.js v18+ (https://nodejs.org)
-- Package manager: pnpm (recommended) or npm
-- Git (optional, for version control)
-
-## Quick Start
-
-\`\`\`bash
-# 1. Install dependencies
-pnpm install  # or: npm install
-
-# 2. Verify setup
-devsteps doctor
-
-# 3. Check project status
-devsteps status
-
-# 4. Add your first item
-devsteps add req "Your first requirement"
-\`\`\`
-
-## MCP Setup (AI Integration)
-
-\`\`\`bash
-# For VS Code or Cursor (auto-detect)
-devsteps setup
-
-# Explicit IDE selection
-devsteps setup --tool vscode
-devsteps setup --tool cursor
-\`\`\`
-
-After setup: restart your IDE, then open Copilot/AI Chat.
-
-## Project Structure
-
-\`\`\`
-${projectName}/
-├── .devsteps/
-│   ├── config.json       # Project configuration
-│   ├── index/            # Refs-style distributed index
-│   ├── items/            # Item files (source of truth)
-│   └── archive/          # Archived items
-└── .vscode/
-    ├── tasks.json        # VS Code tasks
-    └── mcp.json          # MCP configuration
-\`\`\`
-
-## Common Commands
-
-\`\`\`bash
-# Add items
-devsteps add story "Implement feature X"
-devsteps add bug "Error on page load"
-
-# List & filter
-devsteps list --status draft
-devsteps list --type story --priority urgent-important
-
-# Update
-devsteps update STORY-001 --status in-progress
-
-# Link items
-devsteps link TASK-001 implements STORY-005
-
-# Maintenance
-devsteps archive STORY-001
-devsteps purge --status done
-\`\`\`
-
-## Troubleshooting
-
-- **"Project not initialized"** — run \`devsteps init\` in your project directory
-- **"Node.js version too old"** — upgrade to v18+ from nodejs.org
-- **"MCP server not found"** — run \`devsteps setup\`, then restart your IDE
-- **Dependencies missing** — run \`pnpm install\`
-`;
-    writeFileSync(join(devstepsDir, 'SETUP.md'), content);
+    writeFileSync(join(devstepsDir, 'SETUP.md'), renderSetupMd(projectName));
 }
 //# sourceMappingURL=init-helpers.js.map

package/dist/utils/init-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.js","sourceRoot":"","sources":["../../src/utils/init-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init-helpers.js","sourceRoot":"","sources":["../../src/utils/init-helpers.ts"],"names":[],"mappings":"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"}

package/dist/utils/mcp-tool-groups.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Which MCP tool groups a workspace exposes, and how that choice is written
+ * into a host configuration file.
+ *
+ * Three places decide this — the MCP server (reading the environment), the CLI
+ * (`devsteps setup --tools`) and the VS Code extension (a workspace setting) —
+ * and a selection that means different things in different hosts would be worse
+ * than no selection at all. The rules therefore live here, once.
+ *
+ * @see STORY-392
+ */
+/**
+ * Environment variable that selects which MCP tool groups the server exposes.
+ *
+ * Every tool schema sits in the agent's context on every request, so a
+ * workspace that never touches the docs or workflow pipeline can drop those
+ * schemas by naming only the groups it uses. Unset means the default catalog.
+ */
+export declare const MCP_TOOL_GROUP_ENV_VAR = "DEVSTEPS_MCP_TOOLS";
+/**
+ * Selectable MCP tool groups, in catalog order.
+ *
+ * The membership of each group lives in the MCP server's tool catalog; this
+ * list exists so the CLI and the extension can validate a selection without
+ * depending on the server package. `catalog.test.ts` asserts that both stay in
+ * step, so a new group fails there rather than drifting silently.
+ */
+export declare const MCP_TOOL_GROUP_NAMES: readonly ['core', 'docs', 'workflow', 'coord', 'batch'];
+export type McpToolGroupName = (typeof MCP_TOOL_GROUP_NAMES)[number];
+/**
+ * Groups a workspace would get only by naming them, left out of an unset selection and `all`.
+ * Batch creation is explicit; existing default catalog profiles remain unchanged.
+ */
+export declare const MCP_OPT_IN_TOOL_GROUPS: readonly McpToolGroupName[];
+/** What an unset selection or `all` exposes: every group that is not opt-in. */
+export declare const MCP_DEFAULT_TOOL_GROUPS: readonly McpToolGroupName[];
+/**
+ * The groups a parsed selection activates: the default groups for an unset or `all` selection
+ * (plus the opt-in groups it names), the named groups otherwise, and the defaults when nothing
+ * valid remains, so a typo cannot disarm the server.
+ */
+export declare function activeToolGroups(selection: ParsedToolGroupSelection): McpToolGroupName[];
+export interface ParsedToolGroupSelection {
+    /** Recognised group names, deduplicated and in catalog order. */
+    groups: McpToolGroupName[];
+    /** Entries that name neither a group nor the `all` keyword. */
+    unknown: string[];
+    /** True when the selection asks for the default catalog (empty or `all`). */
+    all: boolean;
+}
+/**
+ * Parse a `DEVSTEPS_MCP_TOOLS` value into a validated selection.
+ *
+ * Comma-separated, order- and case-insensitive. Callers decide what to do with
+ * an unusable selection: the server falls back to the default catalog so a typo
+ * cannot disarm it, while the CLI refuses the write and says what is wrong.
+ */
+export declare function parseToolGroupSelection(raw: string | undefined): ParsedToolGroupSelection;
+/**
+ * What a workspace has decided about tool groups.
+ *
+ * `managed: false` means nothing was configured, and the tool-group variable in
+ * an existing host entry is then none of our business — a workspace that wrote
+ * one by hand keeps it. Only an explicit choice makes the key ours to write,
+ * and `all` is explicit too: it removes the key rather than leaving a stale one.
+ */
+export interface ToolGroupSelection {
+    managed: boolean;
+    /** Selected groups, comma-separated; undefined asks for the default catalog. */
+    groups?: string;
+}
+export interface ResolvedToolGroupSelection {
+    selection: ToolGroupSelection;
+    /** Names that were dropped; the caller decides whether to warn or refuse. */
+    unknown: string[];
+}
+/**
+ * Turn a raw setting or flag value into a selection.
+ *
+ * `undefined` means not configured. A value that survives parsing with no valid
+ * group left is treated the same way: acting on a typo would rewrite a host
+ * entry for a selection the server would ignore anyway.
+ */
+export declare function selectToolGroups(raw: string | undefined): ResolvedToolGroupSelection;
+/** The `env` block a selection contributes, empty when the default catalog is active. */
+export declare function toolGroupEnv(selection: ToolGroupSelection | undefined): {
+    env?: Record<string, string>;
+};
+/**
+ * Merge a selection into the environment an existing host entry already carries.
+ *
+ * Variables the workspace added itself are kept — a rewrite is triggered by a
+ * changed runtime resolution, which says nothing about the rest of the entry.
+ * The tool-group key is only replaced when the selection manages it; otherwise
+ * a hand-written selection would be discarded without notice.
+ */
+export declare function mergeToolGroupEnv(existingEnv: unknown, selection: ToolGroupSelection): Record<string, string> | undefined;
+//# sourceMappingURL=mcp-tool-groups.d.ts.map

package/dist/utils/mcp-tool-groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-groups.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-tool-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,YAAI,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAE5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,gBAAgB,EAAc,CAAC;AAE7E,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,EAAE,SAAS,gBAAgB,EAE9D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,wBAAwB,GAAG,gBAAgB,EAAE,CAMxF;AAED,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,wBAAwB,CAczF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,0BAA0B,CAepF;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,SAAS,EAAE,kBAAkB,GAAG,SAAS,GAAG;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,CAEA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,kBAAkB,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAWpC"}