hammoc 1.4.0 → 1.6.0

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

@@ -0,0 +1,181 @@
+/**
+ * Story 31.2 (Task A.3): generator for the standalone SessionStart hook script
+ * `<projectRoot>/.hammoc/hooks/context-builder.mjs`.
+ *
+ * The generated `.mjs` runs independently of the Hammoc server at every session
+ * start. It is REGENERATED on every manifest save, so the declared file list /
+ * variable toggles / acknowledged commands are baked in as a CONFIG literal,
+ * while the actual VALUES (file contents, git output, today's date, active BMad
+ * story, command stdout) are computed FRESH at runtime (AC2.b/2.c — never
+ * snapshotted at generation time).
+ *
+ * Implementation note — the script body is a `String.raw` template so the regex
+ * backslashes (`\s`, `\r`, `\n`) survive into the emitted file verbatim. The two
+ * injected values are spliced in via function-replacement (not `${}`
+ * interpolation) so a `$` inside a path or command cannot trigger a replacement
+ * pattern, and so the body can stay free of `${` entirely.
+ */
+const SCRIPT_BODY = String.raw `// AUTO-GENERATED by Hammoc Context Builder (Story 31.2). DO NOT EDIT BY HAND.
+// Source of truth: <projectRoot>/.hammoc/context-builder.json
+// This file is overwritten on every manifest save. Edits here are lost.
+//
+// At every Claude Code SessionStart it prints a JSON envelope on stdout:
+//   { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "<assembled>" } }
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const PROJECT_ROOT = __PROJECT_ROOT_JSON__;
+const CONFIG = __CONFIG_JSON__;
+
+function gitOutput(args) {
+  return execSync('git ' + args, {
+    cwd: PROJECT_ROOT,
+    encoding: 'utf8',
+    timeout: 5000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+function readDevStoryLocation() {
+  // Resolve devStoryLocation from .bmad-core/core-config.yaml at runtime (no YAML
+  // dependency — a single-line regex is enough). Fallback: docs/stories.
+  try {
+    const cfg = fs.readFileSync(path.join(PROJECT_ROOT, '.bmad-core', 'core-config.yaml'), 'utf8');
+    const lines = cfg.split(/\r?\n/);
+    for (const ln of lines) {
+      const m = ln.match(/^devStoryLocation:\s*(.+?)\s*$/);
+      if (m) return m[1].replace(/^['"]|['"]$/g, '').trim();
+    }
+  } catch (e) {
+    // ignore — fall through to default
+  }
+  return 'docs/stories';
+}
+
+function parseTitle(text, fallback) {
+  const lines = text.split(/\r?\n/);
+  for (const ln of lines) {
+    const m = ln.match(/^#\s+(.+?)\s*$/);
+    if (m) return m[1];
+  }
+  return fallback;
+}
+
+function parseStatus(text) {
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Status\s*$/.test(lines[i])) {
+      for (let j = i + 1; j < lines.length; j++) {
+        const t = lines[j].trim();
+        if (t) return t;
+      }
+    }
+  }
+  return 'unknown';
+}
+
+function activeBmadStory() {
+  // PO-confirmed definition: the latest-mtime .story.md in devStoryLocation,
+  // surfaced as "<title> (Status: <status>)".
+  try {
+    const storyDir = readDevStoryLocation();
+    const dirAbs = path.resolve(PROJECT_ROOT, storyDir);
+    const files = fs.readdirSync(dirAbs).filter(function (f) { return f.endsWith('.story.md'); });
+    if (files.length === 0) return '(no .story.md files in ' + storyDir + ')';
+    let latest = files[0];
+    let latestMs = -1;
+    for (const f of files) {
+      const st = fs.statSync(path.join(dirAbs, f));
+      if (st.mtimeMs > latestMs) { latestMs = st.mtimeMs; latest = f; }
+    }
+    const text = fs.readFileSync(path.join(dirAbs, latest), 'utf8');
+    return parseTitle(text, latest) + ' (Status: ' + parseStatus(text) + ')';
+  } catch (e) {
+    return '(unable to resolve active BMad story)';
+  }
+}
+
+const blocks = [];
+
+// (a) Reference files — read fresh; missing files become a placeholder so the
+// whole script never fails (AC2.c).
+for (const rel of CONFIG.files) {
+  const abs = path.resolve(PROJECT_ROOT, rel);
+  try {
+    const content = fs.readFileSync(abs, 'utf8');
+    blocks.push('## Reference file: ' + rel + '\n\n' + content);
+  } catch (e) {
+    blocks.push('## Reference file: ' + rel + '\n\n(파일을 찾을 수 없음: ' + rel + ')');
+  }
+}
+
+// (b) Built-in dynamic variables — recomputed every run (AC2.b).
+if (CONFIG.variables.gitBranch) {
+  let v;
+  try { v = gitOutput('rev-parse --abbrev-ref HEAD'); } catch (e) { v = '(git unavailable)'; }
+  blocks.push('## Current git branch\n\n' + v);
+}
+if (CONFIG.variables.recentCommits) {
+  const n = CONFIG.recentCommitsCount || 5;
+  let v;
+  try { v = gitOutput('log -n ' + n + ' --pretty=format:%h %s'); } catch (e) { v = '(git unavailable)'; }
+  blocks.push('## Recent ' + n + ' commit(s)\n\n' + v);
+}
+if (CONFIG.variables.uncommittedCount) {
+  let v;
+  try {
+    const out = gitOutput('status --short');
+    v = out ? out.split(/\r?\n/).filter(Boolean).length : 0;
+  } catch (e) { v = '(git unavailable)'; }
+  blocks.push('## Uncommitted file count\n\n' + String(v));
+}
+if (CONFIG.variables.today) {
+  blocks.push('## Today\n\n' + new Date().toISOString().slice(0, 10));
+}
+if (CONFIG.variables.activeBmadStory) {
+  blocks.push('## Active BMad story\n\n' + activeBmadStory());
+}
+
+// (c) Acknowledged custom commands (AC5.b) — only acknowledged commands were
+// baked into CONFIG.
+for (const cc of CONFIG.customCommands) {
+  let out;
+  try {
+    out = execSync(cc.command, { cwd: PROJECT_ROOT, encoding: 'utf8', timeout: 10000 }).trim();
+  } catch (e) {
+    out = '(command failed: ' + (e && e.message ? e.message : 'error') + ')';
+  }
+  blocks.push('## Command: ' + cc.command + '\n\n' + out);
+}
+
+const additionalContext = blocks.join('\n\n');
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'SessionStart',
+    additionalContext: additionalContext,
+  },
+}));
+`;
+/**
+ * Build the `.mjs` script text for the given project root + manifest. Only
+ * acknowledged custom commands are baked in (AC5.b).
+ */
+export function buildContextBuilderScript(projectRoot, manifest) {
+    const config = {
+        files: manifest.files,
+        variables: manifest.variables,
+        recentCommitsCount: manifest.recentCommitsCount ?? 5,
+        customCommands: manifest.customCommands
+            .filter((c) => c.acknowledged)
+            .map((c) => ({ command: c.command })),
+    };
+    // Function replacements so a `$` inside a path/command is never treated as a
+    // replacement pattern (`$&`, `$1`, ...).
+    const projectRootJson = JSON.stringify(projectRoot);
+    const configJson = JSON.stringify(config, null, 2);
+    return SCRIPT_BODY
+        .replace('__PROJECT_ROOT_JSON__', () => projectRootJson)
+        .replace('__CONFIG_JSON__', () => configJson);
+}
+//# sourceMappingURL=contextBuilderScriptTemplate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contextBuilderScriptTemplate.js","sourceRoot":"","sources":["../../src/services/contextBuilderScriptTemplate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6I7B,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,WAAmB,EACnB,QAAgC;IAEhC,MAAM,MAAM,GAAgB;QAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB,IAAI,CAAC;QACpD,cAAc,EAAE,QAAQ,CAAC,cAAc;aACpC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;aAC7B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KACxC,CAAC;IAEF,6EAA6E;IAC7E,yCAAyC;IACzC,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAEnD,OAAO,WAAW;SACf,OAAO,CAAC,uBAAuB,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC;SACvD,OAAO,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC;AAClD,CAAC"}

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

@@ -0,0 +1,68 @@
+/**
+ * Story 31.2: SessionStart context-builder service (Epic 31).
+ *
+ * Domain: the declarative `<projectRoot>/.hammoc/context-builder.json` manifest
+ * (single source of truth) and its two GENERATED artifacts —
+ *   - `<projectRoot>/.hammoc/hooks/context-builder.mjs`   (the SessionStart script)
+ *   - `<projectRoot>/.claude/settings.json` `hooks.SessionStart` entry pointing at it
+ *
+ * The manifest + script live under `.hammoc/`, a SIBLING of `.claude/` (outside
+ * the harness whitelist), so they get dedicated canonical-path resolvers
+ * (`resolveContextBuilderManifestPath` / `resolveContextBuilderScriptPath`) and
+ * are read/written with direct `fs` — exactly like Story 31.1's
+ * `.bmad-core/core-config.yaml`. `settings.json` IS inside `.claude/`, so its
+ * entry registration routes through `harnessService` + `applyJsoncPatch` (JSONC
+ * round-trip preserving comments/order).
+ *
+ * Ownership is identified purely by the command path marker
+ * (`CONTEXT_BUILDER_SCRIPT_MARKER`) — no extra metadata key is written into
+ * settings.json (AC1.e / AC3.a: the path IS the ownership identifier). A
+ * Hammoc-managed SessionStart group is updated in place; foreign (user-authored)
+ * groups are never touched.
+ */
+import { type ContextBuilderReadResponse, type ContextBuilderGenerateResponse } from '@hammoc/shared';
+declare class ContextBuilderService {
+    /**
+     * Read the manifest + derived artifact state. Missing manifest → a default
+     * (disabled, empty) manifest with `mtime: ''` so the panel opens empty
+     * instead of erroring.
+     */
+    readManifest(projectSlug: string): Promise<ContextBuilderReadResponse>;
+    /**
+     * Persist the manifest (SSoT) then regenerate its artifacts. When
+     * `manifest.enabled` is false this is equivalent to `disable` (artifacts are
+     * removed). Returns the new manifest mtime + generated artifact locations +
+     * any non-blocking secret warnings (AC5.c).
+     */
+    writeManifest(projectSlug: string, input: unknown, expectedMtime?: string): Promise<ContextBuilderGenerateResponse>;
+    /**
+     * AC1.f — disable: retain the declaration (`enabled: false`) but remove the
+     * generated script + the Hammoc-managed SessionStart entry (other entries
+     * preserved).
+     */
+    disable(projectSlug: string, expectedMtime?: string): Promise<{
+        mtime: string;
+    }>;
+    /** STALE_WRITE-guarded write of the manifest JSON via direct fs. */
+    private writeManifestFile;
+    /**
+     * Generate the `.mjs` script from the manifest, write it to disk, and
+     * register/refresh the SessionStart entry in settings.json.
+     */
+    private generate;
+    /**
+     * Register (or refresh) the Hammoc-managed SessionStart entry. Updates the
+     * managed group in place when present; otherwise appends a new group, leaving
+     * any foreign groups untouched (AC1.e).
+     */
+    private registerEntry;
+    /**
+     * Remove the Hammoc-managed SessionStart entry (preserving foreign groups)
+     * and delete the generated script. Returns the new settings.json mtime (or
+     * the unchanged/empty value when settings.json does not exist).
+     */
+    private removeEntryAndScript;
+}
+export declare const contextBuilderService: ContextBuilderService;
+export {};
+//# sourceMappingURL=contextBuilderService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contextBuilderService.d.ts","sourceRoot":"","sources":["../../src/services/contextBuilderService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAML,KAAK,0BAA0B,EAC/B,KAAK,8BAA8B,EAGpC,MAAM,gBAAgB,CAAC;AAkIxB,cAAM,qBAAqB;IACzB;;;;OAIG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC;IA0C5E;;;;;OAKG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,8BAA8B,CAAC;IAsB1C;;;;OAIG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAgBtF,oEAAoE;YACtD,iBAAiB;IAyC/B;;;OAGG;YACW,QAAQ;IAoBtB;;;;OAIG;YACW,aAAa;IAoC3B;;;;OAIG;YACW,oBAAoB;CA8BnC;AAED,eAAO,MAAM,qBAAqB,uBAA8B,CAAC"}

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

@@ -0,0 +1,345 @@
+/**
+ * Story 31.2: SessionStart context-builder service (Epic 31).
+ *
+ * Domain: the declarative `<projectRoot>/.hammoc/context-builder.json` manifest
+ * (single source of truth) and its two GENERATED artifacts —
+ *   - `<projectRoot>/.hammoc/hooks/context-builder.mjs`   (the SessionStart script)
+ *   - `<projectRoot>/.claude/settings.json` `hooks.SessionStart` entry pointing at it
+ *
+ * The manifest + script live under `.hammoc/`, a SIBLING of `.claude/` (outside
+ * the harness whitelist), so they get dedicated canonical-path resolvers
+ * (`resolveContextBuilderManifestPath` / `resolveContextBuilderScriptPath`) and
+ * are read/written with direct `fs` — exactly like Story 31.1's
+ * `.bmad-core/core-config.yaml`. `settings.json` IS inside `.claude/`, so its
+ * entry registration routes through `harnessService` + `applyJsoncPatch` (JSONC
+ * round-trip preserving comments/order).
+ *
+ * Ownership is identified purely by the command path marker
+ * (`CONTEXT_BUILDER_SCRIPT_MARKER`) — no extra metadata key is written into
+ * settings.json (AC1.e / AC3.a: the path IS the ownership identifier). A
+ * Hammoc-managed SessionStart group is updated in place; foreign (user-authored)
+ * groups are never touched.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { parse as parseJsonc } from 'jsonc-parser';
+import { HARNESS_ERRORS, CONTEXT_BUILDER_SCRIPT_MARKER, CONTEXT_BUILDER_VARIABLE_IDS, createDefaultContextBuilderManifest, } from '@hammoc/shared';
+import { resolveContextBuilderManifestPath, resolveContextBuilderScriptPath, } from '../utils/harnessPaths.js';
+import { harnessService } from './harnessService.js';
+import { applyJsoncPatch } from '../utils/structuredEditor.js';
+import { detectSecretsInText } from '../utils/secretHeuristic.js';
+import { fileWatcherService } from './fileWatcherService.js';
+import { buildContextBuilderScript } from './contextBuilderScriptTemplate.js';
+function throwMapped(code, message, extras) {
+    const err = new Error(message);
+    err.code = code;
+    if (extras)
+        Object.assign(err, extras);
+    throw err;
+}
+function isFileNotFound(err) {
+    const code = err?.code;
+    return code === 'ENOENT' || code === HARNESS_ERRORS.HARNESS_FILE_NOT_FOUND.code;
+}
+/** Forward-slash a path so the ownership marker match works cross-platform. */
+function normalizeSlashes(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Normalize an arbitrary parsed manifest into a fully-populated, well-typed
+ * shape: all 5 variable keys present, arrays defaulted, version pinned. Guards
+ * against partial on-disk manifests and hand-edits.
+ */
+function normalizeManifest(input) {
+    const base = createDefaultContextBuilderManifest();
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return base;
+    }
+    const raw = input;
+    const files = Array.isArray(raw.files)
+        ? raw.files.filter((f) => typeof f === 'string')
+        : base.files;
+    const variables = { ...base.variables };
+    if (raw.variables && typeof raw.variables === 'object' && !Array.isArray(raw.variables)) {
+        const rv = raw.variables;
+        for (const id of CONTEXT_BUILDER_VARIABLE_IDS) {
+            if (typeof rv[id] === 'boolean')
+                variables[id] = rv[id];
+        }
+    }
+    const customCommands = Array.isArray(raw.customCommands)
+        ? raw.customCommands
+            .filter((c) => !!c && typeof c === 'object')
+            .map((c) => ({
+            command: typeof c.command === 'string' ? c.command : '',
+            acknowledged: c.acknowledged === true,
+        }))
+            .filter((c) => c.command.length > 0)
+        : base.customCommands;
+    const recentCommitsCount = typeof raw.recentCommitsCount === 'number' && raw.recentCommitsCount > 0
+        ? Math.floor(raw.recentCommitsCount)
+        : base.recentCommitsCount;
+    return {
+        version: 1,
+        enabled: raw.enabled === true,
+        files,
+        variables,
+        recentCommitsCount,
+        customCommands,
+    };
+}
+const SETTINGS_REL = 'settings.json';
+function settingsRef(projectSlug) {
+    return { scope: 'project', projectSlug, relativePath: SETTINGS_REL };
+}
+/** Read settings.json via harnessService; missing file → empty content. */
+async function readSettings(projectSlug) {
+    try {
+        const res = await harnessService.read(settingsRef(projectSlug));
+        return { content: res.content ?? '', mtime: res.mtime, exists: true };
+    }
+    catch (err) {
+        if (isFileNotFound(err))
+            return { content: '', mtime: '', exists: false };
+        throw err;
+    }
+}
+function parseSessionStartGroups(settingsContent) {
+    if (!settingsContent.trim())
+        return [];
+    let parsed;
+    try {
+        parsed = parseJsonc(settingsContent);
+    }
+    catch {
+        return [];
+    }
+    const hooks = parsed?.hooks?.SessionStart;
+    return Array.isArray(hooks) ? hooks : [];
+}
+/** Index of the Hammoc-managed SessionStart group, or -1 when none exists. */
+function findManagedIndex(groups) {
+    for (let i = 0; i < groups.length; i += 1) {
+        const hookList = groups[i]?.hooks;
+        if (Array.isArray(hookList) &&
+            hookList.some((h) => typeof h?.command === 'string' &&
+                normalizeSlashes(h.command).includes(CONTEXT_BUILDER_SCRIPT_MARKER))) {
+            return i;
+        }
+    }
+    return -1;
+}
+class ContextBuilderService {
+    /**
+     * Read the manifest + derived artifact state. Missing manifest → a default
+     * (disabled, empty) manifest with `mtime: ''` so the panel opens empty
+     * instead of erroring.
+     */
+    async readManifest(projectSlug) {
+        const { absolutePath } = await resolveContextBuilderManifestPath(projectSlug);
+        let manifest = createDefaultContextBuilderManifest();
+        let mtime = '';
+        try {
+            const stat = await fs.stat(absolutePath);
+            if (stat.isFile()) {
+                const text = await fs.readFile(absolutePath, 'utf-8');
+                try {
+                    manifest = normalizeManifest(JSON.parse(text));
+                }
+                catch {
+                    // Corrupt JSON on disk — surface as PARSE_ERROR so the client can
+                    // reset rather than silently dropping the user's declaration.
+                    throwMapped(HARNESS_ERRORS.HARNESS_PARSE_ERROR.code, 'context-builder.json is not valid JSON');
+                }
+                mtime = stat.mtime.toISOString();
+            }
+        }
+        catch (err) {
+            if (!isFileNotFound(err)) {
+                if (err.code === HARNESS_ERRORS.HARNESS_PARSE_ERROR.code)
+                    throw err;
+                const code = err.code;
+                if (code === 'EACCES')
+                    throwMapped(HARNESS_ERRORS.HARNESS_FORBIDDEN.code, 'permission denied');
+                throw err;
+            }
+        }
+        const { absolutePath: scriptPath } = await resolveContextBuilderScriptPath(projectSlug);
+        let scriptExists = false;
+        try {
+            const st = await fs.stat(scriptPath);
+            scriptExists = st.isFile();
+        }
+        catch {
+            scriptExists = false;
+        }
+        const { content } = await readSettings(projectSlug);
+        const entryRegistered = findManagedIndex(parseSessionStartGroups(content)) >= 0;
+        return { manifest, mtime, scriptExists, entryRegistered };
+    }
+    /**
+     * Persist the manifest (SSoT) then regenerate its artifacts. When
+     * `manifest.enabled` is false this is equivalent to `disable` (artifacts are
+     * removed). Returns the new manifest mtime + generated artifact locations +
+     * any non-blocking secret warnings (AC5.c).
+     */
+    async writeManifest(projectSlug, input, expectedMtime) {
+        const manifest = normalizeManifest(input);
+        // AC5.c — scan acknowledged command strings; NON-BLOCKING notice only.
+        const secretWarningCommandIndices = [];
+        manifest.customCommands.forEach((cc, idx) => {
+            if (cc.acknowledged && detectSecretsInText(cc.command).matched) {
+                secretWarningCommandIndices.push(idx);
+            }
+        });
+        const mtime = await this.writeManifestFile(projectSlug, manifest, expectedMtime);
+        if (!manifest.enabled) {
+            const settingsMtime = await this.removeEntryAndScript(projectSlug);
+            return { mtime, scriptPath: '', settingsMtime, secretWarningCommandIndices };
+        }
+        const { scriptPath, settingsMtime } = await this.generate(projectSlug, manifest);
+        return { mtime, scriptPath, settingsMtime, secretWarningCommandIndices };
+    }
+    /**
+     * AC1.f — disable: retain the declaration (`enabled: false`) but remove the
+     * generated script + the Hammoc-managed SessionStart entry (other entries
+     * preserved).
+     */
+    async disable(projectSlug, expectedMtime) {
+        const current = await this.readManifest(projectSlug);
+        const manifest = { ...current.manifest, enabled: false };
+        const mtime = await this.writeManifestFile(projectSlug, manifest, expectedMtime ?? (current.mtime || undefined));
+        await this.removeEntryAndScript(projectSlug);
+        return { mtime };
+    }
+    // -------------------------------------------------------------------------
+    // internals
+    // -------------------------------------------------------------------------
+    /** STALE_WRITE-guarded write of the manifest JSON via direct fs. */
+    async writeManifestFile(projectSlug, manifest, expectedMtime) {
+        const { absolutePath } = await resolveContextBuilderManifestPath(projectSlug);
+        if (expectedMtime !== undefined) {
+            try {
+                const existing = await fs.stat(absolutePath);
+                const currentMtime = existing.mtime.toISOString();
+                if (currentMtime !== expectedMtime) {
+                    throwMapped(HARNESS_ERRORS.HARNESS_STALE_WRITE.code, 'manifest changed on disk', { currentMtime });
+                }
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'ENOENT') {
+                    // expectedMtime '' (the empty-state default) means "create" — only a
+                    // non-empty expectedMtime against a missing file is a real stale.
+                    if (expectedMtime !== '') {
+                        throwMapped(HARNESS_ERRORS.HARNESS_STALE_WRITE.code, 'manifest missing on disk', { currentMtime: '' });
+                    }
+                }
+                else if (code === HARNESS_ERRORS.HARNESS_STALE_WRITE.code) {
+                    throw error;
+                }
+                else if (code === 'EACCES') {
+                    throwMapped(HARNESS_ERRORS.HARNESS_FORBIDDEN.code, 'permission denied');
+                }
+            }
+        }
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+        try {
+            await fs.writeFile(absolutePath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+        }
+        catch {
+            throwMapped(HARNESS_ERRORS.HARNESS_WRITE_ERROR.code, 'failed to write manifest');
+        }
+        const stat = await fs.stat(absolutePath);
+        fileWatcherService.noteLocalWrite(absolutePath);
+        return stat.mtime.toISOString();
+    }
+    /**
+     * Generate the `.mjs` script from the manifest, write it to disk, and
+     * register/refresh the SessionStart entry in settings.json.
+     */
+    async generate(projectSlug, manifest) {
+        const { resolvedRoot: projectRoot, absolutePath: scriptPath } = await resolveContextBuilderScriptPath(projectSlug);
+        const scriptText = buildContextBuilderScript(projectRoot, manifest);
+        await fs.mkdir(path.dirname(scriptPath), { recursive: true });
+        try {
+            await fs.writeFile(scriptPath, scriptText, 'utf-8');
+        }
+        catch {
+            throwMapped(HARNESS_ERRORS.HARNESS_WRITE_ERROR.code, 'failed to write script');
+        }
+        fileWatcherService.noteLocalWrite(scriptPath);
+        const settingsMtime = await this.registerEntry(projectSlug, projectRoot, scriptPath);
+        return { scriptPath, settingsMtime };
+    }
+    /**
+     * Register (or refresh) the Hammoc-managed SessionStart entry. Updates the
+     * managed group in place when present; otherwise appends a new group, leaving
+     * any foreign groups untouched (AC1.e).
+     */
+    async registerEntry(projectSlug, projectRoot, scriptPath) {
+        // Context builder is NOT BMad-gated — `.claude/` may not exist yet on a
+        // fresh project. Create it so the settings.json write has a parent dir.
+        await fs.mkdir(path.join(projectRoot, '.claude'), { recursive: true });
+        const { content, mtime, exists } = await readSettings(projectSlug);
+        const command = `node "${normalizeSlashes(scriptPath)}"`;
+        const group = { hooks: [{ type: 'command', command }] };
+        const groups = parseSessionStartGroups(content);
+        const managedIdx = findManagedIndex(groups);
+        let patchOp;
+        if (managedIdx >= 0) {
+            patchOp = { path: ['hooks', 'SessionStart', managedIdx], value: group };
+        }
+        else if (groups.length === 0) {
+            patchOp = { path: ['hooks', 'SessionStart'], value: [group] };
+        }
+        else {
+            patchOp = { path: ['hooks', 'SessionStart', groups.length], value: group };
+        }
+        const source = content.trim().length === 0 ? '{}' : content;
+        const patched = applyJsoncPatch(source, [patchOp]);
+        const written = await harnessService.write(settingsRef(projectSlug), {
+            content: patched,
+            // AC1.e — guard against an external settings.json edit landing between
+            // our read and write. Omit on create (file did not exist).
+            expectedMtime: exists ? mtime : undefined,
+        });
+        return written.mtime;
+    }
+    /**
+     * Remove the Hammoc-managed SessionStart entry (preserving foreign groups)
+     * and delete the generated script. Returns the new settings.json mtime (or
+     * the unchanged/empty value when settings.json does not exist).
+     */
+    async removeEntryAndScript(projectSlug) {
+        // Delete the generated script (idempotent).
+        const { absolutePath: scriptPath } = await resolveContextBuilderScriptPath(projectSlug);
+        try {
+            await fs.unlink(scriptPath);
+            fileWatcherService.noteLocalWrite(scriptPath);
+        }
+        catch {
+            // already gone — fine.
+        }
+        const { content, mtime, exists } = await readSettings(projectSlug);
+        if (!exists)
+            return '';
+        const groups = parseSessionStartGroups(content);
+        const managedIdx = findManagedIndex(groups);
+        if (managedIdx < 0)
+            return mtime; // nothing to remove.
+        // Remove the managed group; if it was the only group, drop the SessionStart
+        // key entirely so we don't leave an empty array behind.
+        const ops = groups.length === 1
+            ? [{ path: ['hooks', 'SessionStart'], value: undefined }]
+            : [{ path: ['hooks', 'SessionStart', managedIdx], value: undefined }];
+        const patched = applyJsoncPatch(content, ops);
+        const written = await harnessService.write(settingsRef(projectSlug), {
+            content: patched,
+            expectedMtime: mtime,
+        });
+        return written.mtime;
+    }
+}
+export const contextBuilderService = new ContextBuilderService();
+//# sourceMappingURL=contextBuilderService.js.map

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

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

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

@@ -11,9 +11,20 @@
  * cause an "external change" banner on their own save. Callers must invoke
  * noteLocalWrite(absolutePath) immediately after writing — events for paths
  * noted within the last SELF_WRITE_WINDOW_MS are silently dropped.
+ *
+ * Story 28.0.5: extended with harness-scope watchers over ~/.claude (user) and
+ * <project>/.claude (project). Harness watchers emit `harness:external-change`
+ * on dedicated rooms and share the same self-write-suppression map so writes
+ * coming out of harnessService do not echo back to the originating client.
  */
+import type { HarnessScope } from '@hammoc/shared';
+interface HarnessRef {
+    scope: HarnessScope;
+    projectSlug?: string;
+}
 declare class FileWatcherService {
     private watchers;
+    private harnessWatchers;
     /** absolute path → timestamp (ms) of the last local write */
     private pendingLocalWrites;
     /** Events arriving within this window after a local write are treated as our own echo. */
@@ -25,6 +36,19 @@ declare class FileWatcherService {
     ensureWatcher(projectSlug: string, projectRoot: string): void;
     /** Decrement the ref count and close the watcher when it reaches zero. */
     releaseWatcher(projectSlug: string): void;
+    /**
+     * Start (or increment the ref count of) a harness watcher for the given scope.
+     * - `scope='user'`     → ~/.claude (via `getUserHarnessRoot()`)
+     * - `scope='project'`  → <project>/.claude (via `getProjectHarnessRoot()`)
+     *
+     * Idempotent + reference-counted so concurrent subscribers share one chokidar.
+     * Unlike the project watcher, harness watchers subscribe to `add` in addition
+     * to `change`/`unlink` so they can fire the `'created'` type required by
+     * HarnessExternalChangeEvent.
+     */
+    ensureHarnessWatcher(ref: HarnessRef): Promise<void>;
+    /** Decrement the harness watcher ref count, closing when it reaches zero. */
+    releaseHarnessWatcher(ref: HarnessRef): void;
     /** Mark an absolute path as just-written so the next watcher event is ignored. */
     noteLocalWrite(absolutePath: string): void;
     /** Close every active watcher. Called on server shutdown. */