@claude-code-mastery/starter-kit 1.0.0

package/bin/cli.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import https from 'https';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+// ── low-level helpers (declared first — no hoisting dependency) ───────────────
+
+function paths(homeDir) {
+  const claudeDir = path.join(homeDir, '.claude');
+  return { claudeDir, starterKitDir: path.join(claudeDir, 'starter-kit') };
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function symlinkEntry(src, dest, label) {
+  if (fs.existsSync(dest)) {
+    if (fs.lstatSync(dest).isSymbolicLink()) return; // already linked
+    console.log(`  ⚠  Skipped ${label} — existing user file at ${dest}`);
+    return;
+  }
+  fs.symlinkSync(src, dest);
+  console.log(`  Linked ${label}`);
+}
+
+function symlinkFiles(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) return;
+  ensureDir(destDir);
+  for (const name of fs.readdirSync(srcDir)) {
+    symlinkEntry(path.join(srcDir, name), path.join(destDir, name), name);
+  }
+}
+
+function symlinkDirs(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) return;
+  ensureDir(destDir);
+  for (const name of fs.readdirSync(srcDir)) {
+    const src = path.join(srcDir, name);
+    if (fs.statSync(src).isDirectory()) {
+      symlinkEntry(src, path.join(destDir, name), name);
+    }
+  }
+}
+
+function readInstalledVersion(homeDir) {
+  const { starterKitDir } = paths(homeDir);
+  const versionFile = path.join(starterKitDir, 'version');
+  return fs.existsSync(versionFile) ? fs.readFileSync(versionFile, 'utf8').trim() : null;
+}
+
+function fetchLatestVersion() {
+  return new Promise((resolve, reject) => {
+    https.get(
+      'https://registry.npmjs.org/@claude-code-mastery/starter-kit/latest',
+      { headers: { Accept: 'application/json' } },
+      res => {
+        let body = '';
+        res.on('data', chunk => { body += chunk; });
+        res.on('end', () => {
+          try { resolve(JSON.parse(body).version); } catch { reject(new Error('parse')); }
+        });
+      },
+    ).on('error', reject);
+  });
+}
+
+// ── exported helpers ──────────────────────────────────────────────────────────
+
+export function rewriteHookPath(command, starterKitDir) {
+  return command.replace(/(?<=^|\s)\.claude\/hooks\//g, `${starterKitDir}/hooks/`);
+}
+
+export function copyPackageFiles(homeDir = os.homedir()) {
+  const { starterKitDir } = paths(homeDir);
+  ensureDir(starterKitDir);
+  fs.cpSync(path.join(PKG_ROOT, '.claude'), starterKitDir, { recursive: true, force: true });
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+  fs.writeFileSync(path.join(starterKitDir, 'version'), pkg.version, 'utf8');
+  console.log(`  Copied package files → ${starterKitDir}`);
+}
+
+export function symlinkAll(homeDir = os.homedir()) {
+  const { claudeDir, starterKitDir } = paths(homeDir);
+  symlinkFiles(path.join(starterKitDir, 'commands'),     path.join(claudeDir, 'commands'));
+  symlinkDirs(path.join(starterKitDir, 'skills'),        path.join(claudeDir, 'skills'));
+  symlinkFiles(path.join(starterKitDir, 'agents'),       path.join(claudeDir, 'agents'));
+  // Expose scaffolding templates at ~/.claude/.starter-kit/ so command files can
+  // reference .claude/.starter-kit/ from any project without a local kit install.
+  symlinkEntry(
+    path.join(starterKitDir, '.starter-kit'),
+    path.join(claudeDir, '.starter-kit'),
+    '.starter-kit',
+  );
+}
+
+export function mergeSettings(homeDir = os.homedir()) {
+  const { claudeDir, starterKitDir } = paths(homeDir);
+  const kitPath = path.join(starterKitDir, 'settings.json');
+  if (!fs.existsSync(kitPath)) return;
+
+  const kit    = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+  const glPath = path.join(claudeDir, 'settings.json');
+  const gl     = fs.existsSync(glPath) ? JSON.parse(fs.readFileSync(glPath, 'utf8')) : {};
+  if (!gl.hooks) gl.hooks = {};
+
+  for (const [event, groups] of Object.entries(kit.hooks ?? {})) {
+    if (!gl.hooks[event]) gl.hooks[event] = [];
+
+    for (const group of groups) {
+      const rewritten = (group.hooks ?? []).map(h => ({
+        ...h,
+        command: rewriteHookPath(h.command ?? '', starterKitDir),
+      }));
+
+      const registered = new Set(
+        gl.hooks[event].flatMap(g => (g.hooks ?? []).map(h => h.command)),
+      );
+      const fresh = rewritten.filter(h => !registered.has(h.command));
+      if (fresh.length === 0) continue;
+
+      const existing = gl.hooks[event].find(g => g.matcher === group.matcher);
+      if (existing) {
+        existing.hooks.push(...fresh);
+      } else {
+        gl.hooks[event].push({ ...group, hooks: fresh });
+      }
+      for (const h of fresh) console.log(`  Registered hook: ${h.command}`);
+    }
+  }
+
+  fs.writeFileSync(glPath, JSON.stringify(gl, null, 2), 'utf8');
+}
+
+// ── main commands ─────────────────────────────────────────────────────────────
+
+export async function init(homeDir = os.homedir()) {
+  const { claudeDir, starterKitDir } = paths(homeDir);
+  console.log('Installing @claude-code-mastery/starter-kit...\n');
+  copyPackageFiles(homeDir);
+  symlinkAll(homeDir);
+  mergeSettings(homeDir);
+  // Copy conf to ~/.claude/ and record source path
+  const confSrc = path.join(PKG_ROOT, 'claude-mastery-project.conf');
+  if (fs.existsSync(confSrc)) {
+    ensureDir(claudeDir);
+    fs.copyFileSync(confSrc, path.join(claudeDir, 'claude-mastery-project.conf'));
+    console.log(`  Copied claude-mastery-project.conf → ${claudeDir}`);
+  }
+  fs.writeFileSync(path.join(claudeDir, 'starter-kit-source-path'), starterKitDir, 'utf8');
+  const version = readInstalledVersion(homeDir);
+  console.log(`\n✅ Installed v${version} to ${starterKitDir}`);
+  console.log('   Run /starter-kit update inside Claude Code to update in future.\n');
+}
+
+export async function update(homeDir = os.homedir()) {
+  const { starterKitDir } = paths(homeDir);
+  if (!fs.existsSync(starterKitDir)) {
+    console.error('Not installed. Run: npx @claude-code-mastery/starter-kit init');
+    process.exit(1);
+  }
+  console.log(`Updating from v${readInstalledVersion(homeDir)}...\n`);
+  copyPackageFiles(homeDir);
+  symlinkAll(homeDir);
+  mergeSettings(homeDir);
+  console.log(`\n✅ Updated to v${readInstalledVersion(homeDir)}`);
+}
+
+export async function status(homeDir = os.homedir()) {
+  const installed = readInstalledVersion(homeDir);
+  if (!installed) {
+    console.log('Not installed. Run: npx @claude-code-mastery/starter-kit init');
+    return;
+  }
+  console.log(`Installed: v${installed}`);
+  try {
+    const latest = await fetchLatestVersion();
+    console.log(latest === installed
+      ? `Latest:    v${latest} (up to date ✅)`
+      : `Latest:    v${latest} (run /starter-kit update to upgrade)`);
+  } catch {
+    console.log('Latest:    (could not reach npm registry)');
+  }
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+const isMain = process.argv[1] && __filename === fs.realpathSync(process.argv[1]);
+if (isMain) {
+  const subcommand = process.argv[2];
+  switch (subcommand) {
+    case 'init':   await init();   break;
+    case 'update': await update(); break;
+    case 'status': await status(); break;
+    default:
+      console.log('Usage: npx @claude-code-mastery/starter-kit <init|update|status>');
+      process.exit(1);
+  }
+}

package/claude-mastery-project.conf

@@ -0,0 +1,220 @@
+# Claude Mastery Project Configuration
+# =====================================
+# Define reusable profiles for /new-project
+#
+# Usage:
+#   /new-project my-app clean            → Claude infrastructure only, zero coding opinions
+#   /new-project my-app default          → creates at ~/projects/my-app with full opinionated stack
+#   /new-project my-app api              → creates at ~/projects/my-app with API profile
+#   /new-project ./custom/path my-app    → explicit path overrides root_dir
+#   /new-project my-app default vercel   → profile + override
+#
+# Global settings:
+#   root_dir:        Default parent directory for new projects
+#                    If just a project name is given (no path), it creates at root_dir/<name>
+#                    Override by passing an explicit path (./foo, ~/bar, /abs/path)
+#   default_profile: Profile to use when no profile is specified in /new-project arguments
+#                    e.g. default_profile = clean  → /new-project my-app uses [clean] automatically
+#                    If not set, /new-project asks the user for all choices
+#   auto_branch:     Auto-create feature branches when commands detect you're on main (default: true)
+#                    Set to false if you prefer manual branch management
+#   sanitize:        Auto-sanitize all database query inputs (default: true, handled by StrictDB)
+#                    Set to false if you handle sanitization yourself
+#   docker_test_before_push:
+#                    When true, BLOCK any docker push until the image is built, run locally,
+#                    and verified to start without error (exit code 0, health check passes).
+#                    Default: false. Enable for production projects to prevent broken deploys.
+#
+# Profile values:
+#   type:            webapp | api | fullstack | cli
+#   language:        node | go | python (default: node)
+#   framework:
+#     Node.js frontend: vite | react | vue | svelte | sveltekit | angular | nuxt | next | astro
+#     Node.js backend:  fastify | express | hono
+#     Go:               gin | chi | echo | fiber | stdlib
+#     Python:           fastapi | django | flask
+#   hosting:         dokploy | vercel | static
+#   package_manager: pnpm | npm | bun | gomod | pip | uv | poetry
+#   database:        mongo | postgres | mysql | mssql | sqlite | none
+#   analytics:       rybbit | none
+#   options:         seo, ssr, tailwind, prisma, docker, ci, multiregion
+#   mcp:             playwright, context7, rulecatch, classmcp, strictdb
+#   npm:             additional npm packages (e.g., @rulecatch/ai-pooler, classpresso)
+#
+# Customize these profiles to match YOUR preferred stack.
+# Global fallback: ~/.claude/claude-mastery-project.conf
+
+[global]
+root_dir = ~/projects
+auto_branch = true    # Auto-create feature branches when on main (set false to disable)
+sanitize = true       # Auto-sanitize all database query inputs (handled by StrictDB, set false to disable)
+docker_test_before_push = false  # When true, must build + run + health-check locally before pushing to Docker Hub
+ask_task_on_build = false  # When true, /mdd Build Mode asks "feature or task?" before Phase 1 questions
+
+[clean]
+# All Claude Code infrastructure, zero coding opinions.
+# You get: .claude/ (commands, skills, agents, hooks), project-docs templates,
+#           CLAUDE.md (security rules only), .env pattern, .gitignore, tests/ templates.
+# You DON'T get: TypeScript enforcement, port assignments, database wrapper,
+#                testing frameworks, quality gates, API versioning, SEO rules.
+# Your project, your rules. Claude just works.
+opinionated = false
+
+[default]
+type = fullstack
+framework = next
+hosting = dokploy
+package_manager = pnpm
+database = mongo
+analytics = rybbit
+options = seo, tailwind, docker, ci
+mcp = playwright, context7, rulecatch, classmcp, strictdb
+npm = @rulecatch/ai-pooler, classpresso
+
+[api]
+type = api
+framework = fastify
+hosting = dokploy
+package_manager = pnpm
+database = mongo
+analytics = none
+options = docker, ci
+mcp = context7, rulecatch, strictdb
+npm = @rulecatch/ai-pooler
+
+[static-site]
+type = webapp
+framework = astro
+hosting = static
+package_manager = pnpm
+database = none
+analytics = rybbit
+options = seo, tailwind
+mcp = context7, classmcp
+npm = classpresso
+
+[quick]
+type = webapp
+framework = vite
+hosting = vercel
+package_manager = pnpm
+database = none
+analytics = none
+options = tailwind
+mcp = context7, classmcp
+npm = classpresso
+
+[enterprise]
+type = fullstack
+framework = next
+hosting = dokploy
+package_manager = pnpm
+database = mongo
+analytics = rybbit
+options = seo, ssr, tailwind, prisma, docker, ci, multiregion
+mcp = playwright, context7, rulecatch, classmcp, strictdb
+npm = @rulecatch/ai-pooler, classpresso
+
+[go]
+language = go
+type = api
+framework = gin
+hosting = dokploy
+package_manager = gomod
+database = mongo
+analytics = none
+options = docker, ci
+mcp = context7, rulecatch, strictdb
+
+[vue]
+language = node
+type = webapp
+framework = vue
+hosting = vercel
+package_manager = pnpm
+database = none
+analytics = rybbit
+options = tailwind
+mcp = playwright, context7, classmcp
+npm = classpresso
+
+[nuxt]
+language = node
+type = fullstack
+framework = nuxt
+hosting = dokploy
+package_manager = pnpm
+database = mongo
+analytics = rybbit
+options = seo, tailwind, docker, ci
+mcp = playwright, context7, rulecatch, classmcp, strictdb
+npm = classpresso
+
+[svelte]
+language = node
+type = webapp
+framework = svelte
+hosting = vercel
+package_manager = pnpm
+database = none
+analytics = rybbit
+options = tailwind
+mcp = playwright, context7, classmcp
+npm = classpresso
+
+[sveltekit]
+language = node
+type = fullstack
+framework = sveltekit
+hosting = dokploy
+package_manager = pnpm
+database = mongo
+analytics = rybbit
+options = seo, tailwind, docker, ci
+mcp = playwright, context7, rulecatch, classmcp, strictdb
+npm = classpresso
+
+[angular]
+language = node
+type = webapp
+framework = angular
+hosting = vercel
+package_manager = npm
+database = none
+analytics = rybbit
+options = tailwind
+mcp = playwright, context7, classmcp
+npm = classpresso
+
+[python-api]
+language = python
+type = api
+framework = fastapi
+hosting = dokploy
+package_manager = pip
+database = postgres
+analytics = none
+options = docker, ci
+mcp = context7, rulecatch, strictdb
+
+[django]
+language = python
+type = fullstack
+framework = django
+hosting = dokploy
+package_manager = pip
+database = postgres
+analytics = rybbit
+options = docker, ci
+mcp = context7, rulecatch, classmcp, strictdb
+
+[flask]
+language = python
+type = api
+framework = flask
+hosting = dokploy
+package_manager = pip
+database = postgres
+analytics = none
+options = docker, ci
+mcp = context7, strictdb

package/global-claude-md/CLAUDE.md

@@ -0,0 +1,212 @@
+# Global CLAUDE.md — Security Gatekeeper & Standards
+
+> Place this at ~/.claude/CLAUDE.md
+> It applies to EVERY project you work on.
+> Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+---
+
+## Identity
+
+- GitHub: **YourUsername**
+- SSH: `git@github.com:YourUsername/<repo>.git`
+
+---
+
+## NEVER EVER DO
+
+These rules are ABSOLUTE and apply to every project:
+
+### NEVER Publish Sensitive Data
+- NEVER publish passwords, API keys, tokens to git/npm/docker
+- Before ANY commit: verify no secrets included
+- NEVER output secrets in responses, logs, or suggestions
+
+### NEVER Commit .env Files
+- NEVER commit `.env` to git
+- ALWAYS verify `.env` is in `.gitignore`
+
+### NEVER Auto-Deploy
+- ALWAYS ask before deploying to production
+- NEVER assume approval — wait for explicit "yes, deploy"
+
+### NEVER Hardcode Credentials
+- ALWAYS use environment variables for secrets
+- NEVER put API keys, passwords, or tokens directly in source code
+
+### NEVER Publish Dynamic Data in Markdown Files
+- NEVER hardcode repo names, project names, or URLs in `.md` files
+- ALWAYS reference environment variables instead
+- BAD: `docker push myusername/myproject:latest`
+- GOOD: `docker push $DOCKER_HUB_REPO:latest`
+- This applies to: CLAUDE.md, README.md, CONTRIBUTING.md, and all documentation
+
+### NEVER Put Personal Instructions in Public Files
+- NEVER add personal workflows or non-project instructions to a project's main `CLAUDE.md`
+- ALWAYS store personal procedures in `.claude/LOCAL-INSTRUCTIONS.md` (gitignored)
+- Examples of what belongs there: social media workflows, personal tracking, marketing procedures
+
+### NEVER Rename Without a Plan
+- NEVER do project-wide search-and-replace renames without a checklist
+- Renaming causes cascading failures in .md, .env, comments, strings, and paths
+
+### NEVER Push Docker Images Without Local Testing
+- NEVER push a Docker image without testing it locally first
+- ALWAYS run the container and verify it starts correctly before pushing
+- Check for: no crash on startup, no 502 errors, basic pages load
+
+#### Docker Pre-Push Checklist
+1. Build: `docker build -t $IMAGE_NAME .`
+2. Run: `docker run -d -p 3000:3000 --name test-container $IMAGE_NAME`
+3. Wait for startup, then verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000` (expect 200)
+4. Check logs: `docker logs test-container`
+5. Clean up: `docker stop test-container && docker rm test-container`
+6. Only then push
+
+---
+
+## If Credentials Are Ever Exposed
+
+1. IMMEDIATELY rotate/change the exposed credentials
+2. Clean git history: `git filter-repo --replace-text <(echo 'OLD_SECRET==>REDACTED')`
+3. Force push: `git push --force origin main`
+4. Verify credentials are removed from ALL commits
+5. Alert anyone who may have cloned the repo
+
+---
+
+## New Project Setup
+
+When creating ANY new project:
+
+### Required Files
+- `.env` - Environment variables (NEVER commit)
+- `.env.example` - Template with placeholders (committed)
+- `.gitignore` - Must include: .env, .env.*, node_modules/, dist/, CLAUDE.local.md
+- `.dockerignore` - Must include: .env, .git/, node_modules/
+- `CLAUDE.md` - Project instructions
+- `tsconfig.json` - TypeScript configuration (strict mode)
+
+### Required Structure
+```
+project/
+├── src/
+├── tests/
+├── project-docs/
+├── .claude/
+│   ├── commands/
+│   ├── skills/
+│   └── agents/
+└── scripts/
+```
+
+### TypeScript - Always
+- All new files MUST be TypeScript
+- Use strict mode
+- Never use `any` unless absolutely necessary
+
+---
+
+## Local Instructions Storage
+
+When you have personal procedures that are NOT project code:
+
+- **Project `CLAUDE.md`** - code architecture, build/test/deploy commands, technical standards
+- **`.claude/LOCAL-INSTRUCTIONS.md`** - personal workflows, social media posting, marketing procedures, anything that shouldn't be in the public repo
+
+Setup:
+1. Create `.claude/` in the project root if it doesn't exist
+2. Add `.claude/` to `.gitignore`
+3. Create `.claude/LOCAL-INSTRUCTIONS.md` for personal procedures
+
+---
+
+## Markdown Writing Rules
+
+These apply to any `.md` file:
+
+### No Em Dashes
+- NEVER use em dashes (--)
+- ALWAYS use a regular hyphen (-) instead
+
+### Write Like a Human
+- Avoid AI writing patterns: no "delve into", "leverage", "seamlessly", "robust", "comprehensive", "streamline"
+- Be direct and specific - say what something does, not how impressive it is
+- No filler sentences that add length without adding meaning
+
+### No Repetition
+- NEVER repeat a point already made earlier in the same document
+- If the opening makes an argument, the body must go deeper - not restate it
+- Introductions and conclusions are the worst offenders
+
+---
+
+## Default File Locations
+
+### Documents and Reports
+When asked to create documents (PDF, MD, reports, notes) with no specified location:
+- ALWAYS default to the `/docs` directory in the project root
+- Create `/docs` if it doesn't exist
+- Add `/docs` to `.gitignore` - generated docs don't belong in git
+
+### Tracking Files (CSVs, Logs, Metrics)
+When tracking data in files:
+- ALWAYS create tracking files in `/docs`
+- NEVER commit tracking files to git
+- Before creating any tracking file: verify `/docs` is in `.gitignore`
+
+### Temporary AI Research Files
+When creating research notes, API doc summaries, or analysis during a session:
+- ALWAYS store in `_ai_temp/` directory
+- Add `_ai_temp/` to `.gitignore` if not already there
+- What goes here: research compilations, code analysis notes, temporary drafts, brainstorming
+
+---
+
+## Coding Standards (All Projects)
+
+### Error Handling
+- NEVER swallow errors silently
+- ALWAYS log errors with context before re-throwing
+- Add `process.on('unhandledRejection')` handler to entry points
+
+### Testing
+- ALWAYS define explicit success criteria
+- "Page loads" is NOT a success criterion
+- Every test must assert something meaningful
+
+### Quality Gates
+- No file > 300 lines (split if larger)
+- No function > 50 lines (extract helpers)
+- All tests must pass before committing
+- TypeScript compiles with no errors
+- No linter warnings
+
+### Database
+- ALWAYS use StrictDB for all database access (shared instance pattern)
+- NEVER create database connections in individual files
+
+### Async Performance
+- When multiple `await` calls are independent, ALWAYS use `Promise.all`
+- NEVER await independent operations sequentially - evaluate dependencies first
+
+---
+
+## Image Conversion
+
+When converting images to WebP:
+- Try `ffmpeg` first (most commonly available)
+- Fallback: `cwebp` then `convert` (ImageMagick)
+
+```bash
+ffmpeg -i input.png -quality 85 output.webp
+```
+
+---
+
+## Workflow
+
+- One task, one chat
+- Use `/clear` between unrelated tasks
+- Quality over speed - ask if unsure
+- Use Plan Mode for anything bigger than a simple fix

package/global-claude-md/settings.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}