luxlabs 1.0.0

package/LICENSE

@@ -0,0 +1,37 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2025 Lux AI Labs. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Lux AI Labs.
+
+RESTRICTIONS:
+
+1. You may NOT copy, modify, merge, publish, distribute, sublicense, and/or
+   sell copies of the Software without explicit written permission from
+   Lux AI Labs.
+
+2. You may NOT reverse engineer, decompile, or disassemble the Software.
+
+3. You may NOT use the Software to create derivative works.
+
+4. You may NOT remove or alter any proprietary notices, labels, or marks
+   on the Software.
+
+PERMITTED USE:
+
+You are granted a limited, non-exclusive, non-transferable license to use
+the Software solely for your internal business purposes in connection with
+the Lux platform, subject to the terms and conditions of your agreement
+with Lux AI Labs.
+
+DISCLAIMER:
+
+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
+LUX AI LABS 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.
+
+For licensing inquiries, contact: sam@uselux.ai

package/README.md

@@ -0,0 +1,161 @@
+# luxlabs
+
+Official CLI tool for Lux - Upload and deploy interfaces from your terminal.
+
+**Author:** Jason Henkel at Lux Labs
+
+## Installation
+
+```bash
+npm install -g luxlabs
+```
+
+## Quick Start
+
+```bash
+# Authenticate with Lux
+lux login
+
+# Initialize a new interface project
+lux interface init
+
+# Start local development with hot reload
+lux dev
+
+# Deploy your interface
+lux interface up
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `lux login` | Authenticate with Lux (opens browser) |
+| `lux login --key <api-key>` | Authenticate with an API key |
+| `lux logout` | Log out from Lux |
+
+### Interface Management
+
+| Command | Description |
+|---------|-------------|
+| `lux interface init` | Initialize a new interface project |
+| `lux interface up` | Upload and deploy your interface |
+| `lux interface list` | List all your interfaces |
+| `lux interface link` | Link current directory to an interface |
+| `lux i <subcommand>` | Shorthand alias for interface commands |
+
+### Development
+
+| Command | Description |
+|---------|-------------|
+| `lux dev` | Start local dev server with tunnel |
+| `lux dev -p <port>` | Specify custom port (default: 3000) |
+| `lux dev --no-tunnel` | Disable tunnel (local only) |
+| `lux servers` | List running dev servers |
+| `lux logs <interface>` | View logs from a dev server |
+
+### Data Management
+
+| Command | Description |
+|---------|-------------|
+| `lux data tables` | Manage database tables |
+| `lux data kv` | Manage KV namespaces |
+
+### Storage
+
+| Command | Description |
+|---------|-------------|
+| `lux storage ls` | List files in storage |
+| `lux storage get <key>` | Download a file |
+| `lux storage put <key> <file>` | Upload a file |
+| `lux storage rm <key>` | Delete a file |
+
+### Workflows
+
+| Command | Description |
+|---------|-------------|
+| `lux workflows list` | List all workflows |
+| `lux workflows get <id>` | Get workflow details |
+| `lux workflows create` | Create a new workflow |
+| `lux workflows publish <id>` | Publish a workflow |
+| `lux flow <subcommand>` | Shorthand alias |
+
+### Agents
+
+| Command | Description |
+|---------|-------------|
+| `lux agent list` | List all agents |
+| `lux agent get <id>` | Get agent details |
+| `lux agent create` | Create a new agent |
+| `lux agent prompt <id>` | View/edit agent prompt |
+
+### Knowledge Base
+
+| Command | Description |
+|---------|-------------|
+| `lux knowledge list` | List knowledge bases |
+| `lux knowledge upload <file>` | Upload to knowledge base |
+| `lux kb <subcommand>` | Shorthand alias |
+
+### Voice Agents
+
+| Command | Description |
+|---------|-------------|
+| `lux voice-agents list` | List voice agents |
+| `lux voice-agents create` | Create a voice agent |
+| `lux va <subcommand>` | Shorthand alias |
+
+### Secrets
+
+| Command | Description |
+|---------|-------------|
+| `lux secrets list` | List organization secrets |
+| `lux secrets set <key> <value>` | Set a secret |
+| `lux secrets get <key>` | Get a secret value |
+| `lux secrets delete <key>` | Delete a secret |
+
+### A/B Tests
+
+| Command | Description |
+|---------|-------------|
+| `lux ab-tests list-tests` | List all A/B tests |
+| `lux ab-tests get-test <id>` | Get test details |
+| `lux experiments <subcommand>` | Alias for ab-tests |
+
+### Project Deployment
+
+| Command | Description |
+|---------|-------------|
+| `lux project deploy` | Deploy project to GitHub |
+| `lux proj <subcommand>` | Shorthand alias |
+
+### Preview & Testing
+
+| Command | Description |
+|---------|-------------|
+| `lux preview <interface-id>` | Start interface preview |
+| `lux screenshot <interface-id>` | Take a screenshot |
+| `lux click <interface-id> <selector>` | Click an element |
+| `lux type <interface-id> <selector> <text>` | Type into an element |
+| `lux eval <interface-id> <code>` | Execute JavaScript |
+| `lux url <interface-id>` | Get current URL |
+| `lux nav <interface-id> <url>` | Navigate to URL |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- npm or yarn
+
+## Support
+
+For support and documentation, visit [uselux.ai](https://uselux.ai)
+
+For issues, visit [GitHub Issues](https://github.com/luxAILabs/lux-studio/issues)
+
+## License
+
+Proprietary - See LICENSE file for details.
+
+Copyright (c) 2024-2025 Lux AI Labs. All Rights Reserved.

package/commands/ab-tests.js

@@ -0,0 +1,437 @@
+/**
+ * A/B Tests Commands
+ *
+ * CLI commands for reading A/B test configurations.
+ * These are primarily used by Claude Code to understand what variants exist
+ * and what they should do (via the descriptions).
+ *
+ * Commands:
+ * - lux ab-tests list-tests [interface]              List all A/B tests
+ * - lux ab-tests get-test <key> [interface]          Get details for a specific test
+ * - lux ab-tests get-variant <key> <variant> [interface]  Get details for a specific variant
+ */
+
+const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Show help for ab-tests commands
+ */
+function showHelp() {
+  console.log(chalk.cyan('\nLux A/B Tests Commands:\n'));
+  console.log(chalk.white('  lux ab-tests list-tests [interface]'));
+  console.log(chalk.dim('    List all A/B tests for an interface'));
+  console.log(chalk.dim('    Options: --json (JSON output)\n'));
+  console.log(chalk.white('  lux ab-tests get-test <test-key> [interface]'));
+  console.log(chalk.dim('    Get details for a specific A/B test'));
+  console.log(chalk.dim('    Options: --json (JSON output)\n'));
+  console.log(chalk.white('  lux ab-tests get-variant <test-key> <variant-key> [interface]'));
+  console.log(chalk.dim('    Get details for a specific variant within a test'));
+  console.log(chalk.dim('    Options: --json (JSON output)\n'));
+}
+
+/**
+ * Get the path to ab-tests.json for an interface
+ * Supports both interface ID and interface name
+ */
+function getABTestsPath(interfaceIdentifier) {
+  const interfacesDir = path.join(process.cwd(), 'interfaces');
+
+  if (!fs.existsSync(interfacesDir)) {
+    return null;
+  }
+
+  // If no identifier provided, try to find the only interface
+  if (!interfaceIdentifier) {
+    const entries = fs.readdirSync(interfacesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory());
+
+    if (dirs.length === 0) {
+      return null;
+    }
+
+    if (dirs.length === 1) {
+      // Auto-select the only interface
+      interfaceIdentifier = dirs[0].name;
+    } else {
+      // Multiple interfaces - need to specify
+      console.log(chalk.yellow('Multiple interfaces found. Please specify which one:'));
+      for (const dir of dirs) {
+        const metaPath = path.join(interfacesDir, dir.name, 'metadata.json');
+        let name = dir.name;
+        if (fs.existsSync(metaPath)) {
+          try {
+            const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+            name = meta.name || dir.name;
+          } catch (e) { /* ignore */ }
+        }
+        console.log(chalk.dim(`  - ${name} (${dir.name})`));
+      }
+      return null;
+    }
+  }
+
+  // Check if it's a direct interface ID (directory exists)
+  let interfaceDir = path.join(interfacesDir, interfaceIdentifier, 'repo');
+  if (fs.existsSync(interfaceDir)) {
+    return path.join(interfaceDir, '.lux', 'ab-tests.json');
+  }
+
+  // Try to find by name
+  const entries = fs.readdirSync(interfacesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const metaPath = path.join(interfacesDir, entry.name, 'metadata.json');
+    if (fs.existsSync(metaPath)) {
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        if (meta.name && meta.name.toLowerCase() === interfaceIdentifier.toLowerCase()) {
+          return path.join(interfacesDir, entry.name, 'repo', '.lux', 'ab-tests.json');
+        }
+      } catch (e) { /* ignore */ }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get interface name from identifier
+ */
+function getInterfaceName(interfaceIdentifier) {
+  const interfacesDir = path.join(process.cwd(), 'interfaces');
+
+  if (!interfaceIdentifier) {
+    const entries = fs.readdirSync(interfacesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory());
+    if (dirs.length === 1) {
+      interfaceIdentifier = dirs[0].name;
+    }
+  }
+
+  if (!interfaceIdentifier) return 'Unknown';
+
+  const metaPath = path.join(interfacesDir, interfaceIdentifier, 'metadata.json');
+  if (fs.existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      return meta.name || interfaceIdentifier;
+    } catch (e) { /* ignore */ }
+  }
+
+  return interfaceIdentifier;
+}
+
+/**
+ * Load tests from file
+ */
+function loadTests(interfaceId) {
+  const testsPath = getABTestsPath(interfaceId);
+
+  if (!testsPath) {
+    return { error: 'Could not find interface. Make sure you are in a Lux project directory.' };
+  }
+
+  if (!fs.existsSync(testsPath)) {
+    return { tests: [], empty: true };
+  }
+
+  try {
+    const tests = JSON.parse(fs.readFileSync(testsPath, 'utf-8'));
+    return { tests, testsPath };
+  } catch (e) {
+    return { error: `Failed to parse ab-tests.json: ${e.message}` };
+  }
+}
+
+/**
+ * List all A/B tests for an interface
+ */
+async function listTests(interfaceId, options) {
+  const result = loadTests(interfaceId);
+
+  if (result.error) {
+    console.log(chalk.red(result.error));
+    return;
+  }
+
+  if (result.empty) {
+    if (options.json) {
+      console.log(JSON.stringify({ tests: [] }, null, 2));
+    } else {
+      console.log(chalk.yellow('No A/B tests found for this interface.'));
+      console.log(chalk.dim('Create tests in the Settings tab of your interface.'));
+    }
+    return;
+  }
+
+  const { tests } = result;
+
+  if (options.json) {
+    console.log(JSON.stringify({ tests }, null, 2));
+    return;
+  }
+
+  const interfaceName = getInterfaceName(interfaceId);
+  console.log(chalk.cyan(`\nA/B Tests for "${interfaceName}":`));
+
+  if (tests.length === 0) {
+    console.log(chalk.yellow('\nNo tests configured.'));
+    return;
+  }
+
+  for (const test of tests) {
+    console.log();
+    console.log(chalk.cyan(`📊 ${test.name}`) + chalk.dim(` (key: ${test.key})`));
+    console.log(chalk.dim(`   Status: ${test.status}${test.posthogFlagId ? ` (PostHog flag: ${test.posthogFlagId})` : ''}`));
+
+    if (test.description) {
+      console.log(chalk.white(`   Description: ${test.description}`));
+    }
+
+    // Show referenced components if any
+    if (test.referencedComponents && test.referencedComponents.length > 0) {
+      console.log(chalk.dim(`   Referenced Components: ${test.referencedComponents.join(', ')}`));
+    }
+
+    console.log(chalk.dim('\n   Variants:'));
+    for (const v of test.variants) {
+      const desc = v.description || 'No description';
+      console.log(chalk.white(`   • ${v.key} (${v.percentage}%)`) + chalk.dim(` - ${desc}`));
+    }
+  }
+
+  console.log();
+}
+
+/**
+ * Get details for a specific A/B test
+ */
+async function getTest(testKey, interfaceId, options) {
+  const result = loadTests(interfaceId);
+
+  if (result.error) {
+    console.log(chalk.red(result.error));
+    return;
+  }
+
+  if (result.empty) {
+    console.log(chalk.red('No A/B tests found for this interface.'));
+    return;
+  }
+
+  const { tests } = result;
+  const test = tests.find(t => t.key === testKey);
+
+  if (!test) {
+    console.log(chalk.red(`Test "${testKey}" not found.`));
+    console.log(chalk.dim('\nAvailable tests:'));
+    for (const t of tests) {
+      console.log(chalk.dim(`  - ${t.key} (${t.name})`));
+    }
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ test }, null, 2));
+    return;
+  }
+
+  console.log();
+  console.log(chalk.cyan(`📊 ${test.key}`));
+  console.log(chalk.white(`   Name: ${test.name}`));
+  console.log(chalk.dim(`   Status: ${test.status}${test.posthogFlagId ? ` (PostHog flag: ${test.posthogFlagId})` : ''}`));
+
+  if (test.description) {
+    console.log(chalk.white(`   Description: ${test.description}`));
+  }
+
+  // Show referenced components if any
+  if (test.referencedComponents && test.referencedComponents.length > 0) {
+    console.log(chalk.cyan('\n   Referenced Components:'));
+    for (const comp of test.referencedComponents) {
+      console.log(chalk.white(`   • ${comp}`));
+    }
+  }
+
+  console.log(chalk.dim(`\n   Variants (${test.variants.length}):`));
+  for (const v of test.variants) {
+    console.log(chalk.white(`   • ${v.key} (${v.percentage}%)`));
+    if (v.description) {
+      console.log(chalk.dim(`     ${v.description}`));
+    }
+  }
+
+  // Show implementation pattern
+  const nonControlVariants = test.variants.filter(v => v.key !== 'current' && v.key !== 'control');
+  if (nonControlVariants.length > 0) {
+    console.log(chalk.dim('\n   Implementation Pattern:'));
+    console.log(chalk.gray(`   import { useFeatureFlagVariantKey } from 'posthog-js/react';`));
+    console.log(chalk.gray(`   const variant = useFeatureFlagVariantKey('${test.key}');`));
+    for (const v of nonControlVariants) {
+      const comment = v.description ? ` /* ${v.description} */` : '';
+      console.log(chalk.gray(`   if (variant === '${v.key}') {${comment} }`));
+    }
+  }
+
+  console.log();
+}
+
+/**
+ * Get details for a specific variant within a test
+ */
+async function getVariant(testKey, variantKey, interfaceId, options) {
+  const result = loadTests(interfaceId);
+
+  if (result.error) {
+    console.log(chalk.red(result.error));
+    return;
+  }
+
+  if (result.empty) {
+    console.log(chalk.red('No A/B tests found for this interface.'));
+    return;
+  }
+
+  const { tests } = result;
+  const test = tests.find(t => t.key === testKey);
+
+  if (!test) {
+    console.log(chalk.red(`Test "${testKey}" not found.`));
+    console.log(chalk.dim('\nAvailable tests:'));
+    for (const t of tests) {
+      console.log(chalk.dim(`  - ${t.key} (${t.name})`));
+    }
+    return;
+  }
+
+  const variant = test.variants.find(v => v.key === variantKey);
+
+  if (!variant) {
+    console.log(chalk.red(`Variant "${variantKey}" not found in test "${testKey}".`));
+    console.log(chalk.dim('\nAvailable variants:'));
+    for (const v of test.variants) {
+      console.log(chalk.dim(`  - ${v.key} (${v.name || v.key})`));
+    }
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      test: { key: test.key, name: test.name, description: test.description },
+      variant
+    }, null, 2));
+    return;
+  }
+
+  console.log();
+  console.log(chalk.cyan(`🎯 Variant: ${variant.key}`));
+  console.log(chalk.dim(`   Test: ${test.name} (${test.key})`));
+  console.log(chalk.white(`   Name: ${variant.name || variant.key}`));
+  console.log(chalk.dim(`   Traffic: ${variant.percentage}%`));
+
+  if (variant.description) {
+    console.log(chalk.cyan('\n   Description (what this variant should do):'));
+    console.log(chalk.white(`   ${variant.description}`));
+  } else {
+    console.log(chalk.yellow('\n   No description set for this variant.'));
+  }
+
+  // Show referenced components for this variant if any
+  if (variant.referencedComponents && variant.referencedComponents.length > 0) {
+    console.log(chalk.cyan('\n   Referenced Components:'));
+    for (const comp of variant.referencedComponents) {
+      console.log(chalk.white(`   • ${comp}`));
+    }
+  }
+
+  // Show implementation hint
+  const isControl = variant.key === 'current' || variant.key === 'control';
+  if (!isControl) {
+    console.log(chalk.dim('\n   Implementation:'));
+    console.log(chalk.gray(`   import { useFeatureFlagVariantKey } from 'posthog-js/react';`));
+    console.log(chalk.gray(`   const variant = useFeatureFlagVariantKey('${test.key}');`));
+    console.log(chalk.gray(`   if (variant === '${variant.key}') {`));
+    if (variant.description) {
+      console.log(chalk.gray(`     // ${variant.description}`));
+    }
+    console.log(chalk.gray(`   }`));
+  } else {
+    console.log(chalk.dim('\n   Note: This is the control/baseline variant (default behavior).'));
+  }
+
+  console.log();
+}
+
+/**
+ * Parse command options from args array
+ */
+function parseOptions(args) {
+  const options = { json: false };
+  const remaining = [];
+
+  for (const arg of args) {
+    if (arg === '--json') {
+      options.json = true;
+    } else if (!arg.startsWith('-')) {
+      remaining.push(arg);
+    }
+  }
+
+  return { options, remaining };
+}
+
+/**
+ * Handle ab-tests commands
+ */
+async function handleABTests(args) {
+  const subcommand = args[0];
+  const subArgs = args.slice(1);
+
+  if (!subcommand || subcommand === 'help') {
+    showHelp();
+    return;
+  }
+
+  const { options, remaining } = parseOptions(subArgs);
+
+  switch (subcommand) {
+    case 'list-tests':
+    case 'list':
+    case 'ls':
+      await listTests(remaining[0], options);
+      break;
+
+    case 'get-test':
+    case 'get':
+      if (!remaining[0]) {
+        console.log(chalk.red('Missing test key. Usage: lux ab-tests get-test <test-key> [interface]'));
+        return;
+      }
+      await getTest(remaining[0], remaining[1], options);
+      break;
+
+    case 'get-variant':
+      if (!remaining[0]) {
+        console.log(chalk.red('Missing test key. Usage: lux ab-tests get-variant <test-key> <variant-key> [interface]'));
+        return;
+      }
+      if (!remaining[1]) {
+        console.log(chalk.red('Missing variant key. Usage: lux ab-tests get-variant <test-key> <variant-key> [interface]'));
+        return;
+      }
+      await getVariant(remaining[0], remaining[1], remaining[2], options);
+      break;
+
+    default:
+      console.log(chalk.red(`Unknown subcommand: ${subcommand}`));
+      showHelp();
+      process.exit(1);
+  }
+}
+
+module.exports = {
+  handleABTests,
+};