@loracle-js/cli 1.0.2

package/README.md

@@ -0,0 +1,69 @@
+# Loracle CLI
+
+Publishes your Storybook to Loracle so your AI tools always have up-to-date component context.
+
+<a href="https://www.npmjs.com/package/@loracle-js/cli">
+  <img src="https://badgen.net/npm/v/@loracle-js/cli" alt="Published on npm">
+</a>
+
+## Documentation
+
+👉 Read the [Loracle CLI docs](https://getloracle.com/docs/cli)
+
+## Requirements
+
+- Node.js 18+
+- Storybook 7+
+- A Loracle API key — get one at [getloracle.com](https://getloracle.com)
+
+## Usage
+
+```sh
+npx @loracle-js/cli publish <storybook-url> --version <semver>
+```
+
+**Example:**
+
+```sh
+LORACLE_API_KEY=your_api_key npx @loracle-js/cli publish https://storybook.example.com --version 1.2.0
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `-v, --version` | Semantic version for this build (required) |
+| `--dry-run` | Validate without uploading |
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `LORACLE_API_KEY` | Your Loracle API key (required) |
+
+## CI
+
+### GitHub Actions
+
+```yaml
+- name: Install Playwright browsers
+  run: npx playwright install chromium --with-deps
+
+- name: Publish to Loracle
+  run: npx @loracle-js/cli publish ${{ vars.STORYBOOK_URL }} --version ${{ github.ref_name }}
+  env:
+    LORACLE_API_KEY: ${{ secrets.LORACLE_API_KEY }}
+```
+
+### GitHub Actions (official Playwright image)
+
+```yaml
+container:
+  image: mcr.microsoft.com/playwright:latest
+
+steps:
+  - name: Publish to Loracle
+    run: npx @loracle-js/cli publish ${{ vars.STORYBOOK_URL }} --version ${{ github.ref_name }}
+    env:
+      LORACLE_API_KEY: ${{ secrets.LORACLE_API_KEY }}
+```

package/dist/bin/loracle.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { publish } from '../publish.js';
+import * as dotenv from 'dotenv';
+dotenv.config();
+const program = new Command();
+program
+    .name('loracle')
+    .description('Loracle CLI - Publish your design system to Loracle')
+    .version('1.0.0', '-V, --cli-version', 'output the CLI version');
+program
+    .command('publish')
+    .description('Scrape and publish Storybook components to Loracle')
+    .argument('<url>', 'Storybook URL to publish')
+    .requiredOption('-v, --version <version>', 'Semantic version for this build (e.g., 1.0.0)')
+    .option('--dry-run', 'Scrape and validate without uploading')
+    .action(async (url, options) => {
+    await publish({
+        url,
+        version: options.version,
+        dryRun: options.dryRun,
+    });
+});
+program.parse();

package/dist/publish.js

@@ -0,0 +1,162 @@
+import { StorybookScraper } from './scraper.js';
+import { initBuild, uploadToS3 } from './uploader.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { intro, outro, cancel, error, success, createSpinner, link, ErrorMessages } from './ui.js';
+// Semver validation (from Portal API)
+const semverRegex = /^\d+\.\d+\.\d+(-[\w.-]+)?(\+[\w.-]+)?$/;
+const API_URL = 'https://getloracle.com';
+export async function publish(options) {
+    const { url, version } = options;
+    const startTime = Date.now();
+    // Step 1: Validate API key (skip for dry-run)
+    const apiKey = options.apiKey || process.env.LORACLE_API_KEY;
+    if (!apiKey && !options.dryRun) {
+        error(ErrorMessages.missingApiKey.title, ErrorMessages.missingApiKey.details);
+        cancel('Missing API key');
+        process.exit(1);
+    }
+    // Step 2: Validate version format
+    if (!semverRegex.test(version)) {
+        const err = ErrorMessages.invalidVersion(version);
+        error(err.title, err.details);
+        cancel('Invalid version');
+        process.exit(1);
+    }
+    // Show intro
+    const dryRunLabel = options.dryRun ? ' (dry run)' : '';
+    intro('publish', `v${version}${dryRunLabel}`);
+    // Step 3: Connect to Storybook
+    const connectSpinner = createSpinner();
+    connectSpinner.start('Connecting to Storybook...');
+    let componentCount = 0;
+    try {
+        const baseUrl = url.endsWith('/') ? url : url + '/';
+        const indexUrl = baseUrl + 'index.json';
+        const response = await fetch(indexUrl, { signal: AbortSignal.timeout(10000) });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const indexData = await response.json();
+        // Count unique components (group by component path)
+        const components = new Set();
+        if (indexData.entries) {
+            for (const entry of Object.values(indexData.entries)) {
+                const e = entry;
+                if (e.type === 'docs' || e.type === 'story') {
+                    if (e.title) {
+                        components.add(e.title);
+                    }
+                }
+            }
+        }
+        componentCount = components.size;
+        connectSpinner.stop(`Connected · ${componentCount} components found`);
+    }
+    catch (_error) {
+        connectSpinner.error('Could not connect to Storybook');
+        const err = ErrorMessages.connectionFailed(url);
+        error(err.title, err.details);
+        cancel('Connection failed');
+        process.exit(1);
+    }
+    // Step 4: Scrape components
+    const extractSpinner = createSpinner();
+    extractSpinner.start('Extracting components...');
+    // Create temp directory for output
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'loracle-'));
+    const outputDir = path.join(tempDir, 'output');
+    const componentsDir = path.join(outputDir, 'components');
+    await fs.mkdir(componentsDir, { recursive: true });
+    await fs.mkdir(path.join(outputDir, 'screenshots'), { recursive: true });
+    let scrapedComponents = [];
+    try {
+        const scraper = new StorybookScraper({
+            url,
+            outputDir,
+            headless: true,
+            verbose: false,
+            onProgress: (event) => {
+                switch (event.type) {
+                    case 'component_start':
+                        extractSpinner.message(`Extracting · ${event.name}`);
+                        break;
+                    case 'component_done':
+                        extractSpinner.message(`Extracting · ${event.current}/${event.total}`);
+                        break;
+                }
+            },
+        });
+        scrapedComponents = await scraper.scrape();
+        extractSpinner.stop(`Extracted ${scrapedComponents.length} components`);
+    }
+    catch (err) {
+        extractSpinner.error('Extraction failed');
+        error('Extraction failed', [err instanceof Error ? err.message : String(err)]);
+        cancel('Extraction failed');
+        await fs.rm(tempDir, { recursive: true, force: true });
+        process.exit(1);
+    }
+    // Step 5: Bundle and upload
+    const uploadSpinner = createSpinner();
+    uploadSpinner.start(options.dryRun ? 'Bundling components...' : 'Uploading to Loracle...');
+    try {
+        // Build bundle directly from scraped data
+        const bundle = { version, components: scrapedComponents };
+        const uploadedCount = bundle.components.length;
+        // Count variations
+        let variationCount = 0;
+        for (const component of bundle.components) {
+            variationCount += component.examples?.length || 0;
+        }
+        // Dry-run: skip upload, show summary
+        if (options.dryRun) {
+            uploadSpinner.stop('Dry run complete');
+            await fs.rm(tempDir, { recursive: true, force: true });
+            success('Dry run passed', [
+                `${uploadedCount} components · ${variationCount} variations`,
+                'Ready to publish \u2014 remove --dry-run to upload.'
+            ]);
+            outro(startTime);
+            return;
+        }
+        // Initialize build
+        const { buildId, uploadUrl, projectId } = await initBuild(API_URL, apiKey, version, uploadedCount);
+        // Complete bundle with build metadata
+        const fullBundle = {
+            buildId,
+            projectId,
+            version,
+            components: bundle.components,
+        };
+        // Upload to S3
+        await uploadToS3(uploadUrl, fullBundle);
+        uploadSpinner.stop('Upload complete');
+        // Cleanup temp directory
+        await fs.rm(tempDir, { recursive: true, force: true });
+        // Show success
+        const trackingLink = link('Track progress', `https://getloracle.com/projects/${projectId}`);
+        success('Build submitted', [
+            `${uploadedCount} components · ${variationCount} variations`,
+            trackingLink
+        ]);
+        outro(startTime);
+    }
+    catch (err) {
+        uploadSpinner.error(options.dryRun ? 'Dry run failed' : 'Upload failed');
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        if (errorMessage.includes('Insufficient credits')) {
+            error(ErrorMessages.insufficientCredits.title, ErrorMessages.insufficientCredits.details);
+        }
+        else if (errorMessage.includes('401') || errorMessage.includes('Unauthorized')) {
+            error(ErrorMessages.invalidApiKey.title, ErrorMessages.invalidApiKey.details);
+        }
+        else {
+            error(options.dryRun ? 'Dry run failed' : 'Upload failed', [errorMessage]);
+        }
+        cancel('Failed');
+        await fs.rm(tempDir, { recursive: true, force: true });
+        process.exit(1);
+    }
+}

package/dist/scraper.js

@@ -0,0 +1,688 @@
+import { chromium } from 'playwright';
+import { promises as fs } from 'fs';
+import path from 'path';
+import pLimit from 'p-limit';
+export class StorybookScraper {
+    constructor(options) {
+        this.browser = null;
+        this.context = null;
+        this.processedComponents = new Set();
+        this.cachedIndexData = null;
+        this.options = options;
+        this.concurrency = options.concurrency ?? 8;
+    }
+    emit(event) {
+        if (this.options.onProgress) {
+            // Skip debug/warn events unless verbose
+            if ((event.type === 'debug' || event.type === 'warn') && !this.options.verbose)
+                return;
+            this.options.onProgress(event);
+        }
+    }
+    async scrape() {
+        const results = [];
+        try {
+            await this.initialize();
+            this.emit({ type: 'debug', message: 'Discovering component documentation pages from index.json...' });
+            const storyInfos = await this.discoverStoryPages();
+            const isStoryMode = storyInfos.length > 0 && storyInfos[0].viewMode === 'story';
+            const uniqueComponents = new Set(storyInfos.map(s => s.kind)).size;
+            this.emit({ type: 'discovery', total: isStoryMode ? uniqueComponents : storyInfos.length });
+            if (isStoryMode) {
+                this.emit({ type: 'debug', message: `Found ${storyInfos.length} stories across ${uniqueComponents} components (story-only mode)` });
+            }
+            else {
+                this.emit({ type: 'debug', message: `Found ${storyInfos.length} potential pages to process` });
+            }
+            this.emit({ type: 'debug', message: `Running with ${this.concurrency} parallel workers` });
+            let processedCount = 0;
+            let successCount = 0;
+            const totalCount = storyInfos.length;
+            // Create a limiter for parallel processing
+            const limit = pLimit(this.concurrency);
+            if (isStoryMode) {
+                // Story-only mode: scrape each story individually, then group by component
+                const storyResults = new Map();
+                const tasks = storyInfos.map((storyInfo) => limit(async () => {
+                    const page = await this.context.newPage();
+                    page.setDefaultTimeout(15000);
+                    try {
+                        const example = await this.scrapeStoryPage(storyInfo, page);
+                        if (example) {
+                            // Group into component
+                            const existing = storyResults.get(storyInfo.kind);
+                            if (existing && existing.examples) {
+                                existing.examples.push(example);
+                            }
+                            else {
+                                storyResults.set(storyInfo.kind, {
+                                    name: storyInfo.kind.split('/').pop()?.trim() || storyInfo.kind,
+                                    componentName: storyInfo.kind.split('/').pop()?.trim() || storyInfo.kind,
+                                    examples: [example],
+                                    metadata: { storyId: storyInfo.storyId, framework: 'react', kind: storyInfo.kind },
+                                });
+                            }
+                            successCount++;
+                        }
+                    }
+                    catch (error) {
+                        this.emit({ type: 'debug', message: `Failed to process ${storyInfo.storyId}: ${error}` });
+                    }
+                    finally {
+                        await page.close();
+                    }
+                    processedCount++;
+                    this.emit({ type: 'component_done', current: processedCount, total: totalCount, success: true });
+                }));
+                await Promise.all(tasks);
+                // Save grouped components
+                for (const componentData of storyResults.values()) {
+                    await this.saveComponent(componentData);
+                    results.push(componentData);
+                }
+            }
+            else {
+                // Docs mode: one page per component (original behavior)
+                const tasks = storyInfos.map((storyInfo) => limit(async () => {
+                    this.emit({ type: 'component_start', name: storyInfo.kind });
+                    const page = await this.context.newPage();
+                    page.setDefaultTimeout(15000);
+                    let success = false;
+                    try {
+                        const componentData = await this.scrapeComponentWithPage(storyInfo, page);
+                        if (componentData) {
+                            await this.saveComponent(componentData);
+                            results.push(componentData);
+                            successCount++;
+                            success = true;
+                        }
+                    }
+                    catch (error) {
+                        this.emit({ type: 'debug', message: `Failed to process ${storyInfo.kind}: ${error}` });
+                    }
+                    finally {
+                        await page.close();
+                    }
+                    processedCount++;
+                    this.emit({ type: 'component_done', current: processedCount, total: totalCount, success });
+                }));
+                await Promise.all(tasks);
+            }
+            const savedComponents = isStoryMode ? new Set(storyInfos.map(s => s.kind)).size : successCount;
+            this.emit({ type: 'complete', successCount: savedComponents, totalCount: successCount });
+        }
+        finally {
+            await this.cleanup();
+        }
+        return results;
+    }
+    async initialize() {
+        this.emit({ type: 'browser_launch' });
+        this.browser = await chromium.launch({
+            headless: this.options.headless,
+            args: ['--no-sandbox', '--disable-dev-shm-usage']
+        });
+        this.context = await this.browser.newContext();
+        // Ensure output directories exist (once, not per-component)
+        const componentsDir = path.join(this.options.outputDir, 'components');
+        const screenshotsDir = path.join(this.options.outputDir, 'screenshots');
+        await fs.mkdir(componentsDir, { recursive: true });
+        await fs.mkdir(screenshotsDir, { recursive: true });
+    }
+    async fetchIndexJson() {
+        // Return cached data if available
+        if (this.cachedIndexData)
+            return this.cachedIndexData;
+        try {
+            const baseUrl = this.options.url.endsWith('/') ? this.options.url : this.options.url + '/';
+            const indexUrl = baseUrl + 'index.json';
+            this.emit({ type: 'debug', message: `Fetching index from: ${indexUrl}` });
+            const response = await fetch(indexUrl);
+            if (!response.ok) {
+                this.emit({ type: 'warn', message: `Failed to fetch index.json (${response.status}). Falling back to DOM navigation.` });
+                return null;
+            }
+            const data = await response.json();
+            if (!data.entries || typeof data.entries !== 'object') {
+                this.emit({ type: 'warn', message: 'Invalid index.json structure. Falling back to DOM navigation.' });
+                return null;
+            }
+            this.cachedIndexData = data;
+            return data;
+        }
+        catch (error) {
+            this.emit({ type: 'warn', message: `Error fetching index.json: ${error.message}. Falling back to DOM navigation.` });
+            return null;
+        }
+    }
+    async discoverStoryPagesFromIndex() {
+        const indexData = await this.fetchIndexJson();
+        if (!indexData) {
+            // Fallback to DOM navigation
+            return this.discoverStoryPagesFromDOM();
+        }
+        const storyInfos = [];
+        const baseUrl = this.options.url.endsWith('/') ? this.options.url : this.options.url + '/';
+        // Filter for docs pages with actual stories
+        for (const [id, entry] of Object.entries(indexData.entries)) {
+            if (entry.type === 'docs') {
+                // Skip pure documentation pages without associated stories
+                const hasNoStories = !entry.storiesImports || entry.storiesImports.length === 0;
+                const isUnattachedMdx = entry.tags?.includes('unattached-mdx');
+                if (hasNoStories && isUnattachedMdx) {
+                    this.emit({ type: 'debug', message: `Skipping documentation page: ${entry.title}` });
+                    continue;
+                }
+                // Navigate directly to iframe.html, bypassing the Storybook manager UI
+                const url = `${baseUrl}iframe.html?viewMode=docs&id=${id}`;
+                storyInfos.push({
+                    url,
+                    componentId: id,
+                    kind: entry.title,
+                    viewMode: 'docs',
+                });
+            }
+        }
+        this.emit({ type: 'debug', message: `Found ${storyInfos.length} docs pages from index.json` });
+        // Fallback: if no docs entries found, emit one StoryInfo per individual story
+        if (storyInfos.length === 0) {
+            this.emit({ type: 'debug', message: 'No docs entries found, falling back to story-only mode' });
+            for (const [id, entry] of Object.entries(indexData.entries)) {
+                if (entry.type === 'story') {
+                    storyInfos.push({
+                        url: `${baseUrl}iframe.html?viewMode=story&id=${id}`,
+                        componentId: entry.title.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+                        kind: entry.title,
+                        viewMode: 'story',
+                        storyId: id,
+                        storyName: entry.name,
+                    });
+                }
+            }
+            this.emit({ type: 'debug', message: `Found ${storyInfos.length} stories across ${new Set(storyInfos.map(s => s.kind)).size} components` });
+        }
+        // Filter by kinds if specified
+        if (this.options.kinds && this.options.kinds.length > 0) {
+            return storyInfos.filter(story => this.options.kinds.some(kind => story.kind.includes(kind)));
+        }
+        return storyInfos;
+    }
+    async discoverStoryPages() {
+        // Try index.json first
+        return this.discoverStoryPagesFromIndex();
+    }
+    async discoverStoryPagesFromDOM() {
+        const page = await this.context.newPage();
+        try {
+            await page.goto(this.options.url);
+            // Wait for Storybook to load
+            await page.waitForSelector('nav', { timeout: 10000 });
+            this.emit({ type: 'debug', message: 'Expanding sidebar sections...' });
+            await this.expandAllSections(page);
+            this.emit({ type: 'debug', message: 'Collecting component links...' });
+            const storyInfos = await this.collectComponentLinks(page);
+            // Filter by kinds if specified
+            if (this.options.kinds && this.options.kinds.length > 0) {
+                return storyInfos.filter(story => this.options.kinds.some(kind => story.kind.includes(kind)));
+            }
+            return storyInfos;
+        }
+        finally {
+            await page.close();
+        }
+    }
+    async expandAllSections(page) {
+        // Iteratively expand sections until no more can be expanded
+        let previousCount = 0;
+        let currentCount = 0;
+        let attempts = 0;
+        const maxAttempts = 10; // Prevent infinite loops
+        do {
+            previousCount = currentCount;
+            // Find all currently collapsed buttons
+            const collapsedButtons = await page.locator('nav button[aria-expanded="false"]').all();
+            currentCount = collapsedButtons.length;
+            this.emit({ type: 'debug', message: `Found ${currentCount} collapsed sections to expand` });
+            // Try to expand each collapsed button
+            for (let i = 0; i < collapsedButtons.length; i++) {
+                try {
+                    // Re-query the button to avoid stale element issues
+                    const button = page.locator('nav button[aria-expanded="false"]').nth(i);
+                    // Check if button is still available and visible
+                    if (await button.count() > 0 && await button.isVisible()) {
+                        await button.click({ timeout: 1000 });
+                        await page.waitForTimeout(200); // Allow time for expansion
+                    }
+                }
+                catch (error) {
+                    // Silently continue - button might have disappeared or become unclickable
+                    this.emit({ type: 'debug', message: `Could not expand button ${i}: ${error.message}` });
+                }
+            }
+            attempts++;
+            // Small delay before checking again
+            await page.waitForTimeout(300);
+        } while (attempts < maxAttempts && currentCount > 0 && currentCount !== previousCount);
+        this.emit({ type: 'debug', message: `Expansion completed after ${attempts} attempts` });
+    }
+    async collectComponentLinks(page) {
+        // Find all links in the navigation that point to docs pages
+        const links = await page.locator('nav a[href*="/docs/"]').all();
+        const storyInfos = [];
+        const baseUrl = this.options.url.endsWith('/') ? this.options.url : this.options.url + '/';
+        for (const link of links) {
+            try {
+                const href = await link.getAttribute('href');
+                const text = await link.textContent();
+                if (href && text && href.includes('--docs')) {
+                    // Extract kind from the URL pattern
+                    const kindMatch = href.match(/\/docs\/(.+)--docs/);
+                    if (kindMatch) {
+                        const componentId = kindMatch[1];
+                        const kind = text.trim();
+                        // Use direct iframe URL
+                        storyInfos.push({
+                            url: `${baseUrl}iframe.html?viewMode=docs&id=${componentId}--docs`,
+                            componentId,
+                            kind,
+                            viewMode: 'docs',
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                // Ignore errors for individual links
+                this.emit({ type: 'debug', message: `Could not process link: ${error}` });
+            }
+        }
+        this.emit({ type: 'debug', message: `Found ${storyInfos.length} component documentation links` });
+        return storyInfos;
+    }
+    async scrapeComponentWithPage(storyInfo, page) {
+        // Skip if already processed (thread-safe check)
+        if (this.processedComponents.has(storyInfo.componentId)) {
+            return null;
+        }
+        // Mark as processing to avoid duplicates in parallel execution
+        this.processedComponents.add(storyInfo.componentId);
+        // Navigate directly to iframe.html — no manager UI, no nested iframe
+        await page.goto(storyInfo.url, { waitUntil: 'load' });
+        try {
+            // Wait for Storybook preview to be ready with at least one story render
+            await page.waitForFunction(() => {
+                const preview = window.__STORYBOOK_PREVIEW__;
+                if (!preview?.currentSelection?.viewMode)
+                    return false;
+                if (!preview.storyRenders)
+                    return false;
+                const renders = Object.values(preview.storyRenders);
+                return renders.some((r) => r?.story);
+            }, { timeout: 15000, polling: 200 });
+            // Check if this is a docs page
+            const viewMode = await page.evaluate(() => {
+                return window.__STORYBOOK_PREVIEW__?.currentSelection.viewMode;
+            });
+            if (viewMode !== 'docs' && viewMode !== 'story') {
+                this.emit({ type: 'debug', message: `Skipping ${storyInfo.kind} - unexpected viewMode: ${viewMode}` });
+                return null;
+            }
+            this.emit({ type: 'debug', message: `Processing ${viewMode} page: ${storyInfo.kind}` });
+            // Extract component data directly from page (no iframe indirection)
+            const componentData = await this.extractComponentData(page, storyInfo);
+            return componentData;
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.emit({ type: 'debug', message: `Skipping ${storyInfo.kind}: ${errorMsg}` });
+            return null;
+        }
+    }
+    /**
+     * Story-only mode: navigate to a single story, extract data + screenshot from #storybook-root.
+     * No DOM lookups for story-- elements (they don't exist in story mode).
+     */
+    async scrapeStoryPage(storyInfo, page) {
+        await page.goto(storyInfo.url, { waitUntil: 'load' });
+        try {
+            await page.waitForFunction(() => {
+                const preview = window.__STORYBOOK_PREVIEW__;
+                if (!preview?.currentSelection?.viewMode)
+                    return false;
+                if (!preview.storyRenders)
+                    return false;
+                const renders = Object.values(preview.storyRenders);
+                return renders.some((r) => r?.story);
+            }, { timeout: 15000, polling: 200 });
+        }
+        catch {
+            this.emit({ type: 'debug', message: `Preview timeout for ${storyInfo.storyId}` });
+            return null;
+        }
+        // Extract story metadata from the preview API
+        const storyData = await page.evaluate(() => {
+            const preview = window.__STORYBOOK_PREVIEW__;
+            const storyRenders = preview?.storyRenders ? Object.values(preview.storyRenders) : [];
+            for (const render of storyRenders) {
+                const story = render?.story;
+                if (story) {
+                    return {
+                        name: story.name || 'Unknown',
+                        code: story.parameters?.docs?.source?.code ||
+                            story.parameters?.docs?.source?.originalSource ||
+                            story.parameters?.storySource?.source || '',
+                        description: story.parameters?.docs?.description?.story || '',
+                        metadata: {
+                            storyId: story.id,
+                            framework: story.parameters?.framework || 'react',
+                            kind: story.kind || story.title,
+                        },
+                    };
+                }
+            }
+            return null;
+        });
+        if (!storyData)
+            return null;
+        // Screenshot #storybook-root directly
+        let screenshot = '';
+        try {
+            const root = page.locator('#storybook-root').first();
+            const screenshotBuffer = await root.screenshot({ type: 'png', timeout: 5000 });
+            screenshot = screenshotBuffer.toString('base64');
+            // Save screenshot to file (non-blocking)
+            const screenshotPath = path.join(this.options.outputDir, 'screenshots', `${storyInfo.componentId}_${storyData.name.replace(/[^a-zA-Z0-9]/g, '_')}.png`);
+            fs.writeFile(screenshotPath, screenshotBuffer).catch(() => { });
+        }
+        catch {
+            this.emit({ type: 'warn', message: `Screenshot failed for ${storyInfo.storyId}` });
+        }
+        return {
+            name: storyData.name,
+            code: storyData.code,
+            description: storyData.description,
+            screenshot,
+            metadata: {
+                ...storyData.metadata,
+                storyId: storyInfo.storyId,
+                source: 'index.json',
+            },
+        };
+    }
+    async extractComponentData(page, storyInfo) {
+        // Execute extraction logic directly on the page (no iframe needed)
+        const extractedData = await page.evaluate(() => {
+            const preview = window.__STORYBOOK_PREVIEW__;
+            if (!preview) {
+                throw new Error('Storybook preview not available');
+            }
+            // Try to find current story from storyRenders or currentSelection
+            let currentStory;
+            // Get all story renders
+            const storyRenders = preview.storyRenders ? Object.values(preview.storyRenders) : [];
+            if (storyRenders.length > 0) {
+                // Use first story render that has a story object
+                for (const render of storyRenders) {
+                    if (render?.story) {
+                        currentStory = render.story;
+                        break;
+                    }
+                }
+            }
+            // If still no story, create minimal fallback from URL
+            if (!currentStory) {
+                const url = window.location.href;
+                const urlMatch = url.match(/id=([^&]+)/);
+                const componentId = urlMatch ? urlMatch[1] : 'unknown';
+                const titleMatch = componentId.match(/^(.+?)--/);
+                const title = titleMatch ? titleMatch[1].replace(/-/g, ' ') : componentId;
+                currentStory = {
+                    id: componentId,
+                    title: title,
+                    name: 'Default',
+                    parameters: {},
+                    argTypes: {}
+                };
+            }
+            // Extract component-level data
+            const componentName = currentStory.component?.displayName ||
+                currentStory.component?.name ||
+                currentStory.title?.split('/').pop() ||
+                'Unknown Component';
+            const description = currentStory.component?.__docgenInfo?.description ||
+                currentStory.parameters?.docs?.description?.component ||
+                '';
+            // Extract props from argTypes
+            const props = [];
+            if (currentStory.argTypes) {
+                for (const [name, argType] of Object.entries(currentStory.argTypes)) {
+                    // Transform table to match PropData structure (summary must be defined if present)
+                    const table = argType.table ? {
+                        type: argType.table.type?.summary ? { summary: argType.table.type.summary } : undefined,
+                        defaultValue: argType.table.defaultValue?.summary ? { summary: argType.table.defaultValue.summary } : undefined,
+                        category: argType.table.category
+                    } : undefined;
+                    props.push({
+                        name,
+                        description: argType.description,
+                        type: argType.table?.type?.summary ?? argType.type?.name,
+                        required: argType.type?.required,
+                        options: argType.options,
+                        defaultValue: argType.table?.defaultValue?.summary ? {
+                            value: argType.table.defaultValue.summary,
+                            computed: false
+                        } : undefined,
+                        control: argType.control,
+                        table
+                    });
+                }
+            }
+            // Extract stories from storyRenders
+            const stories = [];
+            const allRenders = preview.storyRenders ? Object.values(preview.storyRenders) : [];
+            for (let i = 0; i < allRenders.length; i++) {
+                const render = allRenders[i];
+                if (render && render.story) {
+                    const story = render.story;
+                    // Get source code if available.
+                    // Priority: `docs.source.code` (user overrides / transforms / dynamic render sources)
+                    // falls back to `docs.source.originalSource` (CSF enrichment default)
+                    // falls back to legacy `storySource.source` (addon-storysource).
+                    let code = '';
+                    if (story.parameters?.docs?.source?.code) {
+                        code = story.parameters.docs.source.code;
+                    }
+                    else if (story.parameters?.docs?.source?.originalSource) {
+                        code = story.parameters.docs.source.originalSource;
+                    }
+                    else if (story.parameters?.storySource?.source) {
+                        code = story.parameters.storySource.source;
+                    }
+                    const storyData = {
+                        name: story.name || `Story ${i + 1}`,
+                        code: code,
+                        description: story.parameters?.docs?.description?.story || '',
+                        storyIndex: i, // We'll use this to match with screenshots
+                        metadata: {
+                            storyId: story.id,
+                            framework: story.parameters?.framework || 'react',
+                            kind: story.kind || story.title
+                        }
+                    };
+                    stories.push(storyData);
+                }
+            }
+            return {
+                componentName,
+                description,
+                props,
+                stories,
+                metadata: {
+                    storyId: currentStory.id,
+                    framework: currentStory.parameters?.framework || 'react',
+                    kind: currentStory.kind || currentStory.title
+                }
+            };
+        });
+        // INDEX-GUIDED APPROACH: Use cached index.json as source of truth
+        const indexData = await this.fetchIndexJson();
+        const validStoryIds = [];
+        if (indexData) {
+            for (const [id, entry] of Object.entries(indexData.entries)) {
+                if (entry.type === 'story' && entry.title === storyInfo.kind) {
+                    validStoryIds.push(id);
+                }
+            }
+        }
+        // Fallback to DOM-first if index.json unavailable or no stories found
+        if (validStoryIds.length === 0) {
+            this.emit({ type: 'warn', message: 'No stories found in index.json, falling back to DOM-first approach' });
+            validStoryIds.push(...extractedData.stories.map(s => s.metadata?.storyId).filter(Boolean));
+        }
+        this.emit({ type: 'debug', message: `Screenshot strategy: Index-guided (${validStoryIds.length} stories from index.json)` });
+        // Capture screenshots by iterating over story IDs from index.json (source of truth)
+        const examples = [];
+        // Wait for first story element to ensure page is fully rendered before starting screenshots
+        if (validStoryIds.length > 0) {
+            const firstStoryId = validStoryIds[0];
+            await page.waitForSelector(`[id="story--${firstStoryId}"]`, { timeout: 8000 }).catch(() => {
+                this.emit({ type: 'warn', message: `First story element not found: ${firstStoryId}` });
+            });
+        }
+        for (let i = 0; i < validStoryIds.length; i++) {
+            const storyId = validStoryIds[i];
+            let screenshot = '';
+            let storyMetadata = null;
+            try {
+                // Direct page access — no iframe indirection needed
+                const storyElement = page.locator(`[id="story--${storyId}"]`).first();
+                try {
+                    await storyElement.waitFor({ state: 'visible', timeout: 3000 });
+                }
+                catch {
+                    // Element didn't become visible in time, continue anyway
+                }
+                // Check if story element exists in DOM
+                const storyElementCount = await storyElement.count().catch(() => 0);
+                if (storyElementCount === 0) {
+                    this.emit({ type: 'warn', message: `Story from index.json not found in DOM: ${storyId}` });
+                    continue;
+                }
+                // Get the .docs-story container (what we want to screenshot)
+                const docsStoryContainer = storyElement.locator('xpath=ancestor::*[contains(@class, "docs-story")]').first();
+                // Check if container exists
+                const containerCount = await docsStoryContainer.count().catch(() => 0);
+                const domElement = containerCount > 0 ? docsStoryContainer : storyElement;
+                if (containerCount === 0) {
+                    this.emit({ type: 'warn', message: `No .docs-story container found for ${storyId}, using story element directly` });
+                }
+                // Get story metadata from API (exact match guaranteed since we're using index.json IDs)
+                storyMetadata = await page.evaluate((targetStoryId) => {
+                    const preview = window.__STORYBOOK_PREVIEW__;
+                    const storyRenders = preview?.storyRenders ? Object.values(preview.storyRenders) : [];
+                    // Find the story render matching this ID
+                    for (const render of storyRenders) {
+                        if (render?.story?.id === targetStoryId) {
+                            const story = render.story;
+                            return {
+                                name: story.name || 'Unknown',
+                                code: story.parameters?.docs?.source?.code ||
+                                    story.parameters?.docs?.source?.originalSource ||
+                                    story.parameters?.storySource?.source || '',
+                                description: story.parameters?.docs?.description?.story || '',
+                                metadata: {
+                                    storyId: story.id,
+                                    framework: story.parameters?.framework || 'react',
+                                    kind: story.kind || story.title
+                                }
+                            };
+                        }
+                    }
+                    // Fallback: return minimal metadata
+                    return {
+                        name: targetStoryId.split('--').pop() || 'Unknown',
+                        code: '',
+                        description: '',
+                        metadata: {
+                            storyId: targetStoryId,
+                            framework: 'react',
+                            kind: ''
+                        }
+                    };
+                }, storyId);
+                // Take screenshot
+                const isVisible = await domElement.isVisible().catch(() => false);
+                if (!isVisible) {
+                    await domElement.scrollIntoViewIfNeeded({ timeout: 2000 }).catch(() => { });
+                }
+                const screenshotBuffer = await domElement.screenshot({
+                    type: 'png',
+                    omitBackground: false,
+                    timeout: 5000
+                });
+                screenshot = screenshotBuffer.toString('base64');
+                // Save screenshot to file (non-blocking)
+                const screenshotPath = path.join(this.options.outputDir, 'screenshots', `${storyInfo.componentId}_${storyMetadata.name.replace(/[^a-zA-Z0-9]/g, '_')}.png`);
+                fs.writeFile(screenshotPath, screenshotBuffer).catch(() => { });
+                this.emit({ type: 'debug', message: `Screenshot captured for ${storyMetadata.name} (${storyId})` });
+                examples.push({
+                    name: storyMetadata.name,
+                    code: storyMetadata.code,
+                    description: storyMetadata.description,
+                    screenshot,
+                    metadata: {
+                        ...storyMetadata.metadata,
+                        storyId: storyId,
+                        source: 'index.json'
+                    }
+                });
+            }
+            catch (screenshotError) {
+                const errorMsg = screenshotError.message;
+                if (errorMsg.includes('detached') || errorMsg.includes('Target closed')) {
+                    this.emit({ type: 'debug', message: `Screenshot skipped for ${storyId}: ${errorMsg}` });
+                }
+                else {
+                    this.emit({ type: 'warn', message: `Screenshot failed for ${storyId}: ${errorMsg}` });
+                }
+                // Still push the example with metadata even if screenshot fails
+                if (storyMetadata) {
+                    examples.push({
+                        name: storyMetadata.name,
+                        code: storyMetadata.code,
+                        description: storyMetadata.description,
+                        screenshot: '',
+                        metadata: storyMetadata.metadata
+                    });
+                }
+            }
+        }
+        // Validate we captured the expected number of stories
+        if (examples.length === validStoryIds.length) {
+            this.emit({ type: 'debug', message: `Captured all ${examples.length} stories from index.json` });
+        }
+        else {
+            this.emit({ type: 'warn', message: `Count mismatch: Expected ${validStoryIds.length} stories, captured ${examples.length}` });
+        }
+        return {
+            name: extractedData.componentName,
+            componentName: extractedData.componentName,
+            description: extractedData.description,
+            props: extractedData.props,
+            examples,
+            metadata: extractedData.metadata
+        };
+    }
+    async saveComponent(componentData) {
+        // Directories are already created in initialize()
+        const componentsDir = path.join(this.options.outputDir, 'components');
+        const filename = `${componentData.componentName || componentData.name}.json`;
+        const filepath = path.join(componentsDir, filename);
+        await fs.writeFile(filepath, JSON.stringify(componentData, null, 2));
+        this.emit({ type: 'debug', message: `Saved component data to ${filepath}` });
+    }
+    async cleanup() {
+        if (this.browser) {
+            await this.browser.close();
+        }
+    }
+}

package/dist/types.js

@@ -0,0 +1,30 @@
+// Helper function to process prop types
+export function processPropType(prop) {
+    if (prop.type?.name === "enum") {
+        return {
+            name: "enum",
+            value: prop.type.value.map((v) => 
+            // Handle both literal enum values and identifier references
+            v.value || v.name || String(v)),
+            required: !!prop.required,
+        };
+    }
+    return {
+        name: prop.type?.name || "any",
+        value: prop.type?.value,
+        required: !!prop.required,
+        defaultValue: prop.defaultValue?.value,
+    };
+}
+// Helper function to process component props into API documentation
+export function processComponentAPI(props) {
+    return {
+        props: props.map((prop) => ({
+            name: prop.name,
+            description: prop.description,
+            type: processPropType(prop),
+            required: !!prop.required,
+            defaultValue: prop.defaultValue?.value,
+        })),
+    };
+}

package/dist/ui.js

@@ -0,0 +1,68 @@
+import * as clack from '@clack/prompts';
+import terminalLink from 'terminal-link';
+export function intro(command, detail) {
+    const title = detail ? `loracle ${command} · ${detail}` : `loracle ${command}`;
+    clack.intro(title);
+}
+export function outro(startTime) {
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    clack.outro(`Done in ${elapsed}s`);
+}
+export function cancel(message) {
+    clack.cancel(message);
+}
+export function step(message) {
+    clack.log.step(message);
+}
+export function error(title, details) {
+    const lines = details ? `${title}\n${details.join('\n')}` : title;
+    clack.log.error(lines);
+}
+export function success(title, details) {
+    const lines = details ? `${title}\n${details.join('\n')}` : title;
+    clack.log.success(lines);
+}
+export function warn(message) {
+    clack.log.warn(message);
+}
+export function createSpinner() {
+    return clack.spinner({ indicator: 'dots' });
+}
+export function link(text, url) {
+    return terminalLink(text, url, { fallback: (t, u) => `${t} (${u})` });
+}
+export const ErrorMessages = {
+    missingApiKey: {
+        title: 'Missing API key',
+        details: [
+            'Set LORACLE_API_KEY environment variable.',
+            `Get your key at ${link('getloracle.com/settings/api-keys', 'https://getloracle.com/settings/api-keys')}`
+        ]
+    },
+    invalidApiKey: {
+        title: 'Invalid API key',
+        details: [
+            `Check your API key at ${link('getloracle.com/settings/api-keys', 'https://getloracle.com/settings/api-keys')}`
+        ]
+    },
+    invalidVersion: (version) => ({
+        title: `Invalid version "${version}"`,
+        details: [
+            'Use semantic versioning (e.g., 1.0.0, 2.1.0-beta.1)'
+        ]
+    }),
+    connectionFailed: (url) => ({
+        title: 'Could not connect to Storybook',
+        details: [
+            'Make sure:',
+            `  - Storybook is running at ${url}`,
+            '  - The URL is accessible from this machine'
+        ]
+    }),
+    insufficientCredits: {
+        title: 'Insufficient credits',
+        details: [
+            `Add credits at ${link('getloracle.com/billing', 'https://getloracle.com/billing')}`
+        ]
+    }
+};

package/dist/uploader.js

@@ -0,0 +1,92 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+/**
+ * Bundle all component JSON files into a single payload
+ */
+export async function bundleComponents(componentsDir, version) {
+    const files = await fs.readdir(componentsDir);
+    const jsonFiles = files.filter(f => f.endsWith('.json'));
+    const components = [];
+    for (const file of jsonFiles) {
+        const filePath = path.join(componentsDir, file);
+        const content = await fs.readFile(filePath, 'utf-8');
+        const component = JSON.parse(content);
+        components.push(component);
+    }
+    return {
+        version,
+        components,
+    };
+}
+/**
+ * Initialize a build via the API
+ */
+export async function initBuild(apiUrl, apiKey, version, componentCount) {
+    const response = await fetch(`${apiUrl}/trpc/builds.initBuild`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+            'X-Loracle-Client': 'cli/0.1.0',
+        },
+        body: JSON.stringify({ version, componentCount }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        // Check for 402-style insufficient credits error
+        try {
+            const errorData = JSON.parse(text);
+            if (errorData.error?.data?.cause?.code === 'INSUFFICIENT_CREDITS') {
+                const cause = errorData.error.data.cause;
+                throw new Error(`Insufficient credits: need ${cause.required}, have ${cause.available}. ` +
+                    `Buy more at ${cause.billingUrl}`);
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.includes('Insufficient credits'))
+                throw e;
+        }
+        throw new Error(`API request failed (${response.status}): ${text}`);
+    }
+    const data = await response.json();
+    if (data.error) {
+        throw new Error(`API error: ${data.error.message}`);
+    }
+    const result = data.result.data;
+    return result;
+}
+/**
+ * Upload bundle to S3 using presigned URL
+ */
+export async function uploadToS3(uploadUrl, bundle) {
+    const response = await fetch(uploadUrl, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(bundle),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`S3 upload failed (${response.status}): ${text}`);
+    }
+}
+/**
+ * Main upload flow
+ */
+export async function uploadComponents(options) {
+    const { componentsDir, version, apiUrl, apiKey } = options;
+    // 1. Bundle components first to get count
+    const partialBundle = await bundleComponents(componentsDir, version);
+    const componentCount = partialBundle.components.length;
+    // 2. Initialize build with component count (triggers credit check)
+    const { buildId, uploadUrl, projectId } = await initBuild(apiUrl, apiKey, version, componentCount);
+    // 3. Complete bundle with buildId and projectId
+    const bundle = {
+        buildId,
+        projectId,
+        ...partialBundle,
+    };
+    // 4. Upload to S3
+    await uploadToS3(uploadUrl, bundle);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@loracle-js/cli",
+  "version": "1.0.2",
+  "description": "Loracle CLI - Publish your design system to Loracle",
+  "author": "Loracle <team@getloracle.com>",
+  "license": "Apache-2.0",
+  "homepage": "https://getloracle.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/getloracle/loracle.git",
+    "directory": "packages/storybook-scraper-v2"
+  },
+  "bugs": {
+    "url": "https://github.com/getloracle/loracle/issues"
+  },
+  "type": "module",
+  "bin": {
+    "loracle": "./dist/bin/loracle.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "tsx src/bin/loracle.ts",
+    "build": "tsc"
+  },
+  "keywords": [
+    "storybook",
+    "loracle",
+    "design-system",
+    "llm",
+    "cli"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "commander": "^12.0.0",
+    "dotenv": "^16.6.1",
+    "p-limit": "^7.1.1",
+    "playwright": "^1.47.0",
+    "terminal-link": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}