featuredrop 2.7.1 → 3.0.1

package/dist/featuredrop.cjs

@@ -8,6 +8,7 @@ var os = require('os');
 var zod = require('zod');
 var posthogNode = require('posthog-node');
 var moduleApi = require('module');
+var fs = require('fs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopNamespace(e) {
@@ -1234,6 +1235,184 @@ function generateRSS(manifest, options) {
     "</rss>"
   ].join("");
 }
+var CLAUDE_SKILL = `# FeatureDrop \u2014 Setup & Configuration Skill
+
+## What it is
+Open-source product adoption toolkit. Changelogs, badges, tours, checklists, feedback.
+Zero dependencies. < 3 kB core. MIT licensed.
+
+## Quick Setup
+1. \`npm install featuredrop\`
+2. Create features.json manifest
+3. Wrap root in \`<FeatureDropProvider manifest={features} storage={new LocalStorageAdapter()}>\`
+4. Drop components or use hooks
+
+## Imports (ALWAYS use subpath imports)
+\`\`\`
+featuredrop                \u2014 core functions (isNew, getNewFeatures, createManifest)
+featuredrop/react          \u2014 components + hooks (NewBadge, ChangelogWidget, Tour, Checklist)
+featuredrop/react/hooks    \u2014 headless hooks only (useChangelog, useTour, useChecklist, useNewFeature)
+featuredrop/adapters       \u2014 storage (PostgresAdapter, RedisAdapter, IndexedDBAdapter, etc.)
+featuredrop/engine         \u2014 AdoptionEngine (smart timing, format selection, adoption scoring)
+featuredrop/schema         \u2014 Zod validation (featureEntrySchema, validateManifest)
+featuredrop/testing        \u2014 test helpers (createMockManifest, createMockStorage, createTestProvider)
+featuredrop/tailwind       \u2014 Tailwind plugin (featureDropPlugin)
+\`\`\`
+
+## Hooks Reference (prefer these for custom UI)
+\`\`\`
+useNewFeature(sidebarKey)  \u2192 { isNew, feature, dismiss }
+useNewCount()              \u2192 number
+useChangelog()             \u2192 { features, newFeatures, newCount, dismiss, dismissAll, markAllSeen, getByCategory }
+useTour(id)                \u2192 { currentStep, stepIndex, totalSteps, isActive, start, next, prev, skip, complete }
+useChecklist(id)           \u2192 { tasks, progress, isComplete, completeTask, resetChecklist }
+useSurvey(id)              \u2192 { isOpen, show, hide, askLater, submitted, canShow }
+useSmartFeature(id)        \u2192 { show, format, feature, dismiss, confidence, reason }
+useAdoptionScore()         \u2192 { score, grade, breakdown, recommendations }
+useFeatureDrop()           \u2192 full provider context (low-level)
+\`\`\`
+
+## Components (ready-made UI with headless render prop mode)
+NewBadge, ChangelogWidget, ChangelogPage, Tour, Checklist, Spotlight, SpotlightChain,
+Hotspot, TooltipGroup, Banner, Toast, AnnouncementModal, Survey, FeedbackWidget,
+FeatureRequestButton, FeatureRequestForm, SmartAnnouncement
+
+## Manifest Format
+\`\`\`json
+{
+  "id": "dark-mode",
+  "label": "Dark Mode",
+  "description": "Toggle between light and dark themes.",
+  "releasedAt": "2026-02-20",
+  "showNewUntil": "2026-04-20",
+  "category": "ui",
+  "priority": "normal",
+  "type": "feature"
+}
+\`\`\`
+
+## Storage Adapters
+- LocalStorageAdapter (browser default, zero-config)
+- MemoryAdapter (testing, SSR)
+- IndexedDBAdapter (offline-first PWAs)
+- PostgresAdapter, RedisAdapter, MySQLAdapter, MongoAdapter, SQLiteAdapter (server)
+- SupabaseAdapter (Supabase with optional realtime)
+- RemoteAdapter (HTTP API with retry + circuit breaker)
+- HybridAdapter (local + remote with batched sync)
+
+## Rules
+- Always use subpath imports (never bare 'featuredrop' for React code)
+- Prefer hooks over components when user has a custom design system
+- Features auto-expire via showNewUntil \u2014 don't build manual expiry logic
+- Zero production dependencies must be maintained
+- TypeScript strict \u2014 no any types
+`;
+var CURSORRULES = `When working with FeatureDrop:
+- FeatureDrop is a product adoption library (changelogs, badges, tours, checklists, feedback)
+- ALWAYS import from subpaths: 'featuredrop/react', 'featuredrop/react/hooks', 'featuredrop/adapters'
+- For custom UI: use hooks from 'featuredrop/react/hooks' (useChangelog, useTour, useChecklist, useSmartFeature)
+- For ready-made UI: use components from 'featuredrop/react' (NewBadge, ChangelogWidget, Tour, SmartAnnouncement)
+- Features are defined in JSON: { id, label, description, releasedAt, showNewUntil? }
+- Wrap app in <FeatureDropProvider manifest={features} storage={new LocalStorageAdapter()}>
+- Storage default: LocalStorageAdapter. Server: PostgresAdapter, RedisAdapter from 'featuredrop/adapters'
+- Engine: import { createAdoptionEngine } from 'featuredrop/engine' for smart timing + format selection
+- Core < 3 kB, React ~12 kB, zero production deps, fully tree-shakable
+- All components support headless mode via render props
+- For shadcn projects: use hooks from 'featuredrop/react/hooks' + shadcn primitives
+- TypeScript strict mode, no 'any' types
+- Zero production dependencies \u2014 do not add external deps
+`;
+var MCP_CONFIG = {
+  featuredrop: {
+    command: "npx",
+    args: ["@featuredrop/mcp"]
+  }
+};
+async function runAiSetup(cwd) {
+  const root = cwd ?? process.cwd();
+  const result = { detected: [], created: [], skipped: [] };
+  const claudeDir = path.join(root, ".claude");
+  const claudeSkillsDir = path.join(claudeDir, "skills");
+  const claudeSkillPath = path.join(claudeSkillsDir, "featuredrop.md");
+  if (fs.existsSync(claudeDir) || fs.existsSync(path.join(root, "CLAUDE.md"))) {
+    result.detected.push("Claude Code");
+    if (fs.existsSync(claudeSkillPath)) {
+      result.skipped.push(claudeSkillPath);
+    } else {
+      await promises.mkdir(claudeSkillsDir, { recursive: true });
+      await promises.writeFile(claudeSkillPath, CLAUDE_SKILL, "utf8");
+      result.created.push(claudeSkillPath);
+    }
+    const claudeSettingsDir = claudeDir;
+    const claudeMcpPath = path.join(claudeSettingsDir, "settings.json");
+    if (!fs.existsSync(claudeMcpPath)) {
+      const settings = { mcpServers: MCP_CONFIG };
+      await promises.writeFile(claudeMcpPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+      result.created.push(claudeMcpPath);
+    } else {
+      try {
+        const existing = JSON.parse(await promises.readFile(claudeMcpPath, "utf8"));
+        const mcpServers = existing.mcpServers ?? {};
+        if (!mcpServers.featuredrop) {
+          mcpServers.featuredrop = MCP_CONFIG.featuredrop;
+          existing.mcpServers = mcpServers;
+          await promises.writeFile(claudeMcpPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+          result.created.push(`${claudeMcpPath} (merged)`);
+        } else {
+          result.skipped.push(claudeMcpPath);
+        }
+      } catch {
+        result.skipped.push(`${claudeMcpPath} (parse error)`);
+      }
+    }
+  }
+  const cursorDir = path.join(root, ".cursor");
+  const cursorRulesPath = path.join(root, ".cursorrules");
+  const cursorMcpPath = path.join(cursorDir, "mcp.json");
+  if (fs.existsSync(cursorDir) || fs.existsSync(cursorRulesPath)) {
+    result.detected.push("Cursor");
+    if (fs.existsSync(cursorRulesPath)) {
+      const content = await promises.readFile(cursorRulesPath, "utf8");
+      if (content.includes("FeatureDrop")) {
+        result.skipped.push(cursorRulesPath);
+      } else {
+        await promises.writeFile(cursorRulesPath, content + "\n\n" + CURSORRULES, "utf8");
+        result.created.push(`${cursorRulesPath} (appended)`);
+      }
+    } else {
+      await promises.writeFile(cursorRulesPath, CURSORRULES, "utf8");
+      result.created.push(cursorRulesPath);
+    }
+    if (fs.existsSync(cursorDir)) {
+      if (!fs.existsSync(cursorMcpPath)) {
+        const config = { servers: MCP_CONFIG };
+        await promises.mkdir(cursorDir, { recursive: true });
+        await promises.writeFile(cursorMcpPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+        result.created.push(cursorMcpPath);
+      } else {
+        result.skipped.push(cursorMcpPath);
+      }
+    }
+  }
+  const vscodeDir = path.join(root, ".vscode");
+  const vscodeMcpPath = path.join(vscodeDir, "mcp.json");
+  if (fs.existsSync(vscodeDir)) {
+    result.detected.push("VS Code");
+    if (!fs.existsSync(vscodeMcpPath)) {
+      const config = { servers: MCP_CONFIG };
+      await promises.writeFile(vscodeMcpPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+      result.created.push(vscodeMcpPath);
+    } else {
+      result.skipped.push(vscodeMcpPath);
+    }
+  }
+  if (result.detected.length === 0) {
+    result.detected.push("(none detected \u2014 creating .cursorrules as default)");
+    await promises.writeFile(cursorRulesPath, CURSORRULES, "utf8");
+    result.created.push(cursorRulesPath);
+  }
+  return result;
+}
 
 // src/cli.ts
 function parseArgs(argv) {
@@ -1247,7 +1426,8 @@ function parseArgs(argv) {
     "stats",
     "doctor",
     "generate-rss",
-    "generate-changelog"
+    "generate-changelog",
+    "ai-setup"
   ]);
   const command = allowed.has(commandRaw) ? commandRaw : "help";
   const parsed = { command };
@@ -1287,6 +1467,7 @@ function printHelp() {
   console.log("  featuredrop doctor [--pattern features/**/*.md] [--cwd .]");
   console.log("  featuredrop generate-rss [--pattern features/**/*.md] [--out featuredrop.rss.xml] [--title ...] [--link ...] [--description ...] [--cwd .]");
   console.log("  featuredrop generate-changelog [--pattern features/**/*.md] [--out CHANGELOG.generated.md] [--cwd .]");
+  console.log("  featuredrop ai-setup [--cwd .]                          Detect AI tools and create context files");
 }
 async function promptForLabelIfNeeded(label) {
   if (label?.trim()) return label.trim();
@@ -1333,6 +1514,32 @@ async function run() {
       await shutdownPostHog();
       return;
     }
+    if (args.command === "ai-setup") {
+      const result = await runAiSetup(args.cwd);
+      if (result.detected.length > 0) {
+        console.log(`Detected: ${result.detected.join(", ")}`);
+      }
+      for (const path of result.created) {
+        console.log(`  Created: ${path}`);
+      }
+      for (const path of result.skipped) {
+        console.log(`  Skipped: ${path} (already exists)`);
+      }
+      if (result.created.length === 0 && result.skipped.length > 0) {
+        console.log("All AI context files already up to date.");
+      }
+      posthog?.capture({
+        distinctId,
+        event: "cli_ai_setup",
+        properties: {
+          detected: result.detected,
+          files_created: result.created.length,
+          files_skipped: result.skipped.length
+        }
+      });
+      await shutdownPostHog();
+      return;
+    }
     if (args.command === "add") {
       const label = await promptForLabelIfNeeded(args.label);
       const result = await addFeatureEntry({