@relipa/ai-flow-kit 0.0.1

package/scripts/hooks/session-start.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook for ai-flow-kit
+ * Injects:
+ *   1. using-superpowers skill content
+ *   2. Active ticket context + gate workflow (if context exists)
+ * Cross-platform replacement for the bash session-start hook.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// This script lives at .claude/hooks/session-start.js
+// Project root is 3 levels up
+const projectRoot = path.resolve(__dirname, '..', '..', '..');
+const skillPath = path.join(projectRoot, '.claude', 'skills', 'using-superpowers', 'SKILL.md');
+const contextPath = path.join(projectRoot, '.claude', 'context', 'current.json');
+
+// ── 1. Load superpowers skill ──────────────────────────────────
+let skillContent = '';
+try {
+    skillContent = fs.readFileSync(skillPath, 'utf-8');
+} catch (_) {
+    // Skill file missing — continue without it
+}
+
+// ── 2. Load active ticket context ──────────────────────────────
+let contextBlock = '';
+try {
+    if (fs.existsSync(contextPath)) {
+        const ctx = JSON.parse(fs.readFileSync(contextPath, 'utf-8'));
+        if (ctx.taskId && ctx.title) {
+            contextBlock = buildContextPrompt(ctx);
+        }
+    }
+} catch (_) {
+    // Context missing or invalid — continue without it
+}
+
+// ── 3. Combine and output ──────────────────────────────────────
+const parts = [];
+
+if (skillContent) {
+    parts.push(`<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${skillContent}\n\n</EXTREMELY_IMPORTANT>`);
+}
+
+if (contextBlock) {
+    parts.push(contextBlock);
+}
+
+const combined = parts.join('\n\n');
+
+// Escape for JSON string embedding
+const escaped = combined
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+
+process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: escaped
+    }
+}));
+
+process.exit(0);
+
+// ── Helper ─────────────────────────────────────────────────────
+
+function buildContextPrompt(ctx) {
+    const taskType = ctx.taskType || 'feature';
+
+    const lines = [];
+    lines.push('<ACTIVE_TASK>');
+    lines.push(`**Active Ticket:** ${ctx.taskId} — ${ctx.title}`);
+    lines.push(`**Type:** ${taskType}`);
+    lines.push(`**Status:** ${ctx.status || 'Unknown'}`);
+    lines.push(`**Assignee:** ${ctx.assignee || 'Unknown'}`);
+    lines.push('');
+
+    if (ctx.description) {
+        lines.push('**Description:**');
+        lines.push(ctx.description.substring(0, 2000));
+        lines.push('');
+    }
+
+    if (ctx.acceptanceCriteria && ctx.acceptanceCriteria.length > 0) {
+        lines.push('**Acceptance Criteria:**');
+        for (const c of ctx.acceptanceCriteria) {
+            lines.push(`- ${c}`);
+        }
+        lines.push('');
+    }
+
+    if (ctx.comments && ctx.comments.length > 0) {
+        lines.push(`**Comments (${ctx.comments.length}):**`);
+        // Include last 5 comments to keep context manageable
+        const recent = ctx.comments.slice(-5);
+        for (const c of recent) {
+            lines.push(c);
+            lines.push('');
+        }
+    }
+
+    if (ctx.context && ctx.context.files && ctx.context.files.length > 0) {
+        lines.push('**Related Files:**');
+        for (const f of ctx.context.files) {
+            lines.push(`- \`${f}\``);
+        }
+        lines.push('');
+    }
+
+    // ── Gate workflow instruction ──
+    lines.push('---');
+    lines.push('');
+    lines.push('**AUTO-START GATE 1: You MUST begin analyzing this ticket immediately.**');
+    lines.push('');
+    lines.push(`INVOKE the \`validate-ticket\` skill NOW for ticket ${ctx.taskId}.`);
+    lines.push('');
+    lines.push('Gate 1 process:');
+    lines.push('1. Read the ticket context above');
+    lines.push('2. Read CLAUDE.md — understand project architecture and conventions');
+    lines.push('3. Read source code — identify related files, data flow, patterns');
+    lines.push('4. If anything is unclear — ask ONE question at a time');
+    lines.push('5. Output plan/' + ctx.taskId + '/requirement.md with:');
+    lines.push('   - Requirements summary');
+    lines.push('   - Source code analysis');
+    lines.push('   - Proposed solution and approach');
+    lines.push('   - Impact analysis');
+    lines.push('   - Effort estimate');
+    lines.push('   - Testing plan');
+    lines.push('6. Display GATE 1 prompt and wait for APPROVED');
+    lines.push('');
+    lines.push('DO NOT wait for the developer to ask. START NOW.');
+    lines.push('</ACTIVE_TASK>');
+
+    return lines.join('\n');
+}

package/scripts/init.js

@@ -0,0 +1,453 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { input } = require('@inquirer/prompts');
+
+const PKG_DIR = path.join(__dirname, '..');
+const PKG_VERSION = require('../package.json').version;
+
+// Map framework → language family for picking the right rules
+const FRAMEWORK_LANGUAGE = {
+    'laravel':      'php',
+    'spring-boot':  'java',
+    'reactjs':      'javascript',
+    'nextjs':       'javascript',
+    'vue-nuxt':     'javascript',
+};
+
+async function copyAssetsToVersion(versionDir, framework) {
+    // ── Skills: merge upstream + custom ──────────────────────────────
+    const upstreamSkills = path.join(PKG_DIR, 'upstream', 'skills');
+    const customSkills   = path.join(PKG_DIR, 'custom',   'skills');
+
+    await fs.ensureDir(path.join(versionDir, 'skills'));
+    if (await fs.pathExists(upstreamSkills)) {
+        await fs.copy(upstreamSkills, path.join(versionDir, 'skills'), { overwrite: true });
+    }
+    if (await fs.pathExists(customSkills)) {
+        await fs.copy(customSkills, path.join(versionDir, 'skills'), { overwrite: true });
+    }
+
+    // ── Rules: common first, then language-specific override ─────────
+    const rulesTarget    = path.join(versionDir, 'rules');
+    const commonRules    = path.join(PKG_DIR, 'custom', 'rules', 'common');
+    const allRules       = path.join(PKG_DIR, 'custom', 'rules');
+
+    await fs.ensureDir(rulesTarget);
+
+    // Copy common rules (language-agnostic) if the folder exists,
+    // otherwise fall back to copying everything at root level
+    if (await fs.pathExists(commonRules)) {
+        await fs.copy(commonRules, rulesTarget, { overwrite: true });
+    } else {
+        // Copy only .md files at root (skip sub-folders like java/, php/, javascript/)
+        const entries = await fs.readdir(allRules, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                await fs.copy(
+                    path.join(allRules, entry.name),
+                    path.join(rulesTarget, entry.name),
+                    { overwrite: true }
+                );
+            }
+        }
+    }
+
+    // Overlay language-specific rules on top
+    if (framework) {
+        const lang = FRAMEWORK_LANGUAGE[framework];
+        if (lang) {
+            const langRules = path.join(PKG_DIR, 'custom', 'rules', lang);
+            if (await fs.pathExists(langRules)) {
+                await fs.copy(langRules, rulesTarget, { overwrite: true });
+                console.log(chalk.gray(`  ✓ Applied ${lang} rules`));
+            }
+        }
+    }
+}
+
+async function updateSymlinks(projectDir, versionDir) {
+    const claudeDir = path.join(projectDir, '.claude');
+    await fs.emptyDir(claudeDir);
+    await fs.copy(path.join(versionDir, 'skills'), path.join(claudeDir, 'skills'), { overwrite: true });
+
+    const rulesDir = path.join(projectDir, '.rules');
+    await fs.emptyDir(rulesDir);
+    await fs.copy(path.join(versionDir, 'rules'), rulesDir, { overwrite: true });
+
+    // Setup SessionStart hook so superpowers auto-triggers on every session
+    await setupSuperpowersHook(projectDir, claudeDir);
+
+    await fs.writeJson(path.join(projectDir, '.aiflow', 'state.json'), {
+        current_version: PKG_VERSION,
+        framework: null,   // will be set after setupFramework
+    });
+}
+
+async function setupSuperpowersHook(_projectDir, claudeDir) {
+    // 1. Copy hook script into .claude/hooks/
+    const hooksDir = path.join(claudeDir, 'hooks');
+    await fs.ensureDir(hooksDir);
+
+    const hookSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-start.js');
+    const hookDest = path.join(hooksDir, 'session-start.js');
+    await fs.copy(hookSrc, hookDest, { overwrite: true });
+
+    // 2. Merge SessionStart hook into .claude/settings.json
+    const settingsFile = path.join(claudeDir, 'settings.json');
+    let settings = {};
+    if (await fs.pathExists(settingsFile)) {
+        settings = await fs.readJson(settingsFile).catch(() => ({}));
+    }
+
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+    // Remove any stale ai-flow-kit hook entry, then add fresh one
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+        h => !(h._aiflowKit)
+    );
+    settings.hooks.SessionStart.push({
+        _aiflowKit: true,   // marker so we can update it cleanly on re-init
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookDest.replace(/\\/g, '/')}"`,
+            }
+        ]
+    });
+
+    await fs.writeJson(settingsFile, settings, { spaces: 2 });
+    console.log(chalk.green(`✓ Superpowers SessionStart hook configured`));
+}
+
+/**
+ * Verify superpowers skills are present — auto-copied from upstream.
+ * Developer does NOT need to install superpowers separately.
+ */
+async function verifySuperpowersSkills(versionDir) {
+    const usingSuperpowers = path.join(versionDir, 'skills', 'using-superpowers', 'SKILL.md');
+    if (await fs.pathExists(usingSuperpowers)) {
+        console.log(chalk.green(`✓ Superpowers skills ready (built-in)`));
+    } else {
+        console.log(chalk.yellow(`! Superpowers skills missing — upstream folder may be empty`));
+    }
+}
+
+/**
+ * Setup CLAUDE.md for a framework.
+ * If multi=true (multiple frameworks), append instead of overwrite.
+ */
+async function setupFramework(projectDir, framework, multi = false) {
+    if (!framework) return;
+    const templatePath = path.join(PKG_DIR, 'custom', 'templates', `${framework}.md`);
+    if (!(await fs.pathExists(templatePath))) {
+        console.log(chalk.yellow(`! No template found for framework: ${framework}`));
+        return;
+    }
+
+    const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+
+    if (!multi) {
+        // Single framework → overwrite
+        await fs.copy(templatePath, claudeMdPath);
+    } else {
+        // Multiple frameworks → append with separator
+        const content = await fs.readFile(templatePath, 'utf-8');
+        const separator = `\n\n---\n\n`;
+        if (await fs.pathExists(claudeMdPath)) {
+            await fs.appendFile(claudeMdPath, separator + content);
+        } else {
+            await fs.writeFile(claudeMdPath, content);
+        }
+    }
+
+    console.log(chalk.green(`✓ CLAUDE.md updated for framework: ${framework}`));
+}
+
+async function setupAdapter(projectDir, adapter) {
+    if (!adapter) return;
+    const presetPath = path.join(PKG_DIR, 'custom', 'mcp-presets', `${adapter}.json`);
+    if (!(await fs.pathExists(presetPath))) {
+        console.log(chalk.yellow(`! No MCP preset found for adapter: ${adapter}`));
+        return;
+    }
+
+    const { mcpServers } = await fs.readJson(presetPath);
+    const serverKey    = Object.keys(mcpServers)[0];
+    const serverConfig = mcpServers[serverKey];
+
+    // ── Load existing credentials (same pattern as `aws configure`) ──
+    const credsFile = path.join(projectDir, '.aiflow', 'credentials.json');
+    let existingCreds = {};
+    if (await fs.pathExists(credsFile)) {
+        existingCreds = await fs.readJson(credsFile).catch(() => ({}));
+    }
+
+    console.log(chalk.cyan(`\nSetup MCP adapter for ${adapter}:`));
+    console.log(chalk.gray('Press Enter to keep existing value shown in [brackets]\n'));
+
+    const credentials = {};
+    for (const [envKey] of Object.entries(serverConfig.env)) {
+        const current = existingCreds[envKey];
+
+        // Show masked current value as default hint (like aws configure)
+        const hint = current
+            ? `[${maskSecret(current)}]`
+            : chalk.gray('[not set — required]');
+
+        let resolved = '';
+        while (true) {
+            const value = await input({
+                message: `${envKey} ${hint}:`,
+                default: '',
+            });
+
+            resolved = value.trim() || current || '';
+
+            if (resolved) break;
+
+            // Empty and no existing value → reject
+            console.log(chalk.red(`  ✗ ${envKey} is required. Please enter a value.`));
+        }
+
+        serverConfig.env[envKey] = resolved;
+        credentials[envKey] = resolved;
+    }
+
+    // ── Verify credentials against real API ──────────────────────────
+    console.log(chalk.cyan(`\nVerifying ${adapter} credentials...`));
+    const verifyResult = await verifyAdapterCredentials(adapter, credentials);
+    if (!verifyResult.ok) {
+        console.log(chalk.red(`✗ Verification failed: ${verifyResult.error}`));
+        console.log(chalk.yellow('  Credentials saved but may not work. Re-run `aiflow init --adapter ' + adapter + '` to update.'));
+    } else {
+        console.log(chalk.green(`✓ Credentials verified successfully`));
+    }
+
+    // ── 1. Save to Claude Desktop MCP config ─────────────────────────
+    const claudeConfigDir = path.join(
+        process.env.APPDATA ||
+        (process.platform === 'darwin'
+            ? process.env.HOME + '/Library/Application Support'
+            : process.env.HOME + '/.config'),
+        'Claude'
+    );
+    const mcpConfigFile = path.join(claudeConfigDir, 'claude_desktop_config.json');
+    let existingConfig = { mcpServers: {} };
+    if (await fs.pathExists(mcpConfigFile)) {
+        existingConfig = await fs.readJson(mcpConfigFile).catch(() => ({ mcpServers: {} }));
+    }
+    if (!existingConfig.mcpServers) existingConfig.mcpServers = {};
+    existingConfig.mcpServers[serverKey] = serverConfig;
+    await fs.ensureDir(path.dirname(mcpConfigFile));
+    await fs.writeJson(mcpConfigFile, existingConfig, { spaces: 2 });
+
+    // ── 2. Save locally as .mcp.json ─────────────────────────────────
+    await fs.writeJson(
+        path.join(projectDir, '.mcp.json'),
+        { mcpServers: { [serverKey]: serverConfig } },
+        { spaces: 2 }
+    );
+
+    // ── 3. Save credentials to .aiflow/credentials.json ──────────────
+    //    use.js will read from here when env vars are not set
+    Object.assign(existingCreds, credentials);
+    await fs.writeJson(credsFile, existingCreds, { spaces: 2 });
+
+    // ── 4. Ensure credentials.json is gitignored ──────────────────────
+    await ensureCredentialsGitignored(projectDir);
+
+    console.log(chalk.green(`✓ MCP configuration saved (global + local + credentials).`));
+}
+
+/**
+ * Verify adapter credentials by making a lightweight API call
+ */
+async function verifyAdapterCredentials(adapter, credentials) {
+    try {
+        if (adapter === 'backlog') {
+            return await verifyBacklog(credentials);
+        }
+        if (adapter === 'jira') {
+            return await verifyJira(credentials);
+        }
+        if (adapter === 'figma') {
+            return await verifyFigma(credentials);
+        }
+        // Unknown adapter — skip verification
+        return { ok: true };
+    } catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+
+function verifyBacklog(credentials) {
+    const https = require('https');
+    const apiKey   = credentials.BACKLOG_API_KEY;
+    const spaceKey = credentials.BACKLOG_SPACE_KEY;
+    const domain   = spaceKey.includes('.') ? spaceKey : `${spaceKey}.backlog.com`;
+
+    return new Promise((resolve) => {
+        const url = `https://${domain}/api/v2/users/myself?apiKey=${apiKey}`;
+        const req = https.get(url, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    const user = JSON.parse(data);
+                    resolve({ ok: true, user: user.name });
+                } else if (res.statusCode === 401) {
+                    resolve({ ok: false, error: 'Invalid API key' });
+                } else if (res.statusCode === 404) {
+                    resolve({ ok: false, error: `Space "${spaceKey}" not found` });
+                } else {
+                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
+                }
+            });
+        });
+        req.on('error', (err) => resolve({ ok: false, error: err.message }));
+        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
+    });
+}
+
+function verifyJira(credentials) {
+    const https = require('https');
+    const { JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN } = credentials;
+    const auth = Buffer.from(`${JIRA_EMAIL}:${JIRA_API_TOKEN}`).toString('base64');
+
+    return new Promise((resolve) => {
+        const options = {
+            hostname: `${JIRA_DOMAIN}.atlassian.net`,
+            path: '/rest/api/3/myself',
+            headers: { 'Authorization': `Basic ${auth}`, 'Accept': 'application/json' },
+        };
+        const req = https.get(options, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    resolve({ ok: true });
+                } else if (res.statusCode === 401) {
+                    resolve({ ok: false, error: 'Invalid email or API token' });
+                } else {
+                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
+                }
+            });
+        });
+        req.on('error', (err) => resolve({ ok: false, error: err.message }));
+        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
+    });
+}
+
+function verifyFigma(credentials) {
+    const https = require('https');
+    const { FIGMA_API_TOKEN } = credentials;
+
+    return new Promise((resolve) => {
+        const options = {
+            hostname: 'api.figma.com',
+            path: '/v1/me',
+            headers: { 'Authorization': `Bearer ${FIGMA_API_TOKEN}` },
+        };
+        const req = https.get(options, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    const user = JSON.parse(data);
+                    resolve({ ok: true, user: user.name || user.email });
+                } else if (res.statusCode === 403 || res.statusCode === 401) {
+                    resolve({ ok: false, error: 'Invalid Figma API token' });
+                } else {
+                    resolve({ ok: false, error: `HTTP ${res.statusCode}` });
+                }
+            });
+        });
+        req.on('error', (err) => resolve({ ok: false, error: err.message }));
+        req.setTimeout(8000, () => { req.destroy(); resolve({ ok: false, error: 'Connection timeout' }); });
+    });
+}
+
+/**
+ * Ensure `.aiflow/credentials.json` is listed in the project's .gitignore.
+ * Appends the entry if missing, creates .gitignore if it doesn't exist.
+ */
+async function ensureCredentialsGitignored(projectDir) {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    const entry = '.aiflow/credentials.json';
+
+    let content = '';
+    if (await fs.pathExists(gitignorePath)) {
+        content = await fs.readFile(gitignorePath, 'utf-8');
+    }
+
+    // Check if already ignored (exact line match)
+    const lines = content.split('\n').map(l => l.trim());
+    if (lines.includes(entry)) return;
+
+    // Append with a trailing newline
+    const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+    await fs.appendFile(gitignorePath, `${separator}${entry}\n`);
+    console.log(chalk.yellow(`  ⚠ Added ${entry} to .gitignore (contains API keys)`));
+}
+
+/**
+ * Mask a secret for display: show first 4 chars + *** + last 4 chars
+ * e.g. "sAgkcqW5Bq...K5xnFvkQ7" → "sAgk***vkQ7"
+ */
+function maskSecret(value) {
+    if (!value || value.length <= 8) return '***';
+    return `${value.slice(0, 4)}***${value.slice(-4)}`;
+}
+
+module.exports = async function init(options) {
+    const projectDir = process.cwd();
+    const aiflowDir  = path.join(projectDir, '.aiflow');
+    // Use primary (first) framework for language-specific rules selection
+    const frameworks = options.frameworks || (options.framework ? [options.framework] : []);
+    const adapters   = options.adapters   || (options.adapter   ? [options.adapter]   : []);
+    const primaryFramework = frameworks[0] || null;
+    const versionDir = path.join(aiflowDir, 'versions', PKG_VERSION);
+
+    try {
+        console.log(chalk.blue(`Initializing ai-flow-kit (v${PKG_VERSION})...`));
+        if (frameworks.length) console.log(chalk.gray(`  Frameworks: ${frameworks.join(', ')}`));
+        if (adapters.length)   console.log(chalk.gray(`  Adapters:   ${adapters.join(', ')}`));
+
+        await fs.ensureDir(versionDir);
+        await copyAssetsToVersion(versionDir, primaryFramework);
+        await verifySuperpowersSkills(versionDir);
+        await updateSymlinks(projectDir, versionDir);
+
+        // Setup each framework (CLAUDE.md = last one wins, or merged)
+        for (const fw of frameworks) {
+            await setupFramework(projectDir, fw, frameworks.length > 1);
+        }
+
+        // Setup each adapter
+        for (const adapter of adapters) {
+            await setupAdapter(projectDir, adapter);
+        }
+
+        // Persist all frameworks + adapters in state
+        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+        if (await fs.pathExists(stateFile)) {
+            const state = await fs.readJson(stateFile);
+            state.frameworks = frameworks;
+            state.adapters   = adapters;
+            await fs.writeJson(stateFile, state);
+        }
+
+        console.log(chalk.green('\n✨ Initialized AI Flow Kit successfully!'));
+        console.log(chalk.blue('\n' + '─'.repeat(62)));
+        console.log(chalk.bold.white('  Next steps:'));
+        console.log(`  ${chalk.green('aiflow use PROJ-33')}    ${chalk.gray('← load ticket context')}`);
+        console.log(`  ${chalk.green('claude')}                ${chalk.gray('← AI auto-starts analyzing requirement')}`);
+        console.log(chalk.blue('─'.repeat(62)));
+        console.log(chalk.gray(`  Full guide: ${chalk.green('aiflow guide')} | Command list: ${chalk.green('aiflow guide --commands')}`));
+        console.log(chalk.blue('─'.repeat(62)) + '\n');
+    } catch (err) {
+        console.error(chalk.red(`Error during initialization: ${err.message}`));
+    }
+};