opscale-setup 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # required for npm provenance
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Publish with provenance
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,111 @@
+# opscale-setup
+
+> Deploy a production-ready Claude Code environment in one command.
+
+```bash
+npx opscale-setup
+```
+
+No global install required. Answers 3 questions, then writes everything to your
+project in under 10 seconds.
+
+---
+
+## What it installs
+
+| File | Description |
+|------|-------------|
+| `CLAUDE.md` | Best-practice prompting guide, tailored to your stack |
+| `.claude/settings.json` | Optimized Claude Code config with hooks wired up |
+| `.claude/hooks/` (10 hooks) | Production-grade guardrails and automation |
+| `.claude/skills/` (5 skills) | High-value slash commands for daily dev work |
+
+### Hooks
+
+| Hook | Trigger | What it does |
+|------|---------|--------------|
+| `block-dangerous.js` | PreToolUse Bash | Blocks `rm -rf /`, `DROP DATABASE`, fork bombs, `curl \| bash` |
+| `secret-guard.js` | PreToolUse Bash + Write | Detects AWS keys, GitHub tokens, Anthropic keys, private key blocks |
+| `branch-guard.js` | PreToolUse Bash | Warns on direct push to main/master; blocks force-push |
+| `dep-audit.js` | PreToolUse Bash | Intercepts npm/pip/cargo installs, flags typosquats + critical CVEs |
+| `deploy-check.js` | PreToolUse Bash | Enforces clean working tree + passing tests before any deploy |
+| `auto-commit-msg.js` | PostToolUse Bash | Validates Conventional Commits format after every commit |
+| `cost-tracker.js` | Stop | Logs session token usage + estimated USD cost to `.claude/cost-log.json` |
+| `test-runner.js` | PostToolUse Write | Auto-discovers and runs related tests when source files are written |
+| `lint-check.js` | PostToolUse Write | Runs ESLint/Biome/Ruff/gofmt on written files |
+| `build-validator.js` | PostToolUse Write | Runs `tsc --noEmit` / `cargo check` / `go build` on written files |
+
+### Skills
+
+| Skill | Command | What it does |
+|-------|---------|--------------|
+| code-review | `/code-review` | Security + correctness review of the current diff |
+| test-generation | `/test-generation <file>` | Generates a full, runnable test suite |
+| pr-description | `/pr-description` | Writes PR title + body from git log + diff |
+| debugging | `/debugging "<symptom>"` | Systematic 5-step debug protocol |
+| deployment | `/deployment` | Pre-deploy checklist + rollback procedures |
+
+---
+
+## Setup wizard
+
+The wizard asks exactly 3 questions:
+
+1. **Project type** — Node.js, Python, Go, Rust, Java, Ruby, Full-stack, Generic
+2. **Team size** — Solo, Small (2–10), Medium (11–50), Large (50+)
+3. **Deploy target** — AWS, GCP, Azure, Vercel, Kubernetes, Docker, VPS, Generic
+
+Answers are embedded in `CLAUDE.md` and `settings.json` to tailor the generated
+files to your environment.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
+
+---
+
+## Publishing your own fork
+
+1. Fork this repo and update `package.json` with your npm username.
+2. Add `NPM_TOKEN` to your GitHub repository secrets.
+3. Tag a release:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+GitHub Actions will run tests and publish to npm automatically.
+
+---
+
+## Customizing hooks
+
+Hooks are plain Node.js scripts in `.claude/hooks/`. They receive tool input as
+JSON on stdin and exit non-zero to abort the tool call.
+
+```js
+// .claude/hooks/my-hook.js
+import { readFileSync } from 'fs';
+
+const input = JSON.parse(readFileSync('/dev/stdin', 'utf8'));
+const command = input?.tool_input?.command ?? '';
+
+if (command.includes('something-forbidden')) {
+  console.error('[my-hook] blocked');
+  process.exit(1);
+}
+
+process.exit(0);
+```
+
+Wire it up in `.claude/settings.json` under `hooks.PreToolUse` or `hooks.PostToolUse`.
+
+---
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from '../src/index.js';
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opscale-setup",
+  "version": "1.0.0",
+  "description": "Deploy a production-ready Claude Code environment in one command",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "opscale-setup": "bin/index.js"
+  },
+  "scripts": {
+    "start": "node bin/index.js",
+    "test": "node --test src/__tests__/*.test.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "developer-tools",
+    "cli",
+    "setup",
+    "hooks",
+    "anthropic"
+  ],
+  "author": "opscale-setup contributors",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.12",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jordan23wagner-ops/opscale-setup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YOUR_USERNAME/opscale-setup/issues"
+  },
+  "homepage": "https://github.com/YOUR_USERNAME/opscale-setup#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,21 @@
+import chalk from 'chalk';
+import { runWizard } from './wizard.js';
+import { install } from './installer.js';
+import { log, banner } from './logger.js';
+
+export async function main() {
+  banner();
+
+  const config = await runWizard();
+
+  log.info('Installing Claude Code environment...');
+  await install(config);
+
+  console.log('\n' + chalk.green.bold('  Setup complete!') + '\n');
+  console.log(chalk.dim('  Files created:'));
+  console.log(chalk.dim('    CLAUDE.md          ') + chalk.white('Best-practice prompting guide'));
+  console.log(chalk.dim('    .claude/settings.json  ') + chalk.white('Optimized Claude Code config'));
+  console.log(chalk.dim('    .claude/hooks/     ') + chalk.white('10 production-grade hooks'));
+  console.log(chalk.dim('    .claude/skills/    ') + chalk.white('5 high-value skill definitions'));
+  console.log('\n' + chalk.cyan('  Run') + ' claude ' + chalk.cyan('to start your session.\n'));
+}

package/src/installer.js

@@ -0,0 +1,75 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs-extra';
+import ora from 'ora';
+import { log } from './logger.js';
+import { renderClaudeMd } from './templates/CLAUDE.md.js';
+import { renderSettings } from './templates/settings.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, 'templates');
+const HOOKS_DIR = path.join(TEMPLATES_DIR, 'hooks');
+const SKILLS_DIR = path.join(TEMPLATES_DIR, 'skills');
+
+export async function install(config) {
+  const cwd = process.cwd();
+  const claudeDir = path.join(cwd, '.claude');
+  const hooksDir = path.join(claudeDir, 'hooks');
+  const skillsDir = path.join(claudeDir, 'skills');
+
+  const spinner = ora({ text: 'Creating directories...', prefixText: '  ' }).start();
+
+  await fs.ensureDir(hooksDir);
+  await fs.ensureDir(skillsDir);
+  spinner.succeed('Directories ready');
+
+  // CLAUDE.md
+  spinner.start('Writing CLAUDE.md...');
+  await fs.writeFile(path.join(cwd, 'CLAUDE.md'), renderClaudeMd(config));
+  spinner.succeed('CLAUDE.md written');
+
+  // settings.json
+  spinner.start('Writing .claude/settings.json...');
+  await fs.writeJSON(path.join(claudeDir, 'settings.json'), renderSettings(config), { spaces: 2 });
+  spinner.succeed('.claude/settings.json written');
+
+  // Hooks
+  spinner.start('Installing hooks...');
+  const hookFiles = await fs.readdir(HOOKS_DIR);
+  for (const file of hookFiles) {
+    const src = path.join(HOOKS_DIR, file);
+    const dest = path.join(hooksDir, file);
+    await fs.copy(src, dest, { overwrite: false });
+    // Mark shell scripts executable on Unix
+    if (file.endsWith('.sh')) {
+      await fs.chmod(dest, 0o755).catch(() => {});
+    }
+  }
+  spinner.succeed(`${hookFiles.length} hooks installed`);
+
+  // Skills
+  spinner.start('Installing skills...');
+  const skillFiles = await fs.readdir(SKILLS_DIR);
+  for (const file of skillFiles) {
+    const src = path.join(SKILLS_DIR, file);
+    const dest = path.join(skillsDir, file);
+    await fs.copy(src, dest, { overwrite: false });
+  }
+  spinner.succeed(`${skillFiles.length} skills installed`);
+
+  // .gitignore safety — ensure .claude/hooks is gitignored if desired
+  await patchGitignore(cwd);
+}
+
+async function patchGitignore(cwd) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const marker = '# opscale-setup';
+  const block = `\n${marker}\n.claude/settings.local.json\n`;
+
+  if (await fs.pathExists(gitignorePath)) {
+    const content = await fs.readFile(gitignorePath, 'utf8');
+    if (!content.includes(marker)) {
+      await fs.appendFile(gitignorePath, block);
+    }
+  }
+}

package/src/logger.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+
+export function banner() {
+  console.log('\n' + chalk.bold.cyan('  ██████╗ ██████╗ ███████╗ ██████╗ █████╗ ██╗     ███████╗'));
+  console.log(chalk.bold.cyan('  ██╔═══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║     ██╔════╝'));
+  console.log(chalk.bold.cyan('  ██║   ██║██████╔╝███████╗██║     ███████║██║     █████╗  '));
+  console.log(chalk.bold.cyan('  ██║   ██║██╔═══╝ ╚════██║██║     ██╔══██║██║     ██╔══╝  '));
+  console.log(chalk.bold.cyan('  ╚██████╔╝██║     ███████║╚██████╗██║  ██║███████╗███████╗'));
+  console.log(chalk.bold.cyan('   ╚═════╝ ╚═╝     ╚══════╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝'));
+  console.log('\n' + chalk.bold('  opscale-setup') + chalk.dim(' — Production Claude Code in one command'));
+  console.log(chalk.dim('  ─────────────────────────────────────────────────────\n'));
+}
+
+export const log = {
+  info:    (msg) => console.log(chalk.blue('  ℹ ') + msg),
+  success: (msg) => console.log(chalk.green('  ✓ ') + msg),
+  warn:    (msg) => console.log(chalk.yellow('  ⚠ ') + msg),
+  error:   (msg) => console.log(chalk.red('  ✗ ') + msg),
+  step:    (msg) => console.log(chalk.cyan('  → ') + msg),
+};

package/src/templates/CLAUDE.md.js

@@ -0,0 +1,82 @@
+export function renderClaudeMd({ projectType, teamSize, deployTarget }) {
+  const projectLabel = {
+    node: 'Node.js / TypeScript', python: 'Python', go: 'Go', rust: 'Rust',
+    java: 'Java / Kotlin', ruby: 'Ruby on Rails', fullstack: 'Full-stack monorepo',
+    generic: 'Generic',
+  }[projectType] ?? projectType;
+
+  return `# CLAUDE.md
+
+## Project Context
+
+- **Stack**: ${projectLabel}
+- **Team size**: ${teamSize}
+- **Deploy target**: ${deployTarget}
+
+---
+
+## How to Work with This Codebase
+
+### Before Starting Any Task
+
+1. Read existing tests to understand intended behavior before changing code.
+2. Check \`git log --oneline -20\` to understand recent changes and momentum.
+3. Grep for the symbol or pattern you're about to create — don't duplicate.
+4. If the task is ambiguous, ask one clarifying question before writing code.
+
+### Coding Standards
+
+- Match the style of the surrounding code exactly (indentation, naming, quotes).
+- No commented-out code. Delete dead code; git history preserves it.
+- No TODO comments unless the task explicitly requires deferral.
+- Prefer editing existing files over creating new abstractions.
+- Three similar lines is better than a premature abstraction.
+
+### What NOT to Do
+
+- Do not add error handling for scenarios that cannot happen in this codebase.
+- Do not write multi-paragraph docstrings for self-explanatory functions.
+- Do not add feature flags or backwards-compat shims unless asked.
+- Do not create planning documents, analysis files, or READMEs unless asked.
+- Do not run \`git add -A\` — stage specific files by name only.
+- Do not amend published commits.
+
+### Security Rules
+
+- Never log secrets, tokens, or PII.
+- Never commit \`.env\` files or credential files.
+- All user input must be validated at the boundary; trust internal types.
+- SQL queries must use parameterized statements — no string interpolation.
+- No \`eval()\`, \`exec()\`, or dynamic code execution on untrusted input.
+
+### Git Workflow
+
+- Commit message format: \`<type>(<scope>): <what changed, present tense>\`
+- Types: \`feat\`, \`fix\`, \`refactor\`, \`test\`, \`docs\`, \`chore\`, \`perf\`
+- One logical change per commit. Keep PRs small and focused.
+- Branch naming: \`<type>/<short-slug>\` e.g. \`feat/user-auth\`
+
+### Testing
+
+- Write tests for every new public function.
+- Tests should verify behavior, not implementation.
+- Do not mock the database in integration tests.
+- A failing test must be fixed before merging — never skip.
+
+### Deploy Checklist (${deployTarget})
+
+- All tests pass locally before pushing.
+- Environment variables documented in \`.env.example\`.
+- Database migrations are backwards-compatible.
+- Rollback plan documented for schema changes.
+- Secrets rotation procedure known to team.
+
+---
+
+## Asking for Help
+
+If you are unsure, say so. A wrong confident answer is worse than an honest
+"I don't know — here's what I'd check." Prefer small, verifiable steps over
+large speculative changes.
+`;
+}

package/src/templates/hooks/auto-commit-msg.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse / Bash — after a git commit, validates the commit message
+ * against Conventional Commits format and prints a warning if it doesn't
+ * match. Never blocks — this is advisory only.
+ */
+import { readFileSync } from 'fs';
+import { execSync } from 'child_process';
+
+const CONVENTIONAL = /^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\(.+\))?: .{1,100}$/;
+
+let input;
+try {
+  input = JSON.parse(readFileSync('/dev/stdin', 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const command = input?.tool_input?.command ?? '';
+if (!/git\s+commit/.test(command)) process.exit(0);
+
+// Read the last commit message
+let msg = '';
+try {
+  msg = execSync('git log -1 --pretty=%s', { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+} catch {
+  process.exit(0);
+}
+
+if (!CONVENTIONAL.test(msg)) {
+  console.error(
+    `[auto-commit-msg] WARNING: commit message doesn't follow Conventional Commits:\n` +
+    `  "${msg}"\n` +
+    `  Expected: <type>(<scope>): <description>\n` +
+    `  Types: feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert`
+  );
+}
+
+process.exit(0);

package/src/templates/hooks/block-dangerous.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse / Bash — blocks shell commands that are almost never safe to run
+ * autonomously. Reads the tool input JSON from stdin and exits non-zero to abort.
+ */
+import { readFileSync } from 'fs';
+
+const BLOCKED = [
+  /rm\s+-rf\s+[/~]/,           // rm -rf / or ~/
+  /rm\s+-rf\s+\*/,             // rm -rf *
+  /DROP\s+DATABASE/i,
+  /DROP\s+TABLE/i,
+  /TRUNCATE\s+TABLE/i,
+  /chmod\s+777/,
+  /curl[^|]+\|\s*bash/,        // curl ... | bash
+  /wget[^|]+\|\s*bash/,        // wget ... | bash
+  /git\s+push\s+--force(?!\s*--no)/,  // force push (not --force-with-lease)
+  /git\s+reset\s+--hard\s+HEAD~[2-9]/, // hard reset >1 commit
+  /:(){:|:&};:/,               // fork bomb
+];
+
+let input;
+try {
+  input = JSON.parse(readFileSync('/dev/stdin', 'utf8'));
+} catch {
+  process.exit(0); // no stdin — allow
+}
+
+const command = input?.tool_input?.command ?? '';
+
+for (const pattern of BLOCKED) {
+  if (pattern.test(command)) {
+    console.error(
+      `[block-dangerous] BLOCKED: command matched safety pattern: ${pattern}\n  Command: ${command}`
+    );
+    process.exit(1);
+  }
+}
+
+process.exit(0);

package/src/templates/hooks/branch-guard.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse / Bash — warns when Claude is about to push or commit directly
+ * to protected branches (main, master, production, release/*).
+ * Exits non-zero to block; exits 0 to allow.
+ */
+import { readFileSync } from 'fs';
+import { execSync } from 'child_process';
+
+const PROTECTED = /^(main|master|production|release\/.+)$/;
+
+let input;
+try {
+  input = JSON.parse(readFileSync('/dev/stdin', 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const command = input?.tool_input?.command ?? '';
+
+// Only care about git push / git commit on protected branches
+if (!/git\s+(push|commit)/.test(command)) process.exit(0);
+
+let branch = '';
+try {
+  branch = execSync('git rev-parse --abbrev-ref HEAD', { stdio: ['pipe', 'pipe', 'pipe'] })
+    .toString().trim();
+} catch {
+  process.exit(0);
+}
+
+if (PROTECTED.test(branch)) {
+  // Force-push to protected branch is always blocked
+  if (/--force/.test(command) || /-f\b/.test(command)) {
+    console.error(
+      `[branch-guard] BLOCKED: force push to protected branch "${branch}" is not allowed.`
+    );
+    process.exit(1);
+  }
+
+  // Warn but allow regular pushes — print to stderr so Claude sees it
+  console.error(
+    `[branch-guard] WARNING: you are about to push directly to "${branch}".\n` +
+    `  Consider using a feature branch and opening a pull request instead.`
+  );
+}
+
+process.exit(0);

package/src/templates/hooks/build-validator.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse / Write — after Claude writes a file, runs a fast type-check or
+ * build to catch compile errors immediately. Advisory only — never blocks.
+ *
+ * Detects: TypeScript (tsc --noEmit), Python (py_compile), Go (go build), Rust (cargo check).
+ */
+import { readFileSync, existsSync } from 'fs';
+import { execSync } from 'child_process';
+import path from 'path';
+
+let input;
+try {
+  input = JSON.parse(readFileSync('/dev/stdin', 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const filePath = input?.tool_input?.file_path ?? '';
+if (!filePath || !existsSync(filePath)) process.exit(0);
+
+const ext = path.extname(filePath);
+
+function run(cmd, label) {
+  try {
+    execSync(cmd, { stdio: 'pipe', timeout: 60_000 });
+    console.error(`[build-validator] ${label} passed`);
+  } catch (err) {
+    console.error(
+      `[build-validator] ${label} failed:\n` +
+      (err.stdout?.toString() ?? '') +
+      (err.stderr?.toString() ?? '')
+    );
+  }
+}
+
+if (['.ts', '.tsx'].includes(ext)) {
+  if (existsSync('tsconfig.json')) {
+    run('npx tsc --noEmit --skipLibCheck', 'TypeScript');
+  }
+} else if (ext === '.py') {
+  run(`python -m py_compile ${filePath}`, 'Python syntax');
+} else if (ext === '.go') {
+  run('go build ./...', 'Go build');
+} else if (ext === '.rs') {
+  run('cargo check --quiet', 'Rust check');
+}
+
+process.exit(0);

package/src/templates/hooks/cost-tracker.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — reads session usage from Claude Code's stop event and appends
+ * a cost record to .claude/cost-log.json so teams can track AI spend over time.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import path from 'path';
+
+// Claude Code pricing (USD per million tokens) as of mid-2025
+// Update these when Anthropic changes pricing.
+const PRICING = {
+  'claude-opus-4':    { input: 15.00,  output: 75.00,  cacheRead: 1.50,  cacheWrite: 18.75 },
+  'claude-sonnet-4':  { input: 3.00,   output: 15.00,  cacheRead: 0.30,  cacheWrite: 3.75  },
+  'claude-haiku-4':   { input: 0.80,   output: 4.00,   cacheRead: 0.08,  cacheWrite: 1.00  },
+};
+
+function cost(usage, model) {
+  const rates = PRICING[model] ?? PRICING['claude-sonnet-4'];
+  const M = 1_000_000;
+  return (
+    (usage.input_tokens         ?? 0) / M * rates.input  +
+    (usage.output_tokens        ?? 0) / M * rates.output +
+    (usage.cache_read_tokens    ?? 0) / M * rates.cacheRead +
+    (usage.cache_creation_tokens ?? 0) / M * rates.cacheWrite
+  );
+}
+
+let event;
+try {
+  event = JSON.parse(readFileSync('/dev/stdin', 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const usage = event?.usage ?? event?.session_stats ?? {};
+const model = event?.model ?? 'claude-sonnet-4';
+const usd = cost(usage, model);
+
+const logPath = path.join(process.cwd(), '.claude', 'cost-log.json');
+let log = [];
+if (existsSync(logPath)) {
+  try { log = JSON.parse(readFileSync(logPath, 'utf8')); } catch { log = []; }
+}
+
+log.push({
+  timestamp: new Date().toISOString(),
+  model,
+  usage,
+  estimated_usd: +usd.toFixed(6),
+});
+
+// Keep last 500 sessions to cap file size
+if (log.length > 500) log = log.slice(-500);
+
+try {
+  writeFileSync(logPath, JSON.stringify(log, null, 2));
+  const total = log.reduce((sum, r) => sum + (r.estimated_usd ?? 0), 0);
+  console.error(
+    `[cost-tracker] Session cost: ~$${usd.toFixed(4)} | All-time logged: ~$${total.toFixed(2)}`
+  );
+} catch { /* read-only fs — skip silently */ }
+
+process.exit(0);