hammoc 1.3.0 → 1.5.0

package/packages/server/dist/utils/secretHeuristic.js

@@ -0,0 +1,163 @@
+/**
+ * Story 30.1 (Task 1): single source of truth for secret-pattern heuristics
+ * used by the harness write paths.
+ *
+ * Replaces four drifted SECRET_PATTERNS definitions (harnessAgentService,
+ * harnessCommandService, harnessHookService, harnessMcpService). Drift
+ * before this module:
+ *
+ *   - agent / command / hook : 32-char base64 unanchored, Bearer unanchored
+ *   - mcp                    : 40-char base64 anchored,   Bearer anchored
+ *
+ * Canonical chosen here (Story 30.1 sub-spike 1.0, option (b)):
+ *   - 32-char base64 unanchored, Bearer unanchored
+ *
+ * Rationale: detection-rate first; Story 30.1 AC4.c provides a per-save
+ * "mark not a secret" opt-out that absorbs false positives, whereas missed
+ * detections silently leak credentials. MCP's stricter anchors were a local
+ * accident, not a deliberate spec decision.
+ *
+ * Two entry points are exposed because the four services walk two distinct
+ * shapes:
+ *
+ *   - detectSecretsInText  → string body (agent / command / hook commands)
+ *                            returns matched line numbers (1-based)
+ *   - detectSecretsInValue → arbitrary JSON-like value (mcp config)
+ *                            returns matched dot-paths
+ *
+ * Both strip `${ENV_VAR}` references first so legitimate env-var indirection
+ * (`Authorization: 'Bearer ${GH_TOKEN}'`) does not raise false positives.
+ */
+export const SECRET_PATTERNS = [
+    { name: 'bearer', re: /Bearer\s+[A-Za-z0-9._-]{16,}/ },
+    { name: 'sk', re: /sk-[A-Za-z0-9]{20,}/ },
+    { name: 'aws', re: /AKIA[0-9A-Z]{16}/ },
+    { name: 'slack', re: /xox[baprs]-[A-Za-z0-9-]{10,}/ },
+    { name: 'base64', re: /[A-Za-z0-9+/=]{32,}/g, minEntropy: 4.0 },
+];
+export const ENV_REF_RE = /\$\{[A-Za-z_][A-Za-z0-9_]*\}/g;
+/**
+ * Shannon entropy in bits/char of an arbitrary string. Used by patterns that
+ * opt in via `minEntropy` (currently the loose base64 pattern only).
+ */
+export function shannonEntropy(s) {
+    if (!s)
+        return 0;
+    const counts = new Map();
+    for (const ch of s)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    const len = s.length;
+    let h = 0;
+    for (const c of counts.values()) {
+        const p = c / len;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+// Story 30.3 spike #2 — the loose base64 pattern adds two combined gates so
+// natural English compounds (e.g. PascalCase identifiers) cannot trigger a
+// false positive:
+//   (i)  Shannon entropy ≥ 4.0 bits/char  — filters single-symbol runs
+//   (ii) ≥ 1 character outside [A-Za-z]   — filters English compounds that
+//        otherwise meet the entropy bar (real base64 of random bytes almost
+//        always contains digits or '+'/'/'/'=' over 32+ chars)
+// Both gates run only for patterns that opt in via `minEntropy`.
+const BASE64_NON_ALPHA_RE = /[0-9+/=]/;
+/**
+ * Tests whether `text` matches a single SecretPattern, applying the optional
+ * `minEntropy` + non-alpha gates to each individual regex match. The pattern's
+ * `re` must be either non-global (single test) or global (per-match gating).
+ */
+function patternMatches(text, pat) {
+    if (pat.minEntropy === undefined) {
+        return pat.re.test(text);
+    }
+    const re = pat.re.global ? pat.re : new RegExp(pat.re.source, pat.re.flags + 'g');
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const s = m[0];
+        if (shannonEntropy(s) >= pat.minEntropy && BASE64_NON_ALPHA_RE.test(s)) {
+            return true;
+        }
+        if (m.index === re.lastIndex)
+            re.lastIndex += 1;
+    }
+    return false;
+}
+function stripEnvRefs(text) {
+    // Reset is required because the regex is /g — but `replace` with a /g regex
+    // re-creates state each call. Still, clone-replace pattern is safest.
+    return text.replace(ENV_REF_RE, '');
+}
+/**
+ * Line-based scanner for textual command / prompt bodies (agent system
+ * prompts, slash command bodies, hook command/prompt strings).
+ */
+export function detectSecretsInText(text) {
+    if (!text || typeof text !== 'string') {
+        return { matched: false, patternNames: [], lines: [] };
+    }
+    const stripped = stripEnvRefs(text);
+    const matchedNames = new Set();
+    for (const pat of SECRET_PATTERNS) {
+        if (patternMatches(stripped, pat)) {
+            matchedNames.add(pat.name);
+        }
+    }
+    if (matchedNames.size === 0) {
+        return { matched: false, patternNames: [], lines: [] };
+    }
+    const lines = [];
+    const split = text.split(/\r?\n/);
+    for (let i = 0; i < split.length; i += 1) {
+        const lineStripped = stripEnvRefs(split[i]);
+        for (const pat of SECRET_PATTERNS) {
+            if (patternMatches(lineStripped, pat)) {
+                lines.push(i + 1);
+                break;
+            }
+        }
+    }
+    return { matched: true, patternNames: Array.from(matchedNames), lines };
+}
+/**
+ * Object-walk scanner for JSON-like values (mcp server config). Each string
+ * leaf is evaluated against the canonical patterns; matches are reported as
+ * dot-paths (`env.GITHUB_TOKEN`, `headers.Authorization`, ...).
+ */
+export function detectSecretsInValue(value, basePath = []) {
+    const paths = [];
+    const matchedNames = new Set();
+    const walk = (v, p) => {
+        if (typeof v === 'string') {
+            const stripped = stripEnvRefs(v);
+            if (!stripped)
+                return;
+            for (const pat of SECRET_PATTERNS) {
+                if (patternMatches(stripped, pat)) {
+                    paths.push(p.join('.'));
+                    matchedNames.add(pat.name);
+                    return;
+                }
+            }
+            return;
+        }
+        if (Array.isArray(v)) {
+            v.forEach((item, i) => walk(item, [...p, String(i)]));
+            return;
+        }
+        if (v && typeof v === 'object') {
+            for (const [k, child] of Object.entries(v)) {
+                walk(child, [...p, k]);
+            }
+        }
+    };
+    walk(value, basePath);
+    return {
+        matched: paths.length > 0,
+        patternNames: Array.from(matchedNames),
+        paths,
+    };
+}
+//# sourceMappingURL=secretHeuristic.js.map

package/packages/server/dist/utils/secretHeuristic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretHeuristic.js","sourceRoot":"","sources":["../../src/utils/secretHeuristic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAgBH,MAAM,CAAC,MAAM,eAAe,GAA6B;IACvD,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,8BAA8B,EAAE;IACtD,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,qBAAqB,EAAE;IACzC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,kBAAkB,EAAE;IACvC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,8BAA8B,EAAE;IACrD,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,sBAAsB,EAAE,UAAU,EAAE,GAAG,EAAE;CAChE,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,+BAA+B,CAAC;AAE1D;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,EAAE,IAAI,CAAC;QAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC;IACrB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QAClB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,4EAA4E;AAC5E,2EAA2E;AAC3E,kBAAkB;AAClB,uEAAuE;AACvE,2EAA2E;AAC3E,4EAA4E;AAC5E,+DAA+D;AAC/D,iEAAiE;AACjE,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAEvC;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,GAAkB;IACtD,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;IAClF,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;IACjB,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,SAAS;YAAE,EAAE,CAAC,SAAS,IAAI,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAcD,SAAS,YAAY,CAAC,IAAY;IAChC,4EAA4E;IAC5E,sEAAsE;IACtE,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,IAAI,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;YAClC,IAAI,cAAc,CAAC,YAAY,EAAE,GAAG,CAAC,EAAE,CAAC;gBACtC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBAClB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,WAAqB,EAAE;IAEvB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,IAAI,GAAG,CAAC,CAAU,EAAE,CAAW,EAAQ,EAAE;QAC7C,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,CAAC,QAAQ;gBAAE,OAAO;YACtB,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;gBAClC,IAAI,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;oBAClC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;oBACxB,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBAC3B,OAAO;gBACT,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACtD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC/B,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,EAAE,CAAC;gBACtE,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtB,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC;QACzB,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC;QACtC,KAAK;KACN,CAAC;AACJ,CAAC"}

package/packages/server/dist/utils/secretPlaceholderNamer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Story 30.3 (Task 2.1): single source of truth for placeholder ENV names
+ * used when `secretsPolicy === 'placeholder'`.
+ *
+ * The export pipeline walks each domain's payload, calls `detectSecretsInValue`
+ * / `detectSecretsInText` from secretHeuristic.ts to locate every secret, and
+ * for each match asks this module to produce a stable ENV reference name.
+ * The name is what gets written to disk as `${ENV_REF_NAME}` so the importer
+ * can wire it up via environment variables.
+ *
+ * Naming policy (AC2.c):
+ *   - mcp     `env.<KEY>`              → `<UPPER_NAME>_<UPPER_KEY>`
+ *   - mcp     `headers.Authorization`  → `BEARER_TOKEN_<UPPER_NAME>`
+ *   - mcp     other paths              → `<UPPER_NAME>_<UPPER_LAST_PATH_SEG>`
+ *   - hook    `command` / `prompt`     → `HOOK_<EVENT>_TOKEN`
+ *   - command body match               → `COMMAND_<UPPER_SLASH_PATH>_TOKEN`
+ *   - agent   body match               → `AGENT_<UPPER_NAME>_TOKEN`
+ *   - claude-md body match             → `CLAUDE_MD_TOKEN_<INDEX>`
+ *
+ * The names are intentionally not collision-free across multiple secrets in
+ * the same card — the export pipeline appends a numeric suffix when the same
+ * name is already emitted in that bundle (handled by the caller, not here),
+ * so this module stays a pure-function lookup table.
+ */
+import type { BundleItemDomain } from '@hammoc/shared';
+export interface NamePlaceholderInput {
+    /** Card domain — disambiguates the naming rule. */
+    domain: BundleItemDomain;
+    /**
+     * For mcp/hook: the dot-path returned by `detectSecretsInValue` (e.g.
+     * `mcpServers.context7.env.API_KEY`, `mcpServers.gh.headers.Authorization`).
+     * For command/agent/claude-md: an empty string or `body:<line>`.
+     */
+    fieldPath: string;
+    /** Active card name (skill: skillName, mcp: serverName, agent: name, etc.). */
+    cardName: string;
+    /** For hook entries — the matched HarnessHookEvent. */
+    hookEvent?: string;
+}
+export declare function namePlaceholder(input: NamePlaceholderInput): string;
+//# sourceMappingURL=secretPlaceholderNamer.d.ts.map

package/packages/server/dist/utils/secretPlaceholderNamer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretPlaceholderNamer.d.ts","sourceRoot":"","sources":["../../src/utils/secretPlaceholderNamer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiBD,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CA4CnE"}

package/packages/server/dist/utils/secretPlaceholderNamer.js

@@ -0,0 +1,81 @@
+/**
+ * Story 30.3 (Task 2.1): single source of truth for placeholder ENV names
+ * used when `secretsPolicy === 'placeholder'`.
+ *
+ * The export pipeline walks each domain's payload, calls `detectSecretsInValue`
+ * / `detectSecretsInText` from secretHeuristic.ts to locate every secret, and
+ * for each match asks this module to produce a stable ENV reference name.
+ * The name is what gets written to disk as `${ENV_REF_NAME}` so the importer
+ * can wire it up via environment variables.
+ *
+ * Naming policy (AC2.c):
+ *   - mcp     `env.<KEY>`              → `<UPPER_NAME>_<UPPER_KEY>`
+ *   - mcp     `headers.Authorization`  → `BEARER_TOKEN_<UPPER_NAME>`
+ *   - mcp     other paths              → `<UPPER_NAME>_<UPPER_LAST_PATH_SEG>`
+ *   - hook    `command` / `prompt`     → `HOOK_<EVENT>_TOKEN`
+ *   - command body match               → `COMMAND_<UPPER_SLASH_PATH>_TOKEN`
+ *   - agent   body match               → `AGENT_<UPPER_NAME>_TOKEN`
+ *   - claude-md body match             → `CLAUDE_MD_TOKEN_<INDEX>`
+ *
+ * The names are intentionally not collision-free across multiple secrets in
+ * the same card — the export pipeline appends a numeric suffix when the same
+ * name is already emitted in that bundle (handled by the caller, not here),
+ * so this module stays a pure-function lookup table.
+ */
+const NON_ALNUM_RE = /[^A-Za-z0-9]+/g;
+function toUpperSnake(input) {
+    return input
+        .trim()
+        .replace(NON_ALNUM_RE, '_')
+        .replace(/^_+|_+$/g, '')
+        .toUpperCase();
+}
+function lastPathSegment(fieldPath) {
+    const segments = fieldPath.split('.').filter((s) => s.length > 0);
+    return segments[segments.length - 1] ?? '';
+}
+export function namePlaceholder(input) {
+    const card = toUpperSnake(input.cardName) || 'UNNAMED';
+    switch (input.domain) {
+        case 'mcp': {
+            const fp = input.fieldPath;
+            // Authorization header → BEARER_TOKEN_<CARD>
+            if (/(^|\.)headers\.Authorization$/i.test(fp)) {
+                return `BEARER_TOKEN_${card}`;
+            }
+            // env.<KEY> → <CARD>_<KEY>
+            const envMatch = fp.match(/(^|\.)env\.([^.]+)$/);
+            if (envMatch) {
+                return `${card}_${toUpperSnake(envMatch[2])}`;
+            }
+            // Fallback: last segment
+            const seg = toUpperSnake(lastPathSegment(fp)) || 'SECRET';
+            return `${card}_${seg}`;
+        }
+        case 'hook': {
+            const evt = toUpperSnake(input.hookEvent ?? 'GENERIC');
+            return `HOOK_${evt}_${card}_TOKEN`;
+        }
+        case 'command': {
+            return `COMMAND_${card}_TOKEN`;
+        }
+        case 'agent': {
+            return `AGENT_${card}_TOKEN`;
+        }
+        case 'claude-md': {
+            return `CLAUDE_MD_${card || 'TOKEN'}_${toUpperSnake(input.fieldPath) || 'TOKEN'}`
+                .replace(/_+$/, '');
+        }
+        case 'skill': {
+            return `SKILL_${card}_TOKEN`;
+        }
+        case 'bmad': {
+            return `BMAD_${card}_TOKEN`;
+        }
+        default: {
+            const _exhaustive = input.domain;
+            return _exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=secretPlaceholderNamer.js.map

package/packages/server/dist/utils/secretPlaceholderNamer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretPlaceholderNamer.js","sourceRoot":"","sources":["../../src/utils/secretPlaceholderNamer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAmBH,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAEtC,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK;SACT,IAAI,EAAE;SACN,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC;SAC1B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,SAAS,eAAe,CAAC,SAAiB;IACxC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClE,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC;IAEvD,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;QACrB,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;YAC3B,6CAA6C;YAC7C,IAAI,gCAAgC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC9C,OAAO,gBAAgB,IAAI,EAAE,CAAC;YAChC,CAAC;YACD,2BAA2B;YAC3B,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;YACjD,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,CAAC;YACD,yBAAyB;YACzB,MAAM,GAAG,GAAG,YAAY,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,IAAI,QAAQ,CAAC;YAC1D,OAAO,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;QAC1B,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,IAAI,SAAS,CAAC,CAAC;YACvD,OAAO,QAAQ,GAAG,IAAI,IAAI,QAAQ,CAAC;QACrC,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,OAAO,WAAW,IAAI,QAAQ,CAAC;QACjC,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,SAAS,IAAI,QAAQ,CAAC;QAC/B,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,OAAO,aAAa,IAAI,IAAI,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,OAAO,EAAE;iBAC9E,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACxB,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,SAAS,IAAI,QAAQ,CAAC;QAC/B,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,OAAO,QAAQ,IAAI,QAAQ,CAAC;QAC9B,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,KAAK,CAAC,MAAM,CAAC;YACxC,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC"}

package/packages/server/dist/utils/serverPathResolver.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Story 30.2 (Task 1.5): server-side PATH resolver for the
+ * `mcp/command-not-on-path` lint rule.
+ *
+ * Mirrors the `which`/`where` + 5s timeout pattern used by
+ * serverController.ts:14-31 for npm path resolution. Absolute paths skip the
+ * shell call entirely and fall through to a simple `fs.existsSync` check —
+ * faster and avoids spurious `which: not found` lines on stderr for inputs
+ * that obviously don't need PATH resolution.
+ *
+ * The result is intentionally shaped as `{ resolved: string | null }` (not a
+ * boolean) so the caller can surface the resolved absolute path in tooltips
+ * without re-running the lookup.
+ */
+export interface ResolveCommandResult {
+    resolved: string | null;
+}
+/**
+ * Resolve `cmd` against the current process PATH.
+ *
+ * - Absolute path → `fs.existsSync` only (no shell).
+ * - Relative path containing a separator → resolved relative to `cwd`
+ *   (uncommon for MCP `command` fields but covered for completeness).
+ * - Bare name → `where.exe` on Windows / `which` elsewhere.
+ *
+ * Never throws — failures collapse to `{ resolved: null }`.
+ */
+export declare function resolveCommandOnServerPath(cmd: string): ResolveCommandResult;
+//# sourceMappingURL=serverPathResolver.d.ts.map

package/packages/server/dist/utils/serverPathResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverPathResolver.d.ts","sourceRoot":"","sources":["../../src/utils/serverPathResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAID;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CA8B5E"}

package/packages/server/dist/utils/serverPathResolver.js

@@ -0,0 +1,59 @@
+/**
+ * Story 30.2 (Task 1.5): server-side PATH resolver for the
+ * `mcp/command-not-on-path` lint rule.
+ *
+ * Mirrors the `which`/`where` + 5s timeout pattern used by
+ * serverController.ts:14-31 for npm path resolution. Absolute paths skip the
+ * shell call entirely and fall through to a simple `fs.existsSync` check —
+ * faster and avoids spurious `which: not found` lines on stderr for inputs
+ * that obviously don't need PATH resolution.
+ *
+ * The result is intentionally shaped as `{ resolved: string | null }` (not a
+ * boolean) so the caller can surface the resolved absolute path in tooltips
+ * without re-running the lookup.
+ */
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+const RESOLVE_TIMEOUT_MS = 5000;
+/**
+ * Resolve `cmd` against the current process PATH.
+ *
+ * - Absolute path → `fs.existsSync` only (no shell).
+ * - Relative path containing a separator → resolved relative to `cwd`
+ *   (uncommon for MCP `command` fields but covered for completeness).
+ * - Bare name → `where.exe` on Windows / `which` elsewhere.
+ *
+ * Never throws — failures collapse to `{ resolved: null }`.
+ */
+export function resolveCommandOnServerPath(cmd) {
+    if (!cmd || typeof cmd !== 'string')
+        return { resolved: null };
+    const trimmed = cmd.trim();
+    if (!trimmed)
+        return { resolved: null };
+    if (path.isAbsolute(trimmed)) {
+        return { resolved: fs.existsSync(trimmed) ? trimmed : null };
+    }
+    // Path with a separator (e.g. "./bin/foo" or "scripts/run.sh") — resolve
+    // against cwd. Server PATH is irrelevant in this case.
+    if (trimmed.includes('/') || trimmed.includes('\\')) {
+        const abs = path.resolve(process.cwd(), trimmed);
+        return { resolved: fs.existsSync(abs) ? abs : null };
+    }
+    const finder = process.platform === 'win32' ? 'where.exe' : 'which';
+    try {
+        const stdout = execFileSync(finder, [trimmed], {
+            encoding: 'utf-8',
+            timeout: RESOLVE_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const first = stdout.trim().split(/\r?\n/)[0]?.trim();
+        return { resolved: first ? first : null };
+    }
+    catch {
+        // Non-zero exit (not found) or timeout — both surface as "unresolved".
+        return { resolved: null };
+    }
+}
+//# sourceMappingURL=serverPathResolver.js.map

package/packages/server/dist/utils/serverPathResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverPathResolver.js","sourceRoot":"","sources":["../../src/utils/serverPathResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAMxB,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAE/D,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAExC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/D,CAAC;IAED,yEAAyE;IACzE,uDAAuD;IACvD,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;QACjD,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC;IACpE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE;YAC7C,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,kBAAkB;YAC3B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACtD,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/packages/server/dist/utils/snippetPaths.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Story 29.2: Snippet path resolver.
+ *
+ * The snippet system has three scopes that map to different on-disk roots:
+ *
+ *   - project   → `<projectRoot>/.hammoc/snippets/`
+ *   - user      → `~/.hammoc/snippets/`
+ *   - bundled   → server-bundled snippets (read-only, located alongside the
+ *                 server build at `<serverDist>/snippets/`)
+ *
+ * `resolveSnippetPath` is the only path-shaping entry point used by
+ * `snippetService` — it accepts `{ scope, projectSlug?, name }` and never lets
+ * a caller-supplied relative path through. NAME_RE rejects anything outside
+ * `[A-Za-z0-9._-]+` so directory traversal (`..`, `/`, `\`, `\0`, drive
+ * letters, UNC prefixes) is impossible by construction.
+ *
+ * On-disk filename normalization: writes always land at `<root>/<name>.md`
+ * regardless of input form. Reads accept both `<name>.md` and the legacy
+ * extension-less `<name>` (snippetResolver supports both for back-compat) so
+ * existing bundled and user files continue to load.
+ */
+/** Snippet name regex — same shape as snippetResolver's NAME_RE. */
+export declare const SNIPPET_NAME_RE: RegExp;
+/** Return the absolute path of `~/.hammoc/snippets/`. */
+export declare function getUserSnippetsDir(): string;
+/** Return the absolute path of the server-bundled snippets directory. */
+export declare function getBundledSnippetsDir(): string;
+/** Return the absolute path of `<projectRoot>/.hammoc/snippets/`. */
+export declare function getProjectSnippetsDir(projectSlug: string): Promise<string>;
+export interface ResolvedSnippetPath {
+    /** Root directory (the snippets dir itself, not the project root). */
+    resolvedRoot: string;
+    /** `<resolvedRoot>/<name>.md`. */
+    absolutePath: string;
+    /** Same path but without `.md` — legacy format used for back-compat reads. */
+    legacyAbsolutePath: string;
+    /** True when this path is read-only (bundled). */
+    readOnly: boolean;
+}
+export type SnippetScope = 'project' | 'user' | 'bundled';
+export interface SnippetPathRef {
+    scope: SnippetScope;
+    /** Required when scope === 'project'. */
+    projectSlug?: string;
+    name: string;
+}
+/**
+ * Resolve a snippet path with NAME_RE validation and bundled read-only flagging.
+ * Throws an Error with `code: 'HARNESS_PATH_DENIED'` for invalid names.
+ */
+export declare function resolveSnippetPath(ref: SnippetPathRef): Promise<ResolvedSnippetPath>;
+/**
+ * Throws an HARNESS_PATH_DENIED Error when the name is invalid.
+ *
+ * Note: SNIPPET_NAME_RE allows `.` so single-dot names (`a.b`) pass through.
+ * That also means literal `..` would pass the regex — we reject it
+ * separately below, mirroring snippetResolver.resolveSnippet's defensive
+ * filter.
+ */
+export declare function validateSnippetName(name: string): void;
+//# sourceMappingURL=snippetPaths.d.ts.map

package/packages/server/dist/utils/snippetPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippetPaths.d.ts","sourceRoot":"","sources":["../../src/utils/snippetPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH,oEAAoE;AACpE,eAAO,MAAM,eAAe,QAAsB,CAAC;AAOnD,yDAAyD;AACzD,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED,qEAAqE;AACrE,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAchF;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA4B1F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAatD"}

package/packages/server/dist/utils/snippetPaths.js

@@ -0,0 +1,123 @@
+/**
+ * Story 29.2: Snippet path resolver.
+ *
+ * The snippet system has three scopes that map to different on-disk roots:
+ *
+ *   - project   → `<projectRoot>/.hammoc/snippets/`
+ *   - user      → `~/.hammoc/snippets/`
+ *   - bundled   → server-bundled snippets (read-only, located alongside the
+ *                 server build at `<serverDist>/snippets/`)
+ *
+ * `resolveSnippetPath` is the only path-shaping entry point used by
+ * `snippetService` — it accepts `{ scope, projectSlug?, name }` and never lets
+ * a caller-supplied relative path through. NAME_RE rejects anything outside
+ * `[A-Za-z0-9._-]+` so directory traversal (`..`, `/`, `\`, `\0`, drive
+ * letters, UNC prefixes) is impossible by construction.
+ *
+ * On-disk filename normalization: writes always land at `<root>/<name>.md`
+ * regardless of input form. Reads accept both `<name>.md` and the legacy
+ * extension-less `<name>` (snippetResolver supports both for back-compat) so
+ * existing bundled and user files continue to load.
+ */
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'node:url';
+import { projectService } from '../services/projectService.js';
+/** Hammoc home root override for tests. Mirrors `HAMMOC_HARNESS_HOME_OVERRIDE`. */
+const HOME_OVERRIDE_ENV = 'HAMMOC_HOME_OVERRIDE';
+/** Bundled snippet directory override for tests (e.g. point at a tmp dir). */
+const BUNDLED_OVERRIDE_ENV = 'HAMMOC_BUNDLED_SNIPPETS_DIR';
+/** Snippet name regex — same shape as snippetResolver's NAME_RE. */
+export const SNIPPET_NAME_RE = /^[a-zA-Z0-9._-]+$/;
+const SNIPPETS_SUBDIR = '.hammoc/snippets';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_BUNDLED_DIR = path.resolve(__dirname, '..', 'snippets');
+/** Return the absolute path of `~/.hammoc/snippets/`. */
+export function getUserSnippetsDir() {
+    const override = process.env[HOME_OVERRIDE_ENV];
+    if (override && override.length > 0) {
+        return path.join(override, '.hammoc', 'snippets');
+    }
+    return path.join(os.homedir(), '.hammoc', 'snippets');
+}
+/** Return the absolute path of the server-bundled snippets directory. */
+export function getBundledSnippetsDir() {
+    const override = process.env[BUNDLED_OVERRIDE_ENV];
+    if (override && override.length > 0) {
+        return override;
+    }
+    return DEFAULT_BUNDLED_DIR;
+}
+/** Return the absolute path of `<projectRoot>/.hammoc/snippets/`. */
+export async function getProjectSnippetsDir(projectSlug) {
+    if (!projectSlug) {
+        throw makePathDeniedError('projectSlug is required for project scope');
+    }
+    if (projectSlug.includes('\0') ||
+        projectSlug.includes('..') ||
+        projectSlug.includes('/') ||
+        projectSlug.includes('\\')) {
+        throw makePathDeniedError('projectSlug must not contain path separators');
+    }
+    const projectRoot = await projectService.resolveOriginalPath(projectSlug);
+    return path.join(projectRoot, SNIPPETS_SUBDIR);
+}
+/**
+ * Resolve a snippet path with NAME_RE validation and bundled read-only flagging.
+ * Throws an Error with `code: 'HARNESS_PATH_DENIED'` for invalid names.
+ */
+export async function resolveSnippetPath(ref) {
+    validateSnippetName(ref.name);
+    let resolvedRoot;
+    let readOnly = false;
+    if (ref.scope === 'project') {
+        if (!ref.projectSlug) {
+            throw makePathDeniedError('projectSlug is required for project scope');
+        }
+        resolvedRoot = path.resolve(await getProjectSnippetsDir(ref.projectSlug));
+    }
+    else if (ref.scope === 'user') {
+        resolvedRoot = path.resolve(getUserSnippetsDir());
+    }
+    else {
+        resolvedRoot = path.resolve(getBundledSnippetsDir());
+        readOnly = true;
+    }
+    // Belt + suspenders: even though NAME_RE forbids separators, double-check
+    // the resolved file stays inside the root.
+    const absolutePath = path.resolve(resolvedRoot, `${ref.name}.md`);
+    if (absolutePath !== resolvedRoot &&
+        !absolutePath.startsWith(resolvedRoot + path.sep)) {
+        throw makePathDeniedError('snippet path escapes root');
+    }
+    const legacyAbsolutePath = path.resolve(resolvedRoot, ref.name);
+    return { resolvedRoot, absolutePath, legacyAbsolutePath, readOnly };
+}
+/**
+ * Throws an HARNESS_PATH_DENIED Error when the name is invalid.
+ *
+ * Note: SNIPPET_NAME_RE allows `.` so single-dot names (`a.b`) pass through.
+ * That also means literal `..` would pass the regex — we reject it
+ * separately below, mirroring snippetResolver.resolveSnippet's defensive
+ * filter.
+ */
+export function validateSnippetName(name) {
+    if (!name || typeof name !== 'string') {
+        throw makePathDeniedError('snippet name is required');
+    }
+    if (name.includes('\0')) {
+        throw makePathDeniedError('null byte in snippet name');
+    }
+    if (name === '..' || name === '.' || name.includes('/') || name.includes('\\')) {
+        throw makePathDeniedError(`path traversal denied: ${name}`);
+    }
+    if (!SNIPPET_NAME_RE.test(name)) {
+        throw makePathDeniedError(`invalid snippet name: ${name}`);
+    }
+}
+function makePathDeniedError(message) {
+    const err = new Error(message);
+    err.code = 'HARNESS_PATH_DENIED';
+    return err;
+}
+//# sourceMappingURL=snippetPaths.js.map

package/packages/server/dist/utils/snippetPaths.js.map

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

package/packages/server/dist/utils/structuredEditor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Story 28.0.5: YAML / JSONC round-trip editor.
+ *
+ * The goal is to mutate a single key inside a structured config file while
+ * preserving the author's comments, blank lines, key order, and quoting style.
+ *
+ * - YAML  → `yaml` (eemeli) `parseDocument` + `doc.setIn/deleteIn` + `doc.toString()`.
+ *           The Document AST keeps comment & blank-line metadata attached to
+ *           each node, and `toString()` re-emits them.
+ *   NOTE: `js-yaml@4` remains a coexisting dependency for session-meta parsing
+ *   elsewhere in the codebase, but has no comment-preservation path and must
+ *   not be used for harness edits.
+ *
+ * - JSONC → `jsonc-parser` `modify` + `applyEdits`. This is the same path VS
+ *           Code uses when it edits user `settings.json` — comments and
+ *           formatting are preserved.
+ *
+ * Both entry points throw `HARNESS_PARSE_ERROR` on unparseable input so the
+ * harness controller can surface the envelope and the client can fall back to
+ * raw editing.
+ */
+import { type HarnessStructuredPatchOp } from '@hammoc/shared';
+/**
+ * Apply structured patches to a YAML source string while preserving comments,
+ * blank lines, and key order.
+ */
+export declare function applyYamlPatch(source: string, ops: HarnessStructuredPatchOp[]): string;
+/**
+ * Apply structured patches to a JSONC source string while preserving comments
+ * and formatting. Inserts missing intermediate objects as needed (matches
+ * `jsonc-parser` `modify` default behavior).
+ */
+export declare function applyJsoncPatch(source: string, ops: HarnessStructuredPatchOp[]): string;
+//# sourceMappingURL=structuredEditor.d.ts.map

package/packages/server/dist/utils/structuredEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredEditor.d.ts","sourceRoot":"","sources":["../../src/utils/structuredEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH,OAAO,EAAkB,KAAK,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAQ/E;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB,EAAE,GAAG,MAAM,CAmCtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB,EAAE,GAAG,MAAM,CAqCvF"}