hammoc 1.5.0 → 1.7.0

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

@@ -0,0 +1,313 @@
+/**
+ * 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 fs from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import Anthropic from '@anthropic-ai/sdk';
+import { createLogger } from '../utils/logger.js';
+import { claudeMdService } from './claudeMdService.js';
+import { harnessSkillService } from './harnessSkillService.js';
+import { contextBuilderService } from './contextBuilderService.js';
+import { projectService } from './projectService.js';
+const log = createLogger('tokenCountService');
+/**
+ * Model passed to count_tokens. The count is tokenizer-family stable across
+ * Claude 4.x, so any current model works; overridable via env in case the
+ * default is later deprecated. spike #2 verified the call live.
+ */
+const COUNT_TOKENS_MODEL = process.env.OBSERVABILITY_COUNT_TOKENS_MODEL || 'claude-sonnet-4-6';
+function sha256(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+function utf8Bytes(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+/** ceil(bytes / 4) — the size-based heuristic (§14). */
+export function approxTokensFromBytes(bytes) {
+    return Math.ceil(Math.max(0, bytes) / 4);
+}
+function samePath(a, b) {
+    const na = path.normalize(a);
+    const nb = path.normalize(b);
+    return process.platform === 'win32' ? na.toLowerCase() === nb.toLowerCase() : na === nb;
+}
+/**
+ * Construct an Anthropic client for count_tokens (spike #2). Priority:
+ * `ANTHROPIC_API_KEY` → the Claude Code OAuth access token from
+ * `~/.claude/.credentials.json` (verified live). Returns null when neither is
+ * available — the caller degrades gracefully.
+ */
+function getAnthropicClient() {
+    if (process.env.ANTHROPIC_API_KEY)
+        return new Anthropic();
+    try {
+        const credPath = path.join(os.homedir(), '.claude', '.credentials.json');
+        const cred = JSON.parse(readFileSync(credPath, 'utf8'));
+        const token = cred?.claudeAiOauth?.accessToken;
+        if (token)
+            return new Anthropic({ authToken: token });
+    }
+    catch {
+        // no credentials — fall through.
+    }
+    return null;
+}
+class TokenCountService {
+    /** sha256(text) → token count. In-memory; persisted best-effort to disk. */
+    cache = new Map();
+    cacheLoaded = false;
+    cacheFilePath() {
+        return path.join(os.homedir(), '.hammoc', 'observability', 'token-count-cache.json');
+    }
+    async loadCache() {
+        if (this.cacheLoaded)
+            return;
+        this.cacheLoaded = true;
+        try {
+            const text = await fs.readFile(this.cacheFilePath(), 'utf8');
+            const obj = JSON.parse(text);
+            for (const [k, v] of Object.entries(obj)) {
+                if (typeof v === 'number')
+                    this.cache.set(k, v);
+            }
+        }
+        catch {
+            // missing/corrupt — start empty.
+        }
+    }
+    async persistCache() {
+        try {
+            const file = this.cacheFilePath();
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            await fs.writeFile(file, JSON.stringify(Object.fromEntries(this.cache)), 'utf8');
+        }
+        catch (err) {
+            log.warn(`token cache persist failed: ${err.message}`);
+        }
+    }
+    /**
+     * Enumerate measured harness elements (AC-B1.a). Missing CLAUDE.md files and a
+     * disabled/empty context builder are omitted (they contribute no tokens).
+     */
+    async listTokenAttribution(projectSlug) {
+        const items = [];
+        // project / global CLAUDE.md
+        const projectMd = await this.readClaudeMd({ scope: 'project', projectSlug });
+        if (projectMd)
+            items.push(this.makeItem('claudeMd-project', 'CLAUDE.md (project)', projectMd.text, projectMd.path));
+        const globalMd = await this.readClaudeMd({ scope: 'user' });
+        if (globalMd)
+            items.push(this.makeItem('claudeMd-global', 'CLAUDE.md (global)', globalMd.text, globalMd.path));
+        // each skill's SKILL.md (active source only)
+        try {
+            const { cards } = await harnessSkillService.listCards(projectSlug);
+            for (const card of cards) {
+                const root = card.sources[0]?.absoluteRoot;
+                if (!root)
+                    continue;
+                const skillMd = path.join(root, 'SKILL.md');
+                try {
+                    const text = await fs.readFile(skillMd, 'utf8');
+                    items.push(this.makeItem('skill', `skill: ${card.name}`, text, skillMd));
+                }
+                catch {
+                    // SKILL.md unreadable — skip this card.
+                }
+            }
+        }
+        catch (err) {
+            log.warn(`skill enumeration failed: ${err.message}`);
+        }
+        // Hammoc-managed context builder injection (manifest-assembled, no execution)
+        const cbText = await this.assembleContextBuilderText(projectSlug);
+        if (cbText)
+            items.push(this.makeItem('contextBuilder', 'Context builder injection', cbText));
+        return items;
+    }
+    /**
+     * 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`.
+     */
+    async exactCount(projectSlug, req) {
+        const text = await this.resolveElementText(projectSlug, req.kind, req.path);
+        if (text == null)
+            return { tokens: 0, cached: false, failed: true };
+        const key = sha256(text);
+        await this.loadCache();
+        const hit = this.cache.get(key);
+        if (hit !== undefined)
+            return { tokens: hit, cached: true };
+        const tokens = await this.callCountTokens(text);
+        if (tokens == null)
+            return { tokens: 0, cached: false, failed: true };
+        this.cache.set(key, tokens);
+        void this.persistCache();
+        return { tokens, cached: false };
+    }
+    // -------------------------------------------------------------------------
+    // internals
+    // -------------------------------------------------------------------------
+    makeItem(kind, label, text, filePath) {
+        const bytes = utf8Bytes(text);
+        return {
+            kind,
+            label,
+            ...(filePath ? { path: filePath } : {}),
+            bytes,
+            approxTokens: approxTokensFromBytes(bytes),
+            contentHash: sha256(text),
+        };
+    }
+    /** Resolve the text used for BOTH attribution and exact-count (N-1). */
+    async resolveElementText(projectSlug, kind, elementPath) {
+        switch (kind) {
+            case 'claudeMd-project':
+                return (await this.readClaudeMd({ scope: 'project', projectSlug }))?.text ?? null;
+            case 'claudeMd-global':
+                return (await this.readClaudeMd({ scope: 'user' }))?.text ?? null;
+            case 'contextBuilder': {
+                const t = await this.assembleContextBuilderText(projectSlug);
+                return t || null;
+            }
+            case 'skill':
+                return this.readSkillTextByPath(projectSlug, elementPath);
+            default:
+                return null;
+        }
+    }
+    async readClaudeMd(ref) {
+        try {
+            const res = await claudeMdService.read(ref);
+            return { text: res.content ?? '', path: res.absolutePath ?? 'CLAUDE.md' };
+        }
+        catch {
+            return null; // missing / not-a-file → omit.
+        }
+    }
+    /**
+     * 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).
+     */
+    async readSkillTextByPath(projectSlug, elementPath) {
+        if (!elementPath)
+            return null;
+        try {
+            const { cards } = await harnessSkillService.listCards(projectSlug);
+            for (const card of cards) {
+                const root = card.sources[0]?.absoluteRoot;
+                if (!root)
+                    continue;
+                const skillMd = path.join(root, 'SKILL.md');
+                if (samePath(skillMd, elementPath)) {
+                    return await fs.readFile(skillMd, 'utf8');
+                }
+            }
+        }
+        catch {
+            // fall through.
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    async assembleContextBuilderText(projectSlug) {
+        let manifest;
+        try {
+            ({ manifest } = await contextBuilderService.readManifest(projectSlug));
+        }
+        catch {
+            return '';
+        }
+        if (!manifest.enabled)
+            return '';
+        let projectRoot;
+        try {
+            projectRoot = await projectService.resolveOriginalPath(projectSlug);
+        }
+        catch {
+            return '';
+        }
+        const blocks = [];
+        for (const rel of manifest.files) {
+            const abs = path.resolve(projectRoot, rel);
+            try {
+                const content = await fs.readFile(abs, 'utf8');
+                blocks.push(`## Reference file: ${rel}\n\n${content}`);
+            }
+            catch {
+                blocks.push(`## Reference file: ${rel}\n\n(파일을 찾을 수 없음: ${rel})`);
+            }
+        }
+        // Dynamic variable headers (values are computed at hook runtime — placeholder here).
+        if (manifest.variables.gitBranch)
+            blocks.push('## Current git branch\n\n(dynamic)');
+        if (manifest.variables.recentCommits) {
+            blocks.push(`## Recent ${manifest.recentCommitsCount ?? 5} commit(s)\n\n(dynamic)`);
+        }
+        if (manifest.variables.uncommittedCount)
+            blocks.push('## Uncommitted file count\n\n(dynamic)');
+        if (manifest.variables.today)
+            blocks.push('## Today\n\n(dynamic)');
+        if (manifest.variables.activeBmadStory)
+            blocks.push('## Active BMad story\n\n(dynamic)');
+        for (const cc of manifest.customCommands) {
+            if (cc.acknowledged)
+                blocks.push(`## Command: ${cc.command}\n\n(dynamic)`);
+        }
+        return blocks.join('\n\n');
+    }
+    async callCountTokens(text) {
+        const client = getAnthropicClient();
+        if (!client) {
+            log.warn('count_tokens unavailable — no ANTHROPIC_API_KEY and no OAuth credentials');
+            return null;
+        }
+        try {
+            const res = await client.messages.countTokens({
+                model: COUNT_TOKENS_MODEL,
+                messages: [{ role: 'user', content: text }],
+            });
+            return res.input_tokens;
+        }
+        catch (err) {
+            log.warn(`count_tokens failed: ${err.message}`);
+            return null;
+        }
+    }
+}
+export const tokenCountService = new TokenCountService();
+//# sourceMappingURL=tokenCountService.js.map

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

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

@@ -1,5 +1,7 @@
-/BMad:agents:dev
----
-*review-qa {arg1}
-
-After completing QA fixes, update the gate YAML file's gate field to 'FIXED'.
+/BMad:agents:dev
+---
+*review-qa {arg1}
+
+After the fixes are applied and you update the story's Dev Agent Record, record which QA gate you addressed so Hammoc can track it. Read the `updated:` value from this story's QA gate YAML, then append this exact line inside the Completion Notes — replace the placeholder with that value. Do NOT change Status and do NOT edit the gate file:
+<!-- hammoc:qa-fix gate="<paste the gate's updated value>" applied="true" -->
+This flips the story from "apply QA fixes" to "request QA re-review" in Hammoc.

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

@@ -1,3 +1,9 @@
 /BMad:agents:qa
 ---
-*review {arg1}
+*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.

package/packages/server/dist/utils/assertSafeBundlePath.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Story 30.5 (AC9): single-source guard against ZIP-slip / path-traversal
+ * during harness bundle import.
+ *
+ * `jszip` does not normalise entry paths — a malicious bundle can ship an
+ * entry called `../../etc/passwd` or `C:\Windows\System32\evil.dll` and naive
+ * code that joins it to the project root would write outside the target.
+ * Every entry path read from an import ZIP must therefore pass through this
+ * function before the bundle service touches disk.
+ *
+ * Rejected shapes:
+ *   - absolute POSIX (`/etc/...`)
+ *   - absolute Windows (`C:\...`, `C:/...`)
+ *   - UNC (`\\server\share`, `//server/share`)
+ *   - any traversal component (`..` segment anywhere in the path)
+ *   - embedded null byte (would terminate the path early in fs APIs)
+ *
+ * Accepted shapes:
+ *   - POSIX-style relative paths (`skills/foo/SKILL.md`)
+ *   - Windows-style backslashes are normalised, then validated
+ *   - the empty string (the zip "/" root) is rejected as it carries no entry
+ */
+export declare class UnsafeBundlePathError extends Error {
+    readonly code = "HARNESS_BUNDLE_UNSAFE_PATH";
+    readonly relativePath: string;
+    constructor(relativePath: string, reason: string);
+}
+export declare function assertSafeBundlePath(relativePath: string): void;
+//# sourceMappingURL=assertSafeBundlePath.d.ts.map

package/packages/server/dist/utils/assertSafeBundlePath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertSafeBundlePath.d.ts","sourceRoot":"","sources":["../../src/utils/assertSafeBundlePath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAClB,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIjD;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAmB/D"}

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

@@ -0,0 +1,53 @@
+/**
+ * Story 30.5 (AC9): single-source guard against ZIP-slip / path-traversal
+ * during harness bundle import.
+ *
+ * `jszip` does not normalise entry paths — a malicious bundle can ship an
+ * entry called `../../etc/passwd` or `C:\Windows\System32\evil.dll` and naive
+ * code that joins it to the project root would write outside the target.
+ * Every entry path read from an import ZIP must therefore pass through this
+ * function before the bundle service touches disk.
+ *
+ * Rejected shapes:
+ *   - absolute POSIX (`/etc/...`)
+ *   - absolute Windows (`C:\...`, `C:/...`)
+ *   - UNC (`\\server\share`, `//server/share`)
+ *   - any traversal component (`..` segment anywhere in the path)
+ *   - embedded null byte (would terminate the path early in fs APIs)
+ *
+ * Accepted shapes:
+ *   - POSIX-style relative paths (`skills/foo/SKILL.md`)
+ *   - Windows-style backslashes are normalised, then validated
+ *   - the empty string (the zip "/" root) is rejected as it carries no entry
+ */
+const ABSOLUTE_WIN_RE = /^[A-Za-z]:[\\/]/;
+const TRAVERSAL_SEGMENT_RE = /(^|[\\/])\.\.([\\/]|$)/;
+export class UnsafeBundlePathError extends Error {
+    code = 'HARNESS_BUNDLE_UNSAFE_PATH';
+    relativePath;
+    constructor(relativePath, reason) {
+        super(`unsafe bundle entry "${relativePath}": ${reason}`);
+        this.relativePath = relativePath;
+    }
+}
+export function assertSafeBundlePath(relativePath) {
+    if (typeof relativePath !== 'string' || relativePath.length === 0) {
+        throw new UnsafeBundlePathError(String(relativePath), 'empty entry path');
+    }
+    if (relativePath.includes('\0')) {
+        throw new UnsafeBundlePathError(relativePath, 'null byte in entry path');
+    }
+    if (relativePath.startsWith('/') || relativePath.startsWith('\\')) {
+        throw new UnsafeBundlePathError(relativePath, 'absolute path not allowed');
+    }
+    if (ABSOLUTE_WIN_RE.test(relativePath)) {
+        throw new UnsafeBundlePathError(relativePath, 'Windows-absolute path not allowed');
+    }
+    if (relativePath.startsWith('\\\\') || relativePath.startsWith('//')) {
+        throw new UnsafeBundlePathError(relativePath, 'UNC path not allowed');
+    }
+    if (TRAVERSAL_SEGMENT_RE.test(relativePath)) {
+        throw new UnsafeBundlePathError(relativePath, 'parent-directory traversal not allowed');
+    }
+}
+//# sourceMappingURL=assertSafeBundlePath.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assertSafeBundlePath.js","sourceRoot":"","sources":["../../src/utils/assertSafeBundlePath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAC1C,MAAM,oBAAoB,GAAG,wBAAwB,CAAC;AAEtD,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,4BAA4B,CAAC;IACpC,YAAY,CAAS;IAC9B,YAAY,YAAoB,EAAE,MAAc;QAC9C,KAAK,CAAC,wBAAwB,YAAY,MAAM,MAAM,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAED,MAAM,UAAU,oBAAoB,CAAC,YAAoB;IACvD,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAqB,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,qBAAqB,CAAC,YAAY,EAAE,2BAA2B,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,eAAe,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,qBAAqB,CAAC,YAAY,EAAE,mCAAmC,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,qBAAqB,CAAC,YAAY,EAAE,sBAAsB,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,oBAAoB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,qBAAqB,CAAC,YAAY,EAAE,wCAAwC,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC"}

package/packages/server/dist/utils/backgroundBlock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Background-execution block policy shared by both chat engines (Story 36.1).
+ *
+ * Hammoc runs one CLI/SDK process per turn (turn-per-process) and kills it when
+ * the turn ends, so a backgrounded tool call (`run_in_background: true`) would be
+ * orphaned/killed and only leaves side effects (e.g. task-notification files).
+ * A PreToolUse hook denies such calls before they reach the shell — and unlike
+ * canUseTool, a PreToolUse deny also covers auto-approved tools (bypass/auto modes).
+ *
+ * SDK mode wires the check as an inline hook callback (see chatService); CLI mode
+ * runs it as an external command hook (resources/hooks/block-background.cjs). The
+ * two runtimes differ, so only the predicate + reason are shared here.
+ *
+ * ⚠️ The .cjs script duplicates BACKGROUND_BLOCK_REASON as a literal (it cannot
+ * import a TS module); keep the two strings in sync.
+ */
+export declare const BACKGROUND_BLOCK_REASON = "Background execution is disabled in Hammoc: it runs one process per turn, so a backgrounded task is killed when the turn ends. Re-run without run_in_background (foreground).";
+/**
+ * True when a tool call requests background execution (`run_in_background: true`) — which
+ * must be blocked regardless of WHICH tool it is. Hammoc is turn-per-process, so ANY
+ * backgrounded call is orphaned at turn end. We key off the INPUT FLAG, not the tool name:
+ * a tool-name allow-list silently misses tools (that was the earlier Windows PowerShell gap),
+ * whereas the flag is the actual thing that makes the call doomed.
+ *
+ * Crucially this does NOT touch foreground execution: several foreground tools launched in
+ * parallel within one turn and awaited carry no `run_in_background` flag, so they pass through.
+ */
+export declare function isBlockedBackgroundCall(toolInput: unknown): boolean;
+//# sourceMappingURL=backgroundBlock.d.ts.map

package/packages/server/dist/utils/backgroundBlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundBlock.d.ts","sourceRoot":"","sources":["../../src/utils/backgroundBlock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,kLAC6I,CAAC;AAElL;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAMnE"}