create-turniza-app 1.0.0 → 1.0.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright © 2025 Turniza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# 🚀 create-turniza-app
+
+A CLI scaffold for creating new **Turniza monorepo apps** with Flutter mobile + Astro web (Cloudflare Workers), pre-configured with a full DevSecOps pipeline.
+
+## What You Get
+
+A production-ready monorepo with:
+
+| Feature | Details |
+|---------|---------|
+| **Flutter mobile** | iOS + Android with 90+ lint rules + DCM |
+| **Astro web** | SSR on Cloudflare Workers |
+| **Makefile** | Single source of truth for all commands |
+| **Pre-commit hooks** | Lefthook → secrets, format, lint |
+| **Testing** | flutter_test, Vitest, Playwright |
+| **Security** | Secrets detection, dependency audit, license check |
+| **AI Agent context** | AGENTS.md, CLAUDE.md, GEMINI.md auto-generated |
+
+## Quick Start
+
+```bash
+# With bun
+bunx create-turniza-app my-app
+
+# With npx
+npx create-turniza-app my-app
+```
+
+The CLI will ask you:
+
+1. **Project name** (kebab-case)
+2. **Organization** (default: Turniza)
+3. **GitHub org/user** (default: Turniza)
+4. **Emoji** for your project
+5. **Description** of the project
+6. **Include mobile?** (Flutter – default: yes)
+7. **Include web?** (Astro + CF Workers – default: yes)
+8. **Init git?** (default: yes)
+9. **Install deps?** (default: yes)
+
+## Generated Project Structure
+
+```
+my-app/
+├── apps/
+│   ├── mobile/    Flutter app (iOS + Android)
+│   └── web/       Astro app (Cloudflare Workers SSR)
+├── packages/      Shared code (future)
+├── Makefile       Developer commands
+├── lefthook.yml   Pre-commit hooks
+├── .gitignore     Comprehensive ignore rules
+├── README.md      Project documentation
+├── SECURITY.md    Vulnerability disclosure policy
+├── AGENTS.md      AI agent instructions
+├── CLAUDE.md      AI agent instructions (Claude)
+└── GEMINI.md      AI agent instructions (Gemini)
+```
+
+## Prerequisites
+
+| Tool | Install |
+|------|---------|
+| Bun | `nix profile install nixpkgs#bun` |
+| Flutter | `nix profile install nixpkgs#flutter` (if using mobile) |
+| DCM | `brew install dcm` (optional, for Dart metrics) |
+| Lefthook | `brew install lefthook` |
+
+## Development
+
+```bash
+# Clone this repo
+git clone git@github.com:Turniza/create-turniza-app.git
+cd create-turniza-app
+
+# Install deps
+bun install
+
+# Test locally
+bun run src/index.ts my-test-app
+
+# Run tests
+make test
+```
+
+## Publishing
+
+```bash
+# Login to npm (first time only)
+npm login
+
+# Dry run
+make publish-dry
+
+# Publish
+make publish
+```
+
+After publishing, anyone can run:
+
+```bash
+bunx create-turniza-app my-project
+# or
+npx create-turniza-app my-project
+```
+
+## License
+
+MIT – © Turniza

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-turniza-app",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "description": "CLI scaffold for creating new Turniza monorepo apps (Flutter + Astro + Cloudflare Workers)",
     "type": "module",
     "bin": {
@@ -8,6 +8,7 @@
     },
     "scripts": {
         "dev": "bun run src/index.ts",
+        "test": "bun test src/",
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
@@ -43,4 +44,4 @@
         "node": ">=18",
         "bun": ">=1.0"
     }
-}
+}

package/src/prompts.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test';
+import { validateProjectName, toTitleCase, toSnakeCase } from './prompts.js';
+
+// ── validateProjectName ──────────────────────────────────────
+
+describe('validateProjectName', () => {
+    test('accepts valid kebab-case names', () => {
+        expect(validateProjectName('my-app')).toBe(true);
+        expect(validateProjectName('a')).toBe(true);
+        expect(validateProjectName('app123')).toBe(true);
+        expect(validateProjectName('my-cool-app-2')).toBe(true);
+    });
+
+    test('rejects empty string', () => {
+        expect(validateProjectName('')).toBe('Project name is required');
+    });
+
+    test('rejects names starting with a number', () => {
+        const result = validateProjectName('1app');
+        expect(result).toBeString();
+        expect(result).not.toBe(true);
+    });
+
+    test('rejects names with uppercase letters', () => {
+        const result = validateProjectName('MyApp');
+        expect(result).toBeString();
+        expect(result).not.toBe(true);
+    });
+
+    test('rejects names with special characters', () => {
+        expect(validateProjectName('my_app')).not.toBe(true);
+        expect(validateProjectName('my.app')).not.toBe(true);
+        expect(validateProjectName('my app')).not.toBe(true);
+        expect(validateProjectName('my@app')).not.toBe(true);
+    });
+
+    test('rejects names longer than 50 characters', () => {
+        const longName = 'a' + '-bcd'.repeat(20); // 81 chars
+        const result = validateProjectName(longName);
+        expect(result).toBe('Must be 50 characters or less');
+    });
+
+    test('accepts name exactly 50 characters', () => {
+        const name = 'a'.repeat(50);
+        expect(validateProjectName(name)).toBe(true);
+    });
+});
+
+// ── toTitleCase ──────────────────────────────────────────────
+
+describe('toTitleCase', () => {
+    test('converts kebab-case to Title Case', () => {
+        expect(toTitleCase('my-cool-app')).toBe('My Cool App');
+    });
+
+    test('converts snake_case to Title Case', () => {
+        expect(toTitleCase('my_cool_app')).toBe('My Cool App');
+    });
+
+    test('handles single word', () => {
+        expect(toTitleCase('app')).toBe('App');
+    });
+
+    test('handles mixed delimiters', () => {
+        expect(toTitleCase('my-cool_app')).toBe('My Cool App');
+    });
+});
+
+// ── toSnakeCase ─────────────────────────────────────────────
+
+describe('toSnakeCase', () => {
+    test('converts kebab-case to snake_case', () => {
+        expect(toSnakeCase('my-cool-app')).toBe('my_cool_app');
+    });
+
+    test('leaves snake_case unchanged', () => {
+        expect(toSnakeCase('my_app')).toBe('my_app');
+    });
+
+    test('leaves single word unchanged', () => {
+        expect(toSnakeCase('app')).toBe('app');
+    });
+});

package/src/prompts.ts

@@ -16,18 +16,18 @@ export interface ProjectOptions {
     compatibilityDate: string;
 }
 
-function toTitleCase(str: string): string {
+export function toTitleCase(str: string): string {
     return str
         .split(/[-_]/)
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join(' ');
 }
 
-function toSnakeCase(str: string): string {
+export function toSnakeCase(str: string): string {
     return str.replace(/-/g, '_');
 }
 
-function validateProjectName(name: string): boolean | string {
+export function validateProjectName(name: string): boolean | string {
     if (!name) return 'Project name is required';
     if (!/^[a-z][a-z0-9-]*$/.test(name)) {
         return 'Must be lowercase, start with a letter, and contain only letters, numbers, and hyphens';

package/src/scaffold.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { tmpdir } from 'os';
+import { mkdtemp, rm, readFile, writeFile, mkdir, readdir, stat } from 'fs/promises';
+import { join } from 'path';
+import { scaffoldProject } from './scaffold.js';
+import type { ProjectOptions } from './prompts.js';
+
+// ── Helpers ──────────────────────────────────────────────────
+
+function makeOptions(overrides: Partial<ProjectOptions> = {}): ProjectOptions {
+    return {
+        projectName: 'test-project',
+        projectTitle: 'Test Project',
+        projectDescription: 'A test project',
+        projectNameSnake: 'test_project',
+        org: 'TestOrg',
+        orgDomain: 'testorg.com',
+        githubOrg: 'TestOrg',
+        emoji: '🧪',
+        includeMobile: false,
+        includeWeb: false,
+        initGit: false,
+        installDeps: false,
+        compatibilityDate: '2026-01-01',
+        ...overrides,
+    };
+}
+
+let tmpDir: string;
+
+beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'scaffold-test-'));
+});
+
+afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── scaffoldProject ─────────────────────────────────────────
+
+describe('scaffoldProject', () => {
+    test('creates base project structure', async () => {
+        const origCwd = process.cwd();
+        process.chdir(tmpDir);
+
+        try {
+            await scaffoldProject(makeOptions());
+        } finally {
+            process.chdir(origCwd);
+        }
+
+        const projectDir = join(tmpDir, 'test-project');
+        const dirStat = await stat(projectDir);
+        expect(dirStat.isDirectory()).toBe(true);
+
+        // packages/.gitkeep should always exist
+        const gitkeep = join(projectDir, 'packages', '.gitkeep');
+        const gitkeepStat = await stat(gitkeep);
+        expect(gitkeepStat.isFile()).toBe(true);
+    });
+
+    test('throws when target directory already exists', async () => {
+        const origCwd = process.cwd();
+        process.chdir(tmpDir);
+
+        // Create the directory upfront
+        await mkdir(join(tmpDir, 'existing-project'));
+
+        try {
+            await expect(
+                scaffoldProject(makeOptions({ projectName: 'existing-project' })),
+            ).rejects.toThrow('already exists');
+        } finally {
+            process.chdir(origCwd);
+        }
+    });
+
+    test('renders Handlebars templates with project context', async () => {
+        const origCwd = process.cwd();
+        process.chdir(tmpDir);
+
+        try {
+            await scaffoldProject(makeOptions({ projectName: 'hbs-test' }));
+        } finally {
+            process.chdir(origCwd);
+        }
+
+        const projectDir = join(tmpDir, 'hbs-test');
+
+        // README.md should exist (from README.md.hbs) and contain the project name
+        const readmePath = join(projectDir, 'README.md');
+        const readme = await readFile(readmePath, 'utf-8');
+        expect(readme).toContain('hbs-test');
+    });
+
+    test('creates mobile directory only when includeMobile is true', async () => {
+        const origCwd = process.cwd();
+        process.chdir(tmpDir);
+
+        try {
+            await scaffoldProject(makeOptions({ projectName: 'no-mobile', includeMobile: false }));
+        } finally {
+            process.chdir(origCwd);
+        }
+
+        const mobileDir = join(tmpDir, 'no-mobile', 'apps', 'mobile');
+        await expect(stat(mobileDir)).rejects.toThrow();
+    });
+
+    test('creates web directory only when includeWeb is true', async () => {
+        const origCwd = process.cwd();
+        process.chdir(tmpDir);
+
+        try {
+            await scaffoldProject(makeOptions({ projectName: 'no-web', includeWeb: false }));
+        } finally {
+            process.chdir(origCwd);
+        }
+
+        const webDir = join(tmpDir, 'no-web', 'apps', 'web');
+        await expect(stat(webDir)).rejects.toThrow();
+    });
+
+    test('creates mobile directory when includeMobile is true', async () => {
+        const origCwd = process.cwd();
+        process.chdir(tmpDir);
+
+        try {
+            await scaffoldProject(makeOptions({ projectName: 'with-mobile', includeMobile: true }));
+        } finally {
+            process.chdir(origCwd);
+        }
+
+        const mobileDir = join(tmpDir, 'with-mobile', 'apps', 'mobile');
+        const mobileStat = await stat(mobileDir);
+        expect(mobileStat.isDirectory()).toBe(true);
+    });
+});

package/src/scaffold.ts

@@ -5,7 +5,7 @@ import chalk from 'chalk';
 import type { ProjectOptions } from './prompts.js';
 import { exec } from './utils.js';
 
-const TEMPLATES_DIR = resolve(import.meta.dirname, '../../templates');
+const TEMPLATES_DIR = resolve(import.meta.dirname, '../templates');
 
 /**
  * Main scaffold function: copies templates, processes Handlebars, and runs post-setup.

package/src/utils.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+import { tmpdir } from 'os';
+import { mkdtemp } from 'fs/promises';
+import { join } from 'path';
+import { exec } from './utils.js';
+
+describe('exec', () => {
+    test('returns trimmed stdout on success', async () => {
+        const result = await exec('echo hello');
+        expect(result).toBe('hello');
+    });
+
+    test('trims trailing whitespace from output', async () => {
+        const result = await exec('printf "  spaced  "');
+        expect(result).toBe('spaced');
+    });
+
+    test('rejects on non-zero exit code', async () => {
+        await expect(exec('exit 1')).rejects.toThrow('failed (exit 1)');
+    });
+
+    test('rejects with stderr content in error message', async () => {
+        await expect(exec('echo "oops" >&2 && exit 1')).rejects.toThrow('oops');
+    });
+
+    test('respects cwd option', async () => {
+        const tmp = await mkdtemp(join(tmpdir(), 'exec-test-'));
+        const result = await exec('pwd', { cwd: tmp });
+        // macOS /private/tmp vs /tmp – resolve both
+        expect(result).toContain(tmp.replace('/private', ''));
+    });
+
+    test('handles multi-line output', async () => {
+        const result = await exec('printf "line1\\nline2"');
+        expect(result).toBe('line1\nline2');
+    });
+});

package/templates/base/AGENTS.md.hbs

@@ -0,0 +1,98 @@
+# AGENTS.md – AI Agent Instructions
+
+> This file provides context for AI coding agents (Claude, Gemini, etc.) working on this repository.
+
+## Repository Overview
+
+**{{projectTitle}}** – {{projectDescription}}
+
+```
+{{projectName}}/
+{{#if includeMobile}}
+├── apps/mobile/ ← Flutter (iOS + Android)
+{{/if}}
+{{#if includeWeb}}
+├── apps/web/ ← Astro (Cloudflare Workers SSR)
+{{/if}}
+├── packages/ ← Shared code (future)
+├── Makefile ← Single source of truth for all commands
+└── lefthook.yml ← Pre-commit hooks (delegates to Makefile)
+```
+
+## Technology Stack
+
+| Component | Technology | Package Manager |
+|-----------|-----------|----------------|
+{{#if includeMobile}}
+| Mobile | Flutter 3.38 / Dart | pub |
+{{/if}}
+{{#if includeWeb}}
+| Web | Astro + TypeScript | bun |
+| Web Deploy | Cloudflare Workers | wrangler |
+{{/if}}
+{{#if includeMobile}}
+| Linting (Dart) | flutter_lints + DCM (integrated in analysis_options.yaml) | – |
+{{/if}}
+{{#if includeWeb}}
+| Linting (Web) | ESLint (strict TS + Astro plugin) | – |
+| Formatting | dart format + Prettier (Astro plugin) | – |
+{{/if}}
+{{#if includeMobile}}
+| Testing (Mobile) | flutter_test + integration_test | – |
+{{/if}}
+{{#if includeWeb}}
+| Testing (Web) | Vitest (unit) + Playwright (e2e) | – |
+{{/if}}
+| Pre-commit | Lefthook → Makefile targets | – |
+
+## Commands Reference
+
+All commands are defined in the Makefile. Run `make` or `make help` for the full list.
+
+## Code Style & Conventions
+
+{{#if includeMobile}}
+### Dart / Flutter (`apps/mobile/`)
+- **Strict analysis**: `analysis_options.yaml` with 90+ lint rules + DCM rules
+- Prefer `const` constructors, `final` variables, single quotes
+- Always use `require_trailing_commas`
+- No `print()` – use proper logging
+- Max cyclomatic complexity: 20, max function lines: 50
+- One widget per file (private widgets excepted)
+
+{{/if}}
+{{#if includeWeb}}
+### TypeScript / Astro (`apps/web/`)
+- **Strict TypeScript**: enabled in `tsconfig.json`
+- **ESLint**: strict TS rules (no `any`, no `eval`, no `console.log`)
+- **Prettier**: single quotes, trailing commas, 100 char width
+- Use `const` over `let`, never `var`
+- Colocate tests: `*.test.ts` next to source files
+
+{{/if}}
+## CI Architecture
+
+```
+Makefile (single source of truth)
+├── lefthook.yml → calls make targets on pre-commit
+└── make ci → runs full pipeline locally
+```
+
+No GitHub Actions configured yet – all checks run locally.
+
+## Branching & Commits
+- Branch from `main`
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, `security:`
+- Pre-commit hooks run automatically via lefthook
+
+## Security
+- Never commit secrets, API keys, or tokens
+- All dependencies are audited via `make security`
+{{#if includeMobile}}
+- DCM activated with license (stored in `~/.dcm/`, never in repo)
+{{/if}}
+- See `SECURITY.md` for disclosure policy
+
+## Design
+- UI design assisted via **Google Stitch** (MCP available)
+- Always refer to the latest Stitch project for design reference