@stackwright-pro/mcp 0.2.0-alpha.4 → 0.2.0-alpha.48

package/LICENSE

@@ -0,0 +1,21 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 Per Aspera LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Per Aspera LLC ("Company").
+
+RESTRICTIONS: You may not use, copy, modify, merge, publish, distribute,
+sublicense, sell, or otherwise exploit this Software or any portion thereof
+without the express prior written consent of the Company.
+
+GOVERNMENT USE: Use, duplication, or disclosure by the U.S. Government is
+subject to restrictions as set forth in FAR 52.227-19 (Commercial Computer
+Software - Restricted Rights) and DFARS 252.227-7013 (Rights in Technical
+Data and Computer Software), as applicable.
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+For licensing inquiries: legal@peraspera.com

package/README.md

@@ -0,0 +1,236 @@
+# @stackwright-pro/mcp
+
+The MCP server that powers the Pro Otter Raft. Exposes 30 deterministic TypeScript tools to Claude Code and other MCP clients for structured pipeline orchestration, artifact validation, and controlled file I/O.
+
+---
+
+## Architecture: Sinks Not Pipes
+
+When the Otter Raft scaled past nine concurrent agents, the foreman's context window became the bottleneck. Every specialist was shovelling its output back into the conversation, bloating the shared context until the whole raft flipped. Coordination collapsed: later otters couldn't reliably read what earlier otters had produced, and the foreman had no authoritative record of what was actually done versus what was merely narrated.
+
+The fix is a single discipline: **every intermediate result is a file on disk; MCP tools are the only I/O interface**. Otters never write anything directly — they call a tool, the tool validates and writes, and the next otter reads via another tool. The foreman never accumulates state in memory; it reads the current truth from disk on every step. This makes the pipeline inspectable, resumable, and safe to parallelize — because there is nothing to lose when a context window expires.
+
+```
+.stackwright/
+├── init-context.json          ← launcher writes once
+├── pipeline-state.json        ← set_pipeline_state
+├── questions/{phase}.json     ← write_phase_questions
+├── answers/{phase}.json       ← save_phase_answers
+└── artifacts/{output}.json    ← validate_artifact (the chokepoint)
+```
+
+---
+
+## Tools Reference
+
+### Pipeline State & Control
+
+Sourced from `registerPipelineTools` (`tools/pipeline.ts`).
+
+| Tool                                    | Purpose                                        | Reads                              | Writes                             |
+| --------------------------------------- | ---------------------------------------------- | ---------------------------------- | ---------------------------------- |
+| `stackwright_pro_get_pipeline_state`    | Read current pipeline state                    | `.stackwright/pipeline-state.json` | —                                  |
+| `stackwright_pro_set_pipeline_state`    | Update phase field or top-level status         | `.stackwright/pipeline-state.json` | `.stackwright/pipeline-state.json` |
+| `stackwright_pro_check_execution_ready` | Gate: true only when all 8 phases have answers | `.stackwright/answers/`            | —                                  |
+| `stackwright_pro_list_artifacts`        | Inventory of completed specialist outputs      | `.stackwright/artifacts/`          | —                                  |
+
+---
+
+### Question Collection
+
+Sourced from `registerPipelineTools` (`tools/pipeline.ts`), `registerQuestionTools` (`tools/questions.ts`), and `registerOrchestrationTools` (`tools/orchestration.ts`).
+
+| Tool                                      | Purpose                                                          | Reads                                 | Writes                                |
+| ----------------------------------------- | ---------------------------------------------------------------- | ------------------------------------- | ------------------------------------- |
+| `stackwright_pro_write_phase_questions`   | Parse otter `QUESTION_COLLECTION_MODE` response and sink to disk | —                                     | `.stackwright/questions/{phase}.json` |
+| `stackwright_pro_present_phase_questions` | Adapt questions for `ask_user_question` format                   | `.stackwright/questions/{phase}.json` | —                                     |
+| `stackwright_pro_save_phase_answers`      | Sink user answers to disk                                        | —                                     | `.stackwright/answers/{phase}.json`   |
+| `stackwright_pro_read_phase_answers`      | Read answers for a phase                                         | `.stackwright/answers/{phase}.json`   | —                                     |
+
+---
+
+### Specialist Execution
+
+Sourced from `registerPipelineTools` (`tools/pipeline.ts`) and `registerOrchestrationTools` (`tools/orchestration.ts`).
+
+| Tool                                      | Purpose                                                       | Reads                                         | Writes                                |
+| ----------------------------------------- | ------------------------------------------------------------- | --------------------------------------------- | ------------------------------------- |
+| `stackwright_pro_build_specialist_prompt` | Assemble answers + upstream artifacts into specialist prompt  | `answers/{phase}.json`, upstream `artifacts/` | —                                     |
+| `stackwright_pro_validate_artifact`       | Validate specialist output, detect off-script, write if valid | —                                             | `.stackwright/artifacts/{phase}.json` |
+| `stackwright_pro_get_otter_name`          | Resolve phase name → otter agent name                         | —                                             | —                                     |
+| `stackwright_pro_parse_otter_response`    | Extract JSON from otter response text                         | —                                             | —                                     |
+| `stackwright_pro_save_manifest`           | Write consolidated question manifest (legacy path)            | —                                             | `.stackwright/question-manifest.json` |
+
+---
+
+### Controlled File I/O
+
+Sourced from `registerSafeWriteTools` (`tools/safe-write.ts`).
+
+| Tool                         | Purpose                                                                             | Reads | Writes                 |
+| ---------------------------- | ----------------------------------------------------------------------------------- | ----- | ---------------------- |
+| `stackwright_pro_safe_write` | Per-otter path allowlist enforcement — the only way specialists write content files | —     | Allowlisted paths only |
+
+---
+
+### Domain Knowledge
+
+Sourced from `registerDomainTools` (`tools/domain.ts`).
+
+| Tool                                    | Purpose                                         | Reads                                                         | Writes |
+| --------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- | ------ |
+| `stackwright_pro_list_collections`      | List API-backed collections for page generation | `.stackwright/artifacts/data-config.json` → `stackwright.yml` | —      |
+| `stackwright_pro_resolve_data_strategy` | Deterministic data freshness strategy lookup    | —                                                             | —      |
+| `stackwright_pro_validate_workflow`     | Validate workflow.yml graph structure           | `.stackwright/artifacts/workflow-config.json`                 | —      |
+
+---
+
+### Integrity
+
+Sourced from `registerIntegrityTools` (`integrity.ts`).
+
+| Tool                                     | Purpose                                                         | Reads                              | Writes |
+| ---------------------------------------- | --------------------------------------------------------------- | ---------------------------------- | ------ |
+| `stackwright_pro_verify_otter_integrity` | SHA-256 certificate-pinned verification of all otter JSON files | `packages/otters/src/*-otter.json` | —      |
+
+---
+
+### Data Explorer
+
+Sourced from `registerDataExplorerTools` (`tools/data-explorer.ts`).
+
+| Tool                              | Purpose                             |
+| --------------------------------- | ----------------------------------- |
+| `stackwright_pro_list_entities`   | List API entities from OpenAPI spec |
+| `stackwright_pro_generate_filter` | Generate endpoint filter config     |
+
+---
+
+### Security
+
+Sourced from `registerSecurityTools` (`tools/security.ts`).
+
+| Tool                                  | Purpose                                     |
+| ------------------------------------- | ------------------------------------------- |
+| `stackwright_pro_validate_spec`       | Validate OpenAPI spec against approved list |
+| `stackwright_pro_add_approved_spec`   | Add spec to approved list                   |
+| `stackwright_pro_list_approved_specs` | List approved specs                         |
+
+---
+
+### ISR Configuration
+
+Sourced from `registerIsrTools` (`tools/isr.ts`).
+
+| Tool                                  | Purpose                                |
+| ------------------------------------- | -------------------------------------- |
+| `stackwright_pro_configure_isr`       | Configure ISR for a single collection  |
+| `stackwright_pro_configure_isr_batch` | Configure ISR for multiple collections |
+
+---
+
+### Auth
+
+Sourced from `registerAuthTools` (`tools/auth.ts`).
+
+| Tool                             | Purpose                                       |
+| -------------------------------- | --------------------------------------------- |
+| `stackwright_pro_configure_auth` | Generate auth middleware from provider config |
+
+---
+
+### Clarification
+
+Sourced from `registerClarificationTools` (`tools/clarification.ts`).
+
+| Tool                              | Purpose                                |
+| --------------------------------- | -------------------------------------- |
+| `stackwright_pro_clarify`         | Surface mid-execution question to user |
+| `stackwright_pro_detect_conflict` | Detect conflicting user preferences    |
+
+---
+
+### Packages
+
+Sourced from `registerPackageTools` (`tools/packages.ts`).
+
+| Tool                             | Purpose                        |
+| -------------------------------- | ------------------------------ |
+| `stackwright_pro_setup_packages` | Bootstrap Pro npm dependencies |
+
+---
+
+### Dashboard Generation
+
+Sourced from `registerDashboardTools` (`tools/dashboard.ts`).
+
+| Tool                                   | Purpose                      |
+| -------------------------------------- | ---------------------------- |
+| `stackwright_pro_generate_dashboard`   | Generate dashboard page spec |
+| `stackwright_pro_generate_detail_page` | Generate detail page spec    |
+
+---
+
+## Security Model
+
+Three layers keep the raft from sinking:
+
+1. **Per-otter path allowlists** — `stackwright_pro_safe_write` enforces that each specialist otter can only write to approved paths. `page-otter` is limited to `pages/*/content.yml`; `auth-otter` is limited to `config/*.yml` and `.env*`. Attempts to write outside the allowlist are rejected with an error — the otter never touches the filesystem directly.
+
+2. **Artifact validation chokepoint** — specialists never write artifacts directly. All specialist output flows through `stackwright_pro_validate_artifact`, which validates the JSON structure and detects off-script code output (e.g. raw TypeScript or markdown smuggled inside a JSON field) before the file is committed. Bad output is rejected and the phase stays incomplete.
+
+3. **Certificate-pinned integrity** — canonical SHA-256 checksums for all otter JSON prompt files are hardcoded inside this MCP package. `stackwright_pro_verify_otter_integrity` re-hashes every file in `packages/otters/src/*-otter.json` at runtime and compares against the pinned values. A modified or tampered otter file is rejected before its prompt ever reaches an LLM.
+
+---
+
+## Phase Dependency Graph
+
+The pipeline enforces this dependency order. A phase cannot begin specialist execution until all of its upstream phases have committed artifacts.
+
+```
+designer ──────────────────────────────┐
+api ────────────────────────────────┐  │
+auth ───────────────────────────┐   │  │
+                                │   │  │
+data    ← api                   │   │  │
+theme   ← designer              │   │  │
+pages   ← designer, theme, api, data, auth
+dashboard ← designer, theme, api, data
+workflow  ← auth
+```
+
+---
+
+## Integrity
+
+The full integrity enforcement model is documented in [docs/INTEGRITY_MODEL.md](docs/INTEGRITY_MODEL.md), including certificate pinning at startup, known enforcement gaps, and the threat model table for each pipeline component.
+
+```bash
+# The MCP server is configured automatically by the launcher
+npx @stackwright-pro/launch-stackwright-pro
+
+# Or manually in claude_desktop_config.json / .mcp.json:
+{
+  "mcpServers": {
+    "stackwright-pro": {
+      "command": "node",
+      "args": ["node_modules/@stackwright-pro/mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+---
+
+## Development
+
+```bash
+pnpm --filter @stackwright-pro/mcp test
+pnpm --filter @stackwright-pro/mcp build
+```
+
+---
+
+## License
+
+Proprietary — Per Aspera LLC

package/dist/integrity.d.mts

@@ -0,0 +1,60 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/** Compute the hex-encoded SHA-256 digest of raw bytes. Pure, no I/O. */
+declare function computeSha256(data: Buffer): string;
+interface VerifyOtterFileResult {
+    verified: boolean;
+    filename: string;
+    error?: string;
+}
+/**
+ * Read a single otter JSON file, check its size, compute its SHA-256,
+ * and constant-time compare against the canonical checksum.
+ *
+ * Single read → hash → decode. No TOCTOU window.
+ */
+declare function verifyOtterFile(filePath: string): VerifyOtterFileResult;
+interface VerifyAllOttersResult {
+    verified: string[];
+    failed: Array<{
+        filename: string;
+        error: string;
+    }>;
+    unknown: string[];
+}
+/**
+ * Scan a directory for `*-otter.json` files, verify each one against
+ * canonical checksums. Returns lists of verified, failed, and unknown files.
+ */
+declare function verifyAllOtters(otterDir: string): VerifyAllOttersResult;
+/**
+ * Structured audit event parameters for an integrity failure.
+ * Kept as a plain interface so callers can pass partial results without
+ * constructing the full VerifyAllOttersResult.
+ */
+interface IntegrityAuditEvent {
+    otterDir: string;
+    failed: Array<{
+        filename: string;
+        error: string;
+    }>;
+    unknown: string[];
+}
+/**
+ * Emit a structured INTEGRITY_FAIL audit event to stderr.
+ *
+ * Writes a single line to process.stderr in the format:
+ *   INTEGRITY_FAIL {"level":"AUDIT","event":"INTEGRITY_FAIL",...}
+ *
+ * The line prefix "INTEGRITY_FAIL" (without JSON) allows log shippers
+ * (FluentBit, syslog, CloudWatch Logs, Splunk) to match and route the
+ * event to a dedicated audit stream using a simple string filter, even
+ * before attempting JSON parsing.
+ *
+ * Exported for unit testing. Do not call directly in production code —
+ * use registerIntegrityTools() which calls this automatically.
+ */
+declare function emitIntegrityAuditEvent(params: IntegrityAuditEvent): void;
+declare function registerIntegrityTools(server: McpServer): void;
+
+export { type IntegrityAuditEvent, type VerifyAllOttersResult, type VerifyOtterFileResult, computeSha256, emitIntegrityAuditEvent, registerIntegrityTools, verifyAllOtters, verifyOtterFile };

package/dist/integrity.d.ts

@@ -0,0 +1,60 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/** Compute the hex-encoded SHA-256 digest of raw bytes. Pure, no I/O. */
+declare function computeSha256(data: Buffer): string;
+interface VerifyOtterFileResult {
+    verified: boolean;
+    filename: string;
+    error?: string;
+}
+/**
+ * Read a single otter JSON file, check its size, compute its SHA-256,
+ * and constant-time compare against the canonical checksum.
+ *
+ * Single read → hash → decode. No TOCTOU window.
+ */
+declare function verifyOtterFile(filePath: string): VerifyOtterFileResult;
+interface VerifyAllOttersResult {
+    verified: string[];
+    failed: Array<{
+        filename: string;
+        error: string;
+    }>;
+    unknown: string[];
+}
+/**
+ * Scan a directory for `*-otter.json` files, verify each one against
+ * canonical checksums. Returns lists of verified, failed, and unknown files.
+ */
+declare function verifyAllOtters(otterDir: string): VerifyAllOttersResult;
+/**
+ * Structured audit event parameters for an integrity failure.
+ * Kept as a plain interface so callers can pass partial results without
+ * constructing the full VerifyAllOttersResult.
+ */
+interface IntegrityAuditEvent {
+    otterDir: string;
+    failed: Array<{
+        filename: string;
+        error: string;
+    }>;
+    unknown: string[];
+}
+/**
+ * Emit a structured INTEGRITY_FAIL audit event to stderr.
+ *
+ * Writes a single line to process.stderr in the format:
+ *   INTEGRITY_FAIL {"level":"AUDIT","event":"INTEGRITY_FAIL",...}
+ *
+ * The line prefix "INTEGRITY_FAIL" (without JSON) allows log shippers
+ * (FluentBit, syslog, CloudWatch Logs, Splunk) to match and route the
+ * event to a dedicated audit stream using a simple string filter, even
+ * before attempting JSON parsing.
+ *
+ * Exported for unit testing. Do not call directly in production code —
+ * use registerIntegrityTools() which calls this automatically.
+ */
+declare function emitIntegrityAuditEvent(params: IntegrityAuditEvent): void;
+declare function registerIntegrityTools(server: McpServer): void;
+
+export { type IntegrityAuditEvent, type VerifyAllOttersResult, type VerifyOtterFileResult, computeSha256, emitIntegrityAuditEvent, registerIntegrityTools, verifyAllOtters, verifyOtterFile };

package/dist/integrity.js

@@ -0,0 +1,290 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/integrity.ts
+var integrity_exports = {};
+__export(integrity_exports, {
+  computeSha256: () => computeSha256,
+  emitIntegrityAuditEvent: () => emitIntegrityAuditEvent,
+  registerIntegrityTools: () => registerIntegrityTools,
+  verifyAllOtters: () => verifyAllOtters,
+  verifyOtterFile: () => verifyOtterFile
+});
+module.exports = __toCommonJS(integrity_exports);
+var import_crypto = require("crypto");
+var import_fs = require("fs");
+var import_path = require("path");
+var _checksums = /* @__PURE__ */ new Map([
+  [
+    "stackwright-pro-api-otter.json",
+    "ed667124af3f025e090c0e65d0a86f0ef08fea06c0029b8fd0edf6df33df9f9c"
+  ],
+  [
+    "stackwright-pro-auth-otter.json",
+    "b5e901262d7b3f26ef390f1d3c9aadfa68376c05f5057edc241eb37b32b40afd"
+  ],
+  [
+    "stackwright-pro-dashboard-otter.json",
+    "5e930b4092b9002e3c1a413b36418e49c865199af12a546890ccf7f9e56a5593"
+  ],
+  [
+    "stackwright-pro-data-otter.json",
+    "04b07f982f73a2904a1d92c6af3c58ecc132b474c57cab3eaec8566d718d2623"
+  ],
+  [
+    "stackwright-pro-designer-otter.json",
+    "e80d4e7bab87d8647debadb238a58aac498ec5074ff25b21abd3b13ff778bf71"
+  ],
+  [
+    "stackwright-pro-foreman-otter.json",
+    "02dd2485562361f2f3cfd998981349020d7599dcd2d969bb022f9f6d537f3517"
+  ],
+  [
+    "stackwright-pro-page-otter.json",
+    "d672dc4dfd6a3b6d66c6cec93c8db6075dcd4c8f1e8d15e2704aca2fca6856a6"
+  ],
+  [
+    "stackwright-pro-theme-otter.json",
+    "d3a15871b71a466c12c4711fe37cbb018c768cb99eff15c40dbbc7061d4e966b"
+  ],
+  [
+    "stackwright-pro-workflow-otter.json",
+    "2ce1bcbb5c45dbb214499ea08c7175f8b743b51b8cb2ad539faf7df11edcf88a"
+  ]
+]);
+Object.freeze(_checksums);
+var CANONICAL_CHECKSUMS = _checksums;
+var SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+for (const [name, digest] of CANONICAL_CHECKSUMS) {
+  if (!SHA256_HEX_RE.test(digest)) {
+    throw new Error(
+      `Malformed SHA-256 in CANONICAL_CHECKSUMS for "${name}": expected 64 hex chars, got ${digest.length}: "${digest}"`
+    );
+  }
+}
+var MAX_OTTER_BYTES = 1 * 1024 * 1024;
+function computeSha256(data) {
+  return (0, import_crypto.createHash)("sha256").update(data).digest("hex");
+}
+function safeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  return (0, import_crypto.timingSafeEqual)(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+function verifyOtterFile(filePath) {
+  const filename = (0, import_path.basename)(filePath);
+  const expected = CANONICAL_CHECKSUMS.get(filename);
+  if (expected === void 0) {
+    return { verified: false, filename, error: `Unknown otter file: not in canonical set` };
+  }
+  let stat;
+  try {
+    stat = (0, import_fs.lstatSync)(filePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { verified: false, filename, error: `Cannot stat file: ${msg}` };
+  }
+  if (stat.isSymbolicLink()) {
+    return { verified: false, filename, error: "Refusing to verify symlink" };
+  }
+  const size = stat.size;
+  if (size > MAX_OTTER_BYTES) {
+    return {
+      verified: false,
+      filename,
+      error: `File exceeds size limit (${MAX_OTTER_BYTES.toLocaleString()} bytes, got ${size.toLocaleString()})`
+    };
+  }
+  let raw;
+  try {
+    raw = (0, import_fs.readFileSync)(filePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { verified: false, filename, error: `Cannot read file: ${msg}` };
+  }
+  if (raw.length > MAX_OTTER_BYTES) {
+    return {
+      verified: false,
+      filename,
+      error: `File exceeds size limit after read (${MAX_OTTER_BYTES.toLocaleString()} bytes, got ${raw.length.toLocaleString()})`
+    };
+  }
+  const actual = computeSha256(raw);
+  if (!safeEqual(actual, expected)) {
+    return {
+      verified: false,
+      filename,
+      error: `SHA-256 mismatch: expected ${expected.substring(0, 8)}\u2026, got ${actual.substring(0, 8)}\u2026`
+    };
+  }
+  try {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    decoder.decode(raw);
+  } catch {
+    return {
+      verified: false,
+      filename,
+      error: "File is not valid UTF-8 \u2014 may be corrupted or contain binary injection"
+    };
+  }
+  return { verified: true, filename };
+}
+function verifyAllOtters(otterDir) {
+  if (/(?:^|[/\\])\.\.(?:[/\\]|$)/.test(otterDir) || otterDir.includes("..")) {
+    return {
+      verified: [],
+      failed: [
+        {
+          filename: "<directory>",
+          error: `Security: path traversal sequence detected in otter directory parameter`
+        }
+      ],
+      unknown: []
+    };
+  }
+  const verified = [];
+  const failed = [];
+  const unknown = [];
+  let entries;
+  try {
+    entries = (0, import_fs.readdirSync)(otterDir);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      verified: [],
+      failed: [{ filename: "<directory>", error: `Cannot read directory: ${msg}` }],
+      unknown: []
+    };
+  }
+  const otterFiles = entries.filter((f) => f.endsWith("-otter.json"));
+  for (const filename of otterFiles) {
+    const filePath = (0, import_path.join)(otterDir, filename);
+    try {
+      if ((0, import_fs.lstatSync)(filePath).isSymbolicLink()) {
+        failed.push({ filename, error: "Skipped: symlink" });
+        continue;
+      }
+    } catch {
+    }
+    const result = verifyOtterFile(filePath);
+    if (result.verified) {
+      verified.push(result.filename);
+    } else if (result.error?.startsWith("Unknown otter file")) {
+      unknown.push(result.filename);
+    } else {
+      failed.push({ filename: result.filename, error: result.error ?? "Unknown error" });
+    }
+  }
+  for (const canonicalName of CANONICAL_CHECKSUMS.keys()) {
+    if (!otterFiles.includes(canonicalName)) {
+      failed.push({ filename: canonicalName, error: "Missing from directory" });
+    }
+  }
+  return { verified, failed, unknown };
+}
+var DEFAULT_SEARCH_PATHS = ["node_modules/@stackwright-pro/otters/src/", "packages/otters/src/"];
+function resolveOtterDir() {
+  const cwd = process.cwd();
+  for (const relative of DEFAULT_SEARCH_PATHS) {
+    const candidate = (0, import_path.join)(cwd, relative);
+    try {
+      (0, import_fs.lstatSync)(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+function emitIntegrityAuditEvent(params) {
+  const record = JSON.stringify({
+    level: "AUDIT",
+    event: "INTEGRITY_FAIL",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    source: "stackwright_pro_verify_otter_integrity",
+    otterDir: params.otterDir,
+    failedCount: params.failed.length,
+    unknownCount: params.unknown.length,
+    failures: params.failed,
+    unknown: params.unknown
+  });
+  process.stderr.write(`INTEGRITY_FAIL ${record}
+`);
+}
+function registerIntegrityTools(server) {
+  server.tool(
+    "stackwright_pro_verify_otter_integrity",
+    "Verify SHA-256 integrity of all Pro otter agent definitions. Call this at startup before discovering otters. Auto-discovers the otter directory from known paths. Returns verified/failed/unknown lists.",
+    {},
+    async () => {
+      const resolved = resolveOtterDir();
+      if (!resolved) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: true,
+                message: "Could not locate otter directory. Searched: " + DEFAULT_SEARCH_PATHS.join(", ")
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const result = verifyAllOtters(resolved);
+      const allGood = result.failed.length === 0 && result.unknown.length === 0;
+      if (!allGood) {
+        emitIntegrityAuditEvent({
+          otterDir: resolved,
+          failed: result.failed,
+          unknown: result.unknown
+        });
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              otterDir: resolved,
+              totalCanonical: CANONICAL_CHECKSUMS.size,
+              verifiedCount: result.verified.length,
+              failedCount: result.failed.length,
+              unknownCount: result.unknown.length,
+              verified: result.verified,
+              failed: result.failed,
+              unknown: result.unknown,
+              ...allGood ? {} : {
+                error: "INTEGRITY CHECK FAILED: SHA-256 mismatch detected in otter agent definitions. Do not proceed \u2014 otter files may have been tampered with."
+              }
+            })
+          }
+        ],
+        isError: !allGood
+      };
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  computeSha256,
+  emitIntegrityAuditEvent,
+  registerIntegrityTools,
+  verifyAllOtters,
+  verifyOtterFile
+});
+//# sourceMappingURL=integrity.js.map