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

package/dist/core/heuristic-classify.js

@@ -0,0 +1,147 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Diataxis heuristic classifier — scoring vector approach (ADR-001)
+ * Pure function: no filesystem access, operates on text excerpts.
+ */
+/** Default threshold for mixed-type detection */
+export const MIXED_THRESHOLD = 0.4;
+/** Minimum H2/H3 subheading ratio to signal explanation type */
+export const SUBHEADING_RATIO_THRESHOLD = 0.08;
+/** Minimum table line ratio to signal reference type */
+export const TABLE_RATIO_THRESHOLD = 0.25;
+/** Secondary table ratio threshold for flat-structure + table → reference heuristic */
+const FLAT_TABLE_THRESHOLD = 0.15;
+/** All Diataxis types */
+export const DIATAXIS_TYPES = [
+    'tutorial',
+    'how-to',
+    'reference',
+    'explanation',
+    'architecture',
+    'research',
+];
+function emptyScores() {
+    return { tutorial: 0, 'how-to': 0, reference: 0, explanation: 0, architecture: 0, research: 0 };
+}
+/**
+ * 9-pattern heuristic classifier from SPIKE-043 + structural heuristics (TASK-549)
+ * + optional Scrum-context boost (STORY-293).
+ * Returns a score vector (ADR-001: scoring approach, not binary).
+ *
+ * @param excerpt - First ~100 lines of the document
+ * @param filepath - Optional file path for path-based heuristics
+ * @param context - Optional Scrum context (Epic/Story title + tags) for bilingual boost
+ */
+export function heuristicClassify(excerpt, filepath, context) {
+    const scores = emptyScores();
+    const lower = excerpt.toLowerCase();
+    const pathLower = (filepath || '').toLowerCase();
+    // --- Path-based signals (strong) ---
+    // Architecture: docs/architecture/, ADR files
+    if (/\/architecture\/|\/adr[-_]|^adr[-_]/i.test(pathLower)) {
+        scores.architecture += 0.6;
+    }
+    // Research: analyst-*, aspect-*, *-session*, research/
+    if (/analyst[-_]|aspect[-_]|[-_]session\d|\/research\//i.test(pathLower)) {
+        scores.research += 0.6;
+    }
+    // --- Content-based signals ---
+    // Tutorial: numbered steps + learning outcomes
+    if (/step\s+\d|## step/i.test(lower))
+        scores.tutorial += 0.3;
+    if (/you will learn|by the end of|prerequisites/i.test(lower))
+        scores.tutorial += 0.3;
+    if (/let'?s\s+(start|begin|create|build)/i.test(lower))
+        scores.tutorial += 0.2;
+    // How-to: imperative headings, task-oriented
+    if (/^##\s+(how to|configure|install|set up|create|add|remove|enable|disable|migrate)/im.test(excerpt)) {
+        scores['how-to'] += 0.4;
+    }
+    if (/quickstart|getting started|setup guide/i.test(lower))
+        scores['how-to'] += 0.3;
+    // Reference: API docs, tables, options
+    if (/^##\s+(api|options|parameters|configuration|properties|methods|endpoints)/im.test(excerpt)) {
+        scores.reference += 0.4;
+    }
+    if (/\|.*\|.*\|/m.test(excerpt) && /type|default|required/i.test(lower))
+        scores.reference += 0.2;
+    if (/```(json|yaml|toml)/i.test(lower))
+        scores.reference += 0.1;
+    // Explanation: conceptual, why-oriented
+    if (/^##\s+(overview|understanding|why|concepts|background|theory|motivation)/im.test(excerpt)) {
+        scores.explanation += 0.4;
+    }
+    if (/the reason|this is because|the idea behind|in contrast/i.test(lower))
+        scores.explanation += 0.2;
+    // Architecture: decision records, ADR patterns in content
+    if (/^##\s+(status|decision outcome|considered options|context and problem)/im.test(excerpt)) {
+        scores.architecture += 0.5;
+    }
+    if (/^##\s+(decision drivers|consequences)/im.test(excerpt))
+        scores.architecture += 0.2;
+    // Research: analysis, findings, investigation
+    if (/^##\s+(findings|analysis|investigation|results|methodology)/im.test(excerpt)) {
+        scores.research += 0.4;
+    }
+    if (/research question|hypothesis|evidence/i.test(lower))
+        scores.research += 0.2;
+    // --- Structural signals (TASK-549) ---
+    const lines = excerpt.split('\n');
+    const nonEmptyLines = lines.filter((l) => l.trim().length > 0).length;
+    const subHeadingLines = lines.filter((l) => /^#{2,3}\s/.test(l)).length;
+    const tableLines = lines.filter((l) => /^\|.+\|/.test(l)).length;
+    const subHeadingRatio = nonEmptyLines > 0 ? subHeadingLines / nonEmptyLines : 0;
+    const tableRatio = nonEmptyLines > 0 ? tableLines / nonEmptyLines : 0;
+    // Signal 1: Rich H2/H3 subheading structure → explanation
+    if (subHeadingRatio > SUBHEADING_RATIO_THRESHOLD)
+        scores.explanation += 0.2;
+    // Signal 2: High table density → reference
+    if (tableRatio > TABLE_RATIO_THRESHOLD)
+        scores.reference += 0.2;
+    // Signal 3: Flat structure (single H1, no sub-headings) + tables → reference
+    const h1Count = lines.filter((l) => /^#\s/.test(l)).length;
+    const h2PlusCount = lines.filter((l) => /^#{2,}\s/.test(l)).length;
+    if (h1Count === 1 && h2PlusCount === 0 && tableRatio > FLAT_TABLE_THRESHOLD) {
+        scores.reference += 0.15;
+    }
+    // --- Scrum-context signals (STORY-293) — bilingual EN + DE ---
+    if (context) {
+        const ctxText = [
+            context.epic_title ?? '',
+            context.story_title ?? '',
+            ...(context.epic_tags ?? []),
+        ]
+            .join(' ')
+            .toLowerCase();
+        if (/hardware|interface|api|spec|datenblatt|kenndaten|grenzwert/.test(ctxText))
+            scores.reference += 0.2;
+        if (/als endnutzer|als benutzer|as a user|möchte ich|i want to/.test(ctxText))
+            scores['how-to'] += 0.2;
+        if (/setup|deployment|installation|konfiguration|einrichtung/.test(ctxText))
+            scores['how-to'] += 0.15;
+        if (/overview|architektur|konzept|hintergrund|warum|why/.test(ctxText))
+            scores.explanation += 0.15;
+        if (/fehler|error|troubleshoot|debug|diagnose/.test(ctxText))
+            scores.reference += 0.1;
+    }
+    // --- Normalize scores to [0, 1] ---
+    const maxRaw = Math.max(...Object.values(scores), 0.001);
+    for (const type of DIATAXIS_TYPES) {
+        scores[type] = Math.min(scores[type] / maxRaw, 1.0);
+    }
+    // --- Determine winner and mixed status ---
+    const sorted = DIATAXIS_TYPES.map((t) => ({ type: t, score: scores[t] })).sort((a, b) => b.score - a.score);
+    const winner = sorted[0];
+    const second = sorted[1];
+    const mixed = second.score >= MIXED_THRESHOLD;
+    return {
+        scores,
+        winner: winner.type,
+        confidence: winner.score,
+        mixed,
+        secondType: mixed ? second.type : undefined,
+    };
+}
+//# sourceMappingURL=heuristic-classify.js.map

package/dist/core/heuristic-classify.js.map

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

package/dist/core/host-config.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The `devsteps` entry every agent host carries, and the rules for merging it
+ * into a file that already exists.
+ *
+ * Three writers produce this entry — `devsteps setup`, the VS Code extension at
+ * activation, and the `setup_host` MCP tool — and before STORY-399 two of them
+ * built it independently. The shape belongs here so a change reaches all three.
+ *
+ * Deliberately free of filesystem access: `host-setup.ts` owns the writing, this
+ * module owns the shape.
+ *
+ * @see EPIC-056 STORY-399 TASK-776
+ */
+import { type ToolGroupSelection } from '../utils/mcp-tool-groups.js';
+/** The explicit hosts DevSteps configures. Each reads a different format. */
+export type AgentHost = 'claude' | 'copilot' | 'codex';
+/** How this machine launches the MCP server. */
+export interface ServerRuntime {
+    command: string;
+    args: string[];
+}
+/** The entry written under the host's server map. */
+export interface HostEntry {
+    type: string;
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/** No opinion on tool groups — leave whatever the entry already carries. */
+export declare const UNMANAGED_SELECTION: ToolGroupSelection;
+/**
+ * Path of the file a host reads, relative to the project root.
+ *
+ * Copilot in VS Code reads `.vscode/mcp.json`; Claude Code reads `.mcp.json` in
+ * the project root and never looks at `.vscode/`. Configuring both means writing
+ * both files, not one shared file.
+ */
+export declare function hostConfigPath(host: AgentHost): string;
+/** Top-level key holding the server map. The two hosts disagree on its name. */
+export declare function hostServersKey(host: AgentHost): 'mcpServers' | 'servers';
+/**
+ * Build the entry for one host.
+ *
+ * The VS Code entry appends `${workspaceFolder}`, which VS Code expands at spawn
+ * time, so the written file stays portable and safe to commit. The Claude entry
+ * must not: Claude Code expands only real environment variables, so the literal
+ * would reach argv and break workspace resolution. It spawns stdio servers with
+ * the working directory set to the project instead, which the server's validated
+ * `process.cwd()` fallback resolves.
+ */
+export declare function buildHostEntry(host: AgentHost, runtime: ServerRuntime, selection?: ToolGroupSelection): HostEntry;
+/**
+ * True when the installed entry already matches what would be written now.
+ *
+ * The tool-group variable joins the comparison only when the selection manages
+ * it. Otherwise a workspace that wrote one by hand would see its entry rewritten
+ * on every activation; when the selection does manage it, comparing it is what
+ * makes a changed selection reach the file at all.
+ */
+export declare function entryMatches(installed: unknown, expected: HostEntry, selection?: ToolGroupSelection): boolean;
+/**
+ * Merge the expected entry over the installed one, keeping every environment
+ * variable the workspace added itself.
+ *
+ * A rewrite is usually triggered by a changed runtime resolution, which says
+ * nothing about the rest of the entry: replacing the whole object would discard
+ * a `NODE_OPTIONS` the workspace relies on, and would silently drop a
+ * hand-written tool-group selection. That key is replaced only when the
+ * selection manages it.
+ */
+export declare function mergeHostEntry(installed: unknown, expected: HostEntry, selection?: ToolGroupSelection): HostEntry;
+/**
+ * Place the merged entry into the host file's document, preserving every other
+ * server the workspace configured.
+ */
+export declare function mergeHostDocument(host: AgentHost, existing: Record<string, unknown> | undefined, expected: HostEntry, selection?: ToolGroupSelection): Record<string, unknown>;
+//# sourceMappingURL=host-config.d.ts.map

package/dist/core/host-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-config.d.ts","sourceRoot":"","sources":["../../src/core/host-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AAErC,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvD,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,kBAAuC,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAGtD;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAGxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,aAAa,EACtB,SAAS,GAAE,kBAAwC,GAClD,SAAS,CAcX;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,OAAO,EAClB,QAAQ,EAAE,SAAS,EACnB,SAAS,GAAE,kBAAwC,GAClD,OAAO,CAgBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,OAAO,EAClB,QAAQ,EAAE,SAAS,EACnB,SAAS,GAAE,kBAAwC,GAClD,SAAS,CAQX;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,QAAQ,EAAE,SAAS,EACnB,SAAS,GAAE,kBAAwC,GAClD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB"}

package/dist/core/host-config.js

@@ -0,0 +1,121 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The `devsteps` entry every agent host carries, and the rules for merging it
+ * into a file that already exists.
+ *
+ * Three writers produce this entry — `devsteps setup`, the VS Code extension at
+ * activation, and the `setup_host` MCP tool — and before STORY-399 two of them
+ * built it independently. The shape belongs here so a change reaches all three.
+ *
+ * Deliberately free of filesystem access: `host-setup.ts` owns the writing, this
+ * module owns the shape.
+ *
+ * @see EPIC-056 STORY-399 TASK-776
+ */
+import { MCP_TOOL_GROUP_ENV_VAR, mergeToolGroupEnv, } from '../utils/mcp-tool-groups.js';
+/** No opinion on tool groups — leave whatever the entry already carries. */
+export const UNMANAGED_SELECTION = { managed: false };
+/**
+ * Path of the file a host reads, relative to the project root.
+ *
+ * Copilot in VS Code reads `.vscode/mcp.json`; Claude Code reads `.mcp.json` in
+ * the project root and never looks at `.vscode/`. Configuring both means writing
+ * both files, not one shared file.
+ */
+export function hostConfigPath(host) {
+    if (host === 'codex')
+        return '.codex/config.toml';
+    return host === 'claude' ? '.mcp.json' : '.vscode/mcp.json';
+}
+/** Top-level key holding the server map. The two hosts disagree on its name. */
+export function hostServersKey(host) {
+    if (host === 'codex')
+        throw new Error('Codex uses the format-aware TOML setup planner.');
+    return host === 'claude' ? 'mcpServers' : 'servers';
+}
+/**
+ * Build the entry for one host.
+ *
+ * The VS Code entry appends `${workspaceFolder}`, which VS Code expands at spawn
+ * time, so the written file stays portable and safe to commit. The Claude entry
+ * must not: Claude Code expands only real environment variables, so the literal
+ * would reach argv and break workspace resolution. It spawns stdio servers with
+ * the working directory set to the project instead, which the server's validated
+ * `process.cwd()` fallback resolves.
+ */
+export function buildHostEntry(host, runtime, selection = UNMANAGED_SELECTION) {
+    if (host === 'codex')
+        throw new Error('Codex uses an explicitly project-bound runtime.');
+    const args = host === 'claude'
+        ? [...runtime.args]
+        : // biome-ignore lint/suspicious/noTemplateCurlyInString: literal VS Code variable syntax
+            [...runtime.args, '${workspaceFolder}'];
+    const env = mergeToolGroupEnv({}, selection);
+    return {
+        type: 'stdio',
+        command: runtime.command,
+        args,
+        ...(env ? { env } : {}),
+    };
+}
+/**
+ * True when the installed entry already matches what would be written now.
+ *
+ * The tool-group variable joins the comparison only when the selection manages
+ * it. Otherwise a workspace that wrote one by hand would see its entry rewritten
+ * on every activation; when the selection does manage it, comparing it is what
+ * makes a changed selection reach the file at all.
+ */
+export function entryMatches(installed, expected, selection = UNMANAGED_SELECTION) {
+    if (!installed || typeof installed !== 'object')
+        return false;
+    const entry = installed;
+    const sameCommand = entry.type === expected.type &&
+        entry.command === expected.command &&
+        JSON.stringify(entry.args) === JSON.stringify(expected.args);
+    if (!sameCommand)
+        return false;
+    if (!selection.managed)
+        return true;
+    // Compare the tool group variable by key: an entry may carry others, such as
+    // a NODE_OPTIONS the workspace set, and a positional comparison would read
+    // whichever happened to come first.
+    const installedEnv = (entry.env ?? {});
+    return installedEnv[MCP_TOOL_GROUP_ENV_VAR] === expected.env?.[MCP_TOOL_GROUP_ENV_VAR];
+}
+/**
+ * Merge the expected entry over the installed one, keeping every environment
+ * variable the workspace added itself.
+ *
+ * A rewrite is usually triggered by a changed runtime resolution, which says
+ * nothing about the rest of the entry: replacing the whole object would discard
+ * a `NODE_OPTIONS` the workspace relies on, and would silently drop a
+ * hand-written tool-group selection. That key is replaced only when the
+ * selection manages it.
+ */
+export function mergeHostEntry(installed, expected, selection = UNMANAGED_SELECTION) {
+    const installedEnv = installed && typeof installed === 'object' ? installed.env : undefined;
+    const env = mergeToolGroupEnv(installedEnv, selection);
+    if (env)
+        return { ...expected, env };
+    const { env: _dropped, ...withoutEnv } = expected;
+    return withoutEnv;
+}
+/**
+ * Place the merged entry into the host file's document, preserving every other
+ * server the workspace configured.
+ */
+export function mergeHostDocument(host, existing, expected, selection = UNMANAGED_SELECTION) {
+    const key = hostServersKey(host);
+    const servers = (existing?.[key] ?? {});
+    return {
+        ...existing,
+        [key]: {
+            ...servers,
+            devsteps: mergeHostEntry(servers.devsteps, expected, selection),
+        },
+    };
+}
+//# sourceMappingURL=host-config.js.map

package/dist/core/host-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-config.js","sourceRoot":"","sources":["../../src/core/host-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAElB,MAAM,6BAA6B,CAAC;AAmBrC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAuB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,oBAAoB,CAAC;IAClD,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,kBAAkB,CAAC;AAC9D,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,IAAI,IAAI,KAAK,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACzF,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAe,EACf,OAAsB,EACtB,SAAS,GAAuB,mBAAmB;IAEnD,IAAI,IAAI,KAAK,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACzF,MAAM,IAAI,GACR,IAAI,KAAK,QAAQ;QACf,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;QACnB,CAAC,CAAC,wFAAwF;YACxF,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,iBAAiB,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC7C,OAAO;QACL,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI;QACJ,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAkB,EAClB,QAAmB,EACnB,SAAS,GAAuB,mBAAmB;IAEnD,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,KAAK,GAAG,SAAoC,CAAC;IAEnD,MAAM,WAAW,GACf,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI;QAC5B,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO;QAClC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,CAAC,SAAS,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAEpC,6EAA6E;IAC7E,2EAA2E;IAC3E,oCAAoC;IACpC,MAAM,YAAY,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAC;IAClE,OAAO,YAAY,CAAC,sBAAsB,CAAC,KAAK,QAAQ,CAAC,GAAG,EAAE,CAAC,sBAAsB,CAAC,CAAC;AACzF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAkB,EAClB,QAAmB,EACnB,SAAS,GAAuB,mBAAmB;IAEnD,MAAM,YAAY,GAChB,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAE,SAA+B,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAChG,MAAM,GAAG,GAAG,iBAAiB,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IACvD,IAAI,GAAG;QAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,CAAC;IAErC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,UAAU,EAAE,GAAG,QAAQ,CAAC;IAClD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAe,EACf,QAA6C,EAC7C,QAAmB,EACnB,SAAS,GAAuB,mBAAmB;IAEnD,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAA4B,CAAC;IACnE,OAAO;QACL,GAAG,QAAQ;QACX,CAAC,GAAG,CAAC,EAAE;YACL,GAAG,OAAO;YACV,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC;SAChE;KACF,CAAC;AACJ,CAAC"}

package/dist/core/host-setup.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * `host-config.ts` owns the shape of what is written; this module owns the
+ * filesystem side and the report a caller shows the user.
+ *
+ * @see EPIC-056 STORY-399 TASK-776 TASK-777
+ */
+import { type CodexMode } from '../utils/codex-types.js';
+import { type ToolGroupSelection } from '../utils/mcp-tool-groups.js';
+import type { UpdateAgentFilesResult } from '../utils/update-agent-files.js';
+import { type AgentHost, type ServerRuntime } from './host-config.js';
+/**
+ * Variable that names the model Claude Code gives a subagent by default.
+ *
+ * A subagent resolves its model as: invocation parameter → its own frontmatter
+ * → this variable → the main session's model. The built-in agent types carry no
+ * frontmatter, so without this they run on whatever the session runs on, which
+ * is the largest model in play.
+ */
+export declare const SUBAGENT_MODEL_ENV_VAR = "CLAUDE_CODE_SUBAGENT_MODEL";
+/**
+ * Model an adapter offers when the user asks for one without naming it.
+ *
+ * Sonnet carries multi-step delegated work while costing a fraction of an
+ * Opus-class session; an agent that needs more says so in its own frontmatter,
+ * which takes precedence over this value. Never applied on its own — writing
+ * `.claude/settings.json` always follows an explicit request.
+ */
+export declare const DEFAULT_SUBAGENT_MODEL = "sonnet";
+/** Public marketplace a consumer project declares to reach the plugin. */
+export declare const PLUGIN_MARKETPLACE = "devsteps";
+export declare const PLUGIN_REPOSITORY = "Schnick371/devsteps";
+export declare const PLUGIN_ID = "devsteps@devsteps";
+export interface HostSetupOptions {
+    codexMode?: CodexMode;
+    sourceCodexDir?: string;
+    packageVersion?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    maxBackups?: number;
+    /** Which hosts to configure. */
+    hosts: AgentHost[];
+    /** Raw tool group selection; omitted or empty leaves an existing one alone. */
+    tools?: string;
+    /** Declare the Claude Code plugin in the project settings as well. */
+    plugin?: boolean;
+    /**
+     * Model for subagents that name none themselves.
+     *
+     * Explicit values replace the declared setting. A fallback fills an absent
+     * preference; omitting the model leaves the project's model untouched.
+     */
+    subagentModel?: string;
+    /** Background preferences fill an absent model; only explicit requests replace one. */
+    subagentModelSource?: 'explicit' | 'fallback';
+    /** Override the runtime resolution; the VS Code extension supplies its own. */
+    runtime?: ServerRuntime;
+}
+export interface HostSetupFile {
+    path: string;
+    action: 'created' | 'updated' | 'unchanged';
+    /** Present only when this write changes the project's subagent model. */
+    subagentModelChange?: {
+        previous?: string;
+        current: string;
+    };
+}
+export interface HostSetupResult {
+    codex?: UpdateAgentFilesResult;
+    dryRun?: boolean;
+    files: HostSetupFile[];
+    runtime: ServerRuntime & {
+        strategy: 'global' | 'npx';
+    };
+    selection: ToolGroupSelection;
+    unknownGroups: string[];
+    /** Subagent model now standing in the project settings, when one was set. */
+    subagentModel?: string;
+    /** True whenever a tool selection was written and the host must restart. */
+    restartRequired: boolean;
+    /** Configuration decisions that adapters must show, such as a declared plugin route. */
+    notes: string[];
+}
+/**
+ * Resolve how this machine should launch the MCP server.
+ *
+ * Global install first, npx second — the order the VS Code extension and the
+ * Claude Code plugin launcher also apply. A maintainer can install a prerelease
+ * globally and have every host pick it up; a pure npx configuration would bypass
+ * that, because npx resolves from the registry and its own cache rather than
+ * from the global npm prefix. Deliberately unpinned so an ordinary user gets the
+ * latest published release.
+ *
+ * The explicit `--package` form is required because the package declares three
+ * bins.
+ */
+export declare function resolveServerRuntime(): ServerRuntime & {
+    strategy: 'global' | 'npx';
+};
+/**
+ * Declare the plugin in the project's `.claude/settings.json`.
+ *
+ * These are the two keys `claude plugin marketplace add --scope project` and
+ * `claude plugin install --scope project` produce. Writing them directly means a
+ * committed project brings the plugin with it, and nobody has to type a
+ * `/plugin` command in a fresh clone.
+ *
+ * The source is the public repository rather than a directory path, because a
+ * directory source resolves only on the machine that wrote it.
+ */
+export interface ClaudeSettingsOptions {
+    /** Declare the marketplace and enable the plugin. */
+    plugin?: boolean;
+    /** Explicit model for subagents; replaces an existing entry. */
+    subagentModel?: string;
+    /** Omitted retains explicit-call compatibility; background callers must use fallback. */
+    subagentModelSource?: 'explicit' | 'fallback';
+}
+export interface ClaudeSettingsResult extends HostSetupFile {
+    /** The model the file now names, whether written here or already present. */
+    subagentModel?: string;
+}
+/**
+ * Write the project-level Claude Code settings DevSteps owns.
+ *
+ * Both concerns share one file, so they share one read-modify-write: two passes
+ * would make the second overwrite the first's in-memory view.
+ */
+export declare function applyClaudeSettings(projectPath: string, options: ClaudeSettingsOptions): ClaudeSettingsResult;
+/**
+ * Declare the plugin in the project's `.claude/settings.json`.
+ *
+ * These are the two keys `claude plugin marketplace add --scope project` and
+ * `claude plugin install --scope project` produce. Writing them directly means a
+ * committed project brings the plugin with it, and nobody has to type a
+ * `/plugin` command in a fresh clone.
+ *
+ * The source is the public repository rather than a directory path, because a
+ * directory source resolves only on the machine that wrote it.
+ */
+export declare function declareClaudePlugin(projectPath: string): HostSetupFile;
+/** Configure host entries and explicitly requested settings, reporting every change. */
+export declare function setupHost(projectPath: string, options: HostSetupOptions): HostSetupResult;
+//# sourceMappingURL=host-setup.d.ts.map

package/dist/core/host-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-setup.d.ts","sourceRoot":"","sources":["../../src/core/host-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EACL,KAAK,SAAS,EAId,KAAK,aAAa,EAEnB,MAAM,kBAAkB,CAAC;AAO1B;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,WAAW,CAAC;AAE/C,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AACvD,eAAO,MAAM,SAAS,sBAAsB,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,mBAAmB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAC9C,+EAA+E;IAC/E,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC5C,yEAAyE;IACzE,mBAAmB,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,aAAa,GAAG;QAAE,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAAA;KAAE,CAAC;IACxD,SAAS,EAAE,kBAAkB,CAAC;IAC9B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,eAAe,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,GAAG;IAAE,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAAA;CAAE,CAYrF;AA+BD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;CAC/C;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CA6CtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAEtE;AAmDD,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAwDzF"}