@quanticjs/create-app 0.1.1

package/dist/utils/template.d.ts

@@ -0,0 +1,10 @@
+export interface TemplateContext {
+    projectName: string;
+    projectDescription: string;
+    projectNameUnderscored: string;
+    projectNamePascal: string;
+    modules: string[];
+}
+export declare function renderTemplate(templatePath: string, ctx: TemplateContext): string;
+export declare function writeFile(filePath: string, content: string): void;
+export declare function renderAndWrite(templatePath: string, outputPath: string, ctx: TemplateContext): void;

package/dist/utils/template.js

@@ -0,0 +1,20 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ejs from 'ejs';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates');
+export function renderTemplate(templatePath, ctx) {
+    const fullPath = join(TEMPLATES_DIR, templatePath);
+    const content = readFileSync(fullPath, 'utf-8');
+    return ejs.render(content, ctx);
+}
+export function writeFile(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, 'utf-8');
+}
+export function renderAndWrite(templatePath, outputPath, ctx) {
+    const content = renderTemplate(templatePath, ctx);
+    writeFile(outputPath, content);
+}
+//# sourceMappingURL=template.js.map

package/dist/utils/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,GAAG,MAAM,KAAK,CAAC;AAEtB,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AAU/D,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,GAAoB;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,OAAO,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,OAAe;IACzD,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,UAAkB,EAClB,GAAoB;IAEpB,MAAM,OAAO,GAAG,cAAc,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAClD,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/utils/validate.d.ts

@@ -0,0 +1,4 @@
+export declare function validateProjectName(name: string): string | true;
+export declare function validateModuleName(name: string): string | true;
+export declare function toUnderscored(kebab: string): string;
+export declare function toPascalCase(kebab: string): string;

package/dist/utils/validate.js

@@ -0,0 +1,27 @@
+const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export function validateProjectName(name) {
+    if (!name)
+        return 'Project name is required';
+    if (!KEBAB_RE.test(name))
+        return 'Must be kebab-case (e.g. cr-workflow)';
+    if (name.length > 50)
+        return 'Must be 50 characters or fewer';
+    return true;
+}
+export function validateModuleName(name) {
+    if (!name)
+        return 'Module name is required';
+    if (!KEBAB_RE.test(name))
+        return 'Must be kebab-case (e.g. change-request)';
+    return true;
+}
+export function toUnderscored(kebab) {
+    return kebab.replace(/-/g, '_');
+}
+export function toPascalCase(kebab) {
+    return kebab
+        .split('-')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('');
+}
+//# sourceMappingURL=validate.js.map

package/dist/utils/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,+BAA+B,CAAC;AAEjD,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,IAAI;QAAE,OAAO,0BAA0B,CAAC;IAC7C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,uCAAuC,CAAC;IACzE,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,gCAAgC,CAAC;IAC9D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC,IAAI;QAAE,OAAO,yBAAyB,CAAC;IAC5C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,0CAA0C,CAAC;IAC5E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@quanticjs/create-app",
+  "version": "0.1.1",
+  "description": "Scaffold a QuanticJS project — NestJS modular monolith + React frontend",
+  "bin": {
+    "create-quanticjs-app": "./dist/index.js"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "quanticjs",
+    "nestjs",
+    "react",
+    "scaffold",
+    "cli",
+    "cqrs"
+  ],
+  "author": "QuanticJS",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ejs": "^3.1.10",
+    "inquirer": "^9.3.0",
+    "ora": "^8.1.0"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5",
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/backend/app.module.ts.ejs

@@ -0,0 +1,61 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { CqrsModule } from '@nestjs/cqrs';
+import { ScheduleModule } from '@nestjs/schedule';
+import { LoggerModule } from 'nestjs-pino';
+import { QuanticModule } from '@nestjs-cqrs/quanticjs';
+import { QuanticHealthModule } from '@quanticjs/core';
+import { BffModule } from './bff/bff.module';
+<% modules.forEach(function(mod) { -%>
+import { <%= toPascalCase(mod) %>Module } from './<%= mod %>/<%= mod %>.module';
+<% }); -%>
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+
+    LoggerModule.forRoot({
+      pinoHttp: {
+        transport:
+          process.env.NODE_ENV !== 'production'
+            ? { target: 'pino-pretty', options: { colorize: true } }
+            : undefined,
+        serializers: {
+          req: (req: any) => ({ id: req.id, method: req.method, url: req.url }),
+          res: (res: any) => ({ statusCode: res.statusCode }),
+        },
+      },
+    }),
+
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        type: 'postgres',
+        host: config.get('DATABASE_HOST', 'localhost'),
+        port: config.get<number>('DATABASE_PORT', 5432),
+        username: config.get('DATABASE_USER', 'postgres'),
+        password: config.get('DATABASE_PASSWORD', 'postgres'),
+        database: config.get('DATABASE_NAME', '<%= projectNameUnderscored %>'),
+        autoLoadEntities: true,
+        synchronize: false,
+        logging: config.get('NODE_ENV') !== 'production',
+      }),
+    }),
+
+    QuanticModule.forRoot({
+      redis: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
+    }),
+
+    QuanticHealthModule.forRoot(),
+    ScheduleModule.forRoot(),
+    CqrsModule.forRoot(),
+
+    BffModule,
+<% modules.forEach(function(mod) { -%>
+    <%= toPascalCase(mod) %>Module,
+<% }); -%>
+  ],
+})
+export class AppModule {}

package/templates/backend/bff.controller.ts.ejs

@@ -0,0 +1,60 @@
+import { Controller, Get, Post, Req, Res, Query } from '@nestjs/common';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import { Request, Response } from 'express';
+import { Public } from '@nestjs-cqrs/quanticjs';
+import { BffService } from './bff.service';
+
+@ApiTags('auth')
+@Controller('auth')
+export class BffController {
+  constructor(private readonly bffService: BffService) {}
+
+  @Public()
+  @Get('login')
+  @ApiOperation({ summary: 'Redirect to Keycloak login' })
+  login(
+    @Query('provider') provider: string,
+    @Query('returnTo') returnTo: string,
+    @Res() res: Response,
+  ) {
+    // TODO: implement PKCE + Keycloak redirect
+    res.redirect('/');
+  }
+
+  @Public()
+  @Get('callback')
+  @ApiOperation({ summary: 'OIDC callback — exchange code for tokens' })
+  async callback(@Req() req: Request, @Res() res: Response) {
+    // TODO: exchange code, store tokens in Redis, set httpOnly cookie
+    res.redirect('/');
+  }
+
+  @Post('refresh')
+  @ApiOperation({ summary: 'Refresh access token' })
+  async refresh(@Req() req: Request) {
+    // TODO: refresh via Redis-stored refresh token
+    return { success: true };
+  }
+
+  @Post('logout')
+  @ApiOperation({ summary: 'Logout — clear session' })
+  async logout(@Req() req: Request, @Res() res: Response) {
+    // TODO: clear cookie, revoke Keycloak session, invalidate Redis
+    res.clearCookie('sid').json({ success: true });
+  }
+
+  @Get('me')
+  @ApiOperation({ summary: 'Get current user info' })
+  async me(@Req() req: Request) {
+    // TODO: read session from Redis, return user info
+    return {
+      id: '',
+      keycloakId: '',
+      email: '',
+      displayName: '',
+      role: 'user',
+      roles: ['user'],
+      permissions: [],
+    };
+  }
+}

package/templates/backend/bff.module.ts.ejs

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { BffController } from './bff.controller';
+import { BffService } from './bff.service';
+
+@Module({
+  controllers: [BffController],
+  providers: [BffService],
+  exports: [BffService],
+})
+export class BffModule {}

package/templates/backend/bff.service.ts.ejs

@@ -0,0 +1,6 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class BffService {
+  // TODO: implement session management (Redis), token exchange, PKCE
+}

package/templates/backend/create-schema.migration.ts.ejs

@@ -0,0 +1,15 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CreateSchemas<%= timestamp %> implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+<% modules.forEach(function(mod) { -%>
+    await queryRunner.query(`CREATE SCHEMA IF NOT EXISTS <%= mod.replace(/-/g, '_') %>`);
+<% }); -%>
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+<% modules.slice().reverse().forEach(function(mod) { -%>
+    await queryRunner.query(`DROP SCHEMA IF EXISTS <%= mod.replace(/-/g, '_') %> CASCADE`);
+<% }); -%>
+  }
+}

package/templates/backend/data-source.ts.ejs

@@ -0,0 +1,13 @@
+import { DataSource } from 'typeorm';
+
+export default new DataSource({
+  type: 'postgres',
+  host: process.env.DATABASE_HOST ?? 'localhost',
+  port: parseInt(process.env.DATABASE_PORT ?? '5432', 10),
+  username: process.env.DATABASE_USER ?? 'postgres',
+  password: process.env.DATABASE_PASSWORD ?? 'postgres',
+  database: process.env.DATABASE_NAME ?? '<%= projectNameUnderscored %>',
+  entities: ['src/**/entities/*.ts'],
+  migrations: ['src/migrations/*.ts'],
+  synchronize: false,
+});

package/templates/backend/env.example.ejs

@@ -0,0 +1,30 @@
+# Application
+NODE_ENV=development
+PORT=3000
+
+# Database
+DATABASE_HOST=postgres
+DATABASE_PORT=5432
+DATABASE_USER=postgres
+DATABASE_PASSWORD=postgres
+DATABASE_NAME=<%= projectNameUnderscored %>
+
+# Redis
+REDIS_URL=redis://redis:6379
+
+# Keycloak
+KEYCLOAK_URL=http://keycloak:8080
+KEYCLOAK_REALM=<%= projectName %>
+KEYCLOAK_CLIENT_ID=<%= projectName %>-backend
+KEYCLOAK_CLIENT_SECRET=change-me
+
+# Session
+SESSION_SECRET=change-me-in-production
+SESSION_COOKIE_NAME=sid
+
+# Sentry (optional)
+SENTRY_DSN=
+
+# Unleash (optional — features enabled by default if not set)
+UNLEASH_URL=
+UNLEASH_API_KEY=

package/templates/backend/main.ts.ejs

@@ -0,0 +1,43 @@
+import { NestFactory } from '@nestjs/core';
+import { ValidationPipe } from '@nestjs/common';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { Logger } from 'nestjs-pino';
+import * as cookieParser from 'cookie-parser';
+import { GlobalExceptionFilter, ResultInterceptor } from '@nestjs-cqrs/quanticjs';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+
+  app.useLogger(app.get(Logger));
+  app.use(cookieParser());
+  app.setGlobalPrefix('api', { exclude: ['auth/(.*)'] });
+
+  app.useGlobalFilters(app.get(GlobalExceptionFilter));
+  app.useGlobalInterceptors(app.get(ResultInterceptor));
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+    }),
+  );
+
+  if (process.env.NODE_ENV !== 'production') {
+    const config = new DocumentBuilder()
+      .setTitle('<%= projectNamePascal %>')
+      .setDescription('API documentation')
+      .setVersion('1.0')
+      .addBearerAuth()
+      .build();
+    const document = SwaggerModule.createDocument(app, config);
+    SwaggerModule.setup('api/docs', app, document);
+  }
+
+  app.enableShutdownHooks();
+
+  const port = process.env.PORT ?? 3000;
+  await app.listen(port);
+}
+bootstrap();

package/templates/backend/module.ts.ejs

@@ -0,0 +1,14 @@
+import { Module } from '@nestjs/common';
+import { CqrsModule } from '@nestjs/cqrs';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+const CommandHandlers: never[] = [];
+const QueryHandlers: never[] = [];
+const Validators: never[] = [];
+
+@Module({
+  imports: [CqrsModule, TypeOrmModule.forFeature([])],
+  controllers: [],
+  providers: [...CommandHandlers, ...QueryHandlers, ...Validators],
+})
+export class <%= modulePascal %>Module {}

package/templates/backend/nest-cli.json.ejs

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/templates/backend/package.json.ejs

@@ -0,0 +1,23 @@
+{
+  "name": "<%= projectName %>",
+  "version": "0.0.1",
+  "description": "<%= projectDescription %>",
+  "private": true,
+  "scripts": {
+    "build": "nest build",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:e2e": "jest --config ./test/jest-e2e.json",
+    "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js -d src/data-source.ts",
+    "migration:generate": "npm run typeorm -- migration:generate",
+    "migration:run": "npm run typeorm -- migration:run",
+    "migration:revert": "npm run typeorm -- migration:revert"
+  }
+}

package/templates/backend/tsconfig.build.json.ejs

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
+}

package/templates/backend/tsconfig.json.ejs

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2021",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/templates/claude/CLAUDE.md.ejs

@@ -0,0 +1,86 @@
+# <%= projectNamePascal %>
+
+## Stack
+
+- **Backend:** NestJS (modular monolith), CQRS with pipeline behaviors, TypeORM, PostgreSQL, Redis, Keycloak BFF auth
+- **Frontend:** React, Vite, TanStack Query, Zustand, React Hook Form + Zod, Tailwind CSS, shadcn/ui
+- **Infrastructure:** Docker Compose (local dev), Kubernetes + Helm + ArgoCD (production)
+
+## Architecture
+
+**Modular monolith.** One backend Docker image, one frontend Docker image. Modules communicate via CommandBus/QueryBus. Each module owns its own PostgreSQL schema.
+
+**CQRS.** Every operation is a Command/Query class + Handler. Controllers are thin — they only parse requests and dispatch to the bus.
+
+**BFF Authentication.** Tokens stored server-side in Redis. Browser gets httpOnly cookies only. No tokens in localStorage/sessionStorage ever.
+
+## Dev Workflow
+
+```bash
+# Start backend + infrastructure
+docker compose up
+
+# Start frontend (separate terminal)
+cd client && npm run dev
+
+# Browser
+open http://localhost:5173
+```
+
+**Ports:** 5173 (frontend/Vite), 3000 (backend API), 8080 (Keycloak)
+
+## Key Conventions
+
+- Database columns are **camelCase** (TypeORM default naming strategy)
+- Handlers return `Result<T>` — never throw for business errors
+- Validation: DTOs use class-validator, Commands use Zod via `@Validate`
+- Entities extend `BaseEntity` from the shared kernel
+- Generate migrations from entities: `npx typeorm migration:generate src/migrations/Name`
+
+## How to Build — Skill Routing
+
+Use the appropriate skill for each task. Skills enforce architectural rules automatically.
+
+| When you need to... | Use |
+|---|---|
+| Add a full feature (backend + frontend) | `/add-feature` (orchestrates all sub-skills) |
+| Add a command/query + validator + handler | `/add-handler` |
+| Add a TypeORM entity | `/add-entity` |
+| Generate a database migration | `/add-migration` |
+| Wire a handler to an HTTP endpoint | `/add-api-endpoint` |
+| Add an authenticated/role-gated endpoint | `/add-auth-endpoint` |
+| Create a new bounded context module | `/add-module` |
+| Add a React page with data fetching | `/add-frontend-page` |
+| Integrate an external API (AI, payment, etc.) | `/add-integration` |
+| Add inter-module async events | `/add-event` |
+| Add live WebSocket updates | `/add-realtime` |
+| Write backend tests | `/write-backend-tests` |
+| Write Playwright E2E tests | `/write-ui-tests` |
+| Find missing E2E coverage | `/e2e-scan` |
+| Walk through journeys via MCP browser | `/e2e-verify` |
+| Audit specs against real pages via MCP | `/e2e-audit` |
+| Run full E2E suite (scan + audit + verify) | `/e2e-full` |
+| Run the test suite | `/run-tests` |
+| Fix a bug (TDD workflow) | `/fix-bug` |
+| Review code before merge | `/review-code` |
+| Debug a failing service | `/debugging` |
+| Manage Docker dev environment | `/docker-dev` |
+| Write a feature spec | `/specify` |
+| Review a spec against rules | `/review-spec` (validates structure + rules compliance, writes corrected `-v2.md`) |
+| Implement an existing spec | `/implement-spec` (spec-driven, picks only needed sub-skills) |
+| Audit code against ADR rules | `/audit-rules` |
+
+**When in doubt, start with `/add-feature`** — it walks through the full flow. If a spec already exists in `docs/specs/`, use `/implement-spec` instead.
+
+## Test Commands
+
+```bash
+# Backend unit + integration tests
+npm test
+
+# Frontend tests
+cd client && npm test
+
+# E2E tests
+cd client && npx playwright test
+```

package/templates/claude/hooks/auto-format.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# PreToolUse hook: auto-format staged files before commit.
+# Exit 0 = allow (formatting is best-effort, never blocks commit).
+set -uo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Only run on git commit
+if ! echo "$COMMAND" | grep -qE "git commit" 2>/dev/null; then
+  exit 0
+fi
+
+# Format staged .ts/.tsx/.js/.jsx files
+FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(tsx?|jsx?)$' || true)
+
+if [[ -n "$FILES" ]]; then
+  echo "$FILES" | xargs npx prettier --write >/dev/null 2>&1 || true
+  echo "$FILES" | xargs git add 2>/dev/null || true
+fi
+
+exit 0

package/templates/claude/hooks/check-secrets.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# PreToolUse hook: prevent committing secrets.
+# Exit 0 = allow, Exit 2 = block (stderr shown to Claude as feedback)
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Only check git add and git commit commands
+if ! echo "$COMMAND" | grep -qE "git (add|commit)" 2>/dev/null; then
+  exit 0
+fi
+
+ERRORS=""
+
+# Check for .env files being staged
+if echo "$COMMAND" | grep -qE "git add" 2>/dev/null; then
+  if echo "$COMMAND" | grep -qE "\\.env" 2>/dev/null && ! echo "$COMMAND" | grep -qE "\\.env\\.example" 2>/dev/null; then
+    ERRORS="$ERRORS\n❌ .env file being staged — contains secrets. Add to .gitignore instead."
+  fi
+fi
+
+# Check staged files for secrets patterns
+STAGED=$(git diff --cached --name-only 2>/dev/null)
+if [[ -z "$STAGED" ]]; then
+  STAGED=$(git diff --name-only 2>/dev/null)
+fi
+
+for file in $STAGED; do
+  [[ -f "$file" ]] || continue
+  [[ "$file" == *.ts || "$file" == *.tsx || "$file" == *.js || "$file" == *.json || "$file" == *.yaml || "$file" == *.yml ]] || continue
+  [[ "$file" == *.spec.* || "$file" == *.test.* ]] && continue
+
+  if grep -qE "(API_KEY|SECRET_KEY|PRIVATE_KEY|PASSWORD)\s*=\s*['\"][^'\"]+['\"]" "$file" 2>/dev/null; then
+    ERRORS="$ERRORS\n❌ $file: Hardcoded secret detected. Use environment variables."
+  fi
+done
+
+# Check for private key files
+if echo "$COMMAND" | grep -qE "\\.pem|\\.key|\\.p12" 2>/dev/null; then
+  ERRORS="$ERRORS\n❌ Private key file being staged. These must never be committed."
+fi
+
+if [[ -n "$ERRORS" ]]; then
+  echo -e "$ERRORS" >&2
+  exit 2
+fi
+
+exit 0

package/templates/claude/hooks/guard-destructive.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# PreToolUse hook: block irreversible commands.
+# Exit 0 = allow, Exit 2 = block (stderr shown to Claude as feedback)
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# Force push to main/master
+if echo "$COMMAND" | grep -qE "git push.*--force.*(main|master)" 2>/dev/null; then
+  echo "❌ BLOCKED: Force push to main/master. This rewrites shared history permanently." >&2
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qE "git push.*-f.*(main|master)" 2>/dev/null; then
+  echo "❌ BLOCKED: Force push to main/master. This rewrites shared history permanently." >&2
+  exit 2
+fi
+
+# git reset --hard
+if echo "$COMMAND" | grep -qE "git reset --hard" 2>/dev/null; then
+  echo "❌ BLOCKED: git reset --hard discards uncommitted work permanently. Use git stash or create a backup branch first." >&2
+  exit 2
+fi
+
+# DROP TABLE / DROP DATABASE
+if echo "$COMMAND" | grep -qiE "DROP (TABLE|DATABASE|SCHEMA)" 2>/dev/null; then
+  echo "❌ BLOCKED: DROP TABLE/DATABASE/SCHEMA is irreversible. Confirm with the user before proceeding." >&2
+  exit 2
+fi
+
+# rm -rf / or rm -rf .
+if echo "$COMMAND" | grep -qE "rm -rf\s+(/|\.)\s*$" 2>/dev/null; then
+  echo "❌ BLOCKED: Catastrophic rm -rf target." >&2
+  exit 2
+fi
+
+exit 0