hammoc 1.5.0 → 1.7.0

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

@@ -0,0 +1,372 @@
+/**
+ * System Browse Service
+ * Directory-only browsing across the whole host filesystem (Epic 34, Story 34.1).
+ *
+ * KEY DIFFERENCE from fileSystemService: there is NO project boundary. This API
+ * runs *before* a project is registered, so it accepts arbitrary ABSOLUTE paths
+ * (drive roots through any directory). It therefore does NOT use
+ * validateProjectPath / validateReadPath. Instead it carries its own guard
+ * (assertSafeAbsolutePath) that blocks null bytes / UNC-device paths and enforces
+ * absoluteness. The write surface is folder create/rename ONLY — there is no
+ * delete method (destructive actions removed from the surface entirely).
+ *
+ * The guard / realpath / EACCES-skip / errno-mapping idioms are borrowed 1:1
+ * from fileSystemService and pathGuard; only the boundary model differs.
+ * [Source: docs/prd/epic-34-directory-browser.md#Story 34.1;
+ *          packages/server/src/services/fileSystemService.ts:162-176, 266-335, 765;
+ *          packages/server/src/middleware/pathGuard.ts:34-58]
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+/**
+ * Windows reserved device names (case-insensitive) — cannot be used as a folder
+ * name on Windows even with an extension (e.g. CON.txt). Rejected everywhere for
+ * cross-platform consistency.
+ */
+const WINDOWS_RESERVED_NAMES = new Set([
+    'CON', 'PRN', 'AUX', 'NUL',
+    'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+    'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+]);
+/** Printable characters not allowed in a folder name (Windows-strict, safe for POSIX). */
+const RESERVED_PRINTABLE_CHARS = new Set(['<', '>', ':', '"', '/', '\\', '|', '?', '*']);
+/**
+ * True if a name contains a reserved printable char OR any control character
+ * (0x00–0x1F). Char-code scan avoids a control-char regex literal entirely.
+ */
+function hasReservedChar(name) {
+    for (let i = 0; i < name.length; i++) {
+        const ch = name[i];
+        if (RESERVED_PRINTABLE_CHARS.has(ch))
+            return true;
+        if (name.charCodeAt(i) < 0x20)
+            return true; // control characters
+    }
+    return false;
+}
+/** OS errno codes that mean "write refused" → mapped to PERMISSION_DENIED (AC9). */
+function isWriteDeniedErrno(error) {
+    const code = error.code;
+    return code === 'EACCES' || code === 'EPERM' || code === 'EROFS';
+}
+class SystemBrowseService {
+    /**
+     * Build a domain error whose `code` the controller maps to an HTTP status +
+     * i18n message (same idiom as fileSystemService: `(err).code = 'CODE'`).
+     */
+    makeError(code, message) {
+        const err = new Error(message);
+        err.code = code;
+        return err;
+    }
+    /**
+     * Guard an incoming absolute path. Blocks null bytes and UNC/device paths,
+     * enforces absoluteness, and normalizes via path.resolve. Throws INVALID_PATH.
+     * Mirrors the null-byte / UNC checks from pathGuard, minus the project-root
+     * containment (this API has no project boundary).
+     */
+    assertSafeAbsolutePath(input) {
+        if (typeof input !== 'string' || input.length === 0) {
+            throw this.makeError('INVALID_PATH', 'Path is required');
+        }
+        // Null byte
+        if (input.includes('\0')) {
+            throw this.makeError('INVALID_PATH', 'Invalid path: null byte detected');
+        }
+        // UNC / device paths (\\server\share, //server, \\?\...) — block network/device access
+        if (input.startsWith('\\\\') || input.startsWith('//')) {
+            throw this.makeError('INVALID_PATH', 'Invalid path: UNC paths are not allowed');
+        }
+        // Must be absolute (relative paths are meaningless without a project root)
+        if (!path.isAbsolute(input)) {
+            throw this.makeError('INVALID_PATH', 'Invalid path: must be absolute');
+        }
+        const resolved = path.resolve(input);
+        // Double-check the resolved form isn't UNC (e.g. mixed-separator input)
+        const normalizedForUNC = resolved.replace(/\//g, '\\');
+        if (normalizedForUNC.startsWith('\\\\')) {
+            throw this.makeError('INVALID_PATH', 'Invalid path: UNC paths are not allowed');
+        }
+        return resolved;
+    }
+    /**
+     * Validate and normalize a single folder name (for mkdir/rename).
+     * Strips directory components via basename (traversal guard), then rejects
+     * empty / dot names, reserved characters, and Windows reserved device names.
+     * If basename(name) !== name the input contained a path separator → traversal
+     * attempt → INVALID_NAME. (fileSystemService:765 basename idiom.)
+     */
+    sanitizeEntryName(name) {
+        if (typeof name !== 'string') {
+            throw this.makeError('INVALID_NAME', 'Name is required');
+        }
+        const base = path.basename(name);
+        // Any directory component (a/b, ../x) makes basename differ from the input.
+        if (base !== name) {
+            throw this.makeError('INVALID_NAME', 'Name must not contain path separators');
+        }
+        if (base === '' || base === '.' || base === '..') {
+            throw this.makeError('INVALID_NAME', 'Invalid name');
+        }
+        if (hasReservedChar(base)) {
+            throw this.makeError('INVALID_NAME', 'Name contains reserved characters');
+        }
+        // Reserved device name check uses the stem before the first dot (CON, CON.txt).
+        const stem = base.split('.')[0].toUpperCase();
+        if (WINDOWS_RESERVED_NAMES.has(stem)) {
+            throw this.makeError('INVALID_NAME', 'Name is a reserved device name');
+        }
+        return base;
+    }
+    /**
+     * Parent path for breadcrumb / up navigation. At a filesystem root (C:\, /)
+     * path.dirname returns the same path → return null so the client maps it to
+     * the "My PC" drive-roots view.
+     */
+    parentOf(abs) {
+        const parent = path.dirname(abs);
+        return parent === abs ? null : parent;
+    }
+    /**
+     * Whether a directory has at least one child directory (tree-chevron signal).
+     * depth-1 guarded readdir, short-circuits on the first directory found. There
+     * is NO recursion anywhere in this service, so symlink cycles can never blow
+     * the stack — a stronger guarantee than searchFiles' visited-set, achieved
+     * structurally. EACCES/EPERM (or any read failure) → false.
+     */
+    async hasChildDirectory(absDir) {
+        let dirents;
+        try {
+            dirents = await fs.readdir(absDir, { withFileTypes: true });
+        }
+        catch {
+            // EACCES/EPERM/ENOENT/etc. — treat as "no expandable children"
+            return false;
+        }
+        for (const dirent of dirents) {
+            try {
+                if (dirent.isDirectory())
+                    return true;
+                if (dirent.isSymbolicLink()) {
+                    // readdir() reports the link itself; resolve to see if it targets a dir.
+                    const target = await fs.realpath(path.join(absDir, dirent.name));
+                    const st = await fs.stat(target);
+                    if (st.isDirectory())
+                        return true;
+                }
+            }
+            catch {
+                // broken symlink / unreadable entry — skip
+                continue;
+            }
+        }
+        return false;
+    }
+    /**
+     * List the child DIRECTORIES of an absolute path (files excluded, AC1).
+     * - ENOENT → NOT_FOUND, non-directory → NOT_A_DIRECTORY
+     * - per-entry try/catch: EACCES/EPERM and broken symlinks are skipped so the
+     *   listing returns a partial result instead of failing (AC4)
+     * - symlinks are resolved via realpath and evaluated as directory-or-not (AC3);
+     *   no recursion means cycles cannot cause infinite descent
+     */
+    async listDirectory(absolutePath) {
+        const abs = this.assertSafeAbsolutePath(absolutePath);
+        let stat;
+        try {
+            stat = await fs.stat(abs);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT')
+                throw this.makeError('NOT_FOUND', 'Path not found');
+            if (isWriteDeniedErrno(error))
+                throw this.makeError('PERMISSION_DENIED', 'Permission denied');
+            throw this.makeError('BROWSE_ERROR', 'Browse error');
+        }
+        if (!stat.isDirectory()) {
+            throw this.makeError('NOT_A_DIRECTORY', 'Path is not a directory');
+        }
+        let dirents;
+        try {
+            dirents = await fs.readdir(abs, { withFileTypes: true });
+        }
+        catch (error) {
+            // The whole listing failed (not a per-entry skip) → surface as a coherent code.
+            if (isWriteDeniedErrno(error))
+                throw this.makeError('PERMISSION_DENIED', 'Permission denied');
+            throw this.makeError('BROWSE_ERROR', 'Browse error');
+        }
+        const entries = [];
+        for (const dirent of dirents) {
+            try {
+                const entryPath = path.join(abs, dirent.name);
+                let isDir = dirent.isDirectory();
+                if (!isDir && dirent.isSymbolicLink()) {
+                    // Broken symlink → realpath throws → caught below → skipped.
+                    const target = await fs.realpath(entryPath);
+                    const st = await fs.stat(target);
+                    isDir = st.isDirectory();
+                }
+                if (!isDir)
+                    continue; // files excluded (AC1)
+                const hasChildren = await this.hasChildDirectory(entryPath);
+                entries.push({ name: dirent.name, path: entryPath, hasChildren });
+            }
+            catch {
+                // EACCES/EPERM/broken symlink → skip (partial result, AC4/AC3)
+                continue;
+            }
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+        return {
+            path: abs,
+            parent: this.parentOf(abs),
+            home: os.homedir(),
+            isDriveRoots: false,
+            entries,
+        };
+    }
+    /**
+     * List drive roots ("My PC" view, AC2).
+     * Windows: probe drive letters A–Z with fs.access — NO child_process (wmic is
+     *   deprecated on newer Windows; PowerShell spawns are slow / shell-dependent /
+     *   test-fragile). Drives that exist but are inaccessible (empty optical drive,
+     *   locked BitLocker volume) make access() throw and are naturally omitted —
+     *   this is the INTENDED meaning of AC2's "available drives", not a defect.
+     * POSIX: root "/" is always present; standard mount-point parents
+     *   (/Volumes, /mnt, /media) are added best-effort only when they exist.
+     */
+    async listDriveRoots() {
+        const entries = [];
+        if (process.platform === 'win32') {
+            for (let i = 65; i <= 90; i++) { // 'A'..'Z'
+                const letter = String.fromCharCode(i);
+                const root = `${letter}:\\`;
+                try {
+                    await fs.access(root);
+                    // Drives are assumed expandable (avoids a probe of every drive's contents).
+                    entries.push({ name: `${letter}:`, path: root, hasChildren: true });
+                }
+                catch {
+                    // Non-existent OR inaccessible drive — intentionally omitted (see doc above).
+                    continue;
+                }
+            }
+        }
+        else {
+            entries.push({ name: '/', path: '/', hasChildren: true });
+            for (const mount of ['/Volumes', '/mnt', '/media']) {
+                try {
+                    const st = await fs.stat(mount);
+                    if (st.isDirectory()) {
+                        entries.push({ name: mount, path: mount, hasChildren: true });
+                    }
+                }
+                catch {
+                    continue; // best-effort: absent mount parents are skipped
+                }
+            }
+        }
+        return {
+            path: null,
+            parent: null,
+            home: os.homedir(),
+            isDriveRoots: true,
+            entries,
+        };
+    }
+    /**
+     * Create a new folder under an absolute parent directory (AC5).
+     * EEXIST → ALREADY_EXISTS (409); EACCES/EPERM/EROFS → PERMISSION_DENIED (403,
+     * AC9 — OS-protected areas are refused safely, never a crash/500).
+     */
+    async makeDirectory(parentAbsolute, name) {
+        const parent = this.assertSafeAbsolutePath(parentAbsolute);
+        const safe = this.sanitizeEntryName(name);
+        let parentStat;
+        try {
+            parentStat = await fs.stat(parent);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw this.makeError('NOT_FOUND', 'Parent directory not found');
+            }
+            if (isWriteDeniedErrno(error))
+                throw this.makeError('PERMISSION_DENIED', 'Permission denied');
+            throw this.makeError('BROWSE_ERROR', 'Browse error');
+        }
+        if (!parentStat.isDirectory()) {
+            throw this.makeError('NOT_A_DIRECTORY', 'Parent path is not a directory');
+        }
+        const target = path.join(parent, safe);
+        try {
+            await fs.mkdir(target);
+            return { success: true, path: target };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'EEXIST')
+                throw this.makeError('ALREADY_EXISTS', 'Directory already exists');
+            if (code === 'ENOENT')
+                throw this.makeError('NOT_FOUND', 'Parent directory not found');
+            if (isWriteDeniedErrno(error))
+                throw this.makeError('PERMISSION_DENIED', 'Permission denied');
+            throw this.makeError('BROWSE_ERROR', 'Browse error');
+        }
+    }
+    /**
+     * Rename an entry within its SAME parent directory (AC6).
+     * Target-exists → ALREADY_EXISTS (409); EACCES/EPERM/EROFS → PERMISSION_DENIED
+     * (AC9). The new name is sanitized and joined to dirname(source), so a rename
+     * can never move an entry into another directory.
+     */
+    async rename(absolute, newName) {
+        const src = this.assertSafeAbsolutePath(absolute);
+        const safe = this.sanitizeEntryName(newName);
+        try {
+            await fs.stat(src);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw this.makeError('NOT_FOUND', 'Source not found');
+            }
+            if (isWriteDeniedErrno(error))
+                throw this.makeError('PERMISSION_DENIED', 'Permission denied');
+            throw this.makeError('BROWSE_ERROR', 'Browse error');
+        }
+        const target = path.join(path.dirname(src), safe);
+        // Target must not already exist (same-parent rename, AC6).
+        try {
+            await fs.stat(target);
+            throw this.makeError('ALREADY_EXISTS', 'Target already exists');
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ALREADY_EXISTS')
+                throw error;
+            if (code !== 'ENOENT') {
+                if (isWriteDeniedErrno(error))
+                    throw this.makeError('PERMISSION_DENIED', 'Permission denied');
+                throw this.makeError('BROWSE_ERROR', 'Browse error');
+            }
+            // ENOENT — target is free, proceed.
+        }
+        try {
+            await fs.rename(src, target);
+            return { success: true, oldPath: src, newPath: target };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'EEXIST' || code === 'ENOTEMPTY') {
+                throw this.makeError('ALREADY_EXISTS', 'Target already exists');
+            }
+            if (isWriteDeniedErrno(error))
+                throw this.makeError('PERMISSION_DENIED', 'Permission denied');
+            throw this.makeError('BROWSE_ERROR', 'Browse error');
+        }
+    }
+}
+export const systemBrowseService = new SystemBrowseService();
+//# sourceMappingURL=systemBrowseService.js.map

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

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