create-z3 0.0.1

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import { select, input } from "@inquirer/prompts";
+import chalk from "chalk";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var packageJson = JSON.parse(
+  readFileSync(join(__dirname, "../package.json"), "utf-8")
+);
+var program = new Command();
+program.name("create-z3").version(packageJson.version).description("CLI for scaffolding Z3 Stack applications").argument("[project-name]", "Name of the project").action(async (projectNameArg) => {
+  try {
+    let projectName = projectNameArg;
+    if (!projectName) {
+      projectName = await input({
+        message: "What is your project named?"
+      });
+    }
+    const framework = await select({
+      message: "Which framework would you like to use?",
+      choices: [
+        { name: "TanStack Start", value: "tanstack" },
+        { name: "Next.js", value: "nextjs" }
+      ],
+      default: "tanstack"
+    });
+    const frameworkName = framework === "tanstack" ? "TanStack Start" : "Next.js";
+    console.log();
+    console.log(chalk.green("\u2705 Configuration complete!"));
+    console.log();
+    console.log(`Project name: ${projectName}`);
+    console.log(`Framework: ${frameworkName}`);
+    console.log();
+    console.log("(No scaffolding yet - this is a test version)");
+    console.log();
+    process.exit(0);
+  } catch (error) {
+    if (error instanceof Error && error.name === "ExitPromptError") {
+      console.log();
+      process.exit(0);
+    }
+    throw error;
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "create-z3",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "CLI for scaffolding Z3 Stack applications (TanStack/Next.js + Convex + Better Auth)",
+  "bin": {
+    "create-z3": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"No tests yet\""
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@inquirer/prompts": "^7.2.0",
+    "fs-extra": "^11.2.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.1.0",
+    "execa": "^9.5.2",
+    "sort-package-json": "^2.10.0",
+    "validate-npm-package-name": "^5.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsup": "^8.0.0",
+    "@types/node": "^22.0.0",
+    "@types/fs-extra": "^11.0.0",
+    "@types/validate-npm-package-name": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cli",
+    "create-z3",
+    "z3-stack",
+    "tanstack",
+    "nextjs",
+    "convex",
+    "better-auth",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zayecq/create-z3-app"
+  },
+  "license": "MIT"
+}

package/templates/tanstack-start/.env.example

@@ -0,0 +1,45 @@
+# -----------------------------------------------------------------------------
+# Environment Variables Template
+# -----------------------------------------------------------------------------
+# Copy this file to .env and fill in the values
+# DO NOT commit .env to version control - it contains secrets!
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# App Environment
+# -----------------------------------------------------------------------------
+NODE_ENV=development
+
+# -----------------------------------------------------------------------------
+# Convex (Database & Realtime Backend)
+# -----------------------------------------------------------------------------
+# Get these from: https://dashboard.convex.dev
+# CONVEX_URL is for server-side operations
+# VITE_CONVEX_URL is for client-side SDK (must start with VITE_)
+CONVEX_URL=https://your-deployment.convex.cloud
+VITE_CONVEX_URL=https://your-deployment.convex.cloud
+CONVEX_SITE_URL=https://your-deployment.convex.site
+VITE_CONVEX_SITE_URL=https://your-deployment.convex.site
+
+# -----------------------------------------------------------------------------
+# Better Auth (Authentication - Phase 0+)
+# -----------------------------------------------------------------------------
+# Generate a random 32+ character secret: openssl rand -base64 32
+BETTER_AUTH_SECRET=your-super-secret-32-character-minimum-string-here
+SITE_URL=http://localhost:3000
+VITE_SITE_URL=http://localhost:3000
+
+# -----------------------------------------------------------------------------
+# AWS (Lambda Workers & Storage - Phase 5+)
+# -----------------------------------------------------------------------------
+# Required for: AI generation workers, job queue, file storage
+# Get credentials from: AWS IAM Console
+AWS_REGION=us-west-1
+AWS_ACCESS_KEY_ID=your-aws-access-key-id
+AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key
+
+# -----------------------------------------------------------------------------
+# Development Tools
+# -----------------------------------------------------------------------------
+# Set to "1" to skip env validation during build (useful for CI/CD)
+# SKIP_ENV_VALIDATION=1

package/templates/tanstack-start/.prettierignore

@@ -0,0 +1,18 @@
+# Build outputs
+dist
+.output
+.nitro
+.tanstack
+
+# Auto-generated files
+**/routeTree.gen.ts
+**/*.gen.ts
+
+# Dependencies
+node_modules
+
+# Cache
+.eslintcache
+
+# Lock files
+pnpm-lock.yaml

package/templates/tanstack-start/README.md

@@ -0,0 +1,221 @@
+# TanStack Start + Better Auth + Convex + shadcn/ui Template
+
+A modern, production-ready SaaS template built with:
+
+- **[TanStack Start](https://tanstack.com/start)** - Full-stack React framework with type-safe routing
+- **[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
+- **[Base UI](https://base-ui.com/)** - Unstyled, accessible component primitives
+- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework
+
+## Getting Started
+
+### 1. Prerequisites
+
+- Node.js 18+ and pnpm installed
+- A Convex account (free at [convex.dev](https://convex.dev))
+
+### 2. Clone and Install
+
+```bash
+# Clone this template
+git clone <your-repo-url>
+cd <your-project-name>
+
+# Install dependencies
+pnpm 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
+pnpm 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 `VITE_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
+VITE_CONVEX_URL=https://your-deployment.convex.cloud
+CONVEX_SITE_URL=https://your-deployment.convex.site
+VITE_CONVEX_SITE_URL=https://your-deployment.convex.site
+
+# Better Auth (same secret you added to Convex Dashboard)
+BETTER_AUTH_SECRET=your-generated-secret-here
+SITE_URL=http://localhost:3000
+VITE_SITE_URL=http://localhost:3000
+```
+
+### 7. Start Development
+
+```bash
+# Terminal 1: Run Convex dev server
+npx convex dev
+
+# Terminal 2: Run the application
+pnpm dev
+```
+
+Visit `http://localhost:3000` to see your application running.
+
+## Customizing Authentication
+
+### Adding OAuth Providers
+
+The template includes Google OAuth as an example. To add or modify 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
+
+```
+.
+├── app/                    # TanStack Start application code
+│   ├── routes/            # File-based routing
+│   ├── components/        # React components
+│   └── lib/               # Utilities and helpers
+├── 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
+pnpm dev              # Start development server
+pnpm build            # Build for production
+pnpm preview          # Preview production build
+pnpm test             # Run tests
+pnpm typecheck        # Type check without emitting
+pnpm lint             # Lint code
+pnpm lint:fix         # Fix linting issues
+pnpm format           # Format code with Prettier
+pnpm format:check     # Check code formatting
+pnpm validate         # Run typecheck, lint, and format check
+pnpm secret:create    # Generate a Better Auth secret
+```
+
+## Documentation Resources
+
+### Core Technologies
+- **TanStack Start**: [tanstack.com/start](https://tanstack.com/start)
+- **TanStack Router**: [tanstack.com/router](https://tanstack.com/router)
+- **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)
+- **Base UI**: [base-ui.com](https://base-ui.com)
+
+### Integration Guides
+- **Better Auth + Convex**: [better-auth.com/docs/integrations/convex](https://www.better-auth.com/docs/integrations/convex)
+- **Better Auth + TanStack Start**: [better-auth.com/docs/integrations/tanstack-start](https://www.better-auth.com/docs/integrations/tanstack-start)
+
+## 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, Netlify, etc.)
+
+4. **Update environment variables** in your hosting provider with production values
+
+See [Convex Production Deployment](https://docs.convex.dev/production/hosting) for detailed deployment instructions.
+
+## License
+
+MIT

package/templates/tanstack-start/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-vega",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.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": {}
+}

package/templates/tanstack-start/convex/_generated/api.d.ts

@@ -0,0 +1,65 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as auth_adapter_index from "../auth/adapter/index.js";
+import type * as auth_adapter_utils from "../auth/adapter/utils.js";
+import type * as auth_api from "../auth/api.js";
+import type * as auth_config from "../auth/config.js";
+import type * as auth_db from "../auth/db.js";
+import type * as auth_index from "../auth/index.js";
+import type * as auth_plugins_index from "../auth/plugins/index.js";
+import type * as auth_sessions from "../auth/sessions.js";
+import type * as http from "../http.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{
+  "auth/adapter/index": typeof auth_adapter_index;
+  "auth/adapter/utils": typeof auth_adapter_utils;
+  "auth/api": typeof auth_api;
+  "auth/config": typeof auth_config;
+  "auth/db": typeof auth_db;
+  "auth/index": typeof auth_index;
+  "auth/plugins/index": typeof auth_plugins_index;
+  "auth/sessions": typeof auth_sessions;
+  http: typeof http;
+}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

package/templates/tanstack-start/convex/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();

package/templates/tanstack-start/convex/_generated/dataModel.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;