🛡️ @devstitch/devflow-guard

> Smart Development Workflow Guard for Node.js Projects

![npm version](https://www.npmjs.com/package/@devstitch/devflow-guard)
![npm downloads](https://www.npmjs.com/package/@devstitch/devflow-guard)
![License: MIT](https://opensource.org/licenses/MIT)

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

---

🚀 Quick Start

bash

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



$3



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)



$3



- 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



$3

bash

@devstitch/devflow-guard init     # Setup in 30 seconds

@devstitch/devflow-guard check    # Validate your code

@devstitch/devflow-guard doctor   # Get fix suggestions





---



📖 Usage



$3

bash

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!

$3

bash

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

$3

bash

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



$3

bash

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!





$3



After initialization, create

.env.example

 file in your project root:

bash

.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



$3



Express.js Example:

javascript

// 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:

typescript

// 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}

,

    },

  });

}

$3

bash

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



$3



If checks fail, use the doctor command:

bash

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:

bash

Create .env.example

touch .env.example



Add your variables

echo "PORT=3000" >> .env.example

echo "DATABASE_URL=postgresql://localhost:5432/mydb" >> .env.example





$3



If you enabled git hooks during

init

, checks run automatically:



Before Commit:

bash

git commit -m "Add new feature"

devflow-guard check runs automatically

Commit blocked if checks fail





Before Push:

bash

git push origin main

devflow-guard check runs automatically

Push blocked if checks fail





---



⚙️ Configuration



Configuration is stored in

.devflowrc.json

json

{

  "enabledRules": [

    "env-file",

    "test-before-push",

    "console-log",

    "package-json"

  ],

  "strictness": "moderate",

  "gitHooks": {

    "enabled": true,

    "preCommit": true,

    "prePush": true

  }

}





$3



- 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:

bash

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!

🛡️ @devstitch/devflow-guard

🚀 Quick Start

bash

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



$3



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)



$3



- 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



$3

bash

@devstitch/devflow-guard init     # Setup in 30 seconds

@devstitch/devflow-guard check    # Validate your code

@devstitch/devflow-guard doctor   # Get fix suggestions





---



📖 Usage



$3

bash

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!

$3

bash

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

$3

bash

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



$3

bash

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!





$3



After initialization, create

.env.example

 file in your project root:

bash

.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



$3



Express.js Example:

javascript

// 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:

typescript

// 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}

,

    },

  });

}

$3

bash

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



$3



If checks fail, use the doctor command:

bash

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:

bash

Create .env.example

touch .env.example



Add your variables

echo "PORT=3000" >> .env.example

echo "DATABASE_URL=postgresql://localhost:5432/mydb" >> .env.example





$3



If you enabled git hooks during

init

, checks run automatically:



Before Commit:

bash

git commit -m "Add new feature"

devflow-guard check runs automatically

Commit blocked if checks fail





Before Push:

bash

git push origin main

devflow-guard check runs automatically

Push blocked if checks fail





---



⚙️ Configuration



Configuration is stored in

.devflowrc.json

json

{

  "enabledRules": [

    "env-file",

    "test-before-push",

    "console-log",

    "package-json"

  ],

  "strictness": "moderate",

  "gitHooks": {

    "enabled": true,

    "preCommit": true,

    "prePush": true

  }

}





$3



- 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:

bash

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

🔗 Links

- npm package
- GitHub repository
- Report an issue

---

⭐ Show Your Support

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