🛡️ @devstitch/devflow-guard

Smart Development Workflow Guard for Node.js Projects

Stop pushing buggy code. devflow-guard is an intelligent workflow guard that helps developers maintain code quality and follow best practices automatically.

🚀 Quick Start

# Run without installation
npx @devstitch/devflow-guard init

# Or install globally
npm install -g @devstitch/devflow-guard

💡 Why devflow-guard?

Developers often:

• ❌ Forget to follow project standards
• ❌ Push code without running tests
• ❌ Miss environment variable setup
• ❌ Skip quality checks

devflow-guard solves these problems with:

• ✅ Auto-detection of project type
• ✅ Smart rule enforcement
• ✅ Human-readable error messages
• ✅ Zero configuration setup

📦 Features

🔍 Smart Project Scanner

Automatically detects:

• Framework (Express, Next.js, React, Vue, NestJS, Angular)
• Language (JavaScript/TypeScript)
• Package manager (npm/yarn/pnpm)
• Testing setup (Jest, Mocha, Vitest)
• Linting configuration (ESLint)

🛡️ Built-in Rules

• Environment Check - Ensures .env.example files exist
• Test Enforcement - Validates test setup and hooks
• Console Log Detection - Warns about console.logs in production code
• Branch Naming - Enforces feature/fix/hotfix pattern
• Commit Message - Validates commit message format
• Package.json Validation - Checks required fields

🎯 Three Simple Commands

@devstitch/devflow-guard init     # Setup in 30 seconds
@devstitch/devflow-guard check    # Validate your code
@devstitch/devflow-guard doctor   # Get fix suggestions

📖 Usage

Initialize in Your Project

cd your-project
npx @devstitch/devflow-guard init

This will:

1. Scan your project automatically
2. Create .devflowrc.json configuration
3. Setup recommended rules
4. Create .env.example if missing
5. Optionally setup git hooks (pre-commit, pre-push)

Example output:

🚀 Initializing devflow-guard...

📊 Scanning project...
✓ Project scanned successfully!
  Framework: Express
  Language: TypeScript
  Package Manager: npm
  Has Tests: Yes
  Has Linting: Yes

? Which rules would you like to enable?
? Select strictness level: Moderate
? Would you like to setup git hooks? Yes

✅ devflow-guard initialized successfully!

Run Checks Manually

npx @devstitch/devflow-guard check

Validates your project against enabled rules and shows:

• ✓ Passed checks
• ✗ Failed checks with suggestions
• ⚠ Warnings
• Summary statistics

Example output:

🔍 Running devflow-guard checks...

📋 Check Results:

✓ Environment File Check
   .env.example file found

✗ Console.log Detection
   Found 3 console.log statement(s) in source files
   💡 Remove console.log statements or replace them with a proper logging library.

📊 Summary:
✓ Passed: 4
✗ Failed: 1
⚠ Warnings: 1

Get Diagnostic Help

npx @devstitch/devflow-guard doctor

Provides comprehensive diagnostics with:

• Detailed explanations of issues
• Step-by-step fix instructions
• Documentation links
• Health score (0-100)

Example output:

🏥 Running devflow-guard doctor...

🔍 Diagnostic Results:

✗ Environment File Check (warning)
   No .env or .env.example file found

   Fix Steps:
   1. Create a .env.example file in your project root
   2. Add placeholder values for required environment variables
   3. Document each variable with a comment

   📚 Documentation: https://github.com/motdotla/dotenv#readme

📊 Health Score:
   75/100

💻 Complete Usage Example

Step 1: Initialize in Your Project

# Navigate to your project
cd my-express-app

# Initialize devflow-guard
npx @devstitch/devflow-guard init

Interactive Setup:

🚀 Initializing devflow-guard...

📊 Scanning project...
✓ Project scanned successfully!
  Framework: Express
  Language: TypeScript
  Package Manager: npm
  Has Tests: Yes
  Has Linting: Yes

? Which rules would you like to enable?
  ◉ env-file
  ◉ test-before-push
  ◉ console-log
  ◉ package-json
  ◉ branch-naming
  ◉ commit-message

? Select strictness level: Moderate

? Would you like to setup git hooks? Yes

? Which git hooks would you like to setup?
  ◉ pre-commit - Run checks before commit
  ◉ pre-push - Run checks before push

✅ devflow-guard initialized successfully!

Step 2: Create .env.example File

After initialization, create .env.example file in your project root:

# .env.example
# Database Configuration
DATABASE_URL=postgresql://localhost:5432/mydb
DB_PASSWORD=your_password_here

# API Keys
API_KEY=your_api_key_here
SECRET_KEY=your_secret_key_here

# Server Configuration
PORT=3000
NODE_ENV=development

# Third-party Services
STRIPE_SECRET_KEY=sk_test_your_stripe_key
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key

Important:

• .env.example should contain placeholder values (not real secrets)
• Add .env to .gitignore to keep real values private
• Document each variable with comments

Step 3: Use Environment Variables in Your Code

Express.js Example:

// src/index.js
require("dotenv").config(); // Load .env file

const express = require("express");
const app = express();

const PORT = process.env.PORT || 3000;
const DATABASE_URL = process.env.DATABASE_URL;
const API_KEY = process.env.API_KEY;

// Use environment variables
app.get("/api/data", (req, res) => {
  // API_KEY is available from .env file
  if (req.headers["x-api-key"] !== API_KEY) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  res.json({ message: "Data retrieved successfully" });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Next.js Example:

// pages/api/users.ts
export default function handler(req, res) {
  // Access environment variables
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  const dbUrl = process.env.DATABASE_URL; // Server-side only

  // Use in your API logic
  fetch(`${apiUrl}/users`, {
    headers: {
      Authorization: `Bearer ${process.env.API_KEY}`,
    },
  });
}

Step 4: Run Checks

# Check your project
npx @devstitch/devflow-guard check

What happens:

• ✅ Checks if .env.example exists
• ✅ Validates package.json has required fields
• ✅ Detects console.log statements
• ✅ Verifies test setup
• ✅ Shows summary with pass/fail status

Step 5: Fix Issues

If checks fail, use the doctor command:

npx @devstitch/devflow-guard doctor

This will show:

• What's wrong
• How to fix it
• Step-by-step instructions

Example Fix:

If .env.example is missing:

✗ Environment File Check (warning)
   No .env or .env.example file found

   Fix Steps:
   1. Create a .env.example file in your project root
   2. Add placeholder values for required environment variables
   3. Document each variable with a comment

Solution:

# Create .env.example
touch .env.example

# Add your variables
echo "PORT=3000" >> .env.example
echo "DATABASE_URL=postgresql://localhost:5432/mydb" >> .env.example

Step 6: Git Hooks (Automatic Checks)

If you enabled git hooks during init, checks run automatically:

Before Commit:

git commit -m "Add new feature"
# devflow-guard check runs automatically
# Commit blocked if checks fail

Before Push:

git push origin main
# devflow-guard check runs automatically
# Push blocked if checks fail

⚙️ Configuration

Configuration is stored in .devflowrc.json:

{
  "enabledRules": [
    "env-file",
    "test-before-push",
    "console-log",
    "package-json"
  ],
  "strictness": "moderate",
  "gitHooks": {
    "enabled": true,
    "preCommit": true,
    "prePush": true
  }
}

Strictness Levels

• strict - All failed rules (errors and warnings) cause exit code 1
• moderate - Only errors cause exit code 1 (default)
• relaxed - Never fails, only reports issues

📋 Built-in Rules

| Rule ID | Name | Severity | Description | | ------------------ | ------------------------- | -------- | ---------------------------------------------- | | env-file | Environment File Check | Warning | Checks if .env.example or .env file exists | | test-before-push | Test Before Push | Info | Validates test scripts and pre-push hooks | | console-log | Console.log Detection | Warning | Detects console.log statements in source files | | branch-naming | Branch Naming Convention | Info | Validates git branch naming patterns | | commit-message | Commit Message Validation | Info | Checks for commit message validation hooks | | package-json | Package.json Validation | Error | Validates required fields in package.json |

🔧 Git Hooks Integration

devflow-guard can automatically setup git hooks:

Pre-commit Hook:

• Runs checks before each commit
• Blocks commits with violations (based on strictness)

Pre-push Hook:

• Runs checks before pushing to remote
• Ensures code quality before sharing

To setup hooks:

npx @devstitch/devflow-guard init
# Select "Yes" when asked about git hooks

🎨 Supported Frameworks

• ✅ Express.js
• ✅ Next.js
• ✅ React
• ✅ Vue.js
• ✅ Angular
• ✅ NestJS
• ✅ Any Node.js project

📝 Requirements

• Node.js >= 14.0.0
• npm, yarn, or pnpm

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🔗 Links

• npm package
• GitHub repository
• Report an issue

⭐ Show Your Support

If this project helped you, please give it a ⭐ on GitHub!