@fragments-sdk/cli 0.13.0 → 0.14.0

package/src/bin.ts

@@ -40,7 +40,7 @@ import { perf } from './commands/perf.js';
 import { doctor } from './commands/doctor.js';
 import { setup } from './commands/setup.js';
 import { sync } from './commands/sync.js';
-import { governCheck, governInit, governReport } from './commands/govern.js';
+import { governCheck, governInit, governReport, governConnect } from './commands/govern.js';
 
 // Import existing commands that were already extracted
 import { runScreenshotCommand } from './screenshot.js';
@@ -828,6 +828,11 @@ program
   .description('Initialize fragments in a project (zero-config by default)')
   .option('--force', 'Overwrite existing config')
   .option('-y, --yes', 'Non-interactive mode (now the default)')
+  .option('--cloud', 'Set up Fragments Cloud governance (zero-config browser auth)')
+  .option('--cloud-url <url>', 'Cloud dashboard URL (default: https://app.usefragments.com)')
+  .option('--port <port>', 'Localhost port for auth callback (default: 9876)')
+  .option('--auth-only', 'Only authenticate, skip project setup')
+  .option('--skip-check', 'Skip running the first governance check')
   .option('--configure', 'Interactive mode for theme seeds, snapshots, etc.')
   .option('--scan <path>', 'Scan a TypeScript component directory and generate fragment files')
   .option('--enrich', 'Use AI to fill knowledge fields during --scan (requires API key)')
@@ -837,6 +842,18 @@ program
   .option('--model <model>', 'Override AI model for enrichment')
   .action(async (options) => {
     try {
+      // Cloud init — separate flow
+      if (options.cloud) {
+        const { initCloud } = await import('./commands/init-cloud.js');
+        await initCloud({
+          url: options.cloudUrl,
+          port: options.port ? Number(options.port) : undefined,
+          authOnly: options.authOnly,
+          skipCheck: options.skipCheck,
+        });
+        return;
+      }
+
       const { init } = await import('./commands/init.js');
       const result = await init({
         projectRoot: process.cwd(),
@@ -1147,8 +1164,8 @@ governCmd
 
 governCmd
   .command('init')
-  .description('Generate a govern.config.ts template')
-  .option('-o, --output <path>', 'Output path', 'govern.config.ts')
+  .description('Generate a fragments.config.ts with govern section')
+  .option('-o, --output <path>', 'Output path', 'fragments.config.ts')
   .action(async (options) => {
     try {
       await governInit({ output: options.output });
@@ -1170,5 +1187,17 @@ governCmd
     }
   });
 
+governCmd
+  .command('connect')
+  .description('Connect your project to the Fragments Govern cloud dashboard')
+  .action(async () => {
+    try {
+      await governConnect();
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // Parse command line arguments
 program.parse();

package/src/commands/govern.ts

@@ -65,13 +65,170 @@ export async function governInit(options: GovernInitOptions = {}): Promise<void>
   const { resolve } = await import('node:path');
   const { generateConfigTemplate } = await import('@fragments-sdk/govern');
 
-  const outputPath = resolve(options.output ?? 'govern.config.ts');
+  const outputPath = resolve(options.output ?? 'fragments.config.ts');
   const template = generateConfigTemplate();
 
   await writeFile(outputPath, template, 'utf-8');
   console.log(pc.green(`✓ Created ${outputPath}\n`));
 }
 
+// ---------------------------------------------------------------------------
+// connect
+// ---------------------------------------------------------------------------
+
+export async function governConnect(): Promise<void> {
+  const { readFile, writeFile, appendFile } = await import('node:fs/promises');
+  const { existsSync } = await import('node:fs');
+  const { resolve } = await import('node:path');
+  const { platform } = await import('node:os');
+  const { exec } = await import('node:child_process');
+  const { password, confirm } = await import('@inquirer/prompts');
+
+  const cloudUrl = process.env.FRAGMENTS_URL ?? 'https://app.usefragments.com';
+
+  console.log(pc.cyan(`\n  ${BRAND.name} — Connect to Cloud\n`));
+  console.log(
+    pc.dim('  This will connect your project to the Fragments dashboard\n') +
+    pc.dim('  for centralized audit tracking and team visibility.\n'),
+  );
+
+  // ── Step 1: Get API key ──────────────────────────────────────────────────
+  console.log(pc.bold('  Step 1 of 3: Get your API key\n'));
+
+  const dashboardUrl = `${cloudUrl}/dashboard/settings`;
+  console.log(pc.dim(`  → Opening the dashboard in your browser...`));
+  console.log(pc.dim(`    Copy your API key from Settings → API Keys\n`));
+
+  // Open browser (best-effort)
+  const os = platform();
+  const openCmd = os === 'darwin'
+    ? `open "${dashboardUrl}"`
+    : os === 'win32'
+      ? `start "" "${dashboardUrl}"`
+      : `xdg-open "${dashboardUrl}"`;
+  exec(openCmd);
+
+  let apiKey: string;
+  let orgName: string;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    apiKey = await password({
+      message: 'Paste your API key:',
+      mask: '*',
+    });
+
+    if (!apiKey.trim()) {
+      console.log(pc.yellow('\n  API key cannot be empty. Please try again.\n'));
+      continue;
+    }
+
+    // Verify key against cloud
+    console.log(pc.dim('\n  Verifying...'));
+    try {
+      const response = await fetch(`${cloudUrl}/api/verify`, {
+        headers: { Authorization: `Bearer ${apiKey.trim()}` },
+      });
+
+      if (!response.ok) {
+        console.log(pc.red(`\n  ✗ Invalid API key (HTTP ${response.status}). Please try again.\n`));
+        continue;
+      }
+
+      const data = (await response.json()) as { valid: boolean; orgName?: string };
+      if (!data.valid) {
+        console.log(pc.red('\n  ✗ API key not recognized. Please try again.\n'));
+        continue;
+      }
+
+      orgName = data.orgName ?? 'your organization';
+      console.log(pc.green(`\n  ✓ Connected to "${orgName}" (verified)\n`));
+      break;
+    } catch (error) {
+      console.log(
+        pc.red('\n  ✗ Could not reach the dashboard.'),
+      );
+      console.log(
+        pc.dim(`    ${error instanceof Error ? error.message : 'Network error'}\n`),
+      );
+      continue;
+    }
+  }
+
+  // ── Step 2: Save configuration ──────────────────────────────────────────
+  console.log(pc.bold('  Step 2 of 3: Save configuration\n'));
+
+  const saveToEnv = await confirm({
+    message: 'Save API key to .env file?',
+    default: true,
+  });
+
+  if (saveToEnv) {
+    const envPath = resolve('.env');
+    const envEntry = `FRAGMENTS_API_KEY=${apiKey.trim()}`;
+
+    if (existsSync(envPath)) {
+      const envContent = await readFile(envPath, 'utf-8');
+      if (envContent.includes('FRAGMENTS_API_KEY=')) {
+        // Replace existing entry
+        const updated = envContent.replace(
+          /^FRAGMENTS_API_KEY=.*$/m,
+          envEntry,
+        );
+        await writeFile(envPath, updated, 'utf-8');
+        console.log(pc.green('  ✓ Updated FRAGMENTS_API_KEY in .env'));
+      } else {
+        await appendFile(envPath, `\n${envEntry}\n`, 'utf-8');
+        console.log(pc.green('  ✓ Added FRAGMENTS_API_KEY to .env'));
+      }
+    } else {
+      await writeFile(envPath, `${envEntry}\n`, 'utf-8');
+      console.log(pc.green('  ✓ Created .env with FRAGMENTS_API_KEY'));
+    }
+
+    // Write FRAGMENTS_URL only if non-default
+    if (cloudUrl !== 'https://app.usefragments.com') {
+      const envContent = await readFile(envPath, 'utf-8');
+      if (!envContent.includes('FRAGMENTS_URL=')) {
+        await appendFile(envPath, `FRAGMENTS_URL=${cloudUrl}\n`, 'utf-8');
+        console.log(pc.green(`  ✓ Added FRAGMENTS_URL to .env`));
+      }
+    }
+
+    // Ensure .env is in .gitignore
+    const gitignorePath = resolve('.gitignore');
+    if (existsSync(gitignorePath)) {
+      const gitignore = await readFile(gitignorePath, 'utf-8');
+      if (!gitignore.split('\n').some((line) => line.trim() === '.env')) {
+        await appendFile(gitignorePath, '\n.env\n', 'utf-8');
+        console.log(pc.green('  ✓ Added .env to .gitignore'));
+      }
+    } else {
+      await writeFile(gitignorePath, '.env\n', 'utf-8');
+      console.log(pc.green('  ✓ Created .gitignore with .env entry'));
+    }
+  }
+
+  // ── Step 3: Config check ────────────────────────────────────────────────
+  console.log(pc.bold('\n  Step 3 of 3: Config check\n'));
+
+  const { findGovernConfig } = await import('@fragments-sdk/govern');
+  const configPath = findGovernConfig();
+
+  if (configPath) {
+    console.log(pc.green(`  ✓ Found govern config: ${configPath}`));
+  } else {
+    console.log(
+      pc.yellow('  No govern config found — run `fragments govern init` to create one'),
+    );
+  }
+
+  // ── Done ────────────────────────────────────────────────────────────────
+  console.log(pc.dim('\n  ─────────────────────────────────────\n'));
+  console.log(pc.green('  ✓ All set!') + ' Run `fragments govern check` to send your first audit.\n');
+  console.log(pc.dim(`  Dashboard: ${cloudUrl}/dashboard\n`));
+}
+
 // ---------------------------------------------------------------------------
 // report
 // ---------------------------------------------------------------------------

package/src/commands/init-cloud.ts

@@ -0,0 +1,354 @@
+/**
+ * fragments init --cloud
+ *
+ * Zero-config cloud setup: opens browser for auth, receives API key
+ * via localhost callback, detects project, installs deps, creates config,
+ * runs first check.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { execSync, exec } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { platform } from 'node:os';
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface AuthResult {
+  apiKey: string;
+  orgName: string;
+}
+
+export interface InitCloudOptions {
+  /** Cloud dashboard URL */
+  url?: string;
+  /** Port for localhost callback server */
+  port?: number;
+  /** Timeout in ms for auth */
+  timeout?: number;
+  /** Skip project detection and setup */
+  authOnly?: boolean;
+  /** Skip the first governance check */
+  skipCheck?: boolean;
+}
+
+// ─── Utilities ──────────────────────────────────────────────────────────────
+
+function detectPackageManager(): 'pnpm' | 'yarn' | 'bun' | 'npm' {
+  // Check current dir and parent dirs (for monorepos)
+  let dir = process.cwd();
+  const root = resolve('/');
+  while (dir !== root) {
+    if (existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock'))) return 'bun';
+    if (existsSync(join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (existsSync(join(dir, 'yarn.lock'))) return 'yarn';
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return 'npm';
+}
+
+function detectFramework(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve('package.json'), 'utf-8'));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (allDeps['next']) return 'Next.js';
+    if (allDeps['nuxt']) return 'Nuxt';
+    if (allDeps['@sveltejs/kit']) return 'SvelteKit';
+    if (allDeps['svelte']) return 'Svelte';
+    if (allDeps['vue']) return 'Vue';
+    if (allDeps['astro']) return 'Astro';
+    if (allDeps['react']) return 'React';
+    return 'Unknown';
+  } catch {
+    return 'Unknown';
+  }
+}
+
+function inferInputGlob(framework: string): string | string[] {
+  switch (framework) {
+    case 'Next.js':
+      return ['./app/**/*.{tsx,jsx}', './components/**/*.{tsx,jsx}'];
+    case 'Nuxt':
+    case 'Vue':
+      return ['./**/*.vue'];
+    case 'SvelteKit':
+    case 'Svelte':
+      return ['./src/**/*.svelte'];
+    case 'Astro':
+      return ['./src/**/*.{astro,tsx,jsx}'];
+    default:
+      return './src/**/*.{tsx,jsx}';
+  }
+}
+
+function openBrowser(url: string): void {
+  const os = platform();
+  const cmd =
+    os === 'darwin' ? 'open' :
+    os === 'win32' ? 'start ""' :
+    'xdg-open';
+
+  exec(`${cmd} "${url}"`);
+}
+
+function installCommand(pm: string): string {
+  switch (pm) {
+    case 'pnpm': return 'pnpm add';
+    case 'yarn': return 'yarn add';
+    case 'bun': return 'bun add';
+    default: return 'npm install';
+  }
+}
+
+function isMonorepoWorkspaceDep(): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve('package.json'), 'utf-8'));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return (
+      allDeps['@fragments-sdk/govern']?.startsWith('workspace:') ||
+      allDeps['@fragments-sdk/cli']?.startsWith('workspace:')
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ─── Localhost Auth Server ──────────────────────────────────────────────────
+
+function waitForAuth(
+  cloudUrl: string,
+  port: number,
+  timeoutMs: number,
+): Promise<AuthResult> {
+  const nonce = randomBytes(16).toString('hex');
+
+  return new Promise<AuthResult>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error('Authentication timed out. Please try again.'));
+    }, timeoutMs);
+
+    const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url!, `http://localhost:${port}`);
+
+      if (url.pathname === '/callback') {
+        const key = url.searchParams.get('key');
+        const org = url.searchParams.get('org');
+        const returnedNonce = url.searchParams.get('nonce');
+
+        if (returnedNonce !== nonce) {
+          res.writeHead(400, { 'Content-Type': 'text/plain' });
+          res.end('Nonce mismatch — please try again.');
+          return;
+        }
+
+        if (!key) {
+          res.writeHead(400, { 'Content-Type': 'text/plain' });
+          res.end('Missing API key in callback.');
+          return;
+        }
+
+        // Show "you can close this tab" page
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(`<!DOCTYPE html>
+<html><head><title>Fragments CLI</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#0a0a0f;color:#e5e5e5}
+.box{text-align:center;padding:48px}.check{font-size:48px;margin-bottom:16px}p{color:#888;margin-top:8px}</style>
+</head><body><div class="box"><div class="check">&#10003;</div><h2>CLI Authorized</h2><p>You can close this tab and return to your terminal.</p></div>
+<script>setTimeout(()=>window.close(),3000)</script>
+</body></html>`);
+
+        clearTimeout(timeout);
+        server.close();
+        resolve({ apiKey: key, orgName: org ?? 'your organization' });
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    server.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE') {
+        clearTimeout(timeout);
+        reject(new Error(`Port ${port} is in use. Try: fragments init --cloud --port ${port + 1}`));
+      } else {
+        clearTimeout(timeout);
+        reject(err);
+      }
+    });
+
+    server.listen(port, '127.0.0.1', () => {
+      const authUrl = `${cloudUrl}/cli-auth?port=${port}&nonce=${nonce}`;
+      openBrowser(authUrl);
+    });
+  });
+}
+
+// ─── Save to .env ───────────────────────────────────────────────────────────
+
+function saveApiKey(apiKey: string, cloudUrl: string): void {
+  const envPath = resolve('.env');
+  const entry = `FRAGMENTS_API_KEY=${apiKey}`;
+
+  if (existsSync(envPath)) {
+    const content = readFileSync(envPath, 'utf-8');
+    if (content.includes('FRAGMENTS_API_KEY=')) {
+      const updated = content.replace(/^FRAGMENTS_API_KEY=.*$/m, entry);
+      writeFileSync(envPath, updated, 'utf-8');
+    } else {
+      appendFileSync(envPath, `\n${entry}\n`, 'utf-8');
+    }
+  } else {
+    writeFileSync(envPath, `${entry}\n`, 'utf-8');
+  }
+
+  // Add FRAGMENTS_URL if non-default
+  if (cloudUrl !== 'https://app.usefragments.com') {
+    const content = readFileSync(envPath, 'utf-8');
+    if (!content.includes('FRAGMENTS_URL=')) {
+      appendFileSync(envPath, `FRAGMENTS_URL=${cloudUrl}\n`, 'utf-8');
+    }
+  }
+
+  // Ensure .env is in .gitignore
+  const gitignorePath = resolve('.gitignore');
+  if (existsSync(gitignorePath)) {
+    const gitignore = readFileSync(gitignorePath, 'utf-8');
+    if (!gitignore.split('\n').some((line) => line.trim() === '.env')) {
+      appendFileSync(gitignorePath, '\n.env\n', 'utf-8');
+    }
+  } else {
+    writeFileSync(gitignorePath, '.env\n', 'utf-8');
+  }
+}
+
+// ─── Write governance config ────────────────────────────────────────────────
+
+function writeGovernConfig(input: string | string[]): void {
+  const configPath = resolve(BRAND.configFile);
+  if (existsSync(configPath)) return; // Don't overwrite
+
+  const inputStr = Array.isArray(input)
+    ? `[${input.map((p) => `'${p}'`).join(', ')}]`
+    : `'${input}'`;
+
+  const template = `import { defineConfig } from '@fragments-sdk/govern';
+
+export default defineConfig({
+  cloud: true,
+  checks: ['accessibility', 'consistency', 'responsive'],
+  input: ${inputStr},
+});
+`;
+
+  writeFileSync(configPath, template, 'utf-8');
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+export async function initCloud(options: InitCloudOptions = {}): Promise<void> {
+  const cloudUrl = options.url ?? process.env.FRAGMENTS_URL ?? 'https://app.usefragments.com';
+  const port = options.port ?? 9876;
+  const timeoutMs = options.timeout ?? 120_000;
+
+  console.log(pc.bold(`\n  ${BRAND.name}\n`));
+
+  // ── 1. Detect project ─────────────────────────────────────────────
+  if (!options.authOnly) {
+    if (!existsSync(resolve('package.json'))) {
+      console.log(pc.red('  No package.json found. Run this from a project directory.\n'));
+      process.exit(1);
+    }
+
+    const pm = detectPackageManager();
+    const framework = detectFramework();
+    console.log(pc.dim(`  Project: ${framework}`));
+    console.log(pc.dim(`  Package manager: ${pm}\n`));
+  }
+
+  // ── 2. Authenticate ───────────────────────────────────────────────
+  console.log(pc.dim('  Opening browser to sign in...\n'));
+
+  let auth: AuthResult;
+  try {
+    auth = await waitForAuth(cloudUrl, port, timeoutMs);
+  } catch (err) {
+    console.log(pc.red(`\n  ${err instanceof Error ? err.message : 'Auth failed'}\n`));
+    process.exit(1);
+  }
+
+  console.log(pc.green(`  ✓ Authenticated — ${auth.orgName}\n`));
+
+  // ── 3. Save API key ──────────────────────────────────────────────
+  saveApiKey(auth.apiKey, cloudUrl);
+  console.log(pc.green('  ✓ API key saved to .env'));
+
+  if (options.authOnly) {
+    console.log(pc.green('\n  ✓ All set!\n'));
+    console.log(pc.dim(`  Dashboard: ${cloudUrl}\n`));
+    return;
+  }
+
+  // ── 4. Install dependencies ───────────────────────────────────────
+  const pm = detectPackageManager();
+
+  if (!isMonorepoWorkspaceDep()) {
+    const deps = '@fragments-sdk/govern @fragments-sdk/cli';
+    console.log(pc.dim(`\n  Installing ${deps}...`));
+    try {
+      execSync(`${installCommand(pm)} ${deps}`, {
+        stdio: 'pipe',
+        cwd: process.cwd(),
+      });
+      console.log(pc.green('  ✓ Dependencies installed'));
+    } catch (err) {
+      console.log(pc.yellow('  ⚠ Install failed — you may need to install manually:'));
+      console.log(pc.dim(`    ${installCommand(pm)} ${deps}\n`));
+    }
+  } else {
+    console.log(pc.dim('\n  Workspace deps detected — skipping install'));
+  }
+
+  // ── 5. Create governance config ───────────────────────────────────
+  const framework = detectFramework();
+  const input = inferInputGlob(framework);
+  const configPath = resolve(BRAND.configFile);
+
+  if (existsSync(configPath)) {
+    console.log(pc.dim(`  Config already exists: ${BRAND.configFile}`));
+  } else {
+    writeGovernConfig(input);
+    console.log(pc.green(`  ✓ Created ${BRAND.configFile}`));
+  }
+
+  // ── 6. Run first check ────────────────────────────────────────────
+  if (!options.skipCheck) {
+    console.log(pc.dim('\n  Running first governance check...\n'));
+    try {
+      const output = execSync('npx fragments govern check --cloud', {
+        stdio: 'pipe',
+        cwd: process.cwd(),
+        env: { ...process.env, FRAGMENTS_API_KEY: auth.apiKey },
+      });
+      console.log(output.toString());
+    } catch (err: any) {
+      // Check may "fail" with violations — that's OK
+      if (err.stdout) {
+        console.log(err.stdout.toString());
+      }
+      console.log(pc.dim('  (check completed with violations — see dashboard for details)'));
+    }
+  }
+
+  // ── 7. Done ───────────────────────────────────────────────────────
+  console.log(pc.green('\n  ✓ All set!') + ' Your project is connected to Fragments Cloud.\n');
+  console.log(pc.dim(`  Dashboard: ${cloudUrl}`));
+  console.log(pc.dim('  Run checks: fragments govern check --cloud'));
+  console.log(pc.dim('  View config: fragments.config.ts\n'));
+}