@downatthebottomofthemolehole/terraform-best-practices-mcp-server 0.1.0 → 2.1.3

package/README.md

@@ -1,26 +1,327 @@
-# terraform-best-practices-mcp
+# Terraform Best Practices MCP Server
 
-An MCP server that helps teams produce better Terraform by combining:
+<!-- mcp-name: io.github.DownAtTheBottomOfTheMoleHole/terraform-best-practices -->
 
-- CLI analysis: `tflint`, `checkov`, `trivy`, `kics`, `infracost`
-- Best-practice retrieval from `terraform-best-practices.com`
-- Cloud provider guidance for `azure`, `aws`, and `gcp`
-- Terraform Registry guidance for providers/resources/modules
+[![CI/Publish](https://github.com/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp/actions/workflows/publish-mcp.yml/badge.svg)](https://github.com/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp/actions/workflows/publish-mcp.yml)
+[![Coverage](https://codecov.io/github/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp/graph/badge.svg?branch=main)](https://codecov.io/github/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp)
+[![npm](https://img.shields.io/npm/v/@downatthebottomofthemolehole/terraform-best-practices-mcp-server.svg)](https://registry.npmjs.org/@downatthebottomofthemolehole/terraform-best-practices-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D24.14.0-brightgreen)](https://nodejs.org/)
 
-## Tool Catalog
+> **Note:** This is a community-maintained MCP server. It is not an official Model Context Protocol server from HashiCorp or any cloud provider.
 
-- `run_tflint`
-- `run_checkov`
-- `run_trivy`
-- `run_kics`
-- `run_infracost`
-- `fetch_terraform_best_practices`
-- `fetch_provider_best_practices`
-- `fetch_terraform_registry_guidance`
+A Model Context Protocol (MCP) server for producing better Terraform through CLI analysis (`tflint`, `checkov`, `trivy`, `kics`, `infracost`), best-practice guidance from [terraform-best-practices.com](https://www.terraform-best-practices.com/), cloud provider recommendations (Azure, AWS, GCP), and Terraform Registry resource and module guidance.
 
-## Prerequisites
+## Overview
 
-- Node.js 24+
+This server provides eighteen MCP tools across CLI analysis, best-practice retrieval, and interactive reporting workflows:
+
+- `run_tflint` to lint Terraform code.
+- `run_checkov` to run security and compliance scanning.
+- `run_trivy` to scan Terraform configuration for vulnerabilities.
+- `run_kics` to run IaC security and compliance scanning.
+- `run_infracost` to estimate cloud costs.
+- `fetch_terraform_best_practices` to retrieve curated Terraform best practices.
+- `fetch_provider_best_practices` to retrieve cloud provider Terraform guidance.
+- `fetch_terraform_registry_guidance` to retrieve Terraform Registry resource and module guidance.
+- `analyze_terraform_code` to analyze code structure, modularity, and best practices.
+- `analyze_terraform_performance` to identify runtime and performance bottlenecks.
+- `analyze_state_management` to assess backend state strategy and collaboration safety.
+- `generate_cost_report` to generate cost analysis with optimization suggestions.
+- `generate_terraform_module_docs` to produce module documentation from Terraform code.
+- `recommend_terraform_modules` to recommend reusable modules from detected patterns.
+- `suggest_terraform_architecture` to suggest multi-environment and multi-region patterns.
+- `suggest_terraform_testing_strategy` to recommend CI-driven testing by risk profile.
+- `suggest_security_hardening` to provide security hardening recommendations.
+- `generate_compliance_summary` to create compliance reports from scan outputs.
+
+### Platform Compatibility
+
+This MCP server is platform-agnostic and works in local and CI environments:
+
+- Local development
+- GitHub Actions
+- GitLab CI/CD
+- Azure DevOps
+- CircleCI, Jenkins, and Bitbucket Pipelines
+- AI Agents and Copilot workflows
+
+The primary requirements are Node.js and optionally the CLI tools on `PATH`. If a CLI is missing, the server returns installation guidance instead of failing silently.
+
+### Tool Matrix
+
+| Tool | Category | Typical outcome |
+| --- | --- | --- |
+| `run_tflint` | CLI Analysis | Lint findings for Terraform code |
+| `run_checkov` | CLI Analysis | Security and compliance scan results |
+| `run_trivy` | CLI Analysis | Vulnerability scan results for IaC |
+| `run_kics` | CLI Analysis | IaC security findings |
+| `run_infracost` | CLI Analysis | Monthly cost baseline for current IaC |
+| `fetch_terraform_best_practices` | Guidance | Curated best-practice checklist from terraform-best-practices.com |
+| `fetch_provider_best_practices` | Guidance | Cloud provider (Azure/AWS/GCP) Terraform recommendations |
+| `fetch_terraform_registry_guidance` | Guidance | Registry guidance for providers, resources, and modules |
+| `analyze_terraform_code` | Analysis | Code structure and modularity assessment |
+| `analyze_terraform_performance` | Analysis | Performance bottleneck and optimization report |
+| `analyze_state_management` | Analysis | State backend strategy and collaboration safety review |
+| `generate_cost_report` | Reporting | Cost analysis with optimization suggestions |
+| `generate_terraform_module_docs` | Reporting | Generated module documentation markdown |
+| `recommend_terraform_modules` | Reporting | Reusable module recommendations from code patterns |
+| `suggest_terraform_architecture` | Architecture | Multi-environment and multi-region architecture patterns |
+| `suggest_terraform_testing_strategy` | Testing | CI-driven testing strategy by risk profile |
+| `suggest_security_hardening` | Security | Security hardening recommendations from scan output |
+| `generate_compliance_summary` | Compliance | Compliance report from scan outputs |
+
+## Tools
+
+### `run_tflint`
+
+Run tflint against a Terraform project directory.
+
+Inputs:
+
+- `path` (string, optional): Terraform project path to scan. Default: `.`.
+- `extraArgs` (string[], optional): Extra CLI arguments.
+- `timeoutMs` (integer, optional): Command timeout in milliseconds.
+
+### `run_checkov`
+
+Run checkov over a Terraform directory.
+
+Inputs:
+
+- `path` (string, optional): Terraform project path to scan. Default: `.`.
+- `extraArgs` (string[], optional): Extra CLI arguments.
+- `timeoutMs` (integer, optional): Command timeout in milliseconds.
+
+### `run_trivy`
+
+Run trivy config scanning against Terraform code.
+
+Inputs:
+
+- `path` (string, optional): Terraform project path to scan. Default: `.`.
+- `extraArgs` (string[], optional): Extra CLI arguments.
+- `timeoutMs` (integer, optional): Command timeout in milliseconds.
+
+### `run_kics`
+
+Run kics IaC scanning against Terraform code.
+
+Inputs:
+
+- `path` (string, optional): Terraform project path to scan. Default: `.`.
+- `extraArgs` (string[], optional): Extra CLI arguments.
+- `timeoutMs` (integer, optional): Command timeout in milliseconds.
+
+### `run_infracost`
+
+Run infracost breakdown for a Terraform directory.
+
+Inputs:
+
+- `path` (string, optional): Terraform project path to scan. Default: `.`.
+- `extraArgs` (string[], optional): Extra CLI arguments.
+- `timeoutMs` (integer, optional): Command timeout in milliseconds.
+
+### `fetch_terraform_best_practices`
+
+Fetch Terraform best-practice guidance from curated checks and optional live summaries from terraform-best-practices.com.
+
+Inputs:
+
+- `topic` (string, optional): Topic filter such as state, modules, security, or naming.
+- `liveFetch` (boolean, optional): When true, fetches and summarises live content. Default: `true`.
+
+### `fetch_provider_best_practices`
+
+Fetch Terraform best-practice guidance for Azure, AWS, or GCP from curated checks and optional live provider docs summaries.
+
+Inputs:
+
+- `provider` (string, required): Cloud provider (`azure`, `aws`, or `gcp`).
+- `topic` (string, optional): Focus area such as state, IAM, modules, networking, or cost.
+- `liveFetch` (boolean, optional): When true, fetches and summarises the linked provider guidance page. Default: `true`.
+
+### `fetch_terraform_registry_guidance`
+
+Fetch Terraform Registry guidance for providers, resources, and modules.
+
+Inputs:
+
+- `provider` (string, optional): Provider name (e.g. `aws`, `azurerm`, `google`).
+- `resource` (string, optional): Resource type used with provider (e.g. `s3_bucket`, `resource_group`).
+- `module` (string, optional): Module path in the form `namespace/name/provider`.
+- `topic` (string, optional): Topic filter for the summary output.
+- `liveFetch` (boolean, optional): When true, fetches and summarises selected Registry pages. Default: `true`.
+
+### `analyze_terraform_code`
+
+Analyze Terraform code structure, modularity, and best practices.
+
+Inputs:
+
+- `code` (string, required): Terraform code snippet to analyze (max 50,000 chars).
+- `focusArea` (string, optional): Analysis focus area (`modularity`, `variables`, `outputs`, `locals`, `general`). Default: `general`.
+
+### `analyze_terraform_performance`
+
+Analyze Terraform runtime and performance bottlenecks and optimization opportunities.
+
+Inputs:
+
+- `terraformCode` (string, required): Terraform code for performance-focused heuristics.
+- `stateSizeMb` (number, optional): State size in MB for scale-aware recommendations.
+- `workspaceCount` (integer, optional): Number of workspaces sharing the same root stack.
+- `providerRateLimitSensitive` (boolean, optional): When true, emphasise provider API throttling protections. Default: `true`.
+
+### `analyze_state_management`
+
+Assess backend state strategy and collaboration safety.
+
+Inputs:
+
+- `terraformCode` (string, required): Terraform code including backend and state-related configuration.
+- `teamSize` (integer, optional): Number of engineers applying Terraform changes. Default: `6`.
+- `environmentCount` (integer, optional): Number of environments managed by the estate. Default: `2`.
+- `currentBackend` (string, optional): State backend in use (`auto`, `s3`, `azurerm`, `gcs`, `remote`, `local`, `unknown`). Default: `auto`.
+- `useWorkspaces` (boolean, optional): Whether multiple environments are managed through workspaces. Default: `false`.
+
+### `generate_cost_report`
+
+Generate cost analysis with optimization suggestions from Infracost output.
+
+Inputs:
+
+- `infracostJson` (string, required): JSON output from infracost breakdown or diff command.
+- `includeOptimizations` (boolean, optional): When true, generates cost optimization suggestions. Default: `true`.
+
+### `generate_terraform_module_docs`
+
+Generate module documentation markdown from Terraform code.
+
+Inputs:
+
+- `terraformCode` (string, required): Terraform module code to document.
+- `moduleName` (string, optional): Friendly name used in generated markdown docs. Default: `terraform-module`.
+- `includeUsageExample` (boolean, optional): Include a usage example section. Default: `true`.
+- `includeInputsOutputsTables` (boolean, optional): Render inputs and outputs as markdown tables. Default: `true`.
+
+### `recommend_terraform_modules`
+
+Recommend reusable Terraform modules from detected code patterns.
+
+Inputs:
+
+- `terraformCode` (string, required): Terraform code used to infer module recommendations.
+- `provider` (string, optional): Preferred cloud provider (`aws`, `azure`, `gcp`, `any`). Default: `any`.
+- `deploymentIntent` (string, optional): Primary deployment goal (`networking`, `kubernetes`, `serverless`, `storage`, `database`, `observability`, `security`, `general`). Default: `general`.
+- `maxRecommendations` (integer, optional): Maximum recommendations to return (1--10). Default: `5`.
+
+### `suggest_terraform_architecture`
+
+Suggest architecture patterns for multi-environment and multi-region estates.
+
+Inputs:
+
+- `workloadType` (string, optional): Primary workload profile (`web-api`, `data-platform`, `event-driven`, `platform-foundation`, `general`). Default: `general`.
+- `environments` (string[], optional): Target environments (`dev`, `test`, `stage`, `prod`, `sandbox`, `dr`). Default: `["dev", "prod"]`.
+- `multiRegion` (boolean, optional): Whether workloads run across multiple regions. Default: `false`.
+- `complianceProfile` (string, optional): Compliance profile (`none`, `cis`, `pci-dss`, `hipaa`, `sox`). Default: `none`.
+- `teamSize` (integer, optional): Number of engineers operating Terraform code. Default: `6`.
+- `currentPainPoints` (string, optional): Pain points or constraints in the current architecture.
+- `includeReferenceLayout` (boolean, optional): Include a suggested repository and folder layout. Default: `true`.
+
+### `suggest_terraform_testing_strategy`
+
+Recommend CI-driven Terraform testing strategy by risk profile.
+
+Inputs:
+
+- `terraformCode` (string, optional): Terraform code for complexity-aware recommendations.
+- `deploymentCriticality` (string, optional): Business impact level (`low`, `medium`, `high`, `mission-critical`). Default: `medium`.
+- `changeFrequency` (string, optional): How often infrastructure changes are introduced (`low`, `medium`, `high`). Default: `medium`.
+- `ciSystem` (string, optional): Target CI system (`github-actions`, `azure-devops`, `gitlab`, `circleci`, `jenkins`, `other`). Default: `github-actions`.
+- `includeExamplePipeline` (boolean, optional): Include an example pipeline sequence. Default: `true`.
+
+### `suggest_security_hardening`
+
+Provide security hardening recommendations from scan output.
+
+Inputs:
+
+- `scanOutput` (string, required): Output from a security scanning tool (checkov, trivy, or kics).
+- `scanTool` (string, optional): Name of the scanning tool (`checkov`, `trivy`, `kics`). Default: `checkov`.
+
+### `generate_compliance_summary`
+
+Create compliance reports from scan outputs.
+
+Inputs:
+
+- `checkovOutput` (string, optional): Output from checkov scan.
+- `trivyOutput` (string, optional): Output from trivy scan.
+- `kicsOutput` (string, optional): Output from kics scan.
+- `complianceFramework` (string, optional): Compliance framework to assess against (`cis`, `pci-dss`, `hipaa`, `sox`, `general`). Default: `general`.
+
+## Prompt Cookbook
+
+Use these minimal prompts in Copilot Chat with `@tf-best-practices`. CLI tools default to the current workspace root when no `path` is provided. Adding `#file` or `#folder` context can improve chat understanding, but tool execution path is controlled by explicit tool inputs (for example, `path`).
+
+### Quick Start (Zero-Argument Prompts)
+
+```text
+@tf-best-practices run run_tflint
+@tf-best-practices run run_checkov
+@tf-best-practices run run_trivy
+@tf-best-practices run run_kics
+@tf-best-practices run run_infracost
+@tf-best-practices run fetch_terraform_best_practices
+```
+
+### CLI Analysis
+
+```text
+@tf-best-practices run run_tflint with path ./modules/network
+@tf-best-practices run run_checkov with path ./environments/prod
+@tf-best-practices run run_trivy with path .
+@tf-best-practices run run_kics with path .
+@tf-best-practices run run_infracost with path .
+```
+
+### Best Practices and Guidance
+
+```text
+@tf-best-practices run fetch_terraform_best_practices with topic modules
+@tf-best-practices run fetch_provider_best_practices with provider azure
+@tf-best-practices run fetch_terraform_registry_guidance with provider azurerm and resource resource_group
+```
+
+### Code Analysis
+
+```text
+@tf-best-practices run analyze_terraform_code with code <paste code> and focusArea modularity
+@tf-best-practices run analyze_terraform_performance with terraformCode <paste code>
+@tf-best-practices run analyze_state_management with terraformCode <paste code>
+```
+
+### Reporting and Recommendations
+
+```text
+@tf-best-practices run generate_cost_report with infracostJson <paste json>
+@tf-best-practices run generate_terraform_module_docs with terraformCode <paste code>
+@tf-best-practices run recommend_terraform_modules with terraformCode <paste code> and provider azure
+@tf-best-practices run suggest_terraform_architecture with workloadType web-api and environments ["dev","stage","prod"]
+@tf-best-practices run suggest_terraform_testing_strategy with ciSystem github-actions
+@tf-best-practices run suggest_security_hardening with scanOutput <paste output> and scanTool checkov
+@tf-best-practices run generate_compliance_summary with complianceFramework cis
+```
+
+## Dependencies
+
+### System Dependencies
+
+- Node.js `>=24.14.0`
+- npm (bundled with Node.js)
 - Optional CLIs available on `PATH` for command tools:
   - `tflint`
   - `checkov`
@@ -30,46 +331,41 @@ An MCP server that helps teams produce better Terraform by combining:
 
 If a CLI is missing, the server returns installation guidance instead of failing silently.
 
-## Setup
-
-```bash
-npm install
-npm run build
-```
-
-## Run
+### npm Dependencies
 
-```bash
-npm run dev
-```
+Runtime:
 
-For production-style execution:
+- `@modelcontextprotocol/sdk` (MCP server SDK)
+- `zod` (input schema validation)
 
-```bash
-npm run build
-npm start
-```
+Development:
 
-## Publish
+- `typescript` (build/compile)
+- `tsx` (development runner)
+- `vitest` (unit test runner)
+- `@types/node` (Node.js typings)
 
-This package is configured for npm as:
+### Environment Variables
 
-- `@downatthebottomofthemolehole/terraform-best-practices-mcp-server`
+- `INFRACOST_API_KEY`: Infracost API key for cloud-backed cost estimates.
 
-To publish:
+## Installation
 
 ```bash
-npm publish --access public
+npm install
+npm run build
 ```
 
-## MCP Configuration
+## Configuration
 
-This project includes `.vscode/mcp.json`:
+### Usage with VS Code Copilot Chat
+
+This workspace is preconfigured in `.vscode/mcp.json`:
 
 ```json
 {
   "servers": {
-    "terraform-best-practices-mcp": {
+    "tf-best-practices": {
       "type": "stdio",
       "command": "npm",
       "args": ["run", "dev"]
@@ -78,15 +374,173 @@ This project includes `.vscode/mcp.json`:
 }
 ```
 
-Registry metadata files used by your other MCP repos are also included:
+Reload VS Code (`Cmd+Shift+P` -> `Developer: Reload Window`) after changing MCP configuration.
 
-- `mcp.json`
-- `server.json`
+Then query the server from Copilot Chat with `@tf-best-practices`, for example:
 
-## References
+```text
+@tf-best-practices run run_tflint
+@tf-best-practices run fetch_terraform_best_practices with topic modules
+```
 
-- [MCP org](https://github.com/modelcontextprotocol)
-- [MCP docs](https://modelcontextprotocol.io/docs)
-- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
-- [terraform-best-practices](https://www.terraform-best-practices.com/)
+### Usage with Other MCP Clients
+
+Use stdio transport with the built entrypoint:
+
+```json
+{
+  "name": "terraform-best-practices-mcp-server",
+  "type": "stdio",
+  "command": "node",
+  "args": ["/absolute/path/to/terraform-best-practices-mcp/dist/index.js"]
+}
+```
+
+Build first with `npm run build`, then start your MCP client.
+
+## Running
+
+```bash
+npm start
+```
+
+Development mode:
+
+```bash
+npm run dev
+```
+
+## Debugging
+
+Use `.vscode/launch.json`:
+
+- `Debug MCP Server` (runs `npm run dev`)
+- `Debug MCP Server (Built)` (runs `dist/index.js` after build)
+
+Set breakpoints in `src/index.ts`, then press `F5`.
+
+## Testing
+
+See [docs/TESTING.md](./docs/TESTING.md) for Copilot Chat scenarios, manual JSON-RPC checks, and troubleshooting guidance.
+
+Quick validation prompt in Copilot Chat:
+
+```text
+@tf-best-practices run run_tflint
+```
+
+## Interactive VS Code Workflows
+
+### 1. Security Triage
+
+1. Run a scan:
+
+```text
+@tf-best-practices run run_checkov
+```
+
+1. Request hardening suggestions:
+
+```text
+@tf-best-practices run suggest_security_hardening with scanOutput <paste checkov output> and scanTool checkov
+```
+
+1. Generate a compliance summary:
+
+```text
+@tf-best-practices run generate_compliance_summary with checkovOutput <paste output> and complianceFramework cis
+```
+
+### 2. Cost Impact Review
+
+1. Generate a cost baseline:
+
+```text
+@tf-best-practices run run_infracost
+```
+
+1. Produce a cost report:
+
+```text
+@tf-best-practices run generate_cost_report with infracostJson <paste json>
+```
+
+### 3. Architecture Review
+
+1. Analyse code quality:
+
+```text
+@tf-best-practices run analyze_terraform_code with code <paste code> and focusArea modularity
+```
+
+1. Review state management:
+
+```text
+@tf-best-practices run analyze_state_management with terraformCode <paste code>
+```
+
+1. Get architecture recommendations:
+
+```text
+@tf-best-practices run suggest_terraform_architecture with workloadType web-api and multiRegion true
+```
+
+### Best Practices
+
+- Start with CLI analysis tools to establish a baseline before using guidance tools.
+- Use `fetch_terraform_best_practices` to align with community conventions.
+- Use `fetch_provider_best_practices` for provider-specific patterns.
+- Keep `timeoutMs` high enough for large Terraform projects.
+- Run `suggest_terraform_testing_strategy` when onboarding new CI/CD pipelines.
+- Use `generate_compliance_summary` regularly for audit readiness.
+
+## Additional Use Cases
+
+- Pre-merge security and compliance gates in pull requests.
+- Automated cost impact reviews for infrastructure changes.
+- Architecture pattern recommendations for greenfield projects.
+- Module documentation generation for shared Terraform modules.
+- CI-driven testing strategy definition by deployment risk profile.
+- Compliance evidence generation for audit trails.
+
+## Related Projects
+
+### Terraform Resources
+
+- [terraform-best-practices.com](https://www.terraform-best-practices.com/)
 - [Terraform Registry](https://registry.terraform.io/)
+- [tflint](https://github.com/terraform-linters/tflint)
+- [checkov](https://www.checkov.io/)
+- [trivy](https://github.com/aquasecurity/trivy)
+- [kics](https://kics.io/)
+- [Infracost](https://www.infracost.io/)
+
+### Model Context Protocol
+
+- [MCP official documentation](https://modelcontextprotocol.io/)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP servers registry](https://github.com/mcp)
+
+## Community and Contributing
+
+- [Contributing Guide](./CONTRIBUTING.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Security Policy](./SECURITY.md)
+- [Testing Guide](./docs/TESTING.md)
+- [Maintainer Guide](./docs/MAINTAINERS.md)
+
+## Attribution and License
+
+Maintained by Carl Dawson under the [Down At The Bottom Of The Mole Hole](https://github.com/downatthebottomofthemolehole) organization.
+
+## Development
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+## License
+
+Licensed under the MIT License.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -77,3 +77,4 @@ main().catch((error) => {
     console.error(`Fatal startup error: ${message}`);
     process.exit(1);
 });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/lib/exec.d.ts

@@ -0,0 +1,20 @@
+export interface CommandExecutionOptions {
+    cwd?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export interface CommandExecutionResult {
+    command: string;
+    args: string[];
+    cwd: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    outputTruncated: boolean;
+}
+export declare class CommandNotFoundError extends Error {
+    constructor(command: string);
+}
+export declare function runCommand(command: string, args: string[], options?: CommandExecutionOptions): Promise<CommandExecutionResult>;

package/dist/lib/exec.js

@@ -84,3 +84,4 @@ export async function runCommand(command, args, options = {}) {
         });
     });
 }
+//# sourceMappingURL=exec.js.map

package/dist/lib/exec.js.map

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

package/dist/lib/http.d.ts

@@ -0,0 +1 @@
+export declare function fetchText(url: string, timeoutMs?: number): Promise<string>;

package/dist/lib/http.js

@@ -17,3 +17,4 @@ export async function fetchText(url, timeoutMs = 15_000) {
         clearTimeout(timeout);
     }
 }
+//# sourceMappingURL=http.js.map

package/dist/lib/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/lib/http.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,SAAS,GAAG,MAAM;IAC7D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAEhE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,OAAO,EAAE;gBACP,YAAY,EAAE,oCAAoC;aACnD;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/lib/text.d.ts

@@ -0,0 +1,2 @@
+export declare function toPlainText(value: string): string;
+export declare function keywordSnippet(text: string, keywords: string[], maxChars?: number): string;

package/dist/lib/text.js

@@ -37,3 +37,4 @@ export function keywordSnippet(text, keywords, maxChars = 2_000) {
     }
     return output || cleaned.slice(0, maxChars);
 }
+//# sourceMappingURL=text.js.map

package/dist/lib/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/lib/text.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK;SACT,OAAO,CAAC,6BAA6B,EAAE,GAAG,CAAC;SAC3C,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC;SACzC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,QAAkB,EAAE,QAAQ,GAAG,KAAK;IAC/E,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,eAAe,GAAG,QAAQ;SAC7B,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAC9C,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE3C,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC5C,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QACvC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,KAAK,MAAM,QAAQ,IAAI,MAAM,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC9D,IAAI,SAAS,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YAChC,MAAM;QACR,CAAC;QACD,MAAM,GAAG,SAAS,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC9C,CAAC"}