@vinesheg/dev-forge 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+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.

package/README.md

@@ -0,0 +1,323 @@
+[![NPM Version](https://img.shields.io/npm/v/dev-forge)](https://www.npmjs.com/package/dev-forge)
+[![Build Status](https://github.com/vinesheg1/dev-forge/actions/workflows/publish.yml/badge.svg)](https://github.com/vinesheg1/dev-forge/actions)
+[![License](https://img.shields.io/github/license/vinesheg1/dev-forge)](https://github.com/vinesheg1/dev-forge/blob/main/LICENSE)
+# dev-forge
+
+> Zero-config developer toolkit with unified CLI for modern projects
+
+A single-dependency meta-package that provides comprehensive tooling for linting, formatting, Git hooks, and code quality checks.
+
+## Features
+
+✨ **Zero Configuration** - Works out of the box with sensible defaults  
+🔧 **Single Dependency** - Install once, get everything you need  
+⚡ **High Performance** - Powered by Biome and Lefthook  
+🎯 **Comprehensive Checks** - Linting, formatting, dead code detection, and more  
+🪝 **Git Hooks** - Automatic pre-commit and commit-msg validation  
+📦 **Package Standards** - Validates package.json structure and content
+
+## Tools Included
+
+- **[Biome](https://biomejs.dev/)** - Fast linting and formatting for JS/TS/JSON
+- **[Knip](https://knip.dev/)** - Find unused files, dependencies, and exports
+- **[Lefthook](https://github.com/evilmartians/lefthook)** - Fast and powerful Git hooks manager
+- **[Commitlint](https://commitlint.js.org/)** - Enforce conventional commit messages
+- **[Stylelint](https://stylelint.io/)** - Modern CSS/SCSS linter
+- **[npm-package-json-lint](https://npmpackagejsonlint.org/)** - Package.json validator
+
+## Installation
+
+```bash
+npm install -D @vinesheg/dev-forge```
+
+Or with yarn:
+
+```bash
+yarn add --dev @vinesheg/dev-forge
+```
+
+## Quick Start
+
+1. **Initialize the toolkit** in your project:
+
+```bash
+npx forge init
+```
+
+This will:
+- Generate configuration files (biome.json, .stylelintrc.json, etc.)
+- Set up Git hooks via Lefthook
+- Add a `prepare` script to your package.json
+
+2. **Run checks** on your codebase:
+
+```bash
+npx forge check
+```
+
+3. **Auto-fix** issues where possible:
+
+```bash
+npx forge fix
+```
+
+## CLI Commands
+
+### `forge init`
+
+Initialize dev-forge in your project. Creates configuration files and sets up Git hooks.
+
+```bash
+npx forge init [options]
+```
+
+**Options:**
+- `--skip-hooks` - Skip Lefthook installation
+
+**What it does:**
+- Creates `biome.json` that extends toolkit defaults
+- Creates `.stylelintrc.json` for CSS/SCSS linting
+- Creates `.npmpackagejsonlintrc.json` for package.json validation
+- Creates `.commitlintrc.json` for commit message validation
+- Copies `lefthook.yml` for Git hook configuration
+- Installs Git hooks via Lefthook
+- Adds `prepare` script to package.json (runs on `npm install`)
+
+### `forge check`
+
+Run all quality checks on your codebase in parallel.
+
+```bash
+npx forge check [options]
+```
+
+**Options:**
+- `--no-parallel` - Run checks sequentially instead of in parallel
+
+**What it checks:**
+- **Biome**: Lints and checks formatting of JS/TS/JSON files
+- **Stylelint**: Validates CSS/SCSS/Sass files
+- **Knip**: Finds unused files, dependencies, and exports
+- **npm-package-json-lint**: Validates package.json structure
+
+### `forge fix`
+
+Auto-fix issues where possible.
+
+```bash
+npx forge fix
+```
+
+**What it fixes:**
+- **Biome**: Applies automatic fixes and formatting
+- **Stylelint**: Fixes auto-fixable CSS/SCSS issues
+
+## Git Hooks
+
+After running `forge init`, the following Git hooks are automatically installed:
+
+### Pre-commit Hook
+
+Runs before each commit and checks:
+- **Biome** on staged JS/TS/JSON files
+- **Stylelint** on staged CSS/SCSS files
+- **npm-package-json-lint** if package.json is staged
+
+### Commit-msg Hook
+
+Runs after entering a commit message and validates:
+- **Commitlint** enforces [Conventional Commits](https://www.conventionalcommits.org/)
+
+Example valid commit messages:
+```
+feat: add user authentication
+fix: resolve memory leak in worker
+docs: update installation instructions
+chore: upgrade dependencies
+```
+
+## Configuration
+
+All tools come pre-configured with sensible defaults, but you can customize them by editing the generated config files:
+
+### Biome (`biome.json`)
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "extends": ["./node_modules/dev-forge/configs/biome.json"]
+}
+```
+
+Add your own rules or override defaults:
+
+```json
+{
+  "extends": ["./node_modules/dev-forge/configs/biome.json"],
+  "linter": {
+    "rules": {
+      "suspicious": {
+        "noExplicitAny": "off"
+      }
+    }
+  }
+}
+```
+
+### Stylelint (`.stylelintrc.json`)
+
+```json
+{
+  "extends": ["./node_modules/dev-forge/configs/stylelint.json"]
+}
+```
+
+### npm-package-json-lint (`.npmpackagejsonlintrc.json`)
+
+```json
+{
+  "extends": "./node_modules/dev-forge/configs/pkg-lint.json"
+}
+```
+
+### Lefthook (`lefthook.yml`)
+
+The default configuration runs checks on staged files. You can add custom commands:
+
+```yaml
+pre-commit:
+  parallel: true
+  commands:
+    biome:
+      glob: "*.{js,jsx,ts,tsx,json,jsonc}"
+      run: npx biome check --staged {staged_files}
+    
+    custom-script:
+      run: npm run my-custom-check
+```
+
+## Package.json Scripts
+
+Add these to your `package.json` for convenience:
+
+```json
+{
+  "scripts": {
+    "prepare": "forge init",
+    "lint": "forge check",
+    "lint:fix": "forge fix"
+  }
+}
+```
+
+Then use:
+```bash
+npm run lint      # Run all checks
+npm run lint:fix  # Auto-fix issues
+```
+
+## CI/CD Integration
+
+Add dev-forge checks to your CI pipeline:
+
+### GitHub Actions
+
+```yaml
+name: Quality Checks
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+      - run: npm ci
+      - run: npx forge check
+```
+
+### GitLab CI
+
+```yaml
+lint:
+  image: node:18
+  script:
+    - npm ci
+    - npx forge check
+```
+
+## Knip Configuration
+
+Knip automatically detects unused files and dependencies. To customize, create a `knip.json`:
+
+```json
+{
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts"],
+  "ignore": ["**/*.test.ts", "scripts/**"]
+}
+```
+
+## Troubleshooting
+
+### Git hooks not running
+
+If hooks aren't running, try:
+
+```bash
+npx forge init
+```
+
+This will reinstall Lefthook hooks.
+
+### Lefthook installation fails
+
+Make sure you have a `.git` directory:
+
+```bash
+git init
+npx forge init
+```
+
+### Configuration not found
+
+Run the init command to generate config files:
+
+```bash
+npx forge init
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Git (for Git hooks)
+
+## Philosophy
+
+`dev-forge` follows the principle of **convention over configuration**. It provides:
+
+1. **Sensible defaults** that work for most projects
+2. **Easy customization** when you need it
+3. **Minimal setup** - one command to get started
+4. **Fast feedback** - catch issues before they reach CI/CD
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and pull requests are welcome! Please follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.
+
+## Acknowledgments
+
+Built with these excellent tools:
+- [Biome](https://biomejs.dev/)
+- [Knip](https://knip.dev/)
+- [Lefthook](https://github.com/evilmartians/lefthook)
+- [Commitlint](https://commitlint.js.org/)
+- [Stylelint](https://stylelint.io/)
+- [npm-package-json-lint](https://npmpackagejsonlint.org/)

package/bin/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+const { Command } = require("commander");
+const path = require("path");
+const { initToolkit } = require("../lib/init");
+const { runCheck, runFix } = require("../lib/runner");
+
+const program = new Command();
+
+program
+	.name("forge")
+	.description("Zero-config developer toolkit for modern projects")
+	.version(require("../package.json").version);
+
+program
+	.command("init")
+	.description(
+		"Initialize dev-forge in your project (generates configs and sets up Git hooks)",
+	)
+	.option("--skip-hooks", "Skip Lefthook installation")
+	.action(async (options) => {
+		try {
+			await initToolkit(options);
+			console.log("✅ dev-forge initialized successfully!");
+		} catch (error) {
+			console.error("❌ Initialization failed:", error.message);
+			process.exit(1);
+		}
+	});
+
+program
+	.command("check")
+	.description("Run all checks (Biome, Stylelint, Knip, package-json-lint)")
+	.option("--no-parallel", "Run checks sequentially instead of in parallel")
+	.action(async (options) => {
+		try {
+			await runCheck(options);
+			console.log("✅ All checks passed!");
+		} catch (error) {
+			console.error("❌ Checks failed:", error.message);
+			process.exit(1);
+		}
+	});
+
+program
+	.command("fix")
+	.description("Auto-fix issues (Biome and Stylelint)")
+	.action(async () => {
+		try {
+			await runFix();
+			console.log("✅ Auto-fix completed!");
+		} catch (error) {
+			console.error("❌ Auto-fix failed:", error.message);
+			process.exit(1);
+		}
+	});
+
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+	program.outputHelp();
+}

package/configs/biome.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://biomejs.dev",
+  "organizeImports": {
+    "enabled": true
+  },
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"complexity": {
+				"noExtraBooleanCast": "error",
+				"noUselessCatch": "error",
+				"noUselessConstructor": "error",
+				"noUselessLabel": "error",
+				"noUselessRename": "error",
+				"noUselessSwitchCase": "error",
+				"useFlatMap": "warn",
+				"useOptionalChain": "warn",
+				"useSimplifiedLogicExpression": "warn"
+			},
+			"correctness": {
+				"noConstAssign": "error",
+				"noConstantCondition": "error",
+				"noEmptyPattern": "error",
+				"noGlobalObjectCalls": "error",
+				"noInvalidConstructorSuper": "error",
+				"noNonoctalDecimalEscape": "error",
+				"noPrecisionLoss": "error",
+				"noSelfAssign": "error",
+				"noSetterReturn": "error",
+				"noSwitchDeclarations": "error",
+				"noUndeclaredVariables": "error",
+				"noUnreachable": "error",
+				"noUnreachableSuper": "error",
+				"noUnsafeFinally": "error",
+				"noUnsafeOptionalChaining": "error",
+				"noUnusedLabels": "error",
+				"noUnusedVariables": "warn",
+				"useIsNan": "error",
+				"useValidForDirection": "error"
+			},
+			"security": {
+				"noDangerouslySetInnerHtml": "warn",
+				"noDangerouslySetInnerHtmlWithChildren": "error"
+			},
+			"style": {				
+				"useConst": "warn",
+				"useTemplate": "warn"
+			},
+			"suspicious": {
+				"noArrayIndexKey": "warn",
+				"noAssignInExpressions": "warn",
+				"noAsyncPromiseExecutor": "error",
+				"noCatchAssign": "error",
+				"noClassAssign": "error",
+				"noCommentText": "warn",
+				"noCompareNegZero": "error",
+				"noControlCharactersInRegex": "error",
+				"noDebugger": "warn",
+				"noDoubleEquals": "warn",
+				"noDuplicateCase": "error",
+				"noDuplicateClassMembers": "error",
+				"noDuplicateObjectKeys": "error",
+				"noDuplicateParameters": "error",
+				"noEmptyBlockStatements": "warn",
+				"noExplicitAny": "warn",
+				"noExtraNonNullAssertion": "error",
+				"noFallthroughSwitchClause": "error",
+				"noFunctionAssign": "error",
+				"noGlobalAssign": "error",
+				"noImportAssign": "error",
+				"noMisleadingCharacterClass": "error",
+				"noPrototypeBuiltins": "warn",
+				"noRedeclare": "error",
+				"noShadowRestrictedNames": "error",
+				"noUnsafeNegation": "error",
+				"useGetterReturn": "error"
+			}
+		}
+	},
+	"formatter": {
+		"enabled": true,
+		"formatWithErrors": false,
+		"indentStyle": "space",
+		"indentWidth": 2,
+		"lineWidth": 100,
+		"lineEnding": "lf"
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "single",
+			"jsxQuoteStyle": "double",
+			"trailingCommas": "es5",
+			"semicolons": "always",
+			"arrowParentheses": "always",
+			"bracketSpacing": true,
+			"bracketSameLine": false
+		}
+	},
+	"json": {
+		"formatter": {
+			"enabled": true,
+			"indentWidth": 2
+		},
+		"parser": {
+			"allowComments": true,
+			"allowTrailingCommas": false
+		}
+	}
+}

package/configs/lefthook.yml

@@ -0,0 +1,22 @@
+pre-commit:
+  parallel: true
+  commands:
+    biome:
+      glob: "*.{js,jsx,ts,tsx,json,jsonc}"
+      run: npx biome check --staged {staged_files}
+      stage_fixed: true
+    
+    stylelint:
+      glob: "*.{css,scss,sass}"
+      run: npx stylelint {staged_files}
+      stage_fixed: true
+    
+    package-json-lint:
+      files: git diff --name-only --cached
+      glob: "package.json"
+      run: npx npmPkgJsonLint .
+
+commit-msg:
+  commands:
+    commitlint:
+      run: npx commitlint --edit {1}

package/configs/pkg-lint.json

@@ -0,0 +1,54 @@
+{
+	"rules": {
+		"require-author": "error",
+		"require-description": "error",
+		"require-keywords": "warning",
+		"require-license": "error",
+		"require-name": "error",
+		"require-repository": "warning",
+		"require-version": "error",
+		"valid-values-author": ["error", ["string", "object"]],
+		"valid-values-license": [
+			"error",
+			["MIT", "Apache-2.0", "BSD-3-Clause", "ISC", "GPL-3.0", "UNLICENSED"]
+		],
+		"name-format": "error",
+		"version-format": "error",
+		"description-format": "error",
+		"prefer-alphabetical-dependencies": "warning",
+		"prefer-alphabetical-devDependencies": "warning",
+		"prefer-alphabetical-peerDependencies": "warning",
+		"prefer-alphabetical-optionalDependencies": "warning",
+		"prefer-no-engineStrict": "error",
+		"no-duplicate-properties": "error",
+		"prefer-property-order": [
+			"warning",
+			[
+				"name",
+				"version",
+				"description",
+				"keywords",
+				"author",
+				"license",
+				"homepage",
+				"repository",
+				"bugs",
+				"main",
+				"module",
+				"types",
+				"exports",
+				"bin",
+				"files",
+				"scripts",
+				"dependencies",
+				"devDependencies",
+				"peerDependencies",
+				"optionalDependencies",
+				"engines"
+			]
+		],
+		"require-scripts": "warning",
+		"no-absolute-version-dependencies": "warning",
+		"no-absolute-version-devDependencies": "warning"
+	}
+}

package/configs/stylelint.json

@@ -0,0 +1,52 @@
+{
+	"extends": "stylelint-config-standard",
+	"rules": {
+		"at-rule-no-unknown": [
+			true,
+			{
+				"ignoreAtRules": [
+					"tailwind",
+					"apply",
+					"variants",
+					"responsive",
+					"screen",
+					"layer",
+					"mixin",
+					"include",
+					"extend",
+					"function",
+					"return",
+					"if",
+					"else",
+					"each",
+					"for",
+					"while"
+				]
+			}
+		],
+		"color-hex-length": "short",
+		"color-named": "never",
+		"declaration-block-no-redundant-longhand-properties": true,
+		"declaration-no-important": true,
+		"font-family-name-quotes": "always-where-recommended",
+		"font-weight-notation": "numeric",
+		"function-url-quotes": "always",
+		"max-nesting-depth": 4,
+		"no-descending-specificity": null,
+		"number-max-precision": 4,
+		"selector-class-pattern": null,
+		"selector-id-pattern": null,
+		"selector-max-compound-selectors": 4,
+		"selector-max-id": 0,
+		"selector-max-specificity": "0,4,0",
+		"selector-max-universal": 1,
+		"selector-no-qualifying-type": [
+			true,
+			{
+				"ignore": ["attribute", "class"]
+			}
+		],
+		"shorthand-property-no-redundant-values": true,
+		"value-keyword-case": "lower"
+	}
+}

package/index.js

@@ -0,0 +1,29 @@
+/**
+ * dev-forge
+ * Zero-config developer toolkit with unified CLI
+ */
+
+const { initToolkit } = require("./lib/init");
+const {
+	runCheck,
+	runFix,
+	runBiomeStaged,
+	runStylelintStaged,
+	getToolBin,
+	runCommand,
+} = require("./lib/runner");
+
+module.exports = {
+	// Initialization
+	initToolkit,
+
+	// Runners
+	runCheck,
+	runFix,
+	runBiomeStaged,
+	runStylelintStaged,
+
+	// Utilities
+	getToolBin,
+	runCommand,
+};

package/lib/init.js

@@ -0,0 +1,170 @@
+const fs = require("fs-extra");
+const path = require("path");
+const execa = require("execa");
+
+const CWD = process.cwd();
+const TOOLKIT_ROOT = path.join(__dirname, "..");
+
+/**
+ * Initialize the toolkit in the user's project
+ * This function is idempotent - safe to run multiple times
+ */
+async function initToolkit(options = {}) {
+	console.log("🔧 Initializing dev-forge...\n");
+
+	// Step 1: Generate local config files that extend the toolkit's configs
+	await generateConfigFiles();
+
+	// Step 2: Initialize Lefthook (Git hooks)
+	if (!options.skipHooks) {
+		await initializeLefthook();
+	}
+
+	// Step 3: Update package.json with prepare script
+	await updatePackageJson();
+
+	console.log("\n📦 Configuration files created:");
+	console.log("   - biome.json");
+	console.log("   - .stylelintrc.json");
+	console.log("   - .npmpackagejsonlintrc.json");
+	console.log("   - .commitlintrc.json");
+	console.log("   - lefthook.yml");
+}
+
+/**
+ * Generate config files that extend the toolkit's internal configs
+ */
+async function generateConfigFiles() {
+	const configs = [
+		{
+			name: "biome.json",
+			content: {
+				$schema: "https://biomejs.dev/schemas/1.9.4/schema.json",
+				extends: [
+					path
+						.relative(CWD, path.join(TOOLKIT_ROOT, "configs/biome.json"))
+						.replace(/\\/g, "/"),
+				],
+			},
+		},
+		{
+			name: ".stylelintrc.json",
+			content: {
+				extends: [
+					path
+						.relative(CWD, path.join(TOOLKIT_ROOT, "configs/stylelint.json"))
+						.replace(/\\/g, "/"),
+				],
+			},
+		},
+		{
+			name: ".npmpackagejsonlintrc.json",
+			content: {
+				extends: path
+					.relative(CWD, path.join(TOOLKIT_ROOT, "configs/pkg-lint.json"))
+					.replace(/\\/g, "/"),
+			},
+		},
+		{
+			name: ".commitlintrc.json",
+			content: {
+				extends: ["@commitlint/config-conventional"],
+			},
+		},
+	];
+
+	for (const config of configs) {
+		const configPath = path.join(CWD, config.name);
+
+		// Only create if doesn't exist (idempotent)
+		if (!(await fs.pathExists(configPath))) {
+			await fs.writeJson(configPath, config.content, { spaces: 2 });
+			console.log(`   ✓ Created ${config.name}`);
+		} else {
+			console.log(`   ⊙ ${config.name} already exists (skipped)`);
+		}
+	}
+
+	// Copy lefthook.yml directly (it doesn't support extends)
+	const lefthookSrc = path.join(TOOLKIT_ROOT, "configs/lefthook.yml");
+	const lefthookDest = path.join(CWD, "lefthook.yml");
+
+	if (!(await fs.pathExists(lefthookDest))) {
+		await fs.copy(lefthookSrc, lefthookDest);
+		console.log("   ✓ Created lefthook.yml");
+	} else {
+		console.log("   ⊙ lefthook.yml already exists (skipped)");
+	}
+}
+
+/**
+ * Initialize Lefthook Git hooks
+ */
+async function initializeLefthook() {
+	console.log("\n🪝 Installing Git hooks...");
+
+	try {
+		const lefthookBin = path.join(TOOLKIT_ROOT, "node_modules/.bin/lefthook");
+
+		// Check if .git directory exists
+		const gitDir = path.join(CWD, ".git");
+		if (!(await fs.pathExists(gitDir))) {
+			console.log(
+				"   ⚠ No .git directory found. Skipping Git hooks installation.",
+			);
+			console.log('   Run "git init" first, then run "forge init" again.');
+			return;
+		}
+
+		await execa(lefthookBin, ["install"], {
+			cwd: CWD,
+			stdio: "inherit",
+		});
+
+		console.log("   ✓ Lefthook installed successfully");
+	} catch (error) {
+		console.error("   ⚠ Lefthook installation failed:", error.message);
+		console.error('   You may need to run "lefthook install" manually.');
+	}
+}
+
+/**
+ * Update user's package.json to include the prepare script
+ */
+async function updatePackageJson() {
+	console.log("\n📝 Updating package.json...");
+
+	const pkgPath = path.join(CWD, "package.json");
+
+	if (!(await fs.pathExists(pkgPath))) {
+		console.log("   ⚠ No package.json found in current directory");
+		return;
+	}
+
+	const pkg = await fs.readJson(pkgPath);
+
+	// Initialize scripts if it doesn't exist
+	if (!pkg.scripts) {
+		pkg.scripts = {};
+	}
+
+	// Add prepare script if it doesn't exist or doesn't include forge init
+	const prepareScript = "forge init";
+
+	if (!pkg.scripts.prepare) {
+		pkg.scripts.prepare = prepareScript;
+		await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+		console.log('   ✓ Added "prepare" script to package.json');
+	} else if (!pkg.scripts.prepare.includes("forge init")) {
+		// Append to existing prepare script
+		pkg.scripts.prepare = `${pkg.scripts.prepare} && ${prepareScript}`;
+		await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+		console.log('   ✓ Updated "prepare" script in package.json');
+	} else {
+		console.log('   ⊙ "prepare" script already includes forge init (skipped)');
+	}
+}
+
+module.exports = {
+	initToolkit,
+};

package/lib/runner.js

@@ -0,0 +1,187 @@
+const execa = require("execa");
+const path = require("path");
+const fs = require("fs-extra");
+
+const CWD = process.cwd();
+const TOOLKIT_ROOT = path.join(__dirname, "..");
+
+/**
+ * Get the path to a tool's binary in the toolkit's node_modules
+ */
+function getToolBin(toolName) {
+	return path.join(TOOLKIT_ROOT, "node_modules/.bin", toolName);
+}
+
+/**
+ * Run a command and handle output
+ */
+async function runCommand(command, args, options = {}) {
+	const toolName = path.basename(command);
+	console.log(`\n🔍 Running ${toolName}...`);
+
+	try {
+		const result = await execa(command, args, {
+			cwd: CWD,
+			stdio: "inherit",
+			...options,
+		});
+
+		console.log(`✅ ${toolName} completed successfully`);
+		return result;
+	} catch (error) {
+		console.error(`❌ ${toolName} failed`);
+		throw error;
+	}
+}
+
+/**
+ * Run all checks in parallel or sequentially
+ */
+async function runCheck(options = {}) {
+	console.log("🔎 Running comprehensive checks...\n");
+
+	const checks = [
+		async () => {
+			// Biome check
+			const biomeBin = getToolBin("biome");
+			return runCommand(biomeBin, ["check", "."]);
+		},
+		async () => {
+			// Stylelint check
+			const stylelintBin = getToolBin("stylelint");
+			const patterns = ["**/*.css", "**/*.scss", "**/*.sass"];
+
+			// Check if any style files exist
+			let hasStyleFiles = false;
+			for (const pattern of patterns) {
+				const files = await fs.pathExists(
+					path.join(CWD, pattern.split("/")[0]),
+				);
+				if (files) {
+					hasStyleFiles = true;
+					break;
+				}
+			}
+
+			if (!hasStyleFiles) {
+				console.log("\n⊙ Stylelint skipped (no style files found)");
+				return;
+			}
+
+			return runCommand(stylelintBin, patterns);
+		},
+		async () => {
+			// Knip check
+			const knipBin = getToolBin("knip");
+			return runCommand(knipBin, []);
+		},
+		async () => {
+			// npm-package-json-lint
+			const pkgLintBin = getToolBin("npmPkgJsonLint");
+			const pkgPath = path.join(CWD, "package.json");
+
+			if (!(await fs.pathExists(pkgPath))) {
+				console.log("\n⊙ package-json-lint skipped (no package.json found)");
+				return;
+			}
+
+			return runCommand(pkgLintBin, ["."]);
+		},
+	];
+
+	if (options.parallel !== false) {
+		// Run in parallel
+		const results = await Promise.allSettled(checks.map((check) => check()));
+
+		const failures = results.filter((r) => r.status === "rejected");
+		if (failures.length > 0) {
+			throw new Error(`${failures.length} check(s) failed`);
+		}
+	} else {
+		// Run sequentially
+		for (const check of checks) {
+			await check();
+		}
+	}
+}
+
+/**
+ * Run auto-fix operations
+ */
+async function runFix() {
+	console.log("🔧 Running auto-fix operations...\n");
+
+	// Biome fix
+	const biomeBin = getToolBin("biome");
+	await runCommand(biomeBin, ["check", "--write", "."]);
+
+	// Stylelint fix
+	const stylelintBin = getToolBin("stylelint");
+	const patterns = ["**/*.css", "**/*.scss", "**/*.sass"];
+
+	try {
+		await runCommand(stylelintBin, [...patterns, "--fix"], { reject: false });
+	} catch (error) {
+		// Stylelint might fail if no files found, which is okay
+		console.log(
+			"   ⊙ Stylelint fix completed (some files may not have been fixable)",
+		);
+	}
+}
+
+/**
+ * Run Biome on staged files (for Git hooks)
+ */
+async function runBiomeStaged(files) {
+	if (!files || files.length === 0) {
+		console.log("⊙ No staged files to check");
+		return;
+	}
+
+	const biomeBin = getToolBin("biome");
+	const jsFiles = files.filter((f) => /\.(js|jsx|ts|tsx|json|jsonc)$/.test(f));
+
+	if (jsFiles.length === 0) {
+		return;
+	}
+
+	console.log(`🔍 Checking ${jsFiles.length} file(s) with Biome...`);
+	await execa(biomeBin, ["check", ...jsFiles], {
+		cwd: CWD,
+		stdio: "inherit",
+	});
+}
+
+/**
+ * Run Stylelint on staged files (for Git hooks)
+ */
+async function runStylelintStaged(files) {
+	if (!files || files.length === 0) {
+		console.log("⊙ No staged style files to check");
+		return;
+	}
+
+	const stylelintBin = getToolBin("stylelint");
+	const styleFiles = files.filter((f) => /\.(css|scss|sass)$/.test(f));
+
+	if (styleFiles.length === 0) {
+		return;
+	}
+
+	console.log(
+		`🎨 Checking ${styleFiles.length} style file(s) with Stylelint...`,
+	);
+	await execa(stylelintBin, styleFiles, {
+		cwd: CWD,
+		stdio: "inherit",
+	});
+}
+
+module.exports = {
+	runCheck,
+	runFix,
+	runBiomeStaged,
+	runStylelintStaged,
+	getToolBin,
+	runCommand,
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "@vinesheg/dev-forge",
+	"version": "1.0.2",
+	"publishConfig": {
+		"access": "public"
+	},
+	"description": "Zero-config developer toolkit with unified CLI for linting, formatting, and Git hooks",
+	"keywords": [
+		"developer-tools",
+		"linting",
+		"formatting",
+		"git-hooks",
+		"biome",
+		"lefthook",
+		"knip",
+		"commitlint",
+		"stylelint"
+	],
+	"author": "Vinesh EG <vinesheg@gmail.com>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/vinesheg1/dev-forge.git"
+	},
+	"bugs": {
+		"url": "https://github.com/vinesheg1/dev-forge/issues"
+	},
+	"homepage": "https://github.com/vinesheg1/dev-forge#readme",
+	"main": "index.js",
+	"types": "index.d.ts",
+	"bin": {
+		"forge": "bin/cli.js"
+	},
+	"files": [
+		"bin",
+		"lib",
+		"configs",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"dependencies": {
+		"@biomejs/biome": "^2.3.14",
+		"@commitlint/cli": "^19.5.0",
+		"@commitlint/config-conventional": "^19.5.0",
+		"commander": "^12.1.0",
+		"execa": "^5.1.1",
+		"fs-extra": "^11.2.0",
+		"knip": "^5.38.2",
+		"lefthook": "^1.9.3",
+		"npm-package-json-lint": "^8.0.0",
+		"stylelint": "^16.10.0",
+		"stylelint-config-standard": "^36.0.1"
+	},
+	"devDependencies": {
+		"@types/node": "^20.17.6"
+	},
+	"scripts": {
+		"forge": "node ./bin/cli.js",
+		"test": "echo \"Error: no test specified\" && exit 1"
+	}
+}