hammoc 1.4.0 → 1.6.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/utils/applyYamlFrontmatterPatch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Story 28.5: YAML frontmatter round-trip helper.
+ *
+ * Slash command files (`.claude/commands/**\/*.md`) are markdown documents with
+ * an optional `--- ... ---` YAML frontmatter block at the top. To preserve
+ * comments / key order / blank lines inside the frontmatter while leaving the
+ * markdown body byte-for-byte intact, we round-trip just the frontmatter slice
+ * via `yaml`(eemeli) `parseDocument`.
+ *
+ * Behaviour:
+ *   - File has no frontmatter + patch is empty (all keys absent) → return source
+ *     unchanged.
+ *   - File has no frontmatter + patch contains keys                → prepend a
+ *     fresh `--- ... ---` block.
+ *   - File has frontmatter + patch is empty                        → strip the
+ *     block entirely (matches AC3.a "all four fields absent ⇒ no frontmatter").
+ *   - File has frontmatter + patch sets keys                       → mutate keys
+ *     in place, preserving comments / order / blank lines for untouched keys.
+ *
+ * The body region (everything after the closing `---`) is taken from the source
+ * via raw substring slicing so byte-level equality holds — this is asserted by
+ * the unit tests with `result.slice(boundary) === source.slice(boundary)`.
+ */
+/**
+ * Apply key-level patches to the YAML frontmatter block of a markdown file.
+ * Body markdown is preserved byte-for-byte. Pass `undefined` to delete a key.
+ *
+ * - When the resulting frontmatter has no keys left, the entire `--- ... ---`
+ *   block (including the closing newline) is stripped.
+ * - When the source has no frontmatter and `newFrontmatter` carries at least
+ *   one defined value, a `--- ... ---` block is prepended with a single
+ *   trailing newline before the body.
+ *
+ * @throws HARNESS_PARSE_ERROR when the existing frontmatter is malformed YAML.
+ */
+export declare function applyYamlFrontmatterPatch(source: string, newFrontmatter: Record<string, unknown>): string;
+/**
+ * Strip the `--- ... ---` block (if any) and return the remaining body.
+ * Convenience helper — used by the service to surface the body separately
+ * from frontmatter on the read path.
+ */
+export declare function splitFrontmatterAndBody(source: string): {
+    frontmatterRaw: string | null;
+    body: string;
+};
+//# sourceMappingURL=applyYamlFrontmatterPatch.d.ts.map

package/packages/server/dist/services/utils/applyYamlFrontmatterPatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyYamlFrontmatterPatch.d.ts","sourceRoot":"","sources":["../../../src/services/utils/applyYamlFrontmatterPatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAuCH;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,MAAM,CAuDR;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG;IACvD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAIA"}

package/packages/server/dist/services/utils/applyYamlFrontmatterPatch.js

@@ -0,0 +1,125 @@
+/**
+ * Story 28.5: YAML frontmatter round-trip helper.
+ *
+ * Slash command files (`.claude/commands/**\/*.md`) are markdown documents with
+ * an optional `--- ... ---` YAML frontmatter block at the top. To preserve
+ * comments / key order / blank lines inside the frontmatter while leaving the
+ * markdown body byte-for-byte intact, we round-trip just the frontmatter slice
+ * via `yaml`(eemeli) `parseDocument`.
+ *
+ * Behaviour:
+ *   - File has no frontmatter + patch is empty (all keys absent) → return source
+ *     unchanged.
+ *   - File has no frontmatter + patch contains keys                → prepend a
+ *     fresh `--- ... ---` block.
+ *   - File has frontmatter + patch is empty                        → strip the
+ *     block entirely (matches AC3.a "all four fields absent ⇒ no frontmatter").
+ *   - File has frontmatter + patch sets keys                       → mutate keys
+ *     in place, preserving comments / order / blank lines for untouched keys.
+ *
+ * The body region (everything after the closing `---`) is taken from the source
+ * via raw substring slicing so byte-level equality holds — this is asserted by
+ * the unit tests with `result.slice(boundary) === source.slice(boundary)`.
+ */
+import { parseDocument } from 'yaml';
+import { HARNESS_ERRORS } from '@hammoc/shared';
+/** Match a leading `---\n...---\n?` frontmatter block. */
+const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n)?/;
+function findFrontmatter(source) {
+    const match = FRONTMATTER_RE.exec(source);
+    if (!match)
+        return null;
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    return { inner: match[1], bodyStart: match[0].length, eol };
+}
+function frontmatterIsEmpty(values) {
+    for (const v of Object.values(values)) {
+        if (v !== undefined)
+            return false;
+    }
+    return true;
+}
+function throwParseError(cause) {
+    const err = new Error(`failed to parse frontmatter: ${cause?.message ?? String(cause)}`);
+    err.code = HARNESS_ERRORS.HARNESS_PARSE_ERROR.code;
+    throw err;
+}
+/**
+ * Apply key-level patches to the YAML frontmatter block of a markdown file.
+ * Body markdown is preserved byte-for-byte. Pass `undefined` to delete a key.
+ *
+ * - When the resulting frontmatter has no keys left, the entire `--- ... ---`
+ *   block (including the closing newline) is stripped.
+ * - When the source has no frontmatter and `newFrontmatter` carries at least
+ *   one defined value, a `--- ... ---` block is prepended with a single
+ *   trailing newline before the body.
+ *
+ * @throws HARNESS_PARSE_ERROR when the existing frontmatter is malformed YAML.
+ */
+export function applyYamlFrontmatterPatch(source, newFrontmatter) {
+    const slice = findFrontmatter(source);
+    const allEmpty = frontmatterIsEmpty(newFrontmatter);
+    if (!slice) {
+        if (allEmpty)
+            return source;
+        const eol = source.includes('\r\n') ? '\r\n' : '\n';
+        let doc;
+        try {
+            doc = parseDocument('', { keepSourceTokens: true });
+        }
+        catch (cause) {
+            throwParseError(cause);
+        }
+        if (doc.contents == null) {
+            doc.contents = doc.createNode({});
+        }
+        for (const [key, value] of Object.entries(newFrontmatter)) {
+            if (value === undefined)
+                continue;
+            doc.setIn([key], value);
+        }
+        const yamlText = doc.toString().replace(/\r?\n$/, '');
+        return `---${eol}${yamlText}${eol}---${eol}${source}`;
+    }
+    let doc;
+    try {
+        doc = parseDocument(slice.inner, { keepSourceTokens: true });
+        if (doc.errors.length > 0) {
+            throw doc.errors[0];
+        }
+    }
+    catch (cause) {
+        throwParseError(cause);
+    }
+    if (doc.contents == null) {
+        doc.contents = doc.createNode({});
+    }
+    for (const [key, value] of Object.entries(newFrontmatter)) {
+        if (value === undefined) {
+            if (doc.hasIn([key]))
+                doc.deleteIn([key]);
+            continue;
+        }
+        doc.setIn([key], value);
+    }
+    // If the patched document is empty (no top-level keys left), strip the block.
+    const docContents = doc.contents;
+    const remainingKeys = docContents?.items?.length ?? 0;
+    if (remainingKeys === 0) {
+        return source.slice(slice.bodyStart);
+    }
+    const yamlText = doc.toString().replace(/\r?\n$/, '');
+    return `---${slice.eol}${yamlText}${slice.eol}---${slice.eol}${source.slice(slice.bodyStart)}`;
+}
+/**
+ * Strip the `--- ... ---` block (if any) and return the remaining body.
+ * Convenience helper — used by the service to surface the body separately
+ * from frontmatter on the read path.
+ */
+export function splitFrontmatterAndBody(source) {
+    const slice = findFrontmatter(source);
+    if (!slice)
+        return { frontmatterRaw: null, body: source };
+    return { frontmatterRaw: slice.inner, body: source.slice(slice.bodyStart) };
+}
+//# sourceMappingURL=applyYamlFrontmatterPatch.js.map

package/packages/server/dist/services/utils/applyYamlFrontmatterPatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyYamlFrontmatterPatch.js","sourceRoot":"","sources":["../../../src/services/utils/applyYamlFrontmatterPatch.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,7 @@
 /BMad:agents:qa
 ---
-*review {arg1}
+*review {arg1}
+
+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/snippets/split-commit

@@ -0,0 +1,9 @@
+Review the current working tree with `git status` and `git diff` (both staged and unstaged). Group the changes into logically coherent units so that each commit represents a single concern (one feature, one fix, one refactor, etc.). For each group:
+
+1. Stage only the files (or hunks, via `git add -p`, when a single file mixes concerns) that belong to the group.
+2. Commit with a clear conventional-commit style message that explains *why* the change exists, not just *what* changed.
+3. Move on to the next group.
+
+Do not push. Do not amend existing commits. If the changes are already coherent as a single commit, say so and make one commit instead of forcing a split.
+
+When you finish, list the resulting commits (hash + subject line) as a summary.

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

@@ -0,0 +1,53 @@
+/**
+ * Story 30.3 (Task 2.2): apply the three `secretsPolicy` modes to a payload
+ * before it is written into the bundle.
+ *
+ * Two operating shapes, mirroring `detectSecretsInValue` / `detectSecretsInText`:
+ *
+ *   1. `applyPolicyToValue` walks a JSON-like value (mcp config, settings.json
+ *      hooks block). For `excluded` the matched leaf is deleted from its
+ *      parent; for `placeholder` it is rewritten as `${ENV_REF_NAME}` using
+ *      `secretPlaceholderNamer`; for `included-explicit` the value is left
+ *      untouched.
+ *
+ *   2. `applyPolicyToText` walks line-oriented text (CLAUDE.md, agent body,
+ *      command body). For `excluded` the offending line is replaced with the
+ *      sentinel `<< SECRET REMOVED >>` so line numbers stay stable; for
+ *      `placeholder` every secret substring on that line is rewritten as
+ *      `${ENV_REF_NAME}`; for `included-explicit` the text is unchanged.
+ *
+ * Both return per-call counters that the caller aggregates into the
+ * `ImportApplySummary` (well, the export equivalent — same idea: surface to
+ * the user how many secrets were affected).
+ */
+import type { BundleItemDomain, SecretsPolicy } from '@hammoc/shared';
+export declare const SECRET_REMOVED_TEXT_PLACEHOLDER = "<< SECRET REMOVED >>";
+export interface ApplyPolicyValueInput {
+    policy: SecretsPolicy;
+    domain: BundleItemDomain;
+    cardName: string;
+    hookEvent?: string;
+    /** Root-relative path prefix for matched dot-paths (e.g. `mcpServers.context7`). */
+    pathPrefix?: string[];
+    value: unknown;
+}
+export interface ApplyPolicyValueResult {
+    value: unknown;
+    removedCount: number;
+    replacedCount: number;
+}
+export interface ApplyPolicyTextInput {
+    policy: SecretsPolicy;
+    domain: BundleItemDomain;
+    cardName: string;
+    hookEvent?: string;
+    text: string;
+}
+export interface ApplyPolicyTextResult {
+    text: string;
+    removedCount: number;
+    replacedCount: number;
+}
+export declare function applyPolicyToText(input: ApplyPolicyTextInput): ApplyPolicyTextResult;
+export declare function applyPolicyToValue(input: ApplyPolicyValueInput): ApplyPolicyValueResult;
+//# sourceMappingURL=applySecretsPolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"applySecretsPolicy.d.ts","sourceRoot":"","sources":["../../src/utils/applySecretsPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEtE,eAAO,MAAM,+BAA+B,yBAAyB,CAAC;AAEtE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAwFD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAsCpF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CA4DvF"}