@devshub198211/devguard 2.0.2 → 2.0.3

package/README.md

@@ -1,167 +1,151 @@
-# devguard
+# @devshub198211/devguard
 
-> **One install. 14 features. Zero external dependencies.**  
-> Security · AI Tooling · Auth · DX — everything a production Node.js/TypeScript project needs.
+> **One install. 14 modules. Zero external dependencies.**
+> Security · AI Tooling · Auth · DX — everything a production Node.js project needs.
 
 ```bash
-npm install devguard
-npx devguard        # instant security scan — no install needed
+npm install @devshub198211/devguard
 ```
 
-[![npm](https://img.shields.io/npm/v/devguard)](https://www.npmjs.com/package/devguard)
-[![license](https://img.shields.io/npm/l/devguard)](LICENSE)
-[![node](https://img.shields.io/node/v/devguard)](package.json)
-
----
-
-## Features
-
-| Category | Feature | What it does |
-|----------|---------|-------------|
-| 🔒 Security | `lockfile-guardian` | SHA-512 tamper detection for npm/yarn/pnpm lockfiles |
-| 🔒 Security | `hook-scanner` | 23-rule malware scanner for install scripts (obfuscation-aware) |
-| 🔒 Security | `token-rotator` | Live API verification + age alerts for npm/GitHub tokens |
-| 🔒 Security | `dep-pincer` | Enforce exact version pins + SRI hash verification |
-| 🤖 AI | `agent-schema` | Validate LLM JSON output, auto-retry on malformed responses |
-| 🤖 AI | `mcp-server-kit` | Build Claude-compatible MCP tool servers in minutes |
-| 🤖 AI | `agent-memory` | Durable agent state: Memory / FileSystem / Redis / DynamoDB |
-| 🤖 AI | `llm-budget` | Token counting + cost tracking for OpenAI/Anthropic/Gemini |
-| 🔑 Auth | `zero-trust-jwt` | JWT verify (HS256/RS256/JWKS), revocation, anomaly detection |
-| 🔑 Auth | `bot-fence` | Multi-signal bot detection middleware for Express/Fastify |
-| 🔑 Auth | `passkey-node` | Production WebAuthn passkey registration & authentication |
-| 🛠 DX | `env-safe` | Typed .env validation with built-in parser — fail fast |
-| 🛠 DX | `log-otlp` | Structured JSON logger with OpenTelemetry trace injection |
-| 🛠 DX | `api-contract` | Zero-dep schema builder with full TypeScript type inference |
-
 ---
 
 ## Quick Start
 
-### CLI
 ```bash
-npx devguard                    # full security scan + score
-npx devguard lockfile snapshot  # create baseline after clean install
-npx devguard lockfile verify    # check integrity
-npx devguard hooks              # scan node_modules for malware
-npx devguard pins --fix         # auto-pin unpinned dependencies
-npx devguard tokens --live      # verify tokens via API
-npx devguard --json             # machine-readable output for CI
-```
+# Initialize DevGuard in your project
+npx @devshub198211/devguard init
 
-### Programmatic
-```typescript
-import { runAllChecks } from 'devguard';
+# Run a full security audit
+npx @devshub198211/devguard check
 
-const report = await runAllChecks();
-// { score: 94, passedAll: true, lockfile: {...}, hooks: {...}, ... }
-if (!report.passedAll) process.exit(1);
+# AI-powered code refactor (free, runs locally)
+npx @devshub198211/devguard refactor src/app.ts
 ```
 
-### Tree-shakeable sub-path imports
-```typescript
-import { verifyLockfile } from 'devguard/security';
-import { LLMBudget }      from 'devguard/ai';
-import { JWTVerifier }    from 'devguard/auth';
-import { loadEnv }        from 'devguard/dx';
+For global CLI access:
+```bash
+npm install -g @devshub198211/devguard
+devguard check
 ```
 
 ---
 
-## Examples
+## All 14 Modules
+
+| # | Category | Module | CLI Command | What It Does |
+|---|----------|--------|-------------|--------------|
+| 1 | 🔒 Security | `lockfile-guardian` | `check` / `snapshot` | SHA-512 lockfile tamper detection |
+| 2 | 🔒 Security | `hook-scanner` | `scan` | 23-rule malware scanner for install scripts |
+| 3 | 🔒 Security | `token-rotator` | `tokens` | Live API token verification + age alerts |
+| 4 | 🔒 Security | `dep-pincer` | `pin --fix` | Enforce exact version pins + SRI hashes |
+| 5 | 🤖 AI | `refactor-engine` | `refactor <file>` | Complexity analysis + security patching |
+| 6 | 🤖 AI | `agent-schema` | `schema <json>` | Validate & auto-repair LLM JSON output |
+| 7 | 🤖 AI | `mcp-server-kit` | `mcp` | Build Claude-compatible MCP tool servers |
+| 8 | 🤖 AI | `agent-memory` | `memory --agent <id>` | Durable state for AI agents (FS/Redis) |
+| 9 | 🤖 AI | `llm-budget` | `budget` | Token counting + cost tracking |
+| 10 | 🔑 Auth | `zero-trust-jwt` | `jwt-verify` / `jwt-sign` | JWT sign & verify with anomaly detection |
+| 11 | 🔑 Auth | `bot-fence` | `bot-check --ip <ip>` | Multi-signal bot detection middleware |
+| 12 | 🔑 Auth | `passkey-node` | `passkey-verify` | WebAuthn passkey registration & auth |
+| 13 | 🛠 DX | `env-safe` | `env-verify` | Typed .env validation — fail fast |
+| 14 | 🛠 DX | `log-otlp` | `log --msg <text>` | Structured JSON logger + OpenTelemetry |
+
+**Bonus:** `api-contract` — zero-dep schema builder with TypeScript inference.
 
-### Security — run all checks
-```typescript
-import { runAllChecks } from 'devguard';
-const report = await runAllChecks();
-console.log(`Security score: ${report.score}/100`);
-```
+---
 
-### AI — validate LLM output
-```typescript
-import { c, parseWithRetry } from 'devguard';
-
-const TaskSchema = c.object({
-  title:    c.string().min(1),
-  priority: c.string().enum(["high","medium","low"]),
-  dueDate:  c.string().optional(),
-});
-
-const result = await parseWithRetry(TaskSchema, async (ctx) => {
-  return await callYourLLM(ctx); // your LLM call here
-});
-// result.data is fully typed: { title: string; priority: "high"|"medium"|"low"; dueDate?: string }
-```
+## Use From Any Language (Python, Go, Bash, etc.)
 
-### AI — agent with durable memory
-```typescript
-import { createMemory } from 'devguard';
+Every command supports `--json` output, making DevGuard usable from **any programming language**:
+
+### Python
+```python
+import subprocess, json
 
-// Persists across serverless invocations
-const memory = createMemory({ agentId: 'agent-001', adapter: 'fs', ttl: 7200 });
-await memory.setState({ step: 3, context: 'processing order' });
-await memory.appendHistory('user', 'Cancel my order');
-const history = await memory.getHistory(10); // last 10 messages
+result = subprocess.run(
+    ["npx", "@devshub198211/devguard", "check", "--json"],
+    capture_output=True, text=True
+)
+report = json.loads(result.stdout)
+print(f"Security Score: {report['score']}/100")
 ```
 
-### AI — build an MCP tool server
-```typescript
-import { MCPServerBuilder } from 'devguard';
-
-new MCPServerBuilder('my-tools', '1.0.0')
-  .addTool({
-    name: 'get_weather',
-    description: 'Get weather for a city',
-    inputSchema: { type:'object', properties:{ city:{type:'string'} }, required:['city'] },
-    handler: async ({ city }) => ({ temp: '22°C', city })
-  })
-  .startStdio(); // works with Claude Desktop + any MCP client
+### Go
+```go
+cmd := exec.Command("npx", "@devshub198211/devguard", "scan", "--json")
+output, _ := cmd.Output()
+// Parse JSON output
 ```
 
-### Auth — JWT verification
-```typescript
-import { JWTVerifier } from 'devguard';
+### Bash
+```bash
+SCORE=$(npx @devshub198211/devguard check --json | jq '.score')
+echo "Score: $SCORE"
 
-const verifier = new JWTVerifier({ secret: process.env.JWT_SECRET! });
-const { valid, payload, anomalies } = await verifier.verify(token);
-// anomalies: { score: 0, level: 'safe', warnings: [] }
+# Sign a JWT
+TOKEN=$(devguard jwt-sign --payload '{"sub":"user-1"}' --secret mykey --json | jq -r '.token')
+
+# Check an IP
+devguard bot-check --ip 203.0.113.5 --json | jq '.verdict'
 ```
 
-### Auth — bot detection middleware
-```typescript
-import express from 'express';
-import { createMiddleware, IPRateLimiter } from 'devguard';
-
-const app = express();
-app.use(createMiddleware({
-  blockThreshold: 70,
-  rateLimiter: new IPRateLimiter(100, 60_000)
-}));
+### Ruby
+```ruby
+result = `npx @devshub198211/devguard check --json`
+report = JSON.parse(result)
+puts "Score: #{report['score']}"
 ```
 
-### DX — typed .env validation
-```typescript
-import { loadEnv } from 'devguard';
-
-const env = loadEnv({
-  DATABASE_URL: { type: 'url',     required: true },
-  PORT:         { type: 'integer', default: '3000', min: 1, max: 65535 },
-  NODE_ENV:     { type: 'string',  enum: ['development','production','test'] },
-  API_KEY:      { type: 'string',  required: true, minLength: 32, secret: true },
-});
-// Throws with clear message if invalid. env.PORT is typed as number.
+---
+
+## CLI Reference
+
+```bash
+# Core
+devguard init                                    # Set up project
+devguard check [--json]                          # Full security audit
+devguard refactor <file> [--json]                # AI code refactor
+devguard mcp                                     # Start MCP server
+
+# Security
+devguard snapshot                                # Create lockfile baseline
+devguard scan [--json]                           # Malware scan
+devguard tokens [--json]                         # Token health check
+devguard pin [--fix] [--json]                    # Pin dependencies
+
+# AI
+devguard schema '<json>' [--json]                # Validate JSON
+devguard memory [--agent <id>] [--json]          # Query agent state
+devguard budget [--json]                         # LLM cost summary
+
+# Auth
+devguard jwt-verify --token <t> --secret <s>     # Verify JWT
+devguard jwt-sign --payload '<json>' --secret <s> # Sign JWT
+devguard bot-check --ip <ip> [--json]            # Bot detection
+
+# DX
+devguard env-verify [--file .env] [--json]       # Validate env
+devguard log --msg <text> [--level info|warn|error]  # Emit log
 ```
 
-### DX — structured logging
+---
+
+## Programmatic Usage (Node.js / TypeScript)
+
 ```typescript
-import { createLogger } from 'devguard';
+import { runAllChecks } from '@devshub198211/devguard';
 
-const log = createLogger({ service: 'api', level: 'info' });
-log.info('Request received', { userId: 'u-123', path: '/orders' });
-log.error('Payment failed', { orderId: 'o-456', reason: 'declined' });
+const report = await runAllChecks();
+console.log(`Security Score: ${report.score}/100`);
+if (!report.passedAll) process.exit(1);
+```
+
+### Tree-Shakeable Sub-Path Imports
 
-// Child logger inherits bindings
-const reqLog = log.child({ requestId: 'req-789' });
-reqLog.info('Processing');
+```typescript
+import { verifyLockfile } from '@devshub198211/devguard/security';
+import { LLMBudget }      from '@devshub198211/devguard/ai';
+import { JWTVerifier }    from '@devshub198211/devguard/auth';
+import { loadEnv }        from '@devshub198211/devguard/dx';
 ```
 
 ---
@@ -179,29 +163,36 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: '20' }
       - run: npm ci
-      - run: npx devguard --json > devguard-report.json
-        env:
-          DEVGUARD_TOKENS: NPM_TOKEN,GITHUB_TOKEN
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - uses: actions/upload-artifact@v4
-        with: { name: security-report, path: devguard-report.json }
-      - run: node -e "const r=require('./devguard-report.json'); if(!r.passedAll) process.exit(1)"
+      - run: npx @devshub198211/devguard check --json > report.json
+      - run: node -e "const r=JSON.parse(require('fs').readFileSync('report.json'));if(!r.passedAll)process.exit(1)"
 ```
 
 ---
 
-## Security
+## Security Guarantees
 
 - ✅ **Zero external runtime dependencies** — only Node.js built-ins
-- ✅ **No network calls** at runtime except token inspection (opt-in)
+- ✅ **No network calls** at runtime (except opt-in token verification)
 - ✅ **No telemetry, no tracking, no phone-home**
-- ✅ **Constant-time JWT comparison** — prevents timing attacks
+- ✅ **Constant-time JWT comparison** — timing attack protection
 - ✅ **Sign-count replay protection** in WebAuthn
+- ✅ **Path traversal protection** — all file IDs are SHA-256 hashed
+- ✅ **Prototype pollution prevention** in CBOR/JSON parsers
+- ✅ **Atomic file writes** — no data corruption during crashes
 - ✅ **Works fully offline** — all security checks are local
 
 ---
 
+## Requirements
+
+- Node.js >= 18.0.0
+
 ## License
 
 MIT © DevGuard Contributors
+
+---
+
+*Your custom notes below:*
+
+<!-- Add your personal notes, contact info, or acknowledgments here -->

package/SETUP.md

@@ -1,168 +1,111 @@
-# devguard — Complete Setup, Publish & Monetisation Guide
+# DevGuard Setup Guide
 
-## PART 1: Local Setup
+Get your project secured in under 2 minutes.
 
-### Step 1 — Prerequisites
-```
-node --version   # must be >= 18.0.0
-npm --version    # must be >= 9.0.0
-```
+---
 
-### Step 2 — Unzip & Install
-```
-unzip devguard-final.zip
-cd devguard-final
-npm install
-```
+## Step 1: Install
 
-### Step 3 — Build
+```bash
+npm install @devshub198211/devguard
 ```
-npm run build
-```
-Generates dist/ with CJS + ESM + TypeScript declarations + CLI.
 
-### Step 4 — Test CLI locally
-```
-node dist/cli.js                    # full security scan
-node dist/cli.js lockfile snapshot  # create integrity baseline
-node dist/cli.js lockfile verify    # verify against baseline
-node dist/cli.js hooks              # scan for malicious scripts
-node dist/cli.js pins --fix         # auto-fix unpinned deps
-node dist/cli.js tokens --live      # live API token check
-node dist/cli.js --json             # machine-readable output
-node dist/cli.js help               # all commands
+Or install globally for CLI access anywhere:
+```bash
+npm install -g @devshub198211/devguard
 ```
 
-### Step 5 — Use in your project
-```
-npm install devguard
-```
-
-```typescript
-import { runAllChecks } from 'devguard';
-const report = await runAllChecks();
-console.log(report.score); // 0-100
-if (!report.passedAll) process.exit(1);
+Or run instantly without installing:
+```bash
+npx @devshub198211/devguard check
 ```
 
 ---
 
-## PART 2: Publish to npm
-
-### Step 1 — Create Account
-1. https://www.npmjs.com/signup
-2. Verify email
-3. Enable 2FA (mandatory): https://www.npmjs.com/settings/~/profile
+## Step 2: Initialize Your Project
 
-### Step 2 — Login
-```
-npm login
-npm whoami
+```bash
+devguard init
 ```
 
-### Step 3 — Check name availability
-```
-npm info devguard
-```
-If taken, rename in package.json: "name": "@yourscope/devguard"
+This creates:
+- **`.devguardrc`** — Configuration file for security rules
+- **`.devguard-memory/`** — Local storage for AI agent state
+- **Security snapshot** — Baseline integrity hash of your lockfiles
 
-### Step 4 — Dry run
-```
-npm publish --dry-run --access public
-```
+---
 
-### Step 5 — Publish
-```
-npm run build
-npm publish --access public
-```
+## Step 3: Run Your First Audit
 
-### Step 6 — Verify
-```
-npm info devguard
-npx devguard help
+```bash
+devguard check
 ```
 
-### Step 7 — Update versions
-```
-npm version patch    # 2.0.0 -> 2.0.1
-npm run build
-npm publish --access public
-```
+You'll see a score out of 100. A perfect project scores 100/100.
 
 ---
 
-## PART 3: GitHub Setup
+## Step 4: Refactor Code (Free, Runs Locally)
 
-```
-git init
-git add .
-git commit -m "feat: devguard v2.0.0"
-gh repo create devguard --public --push
+```bash
+devguard refactor src/your-file.ts
 ```
 
-Add CI (.github/workflows/ci.yml):
-```yaml
-name: CI
-on: [push, pull_request]
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '20', cache: 'npm' }
-      - run: npm ci && npm run build
-      - run: node dist/cli.js --json
-```
+This opens a browser window showing:
+- **Original code** on the left
+- **Optimized code** on the right
+- **Time complexity** analysis (e.g., O(n²) → O(n))
+- **Security fixes** applied (eval removal, XSS patches)
+
+Click "Apply" to save the changes.
 
 ---
 
-## PART 4: Monetisation
+## Step 5: Optional — Enable Cloud AI Mode
 
-### Free (builds audience)
-- GitHub Sponsors: github.com/sponsors/onboarding — $5/$15/$50 tiers
-- Polar.sh: polar.sh — connect repo, create paid issues
-- Target: $200-2000/month at 1k+ weekly downloads
+For deeper AI-powered refactoring using Google Gemini:
 
-### Pro SaaS ($19-299/month)
-Create @devguard/pro package with:
-- Web dashboard (Next.js + Stripe + Supabase)
-- Slack/email alerts for stale tokens
-- Team management
-- PDF reports
+1. Get a free API key: https://aistudio.google.com/app/apikey
+2. Set it:
+   ```bash
+   export DEVGUARD_AI_KEY="your_key_here"
+   ```
+3. Run refactor again — it will use Cloud AI automatically.
 
-Pricing: Indie $19 | Team $79 | Enterprise $299
+Without a key, all features still work using the built-in local analysis engine.
 
-### GitHub Marketplace Action
-Publish a scan action, charge per CI minute.
-Guide: github.com/marketplace/actions/new
+---
+
+## Step 6: Add to CI/CD
 
-### VS Code Extension
-Inline warnings for ^ ~ deps, missing env vars, security score in status bar.
-Freemium: free basic, paid Pro ($4.99/month).
+Add this to your GitHub Actions workflow:
 
-### Enterprise ($5k-50k/year)
-Commercial license + SLA + private registry + security audits.
+```yaml
+- run: npx @devshub198211/devguard check --json > report.json
+```
 
 ---
 
-## PART 5: Marketing
+## Troubleshooting
 
-Week 1: npm publish + GitHub + post on r/node + Hacker News Show HN
-Week 2: Blog post + awesome-nodejs PR + newsletter outreach
-Month 1: Product Hunt + YouTube demo + devguard.dev landing page
+| Problem | Solution |
+|---------|----------|
+| `command not found: devguard` | Use `npx @devshub198211/devguard` instead |
+| `missing script` error | Don't use `npm run devguard` — use `npx devguard` |
+| Refactor opens blank page | Wait 2 seconds, then refresh the browser |
+| Score is 0 | Run `devguard init` first to create a baseline |
 
 ---
 
-## Quick Reference
+## Uninstall
 
+```bash
+npm uninstall @devshub198211/devguard
+rm -rf .devguardrc .devguard-memory .devguard-snapshot.json
 ```
-npm install devguard
 
-import { runAllChecks }   from 'devguard';
-import { verifyLockfile } from 'devguard/security';
-import { LLMBudget }      from 'devguard/ai';
-import { JWTVerifier }    from 'devguard/auth';
-import { loadEnv }        from 'devguard/dx';
-```
+---
+
+*Your custom notes below:*
+
+<!-- Add your personal notes here -->

package/dist/ai.d.ts

@@ -162,6 +162,14 @@ declare class LLMBudget {
         remaining: number;
         isExceeded: boolean;
     };
+    report(): {
+        totalCost: number;
+        recordCount: number;
+        monthlyLimitUSD: number;
+        remaining: number;
+        isOverBudget: boolean;
+        warnAtUSD: number | null;
+    };
     getHistory(limit?: number): LLMUsage[];
     reset(): void;
 }

package/dist/ai.js

@@ -1,2 +1,2 @@
-export { AgentMemory, FileSystemAdapter, LLMBudget, MCPServerBuilder, RedisAdapter, cleanLLMOutput, parseSchema, parseWithRetry } from './chunk-4WCL5IUZ.js';
+export { AgentMemory, FileSystemAdapter, LLMBudget, MCPServerBuilder, RedisAdapter, cleanLLMOutput, parseSchema, parseWithRetry } from './chunk-UXM7HRTI.js';
 export { c, c as s } from './chunk-KSFZPDFO.js';

package/dist/{chunk-4WCL5IUZ.js → chunk-UXM7HRTI.js}

@@ -127,7 +127,7 @@ async function parseWithRetry(schema, promptFn, maxRetries = 3) {
 
 // src/ai/mcp-server-kit.ts
 var ERR = { PARSE: -32700, INVALID: -32600, NOT_FOUND: -32601, PARAMS: -32602, INTERNAL: -32603 };
-var MAX_MESSAGE_SIZE = 10 * 1024 * 1024;
+var MAX_MESSAGE_SIZE = 50 * 1024 * 1024;
 var MAX_NAME_LENGTH = 256;
 var HANDLER_TIMEOUT_MS = 3e4;
 function validateToolInput(args, schema) {
@@ -447,7 +447,7 @@ var AgentMemory = class {
     await this.adapter.clear(agentId);
   }
 };
-var MAX_RECORDS = 5e3;
+var MAX_RECORDS = 5e4;
 var LLMBudget = class {
   constructor(config) {
     this.records = [];
@@ -481,6 +481,16 @@ var LLMBudget = class {
       isExceeded: this.totalCost >= this.config.monthlyLimitUSD
     };
   }
+  report() {
+    return {
+      totalCost: this.totalCost,
+      recordCount: this.records.length,
+      monthlyLimitUSD: this.config.monthlyLimitUSD,
+      remaining: Math.max(0, this.config.monthlyLimitUSD - this.totalCost),
+      isOverBudget: this.totalCost >= this.config.monthlyLimitUSD,
+      warnAtUSD: this.config.warnAtUSD ?? null
+    };
+  }
   getHistory(limit = 100) {
     return this.records.slice(-limit);
   }