@fragments-sdk/cli 0.2.2

package/src/commands/init.ts

@@ -0,0 +1,531 @@
+/**
+ * fragments init - Smart interactive initialization
+ *
+ * Handles three scenarios:
+ * 1. Stories found → Configure and load existing stories
+ * 2. Components found (no stories) → Auto-generate documentation
+ * 3. Fresh project → Guided setup with example component
+ */
+
+import { readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { resolve, join, relative } from "node:path";
+import { spawn } from "node:child_process";
+import pc from "picocolors";
+import { BRAND } from "../core/index.js";
+import fg from "fast-glob";
+import { input, confirm, select } from "@inquirer/prompts";
+
+export interface InitOptions {
+  /** Project root directory */
+  projectRoot?: string;
+  /** Force overwrite existing config */
+  force?: boolean;
+  /** Non-interactive mode - auto-detect and use defaults */
+  yes?: boolean;
+}
+
+export interface InitResult {
+  success: boolean;
+  configPath?: string;
+  scenario: "stories" | "components" | "fresh";
+  storiesFound: number;
+  componentsFound: number;
+  errors: string[];
+}
+
+interface DetectionResult {
+  storyFiles: string[];
+  componentFiles: string[];
+  hasConfig: boolean;
+  configPath: string | null;
+  suggestedComponentPath: string;
+}
+
+/**
+ * Detect what exists in the project
+ */
+async function detectProject(projectRoot: string): Promise<DetectionResult> {
+  console.log(pc.dim("\nScanning project...\n"));
+
+  // Check for existing config
+  const configPath = join(projectRoot, BRAND.configFile);
+  const legacyConfigPath = join(projectRoot, BRAND.legacyConfigFile);
+  let hasConfig = false;
+  let foundConfigPath: string | null = null;
+
+  try {
+    await access(configPath);
+    hasConfig = true;
+    foundConfigPath = configPath;
+  } catch {
+    try {
+      await access(legacyConfigPath);
+      hasConfig = true;
+      foundConfigPath = legacyConfigPath;
+    } catch {
+      // No config
+    }
+  }
+
+  // Scan for story files
+  const storyFiles = await fg(
+    ["**/*.stories.tsx", "**/*.stories.ts", "**/*.stories.jsx", "**/*.stories.js"],
+    {
+      cwd: projectRoot,
+      ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.storybook/**"],
+    }
+  );
+
+  // Scan for component files (React components)
+  const componentFiles = await fg(
+    ["**/components/**/*.tsx", "**/Components/**/*.tsx", "src/**/*.tsx"],
+    {
+      cwd: projectRoot,
+      ignore: [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/*.stories.*",
+        "**/*.test.*",
+        "**/*.spec.*",
+        "**/*.d.ts",
+        "**/index.tsx", // Skip barrel files
+      ],
+    }
+  );
+
+  // Filter to likely component files (capitalized names, not utility files)
+  const likelyComponents = componentFiles.filter((f) => {
+    const fileName = f.split("/").pop() || "";
+    return /^[A-Z]/.test(fileName) && !fileName.includes(".styles");
+  });
+
+  // Suggest component path based on what we found
+  let suggestedComponentPath = "src/components";
+  if (likelyComponents.length > 0) {
+    const firstComponent = likelyComponents[0];
+    const parts = firstComponent.split("/");
+    const componentsIndex = parts.findIndex(
+      (p) => p.toLowerCase() === "components"
+    );
+    if (componentsIndex !== -1) {
+      suggestedComponentPath = parts.slice(0, componentsIndex + 1).join("/");
+    }
+  }
+
+  return {
+    storyFiles,
+    componentFiles: likelyComponents,
+    hasConfig,
+    configPath: foundConfigPath,
+    suggestedComponentPath,
+  };
+}
+
+/**
+ * Generate config file content
+ */
+function generateConfig(options: {
+  includePaths: string[];
+  componentPaths: string[];
+  framework: string;
+}): string {
+  const includeStr = options.includePaths.map((p) => `    '${p}'`).join(",\n");
+  const componentStr = options.componentPaths.map((p) => `    '${p}'`).join(",\n");
+
+  return `import type { FragmentsConfig } from '@fragments/core';
+
+const config: FragmentsConfig = {
+  // Glob patterns for finding fragment/story files
+  include: [
+${includeStr}
+  ],
+
+  // Glob patterns to exclude
+  exclude: ['**/node_modules/**'],
+
+  // Glob patterns for finding component files (for auto-documentation)
+  components: [
+${componentStr}
+  ],
+
+  // Framework (react, vue, svelte)
+  framework: '${options.framework}',
+};
+
+export default config;
+`;
+}
+
+/**
+ * Generate example Button component
+ */
+function generateExampleComponent(): string {
+  return `import React from 'react';
+
+export interface ButtonProps {
+  /** Button label */
+  children: React.ReactNode;
+  /** Visual style variant */
+  variant?: 'primary' | 'secondary' | 'ghost';
+  /** Button size */
+  size?: 'sm' | 'md' | 'lg';
+  /** Disabled state */
+  disabled?: boolean;
+  /** Click handler */
+  onClick?: () => void;
+}
+
+export function Button({
+  children,
+  variant = 'primary',
+  size = 'md',
+  disabled = false,
+  onClick,
+}: ButtonProps) {
+  const baseStyles = 'inline-flex items-center justify-center font-medium rounded-md transition-colors';
+
+  const variantStyles = {
+    primary: 'bg-blue-600 text-white hover:bg-blue-700',
+    secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
+    ghost: 'bg-transparent text-gray-700 hover:bg-gray-100',
+  };
+
+  const sizeStyles = {
+    sm: 'px-3 py-1.5 text-sm',
+    md: 'px-4 py-2 text-base',
+    lg: 'px-6 py-3 text-lg',
+  };
+
+  return (
+    <button
+      className={\`\${baseStyles} \${variantStyles[variant]} \${sizeStyles[size]}\`}
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+`;
+}
+
+/**
+ * Generate example Button fragment file
+ */
+function generateExampleFragment(): string {
+  return `import React from 'react';
+import { defineFragment } from '@fragments/core';
+import { Button } from './Button';
+
+export default defineFragment({
+  component: Button,
+
+  meta: {
+    name: 'Button',
+    description: 'Interactive button for triggering actions',
+    category: 'Actions',
+    status: 'stable',
+  },
+
+  usage: {
+    when: [
+      'Triggering an action (save, submit, delete)',
+      'Form submission',
+      'Opening dialogs or menus',
+    ],
+    whenNot: [
+      'Simple navigation (use Link)',
+      'Toggling state (use Switch)',
+    ],
+    guidelines: [
+      'Use Primary for the main action in a context',
+      'Only one Primary button per section',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      required: true,
+      description: 'Button label content',
+    },
+    variant: {
+      type: 'enum',
+      values: ['primary', 'secondary', 'ghost'],
+      default: 'primary',
+      description: 'Visual style variant',
+    },
+    size: {
+      type: 'enum',
+      values: ['sm', 'md', 'lg'],
+      default: 'md',
+      description: 'Button size',
+    },
+  },
+
+  variants: [
+    {
+      name: 'Primary',
+      description: 'Default action button',
+      render: () => <Button variant="primary">Save Changes</Button>,
+    },
+    {
+      name: 'Secondary',
+      description: 'Less prominent action',
+      render: () => <Button variant="secondary">Cancel</Button>,
+    },
+    {
+      name: 'Ghost',
+      description: 'Minimal visual weight',
+      render: () => <Button variant="ghost">Learn More</Button>,
+    },
+    {
+      name: 'Sizes',
+      description: 'Available size options',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+          <Button size="sm">Small</Button>
+          <Button size="md">Medium</Button>
+          <Button size="lg">Large</Button>
+        </div>
+      ),
+    },
+  ],
+});
+`;
+}
+
+/**
+ * Start the dev server
+ */
+function startDevServer(projectRoot: string): void {
+  console.log(pc.dim("\nStarting development server...\n"));
+
+  // Use process.platform to determine the correct command
+  const isWindows = process.platform === "win32";
+  const cmd = isWindows ? "npx.cmd" : "npx";
+
+  const child = spawn(cmd, [BRAND.cliCommand, "dev"], {
+    cwd: projectRoot,
+    stdio: "inherit",
+  });
+
+  child.on("error", (err) => {
+    console.error(pc.red("Failed to start dev server:"), err.message);
+  });
+}
+
+/**
+ * Main init function - smart and interactive by default
+ */
+export async function init(options: InitOptions = {}): Promise<InitResult> {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const errors: string[] = [];
+
+  console.log(pc.cyan(`\n✨ Welcome to ${BRAND.name}!\n`));
+
+  // Step 1: Detect what exists
+  const detection = await detectProject(projectRoot);
+
+  // Check for existing config
+  if (detection.hasConfig && !options.force) {
+    console.log(pc.yellow(`⚠ Config already exists: ${BRAND.configFile}`));
+
+    if (!options.yes) {
+      const overwrite = await confirm({
+        message: "Do you want to reinitialize? (This will overwrite your config)",
+        default: false,
+      });
+
+      if (!overwrite) {
+        console.log(pc.dim(`\nKeeping existing configuration. Run \`${BRAND.cliCommand} dev\` to start.\n`));
+        return {
+          success: true,
+          scenario: "stories",
+          storiesFound: detection.storyFiles.length,
+          componentsFound: detection.componentFiles.length,
+          errors: [],
+        };
+      }
+    }
+  }
+
+  // Step 2: Determine scenario and show what we found
+  let scenario: "stories" | "components" | "fresh";
+
+  if (detection.storyFiles.length > 0) {
+    scenario = "stories";
+    console.log(pc.green(`✓ Found ${detection.storyFiles.length} Storybook story file(s)`));
+    console.log(pc.dim(`  ${detection.storyFiles.slice(0, 3).join("\n  ")}`));
+    if (detection.storyFiles.length > 3) {
+      console.log(pc.dim(`  ... and ${detection.storyFiles.length - 3} more`));
+    }
+    console.log();
+    console.log(
+      pc.cyan("Great news! ") +
+        "Fragments can load your existing stories automatically."
+    );
+  } else if (detection.componentFiles.length > 0) {
+    scenario = "components";
+    console.log(pc.green(`✓ Found ${detection.componentFiles.length} component file(s)`));
+    console.log(pc.dim(`  ${detection.componentFiles.slice(0, 3).join("\n  ")}`));
+    if (detection.componentFiles.length > 3) {
+      console.log(pc.dim(`  ... and ${detection.componentFiles.length - 3} more`));
+    }
+    console.log();
+    console.log(
+      pc.cyan("No stories found, but that's fine! ") +
+        "Fragments can auto-generate documentation from your TypeScript."
+    );
+  } else {
+    scenario = "fresh";
+    console.log(pc.yellow("No components or stories found."));
+    console.log();
+    console.log(pc.cyan("Let's create your first fragment!"));
+  }
+
+  console.log();
+
+  // Step 3: Gather configuration (interactive unless --yes)
+  let componentPath = detection.suggestedComponentPath;
+  let runScan = scenario === "components";
+  let createExample = scenario === "fresh";
+  let startServer = true;
+
+  if (!options.yes) {
+    // Ask about component location
+    componentPath = await input({
+      message: "Where are your components located?",
+      default: detection.suggestedComponentPath,
+    });
+
+    if (scenario === "components") {
+      // For component-only projects, ask about scanning
+      runScan = await confirm({
+        message: "Auto-generate documentation from TypeScript?",
+        default: true,
+      });
+    } else {
+      // Fresh project - ask about example
+      createExample = await confirm({
+        message: "Create an example Button component to get started?",
+        default: true,
+      });
+    }
+
+    // Ask about starting the server
+    startServer = await confirm({
+      message: "Start the viewer now?",
+      default: true,
+    });
+  }
+
+  // Step 4: Create configuration
+  console.log(pc.dim("\nCreating configuration...\n"));
+
+  // Build include patterns
+  // Note: Stories are loaded separately by the viewer, not via include patterns
+  const includePaths: string[] = [
+    `${componentPath}/**/*.fragment.tsx`,
+    `${componentPath}/**/*.segment.tsx`, // Legacy support
+  ];
+
+  // Create config file
+  const configPath = join(projectRoot, BRAND.configFile);
+  const configContent = generateConfig({
+    includePaths,
+    componentPaths: [`${componentPath}/**/*.tsx`],
+    framework: "react",
+  });
+
+  try {
+    await writeFile(configPath, configContent, "utf-8");
+    console.log(pc.green(`✓ Created ${BRAND.configFile}`));
+  } catch (e) {
+    errors.push(`Failed to create config: ${e}`);
+  }
+
+  // Step 5: Handle scenario-specific setup
+  if (scenario === "fresh" && createExample) {
+    // Create example component
+    const exampleDir = join(projectRoot, componentPath, "Button");
+
+    try {
+      await mkdir(exampleDir, { recursive: true });
+
+      // Write Button.tsx
+      await writeFile(
+        join(exampleDir, "Button.tsx"),
+        generateExampleComponent(),
+        "utf-8"
+      );
+      console.log(
+        pc.green(`✓ Created ${relative(projectRoot, join(exampleDir, "Button.tsx"))}`)
+      );
+
+      // Write Button.fragment.tsx
+      await writeFile(
+        join(exampleDir, "Button.fragment.tsx"),
+        generateExampleFragment(),
+        "utf-8"
+      );
+      console.log(
+        pc.green(
+          `✓ Created ${relative(projectRoot, join(exampleDir, "Button.fragment.tsx"))}`
+        )
+      );
+    } catch (e) {
+      errors.push(`Failed to create example component: ${e}`);
+    }
+  }
+
+  if (scenario === "components" && runScan) {
+    // Run scan to generate fragments.json
+    console.log(pc.dim("\nGenerating documentation from source code...\n"));
+    try {
+      const { scan } = await import("./scan.js");
+      await scan({
+        config: configPath,
+        verbose: false,
+      });
+    } catch (e) {
+      console.log(
+        pc.yellow(`Note: Auto-documentation will run when you start the dev server.`)
+      );
+    }
+  }
+
+  // Step 6: Show next steps or start server
+  if (errors.length === 0) {
+    console.log(pc.green("\n✓ Setup complete!\n"));
+
+    if (startServer) {
+      const serverMessage =
+        scenario === "stories"
+          ? `Your ${detection.storyFiles.length} stories are loading...`
+          : scenario === "components"
+          ? `Your ${detection.componentFiles.length} components are being documented...`
+          : `Your first component is ready!`;
+
+      console.log(pc.cyan(serverMessage));
+      startDevServer(projectRoot);
+    } else {
+      console.log(pc.cyan("Next steps:"));
+      console.log(`  1. Run ${pc.bold(`${BRAND.cliCommand} dev`)} to start the viewer`);
+      if (scenario === "fresh") {
+        console.log(`  2. Edit ${pc.bold(`${componentPath}/Button/Button.fragment.tsx`)}`);
+      }
+      console.log();
+    }
+  }
+
+  return {
+    success: errors.length === 0,
+    configPath: errors.length === 0 ? configPath : undefined,
+    scenario,
+    storiesFound: detection.storyFiles.length,
+    componentsFound: detection.componentFiles.length,
+    errors,
+  };
+}