@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/installer-wizard-patterns.md

@@ -0,0 +1,249 @@
+# Installer Wizard Patterns for Web Applications
+
+## Problem
+Creating a web-based installer wizard that allows non-technical users to install a Node.js application on cPanel shared hosting without command-line access.
+
+---
+
+## Solution: WordPress-Style 5-Minute Install Pattern
+
+### Core Principles
+1. **Single entry point** - One URL to start installation
+2. **Progressive disclosure** - Show only what's needed at each step
+3. **Auto-detection** - Check requirements automatically
+4. **Fallback options** - Multiple paths to success
+5. **Clear feedback** - Show progress and errors clearly
+
+---
+
+## Installer Flow (7 Steps)
+
+### Step 1: Welcome & Requirements Check
+```javascript
+// server/installer/requirements.js
+const checkRequirements = async () => {
+  return {
+    nodeVersion: process.version,
+    nodeOk: semver.gte(process.version, '18.0.0'),
+    phpVersion: await getPhpVersion(), // For cPanel Node.js selector
+    diskSpace: await getDiskSpace(),
+    diskOk: diskSpace > 500 * 1024 * 1024, // 500MB minimum
+    writableDir: await checkWritable(process.cwd()),
+    dbConnectable: await testDbConnection()
+  };
+};
+```
+
+### Step 2: License Key Validation
+```javascript
+// License format: XXXX-XXXX-XXXX-XXXX
+// Checksum: Modified Luhn algorithm with 32-char alphabet
+const LICENSE_CHARS = '23456789ABCDEFGHJKLMNPQRSTUVWXYZ';
+
+const validateLicenseKey = (key) => {
+  const clean = key.replace(/-/g, '').toUpperCase();
+  if (clean.length !== 16) return false;
+
+  // Extract checksum (last char)
+  const payload = clean.slice(0, 15);
+  const checksum = clean[15];
+
+  // Calculate expected checksum
+  let sum = 0;
+  for (let i = 0; i < payload.length; i++) {
+    let val = LICENSE_CHARS.indexOf(payload[i]);
+    if (i % 2 === 0) val *= 2;
+    sum += val % 32 + Math.floor(val / 32);
+  }
+  const expected = LICENSE_CHARS[(32 - (sum % 32)) % 32];
+
+  return checksum === expected;
+};
+```
+
+### Step 3: Database Configuration
+```javascript
+// Support both PostgreSQL and MySQL via Knex.js
+// server/db/knex.js
+const knex = require('knex');
+
+const getKnexConfig = (dbType, connectionString) => {
+  const configs = {
+    postgresql: {
+      client: 'pg',
+      connection: connectionString,
+      pool: { min: 2, max: 10 }
+    },
+    mysql: {
+      client: 'mysql2',
+      connection: connectionString,
+      pool: { min: 2, max: 10 }
+    }
+  };
+  return configs[dbType];
+};
+```
+
+### Step 4: Admin Account Creation
+```javascript
+// Validate admin credentials before creation
+const validateAdminSetup = (data) => {
+  const errors = [];
+
+  if (!data.email || !isValidEmail(data.email)) {
+    errors.push('Valid email required');
+  }
+  if (!data.password || data.password.length < 8) {
+    errors.push('Password must be 8+ characters');
+  }
+  if (data.password !== data.confirmPassword) {
+    errors.push('Passwords do not match');
+  }
+
+  return { valid: errors.length === 0, errors };
+};
+```
+
+### Step 5: Site Configuration
+```javascript
+// Basic site settings
+const siteConfig = {
+  siteName: 'My Learning Platform',
+  siteUrl: 'https://learn.example.com',
+  adminEmail: 'admin@example.com',
+  timezone: 'America/New_York',
+  language: 'en'
+};
+```
+
+### Step 6: Optional Features
+```javascript
+// Feature flags for optional modules
+const optionalFeatures = {
+  podcasts: true,
+  blog: true,
+  certificates: true,
+  payments: false, // Requires Stripe setup
+  emailNotifications: false // Requires SMTP setup
+};
+```
+
+### Step 7: Installation & Verification
+```javascript
+// Run migrations and seed data
+const runInstallation = async (config) => {
+  // 1. Write .env file
+  await writeEnvFile(config);
+
+  // 2. Run database migrations
+  await knex.migrate.latest();
+
+  // 3. Create admin user
+  await createAdminUser(config.admin);
+
+  // 4. Seed starter content (optional)
+  if (config.seedContent) {
+    await knex.seed.run();
+  }
+
+  // 5. Remove installer (security)
+  await disableInstaller();
+
+  return { success: true, loginUrl: '/login' };
+};
+```
+
+---
+
+## Security Considerations
+
+### Disable After Installation
+```javascript
+// server/middleware/installerGuard.js
+const installerGuard = (req, res, next) => {
+  const installed = fs.existsSync('.installed');
+
+  if (installed && req.path.startsWith('/installer')) {
+    return res.redirect('/login');
+  }
+
+  next();
+};
+```
+
+### Secure .env Generation
+```javascript
+// Generate secure random secrets
+const crypto = require('crypto');
+
+const generateSecrets = () => ({
+  JWT_SECRET: crypto.randomBytes(64).toString('hex'),
+  SESSION_SECRET: crypto.randomBytes(32).toString('hex'),
+  ENCRYPTION_KEY: crypto.randomBytes(32).toString('hex')
+});
+```
+
+---
+
+## Database Abstraction with Knex.js
+
+### Migration Example
+```javascript
+// migrations/001_users.js
+exports.up = function(knex) {
+  return knex.schema.createTable('users', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.string('email').unique().notNullable();
+    table.string('password').notNullable();
+    table.string('name');
+    table.enum('role', ['student', 'instructor', 'admin']).defaultTo('student');
+    table.timestamps(true, true);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTable('users');
+};
+```
+
+### Query Abstraction
+```javascript
+// Use Knex query builder for database-agnostic queries
+const findUserByEmail = async (email) => {
+  return knex('users').where({ email }).first();
+};
+
+const createUser = async (userData) => {
+  const [user] = await knex('users')
+    .insert(userData)
+    .returning('*');
+  return user;
+};
+```
+
+---
+
+## cPanel Node.js Selector Setup
+
+### Instructions for Non-Technical Users
+1. Log into cPanel
+2. Find "Setup Node.js App" under Software
+3. Click "Create Application"
+4. Settings:
+   - Node.js version: 18.x or higher
+   - Application mode: Production
+   - Application root: public_html/lms (or subdirectory)
+   - Application URL: your-domain.com/lms
+   - Application startup file: server/index.js
+5. Click "Create"
+6. Click "Run NPM Install"
+7. Visit your URL to start installer wizard
+
+---
+
+## References
+- Full documentation: `docs/installer/INSTALLER_ARCHITECTURE.md`
+- Implementation roadmap: `docs/installer/IMPLEMENTATION_VISION.md`
+- Database abstraction: `docs/installer/DATABASE_ABSTRACTION.md`
+- Licensing system: `docs/installer/LICENSING_SYSTEM.md`
+- WordPress installer analysis: `docs/installer/research/WORDPRESS_INSTALLER_ANALYSIS.md`

package/skills-library/integrations/CLAUDE_CODE_TOKEN_ANALYTICS.md

@@ -0,0 +1,160 @@
+---
+name: claude-code-token-analytics
+category: integrations
+version: 1.0.0
+contributed: 2026-03-01
+contributor: claude-mission-control
+last_updated: 2026-03-01
+tags: [claude-code, tokens, analytics, stats-cache, usage, billing, dashboard]
+difficulty: medium
+---
+
+# Claude Code Token Analytics from stats-cache.json
+
+## Problem
+
+Need to display Claude Code token usage, costs, and cache savings in a dashboard. Claude Code stores rich token data locally but no official API exposes it for custom UIs. Key questions:
+- How many tokens consumed per day/model?
+- What does the API usage cost?
+- How much is saved through prompt caching?
+- Where are billing period boundaries?
+
+## Solution Pattern
+
+Claude Code maintains two local data sources:
+
+1. **`~/.claude/stats-cache.json`** — Pre-aggregated daily stats (fast, recommended)
+2. **`~/.claude/projects/{hash}/{session}.jsonl`** — Raw per-message data (large, slow)
+
+Use `stats-cache.json` for dashboards. It has three arrays:
+- `dailyActivity` — messages, sessions, tool calls per day
+- `dailyModelTokens` — token counts by model per day
+- `modelUsage` — cumulative per-model totals with cache breakdown
+
+### Cache savings calculation
+
+Cache reads are billed at 1/8 of input token price. The savings formula:
+
+```
+savings = cache_read_tokens * (input_price - cache_read_price) / 1,000,000
+```
+
+Per-model pricing (USD/M tokens):
+
+| Model | Input | Output | Cache Read | Cache Write |
+|-------|-------|--------|------------|-------------|
+| Opus 4.6 | $15 | $75 | $1.875 | $18.75 |
+| Sonnet 4.5/4.6 | $3 | $15 | $0.375 | $3.75 |
+| Haiku 4.5 | $0.80 | $4 | $0.10 | $1.00 |
+
+## Code Example
+
+### Backend parser (TypeScript/Express)
+
+```typescript
+function parseTokenAnalytics(period: string) {
+  const statsPath = path.join(CLAUDE_DIR, 'stats-cache.json')
+  if (!existsSync(statsPath)) return { daily: [], totals: {}, usage: {} }
+
+  const stats = JSON.parse(readFileSync(statsPath, 'utf-8'))
+  const { modelUsage = {}, dailyModelTokens = [], dailyActivity = [] } = stats
+
+  // Model breakdown with cost calculations
+  const modelBreakdown = Object.entries(modelUsage).map(([model, usage]) => {
+    const pricing = MODEL_PRICING[model] || DEFAULT_PRICING
+    const inputCost = (usage.inputTokens / 1e6) * pricing.input
+    const outputCost = (usage.outputTokens / 1e6) * pricing.output
+    const cacheReadCost = (usage.cacheReadInputTokens / 1e6) * pricing.cacheRead
+    const cacheSavings = (usage.cacheReadInputTokens / 1e6) * (pricing.input - pricing.cacheRead)
+    return { model, inputCost, outputCost, cacheReadCost, cacheSavings, ... }
+  })
+
+  // Billing period (monthly from first usage date)
+  const firstDate = dailyActivity[0]?.date
+  const startDay = new Date(firstDate).getDate()
+  // ... compute periodStart, periodEnd, daysRemaining
+
+  return { daily: dailyTokens, totals, usage: { todayTokens, periodTokens, ... } }
+}
+```
+
+### stats-cache.json schema
+
+```typescript
+interface StatsCache {
+  version: 1
+  lastComputedDate: string // "2026-02-28"
+  dailyActivity: Array<{
+    date: string
+    messageCount: number
+    sessionCount: number
+    toolCallCount: number
+  }>
+  dailyModelTokens: Array<{
+    date: string
+    tokensByModel: Record<string, number> // model -> output tokens
+  }>
+  modelUsage: Record<string, {
+    inputTokens: number
+    outputTokens: number
+    cacheReadInputTokens: number    // billed at 1/8 input price
+    cacheCreationInputTokens: number // billed at 1.25x input price
+    webSearchRequests: number
+    costUSD: number    // always 0 (not computed by Claude Code)
+    contextWindow: number
+  }>
+}
+```
+
+### Per-message JSONL schema (for real-time tracking)
+
+```typescript
+// Each line in ~/.claude/projects/{hash}/{session}.jsonl
+interface SessionEntry {
+  type: "assistant" | "user"
+  message: {
+    model: string
+    usage: {
+      input_tokens: number
+      output_tokens: number
+      cache_creation_input_tokens: number
+      cache_read_input_tokens: number
+      cache_creation: {
+        ephemeral_5m_input_tokens: number
+        ephemeral_1h_input_tokens: number
+      }
+    }
+  }
+  timestamp: string // ISO-8601
+  sessionId: string
+}
+```
+
+## When to Use
+
+- Building a Claude Code dashboard or analytics panel
+- Tracking AI usage costs across projects
+- Demonstrating cache savings from context engineering
+- Computing billing period boundaries and reset dates
+- Monitoring daily token consumption trends
+
+## When NOT to Use
+
+- Need real-time token counting during a session (use JSONL instead)
+- Tracking non-Claude models (stats-cache only covers Claude models + any models Claude Code uses)
+- Need official billing data (use Anthropic Console API for that)
+
+## Common Mistakes
+
+- **stats-cache is stale**: It's updated by Claude Code, not your app. `lastComputedDate` may be yesterday. For today's data, parse the latest session JSONL.
+- **tokensByModel is OUTPUT tokens only**: The `dailyModelTokens.tokensByModel` values are output token counts, not total. For full breakdown, use `modelUsage`.
+- **costUSD is always 0**: Claude Code doesn't compute costs. You must calculate from per-model pricing.
+- **Cache tokens are massive**: cache_read can be billions (10^9). Use proper number formatting (B/M/K suffixes).
+- **Model names include dates**: `claude-sonnet-4-5-20250929` — strip the date suffix for display.
+
+## References
+
+- Claude API Pricing: https://docs.anthropic.com/en/docs/about-claude/pricing
+- stats-cache.json location: `~/.claude/stats-cache.json`
+- Session JSONL location: `~/.claude/projects/{project-hash}/{session-id}.jsonl`
+- Contributed from: claude-mission-control Token Analytics feature