test-execution-platform-mcp 0.6.0-rc2

package/dist/setup/toml-config.js

@@ -0,0 +1,46 @@
+import { existsSync, copyFileSync, writeFileSync, readFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parse, stringify } from 'smol-toml';
+import { backupPathFor, listBackups, restoreLatestBackup } from './config.js';
+export function readTomlSafe(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        if (raw.trim() === '')
+            return {};
+        return parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function mergeCodexMcpServer(current, serverName, entry) {
+    const mcpServers = { ...(current.mcp_servers ?? {}) };
+    mcpServers[serverName] = { ...(mcpServers[serverName] ?? {}), ...entry };
+    return { ...current, mcp_servers: mcpServers };
+}
+export function writeTomlWithBackup(file, content) {
+    const dir = dirname(file);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    if (existsSync(file)) {
+        copyFileSync(file, backupPathFor(file));
+    }
+    writeFileSync(file, stringify(content), 'utf-8');
+}
+export function removeCodexMcpServer(file, serverName) {
+    const data = readTomlSafe(file);
+    if (!data.mcp_servers || !data.mcp_servers[serverName])
+        return false;
+    delete data.mcp_servers[serverName];
+    writeTomlWithBackup(file, data);
+    return true;
+}
+export function restoreCodexConfigFromBackup(file) {
+    return restoreLatestBackup(file);
+}
+export function listCodexBackups(file) {
+    return listBackups(file);
+}

package/dist/setup/ui.js

@@ -0,0 +1,54 @@
+const ESC = '\x1B';
+const RESET = `${ESC}[0m`;
+const COLORS = {
+    green: `${ESC}[32m`,
+    red: `${ESC}[31m`,
+    yellow: `${ESC}[33m`,
+    blue: `${ESC}[34m`,
+    cyan: `${ESC}[36m`,
+    gray: `${ESC}[90m`,
+};
+export function supportsColor() {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(process.stdout.isTTY);
+}
+export function colorize(text, color, enabled = supportsColor()) {
+    if (!enabled)
+        return text;
+    return `${COLORS[color]}${text}${RESET}`;
+}
+export function formatBanner(title, subtitle) {
+    const bar = '─'.repeat(Math.max(title.length, subtitle.length) + 4);
+    return [
+        colorize(`┌${bar}┐`, 'cyan'),
+        colorize(`│   ${title.padEnd(bar.length - 2)}│`, 'cyan'),
+        colorize(`│   ${subtitle.padEnd(bar.length - 2)}│`, 'gray'),
+        colorize(`└${bar}┘`, 'cyan'),
+    ].join('\n');
+}
+export function formatStep(current, total, message) {
+    return `${colorize(`[${current}/${total}]`, 'blue')} ${message}`;
+}
+export function formatSuccess(message) {
+    return `${colorize('✓', 'green')} ${message}`;
+}
+export function formatWarn(message) {
+    return `${colorize('!', 'yellow')} ${message}`;
+}
+export function formatError(message) {
+    return `${colorize('✗', 'red')} ${message}`;
+}
+export function prompt(question) {
+    return new Promise((resolvePrompt) => {
+        process.stdout.write(`${colorize('?', 'cyan')} ${question} `);
+        const onData = (chunk) => {
+            const s = chunk.toString('utf-8').trim();
+            process.stdin.removeListener('data', onData);
+            resolvePrompt(s);
+        };
+        process.stdin.once('data', onData);
+    });
+}

package/dist/setup/uninstall.js

@@ -0,0 +1,30 @@
+import { writeFileSync } from 'node:fs';
+import { listBackups, readJsonSafe, restoreLatestBackup } from './config.js';
+import { listCodexBackups, readTomlSafe, removeCodexMcpServer, restoreCodexConfigFromBackup } from './toml-config.js';
+export function restoreOrRemoveMcpServer(file, serverName) {
+    const backups = listBackups(file);
+    if (backups.length > 0) {
+        const ok = restoreLatestBackup(file);
+        return { restored: ok, removed: false, path: file };
+    }
+    const data = readJsonSafe(file);
+    if (data.mcpServers?.[serverName]) {
+        delete data.mcpServers[serverName];
+        writeFileSync(file, JSON.stringify(data, null, 2), 'utf-8');
+        return { restored: false, removed: true, path: file };
+    }
+    return { restored: false, removed: false, path: file };
+}
+export function restoreOrRemoveCodexMcpServer(file, serverName) {
+    const backups = listCodexBackups(file);
+    if (backups.length > 0) {
+        const ok = restoreCodexConfigFromBackup(file);
+        return { restored: ok, removed: false, path: file };
+    }
+    const data = readTomlSafe(file);
+    if (data.mcp_servers?.[serverName]) {
+        const ok = removeCodexMcpServer(file, serverName);
+        return { restored: false, removed: ok, path: file };
+    }
+    return { restored: false, removed: false, path: file };
+}

package/dist/setup/update.js

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync, renameSync, unlinkSync, statSync, createWriteStream, chmodSync } from 'node:fs';
+import { prompt } from './ui.js';
+export function parseChecksums(text) {
+    const map = new Map();
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const match = trimmed.match(/^([a-f0-9]+)\s+(.+)$/i);
+        if (match) {
+            map.set(match[2], match[1].toLowerCase());
+        }
+    }
+    return map;
+}
+export function getInstalledVersion(binaryPath) {
+    const versionFile = `${binaryPath}.version`;
+    if (!existsSync(versionFile))
+        return '0.0.0';
+    try {
+        const raw = readFileSync(versionFile, 'utf-8').trim();
+        const m = raw.match(/^v?(\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.]+)?)$/);
+        return m ? m[1] : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function compareVersions(a, b) {
+    const strip = (v) => v.replace(/^v/, '');
+    const parseMain = (v) => strip(v).split('-')[0].split('.').map(Number);
+    const parsePre = (v) => {
+        const m = strip(v).match(/-([^+]*)/);
+        return m ? m[1] : '';
+    };
+    const [aMain, bMain] = [parseMain(a), parseMain(b)];
+    for (let i = 0; i < 3; i++) {
+        const ai = aMain[i] ?? 0, bi = bMain[i] ?? 0;
+        if (ai < bi)
+            return -1;
+        if (ai > bi)
+            return 1;
+    }
+    const aPre = parsePre(a), bPre = parsePre(b);
+    if (!aPre && bPre)
+        return 1;
+    if (aPre && !bPre)
+        return -1;
+    if (aPre < bPre)
+        return -1;
+    if (aPre > bPre)
+        return 1;
+    return 0;
+}
+const ASSET_MAP = {
+    linux: { x64: 'qc-mcp-linux-x64', arm64: 'qc-mcp-linux-arm64' },
+    darwin: { x64: 'qc-mcp-macos-x64', arm64: 'qc-mcp-macos-arm64' },
+    win32: { x64: 'qc-mcp-win-x64.exe', arm64: 'qc-mcp-win-arm64.exe' },
+    // unsupported platforms intentionally absent
+};
+export function selectAssetForPlatform(assets, platform, arch) {
+    const name = ASSET_MAP[platform]?.[arch];
+    if (!name)
+        return null;
+    return assets.has(name) ? name : null;
+}
+export function verifySha256(file, expected) {
+    if (!existsSync(file))
+        return false;
+    const content = readFileSync(file);
+    const hash = createHash('sha256').update(content).digest('hex');
+    return hash.toLowerCase() === expected.toLowerCase();
+}
+export function swapBinary(current, next) {
+    if (!existsSync(current) || !existsSync(next))
+        return false;
+    // Refuse to swap a non-file (e.g., directory) in for a binary
+    if (!statSync(next).isFile())
+        return false;
+    const old = `${current}.old`;
+    if (existsSync(old))
+        unlinkSync(old);
+    renameSync(current, old);
+    try {
+        renameSync(next, current);
+    }
+    catch (err) {
+        // rollback
+        try {
+            renameSync(old, current);
+        }
+        catch {
+            // ignore
+        }
+        return false;
+    }
+    unlinkSync(old);
+    // Defense-in-depth: the auto-update flow downloads the raw binary from
+    // Generic Package Registry, which strips POSIX mode bits. The new
+    // binary would then fail with "Permission denied" on next run. Reapply
+    // 0o755 so the binary stays executable after a self-update. No-op on
+    // Windows (chmod is a no-op there).
+    try {
+        chmodSync(current, 0o755);
+    }
+    catch {
+        // ignore — best effort
+    }
+    return true;
+}
+export async function downloadToFile(url, dest, token, onProgress) {
+    const headers = {};
+    if (token)
+        headers['PRIVATE-TOKEN'] = token;
+    const res = await fetch(url, { headers });
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status} ${res.statusText}`);
+    }
+    if (!res.body) {
+        throw new Error('Response has no body');
+    }
+    const total = Number(res.headers.get('content-length') ?? 0);
+    const file = createWriteStream(dest);
+    let downloaded = 0;
+    let reader = null;
+    try {
+        reader = res.body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            file.write(Buffer.from(value));
+            downloaded += value.length;
+            onProgress?.(downloaded, total);
+        }
+        await new Promise((resolve, reject) => {
+            file.end((err) => err ? reject(err) : resolve());
+        });
+    }
+    catch (err) {
+        file.destroy();
+        // Best-effort cleanup of partial file and underlying stream
+        try {
+            unlinkSync(dest);
+        }
+        catch { /* ignore */ }
+        try {
+            await reader?.cancel();
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+export async function fetchLatestRelease(projectPath, baseUrl = 'https://gitlab.vivas.vn', token) {
+    const url = `${baseUrl}/api/v4/projects/${encodeURIComponent(projectPath)}/releases/permalink/latest`;
+    const headers = { 'User-Agent': 'qc-mcp-setup' };
+    if (token)
+        headers['PRIVATE-TOKEN'] = token;
+    const res = await fetch(url, { headers });
+    if (!res.ok)
+        return null;
+    const body = (await res.json());
+    const assets = new Map();
+    for (const link of body.assets?.links ?? []) {
+        assets.set(link.name, link.url);
+    }
+    return { tag: body.tag_name, assets };
+}
+export async function fetchChecksums(url, token) {
+    const headers = {};
+    if (token)
+        headers['PRIVATE-TOKEN'] = token;
+    const res = await fetch(url, { headers });
+    if (!res.ok)
+        return '';
+    return res.text();
+}
+export async function confirmUpdate(info) {
+    const sizeMB = (info.size / 1024 / 1024).toFixed(1);
+    console.log(`Update available: v${info.from} → v${info.to}`);
+    console.log(`  Size:    ${sizeMB} MB`);
+    console.log(`  SHA-256: ${info.sha256.slice(0, 16)}...`);
+    const ans = (await prompt('Proceed? [y/N]')).trim().toLowerCase();
+    return ans === 'y' || ans === 'yes';
+}

package/dist/setup/verify.js

@@ -0,0 +1,137 @@
+import { spawn } from 'node:child_process';
+const INIT_REQUEST = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'qc-mcp-setup', version: '0.0.0' },
+    },
+});
+const INIT_NOTIF = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' });
+const HEALTH_REQUEST = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 2,
+    method: 'tools/call',
+    params: { name: 'health_check', arguments: {} },
+});
+export function verifyMcpHandshake(input) {
+    const timeoutMs = input.timeoutMs ?? 10_000;
+    return new Promise((resolve) => {
+        const child = spawn(input.binary, [], {
+            env: {
+                ...process.env,
+                TEST_EXECUTION_API_BASE_URL: input.apiBaseUrl,
+                TEST_EXECUTION_MCP_TOKEN: input.token,
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const pending = new Map();
+        let buffer = '';
+        let stderrBuffer = '';
+        let initResponse = null;
+        let healthText = null;
+        let timedOut = false;
+        let resolved = false;
+        const finish = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            try {
+                child.stdin?.end();
+            }
+            catch {
+                // ignore
+            }
+            try {
+                child.kill();
+            }
+            catch {
+                // ignore
+            }
+            resolve(result);
+        };
+        const tryFinishSuccess = () => {
+            if (resolved)
+                return;
+            if (initResponse && healthText !== null) {
+                finish({
+                    ok: true,
+                    serverName: initResponse.serverInfo?.name,
+                    serverVersion: initResponse.serverInfo?.version,
+                    healthCheckText: healthText,
+                });
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            finish({ ok: false, error: 'Timeout waiting for MCP handshake' });
+        }, timeoutMs);
+        child.stdout?.on('data', (chunk) => {
+            buffer += chunk.toString('utf-8');
+            let idx;
+            while ((idx = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, idx).trim();
+                buffer = buffer.slice(idx + 1);
+                if (line.length === 0)
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed?.id === 1 && parsed?.result) {
+                    initResponse = parsed.result;
+                    if (pending.has(1)) {
+                        pending.get(1).resolve(parsed.result);
+                        pending.delete(1);
+                    }
+                }
+                else if (parsed?.id === 2 && parsed?.result) {
+                    const text = parsed.result?.content?.[0]?.text;
+                    if (typeof text === 'string')
+                        healthText = text;
+                    if (pending.has(2)) {
+                        pending.get(2).resolve(parsed.result);
+                        pending.delete(2);
+                    }
+                }
+                else if (parsed?.id && pending.has(parsed.id)) {
+                    pending.get(parsed.id).resolve(parsed);
+                    pending.delete(parsed.id);
+                }
+                // Resolve as soon as both responses arrive. MCP stdio servers stay
+                // alive until stdin closes, so waiting for the child `close` event
+                // would block until our own timeout fires.
+                tryFinishSuccess();
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderrBuffer += chunk.toString('utf-8');
+        });
+        child.on('error', (err) => {
+            finish({ ok: false, error: `spawn error: ${err.message}` });
+        });
+        child.on('close', (code) => {
+            if (timedOut)
+                return;
+            if (resolved)
+                return;
+            // If we never saw both responses, treat unexpected exit as a failure.
+            if (initResponse && healthText !== null) {
+                tryFinishSuccess();
+            }
+            else {
+                finish({
+                    ok: false,
+                    error: `Process exited with code ${code ?? 'unknown'} before handshake completed; stderr=${stderrBuffer.slice(0, 300)}`,
+                });
+            }
+        });
+        child.stdin?.write(`${INIT_REQUEST}\n${INIT_NOTIF}\n${HEALTH_REQUEST}\n`);
+    });
+}

package/dist/setup/version.js

@@ -0,0 +1,32 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+// __filename / __dirname: when compiled to CommonJS, these are runtime
+// globals; when compiled to ESM we derive them from import.meta.url.
+const localFilename = typeof __filename !== 'undefined'
+    ? __filename
+    : fileURLToPath(import.meta.url);
+const localDirname = typeof __dirname !== 'undefined'
+    ? __dirname
+    : dirname(localFilename);
+const CANDIDATE_PATHS = [
+    resolve(localDirname, '..', '..', 'package.json'),
+    resolve(localDirname, '..', '..', '..', 'package.json'),
+    resolve(process.cwd(), 'package.json'),
+];
+export function getVersion() {
+    for (const candidate of CANDIDATE_PATHS) {
+        if (!existsSync(candidate))
+            continue;
+        try {
+            const raw = readFileSync(candidate, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.version)
+                return parsed.version;
+        }
+        catch {
+            // ignore malformed json
+        }
+    }
+    return '0.0.0';
+}

package/dist/tools/core.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { EmptySchema, encodeQuery } from '../types.js';
+import { requireExecuteAfterDryRun } from './dryRun.js';
+export function createCoreTools(api) {
+    return {
+        list_projects: tool('List projects.', EmptySchema, async () => api.get('/api/projects')),
+        list_rounds: tool('List rounds, optionally filtered by project.', z.object({ project_id: z.string().optional() }), async (input) => {
+            const qs = input.project_id ? `?project_id=${encodeQuery(input.project_id)}` : '';
+            return api.get(`/api/rounds${qs}`);
+        }),
+        list_sessions: tool('List active sessions.', EmptySchema, async () => api.get('/api/sessions')),
+        get_session: tool('Get session metadata and file tree.', z.object({ session_id: z.string().min(1) }), async (input) => api.get(`/api/sessions/${encodeQuery(input.session_id)}`)),
+        get_file_tree: tool('Get session file tree.', z.object({ session_id: z.string().min(1) }), async (input) => {
+            const result = await api.get(`/api/sessions/${encodeQuery(input.session_id)}`);
+            return { file_tree: result.file_tree, session: result.session };
+        }),
+        get_testcases_by_path: tool('Get testcases from a testcase markdown path.', z.object({ session_id: z.string().min(1), file_path: z.string().min(1) }), async (input) => {
+            return api.get(`/api/sessions/${encodeQuery(input.session_id)}/testcases?file_path=${encodeQuery(input.file_path)}`);
+        }),
+        get_user_story_file: tool('Read the matching [US-*] user story file.', z.object({ session_id: z.string().min(1), tc_file_path: z.string().min(1) }), async (input) => {
+            return api.get(`/api/sessions/${encodeQuery(input.session_id)}/us-file?tc_file_path=${encodeQuery(input.tc_file_path)}`);
+        }),
+        check_user_story_file_exists: tool('Check whether matching user story file exists.', z.object({ session_id: z.string().min(1), tc_file_path: z.string().min(1) }), async (input) => {
+            return api.get(`/api/sessions/${encodeQuery(input.session_id)}/us-file-exists?tc_file_path=${encodeQuery(input.tc_file_path)}`);
+        }),
+        get_notes: tool('Get notes for a testcase.', z.object({ session_id: z.string().min(1), testcase_id: z.string().min(1) }), async (input) => {
+            return api.get(`/api/sessions/${encodeQuery(input.session_id)}/testcases/${encodeQuery(input.testcase_id)}/notes`);
+        }),
+        create_project: tool('Create a project.', z.object({ name: z.string().min(1), git_url: z.string().min(1), branch: z.string().min(1), description: z.string().optional() }), async (input) => api.post('/api/projects', input)),
+        update_project: tool('Update a project.', z.object({ id: z.string().min(1), name: z.string().optional(), git_url: z.string().optional(), branch: z.string().optional(), description: z.string().optional() }), async ({ id, ...body }) => api.put(`/api/projects/${encodeQuery(id)}`, body)),
+        create_round: tool('Create a round.', z.object({ project_id: z.string().min(1), name: z.string().min(1), round_number: z.number().int().min(1).max(3), status: z.enum(['active', 'completed', 'archived']).optional() }), async (input) => api.post('/api/rounds', input)),
+        update_round: tool('Update a round.', z.object({ id: z.string().min(1), name: z.string().optional(), status: z.enum(['active', 'completed', 'archived']).optional() }), async ({ id, ...body }) => api.put(`/api/rounds/${encodeQuery(id)}`, body)),
+        open_session: tool('Open a session by round_id or git_url + branch.', z.object({ round_id: z.string().optional(), git_url: z.string().optional(), branch: z.string().optional() }), async (input) => api.post('/api/sessions/open', input)),
+        close_session: tool('Close a session.', z.object({ session_id: z.string().min(1) }), async (input) => api.post(`/api/sessions/${encodeQuery(input.session_id)}/close`)),
+        list_branches: tool('List remote branches for a Git URL.', z.object({ git_url: z.string().min(1) }), async (input) => api.post('/api/git/branches', input)),
+        create_testcase: tool('Create one testcase.', z.object({ session_id: z.string().min(1), file_id: z.string().min(1), tc_id: z.string().optional(), test_case_name: z.string().min(1), status: z.string().optional(), type: z.string().optional(), technique: z.string().optional(), precondition: z.string().optional(), steps: z.string().optional(), expected_result: z.string().optional(), priority: z.string().optional(), ai: z.string().optional(), r1: z.string().optional(), r2: z.string().optional(), r3: z.string().optional(), note: z.string().optional() }), async ({ session_id, ...body }) => api.post(`/api/sessions/${encodeQuery(session_id)}/testcases`, body)),
+        update_testcase: tool('Update one testcase.', z.object({ session_id: z.string().min(1), testcase_id: z.string().min(1), test_case_name: z.string().min(1), precondition: z.string().optional(), steps: z.string().optional(), expected_result: z.string().optional(), priority: z.string().optional(), type: z.string().optional(), technique: z.string().optional() }), async ({ session_id, testcase_id, ...body }) => api.put(`/api/sessions/${encodeQuery(session_id)}/testcases/${encodeQuery(testcase_id)}`, body)),
+        update_testcase_dev_status: tool('Update testcase dev_status.', z.object({ session_id: z.string().min(1), testcase_id: z.string().min(1), devStatus: z.enum(['', 'open', 'fixed', 'retest']) }), async ({ session_id, testcase_id, devStatus }) => api.patch(`/api/sessions/${encodeQuery(session_id)}/testcases/${encodeQuery(testcase_id)}/dev-status`, { devStatus })),
+        create_file: tool('Create a testcase markdown file in a session workspace.', z.object({
+            session_id: z.string().min(1),
+            name: z.string().min(1),
+            parent_path: z.string().optional(),
+        }), async ({ session_id, name, parent_path }) => api.post(`/api/sessions/${encodeQuery(session_id)}/files`, { name, parent_path })),
+        create_folder: tool('Create a folder in a session workspace.', z.object({
+            session_id: z.string().min(1),
+            name: z.string().min(1),
+            parent_path: z.string().optional(),
+        }), async ({ session_id, name, parent_path }) => api.post(`/api/sessions/${encodeQuery(session_id)}/folders`, { name, parent_path })),
+        create_note: tool('Create a note for a testcase.', z.object({ session_id: z.string().min(1), testcase_id: z.string().min(1), execution_round: z.enum(['R1', 'R2', 'R3']).nullable().optional(), text: z.string().min(1).max(10000) }), async ({ session_id, testcase_id, ...body }) => api.post(`/api/sessions/${encodeQuery(session_id)}/testcases/${encodeQuery(testcase_id)}/notes`, body)),
+        update_note: tool('Update note text.', z.object({ note_id: z.string().min(1), text: z.string().min(1).max(10000) }), async ({ note_id, text }) => api.put(`/api/notes/${encodeQuery(note_id)}`, { text })),
+        delete_note: tool('Delete a note.', z.object({ note_id: z.string().min(1) }), async ({ note_id }) => api.delete(`/api/notes/${encodeQuery(note_id)}`)),
+        analyze_excel: tool('Analyze an Excel file for import.', z.object({ session_id: z.string().min(1), file_ref: z.string().min(1) }), async (input) => ({ warning: 'File upload transport must be implemented with backend-compatible upload handling.', input })),
+        delete_testcase: tool('Delete a testcase with dry-run guardrail.', z.object({ session_id: z.string().min(1), testcase_id: z.string().min(1), dry_run: z.boolean() }), async (input) => {
+            const preview = requireExecuteAfterDryRun(input, { action: 'delete_testcase', testcase_id: input.testcase_id });
+            if (preview)
+                return preview;
+            return api.delete(`/api/sessions/${encodeQuery(input.session_id)}/testcases/${encodeQuery(input.testcase_id)}`);
+        }),
+        delete_file: tool('Delete a file with dry-run guardrail.', z.object({ session_id: z.string().min(1), file_path: z.string().min(1), dry_run: z.boolean() }), async (input) => {
+            const preview = requireExecuteAfterDryRun(input, { action: 'delete_file', file_path: input.file_path });
+            if (preview)
+                return preview;
+            const encodedPath = input.file_path.split('/').map(encodeURIComponent).join('/');
+            return api.delete(`/api/sessions/${encodeQuery(input.session_id)}/files/${encodedPath}`);
+        }),
+        delete_project: tool('Delete a project with dry-run guardrail.', z.object({ id: z.string().min(1), dry_run: z.boolean() }), async (input) => {
+            const preview = requireExecuteAfterDryRun(input, { action: 'delete_project', project_id: input.id });
+            if (preview)
+                return preview;
+            return api.delete(`/api/projects/${encodeQuery(input.id)}`);
+        }),
+        delete_round: tool('Delete a round with dry-run guardrail.', z.object({ id: z.string().min(1), dry_run: z.boolean() }), async (input) => {
+            const preview = requireExecuteAfterDryRun(input, { action: 'delete_round', round_id: input.id });
+            if (preview)
+                return preview;
+            return api.delete(`/api/rounds/${encodeQuery(input.id)}`);
+        }),
+    };
+}
+function tool(description, inputSchema, handler) {
+    return { description, inputSchema, handler };
+}

package/dist/tools/dryRun.js

@@ -0,0 +1,11 @@
+export function requireExecuteAfterDryRun(input, preview) {
+    if (input.dry_run) {
+        return {
+            dry_run: true,
+            execute_allowed: false,
+            preview,
+            next_steps: ['Review the preview, then call this tool again with dry_run=false to execute.'],
+        };
+    }
+    return null;
+}

package/dist/tools/workflows.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { encodeQuery } from '../types.js';
+import { requireExecuteAfterDryRun } from './dryRun.js';
+export function createWorkflowTools(api) {
+    return {
+        prepare_review_context: tool('Prepare normalized QA review context for Claude.', z.object({ session_id: z.string().min(1), tc_file_path: z.string().min(1), include_notes: z.boolean().default(true), include_user_story: z.boolean().default(true) }), async (input) => {
+            const [sessionResult, testcaseResult, userStoryResult] = await Promise.all([
+                api.get(`/api/sessions/${encodeQuery(input.session_id)}`),
+                api.get(`/api/sessions/${encodeQuery(input.session_id)}/testcases?file_path=${encodeQuery(input.tc_file_path)}`),
+                input.include_user_story ? api.get(`/api/sessions/${encodeQuery(input.session_id)}/us-file?tc_file_path=${encodeQuery(input.tc_file_path)}`).catch((error) => ({ error: String(error) })) : Promise.resolve(null),
+            ]);
+            const testcases = testcaseResult.testcases ?? [];
+            const notesByTestcase = {};
+            if (input.include_notes) {
+                for (const tc of testcases) {
+                    notesByTestcase[tc.id] = await api.get(`/api/sessions/${encodeQuery(input.session_id)}/testcases/${encodeQuery(tc.id)}/notes`).catch((error) => ({ error: String(error) }));
+                }
+            }
+            return {
+                session: sessionResult.session,
+                file_tree: sessionResult.file_tree,
+                testcase_file: { path: input.tc_file_path, summary: testcaseResult.summary ?? '' },
+                user_story: userStoryResult,
+                testcases,
+                notes_by_testcase: notesByTestcase,
+                review_hints: buildReviewHints(testcases),
+            };
+        }),
+        import_excel_with_preview: tool('Preview or execute Excel import.', z.object({ session_id: z.string().min(1), file_ref: z.string().min(1), dry_run: z.boolean() }), async (input) => {
+            const preview = requireExecuteAfterDryRun(input, { action: 'import_excel', session_id: input.session_id, file_ref: input.file_ref, note: 'Use backend analyze endpoint or upload preview before executing import.' });
+            if (preview)
+                return preview;
+            return api.post(`/api/sessions/${encodeQuery(input.session_id)}/excel/import`, { file_ref: input.file_ref });
+        }),
+        bulk_update_testcases_with_preview: tool('Preview or execute bulk testcase updates.', z.object({ session_id: z.string().min(1), updates: z.array(z.object({ testcase_id: z.string().min(1), fields: z.record(z.string(), z.unknown()) })).min(1), dry_run: z.boolean() }), async (input) => {
+            const preview = requireExecuteAfterDryRun(input, { action: 'bulk_update_testcases', count: input.updates.length, testcase_ids: input.updates.map((u) => u.testcase_id) });
+            if (preview)
+                return preview;
+            const results = [];
+            for (const update of input.updates) {
+                results.push(await api.put(`/api/sessions/${encodeQuery(input.session_id)}/testcases/${encodeQuery(update.testcase_id)}`, update.fields));
+            }
+            return { updated: results.length, results };
+        }),
+        prepare_ci_execution_context: tool('Prepare CI-safe context for opening and closing a session.', z.object({ project_id: z.string().optional(), round_id: z.string().optional(), branch_override: z.string().optional() }), async (input) => {
+            const [projects, rounds, sessions] = await Promise.all([
+                api.get('/api/projects'),
+                api.get(input.project_id ? `/api/rounds?project_id=${encodeQuery(input.project_id)}` : '/api/rounds'),
+                api.get('/api/sessions'),
+            ]);
+            return {
+                projects: projects.projects ?? [],
+                rounds: rounds.rounds ?? [],
+                sessions: sessions.sessions ?? [],
+                suggested_open_session_payload: input.round_id ? { round_id: input.round_id } : { project_id: input.project_id, branch: input.branch_override },
+                checklist: ['Open session', 'Run dry-run for import/bulk operations', 'Execute only after preview is reviewed', 'Get session to inspect dirty/last_commit_at', 'Close session'],
+            };
+        }),
+    };
+}
+function buildReviewHints(testcases) {
+    return {
+        missing_steps: testcases.filter((tc) => !String(tc.steps ?? '').trim()).map((tc) => tc.id),
+        missing_expected_result: testcases.filter((tc) => !String(tc.expected_result ?? '').trim()).map((tc) => tc.id),
+        generic_expected_result_candidates: testcases.filter((tc) => /^(ok|pass|success|đúng|thành công)$/i.test(String(tc.expected_result ?? '').trim())).map((tc) => tc.id),
+    };
+}
+function tool(description, inputSchema, handler) {
+    return { description, inputSchema, handler };
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export const EmptySchema = z.object({});
+export const SessionIdSchema = z.object({ session_id: z.string().min(1) });
+export function encodeQuery(value) {
+    return encodeURIComponent(value);
+}