forged-cli 0.1.0 → 0.2.0

package/bin/forged.js

@@ -1,8 +1,17 @@
 #!/usr/bin/env node
 
-const [,, command] = process.argv;
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+const [,, command, ...args] = process.argv;
 
 const commands = {
+  readme:  'Generate a README.md for the current project',
+  scan:    'Audit dependencies for typosquats, bad scripts, and suspicious binaries',
   init:    'Scaffold a new dev environment',
   new:     'Create a new project with GitHub setup',
   install: 'Install Forged into an existing shell config',
@@ -23,11 +32,22 @@ ${Object.entries(commands).map(([cmd, desc]) => `    ${cmd.padEnd(10)} ${desc}`)
 }
 
 if (command === 'version') {
-  const { createRequire } = await import('module');
-  const require = createRequire(import.meta.url);
-  const { version } = require('../package.json');
   console.log(`forged-cli v${version}`);
   process.exit(0);
 }
 
+if (command === 'readme') {
+  const { readmeCommand } = await import('../src/commands/readme.js');
+  await readmeCommand(args[0] || 'README.md');
+  process.exit(0);
+}
+
+if (command === 'scan') {
+  const { scanCommand } = await import('../src/commands/scan.js');
+  const report       = args.includes('--report') || args.includes('--report-md');
+  const reportFormat = args.includes('--report-md') ? 'markdown' : 'json';
+  await scanCommand(process.cwd(), { report, reportFormat });
+  process.exit(0);
+}
+
 console.log(`⚒  Forged — '${command}' coming soon.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forged-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A complete dev environment toolkit — shell, workflows, and project scaffolding in one install.",
   "keywords": [
     "cli",
@@ -29,5 +29,8 @@
   },
   "scripts": {
     "start": "node bin/forged.js"
+  },
+  "dependencies": {
+    "inquirer": "^13.4.2"
   }
 }

package/src/commands/readme.js

@@ -0,0 +1,84 @@
+import { createRequire } from 'module';
+import { writeFile, mkdir } from 'fs/promises';
+import { resolve } from 'path';
+import { detectProjectInfo } from '../utils/detectProject.js';
+import { generateMarkdown } from '../utils/generateMarkdown.js';
+
+const require = createRequire(import.meta.url);
+const { prompt } = require('inquirer');
+
+const green  = '\x1b[32m';
+const purple = '\x1b[35m';
+const reset  = '\x1b[0m';
+
+export async function readmeCommand(outputPath = 'README.md') {
+  const detected = detectProjectInfo();
+
+  console.log(`\n${green}⚒  Forged README Generator${reset}`);
+  if (detected.github) console.log(`   Detected GitHub user: ${detected.github}`);
+  console.log('   Press Enter to accept defaults.\n');
+
+  const answers = await prompt([
+    {
+      type: 'input',
+      name: 'title',
+      message: `${green}Project name:${reset}`,
+      default: detected.title,
+    },
+    {
+      type: 'input',
+      name: 'description',
+      message: `${green}Short description:${reset}`,
+    },
+    {
+      type: 'input',
+      name: 'toDo',
+      message: `${green}To-do items (leave blank to skip section):${reset}`,
+    },
+    {
+      type: 'list',
+      name: 'license',
+      message: `${green}License:${reset}`,
+      choices: ['MIT', 'APACHE 2.0', 'GPL 3.0', 'BSD 3', 'None'],
+    },
+    {
+      type: 'input',
+      name: 'installation',
+      message: `${green}Install command:${reset}`,
+      default: detected.installCommand,
+    },
+    {
+      type: 'input',
+      name: 'test',
+      message: `${green}Test command:${reset}`,
+      default: detected.testCommand,
+    },
+    {
+      type: 'input',
+      name: 'usage',
+      message: `${green}Usage instructions:${reset}`,
+    },
+    {
+      type: 'input',
+      name: 'contributing',
+      message: `${green}Contributing guidelines:${reset}`,
+      default: 'Fork the project and open a pull request with your changes',
+    },
+    {
+      type: 'input',
+      name: 'github',
+      message: `${green}GitHub username:${reset}`,
+      default: detected.github,
+    },
+    {
+      type: 'input',
+      name: 'email',
+      message: `${green}Email address:${reset}`,
+      default: detected.email,
+    },
+  ]);
+
+  const markdown = generateMarkdown(answers);
+  await writeFile(resolve(outputPath), markdown, 'utf8');
+  console.log(`\n${purple}✔  README written to ${outputPath}${reset}\n`);
+}

package/src/commands/scan.js

@@ -0,0 +1,231 @@
+import { readFileSync, existsSync, readdirSync, statSync, writeFileSync } from 'fs';
+import { createHash } from 'crypto';
+import { join, basename } from 'path';
+import { isSuspiciousName } from '../utils/levenshtein.js';
+import { POPULAR_PACKAGES } from '../utils/popularPackages.js';
+import { verifyTarballIntegrity } from '../utils/verifyIntegrity.js';
+
+const green  = '\x1b[32m';
+const yellow = '\x1b[33m';
+const red    = '\x1b[31m';
+const bold   = '\x1b[1m';
+const reset  = '\x1b[0m';
+
+function checkPackageJson(cwd) {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return { deps: {}, error: 'No package.json found' };
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return {
+      deps: { ...pkg.dependencies, ...pkg.devDependencies },
+      scripts: pkg.scripts || {},
+      name: pkg.name,
+      version: pkg.version,
+    };
+  } catch {
+    return { deps: {}, error: 'Could not parse package.json' };
+  }
+}
+
+function scanBinaries(cwd) {
+  const binDir = join(cwd, 'node_modules', '.bin');
+  if (!existsSync(binDir)) return [];
+  const results = [];
+  for (const file of readdirSync(binDir)) {
+    const fullPath = join(binDir, file);
+    try {
+      const stat = statSync(fullPath);
+      if (!stat.isSymbolicLink() && stat.size > 50000) {
+        results.push({ file, size: stat.size, flag: 'large non-symlink binary' });
+      }
+    } catch {}
+  }
+  return results;
+}
+
+function checkDangerousScripts(scripts) {
+  const dangerous = [];
+  const patterns = [
+    /curl\s+.*\|.*sh/,
+    /wget\s+.*\|.*sh/,
+    /eval\s*\(/,
+    /base64\s+--decode/,
+    /python\s+-c/,
+    /exec\s*\(/,
+  ];
+  for (const [name, cmd] of Object.entries(scripts)) {
+    for (const pattern of patterns) {
+      if (pattern.test(cmd)) {
+        dangerous.push({ script: name, command: cmd });
+      }
+    }
+  }
+  return dangerous;
+}
+
+function saveJsonReport(reportPath, data) {
+  writeFileSync(reportPath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+function saveMarkdownReport(reportPath, data) {
+  const { meta, findings } = data;
+  const lines = [
+    `# Forged Scan Report`,
+    ``,
+    `**Project:** ${meta.project}`,
+    `**Scanned:** ${meta.scannedAt}`,
+    `**Packages verified:** ${meta.packagesVerified}`,
+    `**Summary:** ${findings.errors.length} error(s), ${findings.warnings.length} warning(s)`,
+    ``,
+  ];
+
+  if (findings.errors.length > 0) {
+    lines.push(`## Errors`, ``);
+    for (const e of findings.errors) {
+      lines.push(`- ❌ **${e.package ? `${e.package}@${e.version}` : 'project'}**: ${e.message}`);
+      if (e.detail) {
+        lines.push(`  - locked:   \`${e.detail.locked}\``);
+        lines.push(`  - registry: \`${e.detail.registry}\``);
+      }
+    }
+    lines.push(``);
+  }
+
+  if (findings.warnings.length > 0) {
+    lines.push(`## Warnings`, ``);
+    for (const w of findings.warnings) {
+      lines.push(`- ⚠️  **${w.package ? `${w.package}@${w.version}` : 'project'}**: ${w.message}`);
+    }
+    lines.push(``);
+  }
+
+  if (findings.errors.length === 0 && findings.warnings.length === 0) {
+    lines.push(`## Result`, ``, `✅ No issues found. All packages verified clean.`, ``);
+  }
+
+  writeFileSync(reportPath, lines.join('\n'), 'utf8');
+}
+
+export async function scanCommand(cwd = process.cwd(), opts = {}) {
+  const { report, reportFormat = 'json' } = opts;
+
+  console.log(`\n${bold}⚒  Forged Scanner${reset}`);
+  console.log(`   Scanning: ${cwd}\n`);
+
+  const findings = { warnings: [], errors: [], info: [] };
+  let packagesVerified = 0;
+
+  // 1. Parse package.json
+  const { deps, scripts, error, name: pkgName, version: pkgVersion } = checkPackageJson(cwd);
+  if (error) findings.errors.push({ message: error });
+
+  // 2. Dangerous scripts
+  if (scripts) {
+    for (const d of checkDangerousScripts(scripts)) {
+      findings.errors.push({ message: `Dangerous script "${d.script}": ${d.command}` });
+    }
+  }
+
+  // 3. Typosquat check
+  for (const name of Object.keys(deps)) {
+    for (const { known, distance } of isSuspiciousName(name, POPULAR_PACKAGES)) {
+      findings.warnings.push({
+        package: name,
+        message: `${distance} character(s) from popular package "${known}" — possible typosquat`,
+      });
+    }
+  }
+
+  // 4. Tarball integrity verification
+  process.stdout.write('   Verifying tarball integrity');
+  const { error: integrityError, findings: integrityFindings, total } = await verifyTarballIntegrity(
+    cwd,
+    (checked, t) => {
+      if (checked % 10 === 0 || checked === t) {
+        process.stdout.write(`\r   Verifying tarball integrity (${checked}/${t})...`);
+      }
+    }
+  );
+  process.stdout.write('\n');
+
+  if (integrityError) {
+    findings.warnings.push({ message: integrityError });
+  } else {
+    packagesVerified = total || 0;
+    for (const f of integrityFindings) {
+      (f.type === 'error' ? findings.errors : findings.warnings).push(f);
+    }
+    if (total) findings.info.push(`Verified ${total} packages against npm registry`);
+  }
+
+  // 5. Binary scan
+  for (const b of scanBinaries(cwd)) {
+    findings.warnings.push({
+      message: `node_modules/.bin/${b.file} is a large non-symlink binary (${(b.size / 1024).toFixed(1)}KB)`,
+    });
+  }
+
+  // Print results
+  if (findings.errors.length === 0 && findings.warnings.length === 0) {
+    console.log(`${green}✔  No issues found. Looks clean.${reset}\n`);
+  } else {
+    if (findings.errors.length > 0) {
+      console.log(`${red}${bold}ERRORS (${findings.errors.length}):${reset}`);
+      for (const e of findings.errors) {
+        const label = e.package ? `${e.package}@${e.version}: ` : '';
+        console.log(`  ${red}✖${reset}  ${label}${e.message}`);
+        if (e.detail) {
+          console.log(`       locked:   ${e.detail.locked}`);
+          console.log(`       registry: ${e.detail.registry}`);
+        }
+      }
+      console.log();
+    }
+
+    if (findings.warnings.length > 0) {
+      console.log(`${yellow}${bold}WARNINGS (${findings.warnings.length}):${reset}`);
+      for (const w of findings.warnings) {
+        const label = w.package ? `${w.package}@${w.version}: ` : '';
+        console.log(`  ${yellow}⚠${reset}  ${label}${w.message}`);
+      }
+      console.log();
+    }
+  }
+
+  if (findings.info.length > 0) {
+    for (const i of findings.info) console.log(`  ${green}ℹ${reset}  ${i}`);
+    console.log();
+  }
+
+  console.log(`${bold}Summary:${reset} ${findings.errors.length} error(s), ${findings.warnings.length} warning(s)\n`);
+
+  // Save report if requested
+  if (report) {
+    const reportData = {
+      meta: {
+        project: pkgName || basename(cwd),
+        version: pkgVersion || 'unknown',
+        scannedAt: new Date().toISOString(),
+        packagesVerified,
+        cwd,
+      },
+      findings,
+      summary: {
+        errors: findings.errors.length,
+        warnings: findings.warnings.length,
+        clean: findings.errors.length === 0 && findings.warnings.length === 0,
+      },
+    };
+
+    const ext = reportFormat === 'markdown' ? 'md' : 'json';
+    const reportFile = join(cwd, `forged-report.${ext}`);
+
+    if (reportFormat === 'markdown') {
+      saveMarkdownReport(reportFile, reportData);
+    } else {
+      saveJsonReport(reportFile, reportData);
+    }
+
+    console.log(`${green}✔  Report saved: ${reportFile}${reset}\n`);
+  }
+}

package/src/utils/detectProject.js

@@ -0,0 +1,48 @@
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { basename, resolve } from 'path';
+
+export function detectProjectInfo() {
+  const cwd = process.cwd();
+  const info = {
+    title: basename(cwd),
+    github: '',
+    email: '',
+    installCommand: 'npm i',
+    testCommand: 'npm test',
+  };
+
+  // Pull GitHub username + email from git config
+  try {
+    const remoteUrl = execSync('git remote get-url origin 2>/dev/null', { stdio: ['pipe', 'pipe', 'ignore'] })
+      .toString().trim();
+    const match = remoteUrl.match(/github\.com[:/]([^/]+)/);
+    if (match) info.github = match[1];
+  } catch {}
+
+  try {
+    info.email = execSync('git config user.email', { stdio: ['pipe', 'pipe', 'ignore'] })
+      .toString().trim();
+  } catch {}
+
+  // Detect stack and set install/test defaults
+  if (existsSync('package.json')) {
+    try {
+      const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+      if (pkg.scripts?.test && !pkg.scripts.test.includes('no test')) {
+        info.testCommand = 'npm test';
+      }
+    } catch {}
+  } else if (existsSync('requirements.txt')) {
+    info.installCommand = 'pip install -r requirements.txt';
+    info.testCommand = 'pytest';
+  } else if (existsSync('Cargo.toml')) {
+    info.installCommand = 'cargo build';
+    info.testCommand = 'cargo test';
+  } else if (existsSync('go.mod')) {
+    info.installCommand = 'go mod download';
+    info.testCommand = 'go test ./...';
+  }
+
+  return info;
+}

package/src/utils/generateMarkdown.js

@@ -0,0 +1,44 @@
+import { renderLicenseBadge, renderLicenseLink, renderLicenseSection } from './licenseUtils.js';
+
+export function generateMarkdown(data) {
+  return `# ${data.title}
+${renderLicenseBadge(data.license)}
+
+## Description
+${data.description}
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+${data.toDo ? '- [To Do](#to-do)\n' : ''}- [Test](#test)
+- [Contributing](#contributing)
+${renderLicenseLink(data.license)}
+- [Questions](#questions)
+${data.toDo ? `
+## To Do
+${data.toDo}
+` : ''}
+## Installation
+\`\`\`sh
+${data.installation}
+\`\`\`
+
+## Usage
+${data.usage}
+
+## Test
+\`\`\`sh
+${data.test}
+\`\`\`
+
+## Contributing
+${data.contributing}
+
+${renderLicenseSection(data.license)}
+
+## Questions
+Questions? Email me at ${data.email}.
+See more of my work at [github.com/${data.github}](https://github.com/${data.github}).
+`;
+}

package/src/utils/levenshtein.js

@@ -0,0 +1,25 @@
+// Levenshtein distance — catches typosquatted package names
+export function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) =>
+    Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+  );
+  for (let i = 1; i <= m; i++)
+    for (let j = 1; j <= n; j++)
+      dp[i][j] = a[i-1] === b[j-1]
+        ? dp[i-1][j-1]
+        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+  return dp[m][n];
+}
+
+export function isSuspiciousName(name, popularPackages, threshold = 2) {
+  const suspects = [];
+  for (const known of popularPackages) {
+    if (name === known) continue;
+    const dist = levenshtein(name, known);
+    if (dist > 0 && dist <= threshold) {
+      suspects.push({ known, distance: dist });
+    }
+  }
+  return suspects;
+}

package/src/utils/licenseUtils.js

@@ -0,0 +1,14 @@
+export function renderLicenseBadge(license) {
+  if (!license || license === 'None') return '';
+  return `![License](https://img.shields.io/badge/license-${encodeURIComponent(license)}-blue.svg)`;
+}
+
+export function renderLicenseLink(license) {
+  if (!license || license === 'None') return '';
+  return '- [License](#license)';
+}
+
+export function renderLicenseSection(license) {
+  if (!license || license === 'None') return '';
+  return `## License\nThis project is licensed under the ${license} license.`;
+}

package/src/utils/popularPackages.js

@@ -0,0 +1,20 @@
+// Top npm packages by download count — used for typosquat detection
+export const POPULAR_PACKAGES = [
+  'lodash', 'chalk', 'react', 'express', 'axios', 'moment', 'typescript',
+  'webpack', 'babel', 'eslint', 'prettier', 'jest', 'mocha', 'nodemon',
+  'dotenv', 'cors', 'body-parser', 'mongoose', 'sequelize', 'prisma',
+  'next', 'nuxt', 'vite', 'rollup', 'esbuild', 'turbo', 'nx',
+  'inquirer', 'commander', 'yargs', 'minimist', 'ora', 'boxen', 'figlet',
+  'uuid', 'nanoid', 'crypto', 'bcrypt', 'jsonwebtoken', 'passport',
+  'socket.io', 'ws', 'fastify', 'koa', 'hapi', 'restify',
+  'sharp', 'jimp', 'multer', 'formidable', 'busboy',
+  'redis', 'ioredis', 'pg', 'mysql2', 'sqlite3', 'knex',
+  'zod', 'yup', 'joi', 'ajv', 'class-validator',
+  'rxjs', 'immer', 'zustand', 'redux', 'mobx', 'recoil',
+  'date-fns', 'dayjs', 'luxon', 'validator', 'sanitize-html',
+  'cheerio', 'puppeteer', 'playwright', 'cypress',
+  'tar', 'archiver', 'adm-zip', 'node-fetch', 'got', 'superagent',
+  'cross-env', 'rimraf', 'glob', 'chokidar', 'fs-extra', 'mkdirp',
+  'semver', 'debug', 'winston', 'pino', 'morgan',
+  'pm2', 'concurrently', 'husky', 'lint-staged', 'commitizen',
+];

package/src/utils/verifyIntegrity.js

@@ -0,0 +1,127 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// Fetch registry metadata with a simple in-memory cache to avoid duplicate requests
+const registryCache = new Map();
+
+async function fetchRegistryMeta(name) {
+  if (registryCache.has(name)) return registryCache.get(name);
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}`);
+    if (!res.ok) return null;
+    const data = await res.json();
+    registryCache.set(name, data);
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function parseLockfile(cwd) {
+  const lockPath = join(cwd, 'package-lock.json');
+  if (!existsSync(lockPath)) return null;
+  try {
+    return JSON.parse(readFileSync(lockPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export async function verifyTarballIntegrity(cwd, onProgress) {
+  const lock = parseLockfile(cwd);
+  if (!lock) return { error: 'No package-lock.json found — run npm install first', findings: [] };
+
+  const packages = lock.packages || {};
+  const entries = Object.entries(packages).filter(
+    ([path, meta]) => path && path !== '' && meta.version && meta.integrity && !meta.link
+  );
+
+  if (entries.length === 0) return { error: null, findings: [] };
+
+  const findings = [];
+  let checked = 0;
+
+  // Batch requests — 5 at a time to avoid hammering the registry
+  const batchSize = 5;
+  for (let i = 0; i < entries.length; i += batchSize) {
+    const batch = entries.slice(i, i + batchSize);
+
+    await Promise.all(batch.map(async ([pkgPath, meta]) => {
+      // Handle nested node_modules (e.g. "node_modules/pkg/node_modules/dep" → "dep")
+      const name = pkgPath.replace(/^.*node_modules\//, '');
+
+      const registryMeta = await fetchRegistryMeta(name);
+      checked++;
+      if (onProgress) onProgress(checked, entries.length, name);
+
+      if (!registryMeta) {
+        findings.push({
+          type: 'warning',
+          package: name,
+          version: meta.version,
+          message: 'Could not reach registry — unable to verify',
+        });
+        return;
+      }
+
+      // Package not found on registry at all — highly suspicious
+      if (registryMeta.error === 'Not found') {
+        findings.push({
+          type: 'error',
+          package: name,
+          version: meta.version,
+          message: 'Package not found on npm registry — could be a private or malicious package',
+        });
+        return;
+      }
+
+      const versionData = registryMeta.versions?.[meta.version];
+      if (!versionData) {
+        findings.push({
+          type: 'warning',
+          package: name,
+          version: meta.version,
+          message: `Version ${meta.version} not found on registry`,
+        });
+        return;
+      }
+
+      const registryIntegrity = versionData.dist?.integrity;
+      if (!registryIntegrity) return;
+
+      // THE CORE CHECK — lock file hash vs registry hash
+      if (meta.integrity !== registryIntegrity) {
+        findings.push({
+          type: 'error',
+          package: name,
+          version: meta.version,
+          message: 'INTEGRITY MISMATCH — installed package differs from registry',
+          detail: {
+            locked:   meta.integrity.slice(0, 40) + '...',
+            registry: registryIntegrity.slice(0, 40) + '...',
+          },
+        });
+        return;
+      }
+
+      // Check if the author/publisher changed in this version vs the previous one
+      const versions = Object.keys(registryMeta.versions || {});
+      const idx = versions.indexOf(meta.version);
+      if (idx > 0) {
+        const prevVersion = versions[idx - 1];
+        const prevPublisher = registryMeta.versions[prevVersion]?._npmUser?.name;
+        const currPublisher = versionData._npmUser?.name;
+        if (prevPublisher && currPublisher && prevPublisher !== currPublisher) {
+          findings.push({
+            type: 'warning',
+            package: name,
+            version: meta.version,
+            message: `Publisher changed from "${prevPublisher}" to "${currPublisher}" in this version`,
+          });
+        }
+      }
+    }));
+  }
+
+  return { error: null, findings, total: entries.length };
+}

package/.github/workflows/publish.yml

@@ -1,22 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Publish
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}