{"_id":"@dogtags27/prompt-lint","name":"@dogtags27/prompt-lint","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@dogtags27/prompt-lint","version":"0.1.0","description":"Developer-first CLI tool for versioning, testing, and CI/CD safety for LLM prompts","type":"module","main":"./dist/index.js","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./package.json":"./package.json"},"bin":{"prompt":"dist/cli/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","prepublishOnly":"npm run build","test":"echo \"Error: no test specified\" && exit 1","lint":"eslint src --ext .ts","format":"prettier --write \"src/**/*.ts\""},"keywords":["prompt","llm","versioning","testing","ci-cd","semantic-versioning"],"author":{"name":"Hriday Desai"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Dogtags27/prompt-lint.git"},"bugs":{"url":"https://github.com/Dogtags27/prompt-lint/issues"},"homepage":"https://github.com/Dogtags27/prompt-lint#readme","engines":{"node":">=18.0.0"},"dependencies":{"@anthropic-ai/sdk":"^0.20.0","ajv":"^8.12.0","ajv-formats":"^2.1.1","commander":"^11.1.0","semver":"^7.5.4","simple-git":"^3.22.0","tiktoken":"^1.0.15"},"devDependencies":{"@types/node":"^20.10.0","@types/semver":"^7.5.6","@typescript-eslint/eslint-plugin":"^6.13.0","@typescript-eslint/parser":"^6.13.0","eslint":"^8.54.0","prettier":"^3.1.0","typescript":"^5.3.2"},"gitHead":"d14b94bbdd470b499b4286719501c64032776302","types":"./dist/index.d.ts","_id":"@dogtags27/prompt-lint@0.1.0","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-gB1czTFLSQXP8AsewZAXNBaK4o1PSFAdxdRamJ69fWceouE8xdLf+tymQs2nSffWZ/c/HlAa/YYo04of996rew==","shasum":"44f2205b54b979c967623e9c9c276992559e0c91","tarball":"https://registry.npmjs.org/@dogtags27/prompt-lint/-/prompt-lint-0.1.0.tgz","fileCount":268,"unpackedSize":550638,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD4MiGbLTDMwx92z+nWV+kDZ21Y8VsVgJkDDNSKzbF86QIgXA8y8+iVtXb8Orh6PaVvNkfulqABa7wvR0YaS/wBznQ="}]},"_npmUser":{"name":"dogtags27","email":"hriday.nitr.27@gmail.com"},"directories":{},"maintainers":[{"name":"dogtags27","email":"hriday.nitr.27@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/prompt-lint_0.1.0_1769346834844_0.2902472311509372"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-25T13:13:54.739Z","0.1.0":"2026-01-25T13:13:55.032Z","modified":"2026-01-25T13:13:55.265Z"},"maintainers":[{"name":"dogtags27","email":"hriday.nitr.27@gmail.com"}],"description":"Developer-first CLI tool for versioning, testing, and CI/CD safety for LLM prompts","homepage":"https://github.com/Dogtags27/prompt-lint#readme","keywords":["prompt","llm","versioning","testing","ci-cd","semantic-versioning"],"repository":{"type":"git","url":"git+https://github.com/Dogtags27/prompt-lint.git"},"author":{"name":"Hriday Desai"},"bugs":{"url":"https://github.com/Dogtags27/prompt-lint/issues"},"license":"MIT","readme":"# 🚀 PromptLint\r\n\r\n> **Stop treating prompts like strings. Start treating them like production code.**\r\n\r\nPromptLint is the developer-first CLI tool that brings **version control**, **testing**, and **CI/CD safety** to your LLM prompts. Never lose track of prompt changes again. Never deploy a broken prompt. Never wonder \"what changed?\" or \"why did this break?\"\r\n\r\n## ✨ Why PromptLint?\r\n\r\n**The Problem:** Prompts are critical production code, but we treat them like disposable strings. Changes are lost, versions are unclear, and regressions go undetected until users complain.\r\n\r\n**The Solution:** PromptLint gives you:\r\n- 📦 **Semantic versioning** for every prompt change\r\n- 🔍 **Visual diffs** showing exactly what changed (with cost impact!)\r\n- 🧪 **Automated testing** that handles non-deterministic LLM outputs\r\n- 📊 **Regression detection** for cost, latency, and behavior changes\r\n- 🔒 **Immutability** - released versions are locked and Git-tracked\r\n- 💰 **Cost tracking** across versions\r\n- 🔌 **CI/CD ready** - fail builds on breaking changes\r\n\r\n## 🎯 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\nnpm install -g @dogtags27/prompt-lint\r\n```\r\n\r\n### Create Your First Versioned Prompt\r\n\r\n```bash\r\n# Create a new prompt artifact\r\nprompt create --id greeting-bot \\\r\n  --description \"Friendly greeting prompt\" \\\r\n  --provider openai \\\r\n  --model gpt-4\r\n\r\n# Output: Created prompts/greeting-bot/v0.1.0.json\r\n```\r\n\r\n### Run Your Prompt\r\n\r\n```bash\r\n# Execute with inputs\r\nprompt run --prompt-id greeting-bot \\\r\n  --input name=\"Alice\" \\\r\n  --input timeOfDay=\"morning\"\r\n\r\n# Or use JSON input\r\nprompt run --prompt-id greeting-bot \\\r\n  --json-input '{\"name\":\"Alice\",\"timeOfDay\":\"morning\"}'\r\n```\r\n\r\n### See What Changed\r\n\r\n```bash\r\n# Generate beautiful HTML diff comparing versions\r\nprompt diff --prompt-id greeting-bot \\\r\n  --current current \\\r\n  --compare v0.1.0 \\\r\n  --open\r\n\r\n# Opens interactive HTML diff showing:\r\n# - Template changes (side-by-side)\r\n# - Token count changes\r\n# - Cost impact per call\r\n# - Breaking changes detection\r\n```\r\n\r\n## 🎨 Core Features\r\n\r\n### 1. 📦 Semantic Versioning\r\n\r\nTrack every change with semantic versioning (major.minor.patch):\r\n\r\n```bash\r\n# Bump version after making changes\r\nprompt version:bump --prompt-id greeting-bot \\\r\n  --version 0.1.0 \\\r\n  --type minor\r\n\r\n# Major: Breaking changes (output schema, required inputs)\r\n# Minor: New features (optional inputs, extended functionality)  \r\n# Patch: Bug fixes, template improvements\r\n```\r\n\r\n**Example workflow:**\r\n```bash\r\n# 1. Make changes to your prompt template\r\nvim prompts/greeting-bot/v0.1.0.json\r\n\r\n# 2. Test the changes\r\nprompt test --prompt-id greeting-bot\r\n\r\n# 3. Bump version\r\nprompt version:bump --prompt-id greeting-bot \\\r\n  --version 0.1.0 --type patch\r\n\r\n# 4. Review diff before committing\r\nprompt diff --prompt-id greeting-bot \\\r\n  --current current --compare v0.1.1\r\n```\r\n\r\n### 2. 🔍 Visual Diff & Change Tracking\r\n\r\nSee exactly what changed between versions with beautiful HTML diffs:\r\n\r\n```bash\r\n# Compare current working version with latest saved\r\nprompt diff --prompt-id greeting-bot \\\r\n  --current current \\\r\n  --compare v0.2.0 \\\r\n  --format html \\\r\n  --open\r\n\r\n# Output includes:\r\n# ✅ Side-by-side template comparison\r\n# ✅ Token count changes (+150 tokens, +12.5%)\r\n# ✅ Cost impact ($0.0003 per call increase)\r\n# ✅ Breaking changes detection\r\n# ✅ Impact assessment (low/medium/high/breaking)\r\n```\r\n\r\n**Diff formats:**\r\n- `html` - Interactive visual diff (opens in browser)\r\n- `markdown` - Markdown format for documentation\r\n- `json` - Machine-readable diff data\r\n\r\n### 3. 🔎 Auto-Detection & Scanning\r\n\r\nAutomatically discover prompts in your codebase:\r\n\r\n```bash\r\n# Scan current directory\r\nprompt scan\r\n\r\n# Scan specific file\r\nprompt scan --file src/prompts.ts\r\n\r\n# Recursive scan with auto-save\r\nprompt scan --recursive --auto-save\r\n\r\n# Interactive mode (confirm before saving)\r\nprompt scan --interactive\r\n\r\n# Filter by file type\r\nprompt scan --format ts --recursive\r\n```\r\n\r\n**Detects prompts in:**\r\n- TypeScript/JavaScript files\r\n- JSON files\r\n- YAML files\r\n- Inline prompt strings\r\n\r\n### 4. 🧪 Comprehensive Testing\r\n\r\nTest prompts with support for non-deterministic outputs:\r\n\r\n```bash\r\n# Run test suite\r\nprompt test --prompt-id greeting-bot\r\n\r\n# Save baseline for regression detection\r\nprompt test --prompt-id greeting-bot --save-baseline\r\n\r\n# Compare against baseline\r\nprompt test --prompt-id greeting-bot --compare-baseline\r\n\r\n# Generate JUnit XML for CI/CD\r\nprompt test --prompt-id greeting-bot \\\r\n  --junit-output test-results.xml\r\n\r\n# Generate JSON report\r\nprompt test --prompt-id greeting-bot \\\r\n  --json-output test-report.json\r\n```\r\n\r\n**Test assertion types:**\r\n- **Schema assertions** - Validate JSON structure\r\n- **Classification assertions** - Check expected categories\r\n- **Tolerance assertions** - Numeric comparisons with variance\r\n- **Safety assertions** - Content filtering and constraints\r\n\r\n**Example test suite:**\r\n```json\r\n{\r\n  \"promptId\": \"greeting-bot\",\r\n  \"version\": \"0.2.0\",\r\n  \"tests\": [\r\n    {\r\n      \"name\": \"Morning greeting\",\r\n      \"inputs\": { \"name\": \"Alice\", \"timeOfDay\": \"morning\" },\r\n      \"assertions\": [\r\n        {\r\n          \"type\": \"contains\",\r\n          \"field\": \"output\",\r\n          \"value\": \"Good morning\"\r\n        },\r\n        {\r\n          \"type\": \"schema\",\r\n          \"schema\": {\r\n            \"type\": \"object\",\r\n            \"required\": [\"greeting\", \"tone\"]\r\n          }\r\n        }\r\n      ]\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n### 5. 🔍 Search & Discovery\r\n\r\nFind prompts quickly across your codebase:\r\n\r\n```bash\r\n# Full-text search\r\nprompt search --query \"greeting\"\r\n\r\n# Search with filters\r\nprompt search --query \"customer\" \\\r\n  --provider openai \\\r\n  --has-variable userId \\\r\n  --tag production\r\n\r\n# Fuzzy matching\r\nprompt search --query \"greet\" --fuzzy\r\n\r\n# Limit results\r\nprompt search --query \"bot\" --limit 10\r\n```\r\n\r\n**Quick find by pattern:**\r\n```bash\r\n# Find by ID pattern\r\nprompt find --pattern greeting\r\n\r\n# Exact match\r\nprompt find --pattern greeting-bot --exact\r\n\r\n# Show full template\r\nprompt find --pattern greeting-bot --show-template\r\n\r\n# List all variables\r\nprompt find --pattern greeting-bot --list-variables\r\n\r\n# Show file location\r\nprompt find --pattern greeting-bot --show-location\r\n```\r\n\r\n### 6. 📊 Status & Monitoring\r\n\r\nTrack the state of all your prompts:\r\n\r\n```bash\r\n# Status of specific prompt\r\nprompt status --prompt-id greeting-bot\r\n\r\n# Status of all prompts\r\nprompt status\r\n\r\n# Output shows:\r\n# - Current version\r\n# - Latest saved version\r\n# - Git commit status\r\n# - Test status\r\n# - Last modified date\r\n```\r\n\r\n### 7. ⏪ Rollback & Recovery\r\n\r\nSafely rollback to previous versions:\r\n\r\n```bash\r\n# Rollback to previous version\r\nprompt rollback --prompt-id greeting-bot \\\r\n  --version v0.1.0\r\n\r\n# Creates new version from rollback target\r\n# Example: v0.2.0 → rollback to v0.1.0 → creates v0.2.1\r\n```\r\n\r\n### 8. ✅ Validation\r\n\r\nEnsure prompt artifacts are valid:\r\n\r\n```bash\r\n# Validate specific version\r\nprompt validate --prompt-id greeting-bot --version 0.2.0\r\n\r\n# Validate from file\r\nprompt validate --file prompts/greeting-bot/v0.2.0.json\r\n\r\n# Validate all versions\r\nprompt validate --prompt-id greeting-bot --all\r\n```\r\n\r\n### 9. 💰 Cost & Token Tracking\r\n\r\nMonitor cost impact across versions:\r\n\r\n```bash\r\n# Diff shows token and cost changes\r\nprompt diff --prompt-id greeting-bot \\\r\n  --current v0.2.0 \\\r\n  --compare v0.1.0\r\n\r\n# Output includes:\r\n# Token Change: +150 tokens (+12.5%)\r\n# Cost Impact: +$0.0003 per call\r\n```\r\n\r\n### 10. 🔌 CI/CD Integration\r\n\r\nFail builds on breaking changes:\r\n\r\n```bash\r\n# In your CI pipeline\r\nprompt validate --prompt-id greeting-bot --all\r\nprompt test --prompt-id greeting-bot --compare-baseline\r\nprompt diff --prompt-id greeting-bot --format json\r\n\r\n# Exit codes:\r\n# 0 = Success\r\n# 1 = Validation error\r\n# 2 = System error\r\n```\r\n\r\n**GitHub Actions example:**\r\n```yaml\r\n- name: Validate Prompts\r\n  run: |\r\n    prompt validate --prompt-id greeting-bot --all\r\n    prompt test --prompt-id greeting-bot --compare-baseline\r\n```\r\n\r\n## 📁 Project Structure\r\n\r\n```\r\nyour-project/\r\n├── prompts/                    # Versioned prompt artifacts\r\n│   └── greeting-bot/\r\n│       ├── v0.1.0.json        # Initial version\r\n│       ├── v0.1.1.json        # Patch version\r\n│       ├── v0.2.0.json        # Minor version\r\n│       └── .baselines/        # Test baselines\r\n│           └── v0.2.0.json\r\n├── tests/                     # Test suites\r\n│   └── prompts/\r\n│       └── greeting-bot/\r\n│           └── suite.json\r\n├── .prompt-lint/              # Internal index and metadata\r\n│   ├── index.json\r\n│   └── diffs/\r\n└── .promptrc.json             # Configuration (optional)\r\n```\r\n\r\n## ⚙️ Configuration\r\n\r\nCreate `.promptrc.json` in your project root:\r\n\r\n```json\r\n{\r\n  \"baseDir\": \".\",\r\n  \"apiKeys\": {\r\n    \"openai\": \"sk-...\",\r\n    \"anthropic\": \"sk-ant-...\"\r\n  },\r\n  \"defaults\": {\r\n    \"provider\": \"openai\",\r\n    \"temperature\": 0.7,\r\n    \"maxTokens\": 2000\r\n  },\r\n  \"test\": {\r\n    \"runs\": 3,\r\n    \"timeout\": 30000\r\n  },\r\n  \"ci\": {\r\n    \"costThreshold\": 20,\r\n    \"latencyThreshold\": 30\r\n  }\r\n}\r\n```\r\n\r\n**Or use environment variables (recommended):**\r\n```bash\r\nexport OPENAI_API_KEY=\"sk-...\"\r\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\r\n```\r\n\r\n## 📖 Prompt Artifact Format\r\n\r\nA prompt artifact is a structured JSON file:\r\n\r\n```json\r\n{\r\n  \"id\": \"greeting-bot\",\r\n  \"version\": \"0.2.0\",\r\n  \"template\": \"Hello {{name}}! Good {{timeOfDay}}!\",\r\n  \"inputs\": {\r\n    \"required\": {\r\n      \"name\": {\r\n        \"type\": \"string\",\r\n        \"description\": \"User's name\"\r\n      }\r\n    },\r\n    \"optional\": {\r\n      \"timeOfDay\": {\r\n        \"type\": \"string\",\r\n        \"description\": \"Time of day\",\r\n        \"default\": \"day\"\r\n      }\r\n    }\r\n  },\r\n  \"model\": {\r\n    \"provider\": \"openai\",\r\n    \"model\": \"gpt-4\",\r\n    \"temperature\": 0.7,\r\n    \"maxTokens\": 2000\r\n  },\r\n  \"output\": {\r\n    \"format\": \"json\",\r\n    \"schema\": {\r\n      \"type\": \"object\",\r\n      \"properties\": {\r\n        \"greeting\": { \"type\": \"string\" },\r\n        \"tone\": { \"type\": \"string\" }\r\n      },\r\n      \"required\": [\"greeting\", \"tone\"]\r\n    }\r\n  },\r\n  \"metadata\": {\r\n    \"description\": \"Friendly greeting prompt\",\r\n    \"author\": \"Your Name\",\r\n    \"tags\": [\"production\", \"customer-facing\"]\r\n  }\r\n}\r\n```\r\n\r\n## 🎯 Common Workflows\r\n\r\n### Workflow 1: Making Prompt Changes\r\n\r\n```bash\r\n# 1. Edit your prompt\r\nvim prompts/greeting-bot/v0.2.0.json\r\n\r\n# 2. Test locally\r\nprompt run --prompt-id greeting-bot \\\r\n  --input name=\"Alice\"\r\n\r\n# 3. Run tests\r\nprompt test --prompt-id greeting-bot\r\n\r\n# 4. Check diff before committing\r\nprompt diff --prompt-id greeting-bot \\\r\n  --current current --compare v0.2.0\r\n\r\n# 5. Bump version\r\nprompt version:bump --prompt-id greeting-bot \\\r\n  --version 0.2.0 --type patch\r\n\r\n# 6. Commit to Git\r\ngit add prompts/\r\ngit commit -m \"feat: improve greeting prompt\"\r\n```\r\n\r\n### Workflow 2: Onboarding Existing Prompts\r\n\r\n```bash\r\n# 1. Scan your codebase\r\nprompt scan --recursive\r\n\r\n# 2. Review detected prompts\r\nprompt status\r\n\r\n# 3. Save detected prompts\r\nprompt scan --interactive --auto-save\r\n\r\n# 4. Create test suites\r\nprompt test --prompt-id my-prompt --save-baseline\r\n```\r\n\r\n### Workflow 3: CI/CD Pipeline\r\n\r\n```bash\r\n# In your CI script\r\n#!/bin/bash\r\nset -e\r\n\r\n# Validate all prompts\r\nprompt validate --prompt-id greeting-bot --all\r\n\r\n# Run tests and compare baselines\r\nprompt test --prompt-id greeting-bot \\\r\n  --compare-baseline \\\r\n  --junit-output test-results.xml\r\n\r\n# Check for breaking changes\r\nDIFF=$(prompt diff --prompt-id greeting-bot \\\r\n  --current current \\\r\n  --compare latest \\\r\n  --format json)\r\n\r\nif echo \"$DIFF\" | jq '.summary.breakingChanges' | grep -q true; then\r\n  echo \"❌ Breaking changes detected!\"\r\n  exit 1\r\nfi\r\n```\r\n\r\n## 🛠️ All Commands\r\n\r\n| Command | Description | Example |\r\n|---------|-------------|---------|\r\n| `create` | Create new prompt artifact | `prompt create --id my-prompt` |\r\n| `validate` | Validate prompt structure | `prompt validate --prompt-id my-prompt` |\r\n| `run` | Execute a prompt | `prompt run --prompt-id my-prompt --input key=value` |\r\n| `test` | Run test suite | `prompt test --prompt-id my-prompt` |\r\n| `version:bump` | Bump prompt version | `prompt version:bump --prompt-id my-prompt --version 1.0.0 --type minor` |\r\n| `version:show` | Show version info | `prompt version:show --prompt-id my-prompt --version 1.0.0` |\r\n| `status` | Show prompt status | `prompt status --prompt-id my-prompt` |\r\n| `diff` | Compare versions | `prompt diff --prompt-id my-prompt --current current --compare v1.0.0` |\r\n| `rollback` | Rollback to version | `prompt rollback --prompt-id my-prompt --version v1.0.0` |\r\n| `scan` | Auto-detect prompts | `prompt scan --recursive` |\r\n| `search` | Search prompts | `prompt search --query \"greeting\"` |\r\n| `find` | Find by pattern | `prompt find --pattern greeting` |\r\n\r\n## 🔒 Security\r\n\r\n- ✅ API keys are automatically sanitized from outputs\r\n- ✅ `.promptrc.json` is in `.gitignore` by default\r\n- ✅ Environment variables recommended for production\r\n- ✅ Warnings when API keys detected in config files\r\n\r\nSee [SECURITY.md](SECURITY.md) for best practices.\r\n\r\n## 📚 Documentation\r\n\r\n- **[Getting Started Guide](docs/getting-started.md)** - Learn the basics\r\n- **[Prompt Artifact Specification](docs/prompt-artifact-spec.md)** - Understand prompt structure\r\n- **[Testing Guide](docs/testing-guide.md)** - Write and run tests\r\n- **[CI/CD Integration](docs/ci-integration.md)** - Set up continuous integration\r\n- **[CLI Reference](docs/cli-reference.md)** - Complete command reference\r\n- **[Examples](docs/examples.md)** - Real-world examples\r\n\r\n## 🤝 Contributing\r\n\r\nWe welcome contributions! This is a developer-first tool built by developers, for developers.\r\n\r\n## 📄 License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n\r\n## 🔗 Links\r\n\r\n- [GitHub Repository](https://github.com/Dogtags27/prompt-lint)\r\n- [Issue Tracker](https://github.com/Dogtags27/prompt-lint/issues)\r\n- [Full Documentation](docs/)\r\n\r\n---\r\n\r\n**Made with ❤️ for developers who care about prompt quality**\r\n","readmeFilename":"README.md","_rev":"1-99ac9536d397e72c63c5176d9b555f68"}