hammoc 1.6.0 → 1.7.0

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

@@ -0,0 +1,91 @@
+/**
+ * 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 type { BrowseResponse, MkdirResponse, RenameResponse } from '@hammoc/shared';
+declare class SystemBrowseService {
+    /**
+     * Build a domain error whose `code` the controller maps to an HTTP status +
+     * i18n message (same idiom as fileSystemService: `(err).code = 'CODE'`).
+     */
+    private makeError;
+    /**
+     * 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).
+     */
+    private assertSafeAbsolutePath;
+    /**
+     * 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.)
+     */
+    private sanitizeEntryName;
+    /**
+     * 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.
+     */
+    private parentOf;
+    /**
+     * 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.
+     */
+    private hasChildDirectory;
+    /**
+     * 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
+     */
+    listDirectory(absolutePath: string): Promise<BrowseResponse>;
+    /**
+     * 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.
+     */
+    listDriveRoots(): Promise<BrowseResponse>;
+    /**
+     * 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).
+     */
+    makeDirectory(parentAbsolute: string, name: string): Promise<MkdirResponse>;
+    /**
+     * 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.
+     */
+    rename(absolute: string, newName: string): Promise<RenameResponse>;
+}
+export declare const systemBrowseService: SystemBrowseService;
+export {};
+//# sourceMappingURL=systemBrowseService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"systemBrowseService.d.ts","sourceRoot":"","sources":["../../src/services/systemBrowseService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAEV,cAAc,EACd,aAAa,EACb,cAAc,EACf,MAAM,gBAAgB,CAAC;AAmCxB,cAAM,mBAAmB;IACvB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAMjB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAyB9B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;;OAMG;YACW,iBAAiB;IAyB/B;;;;;;;OAOG;IACG,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAyDlE;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,cAAc,CAAC;IAuC/C;;;;OAIG;IACG,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA+BjF;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CA0CzE;AAED,eAAO,MAAM,mBAAmB,qBAA4B,CAAC"}

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

@@ -0,0 +1,24 @@
+/**
+ * Default workspace context template with system variables.
+ * Variables like {gitBranch} are resolved at runtime via resolveTemplateVariables().
+ */
+export declare const DEFAULT_WORKSPACE_TEMPLATE: string;
+/** Available template variables and their descriptions */
+export declare const TEMPLATE_VARIABLES: readonly [{
+    readonly name: "gitBranch";
+    readonly description: "Current git branch name";
+}, {
+    readonly name: "gitMainBranch";
+    readonly description: "Main branch name (main or master)";
+}, {
+    readonly name: "gitStatus";
+    readonly description: "git status --short output (truncated to 30 lines)";
+}, {
+    readonly name: "homeDir";
+    readonly description: "Absolute path to the user home directory";
+}];
+/**
+ * Resolve template variables like {gitBranch} using the project CWD.
+ */
+export declare function resolveTemplateVariables(template: string, cwd: string): string;
+//# sourceMappingURL=workspaceContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceContext.d.ts","sourceRoot":"","sources":["../../src/services/workspaceContext.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAqC3B,CAAC;AAEb,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAKrB,CAAC;AAEX;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CA2C9E"}

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

@@ -0,0 +1,109 @@
+/**
+ * Workspace Context — the Hammoc system-prompt augmentation shared by BOTH chat engines.
+ *
+ * SDK mode (`chatService`) appends `DEFAULT_WORKSPACE_TEMPLATE` to the `claude_code` system-prompt
+ * preset; CLI mode (`cliChatEngine`) reaches the SAME preset via the interactive `claude` binary and
+ * appends the identical resolved template through `--append-system-prompt`. This is the single source
+ * of truth for "what makes the agent Hammoc-aware" (identity, clickable-link convention, feature
+ * pointers, manual/internals locations).
+ *
+ * Extracted out of `chatService` on purpose: that module pulls in the Agent SDK, so anything that
+ * only needs the template (the CLI engine, the preferences/project routes that surface the default)
+ * would otherwise drag the SDK in transitively. This file is light — only `os` + `git` (execSync).
+ */
+import os from 'os';
+import { execSync } from 'child_process';
+/**
+ * Default workspace context template with system variables.
+ * Variables like {gitBranch} are resolved at runtime via resolveTemplateVariables().
+ */
+export const DEFAULT_WORKSPACE_TEMPLATE = [
+    '',
+    '# Hammoc Context',
+    '',
+    'You are running inside Hammoc, a web-based IDE for AI-driven development workflows. Hammoc is built on Claude Code with first-class BMAD-METHOD V4 support, fully responsive (the user may instruct from a phone with very short messages), and delegates implementation work to you while the user reviews via the UI.',
+    '',
+    '## Code References in Text',
+    'IMPORTANT: When referencing files or code locations, use markdown link syntax to make them clickable:',
+    '- For files: [filename.ts](src/filename.ts)',
+    '- For specific lines: [filename.ts:42](src/filename.ts#L42)',
+    '- For a range of lines: [filename.ts:42-51](src/filename.ts#L42-L51)',
+    '- For folders: [src/utils/](src/utils/)',
+    'Unless explicitly asked for by the user, DO NOT USE backticks ` or HTML tags like code for file references - always use markdown [text](link) format.',
+    "The URL links should be relative paths from the root of the user's workspace.",
+    '',
+    '## Hammoc-Specific Features the User May Invoke',
+    'When the user mentions any of these Hammoc concepts and you are unsure how the feature behaves, read the matching manual chapter (see Manual Reference below) before guessing:',
+    '- **Snippets** (`%name`) — reusable prompt templates with arguments. Files in <project-root>/.hammoc/snippets/ and {homeDir}/.hammoc/snippets/',
+    '- **Queue Runner** — batch script of prompts with `@`-prefixed commands (@new, @save, @load, @pause, @model, @delay, @pauseword, @loop/@end, @(/@), # comments)',
+    '- **Project Board** — Kanban with Bug/Improvement issues, severity Low/Medium/High/Critical, status workflow Open → Draft → Approved → In Progress → Blocked → Review → Done → Closed',
+    '- **BMAD-METHOD V4** — agile workflow with agents (SM, PM, Architect, Dev, QA, PO, etc.); .bmad-core directory holds the methodology files',
+    '- **Permission Modes** — Plan / Ask (default) / Auto / Bypass, per-project overridable',
+    '- **Sessions** — fork, rewind, summarize & continue, conversation branching',
+    '',
+    '## Manual Reference',
+    'The full Hammoc user manual is sharded by chapter and synced to:',
+    '  {homeDir}/.hammoc/docs/manual/',
+    'Always start by reading the index — it maps each chapter to its trigger keywords and tags chapters as [agent] (worth reading) or [user-setup] (skip):',
+    '  {homeDir}/.hammoc/docs/manual/INDEX.md',
+    'Read only the chapters you actually need. Do not load the full manual at once. The Read tool does not expand `~` so always use the absolute path above.',
+    '',
+    '## Internals Reference',
+    'Hammoc internal mechanisms that the user does not need to see but the agent may need to read or correlate (e.g. on-disk location of attached images) live separately at:',
+    '  {homeDir}/.hammoc/docs/internals/',
+    'Index:',
+    '  {homeDir}/.hammoc/docs/internals/INDEX.md',
+    'Read individual files only when the user request requires the underlying mechanism. Do not pre-load.',
+].join('\n');
+/** Available template variables and their descriptions */
+export const TEMPLATE_VARIABLES = [
+    { name: 'gitBranch', description: 'Current git branch name' },
+    { name: 'gitMainBranch', description: 'Main branch name (main or master)' },
+    { name: 'gitStatus', description: 'git status --short output (truncated to 30 lines)' },
+    { name: 'homeDir', description: 'Absolute path to the user home directory' },
+];
+/**
+ * Resolve template variables like {gitBranch} using the project CWD.
+ */
+export function resolveTemplateVariables(template, cwd) {
+    const vars = {};
+    // Home directory is OS-level and always resolvable, independent of git state.
+    // The agent needs the absolute path to read ~/.hammoc/docs/manual/INDEX.md
+    // via Read/Edit tools, which do not perform shell-style ~ expansion.
+    vars.homeDir = os.homedir();
+    try {
+        const stdio = ['pipe', 'pipe', 'pipe'];
+        const execOpts = { cwd, encoding: 'utf-8', timeout: 3000, stdio };
+        vars.gitBranch = execSync('git rev-parse --abbrev-ref HEAD', execOpts).toString().trim();
+        let mainBranch = 'main';
+        try {
+            execSync('git rev-parse --verify refs/heads/main', execOpts);
+            mainBranch = 'main';
+        }
+        catch {
+            try {
+                execSync('git rev-parse --verify refs/heads/master', execOpts);
+                mainBranch = 'master';
+            }
+            catch {
+                // fallback
+            }
+        }
+        vars.gitMainBranch = mainBranch;
+        const gitStatus = execSync('git status --short', { ...execOpts, timeout: 5000 }).toString().trim();
+        const statusLines = gitStatus ? gitStatus.split('\n') : [];
+        vars.gitStatus = statusLines.length > 30
+            ? [...statusLines.slice(0, 30), `... and ${statusLines.length - 30} more files`].join('\n')
+            : (gitStatus || '(clean)');
+    }
+    catch {
+        // Not a git repo or git not available
+        vars.gitBranch = '(unknown)';
+        vars.gitMainBranch = 'main';
+        vars.gitStatus = '(not a git repo)';
+    }
+    return template.replace(/\{(\w+)\}/g, (match, varName) => {
+        return vars[varName] ?? match;
+    });
+}
+//# sourceMappingURL=workspaceContext.js.map

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

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

package/packages/server/dist/snippets/qa-review

@@ -2,6 +2,8 @@
 ---
 *review {arg1}
 
+CRITICAL — the gate YAML must parse. Write every free-text field (status_reason, finding, fix_recommendation, notes, etc.) as a block scalar (e.g. `status_reason: |`) on its own indented lines, NOT as a quoted string. Free text here routinely contains backticks, colons, apostrophes and SQL/code snippets, and quoting them has repeatedly produced invalid YAML that silently breaks Hammoc's gate detection. Block scalars need no escaping. After writing the gate file, re-read it and confirm it loads as valid YAML (e.g. run a quick parse); if it fails, fix and rewrite before finishing.
+
 When you write the quality gate, if the gate decision is CONCERNS or FAIL, also record it in the story so Hammoc tracks that a fix is pending. Append this exact line inside the story's QA Results section, replacing the placeholder with the gate's `updated:` value you just wrote:
 <!-- hammoc:qa-fix gate="<paste the gate's updated value>" applied="false" -->
 For a PASS or WAIVED gate, do not add this marker.