@revealui/setup 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 RevealUI Team
+
+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,306 @@
+# @revealui/setup
+
+Shared setup utilities for RevealUI projects. Provides environment variable management, database initialization, and configuration validation.
+
+## Features
+
+- **Environment Setup** - Interactive and automated environment variable configuration
+- **Secret Generation** - Cryptographically secure secret and password generation
+- **Validation** - Type-safe validation for environment variables
+- **Logging** - Consistent, colored console output with log levels
+- **Reusable** - Used by both @revealui/cli and setup scripts
+
+## Installation
+
+```bash
+pnpm add @revealui/setup
+```
+
+## Usage
+
+### Environment Setup
+
+```typescript
+import { setupEnvironment } from '@revealui/setup/environment'
+
+// Interactive setup with prompts
+const result = await setupEnvironment({
+  projectRoot: '/path/to/project',
+  interactive: true
+})
+
+if (result.success) {
+  console.log('Environment configured!')
+} else {
+  console.log('Missing variables:', result.missing)
+}
+```
+
+### Generate Secrets
+
+```typescript
+import { generateSecret, generatePassword } from '@revealui/setup/environment'
+
+const jwtSecret = generateSecret(32)    // 64-char hex string
+const password = generatePassword(16)    // 16-char alphanumeric + special
+```
+
+### Validate Environment
+
+```typescript
+import { validateEnv, REQUIRED_ENV_VARS } from '@revealui/setup/validators'
+
+const validation = validateEnv(REQUIRED_ENV_VARS, process.env)
+
+if (!validation.valid) {
+  console.log('Missing:', validation.missing)
+  console.log('Invalid:', validation.invalid)
+}
+```
+
+### Logging
+
+```typescript
+import { createLogger } from '@revealui/setup/utils'
+
+const logger = createLogger({
+  prefix: 'MyScript',
+  level: 'info',
+  timestamps: true
+})
+
+logger.info('Starting process')
+logger.success('Completed!')
+logger.error('Failed')
+logger.header('Section Title')
+logger.divider()
+logger.progress(50, 100, 'Processing')
+```
+
+## API Reference
+
+### Environment
+
+#### `setupEnvironment(options)`
+
+Sets up environment variables for a project.
+
+**Options:**
+- `projectRoot: string` - Project root directory
+- `templatePath?: string` - Path to .env.template (default: `{projectRoot}/.env.template`)
+- `outputPath?: string` - Output path (default: `{projectRoot}/.env.development.local`)
+- `force?: boolean` - Overwrite existing file without prompting
+- `generateOnly?: boolean` - Only generate secrets, skip prompts
+- `interactive?: boolean` - Enable interactive prompts (default: true)
+- `customVariables?: EnvVariable[]` - Custom variable definitions
+- `logger?: Logger` - Custom logger instance
+
+**Returns:** `Promise<SetupEnvironmentResult>`
+- `success: boolean` - Whether setup completed successfully
+- `envPath: string` - Path to generated env file
+- `missing: string[]` - Variables still missing
+- `invalid: string[]` - Variables with invalid values
+
+#### `generateSecret(length?: number)`
+
+Generates cryptographically secure hex string.
+
+#### `generatePassword(length?: number)`
+
+Generates random password with alphanumeric + special characters.
+
+#### `updateEnvValue(content, key, value)`
+
+Updates or adds an environment variable in file content.
+
+#### `parseEnvContent(content)`
+
+Parses environment file content into key-value object.
+
+### Validators
+
+#### `validateEnv(required, env)`
+
+Validates environment variables against schema.
+
+**Parameters:**
+- `required: EnvVariable[]` - Required variable definitions
+- `env: Record<string, string>` - Environment to validate
+
+**Returns:** `ValidationResult`
+- `valid: boolean`
+- `missing: string[]`
+- `invalid: string[]`
+
+#### `validators`
+
+Pre-built validators:
+- `postgresUrl` - PostgreSQL connection string
+- `stripeSecretKey` - Stripe secret key format
+- `stripePublishableKey` - Stripe publishable key format
+- `url` - Valid URL format
+- `email` - Valid email format
+- `minLength(n)` - Minimum string length
+
+#### `REQUIRED_ENV_VARS`
+
+Default required environment variables for RevealUI:
+- `REVEALUI_SECRET` - JWT secret (min 32 chars)
+- `POSTGRES_URL` - Database connection string
+- `BLOB_READ_WRITE_TOKEN` - Vercel Blob token
+- `STRIPE_SECRET_KEY` - Stripe secret key
+- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - Stripe publishable key
+
+#### `OPTIONAL_ENV_VARS`
+
+Optional environment variables (Supabase, Sentry, admin config, etc.)
+
+### Utilities
+
+#### `createLogger(options)`
+
+Creates a logger instance with configurable options.
+
+**Options:**
+- `level?: 'debug' | 'info' | 'warn' | 'error' | 'silent'`
+- `prefix?: string` - Prefix for all log messages
+- `colors?: boolean` - Enable colors (auto-detected by default)
+- `timestamps?: boolean` - Include timestamps
+
+**Methods:**
+- `debug(msg, ...args)` - Debug message
+- `info(msg, ...args)` - Info message
+- `warn(msg, ...args)` - Warning message
+- `error(msg, ...args)` - Error message
+- `success(msg, ...args)` - Success message
+- `header(msg)` - Formatted header
+- `divider()` - Visual divider
+- `table(data)` - Console table
+- `group(label)` - Start group
+- `groupEnd()` - End group
+- `progress(current, total, label?)` - Progress bar
+
+## Examples
+
+### Complete Setup Flow
+
+```typescript
+import { setupEnvironment, createLogger } from '@revealui/setup'
+
+const logger = createLogger({ prefix: 'Setup' })
+
+logger.header('Project Setup')
+
+const result = await setupEnvironment({
+  projectRoot: process.cwd(),
+  interactive: true,
+  logger
+})
+
+if (result.success) {
+  logger.success('Environment configured successfully!')
+  logger.info(`Config file: ${result.envPath}`)
+} else {
+  logger.error('Setup failed')
+  logger.info('Missing variables:', result.missing.join(', '))
+}
+```
+
+### Non-Interactive Setup
+
+```typescript
+import { setupEnvironment } from '@revealui/setup'
+
+// Generate secrets only, no prompts
+const result = await setupEnvironment({
+  projectRoot: '/path/to/project',
+  interactive: false,
+  generateOnly: true
+})
+```
+
+### Custom Validation
+
+```typescript
+import { validateEnv, validators, type EnvVariable } from '@revealui/setup/validators'
+
+const customVars: EnvVariable[] = [
+  {
+    name: 'API_KEY',
+    description: 'Third-party API key',
+    required: true,
+    validator: validators.minLength(20)
+  },
+  {
+    name: 'WEBHOOK_URL',
+    description: 'Webhook endpoint',
+    required: true,
+    validator: validators.url
+  }
+]
+
+const validation = validateEnv(customVars, process.env)
+```
+
+## Package Exports
+
+```typescript
+// Main export
+import { setupEnvironment, createLogger } from '@revealui/setup'
+
+// Subpath exports
+import { setupEnvironment } from '@revealui/setup/environment'
+import { validateEnv } from '@revealui/setup/validators'
+import { createLogger } from '@revealui/setup/utils'
+```
+
+## Integration
+
+### In @revealui/cli
+
+```typescript
+import { setupEnvironment, createLogger } from '@revealui/setup'
+
+const logger = createLogger({ prefix: '@revealui/cli' })
+
+await setupEnvironment({
+  projectRoot: projectPath,
+  interactive: true,
+  logger
+})
+```
+
+### In Setup Scripts
+
+```typescript
+#!/usr/bin/env tsx
+import { setupEnvironment } from '@revealui/setup'
+
+await setupEnvironment({
+  projectRoot: process.cwd(),
+  force: process.argv.includes('--force')
+})
+```
+
+## Development
+
+```bash
+# Build package
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Run tests
+pnpm test
+
+# Coverage
+pnpm test:coverage
+```
+
+## License
+
+MIT

package/dist/environment/index.d.ts

@@ -0,0 +1,95 @@
+import { createLogger } from '../utils/index.js';
+import { EnvVariable } from '../validators/index.js';
+
+/**
+ * Environment secret and password generators
+ */
+/**
+ * Generates a secure random secret.
+ *
+ * @param length - Length in bytes (default: 32 bytes = 64 hex chars)
+ * @returns Hex-encoded random secret
+ *
+ * @example
+ * ```typescript
+ * const secret = generateSecret() // 64 char hex string
+ * ```
+ */
+declare function generateSecret(length?: number): string;
+/**
+ * Generates a secure password with alphanumeric and special characters.
+ *
+ * @param length - Password length (default: 16)
+ * @returns Random password
+ *
+ * @example
+ * ```typescript
+ * const password = generatePassword(16) // e.g., "aB3!xY9@pQ5#mN7$"
+ * ```
+ */
+declare function generatePassword(length?: number): string;
+/**
+ * Updates a value in environment file content.
+ *
+ * @param content - Original env file content
+ * @param key - Environment variable name
+ * @param value - New value
+ * @returns Updated env file content
+ *
+ * @example
+ * ```typescript
+ * const updated = updateEnvValue(content, 'DB_URL', 'postgresql://...')
+ * ```
+ */
+declare function updateEnvValue(content: string, key: string, value: string): string;
+/**
+ * Parses environment file content into key-value pairs.
+ *
+ * @param content - Environment file content
+ * @returns Parsed environment variables
+ *
+ * @example
+ * ```typescript
+ * const env = parseEnvContent('DB_URL=postgresql://...\nAPI_KEY=abc123')
+ * // { DB_URL: 'postgresql://...', API_KEY: 'abc123' }
+ * ```
+ */
+declare function parseEnvContent(content: string): Record<string, string>;
+
+/**
+ * Environment setup orchestration
+ */
+
+interface SetupEnvironmentOptions {
+    projectRoot: string;
+    templatePath?: string;
+    outputPath?: string;
+    force?: boolean;
+    generateOnly?: boolean;
+    interactive?: boolean;
+    customVariables?: EnvVariable[];
+    logger?: ReturnType<typeof createLogger>;
+}
+interface SetupEnvironmentResult {
+    success: boolean;
+    envPath: string;
+    missing: string[];
+    invalid: string[];
+}
+/**
+ * Sets up environment variables for a project.
+ *
+ * @param options - Setup configuration options
+ * @returns Setup result with validation info
+ *
+ * @example
+ * ```typescript
+ * const result = await setupEnvironment({
+ *   projectRoot: '/path/to/project',
+ *   interactive: true
+ * })
+ * ```
+ */
+declare function setupEnvironment(options: SetupEnvironmentOptions): Promise<SetupEnvironmentResult>;
+
+export { type SetupEnvironmentOptions, type SetupEnvironmentResult, generatePassword, generateSecret, parseEnvContent, setupEnvironment, updateEnvValue };