create-qa-architect 5.0.0 → 5.0.6

package/create-saas-monetization.js

@@ -13,6 +13,16 @@
  * - Conversion landing page
  * - Beta user email campaigns
  * - Upgrade prompts and messaging
+ *
+ * Roadmap / Future Ideas:
+ * - Extract licensing to shared npm package (@vibebuildlab/licensing)
+ *   - Single source of truth across all Vibe Lab products
+ *   - Central license server with one API for all products
+ *   - Device/activation limits (optional enforcement)
+ *   - License revocation for chargebacks
+ * - Team/seat-based licensing with org management
+ * - SSO/SAML integration for Enterprise tier
+ * - Usage-based billing option (metered pricing)
  */
 
 'use strict'
@@ -29,7 +39,7 @@ const FOUNDER_ENTERPRISE_PRICE = '74.50'
 
 class SaaSMonetizationBootstrap {
   constructor() {
-    this.projectRoot = process.cwd()
+    this.projectRoot = path.resolve(process.cwd())
     this.config = {}
     this.templates = {
       stripe: this.getStripeTemplate(),
@@ -40,6 +50,56 @@ class SaaSMonetizationBootstrap {
     }
   }
 
+  resolveProjectPath(relativePath) {
+    const normalizedRoot = this.projectRoot.endsWith(path.sep)
+      ? this.projectRoot
+      : `${this.projectRoot}${path.sep}`
+    const resolvedPath = path.resolve(this.projectRoot, relativePath)
+
+    if (
+      resolvedPath !== this.projectRoot &&
+      !resolvedPath.startsWith(normalizedRoot)
+    ) {
+      throw new Error(
+        `Refusing to access path outside project root: ${relativePath}`
+      )
+    }
+
+    return resolvedPath
+  }
+
+  ensureDir(relativePath) {
+    const target = this.resolveProjectPath(relativePath)
+    // Path is constrained to the project root before touching the filesystem
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    if (!fs.existsSync(target)) {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      fs.mkdirSync(target, { recursive: true })
+    }
+    return target
+  }
+
+  writeProjectFile(relativePath, content) {
+    const target = this.resolveProjectPath(relativePath)
+    // Path is constrained to the project root before touching the filesystem
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    fs.writeFileSync(target, content)
+  }
+
+  readProjectFile(relativePath) {
+    const target = this.resolveProjectPath(relativePath)
+    // Path is constrained to the project root before touching the filesystem
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    return fs.readFileSync(target, 'utf8')
+  }
+
+  projectFileExists(relativePath) {
+    const target = this.resolveProjectPath(relativePath)
+    // Path is constrained to the project root before touching the filesystem
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    return fs.existsSync(target)
+  }
+
   async run() {
     console.log('🚀 Create SaaS Monetization')
     console.log('═══════════════════════════════════')
@@ -149,10 +209,7 @@ class SaaSMonetizationBootstrap {
     const dirs = ['lib/monetization', 'legal', 'marketing', 'billing']
 
     dirs.forEach(dir => {
-      const fullPath = path.join(this.projectRoot, dir)
-      if (!fs.existsSync(fullPath)) {
-        fs.mkdirSync(fullPath, { recursive: true })
-      }
+      this.ensureDir(dir)
     })
   }
 
@@ -162,8 +219,8 @@ class SaaSMonetizationBootstrap {
       .replace(/{{PRO_PRICE}}/g, this.config.proPrice)
       .replace(/{{ENTERPRISE_PRICE}}/g, this.config.enterprisePrice)
 
-    fs.writeFileSync(
-      path.join(this.projectRoot, 'lib/monetization/stripe-integration.js'),
+    this.writeProjectFile(
+      path.join('lib/monetization', 'stripe-integration.js'),
       stripeCode
     )
   }
@@ -178,8 +235,8 @@ class SaaSMonetizationBootstrap {
       .replace(/{{FOUNDER_PRO_PRICE}}/g, this.config.founderProPrice)
       .replace(/{{DOMAIN}}/g, this.config.domain)
 
-    fs.writeFileSync(
-      path.join(this.projectRoot, 'lib/monetization/licensing.js'),
+    this.writeProjectFile(
+      path.join('lib/monetization', 'licensing.js'),
       licensingCode
     )
   }
@@ -194,7 +251,7 @@ class SaaSMonetizationBootstrap {
         .replace(/{{DESCRIPTION}}/g, this.config.description)
         .replace(/{{DATE}}/g, new Date().toISOString().split('T')[0])
 
-      fs.writeFileSync(path.join(this.projectRoot, 'legal', filename), content)
+      this.writeProjectFile(path.join('legal', filename), content)
     }
   }
 
@@ -223,10 +280,7 @@ class SaaSMonetizationBootstrap {
         )
         .replace(/{{SUPPORT_EMAIL}}/g, this.config.supportEmail)
 
-      fs.writeFileSync(
-        path.join(this.projectRoot, 'marketing', filename),
-        content
-      )
+      this.writeProjectFile(path.join('marketing', filename), content)
     }
   }
 
@@ -242,17 +296,14 @@ class SaaSMonetizationBootstrap {
       )
       .replace(/{{PREMIUM_FEATURES}}/g, this.config.premiumFeatures)
 
-    fs.writeFileSync(
-      path.join(this.projectRoot, 'billing/dashboard.html'),
-      billingCode
-    )
+    this.writeProjectFile(path.join('billing', 'dashboard.html'), billingCode)
   }
 
   async updatePackageJson() {
-    const packagePath = path.join(this.projectRoot, 'package.json')
+    const packagePath = 'package.json'
 
-    if (fs.existsSync(packagePath)) {
-      const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'))
+    if (this.projectFileExists(packagePath)) {
+      const pkg = JSON.parse(this.readProjectFile(packagePath))
 
       // Add monetization scripts
       pkg.scripts = pkg.scripts || {}
@@ -266,7 +317,7 @@ class SaaSMonetizationBootstrap {
       pkg.dependencies.stripe = '^14.15.0'
       pkg.dependencies.crypto = '^1.0.1'
 
-      fs.writeFileSync(packagePath, JSON.stringify(pkg, null, 2))
+      this.writeProjectFile(packagePath, JSON.stringify(pkg, null, 2))
     }
   }
 
@@ -297,7 +348,7 @@ COMPANY_NAME=${this.config.companyName}
 # STRIPE_PUBLISHABLE_KEY=pk_live_your_live_key_here
 `
 
-    fs.writeFileSync(path.join(this.projectRoot, '.env.template'), envTemplate)
+    this.writeProjectFile('.env.template', envTemplate)
   }
 
   async generateDeploymentGuide() {
@@ -473,10 +524,7 @@ For implementation questions:
 **Revenue Potential**: $1,500-5,000/month recurring
 `
 
-    fs.writeFileSync(
-      path.join(this.projectRoot, 'MONETIZATION_GUIDE.md'),
-      guide
-    )
+    this.writeProjectFile('MONETIZATION_GUIDE.md', guide)
   }
 
   // Template methods (condensed versions of our implementations)

package/docs/ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# Architecture
+
+## Overview
+
+QA Architect is a CLI tool that bootstraps quality automation in JavaScript/TypeScript and Python projects.
+
+## Core Components
+
+```
+create-qa-architect/
+├── setup.js              # Main CLI entry point
+├── lib/
+│   ├── smart-strategy-generator.js    # Smart test strategy (Pro)
+│   ├── dependency-monitoring-*.js     # Dependency monitoring
+│   └── validation/                    # Validation utilities
+├── templates/            # Project templates
+│   ├── eslint.config.cjs
+│   ├── .prettierrc
+│   ├── .husky/
+│   └── scripts/
+└── config/               # Language-specific configs
+    ├── pyproject.toml
+    └── quality-python.yml
+```
+
+## Data Flow
+
+1. **Detection Phase**: Detect project type (JS/TS/Python/mixed)
+2. **Configuration Phase**: Generate appropriate configs
+3. **Installation Phase**: Copy templates, update package.json
+4. **Validation Phase**: Verify setup is complete
+
+## Extension Points
+
+- Custom templates via `--template` flag
+- Language detection can be extended in `setup.js`
+- New quality checks via template files
+
+## Smart Test Strategy (Pro)
+
+Risk-based pre-push validation that adapts to change context:
+
+1. Calculate risk score (0-10) based on files changed
+2. Select appropriate test tier (minimal → comprehensive)
+3. Run tests with appropriate depth
+
+## CLI Flags
+
+- `--update` - Update existing setup
+- `--deps` - Dependency monitoring only
+- `--security-config` - Security validation
+- `--check-maturity` - Project maturity report
+- `--comprehensive` - Full validation suite

package/docs/DEPLOYMENT.md

@@ -0,0 +1,62 @@
+# Deployment Guide
+
+## Overview
+
+QA Architect is published to npm as `create-qa-architect`.
+
+## Prerequisites
+
+- Node.js 20+
+- npm account with publish access
+- Git repository access
+
+## Release Process
+
+### 1. Pre-Release Validation
+
+```bash
+npm run prerelease    # Run all tests and validations
+npm run test:coverage # Verify coverage thresholds
+```
+
+### 2. Version Bump
+
+```bash
+npm run release:patch  # Bug fixes (1.0.x)
+npm run release:minor  # New features (1.x.0)
+npm run release:major  # Breaking changes (x.0.0)
+```
+
+### 3. Publish
+
+GitHub Actions automatically publishes on tagged releases.
+
+For manual publish:
+
+```bash
+npm publish
+```
+
+## Verification
+
+After release, verify:
+
+```bash
+npx create-qa-architect@latest --version
+npx create-qa-architect@latest --help
+```
+
+## Rollback
+
+If issues are discovered:
+
+```bash
+npm unpublish create-qa-architect@VERSION
+# or
+npm deprecate create-qa-architect@VERSION "Critical bug, use VERSION instead"
+```
+
+## npm Registry
+
+- Package: https://www.npmjs.com/package/create-qa-architect
+- Documentation: https://github.com/vibebuildlab/qa-architect

package/docs/PREFLIGHT_REPORT.md

@@ -0,0 +1,108 @@
+# Preflight Review: QA Architect (create-qa-architect)
+
+**Depth**: standard
+**Date**: 2025-12-09
+**Version**: 5.0.2
+
+---
+
+## Overall Status: ✅ PASS
+
+All critical launch blockers pass. Minor issues documented below are acceptable for npm package release.
+
+---
+
+## Critical Issues (P0) - Must Fix
+
+| Issue | Category | Location | Fix |
+| ----- | -------- | -------- | --- |
+| None  | -        | -        | -   |
+
+---
+
+## Important Issues (P1) - Should Fix
+
+| Issue                    | Category | Location         | Recommendation                                                                                                                 |
+| ------------------------ | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Gitleaks false positives | Security | tests/\*.test.js | Test fixtures use fake API key patterns (QAA-XXXX format); not real secrets. Consider adding `.gitleaksignore` for test files. |
+| npm version mismatch     | Release  | package.json     | Local 5.0.2, npm shows 5.0.1. Publish pending or recently published.                                                           |
+
+---
+
+## P0 Functional Checks
+
+| Check             | Status | Notes                  |
+| ----------------- | ------ | ---------------------- |
+| All tests passing | ✅     | Full test suite passes |
+| npm audit         | ✅     | 0 vulnerabilities      |
+| ESLint            | ✅     | No errors              |
+| Build/validation  | ✅     | Core validation passes |
+
+---
+
+## P0 Security Checks
+
+| Check                     | Status | Notes                                                                |
+| ------------------------- | ------ | -------------------------------------------------------------------- |
+| npm audit (high/critical) | ✅     | 0 vulnerabilities found                                              |
+| Hardcoded secrets scan    | ⚠️     | 4 findings - all in test files with fake keys (QAA-1234-XXXX format) |
+| No production secrets     | ✅     | No `.env` files, no real API keys                                    |
+
+---
+
+## Product Packaging
+
+| Item         | Status | Notes                   |
+| ------------ | ------ | ----------------------- |
+| CHANGELOG.md | ✅     | Present                 |
+| LICENSE      | ✅     | Present                 |
+| README.md    | ✅     | Present                 |
+| .env.example | N/A    | Not needed for CLI tool |
+| Version tags | ✅     | v4.3.0 - v5.0.2         |
+| Git status   | ✅     | Clean working tree      |
+
+---
+
+## Quality Violations
+
+| Type                    | Count | Assessment                                                   |
+| ----------------------- | ----- | ------------------------------------------------------------ |
+| eslint-disable comments | 24    | All have security justification comments explaining why safe |
+| any types               | 0     | JavaScript project, N/A                                      |
+
+**Note**: The `eslint-disable` comments are all for security-related ESLint rules (detect-unsafe-regex, detect-non-literal-fs-filename, detect-object-injection) and each includes a detailed safety justification explaining why the pattern is safe in context.
+
+---
+
+## Silent Killer Check (N/A for npm package)
+
+| Integration     | Status | Notes                 |
+| --------------- | ------ | --------------------- |
+| Stripe webhooks | N/A    | CLI tool, no webhooks |
+| OAuth redirects | N/A    | CLI tool              |
+| API keys        | N/A    | CLI tool              |
+| CORS config     | N/A    | CLI tool              |
+
+---
+
+## Next Steps
+
+1. **Optional**: Add `.gitleaksignore` to exclude test files with fake license keys
+2. **Verify**: Confirm npm publish completed for 5.0.2 (may be propagating)
+3. **Ready**: Proceed with launch/release announcement
+
+---
+
+## Recommendation
+
+**✅ CLEARED FOR LAUNCH**
+
+This is an npm CLI package, not a web application. All critical checks pass:
+
+- Tests passing
+- No security vulnerabilities
+- No real secrets
+- Clean git state
+- Proper versioning and packaging
+
+The gitleaks findings are false positives on intentional test fixtures using fake license key formats.

package/docs/SLA_GATES.md

@@ -0,0 +1,28 @@
+# Quality Gates & Merge Readiness (Default Recommendations)
+
+These defaults are meant to give teams a simple, enforceable bar. They are intentionally conservative so most repos can adopt them on day one without re-architecting.
+
+## Targets
+
+- Coverage: **80%** (line) for critical paths; **70%** repo-wide minimum.
+- Lint: **0** blocking ESLint/Stylelint errors; warnings allowed but surface in PR comment/summary.
+- Secrets: **0** leaked secrets (gitleaks hard fail).
+- Dependency vulns: No **high/critical** advisories (npm/yarn/pnpm audit). Medium allowed with justification.
+- Performance budgets (CI): installs < 2m; test suite < 5m (already enforced in workflow).
+
+## How to enforce
+
+- GitHub Actions: quality.yml is wired to fail on lint/scan/test failures. Set env `MIN_COVERAGE=80` to gate on coverage (add a coverage reporter such as `c8` or `vitest --coverage`).
+- Branch protection: require the “Quality Checks” workflow to pass; enable dismiss stale approvals on push.
+- PR comments: run setup with `--pr-comments` to surface gate status in the PR thread.
+- Alerts: run setup with `--alerts-slack` to post failures to Slack.
+
+## Exceptions
+
+- Allow temporary waivers via labels (e.g., `risk-accepted`) and document in the PR body.
+- Lower coverage floors for greenfield proofs-of-concept (set `MIN_COVERAGE=60`) but time-box the exemption.
+
+## Next steps
+
+- Add repo-specific risk areas to `.qualityrc.json` under `riskAreas`.
+- Track SLA drift in reports (future: audit log + team dashboard hooks).

package/docs/TESTING.md

@@ -0,0 +1,61 @@
+# Testing Strategy
+
+## Overview
+
+QA Architect uses Jest for testing with a focus on integration tests that validate real CLI workflows.
+
+## Running Tests
+
+```bash
+npm test                 # Run all tests
+npm run test:coverage    # Run with coverage report
+npm run test:watch       # Watch mode for development
+```
+
+## Test Structure
+
+```
+tests/
+├── setup.test.js           # Main CLI integration tests
+├── cli-deps-integration.test.js    # Dependency CLI tests
+├── real-world-packages.test.js     # Real package validation
+└── premium-dependency-monitoring.test.js  # Pro feature tests
+```
+
+## Coverage Requirements
+
+- **Overall**: 75%+ lines, statements, functions, branches
+- **New files**: 75%+ coverage before merging
+- **Critical files**: `setup.js` requires 80%+
+
+## Testing Patterns
+
+### Integration Tests
+
+Test real CLI workflows with temp directories:
+
+```javascript
+const testDir = createTempGitRepo()
+const result = execSync('node setup.js --deps', { cwd: testDir })
+assert(fs.existsSync(path.join(testDir, '.github/dependabot.yml')))
+```
+
+### Real-World Data
+
+Use real packages from the ecosystem, not toy examples:
+
+```javascript
+const TOP_PYTHON_PACKAGES = [
+  'django-cors-headers',
+  'scikit-learn',
+  'pytest-cov',
+]
+```
+
+## Pre-Release Validation
+
+Always run before release:
+
+```bash
+npm run prerelease  # Runs docs:check + all tests
+```

package/docs/security/SOC2_STARTER.md

@@ -0,0 +1,29 @@
+# SOC 2 Starter (Preflight Checklist)
+
+This starter doc is a lightweight preflight for teams using QA Architect. It is not a substitute for a real SOC 2 program, but it maps common CI/quality controls to SOC 2 CC/PII areas.
+
+## Controls to Wire First
+
+- **Change Management (CC8.1):** Require PR review + Quality Checks workflow pass; enable branch protection on main.
+- **Secure SDLC (CC6.1):** Keep ESLint security, gitleaks, dependency audit steps enabled; document exceptions in PRs.
+- **Logging & Alerts (CC7.2):** Turn on Slack alerts via `--alerts-slack` and keep CI logs for 90 days.
+- **Backup of Config (CC9.2):** Check in `.qualityrc.json`, `quality.yml`, and Dependabot configs; avoid secrets in repo.
+- **Access (CC6.2):** Use least-privilege GitHub tokens; rotate `GITLEAKS_TOKEN`/`SEMGREP_APP_TOKEN` every 90 days.
+
+## Evidence You Can Collect Today
+
+- CI run artifacts showing lint/test/security passes.
+- Dependency audit reports (npm audit logs) and gitleaks scan results.
+- Coverage reports (c8/Vitest/Jest) stored in artifacts.
+- PR comments from quality workflow (when `--pr-comments` is enabled).
+
+## Gaps to plan for
+
+- **SSO/SAML & RBAC:** Roadmap item (Enterprise); track in issue tracker.
+- **Audit logging:** Add a central log sink (e.g., S3/CloudWatch) for CI events.
+- **Vendor risk:** Document third-party actions; pin SHAs (already pinned in quality.yml) and review quarterly.
+
+## How to use this file
+
+- Keep it checked in; edit per repo to note exceptions and waivers.
+- Link it in onboarding docs so new contributors know the expected bar.

package/lib/config-validator.js

@@ -1,10 +1,16 @@
 'use strict'
 
-const Ajv = require('ajv')
-const addFormats = require('ajv-formats')
+const AjvImport = require('ajv')
+const addFormatsImport = require('ajv-formats')
 const fs = require('fs')
 const path = require('path')
 
+// Handle CJS/ESM interop for Ajv and ajv-formats in JS type-checking
+const Ajv = /** @type {any} */ (AjvImport.default || AjvImport)
+const addFormats = /** @type {(ajv: any) => void} */ (
+  addFormatsImport.default || addFormatsImport
+)
+
 function validateQualityConfig(configPath) {
   const result = {
     valid: false,

package/lib/dependency-monitoring-basic.js

@@ -17,6 +17,7 @@ function hasNpmProject(projectPath) {
 /**
  * Generate basic Dependabot configuration (Free Tier)
  * Limited to npm only, no framework detection, basic settings
+ * Supports monorepo per-package directories
  */
 function generateBasicDependabotConfig(options = {}) {
   const {
@@ -24,49 +25,95 @@ function generateBasicDependabotConfig(options = {}) {
     schedule = 'weekly',
     day = 'monday',
     time = '09:00',
+    monorepoInfo = null, // Optional monorepo detection result
   } = options
 
   if (!hasNpmProject(projectPath)) {
     return null // Only npm projects supported in free tier
   }
 
-  const config = {
-    version: 2,
-    updates: [
-      {
+  const updates = []
+
+  // If monorepo with resolved packages, create per-package entries
+  if (
+    monorepoInfo &&
+    monorepoInfo.isMonorepo &&
+    monorepoInfo.resolvedPackages &&
+    monorepoInfo.resolvedPackages.length > 0
+  ) {
+    // Root package
+    updates.push({
+      'package-ecosystem': 'npm',
+      directory: '/',
+      schedule: {
+        interval: schedule,
+        day: day,
+        time: time,
+      },
+      'open-pull-requests-limit': 5,
+      labels: ['dependencies', 'root'],
+      'commit-message': {
+        prefix: 'deps(root)',
+        include: 'scope',
+      },
+    })
+
+    // Per-package entries
+    for (const pkg of monorepoInfo.resolvedPackages) {
+      const dir = '/' + pkg.relativePath.replace(/\\/g, '/')
+      updates.push({
         'package-ecosystem': 'npm',
-        directory: '/',
+        directory: dir,
         schedule: {
           interval: schedule,
           day: day,
           time: time,
         },
-        'open-pull-requests-limit': 5,
-        labels: ['dependencies'],
+        'open-pull-requests-limit': 3,
+        labels: ['dependencies', pkg.name],
         'commit-message': {
-          prefix: 'deps',
+          prefix: `deps(${pkg.name})`,
           include: 'scope',
         },
-        // Note: Dependabot will create PRs for all dependency updates.
-        // To auto-merge specific updates (e.g., security patches), add a GitHub Actions
-        // workflow with conditions like: if: contains(github.event.pull_request.labels.*.name, 'security')
-        // See: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions
+      })
+    }
+  } else {
+    // Single package (non-monorepo)
+    updates.push({
+      'package-ecosystem': 'npm',
+      directory: '/',
+      schedule: {
+        interval: schedule,
+        day: day,
+        time: time,
       },
-      // GitHub Actions monitoring (free tier includes this)
-      {
-        'package-ecosystem': 'github-actions',
-        directory: '/',
-        schedule: {
-          interval: schedule,
-          day: day,
-          time: time,
-        },
-        labels: ['dependencies', 'github-actions'],
-        'commit-message': {
-          prefix: 'deps(actions)',
-        },
+      'open-pull-requests-limit': 5,
+      labels: ['dependencies'],
+      'commit-message': {
+        prefix: 'deps',
+        include: 'scope',
       },
-    ],
+    })
+  }
+
+  // GitHub Actions monitoring (free tier includes this)
+  updates.push({
+    'package-ecosystem': 'github-actions',
+    directory: '/',
+    schedule: {
+      interval: schedule,
+      day: day,
+      time: time,
+    },
+    labels: ['dependencies', 'github-actions'],
+    'commit-message': {
+      prefix: 'deps(actions)',
+    },
+  })
+
+  const config = {
+    version: 2,
+    updates: updates,
   }
 
   return config