@astralkit/cli 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blue Beacon Creative LLC
+
+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,198 @@
+# @astralkit/cli
+
+Install and manage AstralKit UI components in your project.
+
+## Quick Start
+
+```bash
+# Initialize AstralKit in your project
+npx @astralkit/cli init
+
+# Add a component
+npx @astralkit/cli add button-sizes
+
+# Search for components
+npx @astralkit/cli search "pricing table"
+```
+
+## Commands
+
+### `astralkit init`
+
+Initialize AstralKit in your project. Detects your framework and creates `astralkit.config.json`.
+
+```bash
+astralkit init
+astralkit init --framework=react
+astralkit init --dir=src/components/ui
+```
+
+### `astralkit add <component>`
+
+Add a component to your project. Fetches code from AstralKit and writes it to your components directory.
+
+```bash
+astralkit add avatar-variants
+astralkit add pricing-table --framework=react
+astralkit add data-table --overwrite
+```
+
+Options:
+- `-f, --framework` — Framework version (html, react, vue, nextjs, angular, svelte, astro)
+- `--dir` — Override output directory
+- `--overwrite` — Overwrite existing files
+
+### `astralkit list`
+
+List all available components.
+
+```bash
+astralkit list
+astralkit list --category=forms
+astralkit list --framework=react
+astralkit list --pro
+astralkit list --free
+```
+
+### `astralkit search <query>`
+
+Search for components by name or description.
+
+```bash
+astralkit search "data table"
+astralkit search "pricing" --framework=react
+```
+
+### `astralkit diff <component>`
+
+Show differences between your local component and the latest version.
+
+```bash
+astralkit diff button-sizes
+```
+
+### `astralkit update <component>`
+
+Update a component to the latest version from AstralKit.
+
+```bash
+astralkit update button-sizes
+astralkit update button-sizes --force
+```
+
+### `astralkit login`
+
+Authenticate with AstralKit to access premium components. Opens your browser for secure login.
+
+```bash
+astralkit login
+```
+
+### `astralkit logout`
+
+Remove stored authentication.
+
+### `astralkit whoami`
+
+Show current authentication status and subscription plan. Verifies your token with the server.
+
+## Premium Components
+
+Some components require a Pro subscription. When you try to add a pro component without authentication:
+
+```bash
+$ astralkit add pro-data-table
+✖ Failed to add component.
+Authentication required. Run `astralkit login` to authenticate.
+```
+
+After logging in, pro components install normally:
+
+```bash
+$ astralkit login
+✔ Authenticated successfully!
+  Email: you@example.com
+  Plan:  pro
+
+$ astralkit add pro-data-table
+✔ Added Pro Data Table (react)
+```
+
+## Configuration
+
+### `astralkit.config.json`
+
+Created by `astralkit init` in your project root:
+
+```json
+{
+  "$schema": "https://astralkit.com/schema/config.json",
+  "framework": "nextjs",
+  "componentsDir": "src/components/ui",
+  "tokensImport": "@astralkit/tokens/css"
+}
+```
+
+### `~/.astralkit/config.json`
+
+Stores your authentication token (created by `astralkit login`). This file is created with restricted permissions (owner read/write only).
+
+## CI/CD Usage
+
+For automated environments (CI/CD pipelines, Docker builds), set the `ASTRALKIT_TOKEN` environment variable instead of using browser login:
+
+```bash
+# Set token from your AstralKit dashboard
+export ASTRALKIT_TOKEN="your-api-token"
+
+# Commands automatically use the env var
+astralkit add button-sizes
+astralkit whoami
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ASTRALKIT_TOKEN` | API token for CI/CD (skips browser login) |
+| `ASTRALKIT_API_URL` | Override API base URL (development only) |
+| `ASTRALKIT_LOGIN_PORT` | Override callback port for login (default: 9876) |
+
+## Security
+
+- Authentication tokens are stored at `~/.astralkit/config.json` with `0600` permissions (owner read/write only)
+- The config directory is created with `0700` permissions
+- Browser login uses CSRF state tokens to prevent cross-site attacks
+- CORS is restricted to `astralkit.com` during authentication
+- All API requests use HTTPS with 30-second timeouts
+- No tokens, secrets, or credentials are ever hardcoded in the package
+
+## Troubleshooting
+
+### Port 9876 is in use
+
+If `astralkit login` fails because the port is busy:
+
+```bash
+# Use a different port
+ASTRALKIT_LOGIN_PORT=9877 astralkit login
+```
+
+### Token expired
+
+If you see "Session expired", run `astralkit login` again to get a fresh token.
+
+### Network errors
+
+If you see timeout or connection errors, check your internet connection. The CLI requires access to `astralkit.com`.
+
+## Requirements
+
+- Node.js 18+
+- An AstralKit account for premium components
+
+## Links
+
+- [AstralKit](https://astralkit.com)
+- [Documentation](https://astralkit.com/docs)
+- [Pricing](https://astralkit.com/pricing)

package/bin/index.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+
+const pkg = require(path.join(__dirname, '..', 'package.json'));
+
+const { initCommand } = require('../src/commands/init');
+const { addCommand } = require('../src/commands/add');
+const { loginCommand } = require('../src/commands/login');
+const { listCommand } = require('../src/commands/list');
+const { searchCommand } = require('../src/commands/search');
+const { diffCommand } = require('../src/commands/diff');
+const { updateCommand } = require('../src/commands/update');
+
+const program = new Command();
+
+program
+  .name('astralkit')
+  .description('AstralKit CLI — Install and manage UI components')
+  .version(pkg.version);
+
+// ─── init ────────────────────────────────────────────
+program
+  .command('init')
+  .description('Initialize AstralKit in your project')
+  .option('--framework <framework>', 'Framework to use (auto-detected if omitted)')
+  .option('--dir <directory>', 'Component output directory', 'src/components/ui')
+  .action(initCommand);
+
+// ─── add ─────────────────────────────────────────────
+program
+  .command('add <component>')
+  .description('Add a component to your project')
+  .option('-f, --framework <framework>', 'Framework version (html, react, vue, nextjs)')
+  .option('--dir <directory>', 'Override output directory')
+  .option('--overwrite', 'Overwrite existing files', false)
+  .action(addCommand);
+
+// ─── login ───────────────────────────────────────────
+program
+  .command('login')
+  .description('Authenticate with AstralKit for premium components')
+  .action(loginCommand);
+
+// ─── logout ──────────────────────────────────────────
+program
+  .command('logout')
+  .description('Remove stored authentication')
+  .action(async () => {
+    const { clearToken } = require('../src/lib/auth');
+    clearToken();
+    console.log(chalk.green('Logged out successfully.'));
+  });
+
+// ─── list ────────────────────────────────────────────
+program
+  .command('list')
+  .description('List available components')
+  .option('-c, --category <category>', 'Filter by category')
+  .option('--framework <framework>', 'Filter by supported framework')
+  .option('--pro', 'Show only pro components', false)
+  .option('--free', 'Show only free components', false)
+  .action(listCommand);
+
+// ─── search ──────────────────────────────────────────
+program
+  .command('search <query>')
+  .description('Search for components')
+  .option('--framework <framework>', 'Filter by supported framework')
+  .action(searchCommand);
+
+// ─── diff ────────────────────────────────────────────
+program
+  .command('diff <component>')
+  .description('Show differences between local and remote component')
+  .option('-f, --framework <framework>', 'Framework version')
+  .option('--dir <directory>', 'Override component directory')
+  .action(diffCommand);
+
+// ─── update ──────────────────────────────────────────
+program
+  .command('update <component>')
+  .description('Update a component to the latest version')
+  .option('-f, --framework <framework>', 'Framework version')
+  .option('--dir <directory>', 'Override component directory')
+  .option('--force', 'Skip confirmation prompt', false)
+  .action(updateCommand);
+
+// ─── whoami ──────────────────────────────────────────
+program
+  .command('whoami')
+  .description('Show current authentication status and subscription plan')
+  .action(async () => {
+    const { getAuth } = require('../src/lib/auth');
+    const ora = require('ora');
+
+    const auth = getAuth();
+
+    if (!auth.token) {
+      if (auth.expired) {
+        console.log(chalk.yellow('Session expired.'));
+        console.log(chalk.gray('Run'), chalk.cyan('astralkit login'), chalk.gray('to re-authenticate.'));
+      } else {
+        console.log(chalk.yellow('Not authenticated.'));
+        console.log(chalk.gray('Run'), chalk.cyan('astralkit login'), chalk.gray('to authenticate.'));
+      }
+      return;
+    }
+
+    // Verify with server
+    const spinner = ora('Verifying authentication...').start();
+    try {
+      const { verifyAuth } = require('../src/lib/api');
+      const data = await verifyAuth();
+      spinner.stop();
+
+      console.log(chalk.green('Authenticated as:'), data.email || 'unknown');
+      console.log(chalk.gray('Plan:'), data.plan || 'free');
+      if (auth.source === 'env') {
+        console.log(chalk.gray('Source: ASTRALKIT_TOKEN environment variable'));
+      }
+    } catch (err) {
+      spinner.stop();
+
+      if (err.code === 'AUTH_REQUIRED') {
+        console.log(chalk.yellow('Token is invalid or expired.'));
+        console.log(chalk.gray('Run'), chalk.cyan('astralkit login'), chalk.gray('to re-authenticate.'));
+      } else {
+        // Offline fallback — show cached info
+        console.log(chalk.green('Authenticated as:'), auth.email || 'unknown');
+        console.log(chalk.gray('Plan:'), auth.plan || 'unknown', chalk.gray('(cached — unable to verify)'));
+      }
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@astralkit/cli",
+  "version": "2.0.0",
+  "description": "AstralKit CLI — Install and manage UI components in your project",
+  "license": "MIT",
+  "bin": {
+    "astralkit": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "prepublishOnly": "node -e \"require('./package.json')\""
+  },
+  "keywords": [
+    "astralkit",
+    "ui",
+    "components",
+    "tailwind",
+    "cli",
+    "react",
+    "nextjs",
+    "vue",
+    "svelte"
+  ],
+  "homepage": "https://astralkit.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/efpacc/Astral-new.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/efpacc/Astral-new/issues"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^4.1.2",
+    "ora": "^5.4.1",
+    "inquirer": "^8.2.6",
+    "open": "^8.4.2"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const { getComponent } = require('../lib/api');
+const { getProjectConfig, detectFramework } = require('../lib/config');
+const { validateSlug, validateFramework, isSafePath } = require('../lib/validators');
+
+async function addCommand(componentSlug, options) {
+  // Validate inputs
+  if (!validateSlug(componentSlug)) process.exit(1);
+  if (!validateFramework(options.framework)) process.exit(1);
+
+  // Resolve framework
+  const config = getProjectConfig();
+  const framework = options.framework || config?.framework || detectFramework();
+  const componentsDir = options.dir || config?.componentsDir || 'src/components/ui';
+  const targetDir = path.resolve(process.cwd(), componentsDir, componentSlug);
+
+  // Check for existing files
+  if (fs.existsSync(targetDir) && !options.overwrite) {
+    console.log(chalk.yellow(`Component already exists at ${componentsDir}/${componentSlug}/`));
+    console.log(chalk.gray('Use --overwrite to replace existing files.'));
+    return;
+  }
+
+  const spinner = ora(`Fetching ${componentSlug} (${framework})...`).start();
+
+  try {
+    const data = await getComponent(componentSlug, framework);
+
+    if (!data.files || data.files.length === 0) {
+      spinner.fail(`No ${framework} code available for "${componentSlug}".`);
+      if (data.supported_frameworks?.length) {
+        console.log(chalk.gray(`Available frameworks: ${data.supported_frameworks.join(', ')}`));
+      }
+      return;
+    }
+
+    // Create component directory
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    // Write each file (with path traversal protection)
+    for (const file of data.files) {
+      if (!isSafePath(targetDir, file.path)) {
+        console.log(chalk.red(`  Skipping suspicious file path: ${file.path}`));
+        continue;
+      }
+      const filePath = path.resolve(targetDir, file.path);
+      const fileDir = path.dirname(filePath);
+      if (!fs.existsSync(fileDir)) {
+        fs.mkdirSync(fileDir, { recursive: true });
+      }
+      fs.writeFileSync(filePath, file.content);
+    }
+
+    spinner.succeed(`Added ${chalk.cyan(data.name || componentSlug)} (${framework})`);
+
+    // Show files written
+    console.log(chalk.gray(`  ${componentsDir}/${componentSlug}/`));
+    for (const file of data.files) {
+      console.log(chalk.gray(`    ${file.path}`));
+    }
+
+    // Show dependencies to install
+    if (data.dependencies?.length) {
+      console.log();
+      console.log(chalk.yellow('Install required dependencies:'));
+      console.log(chalk.cyan(`  npm install ${data.dependencies.join(' ')}`));
+    }
+
+    // Pro badge
+    if (data.is_pro) {
+      console.log();
+      console.log(chalk.magenta('Pro component — thank you for your subscription!'));
+    }
+
+  } catch (err) {
+    spinner.fail('Failed to add component.');
+
+    if (err.code === 'AUTH_REQUIRED') {
+      console.log(chalk.yellow(err.message));
+    } else if (err.code === 'PRO_REQUIRED') {
+      console.log(chalk.yellow(err.message));
+    } else {
+      // Try to parse API error for framework suggestions
+      try {
+        const body = JSON.parse(err.message.replace(/^API error \d+: /, ''));
+        if (body.supported_frameworks) {
+          console.log(chalk.yellow(`No ${framework} code available for "${componentSlug}".`));
+          console.log(chalk.gray(`Available frameworks: ${body.supported_frameworks.join(', ')}`));
+          console.log(chalk.gray(`Try: astralkit add ${componentSlug} --framework=${body.supported_frameworks[0]}`));
+          process.exit(1);
+        }
+      } catch {
+        // Not a JSON parse error, show raw message
+      }
+      console.error(chalk.red(err.message));
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = { addCommand };

package/src/commands/diff.js

@@ -0,0 +1,107 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const { getComponent } = require('../lib/api');
+const { getProjectConfig, detectFramework } = require('../lib/config');
+const { validateSlug, validateFramework, isSafePath } = require('../lib/validators');
+
+async function diffCommand(componentSlug, options) {
+  // Validate inputs
+  if (!validateSlug(componentSlug)) process.exit(1);
+  if (!validateFramework(options.framework)) process.exit(1);
+
+  const config = getProjectConfig();
+  const framework = options.framework || config?.framework || detectFramework();
+  const componentsDir = options.dir || config?.componentsDir || 'src/components/ui';
+  const targetDir = path.resolve(process.cwd(), componentsDir, componentSlug);
+
+  // Check if component exists locally
+  if (!fs.existsSync(targetDir)) {
+    console.log(chalk.yellow(`Component "${componentSlug}" not found locally at ${componentsDir}/${componentSlug}/`));
+    console.log(chalk.gray('Nothing to diff.'));
+    return;
+  }
+
+  const spinner = ora(`Fetching latest ${componentSlug} (${framework})...`).start();
+
+  try {
+    const data = await getComponent(componentSlug, framework);
+
+    if (!data.files || data.files.length === 0) {
+      spinner.fail(`No ${framework} code available for "${componentSlug}" on remote.`);
+      return;
+    }
+
+    spinner.stop();
+
+    console.log(chalk.blue.bold(`Diff: ${componentSlug} (${framework})`));
+    console.log();
+
+    let hasChanges = false;
+
+    for (const remoteFile of data.files) {
+      // Path traversal protection
+      if (!isSafePath(targetDir, remoteFile.path)) {
+        console.log(chalk.red(`  Skipping suspicious file path: ${remoteFile.path}`));
+        continue;
+      }
+
+      const localPath = path.resolve(targetDir, remoteFile.path);
+
+      if (!fs.existsSync(localPath)) {
+        console.log(chalk.green(`+ ${remoteFile.path}`), chalk.gray('(new file on remote)'));
+        hasChanges = true;
+        continue;
+      }
+
+      const localContent = fs.readFileSync(localPath, 'utf8');
+      const remoteContent = remoteFile.content;
+
+      if (localContent === remoteContent) {
+        console.log(chalk.gray(`  ${remoteFile.path}`), chalk.green('(up to date)'));
+      } else {
+        hasChanges = true;
+        console.log(chalk.yellow(`~ ${remoteFile.path}`), chalk.yellow('(modified)'));
+
+        // Show simple line count diff
+        const localLines = localContent.split('\n').length;
+        const remoteLines = remoteContent.split('\n').length;
+        const diff = remoteLines - localLines;
+        if (diff > 0) {
+          console.log(chalk.gray(`    Remote has ${diff} more line(s)`));
+        } else if (diff < 0) {
+          console.log(chalk.gray(`    Local has ${Math.abs(diff)} more line(s)`));
+        } else {
+          console.log(chalk.gray(`    Same line count, content differs`));
+        }
+      }
+    }
+
+    // Check for local files not on remote
+    if (fs.existsSync(targetDir)) {
+      const localFiles = fs.readdirSync(targetDir);
+      const remoteFilenames = new Set(data.files.map(f => f.path));
+      for (const localFile of localFiles) {
+        if (!remoteFilenames.has(localFile)) {
+          console.log(chalk.red(`- ${localFile}`), chalk.gray('(local only, not on remote)'));
+          hasChanges = true;
+        }
+      }
+    }
+
+    console.log();
+    if (hasChanges) {
+      console.log(chalk.yellow('Changes detected.'));
+      console.log(chalk.gray(`Run ${chalk.cyan(`astralkit update ${componentSlug}`)} to update.`));
+    } else {
+      console.log(chalk.green('All files are up to date.'));
+    }
+  } catch (err) {
+    spinner.fail('Diff failed.');
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
+module.exports = { diffCommand };