quapp 1.1.2 → 1.1.3

package/README.md

@@ -1,193 +1,127 @@
 # quapp
 
-Development CLI for Quapp projects - start a dev server with LAN QR code and build `.qpp` packages.
+Dev server and build tool for Quapp projects. Serves your app over LAN with a QR code for mobile testing, and packages production builds as `.qpp` files.
 
-## Installation
+## Quick Start
+
+If you scaffolded with `create-quapp`, run the pre-configured scripts:
 
 ```bash
-npm install -D quapp
+npm run dev      # Start dev server
+npm run qbuild   # Build .qpp package
 ```
 
-## Commands
+## Installation
 
-### `quapp init`
+For existing Vite projects:
 
-Initialize Quapp in an existing project. Creates config and adds scripts.
+```bash
+npm install -D quapp
+```
+
+Initialize configuration and scripts:
 
 ```bash
-quapp init [options]
+npx quapp init
 ```
 
-**Options:**
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--yes` | `-y` | Skip confirmation prompt |
-| `--force` | `-f` | Overwrite existing config/scripts |
-| `--dry-run` | | Preview changes without applying |
+## Commands
 
 ### `quapp serve`
 
-Start development server with LAN access and QR code for mobile testing.
+Starts Vite dev server with LAN network access and QR code.
 
 ```bash
-quapp serve [options]
+npx quapp serve
 ```
 
-**Options:**
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--port <port>` | `-p` | Port to run on (default: 5173) |
-| `--host <host>` | | Host to bind to |
-| `--open` | | Open browser automatically |
-| `--no-qr` | | Disable QR code display |
-| `--https` | | Enable HTTPS |
+| Flag | Description |
+|------|-------------|
+| `-p, --port <port>` | Server port (default: 5173) |
+| `--host <host>` | Host to bind |
+| `--open` | Open in browser |
+| `--no-qr` | Disable QR code |
+| `--https` | Enable HTTPS |
 
 ### `quapp build`
 
-Build for production and create `.qpp` package.
+Builds for production and creates `.qpp` package.
 
 ```bash
-quapp build [options]
+npx quapp build
 ```
 
-**Options:**
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--output <file>` | `-o` | Output filename (default: dist.qpp) |
-| `--no-clean` | | Keep dist folder after build |
-| `--skip-prompts` | | Skip interactive prompts |
+| Flag | Description |
+|------|-------------|
+| `-o, --output <file>` | Output filename (default: dist.qpp) |
+| `--skip-prompts` | Non-interactive mode |
+| `--no-clean` | Keep dist folder |
 
-## Global Options
+### `quapp init`
+
+Initialize Quapp in an existing Vite project.
+
+```bash
+npx quapp init
+```
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--json` | | Output as JSON (for automation/AI) |
-| `--no-color` | | Disable colored output |
-| `--verbose` | | Show detailed logs |
-| `--version` | `-v` | Show version |
-| `--help` | `-h` | Show help |
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | Skip prompts |
+| `-f, --force` | Overwrite existing config |
+| `--dry-run` | Preview changes |
 
 ## Configuration
 
-Create `quapp.config.json` in your project root:
+`quapp.config.json`:
 
 ```json
 {
   "server": {
     "port": 5173,
     "qr": true,
-    "network": "private",
-    "openBrowser": false,
-    "https": false,
-    "fallbackPort": true,
-    "autoRetry": true,
-    "strictPort": false
+    "openBrowser": false
   },
   "build": {
-    "outDir": "dist",
     "outputFile": "dist.qpp"
   }
 }
 ```
 
-## Examples
-
-```bash
-# Initialize Quapp in existing project
-quapp init
-
-# Initialize without prompts (AI-friendly)
-quapp init --yes --json
-
-# Start dev server
-quapp serve
-
-# Start on specific port
-quapp serve -p 3000
-
-# Start and open browser
-quapp serve --open
-
-# Build for production
-quapp build
-
-# Build with custom output name
-quapp build -o my-app.qpp
+## Global Options
 
-# Build with JSON output (AI-friendly)
-quapp build --json --skip-prompts
-```
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output for automation |
+| `--verbose` | Detailed logging |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
 
-## AI/Automation Usage
+## Automation
 
-For non-interactive environments:
+For CI/CD or programmatic usage:
 
 ```bash
-# Initialize without prompts
-quapp init --yes --json
-
-# Preview init changes
-quapp init --dry-run --json
-
-# Build without prompts
-quapp build --skip-prompts --json
-
-# Build with custom output
-quapp build -o myapp.qpp --skip-prompts --json
+npx quapp build --skip-prompts --json
 ```
 
-### JSON Output Examples
-
-Init success:
-```json
-{
-  "success": true,
-  "changes": ["quapp.config.json", "script:dev", "script:qbuild", "devDependency:quapp"],
-  "nextSteps": ["npm install", "npm run dev"]
-}
-```
-
-Build success:
 ```json
 {
   "success": true,
   "outputFile": "dist.qpp",
-  "outputPath": "/path/to/project/dist.qpp",
-  "manifest": {
-    "package_name": "com.author.myapp",
-    "version": "1.0.0",
-    "version_code": 10000
-  },
-  "duration": 5230
-}
-```
-
-Error (with suggestion for AI):
-```json
-{
-  "success": false,
-  "errorCode": "NO_BUILD_SCRIPT",
-  "error": "No build script",
-  "suggestion": "Add to package.json: \"scripts\": { \"build\": \"vite build\" }"
+  "outputPath": "/path/to/dist.qpp",
+  "duration": 1234
 }
 ```
 
-## Exit Codes
+## Requirements
 
-| Code | Description |
-|------|-------------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Invalid arguments |
-| 3 | Build failed |
-| 4 | Configuration error |
-| 5 | Missing dependency |
-| 130 | User cancelled |
+- Node.js 18+
+- Vite project
 
-## Requirements
+## Related
 
-- Node.js >= 18.0.0
-- Vite (in your project's dependencies)
+- [create-quapp](https://www.npmjs.com/package/create-quapp) — Project scaffolding
 
 ## License
 

package/bin/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * quapp CLI - Development and build tools for Quapp projects

package/commands/serve.js

@@ -1,9 +1,15 @@
 /**
  * Serve command - Start development server with LAN access
+ * 
+ * Design: We use --strictPort so Vite exits on port conflicts, allowing us to:
+ * 1. Control ALL user-facing messages (no duplicate/conflicting output)
+ * 2. Show accurate port information
+ * 3. Provide a clean, quapp-branded DX
  */
 
 import { spawn } from 'child_process';
 import os from 'os';
+import net from 'net';
 import * as logger from '../lib/logger.js';
 import { loadConfig, checkViteAvailable } from '../lib/config.js';
 import { EXIT_CODES } from '../lib/constants.js';
@@ -27,6 +33,50 @@ function getIP(networkType = 'private') {
   return 'localhost';
 }
 
+/**
+ * Check if a port is available
+ * @param {number} port - Port to check
+ * @param {string} host - Host to check on
+ * @returns {Promise<boolean>}
+ */
+function isPortAvailable(port, host = 'localhost') {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => {
+      server.close(); // Clean up even on error to prevent fd leak
+      resolve(false);
+    });
+    server.once('listening', () => {
+      server.close();
+      resolve(true);
+    });
+    server.listen(port, host);
+  });
+}
+
+/**
+ * Find an available port starting from the given port
+ * @param {number} startPort - Port to start searching from
+ * @param {string} host - Host to check on
+ * @param {number} maxAttempts - Maximum number of ports to try
+ * @returns {Promise<{port: number, retries: number}>}
+ */
+async function findAvailablePort(startPort, host = 'localhost', maxAttempts = 10) {
+  let port = startPort;
+  let retries = 0;
+  
+  while (retries < maxAttempts) {
+    if (await isPortAvailable(port, host)) {
+      return { port, retries };
+    }
+    logger.info(`Port ${port} is in use, trying ${port + 1}...`);
+    port++;
+    retries++;
+  }
+  
+  throw new Error(`Could not find an available port after ${maxAttempts} attempts`);
+}
+
 /**
  * Run the serve command
  * @param {Object} options - Command options
@@ -61,19 +111,29 @@ export async function runServe(options = {}) {
     return { success: false, error: 'Vite not found', exitCode: EXIT_CODES.MISSING_DEPENDENCY };
   }
 
-  logger.debug(`Starting Vite on ${serverConfig.host}:${serverConfig.port}`);
+  // Find available port BEFORE starting Vite (if autoRetry is enabled)
+  let actualPort = serverConfig.port;
+  
+  if (config.server.autoRetry && !serverConfig.strictPort) {
+    try {
+      const { port, retries } = await findAvailablePort(serverConfig.port, serverConfig.host);
+      actualPort = port;
+    } catch (err) {
+      logger.error(err.message);
+      return { success: false, error: err.message, exitCode: EXIT_CODES.GENERAL_ERROR };
+    }
+  }
 
-  // Build Vite arguments
+  logger.debug(`Starting dev server on ${serverConfig.host}:${actualPort}`);
+
+  // Build Vite arguments - always use strictPort since we handle port finding ourselves
   const viteArgs = [
     'vite',
     '--host', serverConfig.host,
-    '--port', String(serverConfig.port),
+    '--port', String(actualPort),
+    '--strictPort', // Always strict since we pre-check port availability
   ];
 
-  if (serverConfig.strictPort || !config.server.autoRetry) {
-    viteArgs.push('--strictPort');
-  }
-
   if (serverConfig.https) {
     viteArgs.push('--https');
   }
@@ -90,24 +150,22 @@ export async function runServe(options = {}) {
     shell: true,
   });
 
-  let qrShown = false;
-
-  // Build URLs - LAN URL for QR code, localhost for browser
+  let serverReady = false;
+  let bannerShown = false;
   const protocol = serverConfig.https ? 'https' : 'http';
-  const lanUrl = `${protocol}://${serverConfig.host}:${serverConfig.port}`;
-  const localUrl = `${protocol}://localhost:${serverConfig.port}`;
+  const lanUrl = `${protocol}://${serverConfig.host}:${actualPort}`;
+  const localUrl = `${protocol}://localhost:${actualPort}`;
+
+  // Function to show our custom banner with QR code
+  const showBanner = async () => {
+    if (bannerShown) return;
+    bannerShown = true;
 
-  // Function to show QR code and open browser
-  const showQRAndOpenBrowser = async () => {
-    if (qrShown) return;
-    qrShown = true;
-    
-    // Show access URLs
     logger.newline();
-    console.log('  \x1b[1m\x1b[32m✓\x1b[0m \x1b[1mServer running!\x1b[0m');
+    console.log('  \x1b[1m\x1b[32m✓\x1b[0m \x1b[1mDev server running!\x1b[0m');
     logger.newline();
     // console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mLocal:\x1b[0m   ${localUrl}`);
-    console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mNetwork:\x1b[0m ${lanUrl}`);
+    // console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mNetwork:\x1b[0m ${lanUrl}`);
     
     // Show QR code for mobile access
     if (serverConfig.qr) {
@@ -118,33 +176,55 @@ export async function runServe(options = {}) {
         logger.newline();
         qrcode.default.generate(lanUrl, { small: true });
       } catch (err) {
-        // qrcode-terminal not available, skip
         logger.debug(`QR code generation failed: ${err.message}`);
       }
     }
     
+    logger.newline();
+    console.log('  \x1b[90mpress h + enter to show help\x1b[0m');
     logger.newline();
 
-    // Open browser if requested - use localhost for local browser access
+    // Open browser if requested
     if (serverConfig.openBrowser) {
       try {
         const open = await import('open');
-        await open.default(lanUrl);
+        await open.default(localUrl);
       } catch (err) {
         logger.debug(`Failed to open browser: ${err.message}`);
       }
     }
   };
 
-  // Show QR code after Vite has had time to start (simple and reliable)
-  setTimeout(showQRAndOpenBrowser, 1500);
-
-  // Handle stdout - just pass through to console
+  // Handle stdout - filter Vite's startup banner, pass through HMR/other messages
   viteProcess.stdout.on('data', (data) => {
+    const output = data.toString();
+    
+    // Detect when Vite is ready
+    if (output.includes('ready in')) {
+      serverReady = true;
+      // Show our banner instead of Vite's
+      showBanner();
+      return; // Don't print Vite's ready line
+    }
+    
+    // Filter out Vite's startup banner lines (we show our own)
+    // These patterns match Vite's default startup output
+    const isStartupBanner = 
+      output.includes('VITE v') ||
+      output.includes('➜  Local:') ||
+      output.includes('➜  Network:') ||
+      output.includes('press h + enter') ||
+      (output.trim() === '' && !serverReady); // Empty lines before ready
+    
+    if (isStartupBanner) {
+      return; // Suppress Vite's banner
+    }
+    
+    // Pass through all other output (HMR updates, warnings, etc.)
     process.stdout.write(data);
   });
 
-  // Handle stderr
+  // Handle stderr - pass through (errors, warnings)
   viteProcess.stderr.on('data', (data) => {
     process.stderr.write(data);
   });
@@ -152,20 +232,10 @@ export async function runServe(options = {}) {
   // Handle process exit
   return new Promise((resolve) => {
     viteProcess.on('close', (code) => {
-      if (code !== 0 && config.server.autoRetry && options._attempt < 10) {
-        const nextPort = serverConfig.port + 1;
-        logger.warn(`Port ${serverConfig.port} in use. Trying port ${nextPort}...`);
-        
-        // Retry with next port
-        resolve(runServe({
-          ...options,
-          port: nextPort,
-          _attempt: (options._attempt || 0) + 1,
-        }));
-      } else if (code !== 0) {
+      if (code !== 0) {
         resolve({
           success: false,
-          error: `Vite exited with code ${code}`,
+          error: `Dev server exited with code ${code}`,
           exitCode: EXIT_CODES.GENERAL_ERROR,
         });
       } else {
@@ -178,7 +248,7 @@ export async function runServe(options = {}) {
     });
 
     viteProcess.on('error', (err) => {
-      logger.error(`Failed to start Vite: ${err.message}`);
+      logger.error(`Failed to start dev server: ${err.message}`);
       resolve({
         success: false,
         error: err.message,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quapp",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "A lightweight CLI tool for Quapp development - start a Vite dev server with LAN QR code and build .qpp packages for production",
   "type": "module",
   "bin": {