hammoc 1.4.0 → 1.5.0

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

@@ -0,0 +1,34 @@
+/**
+ * Story 28.0.5: Harness workbench path resolver.
+ *
+ * Resolves `~/.claude` (user scope) and `<projectRoot>/.claude` (project scope)
+ * into absolute paths and enforces that any relative path requested by the
+ * caller stays inside the resolved root. Every entry point into `harnessService`
+ * MUST route through `resolveHarnessPath` so that Windows/POSIX separator
+ * mixing, drive letters, UNC paths, and null-byte inputs cannot escape the
+ * subtree.
+ */
+import { type HarnessPathRef } from '@hammoc/shared';
+/** Return the absolute path to the user-scope harness root (`~/.claude`). */
+export declare function getUserHarnessRoot(): string;
+/** Return the absolute path to the project-scope harness root (`<project>/.claude`). */
+export declare function getProjectHarnessRoot(projectSlug: string): Promise<string>;
+export interface ResolvedHarnessPath {
+    resolvedRoot: string;
+    absolutePath: string;
+}
+/**
+ * Resolve a `HarnessPathRef` to an absolute path, guaranteed to sit inside the
+ * resolved root. Throws `HARNESS_PATH_DENIED` for any traversal attempt.
+ */
+export declare function resolveHarnessPath(ref: HarnessPathRef): Promise<ResolvedHarnessPath>;
+/**
+ * Story 29.1 (AC6): resolve the project-root `<projectRoot>/CLAUDE.md` path —
+ * the single file in the harness workbench whose location sits OUTSIDE the
+ * project's `.claude/` subtree, so `resolveHarnessPath` would reject it as a
+ * traversal. This helper accepts only `projectSlug` (no caller-supplied
+ * relative path) and returns the canonical CLAUDE.md location alongside the
+ * project root, so traversal is impossible by construction.
+ */
+export declare function resolveProjectClaudeMdPath(projectSlug: string): Promise<ResolvedHarnessPath>;
+//# sourceMappingURL=harnessPaths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"harnessPaths.d.ts","sourceRoot":"","sources":["../../src/utils/harnessPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAWrE,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED,wFAAwF;AACxF,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBhF;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwC1F;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAyBlG"}

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

@@ -0,0 +1,124 @@
+/**
+ * Story 28.0.5: Harness workbench path resolver.
+ *
+ * Resolves `~/.claude` (user scope) and `<projectRoot>/.claude` (project scope)
+ * into absolute paths and enforces that any relative path requested by the
+ * caller stays inside the resolved root. Every entry point into `harnessService`
+ * MUST route through `resolveHarnessPath` so that Windows/POSIX separator
+ * mixing, drive letters, UNC paths, and null-byte inputs cannot escape the
+ * subtree.
+ */
+import os from 'os';
+import path from 'path';
+import { projectService } from '../services/projectService.js';
+import { HARNESS_ERRORS } from '@hammoc/shared';
+/**
+ * Test-only dependency-injection hook. When set, `getUserHarnessRoot()` returns
+ * this value instead of `~/.claude`. Production configurations leave it unset
+ * (no effect); unit tests in `harnessPaths.test.ts` / `harnessService.test.ts`
+ * redirect the user scope to a temp directory so they never touch the real
+ * home directory.
+ */
+const HOME_OVERRIDE_ENV = 'HAMMOC_HARNESS_HOME_OVERRIDE';
+/** Return the absolute path to the user-scope harness root (`~/.claude`). */
+export function getUserHarnessRoot() {
+    const override = process.env[HOME_OVERRIDE_ENV];
+    if (override && override.length > 0) {
+        return override;
+    }
+    // Node resolves %USERPROFILE% on Windows and $HOME on POSIX.
+    return path.join(os.homedir(), '.claude');
+}
+/** Return the absolute path to the project-scope harness root (`<project>/.claude`). */
+export async function getProjectHarnessRoot(projectSlug) {
+    if (!projectSlug) {
+        const err = new Error('projectSlug is required for project scope');
+        err.code = HARNESS_ERRORS.HARNESS_ROOT_MISSING.code;
+        throw err;
+    }
+    try {
+        const projectRoot = await projectService.resolveOriginalPath(projectSlug);
+        return path.join(projectRoot, '.claude');
+    }
+    catch (error) {
+        // Any failure to resolve the project (unknown slug, missing index, etc.)
+        // maps to HARNESS_ROOT_MISSING so the controller can return a uniform 404.
+        const wrapped = new Error(`Unable to resolve harness root for project "${projectSlug}": ${error.message}`);
+        wrapped.code = HARNESS_ERRORS.HARNESS_ROOT_MISSING.code;
+        throw wrapped;
+    }
+}
+/**
+ * Resolve a `HarnessPathRef` to an absolute path, guaranteed to sit inside the
+ * resolved root. Throws `HARNESS_PATH_DENIED` for any traversal attempt.
+ */
+export async function resolveHarnessPath(ref) {
+    const rel = ref.relativePath ?? '';
+    // Reject absolute paths and null bytes before touching `path.join`, since
+    // join would otherwise discard the root prefix (POSIX absolute) or let a
+    // null byte slip through to fs APIs.
+    if (rel.includes('\0')) {
+        const err = new Error('null byte in relative path');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    if (path.isAbsolute(rel)) {
+        const err = new Error('absolute path not allowed');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    // UNC inputs (`\\server\share`) on Windows: path.isAbsolute flags some of
+    // these, but on POSIX it would not — reject the prefix defensively.
+    if (rel.startsWith('\\\\') || rel.startsWith('//')) {
+        const err = new Error('UNC path not allowed');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    const resolvedRoot = ref.scope === 'user'
+        ? path.resolve(getUserHarnessRoot())
+        : path.resolve(await getProjectHarnessRoot(ref.projectSlug ?? ''));
+    const absolutePath = path.resolve(resolvedRoot, rel);
+    // Containment check: absolutePath must be the root itself or sit beneath it.
+    // `startsWith(root + sep)` avoids the false match where root="/a" and
+    // absolutePath="/abc".
+    if (absolutePath !== resolvedRoot && !absolutePath.startsWith(resolvedRoot + path.sep)) {
+        const err = new Error('path escapes harness root');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    return { resolvedRoot, absolutePath };
+}
+/**
+ * Story 29.1 (AC6): resolve the project-root `<projectRoot>/CLAUDE.md` path —
+ * the single file in the harness workbench whose location sits OUTSIDE the
+ * project's `.claude/` subtree, so `resolveHarnessPath` would reject it as a
+ * traversal. This helper accepts only `projectSlug` (no caller-supplied
+ * relative path) and returns the canonical CLAUDE.md location alongside the
+ * project root, so traversal is impossible by construction.
+ */
+export async function resolveProjectClaudeMdPath(projectSlug) {
+    if (!projectSlug || projectSlug.includes('\0')) {
+        const err = new Error('invalid projectSlug');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    // Reject traversal-bearing slugs before they reach projectService — defense in depth.
+    if (projectSlug.includes('..') || projectSlug.includes('/') || projectSlug.includes('\\')) {
+        const err = new Error('projectSlug must not contain path separators');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    let projectRoot;
+    try {
+        projectRoot = await projectService.resolveOriginalPath(projectSlug);
+    }
+    catch (error) {
+        const wrapped = new Error(`Unable to resolve project root for "${projectSlug}": ${error.message}`);
+        wrapped.code = HARNESS_ERRORS.HARNESS_ROOT_MISSING.code;
+        throw wrapped;
+    }
+    const resolvedRoot = path.resolve(projectRoot);
+    const absolutePath = path.join(resolvedRoot, 'CLAUDE.md');
+    return { resolvedRoot, absolutePath };
+}
+//# sourceMappingURL=harnessPaths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"harnessPaths.js","sourceRoot":"","sources":["../../src/utils/harnessPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAuB,MAAM,gBAAgB,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,8BAA8B,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB;IAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAChD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,6DAA6D;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,WAAmB;IAC7D,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,2CAA2C,CAA0B,CAAC;QAC5F,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,oBAAoB,CAAC,IAAI,CAAC;QACpD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,cAAc,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,2EAA2E;QAC3E,MAAM,OAAO,GAAG,IAAI,KAAK,CACvB,+CAA+C,WAAW,MAAO,KAAe,CAAC,OAAO,EAAE,CAClE,CAAC;QAC3B,OAAO,CAAC,IAAI,GAAG,cAAc,CAAC,oBAAoB,CAAC,IAAI,CAAC;QACxD,MAAM,OAAO,CAAC;IAChB,CAAC;AACH,CAAC;AAOD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAmB;IAC1D,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;IAEnC,0EAA0E;IAC1E,yEAAyE;IACzE,qCAAqC;IACrC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,4BAA4B,CAA0B,CAAC;QAC7E,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,mBAAmB,CAAC,IAAI,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,2BAA2B,CAA0B,CAAC;QAC5E,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,mBAAmB,CAAC,IAAI,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,0EAA0E;IAC1E,oEAAoE;IACpE,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,sBAAsB,CAA0B,CAAC;QACvE,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,mBAAmB,CAAC,IAAI,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,YAAY,GAAG,GAAG,CAAC,KAAK,KAAK,MAAM;QACvC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;QACpC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,qBAAqB,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC;IAErE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAErD,6EAA6E;IAC7E,sEAAsE;IACtE,uBAAuB;IACvB,IAAI,YAAY,KAAK,YAAY,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvF,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,2BAA2B,CAA0B,CAAC;QAC5E,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,mBAAmB,CAAC,IAAI,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,WAAmB;IAClE,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,qBAAqB,CAA0B,CAAC;QACtE,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,mBAAmB,CAAC,IAAI,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,sFAAsF;IACtF,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1F,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,8CAA8C,CAA0B,CAAC;QAC/F,GAAG,CAAC,IAAI,GAAG,cAAc,CAAC,mBAAmB,CAAC,IAAI,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,MAAM,cAAc,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,IAAI,KAAK,CACvB,uCAAuC,WAAW,MAAO,KAAe,CAAC,OAAO,EAAE,CAC1D,CAAC;QAC3B,OAAO,CAAC,IAAI,GAAG,cAAc,CAAC,oBAAoB,CAAC,IAAI,CAAC;QACxD,MAAM,OAAO,CAAC;IAChB,CAAC;IACD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IAC1D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AACxC,CAAC"}

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

@@ -0,0 +1,72 @@
+/**
+ * Story 30.1 (Task 1): single source of truth for secret-pattern heuristics
+ * used by the harness write paths.
+ *
+ * Replaces four drifted SECRET_PATTERNS definitions (harnessAgentService,
+ * harnessCommandService, harnessHookService, harnessMcpService). Drift
+ * before this module:
+ *
+ *   - agent / command / hook : 32-char base64 unanchored, Bearer unanchored
+ *   - mcp                    : 40-char base64 anchored,   Bearer anchored
+ *
+ * Canonical chosen here (Story 30.1 sub-spike 1.0, option (b)):
+ *   - 32-char base64 unanchored, Bearer unanchored
+ *
+ * Rationale: detection-rate first; Story 30.1 AC4.c provides a per-save
+ * "mark not a secret" opt-out that absorbs false positives, whereas missed
+ * detections silently leak credentials. MCP's stricter anchors were a local
+ * accident, not a deliberate spec decision.
+ *
+ * Two entry points are exposed because the four services walk two distinct
+ * shapes:
+ *
+ *   - detectSecretsInText  → string body (agent / command / hook commands)
+ *                            returns matched line numbers (1-based)
+ *   - detectSecretsInValue → arbitrary JSON-like value (mcp config)
+ *                            returns matched dot-paths
+ *
+ * Both strip `${ENV_VAR}` references first so legitimate env-var indirection
+ * (`Authorization: 'Bearer ${GH_TOKEN}'`) does not raise false positives.
+ */
+export interface SecretPattern {
+    name: string;
+    re: RegExp;
+    /**
+     * Optional minimum Shannon entropy (bits/char) gate for matched substrings.
+     * Story 30.3 spike #2: applies to the loose base64 pattern only. Natural
+     * English compounds (PascalCase identifiers, prose) sit at ~3.5–3.9; real
+     * base64-encoded tokens sit at ≥ 4.0 due to a-z/A-Z/0-9 uniform distribution.
+     * Other patterns keep their anchored prefixes (Bearer/sk-/AKIA/xox-) which
+     * already gate false positives — no entropy check needed.
+     */
+    minEntropy?: number;
+}
+export declare const SECRET_PATTERNS: readonly SecretPattern[];
+export declare const ENV_REF_RE: RegExp;
+/**
+ * Shannon entropy in bits/char of an arbitrary string. Used by patterns that
+ * opt in via `minEntropy` (currently the loose base64 pattern only).
+ */
+export declare function shannonEntropy(s: string): number;
+export interface DetectSecretsTextResult {
+    matched: boolean;
+    patternNames: string[];
+    lines: number[];
+}
+export interface DetectSecretsValueResult {
+    matched: boolean;
+    patternNames: string[];
+    paths: string[];
+}
+/**
+ * Line-based scanner for textual command / prompt bodies (agent system
+ * prompts, slash command bodies, hook command/prompt strings).
+ */
+export declare function detectSecretsInText(text: string): DetectSecretsTextResult;
+/**
+ * Object-walk scanner for JSON-like values (mcp server config). Each string
+ * leaf is evaluated against the canonical patterns; matches are reported as
+ * dot-paths (`env.GITHUB_TOKEN`, `headers.Authorization`, ...).
+ */
+export declare function detectSecretsInValue(value: unknown, basePath?: string[]): DetectSecretsValueResult;
+//# sourceMappingURL=secretHeuristic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secretHeuristic.d.ts","sourceRoot":"","sources":["../../src/utils/secretHeuristic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAMnD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAkC,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAWhD;AAkCD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAQD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,CA0BzE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,EAAO,GACtB,wBAAwB,CAgC1B"}

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

@@ -0,0 +1,163 @@
+/**
+ * Story 30.1 (Task 1): single source of truth for secret-pattern heuristics
+ * used by the harness write paths.
+ *
+ * Replaces four drifted SECRET_PATTERNS definitions (harnessAgentService,
+ * harnessCommandService, harnessHookService, harnessMcpService). Drift
+ * before this module:
+ *
+ *   - agent / command / hook : 32-char base64 unanchored, Bearer unanchored
+ *   - mcp                    : 40-char base64 anchored,   Bearer anchored
+ *
+ * Canonical chosen here (Story 30.1 sub-spike 1.0, option (b)):
+ *   - 32-char base64 unanchored, Bearer unanchored
+ *
+ * Rationale: detection-rate first; Story 30.1 AC4.c provides a per-save
+ * "mark not a secret" opt-out that absorbs false positives, whereas missed
+ * detections silently leak credentials. MCP's stricter anchors were a local
+ * accident, not a deliberate spec decision.
+ *
+ * Two entry points are exposed because the four services walk two distinct
+ * shapes:
+ *
+ *   - detectSecretsInText  → string body (agent / command / hook commands)
+ *                            returns matched line numbers (1-based)
+ *   - detectSecretsInValue → arbitrary JSON-like value (mcp config)
+ *                            returns matched dot-paths
+ *
+ * Both strip `${ENV_VAR}` references first so legitimate env-var indirection
+ * (`Authorization: 'Bearer ${GH_TOKEN}'`) does not raise false positives.
+ */
+export const SECRET_PATTERNS = [
+    { name: 'bearer', re: /Bearer\s+[A-Za-z0-9._-]{16,}/ },
+    { name: 'sk', re: /sk-[A-Za-z0-9]{20,}/ },
+    { name: 'aws', re: /AKIA[0-9A-Z]{16}/ },
+    { name: 'slack', re: /xox[baprs]-[A-Za-z0-9-]{10,}/ },
+    { name: 'base64', re: /[A-Za-z0-9+/=]{32,}/g, minEntropy: 4.0 },
+];
+export const ENV_REF_RE = /\$\{[A-Za-z_][A-Za-z0-9_]*\}/g;
+/**
+ * Shannon entropy in bits/char of an arbitrary string. Used by patterns that
+ * opt in via `minEntropy` (currently the loose base64 pattern only).
+ */
+export function shannonEntropy(s) {
+    if (!s)
+        return 0;
+    const counts = new Map();
+    for (const ch of s)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    const len = s.length;
+    let h = 0;
+    for (const c of counts.values()) {
+        const p = c / len;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+// Story 30.3 spike #2 — the loose base64 pattern adds two combined gates so
+// natural English compounds (e.g. PascalCase identifiers) cannot trigger a
+// false positive:
+//   (i)  Shannon entropy ≥ 4.0 bits/char  — filters single-symbol runs
+//   (ii) ≥ 1 character outside [A-Za-z]   — filters English compounds that
+//        otherwise meet the entropy bar (real base64 of random bytes almost
+//        always contains digits or '+'/'/'/'=' over 32+ chars)
+// Both gates run only for patterns that opt in via `minEntropy`.
+const BASE64_NON_ALPHA_RE = /[0-9+/=]/;
+/**
+ * Tests whether `text` matches a single SecretPattern, applying the optional
+ * `minEntropy` + non-alpha gates to each individual regex match. The pattern's
+ * `re` must be either non-global (single test) or global (per-match gating).
+ */
+function patternMatches(text, pat) {
+    if (pat.minEntropy === undefined) {
+        return pat.re.test(text);
+    }
+    const re = pat.re.global ? pat.re : new RegExp(pat.re.source, pat.re.flags + 'g');
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const s = m[0];
+        if (shannonEntropy(s) >= pat.minEntropy && BASE64_NON_ALPHA_RE.test(s)) {
+            return true;
+        }
+        if (m.index === re.lastIndex)
+            re.lastIndex += 1;
+    }
+    return false;
+}
+function stripEnvRefs(text) {
+    // Reset is required because the regex is /g — but `replace` with a /g regex
+    // re-creates state each call. Still, clone-replace pattern is safest.
+    return text.replace(ENV_REF_RE, '');
+}
+/**
+ * Line-based scanner for textual command / prompt bodies (agent system
+ * prompts, slash command bodies, hook command/prompt strings).
+ */
+export function detectSecretsInText(text) {
+    if (!text || typeof text !== 'string') {
+        return { matched: false, patternNames: [], lines: [] };
+    }
+    const stripped = stripEnvRefs(text);
+    const matchedNames = new Set();
+    for (const pat of SECRET_PATTERNS) {
+        if (patternMatches(stripped, pat)) {
+            matchedNames.add(pat.name);
+        }
+    }
+    if (matchedNames.size === 0) {
+        return { matched: false, patternNames: [], lines: [] };
+    }
+    const lines = [];
+    const split = text.split(/\r?\n/);
+    for (let i = 0; i < split.length; i += 1) {
+        const lineStripped = stripEnvRefs(split[i]);
+        for (const pat of SECRET_PATTERNS) {
+            if (patternMatches(lineStripped, pat)) {
+                lines.push(i + 1);
+                break;
+            }
+        }
+    }
+    return { matched: true, patternNames: Array.from(matchedNames), lines };
+}
+/**
+ * Object-walk scanner for JSON-like values (mcp server config). Each string
+ * leaf is evaluated against the canonical patterns; matches are reported as
+ * dot-paths (`env.GITHUB_TOKEN`, `headers.Authorization`, ...).
+ */
+export function detectSecretsInValue(value, basePath = []) {
+    const paths = [];
+    const matchedNames = new Set();
+    const walk = (v, p) => {
+        if (typeof v === 'string') {
+            const stripped = stripEnvRefs(v);
+            if (!stripped)
+                return;
+            for (const pat of SECRET_PATTERNS) {
+                if (patternMatches(stripped, pat)) {
+                    paths.push(p.join('.'));
+                    matchedNames.add(pat.name);
+                    return;
+                }
+            }
+            return;
+        }
+        if (Array.isArray(v)) {
+            v.forEach((item, i) => walk(item, [...p, String(i)]));
+            return;
+        }
+        if (v && typeof v === 'object') {
+            for (const [k, child] of Object.entries(v)) {
+                walk(child, [...p, k]);
+            }
+        }
+    };
+    walk(value, basePath);
+    return {
+        matched: paths.length > 0,
+        patternNames: Array.from(matchedNames),
+        paths,
+    };
+}
+//# sourceMappingURL=secretHeuristic.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secretHeuristic.js","sourceRoot":"","sources":["../../src/utils/secretHeuristic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAgBH,MAAM,CAAC,MAAM,eAAe,GAA6B;IACvD,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,8BAA8B,EAAE;IACtD,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,qBAAqB,EAAE;IACzC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,kBAAkB,EAAE;IACvC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,8BAA8B,EAAE;IACrD,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,sBAAsB,EAAE,UAAU,EAAE,GAAG,EAAE;CAChE,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,+BAA+B,CAAC;AAE1D;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,EAAE,IAAI,CAAC;QAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC;IACrB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QAClB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,4EAA4E;AAC5E,2EAA2E;AAC3E,kBAAkB;AAClB,uEAAuE;AACvE,2EAA2E;AAC3E,4EAA4E;AAC5E,+DAA+D;AAC/D,iEAAiE;AACjE,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAEvC;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,GAAkB;IACtD,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;IAClF,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;IACjB,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,cAAc,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,SAAS;YAAE,EAAE,CAAC,SAAS,IAAI,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAcD,SAAS,YAAY,CAAC,IAAY;IAChC,4EAA4E;IAC5E,sEAAsE;IACtE,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,IAAI,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;YAClC,IAAI,cAAc,CAAC,YAAY,EAAE,GAAG,CAAC,EAAE,CAAC;gBACtC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBAClB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,WAAqB,EAAE;IAEvB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,IAAI,GAAG,CAAC,CAAU,EAAE,CAAW,EAAQ,EAAE;QAC7C,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,CAAC,QAAQ;gBAAE,OAAO;YACtB,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;gBAClC,IAAI,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;oBAClC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;oBACxB,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBAC3B,OAAO;gBACT,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACtD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC/B,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,EAAE,CAAC;gBACtE,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtB,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC;QACzB,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC;QACtC,KAAK;KACN,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * Story 30.3 (Task 2.1): single source of truth for placeholder ENV names
+ * used when `secretsPolicy === 'placeholder'`.
+ *
+ * The export pipeline walks each domain's payload, calls `detectSecretsInValue`
+ * / `detectSecretsInText` from secretHeuristic.ts to locate every secret, and
+ * for each match asks this module to produce a stable ENV reference name.
+ * The name is what gets written to disk as `${ENV_REF_NAME}` so the importer
+ * can wire it up via environment variables.
+ *
+ * Naming policy (AC2.c):
+ *   - mcp     `env.<KEY>`              → `<UPPER_NAME>_<UPPER_KEY>`
+ *   - mcp     `headers.Authorization`  → `BEARER_TOKEN_<UPPER_NAME>`
+ *   - mcp     other paths              → `<UPPER_NAME>_<UPPER_LAST_PATH_SEG>`
+ *   - hook    `command` / `prompt`     → `HOOK_<EVENT>_TOKEN`
+ *   - command body match               → `COMMAND_<UPPER_SLASH_PATH>_TOKEN`
+ *   - agent   body match               → `AGENT_<UPPER_NAME>_TOKEN`
+ *   - claude-md body match             → `CLAUDE_MD_TOKEN_<INDEX>`
+ *
+ * The names are intentionally not collision-free across multiple secrets in
+ * the same card — the export pipeline appends a numeric suffix when the same
+ * name is already emitted in that bundle (handled by the caller, not here),
+ * so this module stays a pure-function lookup table.
+ */
+import type { BundleItemDomain } from '@hammoc/shared';
+export interface NamePlaceholderInput {
+    /** Card domain — disambiguates the naming rule. */
+    domain: BundleItemDomain;
+    /**
+     * For mcp/hook: the dot-path returned by `detectSecretsInValue` (e.g.
+     * `mcpServers.context7.env.API_KEY`, `mcpServers.gh.headers.Authorization`).
+     * For command/agent/claude-md: an empty string or `body:<line>`.
+     */
+    fieldPath: string;
+    /** Active card name (skill: skillName, mcp: serverName, agent: name, etc.). */
+    cardName: string;
+    /** For hook entries — the matched HarnessHookEvent. */
+    hookEvent?: string;
+}
+export declare function namePlaceholder(input: NamePlaceholderInput): string;
+//# sourceMappingURL=secretPlaceholderNamer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secretPlaceholderNamer.d.ts","sourceRoot":"","sources":["../../src/utils/secretPlaceholderNamer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiBD,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CA4CnE"}

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

@@ -0,0 +1,81 @@
+/**
+ * Story 30.3 (Task 2.1): single source of truth for placeholder ENV names
+ * used when `secretsPolicy === 'placeholder'`.
+ *
+ * The export pipeline walks each domain's payload, calls `detectSecretsInValue`
+ * / `detectSecretsInText` from secretHeuristic.ts to locate every secret, and
+ * for each match asks this module to produce a stable ENV reference name.
+ * The name is what gets written to disk as `${ENV_REF_NAME}` so the importer
+ * can wire it up via environment variables.
+ *
+ * Naming policy (AC2.c):
+ *   - mcp     `env.<KEY>`              → `<UPPER_NAME>_<UPPER_KEY>`
+ *   - mcp     `headers.Authorization`  → `BEARER_TOKEN_<UPPER_NAME>`
+ *   - mcp     other paths              → `<UPPER_NAME>_<UPPER_LAST_PATH_SEG>`
+ *   - hook    `command` / `prompt`     → `HOOK_<EVENT>_TOKEN`
+ *   - command body match               → `COMMAND_<UPPER_SLASH_PATH>_TOKEN`
+ *   - agent   body match               → `AGENT_<UPPER_NAME>_TOKEN`
+ *   - claude-md body match             → `CLAUDE_MD_TOKEN_<INDEX>`
+ *
+ * The names are intentionally not collision-free across multiple secrets in
+ * the same card — the export pipeline appends a numeric suffix when the same
+ * name is already emitted in that bundle (handled by the caller, not here),
+ * so this module stays a pure-function lookup table.
+ */
+const NON_ALNUM_RE = /[^A-Za-z0-9]+/g;
+function toUpperSnake(input) {
+    return input
+        .trim()
+        .replace(NON_ALNUM_RE, '_')
+        .replace(/^_+|_+$/g, '')
+        .toUpperCase();
+}
+function lastPathSegment(fieldPath) {
+    const segments = fieldPath.split('.').filter((s) => s.length > 0);
+    return segments[segments.length - 1] ?? '';
+}
+export function namePlaceholder(input) {
+    const card = toUpperSnake(input.cardName) || 'UNNAMED';
+    switch (input.domain) {
+        case 'mcp': {
+            const fp = input.fieldPath;
+            // Authorization header → BEARER_TOKEN_<CARD>
+            if (/(^|\.)headers\.Authorization$/i.test(fp)) {
+                return `BEARER_TOKEN_${card}`;
+            }
+            // env.<KEY> → <CARD>_<KEY>
+            const envMatch = fp.match(/(^|\.)env\.([^.]+)$/);
+            if (envMatch) {
+                return `${card}_${toUpperSnake(envMatch[2])}`;
+            }
+            // Fallback: last segment
+            const seg = toUpperSnake(lastPathSegment(fp)) || 'SECRET';
+            return `${card}_${seg}`;
+        }
+        case 'hook': {
+            const evt = toUpperSnake(input.hookEvent ?? 'GENERIC');
+            return `HOOK_${evt}_${card}_TOKEN`;
+        }
+        case 'command': {
+            return `COMMAND_${card}_TOKEN`;
+        }
+        case 'agent': {
+            return `AGENT_${card}_TOKEN`;
+        }
+        case 'claude-md': {
+            return `CLAUDE_MD_${card || 'TOKEN'}_${toUpperSnake(input.fieldPath) || 'TOKEN'}`
+                .replace(/_+$/, '');
+        }
+        case 'skill': {
+            return `SKILL_${card}_TOKEN`;
+        }
+        case 'bmad': {
+            return `BMAD_${card}_TOKEN`;
+        }
+        default: {
+            const _exhaustive = input.domain;
+            return _exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=secretPlaceholderNamer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secretPlaceholderNamer.js","sourceRoot":"","sources":["../../src/utils/secretPlaceholderNamer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAmBH,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAEtC,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK;SACT,IAAI,EAAE;SACN,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC;SAC1B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,SAAS,eAAe,CAAC,SAAiB;IACxC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClE,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC;IAEvD,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;QACrB,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;YAC3B,6CAA6C;YAC7C,IAAI,gCAAgC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC9C,OAAO,gBAAgB,IAAI,EAAE,CAAC;YAChC,CAAC;YACD,2BAA2B;YAC3B,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;YACjD,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,CAAC;YACD,yBAAyB;YACzB,MAAM,GAAG,GAAG,YAAY,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,IAAI,QAAQ,CAAC;YAC1D,OAAO,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;QAC1B,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,IAAI,SAAS,CAAC,CAAC;YACvD,OAAO,QAAQ,GAAG,IAAI,IAAI,QAAQ,CAAC;QACrC,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,OAAO,WAAW,IAAI,QAAQ,CAAC;QACjC,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,SAAS,IAAI,QAAQ,CAAC;QAC/B,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,OAAO,aAAa,IAAI,IAAI,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,OAAO,EAAE;iBAC9E,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACxB,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,SAAS,IAAI,QAAQ,CAAC;QAC/B,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,OAAO,QAAQ,IAAI,QAAQ,CAAC;QAC9B,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,KAAK,CAAC,MAAM,CAAC;YACxC,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,29 @@
+/**
+ * Story 30.2 (Task 1.5): server-side PATH resolver for the
+ * `mcp/command-not-on-path` lint rule.
+ *
+ * Mirrors the `which`/`where` + 5s timeout pattern used by
+ * serverController.ts:14-31 for npm path resolution. Absolute paths skip the
+ * shell call entirely and fall through to a simple `fs.existsSync` check —
+ * faster and avoids spurious `which: not found` lines on stderr for inputs
+ * that obviously don't need PATH resolution.
+ *
+ * The result is intentionally shaped as `{ resolved: string | null }` (not a
+ * boolean) so the caller can surface the resolved absolute path in tooltips
+ * without re-running the lookup.
+ */
+export interface ResolveCommandResult {
+    resolved: string | null;
+}
+/**
+ * Resolve `cmd` against the current process PATH.
+ *
+ * - Absolute path → `fs.existsSync` only (no shell).
+ * - Relative path containing a separator → resolved relative to `cwd`
+ *   (uncommon for MCP `command` fields but covered for completeness).
+ * - Bare name → `where.exe` on Windows / `which` elsewhere.
+ *
+ * Never throws — failures collapse to `{ resolved: null }`.
+ */
+export declare function resolveCommandOnServerPath(cmd: string): ResolveCommandResult;
+//# sourceMappingURL=serverPathResolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serverPathResolver.d.ts","sourceRoot":"","sources":["../../src/utils/serverPathResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAID;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CA8B5E"}

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

@@ -0,0 +1,59 @@
+/**
+ * Story 30.2 (Task 1.5): server-side PATH resolver for the
+ * `mcp/command-not-on-path` lint rule.
+ *
+ * Mirrors the `which`/`where` + 5s timeout pattern used by
+ * serverController.ts:14-31 for npm path resolution. Absolute paths skip the
+ * shell call entirely and fall through to a simple `fs.existsSync` check —
+ * faster and avoids spurious `which: not found` lines on stderr for inputs
+ * that obviously don't need PATH resolution.
+ *
+ * The result is intentionally shaped as `{ resolved: string | null }` (not a
+ * boolean) so the caller can surface the resolved absolute path in tooltips
+ * without re-running the lookup.
+ */
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+const RESOLVE_TIMEOUT_MS = 5000;
+/**
+ * Resolve `cmd` against the current process PATH.
+ *
+ * - Absolute path → `fs.existsSync` only (no shell).
+ * - Relative path containing a separator → resolved relative to `cwd`
+ *   (uncommon for MCP `command` fields but covered for completeness).
+ * - Bare name → `where.exe` on Windows / `which` elsewhere.
+ *
+ * Never throws — failures collapse to `{ resolved: null }`.
+ */
+export function resolveCommandOnServerPath(cmd) {
+    if (!cmd || typeof cmd !== 'string')
+        return { resolved: null };
+    const trimmed = cmd.trim();
+    if (!trimmed)
+        return { resolved: null };
+    if (path.isAbsolute(trimmed)) {
+        return { resolved: fs.existsSync(trimmed) ? trimmed : null };
+    }
+    // Path with a separator (e.g. "./bin/foo" or "scripts/run.sh") — resolve
+    // against cwd. Server PATH is irrelevant in this case.
+    if (trimmed.includes('/') || trimmed.includes('\\')) {
+        const abs = path.resolve(process.cwd(), trimmed);
+        return { resolved: fs.existsSync(abs) ? abs : null };
+    }
+    const finder = process.platform === 'win32' ? 'where.exe' : 'which';
+    try {
+        const stdout = execFileSync(finder, [trimmed], {
+            encoding: 'utf-8',
+            timeout: RESOLVE_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const first = stdout.trim().split(/\r?\n/)[0]?.trim();
+        return { resolved: first ? first : null };
+    }
+    catch {
+        // Non-zero exit (not found) or timeout — both surface as "unresolved".
+        return { resolved: null };
+    }
+}
+//# sourceMappingURL=serverPathResolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serverPathResolver.js","sourceRoot":"","sources":["../../src/utils/serverPathResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAMxB,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAE/D,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAExC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/D,CAAC;IAED,yEAAyE;IACzE,uDAAuD;IACvD,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;QACjD,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC;IACpE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE;YAC7C,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,kBAAkB;YAC3B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACtD,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC"}