{"id":47317328,"url":"https://github.com/monkfromearth/carveman","last_synced_at":"2026-03-17T16:10:23.879Z","repository":{"id":301241906,"uuid":"1008492358","full_name":"monkfromearth/carveman","owner":"monkfromearth","description":"Transform your Postman Collections into Git-friendly file structures and back again!","archived":false,"fork":false,"pushed_at":"2025-06-26T11:31:19.000Z","size":128,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-02T14:17:16.819Z","etag":null,"topics":["api","collections","postman","postman-api","postman-collection"],"latest_commit_sha":null,"homepage":"https://npmjs.com/carveman","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monkfromearth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T16:16:45.000Z","updated_at":"2025-06-30T10:29:06.000Z","dependencies_parsed_at":"2025-06-25T22:07:09.586Z","dependency_job_id":"8a58b0c3-976e-4d4c-89e8-26fe01166c8d","html_url":"https://github.com/monkfromearth/carveman","commit_stats":null,"previous_names":["monkfromearth/carveman"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/monkfromearth/carveman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fcarveman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fcarveman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fcarveman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fcarveman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monkfromearth","download_url":"https://codeload.github.com/monkfromearth/carveman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fcarveman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30626921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T14:16:03.965Z","status":"ssl_error","status_checked_at":"2026-03-17T14:16:03.380Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","collections","postman","postman-api","postman-collection"],"created_at":"2026-03-17T16:10:22.909Z","updated_at":"2026-03-17T16:10:23.872Z","avatar_url":"https://github.com/monkfromearth.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🪓 Carveman - Postman Collection Carver\n\n\u003cdiv align=\"center\"\u003e\n\n**Transform your Postman Collections into Git-friendly file structures and back again!**\n\n[![npm version](https://badge.fury.io/js/carveman.svg)](https://www.npmjs.com/package/carveman)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Built with Bun](https://img.shields.io/badge/Built%20with-Bun-ff69b4.svg)](https://bun.sh/)\n\n*Stop wrestling with massive JSON files. Start collaborating on APIs like a pro.*\n\n[🚀 Quick Start](#-quick-start) • [📖 Documentation](#-commands) • [💡 Examples](#-real-world-examples) • [🤝 Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Why Carveman?\n\n**The Problem:** Postman Collections are stored as monolithic JSON files that are:\n- 😤 **Impossible to diff** meaningfully in Git\n- 🚫 **Merge conflicts galore** when teams collaborate  \n- 🔍 **Hard to review** - who changed what endpoint?\n- 📦 **Bloated repositories** with huge JSON blobs\n\n**The Solution:** Carveman carves your collections into organized, readable file structures:\n\n```\nBefore (1 file):                    After (organized structure):\nmy-api.postman_collection.json  →   my-api/\n                                    ├── index.json          # Collection metadata\n                                    ├── auth/\n                                    │   ├── index.json      # Folder info\n                                    │   ├── login.json      # Individual requests\n                                    │   └── refresh.json\n                                    ├── users/\n                                    │   ├── index.json\n                                    │   ├── get_users.json\n                                    │   ├── create_user.json\n                                    │   └── update_user.json\n                                    └── variables.json      # Collection variables\n```\n\n## ✨ Features That Make Teams Happy\n\n- **🔄 Perfect Round-Trip**: Split → Edit → Build → Deploy seamlessly\n- **👥 Git-Native Collaboration**: Meaningful diffs, easy merges, granular reviews\n- **🏗️ Organized Structure**: Logical folder hierarchies with clean naming\n- **🛡️ Production Ready**: Built-in validation, error handling, and safety checks\n- **⚡ Lightning Fast**: Powered by Bun for optimal performance\n- **🔍 Preview Mode**: Dry-run to see changes before applying\n- **📝 Verbose Logging**: Know exactly what's happening\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Install globally (recommended)\nnpm install -g carveman\n\n# Or use with npx (no installation)\nnpx carveman --help\n\n# Or with bun\nbun install -g carveman\n```\n\n### 30-Second Demo\n\n```bash\n# 1. Split your collection into files\ncarveman split my-api.postman_collection.json\n\n# 2. Edit individual request files with your favorite editor\ncode my-api/users/create_user.json\n\n# 3. Rebuild the collection\ncarveman build my-api --output updated-collection.json\n\n# 4. Import back into Postman and you're done! 🎉\n```\n\n## 📋 Commands\n\n### `split` - Carve Collection into Files\n\nTransform a monolithic Postman Collection into an organized file structure.\n\n```bash\ncarveman split \u003ccollection.json\u003e [options]\n```\n\n**Options:**\n- `--output, -o \u003cdirectory\u003e` - Where to create the file structure\n- `--overwrite` - Replace existing files without asking\n- `--dry-run` - Preview what would be created (safe!)\n- `--verbose, -v` - Show detailed progress\n\n**Examples:**\n```bash\n# Basic split\ncarveman split api.postman_collection.json\n\n# Custom output location with preview\ncarveman split api.json --output ./src/api --dry-run\n\n# Force overwrite with detailed logging\ncarveman split api.json --output ./api --overwrite --verbose\n```\n\n### `build` - Reconstruct Collection\n\nRebuild a Postman Collection from your organized file structure.\n\n```bash\ncarveman build \u003cdirectory\u003e [options]\n```\n\n**Options:**\n- `--output, -o \u003cfile\u003e` - Output JSON file name\n- `--validate` - Validate against Postman schema\n- `--verbose, -v` - Show detailed progress\n\n**Examples:**\n```bash\n# Basic build\ncarveman build ./my-api\n\n# Custom output with validation\ncarveman build ./api --output production-api.json --validate\n\n# Verbose build for debugging\ncarveman build ./api --verbose\n```\n\n### `help` \u0026 `version`\n\n```bash\ncarveman help           # Show general help\ncarveman help split     # Command-specific help\ncarveman version        # Show version info\n```\n\n## 🏗️ File Structure Explained\n\nCarveman creates an intuitive structure that mirrors your collection:\n\n```\nmy-collection/\n├── index.json              # 📋 Collection metadata, variables, auth\n├── users/                  # 📁 Folder from your collection\n│   ├── index.json          # 📋 Folder metadata and request order\n│   ├── get_users.json      # 📄 Individual request\n│   ├── create_user.json    # 📄 Individual request\n│   └── profile/            # 📁 Nested folder\n│       ├── index.json      # 📋 Nested folder metadata\n│       └── get_profile.json # 📄 Nested request\n└── health_check.json       # 📄 Root-level request\n```\n\n### File Types\n\n| File             | Purpose                 | Contains                                                  |\n| ---------------- | ----------------------- | --------------------------------------------------------- |\n| **`index.json`** | Metadata \u0026 Organization | Collection/folder info, variables, auth, request ordering |\n| **`*.json`**     | Individual Requests     | Complete request details, headers, body, tests, examples  |\n\n### Naming Magic ✨\n\nCarveman automatically handles naming:\n- `User Management` → `user_management/`\n- `Get User Profile` → `get_user_profile.json`\n- Special characters are safely removed\n- Duplicates get numbered suffixes\n- Reserved names are avoided\n\n## 💡 Real-World Examples\n\n### 🔄 Team Collaboration Workflow\n\n```bash\n# Team lead splits the main collection\ncarveman split company-api.json --output ./api-structure\n\n# Commit the organized structure\ngit add api-structure/\ngit commit -m \"Split API collection for better collaboration\"\ngit push origin main\n\n# Developer A works on user endpoints\ncd api-structure/users/\n# Edit get_users.json, create_user.json, etc.\ngit add . \u0026\u0026 git commit -m \"Add pagination to user endpoints\"\n\n# Developer B works on auth\ncd api-structure/auth/\n# Edit login.json, refresh.json, etc.\ngit add . \u0026\u0026 git commit -m \"Update OAuth2 flow\"\n\n# Before deployment, rebuild the collection\ncarveman build ./api-structure --output production-api.json --validate\n```\n\n### 🚀 CI/CD Integration\n\n```yaml\n# .github/workflows/api-validation.yml\nname: API Collection Validation\non: [push, pull_request]\n\njobs:\n  validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: oven-sh/setup-bun@v1\n      \n      - name: Install Carveman\n        run: npm install -g carveman\n        \n      - name: Validate API Structure\n        run: carveman build ./api-structure --validate\n        \n      - name: Generate Collection Artifact\n        run: carveman build ./api-structure --output dist/api-collection.json\n        \n      - name: Upload Collection\n        uses: actions/upload-artifact@v3\n        with:\n          name: api-collection\n          path: dist/api-collection.json\n```\n\n### 🔍 Code Review Made Easy\n\n**Before Carveman:**\n```diff\n- Reviewing 5000-line JSON blob\n- \"What changed in the user endpoints?\"\n- Merge conflicts everywhere\n```\n\n**After Carveman:**\n```diff\napi-structure/users/create_user.json\n+ \"header\": [\n+   {\n+     \"key\": \"Content-Type\", \n+     \"value\": \"application/json\"\n+   }\n+ ]\n\napi-structure/auth/login.json  \n- \"url\": \"{{base_url}}/login\"\n+ \"url\": \"{{base_url}}/v2/auth/login\"\n```\n\n### 📦 Environment Management\n\n```bash\n# Development environment\ncarveman split dev-api.json --output ./environments/dev\n\n# Staging environment  \ncarveman split staging-api.json --output ./environments/staging\n\n# Production environment\ncarveman split prod-api.json --output ./environments/prod\n\n# Easy comparison and sync between environments\ndiff -r ./environments/dev ./environments/prod\n```\n\n## 🛠️ Advanced Usage\n\n### Working with Large Collections\n\n```bash\n# Use verbose mode to track progress\ncarveman split huge-collection.json --verbose\n\n# Preview structure first\ncarveman split huge-collection.json --dry-run | grep \"📁\\|📄\"\n\n# Split with custom organization\ncarveman split api.json --output ./src/api-specs\n```\n\n### Automation Scripts\n\n```bash\n#!/bin/bash\n# auto-sync.sh - Keep collections in sync\n\necho \"🔄 Syncing API collections...\"\n\n# Split latest from Postman export\ncarveman split latest-export.json --output ./api --overwrite\n\n# Commit changes\ngit add api/\ngit commit -m \"Auto-sync: $(date)\"\n\n# Rebuild for deployment\ncarveman build ./api --output deploy/api-collection.json --validate\n\necho \"✅ Sync complete!\"\n```\n\n### Custom Workflows\n\n```bash\n# Split multiple collections\nfor collection in *.postman_collection.json; do\n  name=$(basename \"$collection\" .postman_collection.json)\n  carveman split \"$collection\" --output \"./collections/$name\"\ndone\n\n# Batch rebuild\nfind ./collections -type d -name \"*.api\" -exec carveman build {} \\;\n```\n\n## 🧪 Testing \u0026 Validation\n\nCarveman includes comprehensive validation:\n\n```bash\n# Validate collection structure\ncarveman build ./api --validate --verbose\n\n# Check for common issues\ncarveman split problematic.json --dry-run --verbose\n```\n\n**Common Validations:**\n- ✅ Postman Collection v2.1 schema compliance\n- ✅ Required fields (`info`, `item`) presence\n- ✅ Valid JSON structure\n- ✅ Circular reference detection\n- ✅ File system safety checks\n\n## 🐛 Troubleshooting\n\n### Common Issues \u0026 Solutions\n\n**❌ \"Collection must have an 'info' object\"**\n```bash\n# Your JSON might not be a valid Postman Collection\n# Check the file format and schema version\ncarveman split your-file.json --verbose\n```\n\n**❌ \"Directory already exists\"**\n```bash\n# Use --overwrite or choose different output\ncarveman split api.json --output ./api-v2\n# or\ncarveman split api.json --overwrite\n```\n\n**❌ \"Build fails with validation errors\"**\n```bash\n# Use verbose mode to see detailed errors\ncarveman build ./api --validate --verbose\n\n# Check for missing files or corrupted structure\nfind ./api -name \"*.json\" -exec echo \"Checking: {}\" \\; -exec cat {} \\; \u003e /dev/null\n```\n\n**❌ Import issues in Node.js**\n```bash\n# Make sure you're using a recent Node.js version (18+)\nnode --version\n\n# Try with npx instead\nnpx carveman split your-collection.json\n```\n\n### Getting Help\n\n```bash\n# Command-specific help\ncarveman help split\ncarveman help build\n\n# Verbose output for debugging  \ncarveman split file.json --verbose\ncarveman build directory --verbose\n```\n\n## 📊 Schema Support\n\n**Full Postman Collection Format v2.1 Support:**\n\n| Feature            | Status       | Notes                                     |\n| ------------------ | ------------ | ----------------------------------------- |\n| ✅ Requests         | Full Support | All HTTP methods, headers, body types     |\n| ✅ Folders          | Full Support | Nested folder structures preserved        |\n| ✅ Variables        | Full Support | Collection, environment, global variables |\n| ✅ Authentication   | Full Support | Bearer, Basic, API Key, OAuth, etc.       |\n| ✅ Scripts          | Full Support | Pre-request and test scripts              |\n| ✅ Examples         | Full Support | Request/response examples                 |\n| ✅ Headers          | Full Support | Dynamic and static headers                |\n| ✅ Request Bodies   | Full Support | JSON, form-data, raw, binary              |\n| ✅ Query Parameters | Full Support | Static and dynamic parameters             |\n\n## 🚀 Performance\n\nCarveman is built for speed:\n\n- **⚡ Bun Runtime**: 3x faster than Node.js for file operations\n- **🔄 Streaming Processing**: Handles large collections efficiently  \n- **💾 Memory Efficient**: Processes files incrementally\n- **🎯 Optimized Bundling**: Single executable with minimal dependencies\n\n**Benchmarks:**\n- Small collection (10 requests): ~50ms\n- Medium collection (100 requests): ~200ms  \n- Large collection (1000+ requests): ~2s\n\n## 🛠️ Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) v1.0+\n- Node.js v18+ (for compatibility testing)\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/monkfromearth/carveman.git\ncd carveman\n\n# Install dependencies\nbun install\n\n# Development mode\nbun run dev split example.json\n\n# Build for production\nbun run build\n\n# Run tests\nbun test\n\n# Run specific tests\nbun test --grep \"split command\"\n```\n\n### Project Structure\n\n```\nsrc/\n├── cli/                    # 🖥️  CLI argument parsing\n├── commands/               # ⚙️  Split and build implementations  \n├── fs/                     # 📁 File system operations\n├── parser/                 # 🔍 Postman collection parsing\n├── types/                  # 📝 TypeScript definitions\n├── utils/                  # 🛠️  Utility functions\n└── index.ts               # 🚀 Main entry point\n\ntests/\n├── unit/                   # 🧪 Unit tests\n├── integration/            # 🔗 Integration tests\n└── fixtures/              # 📋 Test data\n```\n\n### Contributing Workflow\n\n1. **Fork \u0026 Clone**: `git clone your-fork-url`\n2. **Create Branch**: `git checkout -b feature/amazing-feature`\n3. **Make Changes**: Follow the coding standards\n4. **Add Tests**: Ensure good coverage\n5. **Test**: `bun test` and manual testing\n6. **Commit**: `git commit -m 'Add amazing feature'`\n7. **Push**: `git push origin feature/amazing-feature`\n8. **PR**: Open a Pull Request with good description\n\n## 🤝 Contributing\n\nWe love contributions! Here's how you can help:\n\n### 🐛 Found a Bug?\n- Check [existing issues](https://github.com/monkfromearth/carveman/issues)\n- Create a [new issue](https://github.com/monkfromearth/carveman/issues/new) with:\n  - Clear description\n  - Steps to reproduce\n  - Expected vs actual behavior\n  - Your environment details\n\n### 💡 Have an Idea?\n- Check [discussions](https://github.com/monkfromearth/carveman/discussions)\n- Open a [feature request](https://github.com/monkfromearth/carveman/issues/new)\n- Consider implementing it yourself!\n\n### 📖 Improve Documentation?\n- Fix typos, add examples, clarify instructions\n- Documentation PRs are always welcome\n\n### Code Style\n\n- **TypeScript**: Strict mode enabled\n- **Naming**: snake_case for variables, camelCase for functions, PascalCase for classes\n- **Testing**: Add tests for new features\n- **Comments**: Document complex logic\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- 🔥 **[Bun](https://bun.sh/)** - For the amazing runtime that makes this fast\n- 📮 **[Postman](https://www.postman.com/)** - For the excellent API platform and collection format\n- 🌟 **Open Source Community** - For inspiration and feedback\n- 💼 **API Developers Everywhere** - This tool is for you!\n\n## 📞 Support \u0026 Community\n\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/monkfromearth/carveman/issues)\n- 💡 **Feature Requests**: [GitHub Issues](https://github.com/monkfromearth/carveman/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/monkfromearth/carveman/discussions)\n- 📖 **Documentation**: [GitHub Wiki](https://github.com/monkfromearth/carveman/wiki)\n- 🐦 **Updates**: Follow [@monkfromearth](https://twitter.com/monkfromearth) for updates\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for API developers who believe in clean, collaborative workflows**\n\n*Stop fighting with JSON. Start carving with Carveman.* 🪓\n\n[⬆️ Back to Top](#-carveman---postman-collection-carver)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkfromearth%2Fcarveman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonkfromearth%2Fcarveman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkfromearth%2Fcarveman/lists"}