@claude-code-mastery/starter-kit 1.0.0 → 1.2.0

package/README.npm.md

@@ -0,0 +1,190 @@
+# @claude-code-mastery/starter-kit
+
+A Claude Code toolkit that installs 27 commands, 10 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
+
+**Requires:** Node.js 20+ and [Claude Code](https://claude.ai/code)
+
+---
+
+## Install
+
+```bash
+npx @claude-code-mastery/starter-kit init
+```
+
+That's the only command you need to run once. Everything else happens inside Claude Code.
+
+---
+
+## What gets installed
+
+After `init`, your `~/.claude/` directory looks like this:
+
+```
+~/.claude/
+├── starter-kit/                  <- package files live here (single source of truth)
+│   ├── commands/                 <- 27 slash commands
+│   ├── hooks/                    <- 10 lifecycle hooks
+│   ├── skills/                   <- 10 skill files
+│   └── .starter-kit/             <- scaffolding templates for /new-project
+├── commands/
+│   ├── new-project.md  -> (symlink to starter-kit/commands/new-project.md)
+│   ├── review.md       -> (symlink to starter-kit/commands/review.md)
+│   └── ...             -> one symlink per command
+├── skills/
+│   ├── code-review/    -> (symlink to starter-kit/skills/code-review/)
+│   └── ...
+└── settings.json       <- hooks registered with absolute paths
+```
+
+Commands and skills are **symlinked**, not copied. When you update the package, the symlinks point to the new files immediately - no re-linking needed.
+
+Hooks are registered by absolute path in `~/.claude/settings.json`, which is the same pattern Claude Code uses for its own global configuration.
+
+---
+
+## Commands
+
+Once installed, these slash commands are available in every Claude Code session:
+
+| Command | What it does |
+|---|---|
+| `/new-project <name> [profile]` | Scaffold a new project with full Claude Code tooling |
+| `/convert-project-to-starter-kit` | Add kit infrastructure to an existing project (non-destructive) |
+| `/add-feature <capability>` | Add MongoDB, Docker, testing, etc. to an existing project |
+| `/review` | Review code for bugs, security issues, and best practices |
+| `/commit` | Generate a conventional commit message from staged changes |
+| `/create-api <resource>` | Scaffold a full API endpoint with route, handler, types, and tests |
+| `/create-e2e <feature>` | Create a Playwright E2E test with explicit success criteria |
+| `/refactor <file>` | Refactor a file following project best practices |
+| `/security-check` | Scan for exposed secrets, missing .gitignore entries, unsafe patterns |
+| `/optimize-docker` | Audit a Dockerfile against 12 best practices |
+| `/diagram <type>` | Generate architecture, API, database, or infrastructure diagrams |
+| `/worktree <name>` | Create an isolated git worktree and branch for a task |
+| `/setup` | Configure .env, GitHub, Docker, analytics, and services interactively |
+| `/test-plan <feature>` | Generate a structured test plan |
+| `/progress` | Show what's done, pending, and next in the project |
+| `/starter-kit update` | Update to the latest version from npm |
+| `/starter-kit status` | Show installed version vs latest |
+| `/starter-kit add` | Install the kit into the current project's .claude/ directory |
+
+---
+
+## Skills
+
+Skills are expertise files Claude loads when relevant. These install automatically:
+
+- `code-review` - security, performance, and correctness checks with severity rankings
+- `test-writer` - tests with explicit assertions and realistic data
+- `debugger` - root cause diagnosis for crashes, stack traces, and intermittent bugs
+- `dependency-vetting` - supply-chain risk assessment before adding a package
+- `design-review` - usability, accessibility, and visual feedback on UI
+- `mongodb-rules` - native-driver and StrictDB rules for MongoDB data access
+- `api-conventions` - routing and layering conventions for service code
+- `create-service` - scaffolding patterns for new services
+- `mcp-builder` - MCP server development patterns
+- `terminal-tui` - Ink + React TUI patterns, resize handling
+
+---
+
+## Hooks
+
+Hooks fire automatically during Claude Code sessions:
+
+| Hook | When it fires | What it does |
+|---|---|---|
+| `check-branch.sh` | Before commit | Blocks commits directly to main |
+| `check-rybbit.sh` | Before deploy commands | Ensures analytics are configured |
+| `check-ports.sh` | Before starting servers | Checks for port conflicts |
+| `check-e2e.sh` | Before E2E tests | Validates test configuration |
+| `check-env-sync.sh` | After editing .env | Flags when .env.example is out of sync |
+| `check-rulecatch.sh` | After commits | Runs RuleCatch violation checks |
+| `block-dangerous-bash.py` | Before Bash tool | Blocks destructive shell commands |
+| `check-file-length.py` | After Write/Edit | Warns when files exceed 300 lines |
+| `lint-on-save.sh` | After Write/Edit | Runs linter on changed files |
+| `verify-no-secrets.sh` | Before commit | Scans staged files for secrets |
+
+---
+
+## How Claude Code discovers the installed content
+
+Claude Code does not scan `node_modules/`. Instead it looks in specific directories:
+
+| Content type | Where Claude Code looks |
+|---|---|
+| Commands | `~/.claude/commands/` and `<project>/.claude/commands/` |
+| Skills | `~/.claude/skills/` and `<project>/.claude/skills/` |
+| Hooks | Absolute paths registered in `~/.claude/settings.json` |
+
+After `init`, the package files live in `~/.claude/starter-kit/` and are exposed via symlinks and hook registrations in exactly the places Claude Code already checks. No configuration changes to Claude Code are needed.
+
+---
+
+## Updating
+
+```bash
+npx @claude-code-mastery/starter-kit update
+```
+
+Or from inside Claude Code after the first install:
+
+```
+/starter-kit update
+```
+
+This overwrites `~/.claude/starter-kit/` with the latest package content. Because commands and skills are symlinked, they reflect the update without any re-linking step.
+
+---
+
+## Adding to a specific project
+
+To give a project its own local copy of the commands and hooks (useful for team repos):
+
+```
+/starter-kit add
+```
+
+This copies from `~/.claude/starter-kit/` into the current project's `.claude/` directory. Existing files are not overwritten.
+
+---
+
+## Checking what's installed
+
+```bash
+npx @claude-code-mastery/starter-kit status
+```
+
+Or from Claude Code:
+
+```
+/starter-kit status
+```
+
+---
+
+## Profiles for /new-project
+
+The `/new-project` command uses profiles to scaffold different project types:
+
+| Profile | What it creates |
+|---|---|
+| `clean` | Minimal structure - just the Claude Code tooling, no framework |
+| `node` (default) | Node.js + TypeScript, Express or similar, StrictDB |
+| `go` | Go project with standard layout, golangci-lint, Makefile |
+| `python` | Python + FastAPI or Django, pytest, ruff, Pydantic |
+
+```bash
+# Examples inside Claude Code:
+/new-project my-api node
+/new-project my-service go
+/new-project my-site clean
+```
+
+---
+
+## Source and contributing
+
+The package content lives in the starter kit repo:
+[github.com/TheDecipherist/claude-code-mastery-project-starter-kit](https://github.com/TheDecipherist/claude-code-mastery-project-starter-kit)
+
+Clone the repo to customize commands, hooks, or skills for your own team, or fork it and publish under your own org.

package/bin/cli.js

@@ -80,7 +80,29 @@ export function rewriteHookPath(command, starterKitDir) {
 export function copyPackageFiles(homeDir = os.homedir()) {
   const { starterKitDir } = paths(homeDir);
   ensureDir(starterKitDir);
+  // Copy .claude/ subdirectory contents (commands, hooks, skills, agents, .starter-kit, settings.json)
   fs.cpSync(path.join(PKG_ROOT, '.claude'), starterKitDir, { recursive: true, force: true });
+  // Copy root template files that command files reference via $SOURCE/<file>
+  const rootTemplates = [
+    'CLAUDE.md',
+    '.env.example',
+    '.gitignore',
+    '.dockerignore',
+    'vitest.config.ts',
+    'playwright.config.ts',
+    'tsconfig.json',
+    'scripts',
+  ];
+  for (const name of rootTemplates) {
+    const src = path.join(PKG_ROOT, name);
+    if (!fs.existsSync(src)) continue;
+    const dest = path.join(starterKitDir, name);
+    if (fs.statSync(src).isDirectory()) {
+      fs.cpSync(src, dest, { recursive: true, force: true });
+    } else {
+      fs.copyFileSync(src, dest);
+    }
+  }
   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}`);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@claude-code-mastery/starter-kit",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Production-ready Claude Code starter kit — commands, hooks, skills, and agents for AI-assisted development",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "@claude-code-mastery/starter-kit": "./bin/cli.js"
+    "starter-kit": "bin/cli.js"
   },
   "files": [
     ".claude/commands/",
@@ -18,7 +18,15 @@
     ".claude/settings.json",
     "bin/",
     "claude-mastery-project.conf",
-    "global-claude-md/"
+    "global-claude-md/",
+    "CLAUDE.md",
+    ".env.example",
+    ".gitignore",
+    ".dockerignore",
+    "vitest.config.ts",
+    "playwright.config.ts",
+    "tsconfig.json",
+    "scripts/"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
@@ -53,7 +61,9 @@
     "ai:monitor": "npx @rulecatch/ai-pooler monitor --no-api-key",
     "docker:optimize": "echo 'Run /optimize-docker in Claude Code to audit your Dockerfile'",
     "clean": "rm -rf dist coverage test-results playwright-report",
-    "precommit": "tsc --noEmit"
+    "precommit": "tsc --noEmit",
+    "prepack": "mv README.md _gh_readme.md && cp README.npm.md README.md",
+    "postpack": "mv _gh_readme.md README.md"
   },
   "engines": {
     "node": ">=20.0.0"

package/playwright.config.ts

@@ -0,0 +1,79 @@
+/**
+ * Playwright E2E Test Configuration
+ *
+ * IMPORTANT: E2E tests run on TEST PORTS, not dev ports.
+ * This prevents conflicts with running dev servers.
+ *
+ * Test Ports (from CLAUDE.md — NEVER CHANGE):
+ *   Website:   4000
+ *   API:       4010
+ *   Dashboard: 4020
+ *
+ * Dev Ports (for development — NOT used in tests):
+ *   Website:   3000
+ *   API:       3001
+ *   Dashboard: 3002
+ */
+
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report' }],
+    ['list'],
+  ],
+  outputDir: 'test-results',
+
+  use: {
+    /* Base URL for E2E tests — uses TEST port, not dev port */
+    baseURL: 'http://localhost:4000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+  ],
+
+  /* Start services on TEST ports before running E2E tests */
+  webServer: [
+    {
+      command: 'pnpm dev:test:website',
+      port: 4000,
+      reuseExistingServer: !process.env.CI,
+      timeout: 30_000,
+    },
+    {
+      command: 'pnpm dev:test:api',
+      port: 4010,
+      reuseExistingServer: !process.env.CI,
+      timeout: 30_000,
+    },
+    {
+      command: 'pnpm dev:test:dashboard',
+      port: 4020,
+      reuseExistingServer: !process.env.CI,
+      timeout: 30_000,
+    },
+  ],
+});

package/scripts/build-content.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env npx tsx
+/**
+ * build-content.ts — Markdown-to-HTML Article Builder (CLI)
+ *
+ * Converts markdown files to fully SEO-ready static HTML pages using a
+ * JSON config file as the single source of truth.
+ *
+ * Based on the production article builder from TheDecipherist.
+ * https://github.com/TheDecipherist/claude-code-mastery
+ *
+ * USAGE:
+ *   npx tsx scripts/build-content.ts                    # Build all published
+ *   npx tsx scripts/build-content.ts --id getting-started # Build one article
+ *   npx tsx scripts/build-content.ts --list             # List all articles
+ *   npx tsx scripts/build-content.ts --dry-run          # Show what would build
+ *
+ * CONFIG:
+ *   Edit scripts/content.config.json to add/modify articles.
+ *   Each article needs: id, mdSource, htmlOutput, title, description, url
+ *
+ * MODULES:
+ *   scripts/content/types.ts             — Types & Zod validation
+ *   scripts/content/markdown-processor.ts — Markdown → HTML conversion
+ *   scripts/content/seo-generator.ts     — Schema.org JSON-LD
+ *   scripts/content/sidebar-generator.ts — Sidebar TOC & navigation
+ *   scripts/content/html-template.ts     — Full HTML page assembly
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { ContentConfigSchema } from './content/types.js';
+import { buildArticle } from './content/html-template.js';
+
+function main(): void {
+  const args = process.argv.slice(2);
+  const configPath = path.resolve(import.meta.dirname ?? __dirname, 'content.config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(`Config not found: ${configPath}`);
+    console.error('Create scripts/content.config.json first.');
+    process.exit(1);
+  }
+
+  const raw: unknown = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const parsed = ContentConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    console.error('\n  Invalid content.config.json:\n');
+    for (const issue of parsed.error.issues) {
+      console.error(`    - ${issue.path.join('.')}: ${issue.message}`);
+    }
+    console.error('');
+    process.exit(1);
+  }
+  const config = parsed.data;
+
+  const published = config.articles.filter((a) => a.published);
+
+  // --list
+  if (args.includes('--list')) {
+    console.log(`\n  ${config.articles.length} articles (${published.length} published):\n`);
+    for (const a of config.articles) {
+      const status = a.published ? '\u2713' : '\u25CB';
+      console.log(`    ${status} ${a.id.padEnd(35)} ${a.category ?? ''}`);
+    }
+    console.log('');
+    return;
+  }
+
+  // --dry-run
+  if (args.includes('--dry-run')) {
+    console.log(`\n  Would build ${published.length} articles:\n`);
+    for (const a of published) {
+      console.log(`    ${a.mdSource} \u2192 ${a.htmlOutput}`);
+    }
+    console.log('');
+    return;
+  }
+
+  // --id <article-id>
+  const idIdx = args.indexOf('--id');
+  if (idIdx !== -1) {
+    const targetId = args[idIdx + 1];
+    const article = config.articles.find((a) => a.id === targetId);
+    if (!article) {
+      console.error(`Article not found: ${targetId}`);
+      console.error('Run with --list to see available articles.');
+      process.exit(1);
+    }
+    console.log(`\n  Building: ${article.id}\n`);
+    buildArticle(article, config);
+    console.log('\n  Done.\n');
+    return;
+  }
+
+  // Default: build all published
+  if (published.length === 0) {
+    console.log('\n  No published articles to build.\n');
+    return;
+  }
+
+  console.log(`\n  Building ${published.length} published article(s)...\n`);
+  for (const article of published) {
+    buildArticle(article, config);
+  }
+  console.log(`\n  Done. ${published.length} articles built.\n`);
+}
+
+main();

package/scripts/content/html-template.ts

@@ -0,0 +1,144 @@
+/**
+ * Content Builder — HTML Page Template
+ *
+ * Assembles final HTML pages from processed content, SEO data, and sidebar.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { ArticleConfig, ContentConfig, CollectedHeading } from './types.js';
+import { convertMarkdownToHtml } from './markdown-processor.js';
+import { generateSchemaJson } from './seo-generator.js';
+import { generateSidebarHtml } from './sidebar-generator.js';
+
+export function buildArticle(article: ArticleConfig, config: ContentConfig): void {
+  const markdown = fs.readFileSync(article.mdSource, 'utf8').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+  const headings: CollectedHeading[] = [];
+
+  // Remove first H1 (shown in header)
+  const processedMd = markdown.replace(/^# .*\n+/, '');
+  const articleContent = convertMarkdownToHtml(processedMd.trim(), headings);
+
+  const sidebarHtml = generateSidebarHtml(article, headings);
+  const hasSidebar = article.sidebar === true;
+
+  const mainSection = hasSidebar
+    ? `    <div class="article-layout">
+${sidebarHtml}
+        <main>
+            <article class="article-content">
+${articleContent}
+            </article>
+        </main>
+    </div>
+    <div class="sidebar-overlay" id="sidebarOverlay"></div>
+    <button class="sidebar-toggle" id="sidebarToggle">Contents</button>`
+    : `    <main>
+        <article class="article-content">
+${articleContent}
+        </article>
+    </main>`;
+
+  const sidebarJs = hasSidebar ? generateSidebarJs() : '';
+
+  const fullHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${article.title} — ${config.siteName}</title>
+    <meta name="description" content="${article.description}">
+    <meta name="author" content="${config.author}">
+    <meta name="robots" content="index, follow">
+    <link rel="canonical" href="${article.url}">
+
+    <!-- Open Graph / Facebook -->
+    <meta property="og:type" content="article">
+    <meta property="og:url" content="${article.url}">
+    <meta property="og:title" content="${article.title} — ${config.siteName}">
+    <meta property="og:description" content="${article.description}">
+    ${article.bannerImage ? `<meta property="og:image" content="${config.siteUrl}${article.bannerImage}">` : ''}
+    <meta property="og:site_name" content="${config.siteName}">
+
+    <!-- Twitter -->
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:title" content="${article.title} — ${config.siteName}">
+    <meta name="twitter:description" content="${article.description}">
+    ${article.bannerImage ? `<meta name="twitter:image" content="${config.siteUrl}${article.bannerImage}">` : ''}
+
+    <!-- Schema.org -->
+${generateSchemaJson(article, config)}
+
+    <!-- Syntax highlighting -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css">
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+
+    <!-- Add your CSS here -->
+    <link rel="stylesheet" href="/css/global.css">
+    <link rel="stylesheet" href="/css/article.css">
+</head>
+<body>
+    <header>
+        <h1>${article.titleHtml ?? article.title}</h1>
+        ${article.subtitle ? `<p class="subtitle">${article.subtitle}</p>` : ''}
+    </header>
+
+    ${article.bannerImage ? `<div class="hero-banner" role="img" aria-label="${article.bannerAlt ?? article.title}" style="background-image: url('${article.bannerImage}')"></div>` : ''}
+
+${mainSection}
+
+    <script>
+        document.addEventListener('DOMContentLoaded', function() {
+            document.querySelectorAll('pre code').forEach(function(block) {
+                hljs.highlightElement(block);
+            });
+        });
+${sidebarJs}
+    </script>
+</body>
+</html>`;
+
+  const outputDir = path.dirname(article.htmlOutput);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.writeFileSync(article.htmlOutput, fullHtml);
+  const sizeKb = (fullHtml.length / 1024).toFixed(1);
+  console.log(`  \u2713 ${article.id} \u2192 ${article.htmlOutput} (${sizeKb} KB, ${headings.length} headings)`);
+}
+
+function generateSidebarJs(): string {
+  return `
+        // Sidebar scroll spy
+        (function() {
+            var tocLinks = document.querySelectorAll('.sidebar-toc a');
+            var headings = [];
+            tocLinks.forEach(function(link) {
+                var id = link.getAttribute('href').slice(1);
+                var heading = document.getElementById(id);
+                if (heading) headings.push({ el: heading, link: link });
+            });
+            if (headings.length > 0) {
+                var observer = new IntersectionObserver(function(entries) {
+                    entries.forEach(function(entry) {
+                        if (entry.isIntersecting) {
+                            tocLinks.forEach(function(l) { l.classList.remove('active'); });
+                            var match = headings.find(function(h) { return h.el === entry.target; });
+                            if (match) match.link.classList.add('active');
+                        }
+                    });
+                }, { rootMargin: '-80px 0px -70% 0px' });
+                headings.forEach(function(h) { observer.observe(h.el); });
+            }
+            var sidebar = document.getElementById('articleSidebar');
+            var overlay = document.getElementById('sidebarOverlay');
+            var toggle = document.getElementById('sidebarToggle');
+            function openSidebar() { if (sidebar) sidebar.classList.add('open'); if (overlay) overlay.classList.add('open'); }
+            function closeSidebar() { if (sidebar) sidebar.classList.remove('open'); if (overlay) overlay.classList.remove('open'); }
+            if (toggle) toggle.addEventListener('click', openSidebar);
+            if (overlay) overlay.addEventListener('click', closeSidebar);
+            tocLinks.forEach(function(link) { link.addEventListener('click', closeSidebar); });
+        })();`;
+}