create-velox-app 0.6.31 → 0.6.52

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # create-velox-app
 
+## 0.6.52
+
+### Patch Changes
+
+- feat(mcp): smart CLI resolution with fallbacks
+
+## 0.6.51
+
+### Patch Changes
+
+- fix(web): configure @vinxi/server-functions for RSC server actions
+
+## 0.6.50
+
+### Patch Changes
+
+- lint fixed
+
+## 0.6.49
+
+### Patch Changes
+
+- feat(create): add client import lint script for RSC templates
+
+## 0.6.48
+
+### Patch Changes
+
+- fix(web): remove server-only guards incompatible with Vite SS
+
+## 0.6.47
+
+### Patch Changes
+
+- fix(web): use /adapters for createH3ApiHandler to avoid server-only
+
+## 0.6.46
+
+### Patch Changes
+
+- fix(web): remove transitive server-only import from main entry
+
+## 0.6.45
+
+### Patch Changes
+
+- fix(web): remove server-only guard from main entry for Vinxi compat
+
+## 0.6.44
+
+### Patch Changes
+
+- refactor(web): implement proper RSC server/client separation
+
+## 0.6.43
+
+### Patch Changes
+
+- fix(web): exclude native modules from Vite dependency optimization
+
+## 0.6.42
+
+### Patch Changes
+
+- fix(web): enable tsconfig path aliases for Vite/Vinxi + docs(web): add @public/@internal JSDoc annotations to server actions
+
+## 0.6.41
+
+### Patch Changes
+
+- feat(web): add authAction helper for procedure bridge authentication
+
+## 0.6.40
+
+### Patch Changes
+
+- feat(create): consolidate template styles with unified dark mode design
+
+## 0.6.39
+
+### Patch Changes
+
+- fix RSC client hydration with split layout architecture
+
+## 0.6.38
+
+### Patch Changes
+
+- fix client hydration for RSC templates
+
+## 0.6.37
+
+### Patch Changes
+
+- feat(web): add validated() helper for secure server actions & add rsc-auth template with validated()
+
+## 0.6.36
+
+### Patch Changes
+
+- Gap Remediation Plan
+
+## 0.6.35
+
+### Patch Changes
+
+- proper auth template testing in verify-publis
+
+## 0.6.34
+
+### Patch Changes
+
+- update PostgreSQL adapter for Prisma 7 API
+
+## 0.6.33
+
+### Patch Changes
+
+- changed claude.md instruction, added prisma config
+
+## 0.6.32
+
+### Patch Changes
+
+- Introducing new Ecosystem Expansion packages: cache, queue, mail, storage, scheduler, events. Do not use yet
+
 ## 0.6.31
 
 ### Patch Changes

package/GUIDE.md

@@ -53,6 +53,236 @@ curl -X POST http://localhost:3030/api/users \
   -d '{"name": "Alice", "email": "alice@example.com"}'
 ```
 
+## Post-Publish Verification
+
+The `verify-publish.sh` script tests actual published npm packages to ensure they work correctly after publishing. Unlike the smoke test (which uses local `file:` references), this script downloads packages from npm and validates the complete user experience.
+
+### When to Use
+
+- **After publishing** to npm to verify packages work correctly
+- **Before major releases** to test all template/database combinations
+- **With Verdaccio** to test packages locally before publishing to npm
+- **In CI/CD** as a post-publish validation step
+
+### Prerequisites
+
+- Node.js 20+
+- npm
+- curl
+- Docker (optional, for PostgreSQL runtime tests)
+
+### Basic Usage
+
+```bash
+cd packages/create
+
+# Test latest published version (spa + sqlite)
+pnpm verify-publish
+
+# Test specific version
+pnpm verify-publish 0.6.34
+
+# Test from local Verdaccio registry
+pnpm verify-publish --registry http://localhost:4873
+
+# Test specific template
+pnpm verify-publish --template auth
+
+# Test specific database (Docker auto-enabled for postgresql)
+pnpm verify-publish --database postgresql
+
+# Test specific combination
+pnpm verify-publish --template auth --database sqlite
+
+# Test all combinations (full matrix)
+pnpm verify-publish --all
+
+# Keep test projects for inspection
+pnpm verify-publish --keep
+```
+
+### Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `VERSION` | Package version to test | `latest` |
+| `--registry URL` | npm registry URL | `https://registry.npmjs.org` |
+| `--template NAME` | Template to test (`spa`, `auth`, `trpc`, `rsc`) | `spa` |
+| `--database NAME` | Database to test (`sqlite`, `postgresql`) | `sqlite` |
+| `--all` | Test all template/database combinations | `false` |
+| `--docker` | Force Docker (auto-enabled for postgresql) | `false` |
+| `--keep` | Keep test projects after completion | `false` |
+| `--help` | Show help message | - |
+
+### What Gets Tested
+
+For each template/database combination, the script validates:
+
+1. **Project Creation** - `npx create-velox-app` succeeds
+2. **Project Structure** - Required files exist (package.json, prisma.config.ts, schema.prisma, docker-compose.yml for PostgreSQL)
+3. **Dependency Installation** - `npm install` succeeds
+4. **Prisma Generation** - `npm run db:generate` succeeds
+5. **Build** - `npm run build` (or `npm run -w api build` for monorepo) succeeds
+6. **Database Setup** - `npm run db:push` succeeds (SQLite direct, PostgreSQL via Docker)
+7. **Runtime Endpoints** (all databases - Docker auto-enabled for PostgreSQL):
+   - `GET /api/health` → 200
+   - `GET /api/users` → 200
+   - `POST /api/users` → 201
+   - `GET /api/users/:id` → 200
+   - `DELETE /api/users/:id` → 200
+   - Auth template also tests `/auth/register` and `/auth/login`
+
+### Examples
+
+#### Quick Sanity Check
+```bash
+# Test default template with SQLite (fastest)
+pnpm verify-publish
+```
+
+#### Test Specific Version from npm
+```bash
+pnpm verify-publish 0.6.31
+```
+
+#### Test with Local Verdaccio Before Publishing
+```bash
+# 1. Start Verdaccio
+npx verdaccio
+
+# 2. Publish packages to Verdaccio
+pnpm publish --registry http://localhost:4873 --no-git-checks
+
+# 3. Verify the published packages
+pnpm verify-publish --registry http://localhost:4873
+```
+
+#### Full Matrix Test
+```bash
+# Test all 8 combinations (4 templates × 2 databases)
+# Docker auto-enabled for PostgreSQL runtime tests
+pnpm verify-publish --all
+```
+
+#### PostgreSQL (Docker Auto-Enabled)
+```bash
+# Docker automatically starts for PostgreSQL runtime tests
+pnpm verify-publish --template spa --database postgresql
+```
+
+#### Debug Failed Tests
+```bash
+# Keep projects for manual inspection
+pnpm verify-publish --template auth --keep
+
+# Projects saved to /tmp/velox-publish-verify-XXXX/
+```
+
+### Understanding Output
+
+```
+=== Post-Publish Verification ===
+Registry: https://registry.npmjs.org
+Version: 0.6.34
+Templates: spa auth trpc rsc
+Databases: sqlite postgresql
+
+=== Testing: spa + sqlite ===
+✓ Project created
+✓ Project structure verified
+✓ Dependencies installed
+✓ Prisma client generated
+✓ Build successful
+✓ Database schema pushed
+✓ Server started
+✓ GET /api/health (200)
+✓ GET /api/users (200)
+✓ POST /api/users (201)
+✓ GET /api/users/:id (200)
+✓ DELETE /api/users/:id (200)
+✓ All endpoint tests passed
+
+=== Verification Summary ===
+  Passed:  1
+  Failed:  0
+  Skipped: 0
+
+All verifications passed!
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All tests passed |
+| 1 | One or more tests failed |
+
+### Troubleshooting
+
+#### "No matching version found"
+The specified version doesn't exist on the registry:
+```bash
+# Check available versions
+npm view create-velox-app versions --registry http://localhost:4873
+```
+
+#### Docker Not Running
+PostgreSQL tests require Docker to be running:
+```bash
+# Start Docker Desktop or daemon first, then run:
+pnpm verify-publish --database postgresql
+```
+
+#### Port Already in Use
+The script uses random ports (3030-4030), but conflicts can occur:
+```bash
+# Kill processes on common ports
+lsof -ti :3030 | xargs kill -9
+```
+
+#### Inspect Failed Project
+```bash
+# Keep the test project
+pnpm verify-publish --template auth --keep
+
+# Navigate to it
+cd /tmp/velox-publish-verify-XXXXX/test-auth-sqlite
+
+# Manually debug
+npm run dev
+```
+
+### CI/CD Integration
+
+```yaml
+# GitHub Actions example
+verify-publish:
+  runs-on: ubuntu-latest
+  needs: publish
+  steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v2
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Verify published packages
+      run: |
+        cd packages/create
+        ./scripts/verify-publish.sh ${{ needs.publish.outputs.version }}
+```
+
+### Comparison: smoke-test vs verify-publish
+
+| Aspect | smoke-test | verify-publish |
+|--------|------------|----------------|
+| **Purpose** | Pre-publish validation | Post-publish validation |
+| **Package Source** | Local `file:` references | npm registry |
+| **Speed** | Faster (no npm download) | Slower (full npm install) |
+| **When to Run** | Before publishing | After publishing |
+| **Matrix Testing** | Single template | All combinations |
+| **Docker Support** | No | Auto (PostgreSQL) |
+
 ## Learn More
 
 See [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox) for complete documentation.

package/dist/cli.js

@@ -47,6 +47,7 @@ Templates:
   auth       ${TEMPLATE_METADATA.auth.description}
   trpc       ${TEMPLATE_METADATA.trpc.description}
   rsc        ${TEMPLATE_METADATA.rsc.description}
+  rsc-auth   ${TEMPLATE_METADATA['rsc-auth'].description}
 
 Databases:
   sqlite     ${DATABASE_METADATA.sqlite.hint}

package/dist/index.js

@@ -356,8 +356,10 @@ async function generatePrismaClient(config) {
         color: 'cyan',
     }).start();
     try {
-        // RSC template has Prisma in root, others in apps/api
-        const prismaDir = config.template === 'rsc' ? config.directory : path.join(config.directory, 'apps', 'api');
+        // RSC templates have Prisma in root, others in apps/api
+        const prismaDir = config.template === 'rsc' || config.template === 'rsc-auth'
+            ? config.directory
+            : path.join(config.directory, 'apps', 'api');
         await execAsync('npx prisma generate', {
             cwd: prismaDir,
             timeout: EXEC_TIMEOUT_MS,
@@ -422,11 +424,14 @@ function printSuccessMessage(config) {
     console.log(pc.green(`  Success! Created ${pc.bold(config.name)} with ${config.template} template`));
     console.log('');
     // Different structure messages based on template
-    if (config.template === 'rsc') {
+    if (config.template === 'rsc' || config.template === 'rsc-auth') {
         console.log(pc.dim('  Full-stack RSC application with:'));
         console.log(pc.dim('    app/pages   - React Server Components (file-based routing)'));
         console.log(pc.dim('    app/actions - Server actions'));
         console.log(pc.dim('    src/api     - Embedded Fastify API at /api/*'));
+        if (config.template === 'rsc-auth') {
+            console.log(pc.dim('    src/api/utils/auth.ts - JWT authentication helpers'));
+        }
     }
     else {
         console.log(pc.dim('  Full-stack workspace with:'));
@@ -445,7 +450,7 @@ function printSuccessMessage(config) {
     console.log(`    ${pc.cyan(devCommand)}${pc.dim('   # Start dev servers')}`);
     console.log('');
     // Different URL messages based on template
-    if (config.template === 'rsc') {
+    if (config.template === 'rsc' || config.template === 'rsc-auth') {
         console.log('  Your app will be available at:');
         console.log(`    ${pc.cyan('http://localhost:3030')}${pc.dim('  # Full-stack app')}`);
         console.log(`    ${pc.cyan('http://localhost:3030/api/*')}${pc.dim('  # API routes')}`);
@@ -460,5 +465,10 @@ function printSuccessMessage(config) {
         console.log('');
         console.log(pc.yellow('  Note: Set JWT_SECRET and JWT_REFRESH_SECRET in apps/api/.env for production'));
     }
+    // RSC-Auth template specific message
+    if (config.template === 'rsc-auth') {
+        console.log('');
+        console.log(pc.yellow('  Note: Set JWT_SECRET and JWT_REFRESH_SECRET in .env for production'));
+    }
     console.log('');
 }

package/dist/templates/auth.js

@@ -77,6 +77,9 @@ function generateApiTypesDts() {
 function generateAuthUtils() {
     return compileTemplate('api/utils/auth.ts', AUTH_CONFIG);
 }
+function generateDockerCompose(config) {
+    return compileTemplate('api/docker-compose.yml', config);
+}
 // ============================================================================
 // Auth Template Generator
 // ============================================================================
@@ -108,6 +111,13 @@ export function generateAuthTemplate(config) {
         { path: 'apps/api/src/types.d.ts', content: generateApiTypesDts() },
         { path: 'apps/api/src/utils/auth.ts', content: generateAuthUtils() },
     ];
+    // Add docker-compose for PostgreSQL
+    if (config.database === 'postgresql') {
+        files.push({
+            path: 'apps/api/docker-compose.yml',
+            content: generateDockerCompose(config),
+        });
+    }
     // Add root workspace files
     const rootFiles = generateRootFiles(config, true);
     // Add web package files (with auth UI)

package/dist/templates/index.js

@@ -5,6 +5,7 @@
  */
 import { generateAuthTemplate } from './auth.js';
 import { generateRscTemplate } from './rsc.js';
+import { generateRscAuthTemplate } from './rsc-auth.js';
 import { VELOXTS_VERSION } from './shared.js';
 import { generateSpaTemplate } from './spa.js';
 import { generateTrpcTemplate } from './trpc.js';
@@ -28,6 +29,8 @@ export function generateTemplateFiles(config) {
             return generateTrpcTemplate(config);
         case 'rsc':
             return generateRscTemplate(config);
+        case 'rsc-auth':
+            return generateRscAuthTemplate(config);
         case 'spa':
             return generateSpaTemplate(config);
         default: {
@@ -41,7 +44,7 @@ export function generateTemplateFiles(config) {
  * Get directories that need to be created for the template
  */
 export function getTemplateDirectories(template) {
-    // RSC template has a different structure (single-package, not monorepo)
+    // RSC templates have a different structure (single-package, not monorepo)
     if (template === 'rsc') {
         return [
             // App layer (RSC)
@@ -58,6 +61,32 @@ export function getTemplateDirectories(template) {
             'prisma',
             // Public assets
             'public',
+            // Scripts
+            'scripts',
+        ];
+    }
+    // RSC with Auth has additional directories for auth pages and utils
+    if (template === 'rsc-auth') {
+        return [
+            // App layer (RSC)
+            'app',
+            'app/pages',
+            'app/pages/auth',
+            'app/pages/dashboard',
+            'app/layouts',
+            'app/actions',
+            // Source layer
+            'src',
+            'src/api',
+            'src/api/procedures',
+            'src/api/schemas',
+            'src/api/utils',
+            // Prisma
+            'prisma',
+            // Public assets
+            'public',
+            // Scripts
+            'scripts',
         ];
     }
     // Workspace-based directory structure (default, auth, trpc)

package/dist/templates/placeholders.js

@@ -96,7 +96,6 @@ function getWsApiCommand(packageManager) {
             return 'npm run -w api';
         case 'yarn':
             return 'yarn workspace api';
-        case 'pnpm':
         default:
             return 'pnpm -F api';
     }
@@ -115,7 +114,6 @@ function getDevCommand(packageManager) {
             return 'concurrently \\"npm run -w api dev\\" \\"npm run -w web dev\\"';
         case 'yarn':
             return 'yarn workspaces foreach -A --parallel run dev';
-        case 'pnpm':
         default:
             return 'pnpm --parallel -r dev';
     }
@@ -130,7 +128,6 @@ function getWsAllCommand(packageManager) {
             return 'npm run -ws --if-present';
         case 'yarn':
             return 'yarn workspaces foreach -A run';
-        case 'pnpm':
         default:
             return 'pnpm -r';
     }

package/dist/templates/rsc-auth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * RSC Auth Template (React Server Components + Authentication)
+ *
+ * Full-stack application with:
+ * - React Server Components (RSC) with Vinxi
+ * - JWT Authentication via @veloxts/auth
+ * - Validated server actions with security features
+ * - File-based routing with auth pages
+ * - Embedded Fastify API at /api/*
+ */
+import type { TemplateConfig, TemplateFile } from './types.js';
+export declare function generateRscAuthTemplate(config: TemplateConfig): TemplateFile[];