create-z3 0.0.11 → 0.0.13

package/dist/index.js

@@ -72,7 +72,10 @@ async function copyTemplate(framework, targetPath) {
   const __filename2 = fileURLToPath(import.meta.url);
   const __dirname2 = dirname(__filename2);
   const templateDir = framework === "tanstack" ? "tanstack-start" : "nextjs";
-  const templatePath = join(__dirname2, "../templates", templateDir);
+  let templatePath = join(__dirname2, "../../templates", templateDir);
+  if (!fs2.existsSync(templatePath)) {
+    templatePath = join(__dirname2, "../templates", templateDir);
+  }
   await fs2.copy(templatePath, targetPath, {
     overwrite: false,
     errorOnExist: false
@@ -1725,25 +1728,25 @@ function getAdditionalProviders() {
 
 // src/installers/string-utils.ts
 import fs3 from "fs-extra";
-var DEFAULT_THEME = `--background: 0 0% 100%;
---foreground: 240 10% 3.9%;
---card: 0 0% 100%;
---card-foreground: 240 10% 3.9%;
---popover: 0 0% 100%;
---popover-foreground: 240 10% 3.9%;
---primary: 240 5.9% 10%;
---primary-foreground: 0 0% 98%;
---secondary: 240 4.8% 95.9%;
---secondary-foreground: 240 5.9% 10%;
---muted: 240 4.8% 95.9%;
---muted-foreground: 240 3.8% 46.1%;
---accent: 240 4.8% 95.9%;
---accent-foreground: 240 5.9% 10%;
---destructive: 0 84.2% 60.2%;
---destructive-foreground: 0 0% 98%;
---border: 240 5.9% 90%;
---input: 240 5.9% 90%;
---ring: 240 5.9% 10%;
+var DEFAULT_THEME = `--background: 100% 0.000 0;
+--foreground: 3.9% 0.006 240;
+--card: 100% 0.000 0;
+--card-foreground: 3.9% 0.006 240;
+--popover: 100% 0.000 0;
+--popover-foreground: 3.9% 0.006 240;
+--primary: 10% 0.003 240;
+--primary-foreground: 98% 0.000 0;
+--secondary: 95.9% 0.002 240;
+--secondary-foreground: 10% 0.003 240;
+--muted: 95.9% 0.002 240;
+--muted-foreground: 46.1% 0.002 240;
+--accent: 95.9% 0.002 240;
+--accent-foreground: 10% 0.003 240;
+--destructive: 60.2% 0.168 0;
+--destructive-foreground: 98% 0.000 0;
+--border: 90% 0.003 240;
+--input: 90% 0.003 240;
+--ring: 10% 0.003 240;
 --radius: 0.5rem;`;
 function detectIndentation(line) {
   const match = line.match(/^(\s*)/);
@@ -1927,6 +1930,129 @@ import { join as join2 } from "path";
 import { execa } from "execa";
 import ora from "ora";
 import crypto from "crypto";
+
+// src/utils/tweakcn-converter.ts
+import fs4 from "fs-extra";
+import convert from "color-convert";
+async function convertTweakCNToOKLCH(options) {
+  const { source, format = "oklch" } = options;
+  const cssContent = await fetchOrReadCSS(source);
+  const colors = parseColorsFromCSS(cssContent);
+  const convertedColors = colors.map((color) => ({
+    ...color,
+    oklch: convertColorToOKLCH(color.value)
+  }));
+  return generateCSSOutput(convertedColors, format);
+}
+async function fetchOrReadCSS(source) {
+  if (source.startsWith("http://") || source.startsWith("https://")) {
+    try {
+      const response = await fetch(source);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      return await response.text();
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch CSS from URL: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  try {
+    return await fs4.readFile(source, "utf-8");
+  } catch (error) {
+    throw new Error(
+      `Failed to read CSS from file: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+  }
+}
+function parseColorsFromCSS(css) {
+  const colors = [];
+  const cssVarRegex = /--([\w-]+)\s*:\s*([^;]+);/g;
+  let match;
+  while ((match = cssVarRegex.exec(css)) !== null) {
+    const name = `--${match[1]}`;
+    const value = match[2].trim();
+    if (isColorValue(value)) {
+      colors.push({ name, value });
+    }
+  }
+  return colors;
+}
+function isColorValue(value) {
+  if (value.startsWith("#")) {
+    return true;
+  }
+  if (value.startsWith("rgb(") || value.startsWith("rgba(")) {
+    return true;
+  }
+  if (value.startsWith("hsl(") || value.startsWith("hsla(")) {
+    return true;
+  }
+  if (value.startsWith("oklch(")) {
+    return true;
+  }
+  if (/^\d+(\.\d+)?\s+\d+(\.\d+)?%\s+\d+(\.\d+)?%$/.test(value)) {
+    return true;
+  }
+  return false;
+}
+function convertColorToOKLCH(colorValue) {
+  const trimmed = colorValue.trim();
+  if (trimmed.startsWith("oklch(")) {
+    const match = trimmed.match(/oklch\(([\d.]+%?)\s+([\d.]+)\s+([\d.]+)\)/);
+    if (match) {
+      return `${match[1]} ${match[2]} ${match[3]}`;
+    }
+  }
+  let rgb;
+  try {
+    if (trimmed.startsWith("#")) {
+      rgb = convert.hex.rgb(trimmed.slice(1));
+    } else if (trimmed.startsWith("rgb(") || trimmed.startsWith("rgba(")) {
+      const match = trimmed.match(/rgba?\((\d+),?\s*(\d+),?\s*(\d+)/);
+      if (!match) throw new Error("Invalid RGB format");
+      rgb = [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])];
+    } else if (trimmed.startsWith("hsl(") || trimmed.startsWith("hsla(")) {
+      const match = trimmed.match(/hsla?\((\d+),?\s*(\d+)%?,?\s*(\d+)%?/);
+      if (!match) throw new Error("Invalid HSL format");
+      const hsl2 = [
+        parseInt(match[1]),
+        parseInt(match[2]),
+        parseInt(match[3])
+      ];
+      rgb = convert.hsl.rgb(hsl2);
+    } else if (/^\d+(\.\d+)?\s+\d+(\.\d+)?%\s+\d+(\.\d+)?%$/.test(trimmed)) {
+      const parts = trimmed.split(/\s+/);
+      const h2 = parseFloat(parts[0]);
+      const s = parseFloat(parts[1].replace("%", ""));
+      const l2 = parseFloat(parts[2].replace("%", ""));
+      rgb = convert.hsl.rgb([h2, s, l2]);
+    } else {
+      return trimmed;
+    }
+    const hsl = convert.rgb.hsl(rgb);
+    const l = hsl[2];
+    const c = hsl[1] / 100 * 0.4;
+    const h = hsl[0];
+    return `${l}% ${c.toFixed(3)} ${h}`;
+  } catch (error) {
+    console.warn(`Failed to convert color "${colorValue}": ${error instanceof Error ? error.message : "Unknown error"}`);
+    return trimmed;
+  }
+}
+function generateCSSOutput(colors, format) {
+  if (colors.length === 0) {
+    return "";
+  }
+  const declarations = colors.map((color) => {
+    const value = format === "oklch" && color.oklch ? color.oklch : color.value;
+    return `${color.name}: ${value};`;
+  }).join("\n");
+  return declarations;
+}
+
+// src/installers/base.ts
 var FrameworkInstaller = class {
   /**
    * Constructor for FrameworkInstaller
@@ -1947,24 +2073,22 @@ var FrameworkInstaller = class {
   }
   /**
    * Detect the package manager used to invoke the CLI
-   * Checks npm_config_user_agent environment variable
+   * Checks environment variables set by package managers
    *
-   * @returns Detected package manager, defaults to 'npm'
+   * @returns Detected package manager ('npm', 'yarn', 'pnpm', or 'bun')
    */
   detectPackageManager() {
-    const userAgent = process.env.npm_config_user_agent || "";
-    if (userAgent.includes("pnpm")) {
-      return "pnpm";
-    } else if (userAgent.includes("yarn")) {
-      return "yarn";
-    } else if (userAgent.includes("bun")) {
-      return "bun";
+    const userAgent = process.env.npm_config_user_agent;
+    if (userAgent) {
+      if (userAgent.includes("pnpm")) return "pnpm";
+      if (userAgent.includes("yarn")) return "yarn";
+      if (userAgent.includes("bun")) return "bun";
     }
     return "npm";
   }
   /**
    * Install project dependencies using detected package manager
-   * Shows progress with ora spinner
+   * Shows progress spinner during installation
    */
   async installDependencies() {
     const packageManager = this.detectPackageManager();
@@ -1974,21 +2098,21 @@ var FrameworkInstaller = class {
         cwd: this.targetPath,
         stdio: "pipe"
       });
-      spinner.succeed(`Dependencies installed with ${packageManager}`);
+      spinner.succeed("Dependencies installed successfully");
     } catch (error) {
-      spinner.fail(`Failed to install dependencies with ${packageManager}`);
+      spinner.fail("Failed to install dependencies");
       throw new Error(
         `Dependency installation failed: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
   /**
-   * Format generated files using the project's format command
-   * Runs after all file modifications to ensure consistent code style
+   * Format code using project's formatter (Prettier via package.json script)
+   * Non-blocking - continues even if formatting fails
    */
   async formatCode() {
     const packageManager = this.detectPackageManager();
-    const spinner = ora("Formatting generated files...").start();
+    const spinner = ora("Formatting code...").start();
     try {
       await execa(packageManager, ["run", "format"], {
         cwd: this.targetPath,
@@ -2072,13 +2196,15 @@ Make sure you are authenticated with GitHub CLI (run "gh auth login")`
     return crypto.randomBytes(32).toString("hex");
   }
   /**
-   * Fetch TweakCN theme CSS from URL
+   * Fetch TweakCN theme CSS from URL and convert to OKLCH format
    * Handles network errors and provides retry suggestions
+   * Optionally converts fetched theme through OKLCH converter for consistent color format
    *
    * @param url - URL to fetch theme from
-   * @returns Theme CSS content
+   * @param convertToOklch - Whether to convert theme colors to OKLCH format (default: true)
+   * @returns Theme CSS content in OKLCH format (if conversion enabled)
    */
-  async fetchThemeFromUrl(url) {
+  async fetchThemeFromUrl(url, convertToOklch = true) {
     const spinner = ora("Fetching TweakCN theme...").start();
     try {
       const response = await fetch(url);
@@ -2087,6 +2213,23 @@ Make sure you are authenticated with GitHub CLI (run "gh auth login")`
       }
       const content = await response.text();
       spinner.succeed("TweakCN theme fetched");
+      if (convertToOklch) {
+        const convertSpinner = ora("Converting theme to OKLCH format...").start();
+        try {
+          const convertedContent = await convertTweakCNToOKLCH({
+            source: url,
+            format: "oklch"
+          });
+          convertSpinner.succeed("Theme converted to OKLCH format");
+          return convertedContent;
+        } catch (convertError) {
+          convertSpinner.warn("OKLCH conversion failed, using raw theme CSS");
+          console.warn(
+            `Warning: Failed to convert theme to OKLCH: ${convertError instanceof Error ? convertError.message : "Unknown error"}`
+          );
+          return content;
+        }
+      }
       return content;
     } catch (error) {
       spinner.fail("Failed to fetch TweakCN theme");
@@ -2111,15 +2254,17 @@ Please check the URL and your internet connection, then try again.`
       copySpinner.fail("Failed to copy template files");
       throw error;
     }
-    if (options.emailPasswordAuth || options.oauthProviders.length > 0) {
-      const authSpinner = ora("Configuring authentication...").start();
-      try {
-        await this.updateOAuthConfig(options.oauthProviders, options.emailPasswordAuth);
+    const authSpinner = ora("Configuring authentication...").start();
+    try {
+      await this.updateOAuthConfig(options.oauthProviders, options.emailPasswordAuth);
+      if (options.emailPasswordAuth || options.oauthProviders.length > 0) {
         authSpinner.succeed("Authentication configuration updated");
-      } catch (error) {
-        authSpinner.fail("Failed to configure authentication");
-        throw error;
+      } else {
+        authSpinner.succeed("Authentication placeholders cleaned up");
       }
+    } catch (error) {
+      authSpinner.fail("Failed to configure authentication");
+      throw error;
     }
     const oauthUISpinner = ora("Configuring OAuth UI...").start();
     try {
@@ -2175,16 +2320,17 @@ Please check the URL and your internet connection, then try again.`
       if (options.tweakcnTheme) {
         if (options.tweakcnTheme.type === "url") {
           themeContent = await this.fetchThemeFromUrl(options.tweakcnTheme.content);
+        } else if (options.tweakcnTheme.type === "css") {
+          themeContent = options.tweakcnTheme.content;
         } else {
           themeContent = options.tweakcnTheme.content;
         }
+        await this.applyTweakCNTheme(themeContent);
+        themeSpinner.succeed("TweakCN theme applied");
       } else {
-        themeContent = DEFAULT_THEME;
+        await this.applyTweakCNTheme(DEFAULT_THEME);
+        themeSpinner.succeed("Default theme applied");
       }
-      await this.applyTweakCNTheme(themeContent);
-      themeSpinner.succeed(
-        options.tweakcnTheme ? "TweakCN theme applied" : "Default theme applied"
-      );
     } catch (error) {
       themeSpinner.fail("Failed to apply theme");
       throw error;
@@ -2194,7 +2340,6 @@ Please check the URL and your internet connection, then try again.`
     }
     if (options.installDependencies) {
       await this.installDependencies();
-      await this.formatCode();
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-z3",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "description": "CLI for scaffolding Z3 Stack applications (TanStack/Next.js + Convex + Better Auth)",
   "bin": {
@@ -25,7 +25,8 @@
     "ora": "^8.1.0",
     "execa": "^9.5.2",
     "sort-package-json": "^2.10.0",
-    "validate-npm-package-name": "^5.0.0"
+    "validate-npm-package-name": "^5.0.0",
+    "color-convert": "^2.0.1"
   },
   "devDependencies": {
     "typescript": "^5.7.0",
@@ -33,6 +34,7 @@
     "@types/node": "^22.0.0",
     "@types/fs-extra": "^11.0.0",
     "@types/validate-npm-package-name": "^4.0.0",
+    "@types/color-convert": "^2.0.3",
     "vitest": "^2.0.0"
   },
   "engines": {

package/templates/nextjs/README.md

@@ -1,26 +1,250 @@
-# Next.js Template - Placeholder
+# Next.js + Better Auth + Convex + shadcn/ui Template
 
-This is a placeholder template for Next.js projects in the Z3 Stack CLI.
+A modern, production-ready SaaS template built with:
 
-## Status
+- **[Next.js](https://nextjs.org)** - The React framework for production with App Router
+- **[Better Auth](https://www.better-auth.com/)** - Modern authentication with email/password and OAuth providers
+- **[Convex](https://convex.dev/)** - Real-time database and backend
+- **[shadcn/ui](https://ui.shadcn.com/)** - Beautifully designed components built on Radix UI
+- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework
 
-This template is currently a minimal placeholder structure. The full Next.js template with Convex, Better Auth, and shadcn/ui integration will be implemented in a future specification.
+## Getting Started
 
-## Current Structure
+### 1. Prerequisites
 
-- `package.json` - Minimal Next.js dependencies with project name placeholder
-- `.gitignore` - Standard Next.js ignore patterns
-- `src/` - Empty source directory (placeholder)
+- Node.js 18+ and npm/pnpm/yarn installed
+- A Convex account (free at [convex.dev](https://convex.dev))
 
-## Future Implementation
+### 2. Clone and Install
 
-The complete Next.js template will include:
-- Full Convex integration and schema
-- Better Auth setup with OAuth providers
-- shadcn/ui components
-- TypeScript configuration
-- Tailwind CSS setup
-- App Router structure
-- Environment configuration
+```bash
+# Clone this template
+git clone <your-repo-url>
+cd <your-project-name>
 
-For now, this structure serves as a placeholder to support Next.js selection in the CLI framework prompts.
+# Install dependencies
+npm install
+# or
+pnpm install
+# or
+yarn install
+```
+
+### 3. Environment Setup
+
+Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+### 4. Generate Better Auth Secret
+
+Generate a secure secret for Better Auth:
+
+```bash
+npm run secret:create
+# or
+pnpm secret:create
+# or
+yarn secret:create
+```
+
+This will generate a random 32-character hex string and copy it to your clipboard.
+
+### 5. Configure Convex
+
+#### Set up Convex project
+
+```bash
+npx convex dev
+```
+
+This will:
+- Create a new Convex project (or link to an existing one)
+- Generate your `CONVEX_URL` and `NEXT_PUBLIC_CONVEX_URL`
+- Start the Convex development server
+
+#### Add environment variables to Convex
+
+You need to add two critical environment variables to your Convex deployment via the [Convex Dashboard](https://dashboard.convex.dev):
+
+1. **BETTER_AUTH_SECRET**: Paste the secret you generated in step 4
+2. **SITE_URL**: Set to your application URL
+   - Development: `http://localhost:3000` (or whatever port your dev server uses)
+   - Production: Your production domain (e.g., `https://yourdomain.com`)
+
+To add these in the Convex Dashboard:
+1. Go to your project at [dashboard.convex.dev](https://dashboard.convex.dev)
+2. Navigate to "Settings" → "Environment Variables"
+3. Add both `BETTER_AUTH_SECRET` and `SITE_URL`
+
+### 6. Update Your .env File
+
+Update your `.env` file with the values from Convex setup:
+
+```env
+NODE_ENV=development
+
+# From Convex setup
+CONVEX_URL=https://your-deployment.convex.cloud
+NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
+CONVEX_SITE_URL=https://your-deployment.convex.site
+NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
+
+# Better Auth (same secret you added to Convex Dashboard)
+BETTER_AUTH_SECRET=your-generated-secret-here
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
+```
+
+### 7. Start Development
+
+```bash
+# Terminal 1: Run Convex dev server
+npx convex dev
+
+# Terminal 2: Run the application
+npm run dev
+# or
+pnpm dev
+# or
+yarn dev
+```
+
+Visit `http://localhost:3000` to see your application running.
+
+## Authentication Setup
+
+This project uses Better Auth for authentication.
+
+<!-- {{OAUTH_SETUP_GUIDE}} -->
+
+## Customizing Authentication
+
+### Adding OAuth Providers
+
+To add or modify OAuth providers:
+
+1. **Update Better Auth configuration** in `convex/auth/index.ts`:
+
+```typescript
+export const createAuth = (ctx: GenericActionCtx<DataModel>) => {
+  return betterAuth({
+    socialProviders: {
+      google: {
+        clientId: process.env.GOOGLE_CLIENT_ID!,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+        redirectURI: `${process.env.SITE_URL}/api/auth/callback/google`
+      },
+      // Add more providers
+      github: {
+        clientId: process.env.GITHUB_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      }
+    },
+    // ... rest of config
+  })
+}
+```
+
+2. **Add credentials to Convex Dashboard** as environment variables
+
+3. **Consult the Better Auth documentation** for provider-specific configuration:
+   - [Better Auth Providers](https://www.better-auth.com/docs/authentication/social-login)
+
+### Customizing User Schema
+
+To add custom fields to your user model:
+
+1. Update the `user.additionalFields` in `convex/auth/index.ts`
+2. Update your Convex schema accordingly
+3. See [Better Auth User Management](https://www.better-auth.com/docs/concepts/user-management) for details
+
+### Email/Password Configuration
+
+The template has email/password authentication enabled by default. To customize:
+
+- [Better Auth Email/Password Docs](https://www.better-auth.com/docs/authentication/email-password)
+- [Email Verification Setup](https://www.better-auth.com/docs/authentication/email-verification)
+
+## Project Structure
+
+```
+.
+├── src/
+│   ├── app/                    # Next.js App Router
+│   │   ├── (frontend)/        # Frontend routes group
+│   │   ├── api/               # API routes
+│   │   └── layout.tsx         # Root layout
+│   ├── auth/                  # Authentication components
+│   ├── components/            # React components
+│   ├── lib/                   # Utilities and helpers
+│   └── env.mjs                # Typed environment variables
+├── convex/                    # Convex backend
+│   ├── auth/                  # Better Auth integration
+│   ├── schema.ts              # Database schema
+│   └── *.ts                   # Convex functions (queries, mutations, actions)
+├── public/                    # Static assets
+└── .env                       # Environment variables (not committed)
+```
+
+## Development Scripts
+
+```bash
+npm run dev              # Start development server
+npm run build            # Build for production
+npm run start            # Start production server
+npm run lint             # Lint code
+npm run typecheck        # Type check without emitting
+npm run format           # Format code with Prettier
+npm run format:check     # Check code formatting
+npm run secret:create    # Generate a Better Auth secret
+```
+
+## Documentation Resources
+
+### Core Technologies
+- **Next.js**: [nextjs.org/docs](https://nextjs.org/docs)
+- **Better Auth**: [better-auth.com/docs](https://www.better-auth.com/docs)
+- **Convex**: [docs.convex.dev](https://docs.convex.dev)
+- **shadcn/ui**: [ui.shadcn.com](https://ui.shadcn.com)
+- **Tailwind CSS**: [tailwindcss.com/docs](https://tailwindcss.com/docs)
+
+### Integration Guides
+- **Better Auth + Convex**: [better-auth.com/docs/integrations/convex](https://www.better-auth.com/docs/integrations/convex)
+- **Better Auth + Next.js**: [better-auth.com/docs/integrations/nextjs](https://www.better-auth.com/docs/integrations/nextjs)
+
+## Deployment
+
+### Deploy to Production
+
+1. **Deploy Convex Backend**:
+```bash
+npx convex deploy
+```
+
+2. **Update Convex environment variables** in production:
+   - Set `SITE_URL` to your production domain
+   - Keep `BETTER_AUTH_SECRET` the same (or rotate it)
+
+3. **Deploy your application** to your hosting provider (Vercel recommended):
+
+For Vercel:
+```bash
+npm install -g vercel
+vercel
+```
+
+Or connect your GitHub repository to Vercel for automatic deployments.
+
+4. **Update environment variables** in your hosting provider with production values:
+   - `NEXT_PUBLIC_CONVEX_URL`
+   - `NEXT_PUBLIC_CONVEX_SITE_URL`
+   - `NEXT_PUBLIC_SITE_URL`
+   - `BETTER_AUTH_SECRET`
+
+See [Next.js Deployment](https://nextjs.org/docs/app/building-your-application/deploying) and [Convex Production Deployment](https://docs.convex.dev/production/hosting) for detailed deployment instructions.
+
+## License
+
+MIT

package/templates/nextjs/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-vega",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "~/components",
+    "utils": "~/lib/utils",
+    "ui": "~/components/ui",
+    "lib": "~/lib",
+    "hooks": "~/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}