@relipa/ai-flow-kit 0.0.4-beta.2 → 0.0.4

package/scripts/use.js

@@ -1,594 +1,594 @@
-const fs = require('fs-extra');
-const path = require('path');
-const chalk = require('chalk');
-const https = require('https');
-const { select, input } = require('@inquirer/prompts');
-
-const PROJECT_DIR = process.cwd();
-const AIFLOW_DIR = path.join(PROJECT_DIR, '.aiflow');
-const STATE_FILE = path.join(AIFLOW_DIR, 'state.json');
-const CONTEXT_DIR = path.join(PROJECT_DIR, '.claude', 'context');
-
-// ──────────────────────────────────────────────────────────────
-// Entry point
-// ──────────────────────────────────────────────────────────────
-
-module.exports = async function use(target, options = {}) {
-    if (!(await fs.pathExists(STATE_FILE))) {
-        console.log(chalk.red('Project is not initialized. Run `aiflow init` first.'));
-        return;
-    }
-
-    // ── Manual entry ──
-    if (options.manual) {
-        return await manualContext();
-    }
-
-    // ── Load from local file ──
-    if (options.file) {
-        return await loadFromFile(options.file, options);
-    }
-
-    // ── No target → version switcher ──
-    if (!target) {
-        return await switchVersion();
-    }
-
-    // ── Detect target type and dispatch ──
-    if (isVersion(target)) {
-        return await switchVersion(target);
-    }
-
-    if (isTicketId(target)) {
-        const adapter = await resolveTicketAdapter();
-        if (adapter === 'jira') return await loadFromJira(target, options);
-        return await loadFromBacklog(target, options);
-    }
-
-    if (isBacklogUrl(target)) {
-        const id = extractBacklogId(target);
-        return await loadFromBacklog(id, options);
-    }
-
-    // ── Fallback: try Backlog then manual ──
-    console.log(chalk.yellow(`Cannot detect format for: ${target}`));
-    console.log(chalk.gray('Supported: PROJ-33, APP-123, version number, --manual'));
-    return await manualContext();
-};
-
-// ──────────────────────────────────────────────────────────────
-// Detectors
-// ──────────────────────────────────────────────────────────────
-
-function isVersion(s) {
-    return /^\d+\.\d+\.\d+$/.test(s);
-}
-
-/** Both Backlog and Jira use the same PROJECT-NUMBER format. */
-function isTicketId(s) {
-    return /^[A-Z][A-Z0-9_]+-\d+$/.test(s);
-}
-
-/**
- * Determine which adapter to use for a ticket ID based on configured adapters
- * in state.json. Falls back to backlog if both or neither are configured.
- */
-async function resolveTicketAdapter() {
-    try {
-        if (await fs.pathExists(STATE_FILE)) {
-            const state = await fs.readJson(STATE_FILE);
-            const adapters = state.adapters || [];
-            if (adapters.includes('jira') && !adapters.includes('backlog')) {
-                return 'jira';
-            }
-        }
-    } catch (_) { /* ignore */ }
-    return 'backlog';
-}
-
-function isBacklogUrl(s) {
-    return s.includes('backlog.com/view/') || s.includes('backlogtool.com/view/');
-}
-
-function extractBacklogId(url) {
-    const match = url.match(/\/view\/([A-Z][A-Z0-9_]+-\d+)/);
-    return match ? match[1] : null;
-}
-
-// ──────────────────────────────────────────────────────────────
-// Version switcher (original behavior)
-// ──────────────────────────────────────────────────────────────
-
-async function switchVersion(versionReq) {
-    const versionsDir = path.join(AIFLOW_DIR, 'versions');
-    if (!(await fs.pathExists(versionsDir))) {
-        console.log(chalk.red('No versions directory found.'));
-        return;
-    }
-
-    const available = await fs.readdir(versionsDir);
-    if (!available.length) {
-        console.log(chalk.red('No installed versions found.'));
-        return;
-    }
-
-    let targetVersion = versionReq;
-    if (!targetVersion) {
-        targetVersion = await select({
-            message: 'Select version to use:',
-            choices: available.map(v => ({ name: `v${v}`, value: v }))
-        });
-    }
-
-    if (!available.includes(targetVersion)) {
-        console.log(chalk.red(`Version v${targetVersion} is not installed.`));
-        return;
-    }
-
-    console.log(chalk.blue(`Switching to v${targetVersion}...`));
-    const versionDir = path.join(versionsDir, targetVersion);
-
-    const claudeDir = path.join(PROJECT_DIR, '.claude');
-    await fs.emptyDir(claudeDir);
-    await fs.copy(path.join(versionDir, 'skills'), path.join(claudeDir, 'skills'), { overwrite: true });
-
-    const rulesDir = path.join(PROJECT_DIR, '.rules');
-    await fs.emptyDir(rulesDir);
-    await fs.copy(path.join(versionDir, 'rules'), rulesDir, { overwrite: true });
-
-    const state = await fs.readJson(STATE_FILE);
-    state.current_version = targetVersion;
-    await fs.writeJson(STATE_FILE, state);
-
-    console.log(chalk.green(`✓ Switched to v${targetVersion}.`));
-}
-
-// ──────────────────────────────────────────────────────────────
-// Backlog context loader
-// ──────────────────────────────────────────────────────────────
-
-async function loadFromBacklog(issueKey, options = {}) {
-    const creds = await loadCredentials();
-    const apiKey   = process.env.BACKLOG_API_KEY   || creds.BACKLOG_API_KEY;
-    const spaceKey = process.env.BACKLOG_SPACE_KEY  || creds.BACKLOG_SPACE_KEY
-                  || process.env.BACKLOG_DOMAIN      || creds.BACKLOG_DOMAIN;
-
-    if (!apiKey || !spaceKey) {
-        console.log(chalk.yellow('⚠ Backlog credentials not set.'));
-        console.log(chalk.gray('Run: aiflow init --adapter backlog'));
-        console.log(chalk.gray('Or set environment variables:'));
-        console.log(chalk.gray('  BACKLOG_API_KEY=your-api-key'));
-        console.log(chalk.gray('  BACKLOG_SPACE_KEY=your-space (e.g. mycompany)'));
-        console.log(chalk.gray('\nFalling back to manual entry...\n'));
-        return await manualContext(issueKey);
-    }
-
-    // spaceKey can be full domain (mycompany.backlog.com) or just the space (mycompany)
-    const domain = spaceKey.includes('.') ? spaceKey : `${spaceKey}.backlog.com`;
-
-    console.log(chalk.blue(`Fetching context from Backlog: ${issueKey}...`));
-
-    try {
-        // Default: description only. Comments loaded only when explicitly requested.
-        const loadComments = options.withComments || options.commentsLast != null || options.commentsFrom != null;
-        const [issue, rawComments] = await Promise.all([
-            fetchBacklogIssue(domain, apiKey, issueKey),
-            loadComments
-                ? fetchBacklogComments(domain, apiKey, issueKey)
-                : Promise.resolve([]),
-        ]);
-
-        const comments = filterComments(rawComments, options);
-        const context = buildContextFromBacklog(issue, comments, issueKey, domain);
-        await saveContext(context, options.save);
-        printContextSummary(context);
-        await suggestNextStep(context);
-    } catch (err) {
-        console.log(chalk.yellow(`⚠ Could not fetch from Backlog: ${err.message}`));
-        console.log(chalk.gray('Falling back to manual entry...\n'));
-        await manualContext(issueKey);
-    }
-}
-
-/**
- * Filter comments array based on CLI options:
- *   --no-comments      → empty array (already handled upstream, but safe here too)
- *   --comments-last N  → last N comments
- *   --comments-from N  → comments starting at index N (0-based)
- *   (default)          → all comments
- */
-function filterComments(comments, options = {}) {
-    if (!comments || !comments.length) return [];
-
-    if (options.commentsLast != null) {
-        const n = Math.max(1, options.commentsLast);
-        return comments.slice(-n);
-    }
-
-    if (options.commentsFrom != null) {
-        const from = Math.max(0, options.commentsFrom);
-        return comments.slice(from);
-    }
-
-    return comments;
-}
-
-/**
- * Generic Backlog GET helper
- */
-function backlogGet(url) {
-    return new Promise((resolve, reject) => {
-        https.get(url, (res) => {
-            let data = '';
-            res.on('data', chunk => data += chunk);
-            res.on('end', () => {
-                if (res.statusCode !== 200) {
-                    reject(new Error(`HTTP ${res.statusCode}: ${data}`));
-                    return;
-                }
-                try {
-                    resolve(JSON.parse(data));
-                } catch (e) {
-                    reject(new Error('Invalid JSON response from Backlog'));
-                }
-            });
-        }).on('error', reject);
-    });
-}
-
-/**
- * Fetch issue detail from Backlog REST API
- */
-function fetchBacklogIssue(domain, apiKey, issueKey) {
-    return backlogGet(`https://${domain}/api/v2/issues/${issueKey}?apiKey=${apiKey}`);
-}
-
-/**
- * Fetch ALL comments of an issue from Backlog REST API (paginated, max 100/page).
- */
-async function fetchBacklogComments(domain, apiKey, issueKey) {
-    const all = [];
-    let offset = 0;
-    try {
-        while (true) {
-            const batch = await backlogGet(
-                `https://${domain}/api/v2/issues/${issueKey}/comments?apiKey=${apiKey}&count=100&offset=${offset}&order=asc`
-            );
-            all.push(...batch);
-            if (batch.length < 100) break;
-            offset += 100;
-        }
-    } catch (_) {
-        // comments are optional — don't fail the whole fetch
-    }
-    return all;
-}
-
-/**
- * Transform Backlog API response + comments to internal context format
- */
-function buildContextFromBacklog(issue, comments, issueKey, domain) {
-    const type = detectTaskType(issue);
-
-    // Format comments into readable text for AI context
-    const formattedComments = (comments || [])
-        .filter(c => c.content && c.content.trim())
-        .map(c => {
-            const author = c.createdUser?.name || 'Unknown';
-            const date   = c.created ? new Date(c.created).toLocaleDateString('vi-VN') : '';
-            return `[${author} - ${date}]\n${c.content.trim()}`;
-        });
-
-    const allText = [issue.description || '', ...formattedComments.map(c => c)].join('\n');
-
-    return {
-        taskId: issueKey,
-        taskType: type,
-        title: issue.summary || '',
-        description: issue.description || '',
-        status: issue.status?.name || 'Unknown',
-        priority: issue.priority?.name || 'Unknown',
-        assignee: issue.assignee?.name || 'Unassigned',
-
-        // Comments from all participants
-        comments: formattedComments,
-        commentCount: formattedComments.length,
-
-        // Parse checklist-style acceptance criteria from description
-        acceptanceCriteria: extractCriteria(issue.description || ''),
-
-        // Related files mentioned anywhere in ticket
-        context: {
-            files: extractFiles(allText),
-            mentionedServices: [],
-            relatedTickets: extractRelatedTickets(allText),
-        },
-
-        metadata: {
-            created: issue.created,
-            updated: issue.updated,
-            loadedFrom: 'backlog',
-            adapter: 'backlog',
-            sourceUrl: `https://${domain}/view/${issueKey}`,
-        }
-    };
-}
-
-// ──────────────────────────────────────────────────────────────
-// Jira context loader
-// ──────────────────────────────────────────────────────────────
-
-async function loadFromJira(issueKey, options = {}) {
-    const creds = await loadCredentials();
-    const apiToken = process.env.JIRA_API_TOKEN || creds.JIRA_API_TOKEN;
-    const email    = process.env.JIRA_EMAIL      || creds.JIRA_EMAIL;
-    const domain   = process.env.JIRA_DOMAIN     || creds.JIRA_DOMAIN;
-
-    if (!apiToken || !email || !domain) {
-        console.log(chalk.yellow('⚠ Jira credentials not set.'));
-        console.log(chalk.gray('Run: aiflow init --adapter jira'));
-        console.log(chalk.gray('Or set environment variables: JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN'));
-        console.log(chalk.gray('\nFalling back to manual entry...\n'));
-        return await manualContext(issueKey);
-    }
-
-    console.log(chalk.blue(`Fetching context from Jira: ${issueKey}...`));
-
-    try {
-        const issue = await fetchJiraIssue(domain, email, apiToken, issueKey);
-        const context = buildContextFromJira(issue, issueKey, domain);
-        await saveContext(context, options.save);
-        printContextSummary(context);
-        await suggestNextStep(context);
-    } catch (err) {
-        console.log(chalk.yellow(`⚠ Could not fetch from Jira: ${err.message}`));
-        console.log(chalk.gray('Falling back to manual entry...\n'));
-        await manualContext(issueKey);
-    }
-}
-
-function fetchJiraIssue(domain, email, apiToken, issueKey) {
-    return new Promise((resolve, reject) => {
-        const auth = Buffer.from(`${email}:${apiToken}`).toString('base64');
-        const url = `https://${domain}.atlassian.net/rest/api/3/issue/${issueKey}`;
-        const options = {
-            headers: {
-                'Authorization': `Basic ${auth}`,
-                'Accept': 'application/json'
-            }
-        };
-
-        https.get(url, options, (res) => {
-            let data = '';
-            res.on('data', chunk => data += chunk);
-            res.on('end', () => {
-                if (res.statusCode !== 200) {
-                    reject(new Error(`HTTP ${res.statusCode}: ${data}`));
-                    return;
-                }
-                try {
-                    resolve(JSON.parse(data));
-                } catch (e) {
-                    reject(new Error('Invalid JSON response from Jira'));
-                }
-            });
-        }).on('error', reject);
-    });
-}
-
-function buildContextFromJira(issue, issueKey, domain) {
-    const fields = issue.fields || {};
-    const type = detectTaskTypeFromString(fields.issuetype?.name || '');
-
-    return {
-        taskId: issueKey,
-        taskType: type,
-        title: fields.summary || '',
-        description: fields.description?.content?.map(block =>
-            block.content?.map(c => c.text).join('') || ''
-        ).join('\n') || '',
-        status: fields.status?.name || 'Unknown',
-        priority: fields.priority?.name || 'Unknown',
-        assignee: fields.assignee?.displayName || 'Unassigned',
-        acceptanceCriteria: extractCriteria(fields.description?.toString() || ''),
-        context: {
-            files: [],
-            relatedTickets: []
-        },
-        metadata: {
-            created: fields.created,
-            updated: fields.updated,
-            loadedFrom: 'jira',
-            adapter: 'jira',
-            sourceUrl: `https://${domain}.atlassian.net/browse/${issueKey}`
-        }
-    };
-}
-
-// ──────────────────────────────────────────────────────────────
-// Manual context entry
-// ──────────────────────────────────────────────────────────────
-
-async function manualContext(prefillId = '') {
-    console.log(chalk.cyan('\nManual Context Entry\n'));
-
-    const taskId = await input({
-        message: 'Ticket ID (e.g. PROJ-33):',
-        default: prefillId
-    });
-
-    const title = await input({ message: 'Title:' });
-    const description = await input({ message: 'Description (brief):' });
-    const taskType = await select({
-        message: 'Task type:',
-        choices: [
-            { name: '🐛 Bug Fix', value: 'bug-fix' },
-            { name: '✨ Feature', value: 'feature' },
-            { name: '🔍 Investigation', value: 'investigation' },
-            { name: '♻️  Refactor', value: 'refactor' },
-            { name: '📊 Impact Analysis', value: 'impact-analysis' }
-        ]
-    });
-
-    const context = {
-        taskId,
-        taskType,
-        title,
-        description,
-        status: 'In Progress',
-        acceptanceCriteria: [],
-        context: { files: [], relatedTickets: [] },
-        metadata: {
-            created: new Date().toISOString(),
-            loadedFrom: 'manual',
-            adapter: 'manual'
-        }
-    };
-
-    await saveContext(context);
-    printContextSummary(context);
-    await suggestNextStep(context);
-}
-
-// ──────────────────────────────────────────────────────────────
-// Load from JSON file
-// ──────────────────────────────────────────────────────────────
-
-async function loadFromFile(filePath, options = {}) {
-    if (!(await fs.pathExists(filePath))) {
-        console.log(chalk.red(`File not found: ${filePath}`));
-        return;
-    }
-    const context = await fs.readJson(filePath);
-    await saveContext(context, options.save);
-    printContextSummary(context);
-    await suggestNextStep(context);
-}
-
-// ──────────────────────────────────────────────────────────────
-// Credentials loader (reads .aiflow/credentials.json as fallback)
-// ──────────────────────────────────────────────────────────────
-
-async function loadCredentials() {
-    const credsFile = path.join(PROJECT_DIR, '.aiflow', 'credentials.json');
-    if (await fs.pathExists(credsFile)) {
-        return await fs.readJson(credsFile).catch(() => ({}));
-    }
-    return {};
-}
-
-// ──────────────────────────────────────────────────────────────
-// Context persistence
-// ──────────────────────────────────────────────────────────────
-
-async function saveContext(context, saveName) {
-    await fs.ensureDir(CONTEXT_DIR);
-    await fs.ensureDir(path.join(CONTEXT_DIR, 'history'));
-
-    // Save as current
-    await fs.writeJson(path.join(CONTEXT_DIR, 'current.json'), context, { spaces: 2 });
-
-    // Save to history
-    const histFile = path.join(CONTEXT_DIR, 'history', `${context.taskId || 'manual'}.json`);
-    await fs.writeJson(histFile, context, { spaces: 2 });
-
-    // Save named snapshot if requested
-    if (saveName) {
-        const namedFile = path.join(CONTEXT_DIR, 'history', `${saveName}.json`);
-        await fs.writeJson(namedFile, context, { spaces: 2 });
-        console.log(chalk.gray(`  Context also saved as: ${saveName}`));
-    }
-
-    // Update state
-    if (await fs.pathExists(STATE_FILE)) {
-        const state = await fs.readJson(STATE_FILE);
-        state.current_context = context.taskId;
-        state.current_context_type = context.taskType;
-        await fs.writeJson(STATE_FILE, state);
-    }
-}
-
-// ──────────────────────────────────────────────────────────────
-// Helpers
-// ──────────────────────────────────────────────────────────────
-
-function detectTaskType(issue) {
-    const name = issue.issueType?.name || issue.type?.name || '';
-    const summary = issue.summary || '';
-    return detectTaskTypeFromString(name || summary);
-}
-
-function detectTaskTypeFromString(text) {
-    const lower = text.toLowerCase();
-    if (['bug', 'defect', 'バグ'].some(k => lower.includes(k))) return 'bug-fix';
-    if (['task', 'story', 'feature', 'タスク'].some(k => lower.includes(k))) return 'feature';
-    if (['research', 'investigation', '調査'].some(k => lower.includes(k))) return 'investigation';
-    return 'bug-fix'; // default for unknown
-}
-
-function extractCriteria(text) {
-    const lines = text.split('\n');
-    return lines
-        .filter(l => l.trim().match(/^[-*•]|^\d+\./))
-        .map(l => l.replace(/^[-*•\d.]+\s*/, '').trim())
-        .filter(l => l.length > 0)
-        .slice(0, 10);
-}
-
-function extractFiles(text) {
-    const matches = text.match(/[\w/]+\.(php|js|ts|vue|jsx|tsx|css|html)/g) || [];
-    return [...new Set(matches)];
-}
-
-function extractRelatedTickets(text) {
-    const matches = text.match(/[A-Z][A-Z0-9_]+-\d+/g) || [];
-    return [...new Set(matches)];
-}
-
-function printContextSummary(context) {
-    console.log(chalk.green('\n✓ Context loaded\n'));
-    console.log(`  ${chalk.white('Ticket:')}   ${context.taskId}`);
-    console.log(`  ${chalk.white('Type:')}     ${context.taskType}`);
-    console.log(`  ${chalk.white('Title:')}    ${context.title.substring(0, 70)}`);
-    console.log(`  ${chalk.white('Status:')}   ${context.status}`);
-    console.log(`  ${chalk.white('Assignee:')} ${context.assignee}`);
-    if (context.description) {
-        console.log(`  ${chalk.white('Desc:')}     ${context.description.substring(0, 80)}...`);
-    }
-    if (context.acceptanceCriteria?.length) {
-        console.log(`  ${chalk.white('Criteria:')} ${context.acceptanceCriteria.length} item(s)`);
-    }
-    if (context.commentCount > 0) {
-        console.log(`  ${chalk.white('Comments:')} ${context.commentCount} comment(s) loaded`);
-    }
-    console.log();
-}
-
-async function suggestNextStep(context) {
-    let aiTools = ['claude']; // Default
-    try {
-        if (await fs.pathExists(STATE_FILE)) {
-            const state = await fs.readJson(STATE_FILE);
-            if (state.aiTools && state.aiTools.length) {
-                aiTools = state.aiTools;
-            }
-        }
-    } catch (_) {}
-
-    console.log(chalk.cyan('\nNext Steps:'));
-    
-    if (aiTools.includes('claude')) {
-        console.log(`  ${chalk.white('1. Claude:')} Run ${chalk.bold.green('claude start')} in terminal. ${chalk.gray('(Quickest way to start)')}`);
-    }
-    
-    if (aiTools.includes('cursor')) {
-        console.log(`  ${chalk.white('2. Cursor:')} Open Cursor Chat ${chalk.gray('(Ctrl+L)')}.`);
-    }
-    
-    if (aiTools.includes('gemini')) {
-        console.log(`  ${chalk.white('3. Gemini:')} Open Gemini and load project context.`);
-    }
-
-    console.log(`\n  ${chalk.yellow('Note:')} If the AI does not start automatically, type ${chalk.bold.green('"Gate 1"')} or ${chalk.bold.green('"Analyze ticket"')} to begin.`);
-    console.log();
-}
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const https = require('https');
+const { select, input } = require('@inquirer/prompts');
+
+const PROJECT_DIR = process.cwd();
+const AIFLOW_DIR = path.join(PROJECT_DIR, '.aiflow');
+const STATE_FILE = path.join(AIFLOW_DIR, 'state.json');
+const CONTEXT_DIR = path.join(PROJECT_DIR, '.aiflow', 'context');
+
+// ──────────────────────────────────────────────────────────────
+// Entry point
+// ──────────────────────────────────────────────────────────────
+
+module.exports = async function use(target, options = {}) {
+    if (!(await fs.pathExists(STATE_FILE))) {
+        console.log(chalk.red('Project is not initialized. Run `aiflow init` first.'));
+        return;
+    }
+
+    // ── Manual entry ──
+    if (options.manual) {
+        return await manualContext();
+    }
+
+    // ── Load from local file ──
+    if (options.file) {
+        return await loadFromFile(options.file, options);
+    }
+
+    // ── No target → version switcher ──
+    if (!target) {
+        return await switchVersion();
+    }
+
+    // ── Detect target type and dispatch ──
+    if (isVersion(target)) {
+        return await switchVersion(target);
+    }
+
+    if (isTicketId(target)) {
+        const adapter = await resolveTicketAdapter();
+        if (adapter === 'jira') return await loadFromJira(target, options);
+        return await loadFromBacklog(target, options);
+    }
+
+    if (isBacklogUrl(target)) {
+        const id = extractBacklogId(target);
+        return await loadFromBacklog(id, options);
+    }
+
+    // ── Fallback: try Backlog then manual ──
+    console.log(chalk.yellow(`Cannot detect format for: ${target}`));
+    console.log(chalk.gray('Supported: PROJ-33, APP-123, version number, --manual'));
+    return await manualContext();
+};
+
+// ──────────────────────────────────────────────────────────────
+// Detectors
+// ──────────────────────────────────────────────────────────────
+
+function isVersion(s) {
+    return /^\d+\.\d+\.\d+$/.test(s);
+}
+
+/** Both Backlog and Jira use the same PROJECT-NUMBER format. */
+function isTicketId(s) {
+    return /^[A-Z][A-Z0-9_]+-\d+$/.test(s);
+}
+
+/**
+ * Determine which adapter to use for a ticket ID based on configured adapters
+ * in state.json. Falls back to backlog if both or neither are configured.
+ */
+async function resolveTicketAdapter() {
+    try {
+        if (await fs.pathExists(STATE_FILE)) {
+            const state = await fs.readJson(STATE_FILE);
+            const adapters = state.adapters || [];
+            if (adapters.includes('jira') && !adapters.includes('backlog')) {
+                return 'jira';
+            }
+        }
+    } catch (_) { /* ignore */ }
+    return 'backlog';
+}
+
+function isBacklogUrl(s) {
+    return s.includes('backlog.com/view/') || s.includes('backlogtool.com/view/');
+}
+
+function extractBacklogId(url) {
+    const match = url.match(/\/view\/([A-Z][A-Z0-9_]+-\d+)/);
+    return match ? match[1] : null;
+}
+
+// ──────────────────────────────────────────────────────────────
+// Version switcher (original behavior)
+// ──────────────────────────────────────────────────────────────
+
+async function switchVersion(versionReq) {
+    const versionsDir = path.join(AIFLOW_DIR, 'versions');
+    if (!(await fs.pathExists(versionsDir))) {
+        console.log(chalk.red('No versions directory found.'));
+        return;
+    }
+
+    const available = await fs.readdir(versionsDir);
+    if (!available.length) {
+        console.log(chalk.red('No installed versions found.'));
+        return;
+    }
+
+    let targetVersion = versionReq;
+    if (!targetVersion) {
+        targetVersion = await select({
+            message: 'Select version to use:',
+            choices: available.map(v => ({ name: `v${v}`, value: v }))
+        });
+    }
+
+    if (!available.includes(targetVersion)) {
+        console.log(chalk.red(`Version v${targetVersion} is not installed.`));
+        return;
+    }
+
+    console.log(chalk.blue(`Switching to v${targetVersion}...`));
+    const versionDir = path.join(versionsDir, targetVersion);
+
+    const claudeDir = path.join(PROJECT_DIR, '.claude');
+    await fs.emptyDir(claudeDir);
+    await fs.copy(path.join(versionDir, 'skills'), path.join(claudeDir, 'skills'), { overwrite: true });
+
+    const rulesDir = path.join(PROJECT_DIR, '.rules');
+    await fs.emptyDir(rulesDir);
+    await fs.copy(path.join(versionDir, 'rules'), rulesDir, { overwrite: true });
+
+    const state = await fs.readJson(STATE_FILE);
+    state.current_version = targetVersion;
+    await fs.writeJson(STATE_FILE, state);
+
+    console.log(chalk.green(`✓ Switched to v${targetVersion}.`));
+}
+
+// ──────────────────────────────────────────────────────────────
+// Backlog context loader
+// ──────────────────────────────────────────────────────────────
+
+async function loadFromBacklog(issueKey, options = {}) {
+    const creds = await loadCredentials();
+    const apiKey   = process.env.BACKLOG_API_KEY   || creds.BACKLOG_API_KEY;
+    const spaceKey = process.env.BACKLOG_SPACE_KEY  || creds.BACKLOG_SPACE_KEY
+                  || process.env.BACKLOG_DOMAIN      || creds.BACKLOG_DOMAIN;
+
+    if (!apiKey || !spaceKey) {
+        console.log(chalk.yellow('⚠ Backlog credentials not set.'));
+        console.log(chalk.gray('Run: aiflow init --adapter backlog'));
+        console.log(chalk.gray('Or set environment variables:'));
+        console.log(chalk.gray('  BACKLOG_API_KEY=your-api-key'));
+        console.log(chalk.gray('  BACKLOG_SPACE_KEY=your-space (e.g. mycompany)'));
+        console.log(chalk.gray('\nFalling back to manual entry...\n'));
+        return await manualContext(issueKey);
+    }
+
+    // spaceKey can be full domain (mycompany.backlog.com) or just the space (mycompany)
+    const domain = spaceKey.includes('.') ? spaceKey : `${spaceKey}.backlog.com`;
+
+    console.log(chalk.blue(`Fetching context from Backlog: ${issueKey}...`));
+
+    try {
+        // Default: description only. Comments loaded only when explicitly requested.
+        const loadComments = options.withComments || options.commentsLast != null || options.commentsFrom != null;
+        const [issue, rawComments] = await Promise.all([
+            fetchBacklogIssue(domain, apiKey, issueKey),
+            loadComments
+                ? fetchBacklogComments(domain, apiKey, issueKey)
+                : Promise.resolve([]),
+        ]);
+
+        const comments = filterComments(rawComments, options);
+        const context = buildContextFromBacklog(issue, comments, issueKey, domain);
+        await saveContext(context, options.save);
+        printContextSummary(context);
+        await suggestNextStep(context);
+    } catch (err) {
+        console.log(chalk.yellow(`⚠ Could not fetch from Backlog: ${err.message}`));
+        console.log(chalk.gray('Falling back to manual entry...\n'));
+        await manualContext(issueKey);
+    }
+}
+
+/**
+ * Filter comments array based on CLI options:
+ *   --no-comments      → empty array (already handled upstream, but safe here too)
+ *   --comments-last N  → last N comments
+ *   --comments-from N  → comments starting at index N (0-based)
+ *   (default)          → all comments
+ */
+function filterComments(comments, options = {}) {
+    if (!comments || !comments.length) return [];
+
+    if (options.commentsLast != null) {
+        const n = Math.max(1, options.commentsLast);
+        return comments.slice(-n);
+    }
+
+    if (options.commentsFrom != null) {
+        const from = Math.max(0, options.commentsFrom);
+        return comments.slice(from);
+    }
+
+    return comments;
+}
+
+/**
+ * Generic Backlog GET helper
+ */
+function backlogGet(url) {
+    return new Promise((resolve, reject) => {
+        https.get(url, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(data));
+                } catch (e) {
+                    reject(new Error('Invalid JSON response from Backlog'));
+                }
+            });
+        }).on('error', reject);
+    });
+}
+
+/**
+ * Fetch issue detail from Backlog REST API
+ */
+function fetchBacklogIssue(domain, apiKey, issueKey) {
+    return backlogGet(`https://${domain}/api/v2/issues/${issueKey}?apiKey=${apiKey}`);
+}
+
+/**
+ * Fetch ALL comments of an issue from Backlog REST API (paginated, max 100/page).
+ */
+async function fetchBacklogComments(domain, apiKey, issueKey) {
+    const all = [];
+    let offset = 0;
+    try {
+        while (true) {
+            const batch = await backlogGet(
+                `https://${domain}/api/v2/issues/${issueKey}/comments?apiKey=${apiKey}&count=100&offset=${offset}&order=asc`
+            );
+            all.push(...batch);
+            if (batch.length < 100) break;
+            offset += 100;
+        }
+    } catch (_) {
+        // comments are optional — don't fail the whole fetch
+    }
+    return all;
+}
+
+/**
+ * Transform Backlog API response + comments to internal context format
+ */
+function buildContextFromBacklog(issue, comments, issueKey, domain) {
+    const type = detectTaskType(issue);
+
+    // Format comments into readable text for AI context
+    const formattedComments = (comments || [])
+        .filter(c => c.content && c.content.trim())
+        .map(c => {
+            const author = c.createdUser?.name || 'Unknown';
+            const date   = c.created ? new Date(c.created).toLocaleDateString('vi-VN') : '';
+            return `[${author} - ${date}]\n${c.content.trim()}`;
+        });
+
+    const allText = [issue.description || '', ...formattedComments.map(c => c)].join('\n');
+
+    return {
+        taskId: issueKey,
+        taskType: type,
+        title: issue.summary || '',
+        description: issue.description || '',
+        status: issue.status?.name || 'Unknown',
+        priority: issue.priority?.name || 'Unknown',
+        assignee: issue.assignee?.name || 'Unassigned',
+
+        // Comments from all participants
+        comments: formattedComments,
+        commentCount: formattedComments.length,
+
+        // Parse checklist-style acceptance criteria from description
+        acceptanceCriteria: extractCriteria(issue.description || ''),
+
+        // Related files mentioned anywhere in ticket
+        context: {
+            files: extractFiles(allText),
+            mentionedServices: [],
+            relatedTickets: extractRelatedTickets(allText),
+        },
+
+        metadata: {
+            created: issue.created,
+            updated: issue.updated,
+            loadedFrom: 'backlog',
+            adapter: 'backlog',
+            sourceUrl: `https://${domain}/view/${issueKey}`,
+        }
+    };
+}
+
+// ──────────────────────────────────────────────────────────────
+// Jira context loader
+// ──────────────────────────────────────────────────────────────
+
+async function loadFromJira(issueKey, options = {}) {
+    const creds = await loadCredentials();
+    const apiToken = process.env.JIRA_API_TOKEN || creds.JIRA_API_TOKEN;
+    const email    = process.env.JIRA_EMAIL      || creds.JIRA_EMAIL;
+    const domain   = process.env.JIRA_DOMAIN     || creds.JIRA_DOMAIN;
+
+    if (!apiToken || !email || !domain) {
+        console.log(chalk.yellow('⚠ Jira credentials not set.'));
+        console.log(chalk.gray('Run: aiflow init --adapter jira'));
+        console.log(chalk.gray('Or set environment variables: JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN'));
+        console.log(chalk.gray('\nFalling back to manual entry...\n'));
+        return await manualContext(issueKey);
+    }
+
+    console.log(chalk.blue(`Fetching context from Jira: ${issueKey}...`));
+
+    try {
+        const issue = await fetchJiraIssue(domain, email, apiToken, issueKey);
+        const context = buildContextFromJira(issue, issueKey, domain);
+        await saveContext(context, options.save);
+        printContextSummary(context);
+        await suggestNextStep(context);
+    } catch (err) {
+        console.log(chalk.yellow(`⚠ Could not fetch from Jira: ${err.message}`));
+        console.log(chalk.gray('Falling back to manual entry...\n'));
+        await manualContext(issueKey);
+    }
+}
+
+function fetchJiraIssue(domain, email, apiToken, issueKey) {
+    return new Promise((resolve, reject) => {
+        const auth = Buffer.from(`${email}:${apiToken}`).toString('base64');
+        const url = `https://${domain}.atlassian.net/rest/api/3/issue/${issueKey}`;
+        const options = {
+            headers: {
+                'Authorization': `Basic ${auth}`,
+                'Accept': 'application/json'
+            }
+        };
+
+        https.get(url, options, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(data));
+                } catch (e) {
+                    reject(new Error('Invalid JSON response from Jira'));
+                }
+            });
+        }).on('error', reject);
+    });
+}
+
+function buildContextFromJira(issue, issueKey, domain) {
+    const fields = issue.fields || {};
+    const type = detectTaskTypeFromString(fields.issuetype?.name || '');
+
+    return {
+        taskId: issueKey,
+        taskType: type,
+        title: fields.summary || '',
+        description: fields.description?.content?.map(block =>
+            block.content?.map(c => c.text).join('') || ''
+        ).join('\n') || '',
+        status: fields.status?.name || 'Unknown',
+        priority: fields.priority?.name || 'Unknown',
+        assignee: fields.assignee?.displayName || 'Unassigned',
+        acceptanceCriteria: extractCriteria(fields.description?.toString() || ''),
+        context: {
+            files: [],
+            relatedTickets: []
+        },
+        metadata: {
+            created: fields.created,
+            updated: fields.updated,
+            loadedFrom: 'jira',
+            adapter: 'jira',
+            sourceUrl: `https://${domain}.atlassian.net/browse/${issueKey}`
+        }
+    };
+}
+
+// ──────────────────────────────────────────────────────────────
+// Manual context entry
+// ──────────────────────────────────────────────────────────────
+
+async function manualContext(prefillId = '') {
+    console.log(chalk.cyan('\nManual Context Entry\n'));
+
+    const taskId = await input({
+        message: 'Ticket ID (e.g. PROJ-33):',
+        default: prefillId
+    });
+
+    const title = await input({ message: 'Title:' });
+    const description = await input({ message: 'Description (brief):' });
+    const taskType = await select({
+        message: 'Task type:',
+        choices: [
+            { name: '🐛 Bug Fix', value: 'bug-fix' },
+            { name: '✨ Feature', value: 'feature' },
+            { name: '🔍 Investigation', value: 'investigation' },
+            { name: '♻️  Refactor', value: 'refactor' },
+            { name: '📊 Impact Analysis', value: 'impact-analysis' }
+        ]
+    });
+
+    const context = {
+        taskId,
+        taskType,
+        title,
+        description,
+        status: 'In Progress',
+        acceptanceCriteria: [],
+        context: { files: [], relatedTickets: [] },
+        metadata: {
+            created: new Date().toISOString(),
+            loadedFrom: 'manual',
+            adapter: 'manual'
+        }
+    };
+
+    await saveContext(context);
+    printContextSummary(context);
+    await suggestNextStep(context);
+}
+
+// ──────────────────────────────────────────────────────────────
+// Load from JSON file
+// ──────────────────────────────────────────────────────────────
+
+async function loadFromFile(filePath, options = {}) {
+    if (!(await fs.pathExists(filePath))) {
+        console.log(chalk.red(`File not found: ${filePath}`));
+        return;
+    }
+    const context = await fs.readJson(filePath);
+    await saveContext(context, options.save);
+    printContextSummary(context);
+    await suggestNextStep(context);
+}
+
+// ──────────────────────────────────────────────────────────────
+// Credentials loader (reads .aiflow/credentials.json as fallback)
+// ──────────────────────────────────────────────────────────────
+
+async function loadCredentials() {
+    const credsFile = path.join(PROJECT_DIR, '.aiflow', 'credentials.json');
+    if (await fs.pathExists(credsFile)) {
+        return await fs.readJson(credsFile).catch(() => ({}));
+    }
+    return {};
+}
+
+// ──────────────────────────────────────────────────────────────
+// Context persistence
+// ──────────────────────────────────────────────────────────────
+
+async function saveContext(context, saveName) {
+    await fs.ensureDir(CONTEXT_DIR);
+    await fs.ensureDir(path.join(CONTEXT_DIR, 'history'));
+
+    // Save as current
+    await fs.writeJson(path.join(CONTEXT_DIR, 'current.json'), context, { spaces: 2 });
+
+    // Save to history
+    const histFile = path.join(CONTEXT_DIR, 'history', `${context.taskId || 'manual'}.json`);
+    await fs.writeJson(histFile, context, { spaces: 2 });
+
+    // Save named snapshot if requested
+    if (saveName) {
+        const namedFile = path.join(CONTEXT_DIR, 'history', `${saveName}.json`);
+        await fs.writeJson(namedFile, context, { spaces: 2 });
+        console.log(chalk.gray(`  Context also saved as: ${saveName}`));
+    }
+
+    // Update state
+    if (await fs.pathExists(STATE_FILE)) {
+        const state = await fs.readJson(STATE_FILE);
+        state.current_context = context.taskId;
+        state.current_context_type = context.taskType;
+        await fs.writeJson(STATE_FILE, state);
+    }
+}
+
+// ──────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────
+
+function detectTaskType(issue) {
+    const name = issue.issueType?.name || issue.type?.name || '';
+    const summary = issue.summary || '';
+    return detectTaskTypeFromString(name || summary);
+}
+
+function detectTaskTypeFromString(text) {
+    const lower = text.toLowerCase();
+    if (['bug', 'defect', 'バグ'].some(k => lower.includes(k))) return 'bug-fix';
+    if (['task', 'story', 'feature', 'タスク'].some(k => lower.includes(k))) return 'feature';
+    if (['research', 'investigation', '調査'].some(k => lower.includes(k))) return 'investigation';
+    return 'bug-fix'; // default for unknown
+}
+
+function extractCriteria(text) {
+    const lines = text.split('\n');
+    return lines
+        .filter(l => l.trim().match(/^[-*•]|^\d+\./))
+        .map(l => l.replace(/^[-*•\d.]+\s*/, '').trim())
+        .filter(l => l.length > 0)
+        .slice(0, 10);
+}
+
+function extractFiles(text) {
+    const matches = text.match(/[\w/]+\.(php|js|ts|vue|jsx|tsx|css|html)/g) || [];
+    return [...new Set(matches)];
+}
+
+function extractRelatedTickets(text) {
+    const matches = text.match(/[A-Z][A-Z0-9_]+-\d+/g) || [];
+    return [...new Set(matches)];
+}
+
+function printContextSummary(context) {
+    console.log(chalk.green('\n✓ Context loaded\n'));
+    console.log(`  ${chalk.white('Ticket:')}   ${context.taskId}`);
+    console.log(`  ${chalk.white('Type:')}     ${context.taskType}`);
+    console.log(`  ${chalk.white('Title:')}    ${context.title.substring(0, 70)}`);
+    console.log(`  ${chalk.white('Status:')}   ${context.status}`);
+    console.log(`  ${chalk.white('Assignee:')} ${context.assignee}`);
+    if (context.description) {
+        console.log(`  ${chalk.white('Desc:')}     ${context.description.substring(0, 80)}...`);
+    }
+    if (context.acceptanceCriteria?.length) {
+        console.log(`  ${chalk.white('Criteria:')} ${context.acceptanceCriteria.length} item(s)`);
+    }
+    if (context.commentCount > 0) {
+        console.log(`  ${chalk.white('Comments:')} ${context.commentCount} comment(s) loaded`);
+    }
+    console.log();
+}
+
+async function suggestNextStep(context) {
+    let aiTools = ['claude']; // Default
+    try {
+        if (await fs.pathExists(STATE_FILE)) {
+            const state = await fs.readJson(STATE_FILE);
+            if (state.aiTools && state.aiTools.length) {
+                aiTools = state.aiTools;
+            }
+        }
+    } catch (_) {}
+
+    console.log(chalk.cyan('\nNext Steps:'));
+    
+    if (aiTools.includes('claude')) {
+        console.log(`  ${chalk.white('1. Claude:')} Run ${chalk.bold.green('claude start')} in terminal. ${chalk.gray('(Quickest way to start)')}`);
+    }
+    
+    if (aiTools.includes('cursor')) {
+        console.log(`  ${chalk.white('2. Cursor:')} Open Cursor Chat ${chalk.gray('(Ctrl+L)')}.`);
+    }
+    
+    if (aiTools.includes('gemini')) {
+        console.log(`  ${chalk.white('3. Gemini:')} Run ${chalk.bold.green('gemini')} then type ${chalk.bold.green('"start"')} or ${chalk.bold.green('"Gate 1"')}.`);
+    }
+
+    console.log(`\n  ${chalk.yellow('Note:')} If the AI does not start automatically, type ${chalk.bold.green('"Gate 1"')} or ${chalk.bold.green('"Analyze ticket"')} to begin.`);
+    console.log();
+}