hammoc 1.4.0 → 1.6.0

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"}

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

@@ -0,0 +1,111 @@
+/**
+ * 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 { parseDocument } from 'yaml';
+import { modify, applyEdits, parse, parseTree, findNodeAtLocation, printParseErrorCode, } from 'jsonc-parser';
+import { HARNESS_ERRORS } from '@hammoc/shared';
+function parseError(format, cause) {
+    const err = new Error(`failed to parse ${format}: ${cause?.message ?? String(cause)}`);
+    err.code = HARNESS_ERRORS.HARNESS_PARSE_ERROR.code;
+    return err;
+}
+/**
+ * Apply structured patches to a YAML source string while preserving comments,
+ * blank lines, and key order.
+ */
+export function applyYamlPatch(source, ops) {
+    let doc;
+    try {
+        doc = parseDocument(source, { keepSourceTokens: true });
+        if (doc.errors.length > 0) {
+            throw doc.errors[0];
+        }
+    }
+    catch (cause) {
+        throw parseError('yaml', cause);
+    }
+    // A freshly-created empty document has `contents: null`; we need a map so
+    // setIn can plant new keys at the top level.
+    if (doc.contents == null) {
+        doc.contents = doc.createNode({});
+    }
+    for (const op of ops) {
+        if (!op.path || op.path.length === 0) {
+            throw parseError('yaml', new Error('patch op requires a non-empty path'));
+        }
+        if (op.value === undefined) {
+            // Idempotent delete: if any segment (including intermediates) is already
+            // absent, the target is effectively deleted — skip. `doc.deleteIn`
+            // itself only no-ops on a missing leaf; a missing intermediate throws.
+            if (!doc.hasIn(op.path))
+                continue;
+            doc.deleteIn(op.path);
+        }
+        else {
+            doc.setIn(op.path, op.value);
+        }
+    }
+    // toString() preserves original comments/blank lines/quote style for any
+    // node that was not explicitly replaced.
+    return doc.toString();
+}
+/**
+ * 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 function applyJsoncPatch(source, ops) {
+    // Validate the source up front — `modify` silently starts from `{}` on
+    // garbage input, which would quietly erase the user's file. Feed the
+    // official errors array to catch unterminated strings, missing values, etc.
+    if (source.trim().length > 0) {
+        const errors = [];
+        parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+        if (errors.length > 0) {
+            const first = errors[0];
+            throw parseError('jsonc', new Error(`${printParseErrorCode(first.error)} at offset ${first.offset}`));
+        }
+    }
+    const formattingOptions = {
+        insertSpaces: true,
+        tabSize: 2,
+        eol: source.includes('\r\n') ? '\r\n' : '\n',
+    };
+    let current = source;
+    for (const op of ops) {
+        if (!op.path || op.path.length === 0) {
+            throw parseError('jsonc', new Error('patch op requires a non-empty path'));
+        }
+        // Idempotent delete: `modify(undefined)` throws "Can not delete…" when the
+        // target (or any intermediate) does not exist; treat that as a no-op so
+        // callers can apply delete patches without first probing state.
+        if (op.value === undefined) {
+            const tree = parseTree(current, [], { allowTrailingComma: true, disallowComments: false });
+            if (!tree || !findNodeAtLocation(tree, op.path))
+                continue;
+        }
+        // `modify` takes `undefined` to mean "remove", matching HarnessStructuredPatchOp.value semantics.
+        const edits = modify(current, op.path, op.value, { formattingOptions });
+        current = applyEdits(current, edits);
+    }
+    return current;
+}
+//# sourceMappingURL=structuredEditor.js.map

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

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

package/packages/server/package.json

@@ -15,23 +15,27 @@
     "test:all": "vitest run"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.114",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.158",
+    "@anthropic-ai/sdk": "^0.100.1",
     "@hammoc/shared": "*",
     "bcrypt": "^6.0.0",
     "chokidar": "^5.0.0",
     "cookie-session": "^2.1.1",
     "cors": "^2.8.5",
     "express": "^4.21.0",
-    "express-rate-limit": "^8.3.1",
     "helmet": "^8.1.0",
     "i18next": "^24.2.3",
+    "ignore": "^5.3.2",
     "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
+    "jszip": "^3.10.1",
     "multer": "^2.1.1",
     "node-pty": "^1.0.0",
     "sharp": "^0.34.5",
     "simple-git": "^3.27.0",
     "socket.io": "^4.8.0",
     "web-push": "^3.6.7",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/packages/server/resources/internals/INDEX.md

@@ -0,0 +1,25 @@
+# Hammoc Internals (Agent-Only Reference)
+
+This folder documents Hammoc's internal mechanisms that an in-IDE agent may need to read or correlate, but that are deliberately omitted from the user-facing manual. The user does not need to know any of this; the agent does.
+
+## How to use
+
+Read individual entries **on demand** when the user's request involves the underlying mechanism (for example: correlating an attached image with a file on disk, understanding how a session ID maps to a JSONL file). Do not pre-load this folder.
+
+## Entries
+
+- [Image Storage](./image-storage.md) — On-disk path and filename scheme for chat-attached images
+- [Harness File Layout](./harness-files.md) — Where `.claude/` items (skills, commands, agents, hooks, MCP servers, `CLAUDE.md`) live on disk, when changes take effect, the Context Builder's Hammoc-managed SessionStart files, plugin install-state paths, and how the Secret-on-Shared guard relates to direct file writes
+- [Observability Storage](./observability-storage.md) — Where the MCP call log and exact-token-count cache live, their JSONL/JSON format, body-stripping, and 30-day retention
+- [BMad QA-Fix Marker](./bmad-qa-fix-marker.md) — The `<!-- hammoc:qa-fix -->` story-file convention that drives QA re-review recommendations and the board's "QA Fixed" badge
+
+## Maintenance
+
+Add a new file here whenever there is internal behavior the agent needs to act on but the user does not need to see. Likely future entries:
+
+- Session ID and project-path slug encoding under `~/.claude/projects/`
+- JSONL message tree structure (parent/child UUIDs, branching)
+- Permission-mode internal effects on the SDK call
+- Snippet resolution order and substitution rules
+
+Each new file should describe the on-disk reality (paths, formats, lifecycle), not the user-facing UI behavior — that belongs in the user manual.

package/packages/server/resources/internals/bmad-qa-fix-marker.md

@@ -0,0 +1,32 @@
+# BMad QA-Fix Marker
+
+A Hammoc-specific convention layered on top of standard BMad story files. It lets the project-overview Next Step Recommender (manual §11.5) and the board's "QA Fixed" badge (§10.7) know whether a developer has already addressed the **current** QA gate — without guessing from file modification times (the old, unreliable approach: `review-story` rewrites the story after the gate, which made a freshly-reviewed story look "stale").
+
+## The marker
+
+A single HTML comment inside the story markdown file:
+
+```
+<!-- hammoc:qa-fix gate="<the gate's `updated` value>" applied="true|false" -->
+```
+
+- It is an HTML comment, so standard BMad tooling ignores it and it never changes the story's Status or the gate file.
+- `gate` is the QA gate's `updated:` value — it ties the marker to one specific gate. When QA later re-reviews, the gate's `updated` changes and any marker pointing at the old value becomes stale automatically.
+- `applied="false"` → "QA flagged this gate; a fix is still needed." `applied="true"` → "Dev addressed this gate."
+
+## Who writes it
+
+- **QA review** (Hammoc's bundled `qa-review` snippet) appends `applied="false"` in the story's **QA Results** section when it issues a CONCERNS or FAIL gate.
+- **Apply QA fixes** (the bundled `apply-qa-fixes` snippet) appends `applied="true"` in the story's **Completion Notes** after the fixes are made — without touching Status or the gate file.
+
+If you perform a QA review or apply QA fixes **manually** (not through these snippets), append the matching marker yourself so the recommender and badge stay accurate.
+
+## How it is read
+
+The server (BMad status service) collects all markers in a story and matches them against the **current** gate's `updated` value to derive a per-story `gateFixState`:
+
+- an `applied="true"` marker for the current gate → **`applied`** (Dev done; QA re-review is the next step)
+- only an `applied="false"` marker for the current gate → **`needed`** (Dev must apply fixes)
+- no marker for the current gate → **`undefined`** → the UI offers **both** actions (Apply QA fixes / Request QA review) and lets the user choose, because it can't tell whether fixes were applied (legacy story, external BMad project, or manually-edited gate)
+
+An `applied` marker wins over a `needed` marker for the same gate. The board shows the sky-blue **QA Fixed** badge only when `gateFixState='applied'` for a FAIL/CONCERNS gate.

package/packages/server/resources/internals/harness-files.md

@@ -0,0 +1,85 @@
+# Harness File Layout
+
+The Harness Workbench (user-facing, see manual §12) edits Claude Code's `.claude/` configuration trees in place. An agent can reach the same files directly with Read / Write / Edit and skip the UI when that's faster.
+
+## On-disk roots
+
+Two trees, walked in this priority order:
+
+```
+<projectRoot>/.claude/        # project scope (highest)
+<homeDir>/.claude/            # global scope (user scope)
+```
+
+When the same name (skill, command, agent, hook, MCP server, snippet) exists in both, the project copy is **active** and the global copy is **shadowed** but kept on disk.
+
+`<homeDir>` must be resolved before use — Read / Write / Edit do not expand `~`. On Windows that is `C:\Users\<user>\`.
+
+## Per-item layout
+
+| Item | Path (under either `.claude/` root) | Format |
+|------|--------------------------------------|--------|
+| Skill | `skills/<name>/SKILL.md` + bundle assets in the same directory | Markdown body + YAML frontmatter (`name`, `description`, `version`) |
+| Slash command | `commands/<name>.md` | Markdown body + YAML frontmatter |
+| Sub-agent | `agents/<name>.md` | Markdown body + YAML frontmatter (`name`, `description`, `tools`) |
+| Hook | `settings.json` → `hooks.<EventName>[]` entries | JSON; one event name per array key (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreCompact`, `Notification`) |
+| MCP server | `.mcp.json` at the project root, or `<homeDir>/.claude/.mcp.json` | JSON; entries under `mcpServers.<name>` |
+| `CLAUDE.md` | `<projectRoot>/.claude/CLAUDE.md`, `<homeDir>/.claude/CLAUDE.md` | Plain Markdown; both files load into every session, project wins on conflict |
+| Plugin | `plugins/<vendor>__<name>/` | Plugin bundle directory; treated read-only by Hammoc — copy items out to project/global to customize |
+
+Hammoc-native `%snippets` are a separate layer (see manual §4.6); they live under `<projectRoot>/.hammoc/snippets/` and `<homeDir>/.hammoc/snippets/`, **not** the `.claude/` tree.
+
+## Context Builder generated files (Hammoc-managed)
+
+The Context Builder (manual §12.17) writes two Hammoc-owned files plus one `settings.json` entry:
+
+| File | Role |
+|------|------|
+| `<projectRoot>/.hammoc/context-builder.json` | Manifest — the single source of truth: `enabled` flag, reference-file list, dynamic-variable toggles, recent-commit count, custom-command list |
+| `<projectRoot>/.hammoc/hooks/context-builder.mjs` | Generated Node.js SessionStart hook. Regenerated from the manifest on every change; reads the reference files fresh, recomputes the variables, runs acknowledged custom commands, and prints `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"…"}}` |
+| `<projectRoot>/.claude/settings.json` → `hooks.SessionStart[]` | Auto-registered entry whose `command` is `node "<absPath>/.hammoc/hooks/context-builder.mjs"` (forward-slash normalized) |
+
+Hammoc recognizes its own SessionStart entry by the `.hammoc/hooks/context-builder.` substring in the command — there is no metadata key. **Do not hand-edit that entry or the `.mjs` script directly**: the Context Builder panel owns them and regenerates the script (overwriting manual edits) on the next save. To change the injected context, edit `context-builder.json` (or use the panel). User-authored SessionStart entries that do not contain the marker substring are left untouched.
+
+## Plugin install state (read-only)
+
+The Marketplace panel (manual §12.19) and the Plugins panel read Claude Code's own plugin bookkeeping under `<homeDir>/.claude/plugins/`:
+
+- `known_marketplaces.json` — registered marketplace repos
+- `marketplaces/<name>/.claude-plugin/marketplace.json` — each marketplace's catalog manifest (`plugins[]`)
+- `installed_plugins.json` — which plugins are installed (used to mark catalog cards "Installed")
+
+Hammoc only **reads** these; installs/uninstalls happen through the interactive `/plugin …` slash commands in a Claude CLI session, after which a file watcher refreshes the cards.
+
+## Sharing scope
+
+Each file's "share" status is computed from the project's `.gitignore`:
+
+- **Shared** — File path is tracked by git
+- **Local** — File path is untracked but `.claude/` is not ignored
+- **Ignored** — A `.gitignore` rule excludes `.claude/` (or an ancestor)
+
+The workbench shows a badge for each file. When an agent writes a file under `.claude/`, the resulting share scope is whatever the `.gitignore` already says — Hammoc does not rewrite `.gitignore` on the agent's behalf.
+
+## Secret-on-Shared guard
+
+When the user saves a `Shared`-scope file through the UI, Hammoc scans for plaintext secrets (entropy + pattern heuristic) and blocks the save with a dialog. **An agent writing the file directly via Write / Edit bypasses that dialog.** If the agent is editing a `Shared` file under `.claude/`, it must avoid committing plaintext API keys, bearer tokens, etc. Use a sibling `*.local.<ext>` file (gitignored) and reference it from the shared file, or use `${ENV_VAR}` references that the hook / MCP runtime expands.
+
+## When changes take effect
+
+- **Skills, commands, agents, CLAUDE.md, snippets** — Picked up on the next message in a chat turn (the system prompt and tool list re-resolve on each turn).
+- **Hooks** — Same: next message in a chat turn.
+- **MCP servers** — Picked up only on a **fresh session spawn**, not mid-session. The workbench UI shows a "Takes effect on your next user message" banner with a "Start new session" button after the user edits an MCP entry; an agent making MCP edits should remind the user to start a new session, or do so on their behalf.
+- **Plugin enable/disable** — Same as MCP: fresh spawn required.
+
+## Static lint (informational)
+
+The workbench runs seven static-lint rules over the trees (see manual §12.12). Agents writing harness files should keep these rules in mind even though writes are not blocked:
+
+- duplicate names across scopes
+- invalid hook matcher regex
+- frontmatter / JSON parse errors
+- MCP `stdio` command not on `PATH`
+- malformed MCP URLs
+- non-standard agent tool names
+- hook bodies referencing undefined env vars