hammoc 1.4.0 → 1.6.0

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/tokenCountService.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Story 31.3 (Task A.3 / A.5): token attribution + exact count_tokens proxy.
+ *
+ * Two responsibilities, sharing one text-resolution path so the "exact count"
+ * input and the "approximation" input are always the same bytes (N-1):
+ *
+ *   1. listTokenAttribution(projectSlug) — enumerate the measured harness
+ *      elements (project/global CLAUDE.md · each skill's SKILL.md · the
+ *      Hammoc-managed context-builder injection) and report UTF-8 byte size +
+ *      `approxTokens = ceil(bytes/4)` + a sha256 content hash (AC-B1 / AC-B2).
+ *
+ *   2. exactCount(projectSlug, req) — proxy the official `count_tokens` via the
+ *      already-installed `@anthropic-ai/sdk` `messages.countTokens` (spike #2,
+ *      §15 — no new dependency), keyed by a server-recomputed content hash
+ *      (N-B: the request hash is only an optimistic hint). Failures are
+ *      non-blocking (`failed: true`) so the client keeps the approximation
+ *      (AC-B3.c).
+ *
+ * Enumeration REUSES existing controllers/services (claudeMdService,
+ * harnessSkillService, contextBuilderService) — no new file scanner (S-2). The
+ * context-builder injection is estimated from the Story 31.2 manifest WITHOUT
+ * executing the hook (dynamic variable / command values are placeholders).
+ *
+ * Per spike #1 (§14) the SERVER approximation tier is byte `size/4` only — the
+ * `@anthropic-ai/tokenizer` tier was NOT adopted (Task A.4 skipped).
+ */
+import { type TokenAttributionItem, type ExactTokenCountRequest, type ExactTokenCountResponse } from '@hammoc/shared';
+/** ceil(bytes / 4) — the size-based heuristic (§14). */
+export declare function approxTokensFromBytes(bytes: number): number;
+declare class TokenCountService {
+    /** sha256(text) → token count. In-memory; persisted best-effort to disk. */
+    private cache;
+    private cacheLoaded;
+    private cacheFilePath;
+    private loadCache;
+    private persistCache;
+    /**
+     * Enumerate measured harness elements (AC-B1.a). Missing CLAUDE.md files and a
+     * disabled/empty context builder are omitted (they contribute no tokens).
+     */
+    listTokenAttribution(projectSlug: string): Promise<TokenAttributionItem[]>;
+    /**
+     * Exact count for one element (AC-B3). The text is re-resolved server-side and
+     * its sha256 is the AUTHORITATIVE cache key (N-B) — the request `contentHash`
+     * is only an optimistic hint. count_tokens failures return `failed: true`.
+     */
+    exactCount(projectSlug: string, req: ExactTokenCountRequest): Promise<ExactTokenCountResponse>;
+    private makeItem;
+    /** Resolve the text used for BOTH attribution and exact-count (N-1). */
+    private resolveElementText;
+    private readClaudeMd;
+    /**
+     * Read a skill's SKILL.md, validating `elementPath` against the enumerated
+     * skills so an arbitrary client path can never be read (the path must be one
+     * the server itself vouched for in listTokenAttribution).
+     */
+    private readSkillTextByPath;
+    /**
+     * Assemble the context-builder `additionalContext` text WITHOUT executing the
+     * hook (N-1). Reference files are read (their content dominates the size);
+     * dynamic variables / acknowledged commands contribute only their block
+     * headers with a `(dynamic)` placeholder. Mirrors the block format of
+     * `contextBuilderScriptTemplate` for the statically-knowable parts. Returns ''
+     * when the builder is disabled or empty.
+     */
+    private assembleContextBuilderText;
+    private callCountTokens;
+}
+export declare const tokenCountService: TokenCountService;
+export {};
+//# sourceMappingURL=tokenCountService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokenCountService.d.ts","sourceRoot":"","sources":["../../src/services/tokenCountService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,OAAO,EACL,KAAK,oBAAoB,EAEzB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,gBAAgB,CAAC;AAwBxB,wDAAwD;AACxD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AA6BD,cAAM,iBAAiB;IACrB,4EAA4E;IAC5E,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO,CAAC,aAAa;YAIP,SAAS;YAcT,YAAY;IAU1B;;;OAGG;IACG,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAkChF;;;;OAIG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAqBpG,OAAO,CAAC,QAAQ;IAiBhB,wEAAwE;YAC1D,kBAAkB;YAqBlB,YAAY;IAW1B;;;;OAIG;YACW,mBAAmB;IAkBjC;;;;;;;OAOG;YACW,0BAA0B;YAwC1B,eAAe;CAiB9B;AAED,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}