hammoc 1.4.0 → 1.5.0

package/packages/server/dist/services/snippetService.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Story 29.2: Snippet management service.
+ *
+ * Manages the three-scope snippet store consumed by `snippetResolver` for
+ * `%name%` chat-input expansion:
+ *
+ *   - project   → `<projectRoot>/.hammoc/snippets/<name>.md`         (mutable)
+ *   - user      → `~/.hammoc/snippets/<name>.md`                     (mutable)
+ *   - bundled   → `<serverDist>/snippets/<name>[.md]`                (read-only)
+ *
+ * Differences from the harness services (Epic 28):
+ *   - no YAML frontmatter — body is free-form markdown
+ *   - no plugin scope — `bundled` replaces it but is structurally simpler
+ *     (no manifest, no installed_plugins.json lookup)
+ *   - no watcher integration (Story 29.2 Phase 1) — `noteLocalWrite` is not
+ *     called because snippets are NOT in the harness watcher's subscription
+ *     tree (`fileWatcherService` only watches `.claude/`, never `.hammoc/`)
+ *
+ * STALE_WRITE / HARNESS_FILE_EXISTS contract mirrors `harnessService` so the
+ * client can reuse its existing conflict UX.
+ */
+import { type SnippetCopyRequest, type SnippetCopyResponse, type SnippetDeleteRequest, type SnippetDeleteResponse, type SnippetListResponse, type SnippetReadResponse, type SnippetWriteRequest, type SnippetWriteResponse } from '@hammoc/shared';
+import { type SnippetPathRef } from '../utils/snippetPaths.js';
+declare class SnippetService {
+    /**
+     * List snippets across all three scopes. Names are NOT deduplicated — the
+     * client renders one card per (scope, name) combination so users can see
+     * shadowing relationships explicitly. Resolution at runtime
+     * (snippetResolver) still applies project > user > bundled precedence.
+     */
+    list(opts: {
+        projectSlug?: string;
+    }): Promise<SnippetListResponse>;
+    read(ref: SnippetPathRef): Promise<SnippetReadResponse>;
+    /** Create a new snippet — fails with HARNESS_FILE_EXISTS when a same-named file exists. */
+    create(ref: SnippetPathRef, body: SnippetWriteRequest): Promise<SnippetWriteResponse>;
+    /** Update an existing snippet body with optional STALE_WRITE guard. */
+    update(ref: SnippetPathRef, body: SnippetWriteRequest): Promise<SnippetWriteResponse>;
+    delete(ref: SnippetPathRef, body: SnippetDeleteRequest): Promise<SnippetDeleteResponse>;
+    /**
+     * Copy a snippet across scopes.
+     *
+     *   project ↔ user      → bi-directional
+     *   bundled → project   → one-way clone
+     *   bundled → user      → one-way clone
+     *
+     * `bundled` is never a target. When the target exists the call resolves
+     * according to `onConflict` (default 'abort' → HARNESS_FILE_EXISTS).
+     */
+    copy(req: SnippetCopyRequest): Promise<SnippetCopyResponse>;
+}
+export declare const snippetService: SnippetService;
+export {};
+//# sourceMappingURL=snippetService.d.ts.map

package/packages/server/dist/services/snippetService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippetService.d.ts","sourceRoot":"","sources":["../../src/services/snippetService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAExB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AA0FlC,cAAM,cAAc;IAClB;;;;;OAKG;IACG,IAAI,CAAC,IAAI,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgBlE,IAAI,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsB7D,2FAA2F;IACrF,MAAM,CACV,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,oBAAoB,CAAC;IAyBhC,uEAAuE;IACjE,MAAM,CACV,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,oBAAoB,CAAC;IA4C1B,MAAM,CACV,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,qBAAqB,CAAC;IAiCjC;;;;;;;;;OASG;IACG,IAAI,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CA4FlE;AAeD,eAAO,MAAM,cAAc,gBAAuB,CAAC"}

package/packages/server/dist/services/snippetService.js

@@ -0,0 +1,371 @@
+/**
+ * Story 29.2: Snippet management service.
+ *
+ * Manages the three-scope snippet store consumed by `snippetResolver` for
+ * `%name%` chat-input expansion:
+ *
+ *   - project   → `<projectRoot>/.hammoc/snippets/<name>.md`         (mutable)
+ *   - user      → `~/.hammoc/snippets/<name>.md`                     (mutable)
+ *   - bundled   → `<serverDist>/snippets/<name>[.md]`                (read-only)
+ *
+ * Differences from the harness services (Epic 28):
+ *   - no YAML frontmatter — body is free-form markdown
+ *   - no plugin scope — `bundled` replaces it but is structurally simpler
+ *     (no manifest, no installed_plugins.json lookup)
+ *   - no watcher integration (Story 29.2 Phase 1) — `noteLocalWrite` is not
+ *     called because snippets are NOT in the harness watcher's subscription
+ *     tree (`fileWatcherService` only watches `.claude/`, never `.hammoc/`)
+ *
+ * STALE_WRITE / HARNESS_FILE_EXISTS contract mirrors `harnessService` so the
+ * client can reuse its existing conflict UX.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { HARNESS_ERRORS, } from '@hammoc/shared';
+import { getBundledSnippetsDir, getProjectSnippetsDir, getUserSnippetsDir, resolveSnippetPath, validateSnippetName, } from '../utils/snippetPaths.js';
+const MAX_FILE_SIZE = 102_400; // 100KB — matches snippetResolver
+const PREVIEW_MAX_LEN = 80;
+function throwMapped(code, message, extras) {
+    const err = new Error(message);
+    err.code = code;
+    if (extras)
+        Object.assign(err, extras);
+    throw err;
+}
+/**
+ * Read snippet content from a path, transparently handling both `<name>.md`
+ * and the legacy extension-less `<name>` form (snippetResolver back-compat).
+ * Returns `null` when neither path exists.
+ */
+async function readSnippetFile(primaryPath, legacyPath) {
+    for (const candidate of [primaryPath, legacyPath]) {
+        try {
+            const stat = await fs.stat(candidate);
+            if (!stat.isFile())
+                continue;
+            const content = await fs.readFile(candidate, 'utf-8');
+            return {
+                content,
+                mtime: stat.mtime.toISOString(),
+                size: stat.size,
+                effectivePath: candidate,
+            };
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT')
+                continue;
+            throw err;
+        }
+    }
+    return null;
+}
+/** Scan one root for `.md` and extension-less files, returning SnippetCard entries. */
+async function scanSnippetDir(dir, scope) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const cards = [];
+    // Use `for await` style so we don't touch fs serially in a way that blows up
+    // on large dirs — but with awaits inside a loop the cost is bounded by the
+    // number of files; the user-facing dir is tiny.
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const rawName = entry.name;
+        const name = rawName.endsWith('.md') ? rawName.slice(0, -3) : rawName;
+        // Skip files whose stem fails NAME_RE — e.g. README.md inside the bundled dir.
+        try {
+            validateSnippetName(name);
+        }
+        catch {
+            continue;
+        }
+        const abs = path.join(dir, rawName);
+        let stat;
+        try {
+            stat = await fs.stat(abs);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        let preview;
+        try {
+            const content = await fs.readFile(abs, 'utf-8');
+            const firstLine = content.split('\n').find((l) => l.trim().length > 0);
+            if (firstLine)
+                preview = firstLine.trim().slice(0, PREVIEW_MAX_LEN);
+        }
+        catch {
+            // unreadable — leave preview undefined
+        }
+        cards.push({
+            scope,
+            name,
+            preview,
+            mtime: stat.mtime.toISOString(),
+            size: stat.size,
+        });
+    }
+    return cards;
+}
+class SnippetService {
+    /**
+     * List snippets across all three scopes. Names are NOT deduplicated — the
+     * client renders one card per (scope, name) combination so users can see
+     * shadowing relationships explicitly. Resolution at runtime
+     * (snippetResolver) still applies project > user > bundled precedence.
+     */
+    async list(opts) {
+        const tasks = [
+            scanSnippetDir(getUserSnippetsDir(), 'user'),
+            scanSnippetDir(getBundledSnippetsDir(), 'bundled'),
+        ];
+        if (opts.projectSlug) {
+            tasks.push(getProjectSnippetsDir(opts.projectSlug).then((dir) => scanSnippetDir(dir, 'project')));
+        }
+        const results = await Promise.all(tasks);
+        const merged = results.flat();
+        merged.sort((a, b) => a.name.localeCompare(b.name) || a.scope.localeCompare(b.scope));
+        return { snippets: merged };
+    }
+    async read(ref) {
+        const { absolutePath, legacyAbsolutePath } = await resolveSnippetPath(ref);
+        const file = await readSnippetFile(absolutePath, legacyAbsolutePath);
+        if (!file) {
+            throwMapped(HARNESS_ERRORS.HARNESS_FILE_NOT_FOUND.code, 'snippet not found', {
+                absolutePath,
+            });
+        }
+        if (file.size > MAX_FILE_SIZE) {
+            // Truncate to stay consistent with snippetResolver's 100KB limit.
+            throwMapped(HARNESS_ERRORS.HARNESS_PARSE_ERROR.code, 'snippet exceeds 100KB limit');
+        }
+        return {
+            scope: ref.scope,
+            name: ref.name,
+            content: file.content,
+            mtime: file.mtime,
+            size: file.size,
+            absolutePath: file.effectivePath,
+        };
+    }
+    /** Create a new snippet — fails with HARNESS_FILE_EXISTS when a same-named file exists. */
+    async create(ref, body) {
+        if (ref.scope === 'bundled') {
+            throwMapped(HARNESS_ERRORS.HARNESS_BUNDLED_READONLY.code, 'bundled scope is read-only');
+        }
+        const { absolutePath, legacyAbsolutePath, resolvedRoot } = await resolveSnippetPath(ref);
+        // Reject creation if either form already exists.
+        for (const candidate of [absolutePath, legacyAbsolutePath]) {
+            try {
+                const stat = await fs.stat(candidate);
+                if (stat.isFile()) {
+                    throwMapped(HARNESS_ERRORS.HARNESS_FILE_EXISTS.code, 'snippet already exists');
+                }
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === 'ENOENT')
+                    continue;
+                if (code === HARNESS_ERRORS.HARNESS_FILE_EXISTS.code)
+                    throw err;
+                throw err;
+            }
+        }
+        await fs.mkdir(resolvedRoot, { recursive: true });
+        await writeSnippetFile(absolutePath, body.content);
+        const stat = await fs.stat(absolutePath);
+        return { success: true, size: stat.size, mtime: stat.mtime.toISOString() };
+    }
+    /** Update an existing snippet body with optional STALE_WRITE guard. */
+    async update(ref, body) {
+        if (ref.scope === 'bundled') {
+            throwMapped(HARNESS_ERRORS.HARNESS_BUNDLED_READONLY.code, 'bundled scope is read-only');
+        }
+        const { absolutePath, legacyAbsolutePath, resolvedRoot } = await resolveSnippetPath(ref);
+        // STALE_WRITE check — try `.md` first, fall back to legacy ext-less form
+        // because the existing file may still be in the legacy layout. If neither
+        // exists, treat the write as a fresh create (no guard).
+        let targetPath = absolutePath;
+        let existing;
+        try {
+            existing = await fs.stat(absolutePath);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            try {
+                existing = await fs.stat(legacyAbsolutePath);
+                targetPath = legacyAbsolutePath;
+            }
+            catch (err2) {
+                if (err2.code !== 'ENOENT')
+                    throw err2;
+                // Neither exists — caller should use create(); but to keep update()
+                // forgiving we proceed and let it be created at the canonical .md path.
+                existing = undefined;
+                targetPath = absolutePath;
+            }
+        }
+        if (body.expectedMtime !== undefined && existing) {
+            const currentMtime = existing.mtime.toISOString();
+            if (currentMtime !== body.expectedMtime) {
+                throwMapped(HARNESS_ERRORS.HARNESS_STALE_WRITE.code, 'snippet changed on disk', {
+                    currentMtime,
+                });
+            }
+        }
+        if (!existing) {
+            await fs.mkdir(resolvedRoot, { recursive: true });
+        }
+        await writeSnippetFile(targetPath, body.content);
+        const stat = await fs.stat(targetPath);
+        return { success: true, size: stat.size, mtime: stat.mtime.toISOString() };
+    }
+    async delete(ref, body) {
+        if (ref.scope === 'bundled') {
+            throwMapped(HARNESS_ERRORS.HARNESS_BUNDLED_READONLY.code, 'bundled scope is read-only');
+        }
+        const { absolutePath, legacyAbsolutePath } = await resolveSnippetPath(ref);
+        let targetPath = null;
+        let stat;
+        for (const candidate of [absolutePath, legacyAbsolutePath]) {
+            try {
+                stat = await fs.stat(candidate);
+                if (stat.isFile()) {
+                    targetPath = candidate;
+                    break;
+                }
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    continue;
+                throw err;
+            }
+        }
+        if (!targetPath || !stat) {
+            throwMapped(HARNESS_ERRORS.HARNESS_FILE_NOT_FOUND.code, 'snippet not found');
+        }
+        if (body.expectedMtime !== undefined && stat.mtime.toISOString() !== body.expectedMtime) {
+            throwMapped(HARNESS_ERRORS.HARNESS_STALE_WRITE.code, 'snippet changed on disk', {
+                currentMtime: stat.mtime.toISOString(),
+            });
+        }
+        await fs.unlink(targetPath);
+        return { success: true };
+    }
+    /**
+     * Copy a snippet across scopes.
+     *
+     *   project ↔ user      → bi-directional
+     *   bundled → project   → one-way clone
+     *   bundled → user      → one-way clone
+     *
+     * `bundled` is never a target. When the target exists the call resolves
+     * according to `onConflict` (default 'abort' → HARNESS_FILE_EXISTS).
+     */
+    async copy(req) {
+        if (req.targetScope !== 'project' && req.targetScope !== 'user') {
+            throwMapped(HARNESS_ERRORS.HARNESS_BUNDLED_READONLY.code, 'bundled cannot be a copy target');
+        }
+        if (req.sourceScope === 'project' && !req.sourceProjectSlug) {
+            throwMapped(HARNESS_ERRORS.HARNESS_ROOT_MISSING.code, 'sourceProjectSlug is required');
+        }
+        if (req.targetScope === 'project' && !req.targetProjectSlug) {
+            throwMapped(HARNESS_ERRORS.HARNESS_ROOT_MISSING.code, 'targetProjectSlug is required');
+        }
+        const sourceRef = {
+            scope: req.sourceScope,
+            projectSlug: req.sourceProjectSlug,
+            name: req.sourceName,
+        };
+        const sourceResolved = await resolveSnippetPath(sourceRef);
+        const sourceFile = await readSnippetFile(sourceResolved.absolutePath, sourceResolved.legacyAbsolutePath);
+        if (!sourceFile) {
+            throwMapped(HARNESS_ERRORS.HARNESS_FILE_NOT_FOUND.code, 'source snippet not found');
+        }
+        const targetName = req.targetName ?? req.sourceName;
+        validateSnippetName(targetName);
+        const targetRef = {
+            scope: req.targetScope,
+            projectSlug: req.targetProjectSlug,
+            name: targetName,
+        };
+        const targetResolved = await resolveSnippetPath(targetRef);
+        // Detect target conflict (either canonical or legacy form).
+        let targetExisting = false;
+        let targetExistingPath = '';
+        for (const candidate of [
+            targetResolved.absolutePath,
+            targetResolved.legacyAbsolutePath,
+        ]) {
+            try {
+                const stat = await fs.stat(candidate);
+                if (stat.isFile()) {
+                    targetExisting = true;
+                    targetExistingPath = candidate;
+                    break;
+                }
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    continue;
+                throw err;
+            }
+        }
+        const onConflict = req.onConflict ?? 'abort';
+        if (targetExisting) {
+            if (onConflict === 'abort') {
+                throwMapped(HARNESS_ERRORS.HARNESS_FILE_EXISTS.code, 'target snippet already exists');
+            }
+            if (onConflict === 'rename') {
+                // Rename mode requires a fresh targetName, which the caller is
+                // responsible for choosing. If the new name still collides, surface
+                // the same 409 — the dialog will re-prompt.
+                if (!req.targetName || req.targetName === req.sourceName) {
+                    throwMapped(HARNESS_ERRORS.HARNESS_FILE_EXISTS.code, 'rename requires a distinct targetName');
+                }
+            }
+            // overwrite → fall through; we'll write to the canonical .md path so
+            // the target is always normalized to `<name>.md` even if the existing
+            // form was legacy.
+        }
+        await fs.mkdir(targetResolved.resolvedRoot, { recursive: true });
+        await writeSnippetFile(targetResolved.absolutePath, sourceFile.content);
+        // If the existing file was at the legacy path, leave it in place per the
+        // story's "no automatic rename" policy (S4 in AC1.b). The client may end
+        // up with two files (legacy + new .md) — listSnippets will show only the
+        // canonical card because scanSnippetDir dedupes by stem name.
+        void targetExistingPath;
+        return {
+            success: true,
+            target: {
+                scope: req.targetScope,
+                name: targetName,
+                absolutePath: targetResolved.absolutePath,
+            },
+        };
+    }
+}
+/** Atomic-ish file write — `fs.writeFile` with utf-8 encoding. */
+async function writeSnippetFile(absolutePath, content) {
+    try {
+        await fs.writeFile(absolutePath, content, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EACCES') {
+            throwMapped(HARNESS_ERRORS.HARNESS_FORBIDDEN.code, 'permission denied');
+        }
+        throwMapped(HARNESS_ERRORS.HARNESS_WRITE_ERROR.code, 'failed to write snippet');
+    }
+}
+export const snippetService = new SnippetService();
+//# sourceMappingURL=snippetService.js.map

package/packages/server/dist/services/snippetService.js.map

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

package/packages/server/dist/services/utils/applyYamlFrontmatterPatch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Story 28.5: YAML frontmatter round-trip helper.
+ *
+ * Slash command files (`.claude/commands/**\/*.md`) are markdown documents with
+ * an optional `--- ... ---` YAML frontmatter block at the top. To preserve
+ * comments / key order / blank lines inside the frontmatter while leaving the
+ * markdown body byte-for-byte intact, we round-trip just the frontmatter slice
+ * via `yaml`(eemeli) `parseDocument`.
+ *
+ * Behaviour:
+ *   - File has no frontmatter + patch is empty (all keys absent) → return source
+ *     unchanged.
+ *   - File has no frontmatter + patch contains keys                → prepend a
+ *     fresh `--- ... ---` block.
+ *   - File has frontmatter + patch is empty                        → strip the
+ *     block entirely (matches AC3.a "all four fields absent ⇒ no frontmatter").
+ *   - File has frontmatter + patch sets keys                       → mutate keys
+ *     in place, preserving comments / order / blank lines for untouched keys.
+ *
+ * The body region (everything after the closing `---`) is taken from the source
+ * via raw substring slicing so byte-level equality holds — this is asserted by
+ * the unit tests with `result.slice(boundary) === source.slice(boundary)`.
+ */
+/**
+ * Apply key-level patches to the YAML frontmatter block of a markdown file.
+ * Body markdown is preserved byte-for-byte. Pass `undefined` to delete a key.
+ *
+ * - When the resulting frontmatter has no keys left, the entire `--- ... ---`
+ *   block (including the closing newline) is stripped.
+ * - When the source has no frontmatter and `newFrontmatter` carries at least
+ *   one defined value, a `--- ... ---` block is prepended with a single
+ *   trailing newline before the body.
+ *
+ * @throws HARNESS_PARSE_ERROR when the existing frontmatter is malformed YAML.
+ */
+export declare function applyYamlFrontmatterPatch(source: string, newFrontmatter: Record<string, unknown>): string;
+/**
+ * Strip the `--- ... ---` block (if any) and return the remaining body.
+ * Convenience helper — used by the service to surface the body separately
+ * from frontmatter on the read path.
+ */
+export declare function splitFrontmatterAndBody(source: string): {
+    frontmatterRaw: string | null;
+    body: string;
+};
+//# sourceMappingURL=applyYamlFrontmatterPatch.d.ts.map

package/packages/server/dist/services/utils/applyYamlFrontmatterPatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyYamlFrontmatterPatch.d.ts","sourceRoot":"","sources":["../../../src/services/utils/applyYamlFrontmatterPatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAuCH;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,MAAM,CAuDR;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG;IACvD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAIA"}

package/packages/server/dist/services/utils/applyYamlFrontmatterPatch.js

@@ -0,0 +1,125 @@
+/**
+ * Story 28.5: YAML frontmatter round-trip helper.
+ *
+ * Slash command files (`.claude/commands/**\/*.md`) are markdown documents with
+ * an optional `--- ... ---` YAML frontmatter block at the top. To preserve
+ * comments / key order / blank lines inside the frontmatter while leaving the
+ * markdown body byte-for-byte intact, we round-trip just the frontmatter slice
+ * via `yaml`(eemeli) `parseDocument`.
+ *
+ * Behaviour:
+ *   - File has no frontmatter + patch is empty (all keys absent) → return source
+ *     unchanged.
+ *   - File has no frontmatter + patch contains keys                → prepend a
+ *     fresh `--- ... ---` block.
+ *   - File has frontmatter + patch is empty                        → strip the
+ *     block entirely (matches AC3.a "all four fields absent ⇒ no frontmatter").
+ *   - File has frontmatter + patch sets keys                       → mutate keys
+ *     in place, preserving comments / order / blank lines for untouched keys.
+ *
+ * The body region (everything after the closing `---`) is taken from the source
+ * via raw substring slicing so byte-level equality holds — this is asserted by
+ * the unit tests with `result.slice(boundary) === source.slice(boundary)`.
+ */
+import { parseDocument } from 'yaml';
+import { HARNESS_ERRORS } from '@hammoc/shared';
+/** Match a leading `---\n...---\n?` frontmatter block. */
+const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n)?/;
+function findFrontmatter(source) {
+    const match = FRONTMATTER_RE.exec(source);
+    if (!match)
+        return null;
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    return { inner: match[1], bodyStart: match[0].length, eol };
+}
+function frontmatterIsEmpty(values) {
+    for (const v of Object.values(values)) {
+        if (v !== undefined)
+            return false;
+    }
+    return true;
+}
+function throwParseError(cause) {
+    const err = new Error(`failed to parse frontmatter: ${cause?.message ?? String(cause)}`);
+    err.code = HARNESS_ERRORS.HARNESS_PARSE_ERROR.code;
+    throw err;
+}
+/**
+ * Apply key-level patches to the YAML frontmatter block of a markdown file.
+ * Body markdown is preserved byte-for-byte. Pass `undefined` to delete a key.
+ *
+ * - When the resulting frontmatter has no keys left, the entire `--- ... ---`
+ *   block (including the closing newline) is stripped.
+ * - When the source has no frontmatter and `newFrontmatter` carries at least
+ *   one defined value, a `--- ... ---` block is prepended with a single
+ *   trailing newline before the body.
+ *
+ * @throws HARNESS_PARSE_ERROR when the existing frontmatter is malformed YAML.
+ */
+export function applyYamlFrontmatterPatch(source, newFrontmatter) {
+    const slice = findFrontmatter(source);
+    const allEmpty = frontmatterIsEmpty(newFrontmatter);
+    if (!slice) {
+        if (allEmpty)
+            return source;
+        const eol = source.includes('\r\n') ? '\r\n' : '\n';
+        let doc;
+        try {
+            doc = parseDocument('', { keepSourceTokens: true });
+        }
+        catch (cause) {
+            throwParseError(cause);
+        }
+        if (doc.contents == null) {
+            doc.contents = doc.createNode({});
+        }
+        for (const [key, value] of Object.entries(newFrontmatter)) {
+            if (value === undefined)
+                continue;
+            doc.setIn([key], value);
+        }
+        const yamlText = doc.toString().replace(/\r?\n$/, '');
+        return `---${eol}${yamlText}${eol}---${eol}${source}`;
+    }
+    let doc;
+    try {
+        doc = parseDocument(slice.inner, { keepSourceTokens: true });
+        if (doc.errors.length > 0) {
+            throw doc.errors[0];
+        }
+    }
+    catch (cause) {
+        throwParseError(cause);
+    }
+    if (doc.contents == null) {
+        doc.contents = doc.createNode({});
+    }
+    for (const [key, value] of Object.entries(newFrontmatter)) {
+        if (value === undefined) {
+            if (doc.hasIn([key]))
+                doc.deleteIn([key]);
+            continue;
+        }
+        doc.setIn([key], value);
+    }
+    // If the patched document is empty (no top-level keys left), strip the block.
+    const docContents = doc.contents;
+    const remainingKeys = docContents?.items?.length ?? 0;
+    if (remainingKeys === 0) {
+        return source.slice(slice.bodyStart);
+    }
+    const yamlText = doc.toString().replace(/\r?\n$/, '');
+    return `---${slice.eol}${yamlText}${slice.eol}---${slice.eol}${source.slice(slice.bodyStart)}`;
+}
+/**
+ * Strip the `--- ... ---` block (if any) and return the remaining body.
+ * Convenience helper — used by the service to surface the body separately
+ * from frontmatter on the read path.
+ */
+export function splitFrontmatterAndBody(source) {
+    const slice = findFrontmatter(source);
+    if (!slice)
+        return { frontmatterRaw: null, body: source };
+    return { frontmatterRaw: slice.inner, body: source.slice(slice.bodyStart) };
+}
+//# sourceMappingURL=applyYamlFrontmatterPatch.js.map

package/packages/server/dist/services/utils/applyYamlFrontmatterPatch.js.map

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

package/packages/server/dist/snippets/split-commit

@@ -0,0 +1,9 @@
+Review the current working tree with `git status` and `git diff` (both staged and unstaged). Group the changes into logically coherent units so that each commit represents a single concern (one feature, one fix, one refactor, etc.). For each group:
+
+1. Stage only the files (or hunks, via `git add -p`, when a single file mixes concerns) that belong to the group.
+2. Commit with a clear conventional-commit style message that explains *why* the change exists, not just *what* changed.
+3. Move on to the next group.
+
+Do not push. Do not amend existing commits. If the changes are already coherent as a single commit, say so and make one commit instead of forcing a split.
+
+When you finish, list the resulting commits (hash + subject line) as a summary.