{"_id":"@devstitch/devflow-guard","name":"@devstitch/devflow-guard","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@devstitch/devflow-guard","version":"1.0.0","description":"A powerful CLI tool for validating and enforcing development workflow best practices in Node.js projects","main":"dist/index.js","types":"dist/index.d.ts","bin":{"devflow-guard":"dist/index.js"},"scripts":{"build":"tsc && node -e \"const fs=require('fs');const f='dist/index.js';const d=fs.readFileSync(f,'utf8');if(!d.startsWith('#!/usr/bin/env node'))fs.writeFileSync(f,'#!/usr/bin/env node\\n'+d);\"","dev":"nodemon --watch src --exec ts-node src/index.ts","test":"jest --passWithNoTests","test:watch":"jest --watch","test:coverage":"jest --coverage","test:local":"node scripts/test-locally.js","test:manual":"echo 'Follow TESTING.md checklist for manual testing'","prepublishOnly":"npm run build && npm test","pack:local":"npm run build && npm pack"},"keywords":["devflow","workflow","validation","linting","code-quality","git-hooks","ci-cd","best-practices","development-tools","project-scanner","rules-engine","typescript","javascript","nodejs"],"author":{"name":"DevStitch","email":"contact@devstitch.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/devstitch/devflow-guard.git"},"bugs":{"url":"https://github.com/devstitch/devflow-guard/issues"},"homepage":"https://github.com/devstitch/devflow-guard#readme","engines":{"node":">=14.0.0"},"dependencies":{"boxen":"^7.1.1","chalk":"^4.1.2","commander":"^11.1.0","fs-extra":"^11.2.0","inquirer":"^8.2.6","ora":"^5.4.1"},"devDependencies":{"@types/fs-extra":"^11.0.4","@types/inquirer":"^8.2.12","@types/jest":"^29.5.11","@types/node":"^20.10.0","jest":"^29.7.0","nodemon":"^3.0.2","ts-jest":"^29.1.1","ts-node":"^10.9.2","typescript":"^5.3.3"},"publishConfig":{"access":"public"},"gitHead":"7a504d07fd3775e078282955168c74f4326b0da5","_id":"@devstitch/devflow-guard@1.0.0","_nodeVersion":"25.1.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-K9eTkF1O0CuNB71YZSd6jA34iyIe4W2z39FXcNAF2sxOtwOznhQGgK0Bngq+iA75HHY3du3Gw2qNm3vPtLhWuA==","shasum":"d079238c1af7f641c7654e651d43485ef77aafe6","tarball":"https://registry.npmjs.org/@devstitch/devflow-guard/-/devflow-guard-1.0.0.tgz","fileCount":40,"unpackedSize":123496,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC+eQfjtIhgSRc27ISSZSzdfBTDTeEa1ZHqgu3Wzuu++gIhAPOw39XEu+8QgV6oGEBqgdFAiXd7f6TioViQ3B4FZmL3"}]},"_npmUser":{"name":"asadchaudhary","email":"assadblogger@gmail.com"},"directories":{},"maintainers":[{"name":"~sab-khan","email":"saboor@devstitch.com"},{"name":"asadchaudhary","email":"assadblogger@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/devflow-guard_1.0.0_1767594985275_0.10860513754951695"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-05T06:36:25.110Z","1.0.0":"2026-01-05T06:36:25.408Z","modified":"2026-01-05T06:36:25.786Z"},"maintainers":[{"name":"~sab-khan","email":"saboor@devstitch.com"},{"name":"asadchaudhary","email":"assadblogger@gmail.com"}],"description":"A powerful CLI tool for validating and enforcing development workflow best practices in Node.js projects","homepage":"https://github.com/devstitch/devflow-guard#readme","keywords":["devflow","workflow","validation","linting","code-quality","git-hooks","ci-cd","best-practices","development-tools","project-scanner","rules-engine","typescript","javascript","nodejs"],"repository":{"type":"git","url":"git+https://github.com/devstitch/devflow-guard.git"},"author":{"name":"DevStitch","email":"contact@devstitch.com"},"bugs":{"url":"https://github.com/devstitch/devflow-guard/issues"},"license":"MIT","readme":"# 🛡️ @devstitch/devflow-guard\r\n\r\n> Smart Development Workflow Guard for Node.js Projects\r\n\r\n[![npm version](https://img.shields.io/npm/v/@devstitch/devflow-guard.svg)](https://www.npmjs.com/package/@devstitch/devflow-guard)\r\n[![npm downloads](https://img.shields.io/npm/dm/@devstitch/devflow-guard.svg)](https://www.npmjs.com/package/@devstitch/devflow-guard)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\nStop pushing buggy code. **devflow-guard** is an intelligent workflow guard that helps developers maintain code quality and follow best practices automatically.\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\n```bash\r\n# Run without installation\r\nnpx @devstitch/devflow-guard init\r\n\r\n# Or install globally\r\nnpm install -g @devstitch/devflow-guard\r\n```\r\n\r\n---\r\n\r\n## 💡 Why devflow-guard?\r\n\r\nDevelopers often:\r\n\r\n- ❌ Forget to follow project standards\r\n- ❌ Push code without running tests\r\n- ❌ Miss environment variable setup\r\n- ❌ Skip quality checks\r\n\r\n**devflow-guard** solves these problems with:\r\n\r\n- ✅ Auto-detection of project type\r\n- ✅ Smart rule enforcement\r\n- ✅ Human-readable error messages\r\n- ✅ Zero configuration setup\r\n\r\n---\r\n\r\n## 📦 Features\r\n\r\n### 🔍 Smart Project Scanner\r\n\r\nAutomatically detects:\r\n\r\n- Framework (Express, Next.js, React, Vue, NestJS, Angular)\r\n- Language (JavaScript/TypeScript)\r\n- Package manager (npm/yarn/pnpm)\r\n- Testing setup (Jest, Mocha, Vitest)\r\n- Linting configuration (ESLint)\r\n\r\n### 🛡️ Built-in Rules\r\n\r\n- **Environment Check** - Ensures .env.example files exist\r\n- **Test Enforcement** - Validates test setup and hooks\r\n- **Console Log Detection** - Warns about console.logs in production code\r\n- **Branch Naming** - Enforces feature/fix/hotfix pattern\r\n- **Commit Message** - Validates commit message format\r\n- **Package.json Validation** - Checks required fields\r\n\r\n### 🎯 Three Simple Commands\r\n\r\n```bash\r\n@devstitch/devflow-guard init     # Setup in 30 seconds\r\n@devstitch/devflow-guard check    # Validate your code\r\n@devstitch/devflow-guard doctor   # Get fix suggestions\r\n```\r\n\r\n---\r\n\r\n## 📖 Usage\r\n\r\n### Initialize in Your Project\r\n\r\n```bash\r\ncd your-project\r\nnpx @devstitch/devflow-guard init\r\n```\r\n\r\nThis will:\r\n\r\n1. Scan your project automatically\r\n2. Create `.devflowrc.json` configuration\r\n3. Setup recommended rules\r\n4. Create `.env.example` if missing\r\n5. Optionally setup git hooks (pre-commit, pre-push)\r\n\r\n**Example output:**\r\n\r\n```\r\n🚀 Initializing devflow-guard...\r\n\r\n📊 Scanning project...\r\n✓ Project scanned successfully!\r\n  Framework: Express\r\n  Language: TypeScript\r\n  Package Manager: npm\r\n  Has Tests: Yes\r\n  Has Linting: Yes\r\n\r\n? Which rules would you like to enable?\r\n? Select strictness level: Moderate\r\n? Would you like to setup git hooks? Yes\r\n\r\n✅ devflow-guard initialized successfully!\r\n```\r\n\r\n### Run Checks Manually\r\n\r\n```bash\r\nnpx @devstitch/devflow-guard check\r\n```\r\n\r\nValidates your project against enabled rules and shows:\r\n\r\n- ✓ Passed checks\r\n- ✗ Failed checks with suggestions\r\n- ⚠ Warnings\r\n- Summary statistics\r\n\r\n**Example output:**\r\n\r\n```\r\n🔍 Running devflow-guard checks...\r\n\r\n📋 Check Results:\r\n\r\n✓ Environment File Check\r\n   .env.example file found\r\n\r\n✗ Console.log Detection\r\n   Found 3 console.log statement(s) in source files\r\n   💡 Remove console.log statements or replace them with a proper logging library.\r\n\r\n📊 Summary:\r\n✓ Passed: 4\r\n✗ Failed: 1\r\n⚠ Warnings: 1\r\n```\r\n\r\n### Get Diagnostic Help\r\n\r\n```bash\r\nnpx @devstitch/devflow-guard doctor\r\n```\r\n\r\nProvides comprehensive diagnostics with:\r\n\r\n- Detailed explanations of issues\r\n- Step-by-step fix instructions\r\n- Documentation links\r\n- Health score (0-100)\r\n\r\n**Example output:**\r\n\r\n```\r\n🏥 Running devflow-guard doctor...\r\n\r\n🔍 Diagnostic Results:\r\n\r\n✗ Environment File Check (warning)\r\n   No .env or .env.example file found\r\n\r\n   Fix Steps:\r\n   1. Create a .env.example file in your project root\r\n   2. Add placeholder values for required environment variables\r\n   3. Document each variable with a comment\r\n\r\n   📚 Documentation: https://github.com/motdotla/dotenv#readme\r\n\r\n📊 Health Score:\r\n   75/100\r\n```\r\n\r\n---\r\n\r\n## 💻 Complete Usage Example\r\n\r\n### Step 1: Initialize in Your Project\r\n\r\n```bash\r\n# Navigate to your project\r\ncd my-express-app\r\n\r\n# Initialize devflow-guard\r\nnpx @devstitch/devflow-guard init\r\n```\r\n\r\n**Interactive Setup:**\r\n\r\n```\r\n🚀 Initializing devflow-guard...\r\n\r\n📊 Scanning project...\r\n✓ Project scanned successfully!\r\n  Framework: Express\r\n  Language: TypeScript\r\n  Package Manager: npm\r\n  Has Tests: Yes\r\n  Has Linting: Yes\r\n\r\n? Which rules would you like to enable?\r\n  ◉ env-file\r\n  ◉ test-before-push\r\n  ◉ console-log\r\n  ◉ package-json\r\n  ◉ branch-naming\r\n  ◉ commit-message\r\n\r\n? Select strictness level: Moderate\r\n\r\n? Would you like to setup git hooks? Yes\r\n\r\n? Which git hooks would you like to setup?\r\n  ◉ pre-commit - Run checks before commit\r\n  ◉ pre-push - Run checks before push\r\n\r\n✅ devflow-guard initialized successfully!\r\n```\r\n\r\n### Step 2: Create .env.example File\r\n\r\nAfter initialization, create `.env.example` file in your project root:\r\n\r\n```bash\r\n# .env.example\r\n# Database Configuration\r\nDATABASE_URL=postgresql://localhost:5432/mydb\r\nDB_PASSWORD=your_password_here\r\n\r\n# API Keys\r\nAPI_KEY=your_api_key_here\r\nSECRET_KEY=your_secret_key_here\r\n\r\n# Server Configuration\r\nPORT=3000\r\nNODE_ENV=development\r\n\r\n# Third-party Services\r\nSTRIPE_SECRET_KEY=sk_test_your_stripe_key\r\nAWS_ACCESS_KEY_ID=your_aws_access_key\r\nAWS_SECRET_ACCESS_KEY=your_aws_secret_key\r\n```\r\n\r\n**Important:**\r\n\r\n- `.env.example` should contain placeholder values (not real secrets)\r\n- Add `.env` to `.gitignore` to keep real values private\r\n- Document each variable with comments\r\n\r\n### Step 3: Use Environment Variables in Your Code\r\n\r\n**Express.js Example:**\r\n\r\n```javascript\r\n// src/index.js\r\nrequire(\"dotenv\").config(); // Load .env file\r\n\r\nconst express = require(\"express\");\r\nconst app = express();\r\n\r\nconst PORT = process.env.PORT || 3000;\r\nconst DATABASE_URL = process.env.DATABASE_URL;\r\nconst API_KEY = process.env.API_KEY;\r\n\r\n// Use environment variables\r\napp.get(\"/api/data\", (req, res) => {\r\n  // API_KEY is available from .env file\r\n  if (req.headers[\"x-api-key\"] !== API_KEY) {\r\n    return res.status(401).json({ error: \"Unauthorized\" });\r\n  }\r\n  res.json({ message: \"Data retrieved successfully\" });\r\n});\r\n\r\napp.listen(PORT, () => {\r\n  console.log(`Server running on port ${PORT}`);\r\n});\r\n```\r\n\r\n**Next.js Example:**\r\n\r\n```typescript\r\n// pages/api/users.ts\r\nexport default function handler(req, res) {\r\n  // Access environment variables\r\n  const apiUrl = process.env.NEXT_PUBLIC_API_URL;\r\n  const dbUrl = process.env.DATABASE_URL; // Server-side only\r\n\r\n  // Use in your API logic\r\n  fetch(`${apiUrl}/users`, {\r\n    headers: {\r\n      Authorization: `Bearer ${process.env.API_KEY}`,\r\n    },\r\n  });\r\n}\r\n```\r\n\r\n### Step 4: Run Checks\r\n\r\n```bash\r\n# Check your project\r\nnpx @devstitch/devflow-guard check\r\n```\r\n\r\n**What happens:**\r\n\r\n- ✅ Checks if `.env.example` exists\r\n- ✅ Validates package.json has required fields\r\n- ✅ Detects console.log statements\r\n- ✅ Verifies test setup\r\n- ✅ Shows summary with pass/fail status\r\n\r\n### Step 5: Fix Issues\r\n\r\nIf checks fail, use the doctor command:\r\n\r\n```bash\r\nnpx @devstitch/devflow-guard doctor\r\n```\r\n\r\nThis will show:\r\n\r\n- What's wrong\r\n- How to fix it\r\n- Step-by-step instructions\r\n\r\n**Example Fix:**\r\n\r\nIf `.env.example` is missing:\r\n\r\n```\r\n✗ Environment File Check (warning)\r\n   No .env or .env.example file found\r\n\r\n   Fix Steps:\r\n   1. Create a .env.example file in your project root\r\n   2. Add placeholder values for required environment variables\r\n   3. Document each variable with a comment\r\n```\r\n\r\n**Solution:**\r\n\r\n```bash\r\n# Create .env.example\r\ntouch .env.example\r\n\r\n# Add your variables\r\necho \"PORT=3000\" >> .env.example\r\necho \"DATABASE_URL=postgresql://localhost:5432/mydb\" >> .env.example\r\n```\r\n\r\n### Step 6: Git Hooks (Automatic Checks)\r\n\r\nIf you enabled git hooks during `init`, checks run automatically:\r\n\r\n**Before Commit:**\r\n\r\n```bash\r\ngit commit -m \"Add new feature\"\r\n# devflow-guard check runs automatically\r\n# Commit blocked if checks fail\r\n```\r\n\r\n**Before Push:**\r\n\r\n```bash\r\ngit push origin main\r\n# devflow-guard check runs automatically\r\n# Push blocked if checks fail\r\n```\r\n\r\n---\r\n\r\n## ⚙️ Configuration\r\n\r\nConfiguration is stored in `.devflowrc.json`:\r\n\r\n```json\r\n{\r\n  \"enabledRules\": [\r\n    \"env-file\",\r\n    \"test-before-push\",\r\n    \"console-log\",\r\n    \"package-json\"\r\n  ],\r\n  \"strictness\": \"moderate\",\r\n  \"gitHooks\": {\r\n    \"enabled\": true,\r\n    \"preCommit\": true,\r\n    \"prePush\": true\r\n  }\r\n}\r\n```\r\n\r\n### Strictness Levels\r\n\r\n- **strict** - All failed rules (errors and warnings) cause exit code 1\r\n- **moderate** - Only errors cause exit code 1 (default)\r\n- **relaxed** - Never fails, only reports issues\r\n\r\n---\r\n\r\n## 📋 Built-in Rules\r\n\r\n| Rule ID            | Name                      | Severity | Description                                    |\r\n| ------------------ | ------------------------- | -------- | ---------------------------------------------- |\r\n| `env-file`         | Environment File Check    | Warning  | Checks if .env.example or .env file exists     |\r\n| `test-before-push` | Test Before Push          | Info     | Validates test scripts and pre-push hooks      |\r\n| `console-log`      | Console.log Detection     | Warning  | Detects console.log statements in source files |\r\n| `branch-naming`    | Branch Naming Convention  | Info     | Validates git branch naming patterns           |\r\n| `commit-message`   | Commit Message Validation | Info     | Checks for commit message validation hooks     |\r\n| `package-json`     | Package.json Validation   | Error    | Validates required fields in package.json      |\r\n\r\n---\r\n\r\n## 🔧 Git Hooks Integration\r\n\r\ndevflow-guard can automatically setup git hooks:\r\n\r\n**Pre-commit Hook:**\r\n\r\n- Runs checks before each commit\r\n- Blocks commits with violations (based on strictness)\r\n\r\n**Pre-push Hook:**\r\n\r\n- Runs checks before pushing to remote\r\n- Ensures code quality before sharing\r\n\r\nTo setup hooks:\r\n\r\n```bash\r\nnpx @devstitch/devflow-guard init\r\n# Select \"Yes\" when asked about git hooks\r\n```\r\n\r\n---\r\n\r\n## 🎨 Supported Frameworks\r\n\r\n- ✅ Express.js\r\n- ✅ Next.js\r\n- ✅ React\r\n- ✅ Vue.js\r\n- ✅ Angular\r\n- ✅ NestJS\r\n- ✅ Any Node.js project\r\n\r\n---\r\n\r\n## 📝 Requirements\r\n\r\n- Node.js >= 14.0.0\r\n- npm, yarn, or pnpm\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nMIT License\r\n\r\nCopyright (c) 2025\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy\r\nof this software and associated documentation files (the \"Software\"), to deal\r\nin the Software without restriction, including without limitation the rights\r\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\ncopies of the Software, and to permit persons to whom the Software is\r\nfurnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all\r\ncopies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\nSOFTWARE.\r\n\r\n---\r\n\r\n## 🔗 Links\r\n\r\n- [npm package](https://www.npmjs.com/package/@devstitch/devflow-guard)\r\n- [GitHub repository](https://github.com/devstitch/devflow-guard)\r\n- [Report an issue](https://github.com/devstitch/devflow-guard/issues)\r\n\r\n---\r\n\r\n## ⭐ Show Your Support\r\n\r\nIf this project helped you, please give it a ⭐ on GitHub!\r\n","readmeFilename":"README.md","_rev":"1-18dd3c0a1ede290a8b59ae093738583d"}