@reshotdev/screenshot 0.0.1-beta.0

package/src/commands/setup-wizard.js

@@ -0,0 +1,740 @@
+// setup-wizard.js - Comprehensive interactive setup wizard
+// Consolidates the initial setup flow: auth + init + feature configuration
+// Individual commands (auth, init) still exist for power users
+
+const inquirer = require("inquirer");
+const chalk = require("chalk");
+const fs = require("fs-extra");
+const path = require("path");
+const config = require("../lib/config");
+const {
+  validateStorageConfig,
+  getStorageSetupHelp,
+} = require("../lib/storage-providers");
+
+/**
+ * Auto-detect documentation directories
+ */
+function detectDocumentationRoot() {
+  const commonPaths = [
+    "docs",
+    "documentation",
+    "content",
+    "doc",
+    "guides",
+    ".vitepress/content",
+    ".docusaurus/docs",
+  ];
+
+  for (const dir of commonPaths) {
+    const fullPath = path.join(process.cwd(), dir);
+    if (fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory()) {
+      const files = fs.readdirSync(fullPath);
+      if (files.some((f) => f.endsWith(".md") || f.endsWith(".mdx"))) {
+        return dir;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect if this is a Git repository and if it's GitHub
+ */
+function detectGitInfo() {
+  const isGitRepo = fs.existsSync(path.join(process.cwd(), ".git"));
+  let isGitHub = false;
+  let remoteUrl = null;
+
+  if (isGitRepo) {
+    try {
+      const { execSync } = require("child_process");
+      remoteUrl = execSync("git remote get-url origin", {
+        encoding: "utf-8",
+      }).trim();
+      isGitHub = remoteUrl.includes("github.com");
+    } catch {
+      // No remote configured
+    }
+  }
+
+  return { isGitRepo, isGitHub, remoteUrl };
+}
+
+/**
+ * Detect Playwright configuration
+ */
+function detectPlaywright() {
+  const configFiles = [
+    "playwright.config.ts",
+    "playwright.config.js",
+    "playwright.config.mjs",
+  ];
+
+  for (const file of configFiles) {
+    if (fs.existsSync(path.join(process.cwd(), file))) {
+      return { hasPlaywright: true, configFile: file };
+    }
+  }
+
+  // Check package.json for playwright dependency
+  try {
+    const pkg = fs.readJsonSync(path.join(process.cwd(), "package.json"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps["@playwright/test"] || deps["playwright"]) {
+      return { hasPlaywright: true, configFile: null };
+    }
+  } catch {
+    // No package.json
+  }
+
+  return { hasPlaywright: false, configFile: null };
+}
+
+/**
+ * Generate documentation block configuration
+ */
+function generateDocumentationConfig(root = "./docs", strategy = "git_pr") {
+  return {
+    root,
+    include: ["**/*.md", "**/*.mdx"],
+    exclude: ["**/_*.mdx", "**/node_modules/**", "**/.next/**"],
+    strategy,
+    assetFormat: "markdown",
+    mappings: {},
+  };
+}
+
+/**
+ * Scaffold a basic documentation structure
+ */
+async function scaffoldDocumentation(template = "basic") {
+  const docsDir = path.join(process.cwd(), "docs");
+  fs.ensureDirSync(docsDir);
+
+  const readmeContent = `# Documentation
+
+This directory contains documentation for your project.
+
+## Linking Docs to Visual Journeys
+
+Add \`reshot_journey\` frontmatter to your markdown files to link them to Playwright test captures:
+
+\`\`\`markdown
+---
+title: "Feature Name"
+reshot_journey: "feature/workflow-name"
+---
+
+# Feature Documentation
+
+Your content here...
+\`\`\`
+
+The journey key should match your Playwright test structure. For example:
+- Test file: \`tests/01-auth-flows.spec.ts\` with "Login Flow" describe block
+- Journey key: \`auth-flows/login-flow\`
+
+## Commands
+
+- \`reshot import-tests\` - Import existing Playwright tests
+- \`reshot sync\` - Sync visuals and documentation  
+- \`reshot status\` - View sync status and drifts
+- \`reshot validate\` - Validate configuration
+- \`reshot studio\` - Open visual management UI
+
+For more information, visit: https://docs.reshot.dev
+`;
+
+  fs.writeFileSync(path.join(docsDir, "README.md"), readmeContent);
+
+  const exampleContent = `---
+title: "Getting Started"
+reshot_journey: "onboarding/first-steps"
+description: "Quick start guide for new users"
+---
+
+# Getting Started
+
+Welcome! This is an example documentation file linked to the \`onboarding/first-steps\` journey.
+
+## Overview
+
+When Reshot detects UI changes in your Playwright tests, it will automatically propose updates to this document with new screenshots and descriptions.
+
+## Steps
+
+1. **Step 1**: Description of first step
+
+   <!-- Reshot will inject screenshots here when visual drift is detected -->
+
+2. **Step 2**: Description of second step
+
+3. **Step 3**: Description of third step
+
+## Next Steps
+
+- Link more documents to journeys
+- Run \`reshot sync\` to upload traces
+- Check \`reshot status\` for drift notifications
+`;
+
+  fs.writeFileSync(path.join(docsDir, "getting-started.md"), exampleContent);
+  return "docs";
+}
+
+/**
+ * Check if a documentation framework is already set up
+ */
+function detectDocumentationFramework() {
+  const frameworks = [
+    {
+      name: "Astro/Starlight",
+      files: ["astro.config.mjs", "astro.config.ts"],
+      deps: ["@astrojs/starlight"],
+    },
+    {
+      name: "Docusaurus",
+      files: ["docusaurus.config.js", "docusaurus.config.ts"],
+      deps: ["@docusaurus/core"],
+    },
+    {
+      name: "VitePress",
+      files: [".vitepress/config.js", ".vitepress/config.ts"],
+      deps: ["vitepress"],
+    },
+    { name: "Mintlify", files: ["mint.json"], deps: [] },
+    { name: "GitBook", files: [".gitbook.yaml"], deps: [] },
+  ];
+
+  // Check for config files
+  for (const fw of frameworks) {
+    for (const file of fw.files) {
+      if (fs.existsSync(path.join(process.cwd(), file))) {
+        return { framework: fw.name, detected: true };
+      }
+    }
+  }
+
+  // Check package.json for deps
+  try {
+    const pkg = fs.readJsonSync(path.join(process.cwd(), "package.json"));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    for (const fw of frameworks) {
+      for (const dep of fw.deps) {
+        if (allDeps[dep]) {
+          return { framework: fw.name, detected: true };
+        }
+      }
+    }
+  } catch {
+    // No package.json
+  }
+
+  return { framework: null, detected: false };
+}
+
+/**
+ * Count documentation files in a directory
+ */
+function countDocFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+
+  let count = 0;
+  function walk(d) {
+    for (const item of fs.readdirSync(d)) {
+      const full = path.join(d, item);
+      if (fs.statSync(full).isDirectory()) {
+        if (!item.startsWith(".") && item !== "node_modules") walk(full);
+      } else if (item.endsWith(".md") || item.endsWith(".mdx")) {
+        count++;
+      }
+    }
+  }
+  walk(dir);
+  return count;
+}
+
+/**
+ * Main setup wizard
+ */
+async function setupWizard(options = {}) {
+  const { offline = false, force = false } = options;
+
+  console.log(chalk.cyan.bold("\n🚀 Reshot Setup Wizard\n"));
+  console.log(chalk.gray("Let's configure Reshot for your project.\n"));
+
+  // Detect project context
+  const gitInfo = detectGitInfo();
+  const playwrightInfo = detectPlaywright();
+  const existingDocsRoot = detectDocumentationRoot();
+
+  // Check existing setup
+  let existingSettings = null;
+  let existingConfig = null;
+  let isAlreadyAuthed = false;
+
+  try {
+    existingSettings = config.readSettings();
+    isAlreadyAuthed = !!(
+      existingSettings?.apiKey && existingSettings?.projectId
+    );
+  } catch {
+    // No existing settings
+  }
+
+  try {
+    if (config.configExists()) {
+      existingConfig = config.readConfig();
+    }
+  } catch {
+    // No existing config
+  }
+
+  // If already set up and not forcing, confirm continue
+  if ((isAlreadyAuthed || existingConfig) && !force) {
+    console.log(
+      chalk.yellow("⚠ Reshot is already configured in this project.\n"),
+    );
+
+    if (isAlreadyAuthed) {
+      console.log(
+        chalk.green("  ✔ Authenticated:"),
+        chalk.cyan(existingSettings.projectName || existingSettings.projectId),
+      );
+    }
+    if (existingConfig) {
+      console.log(
+        chalk.green("  ✔ Config found:"),
+        chalk.cyan("docsync.config.json"),
+      );
+    }
+
+    const { continueSetup } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "continueSetup",
+        message: "Would you like to reconfigure?",
+        default: false,
+      },
+    ]);
+
+    if (!continueSetup) {
+      console.log(
+        chalk.gray("\nRun"),
+        chalk.cyan("reshot studio"),
+        chalk.gray("to manage your visuals.\n"),
+      );
+      return;
+    }
+  }
+
+  // ========================================
+  // STEP 1: Platform Connection
+  // ========================================
+  console.log(chalk.cyan("\n━━━ Step 1: Platform Connection ━━━\n"));
+
+  let useCloud = false;
+  let projectId = existingSettings?.projectId;
+  let apiKey = existingSettings?.apiKey;
+  let projectName = existingSettings?.projectName;
+
+  if (!offline) {
+    const { connectToCloud } = await inquirer.prompt([
+      {
+        type: "list",
+        name: "connectToCloud",
+        message: "How would you like to use Reshot?",
+        choices: [
+          {
+            name: `${chalk.cyan("Connect to Reshot Cloud")} - Governance, CDN hosting, team collaboration`,
+            value: true,
+          },
+          {
+            name: `${chalk.gray("Offline mode")} - Local-only visuals (no cloud sync)`,
+            value: false,
+          },
+        ],
+        default: isAlreadyAuthed ? 0 : 1,
+      },
+    ]);
+
+    useCloud = connectToCloud;
+
+    if (useCloud && !isAlreadyAuthed) {
+      console.log(chalk.gray("\nOpening browser for authentication...\n"));
+
+      const authCommand = require("./auth");
+      await authCommand();
+
+      // Re-read settings after auth
+      try {
+        existingSettings = config.readSettings();
+        projectId = existingSettings?.projectId;
+        apiKey = existingSettings?.apiKey;
+        projectName = existingSettings?.projectName;
+        isAlreadyAuthed = !!(apiKey && projectId);
+      } catch {
+        throw new Error("Authentication failed. Please try again.");
+      }
+
+      if (!isAlreadyAuthed) {
+        throw new Error("Authentication was not completed.");
+      }
+
+      console.log(
+        chalk.green("\n✔ Connected to"),
+        chalk.cyan(projectName || projectId),
+      );
+    } else if (useCloud && isAlreadyAuthed) {
+      console.log(
+        chalk.green("✔ Already connected to"),
+        chalk.cyan(projectName || projectId),
+      );
+    }
+  } else {
+    console.log(chalk.gray("Running in offline mode - no cloud sync."));
+  }
+
+  // ========================================
+  // STEP 2: Feature Selection
+  // ========================================
+  console.log(chalk.cyan("\n━━━ Step 2: Features ━━━\n"));
+
+  const { features } = await inquirer.prompt([
+    {
+      type: "checkbox",
+      name: "features",
+      message: "Which features would you like to enable?",
+      choices: [
+        {
+          name: "Visual capture from Playwright tests",
+          value: "visuals",
+          checked: playwrightInfo.hasPlaywright,
+        },
+        {
+          name: "Documentation sync (detect drift, auto-update docs)",
+          value: "docsync",
+          checked: !!existingDocsRoot,
+        },
+      ],
+      validate: (answers) => {
+        if (answers.length === 0) {
+          return "Please select at least one feature";
+        }
+        return true;
+      },
+    },
+  ]);
+
+  const enableVisuals = features.includes("visuals");
+  const enableDocSync = features.includes("docsync");
+
+  // ========================================
+  // STEP 3: Visuals Configuration (if enabled)
+  // ========================================
+  let traceDir = "./test-results";
+  let journeyMappings = {};
+
+  if (enableVisuals) {
+    console.log(chalk.cyan("\n━━━ Step 3: Visual Capture ━━━\n"));
+
+    if (playwrightInfo.hasPlaywright) {
+      console.log(chalk.green("✔ Playwright detected"));
+      if (playwrightInfo.configFile) {
+        console.log(chalk.gray(`  Config: ${playwrightInfo.configFile}`));
+      }
+
+      // Offer to import existing tests
+      const { importTests } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "importTests",
+          message:
+            "Import existing Playwright tests to create journey mappings?",
+          default: true,
+        },
+      ]);
+
+      if (importTests) {
+        console.log(chalk.gray("\nScanning Playwright tests..."));
+        try {
+          const importTestsCommand = require("./import-tests");
+          const result = await importTestsCommand({
+            interactive: false,
+            dryRun: false,
+          });
+          if (result?.journeyMappings) {
+            journeyMappings = result.journeyMappings;
+            console.log(
+              chalk.green(
+                `✔ Imported ${Object.keys(journeyMappings).length} journey mapping(s)`,
+              ),
+            );
+          }
+        } catch (err) {
+          console.log(chalk.yellow(`⚠ Could not import tests: ${err.message}`));
+        }
+      }
+    } else {
+      console.log(chalk.yellow("⚠ Playwright not detected"));
+      console.log(
+        chalk.gray("  Install with: npm install -D @playwright/test"),
+      );
+    }
+
+    const { customTraceDir } = await inquirer.prompt([
+      {
+        type: "input",
+        name: "customTraceDir",
+        message: "Playwright test-results directory:",
+        default: "./test-results",
+      },
+    ]);
+
+    traceDir = customTraceDir;
+  }
+
+  // ========================================
+  // STEP 4: Documentation Configuration (if enabled)
+  // ========================================
+  let docConfig = null;
+
+  if (enableDocSync) {
+    console.log(chalk.cyan("\n━━━ Step 4: Documentation Sync ━━━\n"));
+
+    // Check for existing documentation framework
+    const docFramework = detectDocumentationFramework();
+    let docsRoot = existingDocsRoot;
+
+    if (docFramework.detected) {
+      console.log(chalk.green(`✔ ${docFramework.framework} detected`));
+    }
+
+    if (docsRoot) {
+      const docCount = countDocFiles(path.join(process.cwd(), docsRoot));
+      console.log(
+        chalk.green(
+          `✔ Found documentation at: ${docsRoot}/ (${docCount} files)`,
+        ),
+      );
+
+      const { useDetected } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "useDetected",
+          message: `Use ${docsRoot}/ for documentation sync?`,
+          default: true,
+        },
+      ]);
+
+      if (!useDetected) {
+        docsRoot = null;
+      }
+    }
+
+    if (!docsRoot) {
+      const choices = [
+        { name: "Create docs/ directory with examples", value: "scaffold" },
+        { name: "Specify existing directory path", value: "specify" },
+      ];
+
+      // Add Astro Starlight option if not already a docs framework
+      if (!docFramework.detected) {
+        choices.push({
+          name:
+            chalk.cyan("Create Astro Starlight project") +
+            chalk.gray(" (recommended for new docs)"),
+          value: "starlight",
+        });
+      }
+
+      const { docAction } = await inquirer.prompt([
+        {
+          type: "list",
+          name: "docAction",
+          message: "Documentation setup:",
+          choices,
+        },
+      ]);
+
+      if (docAction === "scaffold") {
+        console.log(chalk.gray("\nCreating docs/ directory..."));
+        docsRoot = await scaffoldDocumentation();
+        console.log(chalk.green("✔ Created docs/ with example files"));
+      } else if (docAction === "starlight") {
+        console.log(chalk.cyan("\nTo create an Astro Starlight project:\n"));
+        console.log(
+          chalk.white("  npm create astro@latest -- --template starlight"),
+        );
+        console.log(
+          chalk.gray(
+            "\nRun that command, then re-run reshot setup to link it.\n",
+          ),
+        );
+
+        // Still create a basic docs folder as fallback
+        const { createBasic } = await inquirer.prompt([
+          {
+            type: "confirm",
+            name: "createBasic",
+            message: "Create a basic docs/ folder for now?",
+            default: true,
+          },
+        ]);
+
+        if (createBasic) {
+          docsRoot = await scaffoldDocumentation();
+          console.log(chalk.green("✔ Created docs/ with example files"));
+        }
+      } else {
+        const { customPath } = await inquirer.prompt([
+          {
+            type: "input",
+            name: "customPath",
+            message: "Documentation directory path:",
+            default: "./docs",
+            validate: (input) => {
+              const fullPath = path.join(process.cwd(), input);
+              if (!fs.existsSync(fullPath)) {
+                return `Directory ${input} does not exist. Create it first or use scaffolding.`;
+              }
+              return true;
+            },
+          },
+        ]);
+        docsRoot = customPath;
+      }
+    }
+
+    // Determine strategy
+    let strategy = "git_pr";
+
+    if (useCloud && docsRoot) {
+      if (gitInfo.isGitHub) {
+        console.log(chalk.green("\n✔ GitHub repository detected"));
+        const { useGitPR } = await inquirer.prompt([
+          {
+            type: "confirm",
+            name: "useGitPR",
+            message: "Auto-create Pull Requests for documentation updates?",
+            default: true,
+          },
+        ]);
+        strategy = useGitPR ? "git_pr" : "external_host";
+      } else {
+        const { strategyChoice } = await inquirer.prompt([
+          {
+            type: "list",
+            name: "strategyChoice",
+            message: "How should documentation updates be delivered?",
+            choices: [
+              { name: "Git Pull Requests", value: "git_pr" },
+              {
+                name: "Notifications only (external CMS)",
+                value: "external_host",
+              },
+            ],
+          },
+        ]);
+        strategy = strategyChoice;
+      }
+    }
+
+    docConfig = generateDocumentationConfig(docsRoot, strategy);
+  }
+
+  // ========================================
+  // STEP 5: Generate Configuration
+  // ========================================
+  console.log(chalk.cyan("\n━━━ Generating Configuration ━━━\n"));
+
+  const newConfig = {
+    $schema: "https://reshot.dev/schemas/docsync-config.json",
+    version: "2.0",
+    baseUrl: existingConfig?.baseUrl || "http://localhost:3000",
+    viewport: existingConfig?.viewport || { width: 1280, height: 720 },
+    _metadata: {
+      features: {
+        visuals: enableVisuals,
+        docsync: enableDocSync,
+      },
+    },
+  };
+
+  if (useCloud && projectId) {
+    newConfig.projectId = projectId;
+  }
+
+  if (enableVisuals) {
+    newConfig.visuals = {
+      traceDir,
+      journeyMappings:
+        Object.keys(journeyMappings).length > 0 ? journeyMappings : undefined,
+    };
+    newConfig.assetDir = ".reshot/output";
+    newConfig.scenarios = existingConfig?.scenarios || [];
+  }
+
+  if (enableDocSync && docConfig) {
+    newConfig.documentation = docConfig;
+  }
+
+  // Write configuration
+  config.writeConfig(newConfig);
+  console.log(chalk.green("✔ Created docsync.config.json"));
+
+  // ========================================
+  // STEP 6: Success & Next Steps
+  // ========================================
+  console.log(chalk.green("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+  console.log(chalk.green.bold("✔ Reshot setup complete!"));
+  console.log(chalk.green("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"));
+
+  console.log(chalk.cyan("Next steps:\n"));
+
+  console.log(
+    `  1. ${chalk.gray("Review")} ${chalk.cyan("docsync.config.json")} ${chalk.gray("and commit to your repo")}`,
+  );
+
+  if (enableVisuals) {
+    console.log(
+      `  2. ${chalk.gray("Run Playwright tests to generate traces:")}`,
+    );
+    console.log(`     ${chalk.cyan("npx playwright test")}`);
+  }
+
+  if (enableDocSync) {
+    console.log(
+      `  ${enableVisuals ? "3" : "2"}. ${chalk.gray("Add")} ${chalk.cyan("reshot_journey")} ${chalk.gray("frontmatter to your markdown files")}`,
+    );
+    console.log(
+      `     ${chalk.gray('Example: reshot_journey: "auth/login-flow"')}`,
+    );
+  }
+
+  console.log(`\n  ${chalk.gray("Sync visuals and docs to Reshot:")}`);
+  console.log(`     ${chalk.cyan("reshot sync")}`);
+
+  console.log(`\n  ${chalk.gray("Launch the visual management UI:")}`);
+  console.log(`     ${chalk.cyan("reshot studio")}\n`);
+
+  // Offer to launch studio
+  const { launchStudio } = await inquirer.prompt([
+    {
+      type: "confirm",
+      name: "launchStudio",
+      message: "Launch Reshot Studio now?",
+      default: true,
+    },
+  ]);
+
+  if (launchStudio) {
+    console.log(chalk.cyan("\n🎬 Launching Reshot Studio...\n"));
+    const uiCommand = require("./ui");
+    await uiCommand({ open: true });
+  }
+}
+
+module.exports = setupWizard;