@ihyeon/flow-qa 0.0.0-stage → 0.1.0-alpha.2

package/dist/src/report.js

@@ -0,0 +1,315 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { expectedChecks } from "./compiler.js";
+import { localized, localizeProductMessage } from "./i18n.js";
+function object(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Invalid raw report field: ${label}.`);
+    return value;
+}
+function string(value, label) {
+    if (typeof value !== 'string')
+        throw new Error(`Invalid raw report field: ${label}.`);
+    return value;
+}
+function array(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`Invalid raw report field: ${label}.`);
+    return value;
+}
+function number(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+        throw new Error(`Invalid raw report field: ${label}.`);
+    return value;
+}
+function integer(value, label) {
+    const checked = number(value, label);
+    if (!Number.isInteger(checked))
+        throw new Error(`Invalid raw report field: ${label}.`);
+    return checked;
+}
+function oneOf(value, choices, label) {
+    if (typeof value !== 'string' || !choices.includes(value))
+        throw new Error(`Unsupported raw report value: ${label}.`);
+    return value;
+}
+function rawError(value) {
+    const item = object(value, 'error');
+    return { code: string(item.code, 'error.code'), message: string(item.message, 'error.message'),
+        ...(item.category === undefined ? {} : { category: oneOf(item.category, ['test', 'configuration', 'infrastructure', 'internal', 'interrupted'], 'error.category') }) };
+}
+const attemptStatuses = ['passed', 'failed', 'timed-out', 'interrupted', 'skipped'];
+const resultStatuses = ['passed', 'flaky', 'failed', 'timed-out', 'interrupted', 'skipped'];
+const runStatuses = ['passed', 'failed', 'blocked', 'error', 'interrupted'];
+const redactionStatuses = ['complete', 'not-required', 'incomplete'];
+// e2e 0.15.1's documented blockedCategory codes. Only a final attempt carrying
+// one of these codes proves that a failed/timed-out result was blocked.
+const blockableCodes = new Set([
+    'AUTH_CREDENTIAL_UNAVAILABLE', 'AUTH_CREDENTIAL_INVALID', 'SECRET_UNAVAILABLE',
+    'ENVIRONMENT_UNAVAILABLE', 'APP_UNREACHABLE', 'APP_ALREADY_RUNNING',
+    'SEED_DATA_MISSING', 'TEST_SETUP_FAILED', 'APP_NOT_OPEN', 'POLICY_DENIED',
+    'MODEL_UNAVAILABLE', 'AUTOMATION_UNSUPPORTED', 'STEP_BUDGET_EXHAUSTED',
+    'STEP_TIMEOUT', 'CONTEXT_OVERFLOW',
+]);
+function resultCaseStatus(status, attempts) {
+    if (status === 'passed' || status === 'flaky' || status === 'skipped')
+        return status;
+    const lastError = attempts.at(-1)?.error;
+    if (lastError && blockableCodes.has(lastError.code))
+        return 'blocked';
+    if (lastError?.category === 'configuration' || lastError?.category === 'infrastructure' || lastError?.category === 'internal' || lastError?.category === 'interrupted')
+        return 'error';
+    return status === 'interrupted' ? 'error' : 'failed';
+}
+/** Only paths inside the current run's artifact directory can become links. */
+function localArtifactPath(rawPath, rawDir) {
+    if (typeof rawPath !== 'string' || !/^[^\\\x00-\x1f?#]+$/.test(rawPath))
+        return undefined;
+    const parts = rawPath.split('/');
+    if (parts.length < 1 || parts.some((part) => part === '' || part === '.' || part === '..' || part.startsWith('.')))
+        return undefined;
+    const candidate = path.resolve(rawDir, 'artifacts', ...parts);
+    const artifactRoot = path.resolve(rawDir, 'artifacts');
+    if (!candidate.startsWith(`${artifactRoot}${path.sep}`))
+        return undefined;
+    try {
+        const realRoot = realpathSync(artifactRoot);
+        const realFile = realpathSync(candidate);
+        if (!realFile.startsWith(`${realRoot}${path.sep}`))
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return `raw/artifacts/${parts.join('/')}`;
+}
+function normalizeAttempt(value, rawDir) {
+    const item = object(value, 'attempt');
+    const steps = array(item.steps, 'attempt.steps').map((value) => {
+        const step = object(value, 'step');
+        const model = step.model === undefined ? undefined : object(step.model, 'step.model');
+        return {
+            api: string(step.api, 'step.api'),
+            label: string(step.label, 'step.label'),
+            status: oneOf(step.status, ['passed', 'failed', 'blocked', 'timed-out', 'cancelled'], 'step.status'),
+            ...(step.error === undefined ? {} : { error: rawError(step.error) }),
+            ...(model === undefined ? {} : { model: {
+                    provider: string(model.provider, 'step.model.provider'),
+                    model: string(model.model, 'step.model.model'),
+                    inputTokens: number(model.inputTokens, 'step.model.inputTokens'),
+                    outputTokens: number(model.outputTokens, 'step.model.outputTokens'),
+                    ...(model.estimatedCostUsd === undefined ? {} : { estimatedCostUsd: number(model.estimatedCostUsd, 'step.model.estimatedCostUsd') }),
+                } }),
+        };
+    });
+    const artifacts = array(item.artifacts, 'attempt.artifacts').map((value) => {
+        const artifact = object(value, 'artifact');
+        const redaction = oneOf(artifact.redaction, redactionStatuses, 'artifact.redaction');
+        const safePath = redaction === 'incomplete' ? undefined : localArtifactPath(artifact.path, rawDir);
+        return {
+            kind: string(artifact.kind, 'artifact.kind'),
+            redaction,
+            ...(safePath === undefined ? {} : { path: safePath }),
+        };
+    });
+    return {
+        index: integer(item.index, 'attempt.index'),
+        status: oneOf(item.status, attemptStatuses, 'attempt.status'),
+        startedAt: string(item.startedAt, 'attempt.startedAt'),
+        durationMs: number(item.durationMs, 'attempt.durationMs'),
+        ...(item.error === undefined ? {} : { error: rawError(item.error) }),
+        secondaryErrors: array(item.secondaryErrors, 'attempt.secondaryErrors').map(rawError),
+        steps,
+        artifacts,
+    };
+}
+/** Adapt e2e's report-1 document. Any unsupported or mismatched result fails closed. */
+export function normalizeReport1(raw, context) {
+    const document = object(raw, 'root');
+    if (document.schemaVersion !== 'report-1')
+        throw new Error('Unsupported e2e report version.');
+    const run = object(document.run, 'run');
+    string(run.id, 'run.id');
+    if (run.specVersion !== '0.1' || object(run.runner, 'run.runner').name !== 'e2e')
+        throw new Error('The raw report runner contract does not match.');
+    const rawStatus = oneOf(run.status, runStatuses, 'run.status');
+    if (![0, 1, 2, 3, 4, 130].includes(run.exitCode))
+        throw new Error('Unsupported raw report exit code.');
+    if (rawStatus === 'passed' && run.exitCode !== 0)
+        throw new Error('The raw report passed status and exit code disagree.');
+    string(run.startedAt, 'run.startedAt');
+    string(run.finishedAt, 'run.finishedAt');
+    const project = object(run.project, 'run.project');
+    const targetEntries = array(run.targets, 'run.targets');
+    if (rawStatus !== 'error' && project.id !== context.suite.id)
+        throw new Error('The raw report project does not match the current suite.');
+    if (rawStatus !== 'error' && !targetEntries.some((item) => object(item, 'target').id === context.target.name)) {
+        throw new Error('The raw report target does not match the current run target.');
+    }
+    object(run.summary, 'run.summary');
+    const rawResults = array(run.results, 'run.results');
+    const rawErrors = array(run.errors, 'run.errors').map(rawError);
+    const sourceName = path.basename(context.testFile);
+    const knownTitles = new Map(context.suite.cases.map((testCase) => [`[${testCase.id}] ${testCase.title}`, testCase.id]));
+    const mapped = new Map();
+    for (const value of rawResults) {
+        const result = object(value, 'result');
+        const titlePath = array(result.titlePath, 'result.titlePath');
+        const title = titlePath.length === 1 ? string(titlePath[0], 'result.titlePath[0]') : '';
+        const id = knownTitles.get(title);
+        if (id === undefined || result.file !== sourceName || result.targetId !== context.target.name || result.kind !== 'test' || result.selected !== true) {
+            throw new Error('The raw report test does not match the current suite, target, or test file.');
+        }
+        if (mapped.has(id))
+            throw new Error(`Duplicate test result in the raw report: ${id}`);
+        const status = oneOf(result.status, resultStatuses, 'result.status');
+        const attempts = array(result.attempts, 'result.attempts').map((attempt) => normalizeAttempt(attempt, context.rawDir));
+        if (status !== 'skipped' && attempts.length === 0)
+            throw new Error(`Test result has no attempts: ${id}`);
+        if (status === 'passed' && attempts.at(-1)?.status !== 'passed')
+            throw new Error(`Passed status and attempts disagree: ${id}`);
+        if (status === 'flaky' && (attempts.at(-1)?.status !== 'passed' || !attempts.slice(0, -1).some((attempt) => attempt.status !== 'passed'))) {
+            throw new Error(`Flaky status and attempts disagree: ${id}`);
+        }
+        if (context.blockedReasons.has(id) && status !== 'skipped')
+            throw new Error(`A blocked case was recorded as executed: ${id}`);
+        const skip = result.skip === undefined ? undefined : object(result.skip, 'result.skip');
+        mapped.set(id, { status, attempts, ...(skip === undefined ? {} : { reason: string(skip.reason, 'result.skip.reason') }) });
+    }
+    const errors = rawErrors.map((error) => `${error.code}: ${error.message}`);
+    const cases = context.suite.cases.map((testCase) => {
+        const expected = expectedChecks(testCase);
+        const result = mapped.get(testCase.id);
+        const blockedReason = context.blockedReasons.get(testCase.id);
+        if (blockedReason !== undefined)
+            return { id: testCase.id, title: testCase.title, status: 'blocked', expected, attempts: result?.attempts ?? [], reason: blockedReason };
+        if (result === undefined)
+            return { id: testCase.id, title: testCase.title, status: 'error', expected, attempts: [], reason: 'The raw report has no result for this case.' };
+        const status = resultCaseStatus(result.status, result.attempts);
+        const reason = status === 'blocked' ? result.attempts.at(-1)?.error?.message ?? result.reason : result.reason;
+        return { id: testCase.id, title: testCase.title, status, expected, attempts: result.attempts, ...(reason === undefined ? {} : { reason }) };
+    });
+    if (cases.some((item) => item.status === 'error' && !context.blockedReasons.has(item.id)))
+        errors.push('One or more cases ended without a result or were interrupted.');
+    const usage = object(run.usage, 'run.usage');
+    const modelTokens = number(usage.modelTokens, 'run.usage.modelTokens');
+    const reportUsage = {
+        modelTokens,
+        ...(usage.modelCachedTokens === undefined ? {} : { modelCachedTokens: number(usage.modelCachedTokens, 'run.usage.modelCachedTokens') }),
+        ...(usage.estimatedCostUsd === undefined ? {} : { estimatedCostUsd: number(usage.estimatedCostUsd, 'run.usage.estimatedCostUsd') }),
+    };
+    const blockedMismatch = rawStatus === 'blocked' && cases.some((item) => item.status === 'failed');
+    if (blockedMismatch) {
+        errors.push('The e2e blocked status conflicts with a failed case result.');
+    }
+    const status = rawStatus === 'interrupted' ? 'interrupted'
+        : rawStatus === 'error' || rawErrors.length > 0 || cases.some((item) => item.status === 'error') || blockedMismatch ? 'error'
+            : rawStatus === 'blocked' ? 'blocked'
+                : cases.some((item) => item.status === 'failed' || item.status === 'flaky') ? 'failed'
+                    : cases.some((item) => item.status === 'blocked' || item.status === 'skipped') ? 'blocked'
+                        : rawStatus === 'failed' ? 'failed'
+                            : 'passed';
+    return {
+        schemaVersion: 'flow-qa/report-1', runId: context.runId, suiteId: context.suite.id,
+        suiteHash: context.suiteHash, target: context.target, startedAt: context.startedAt,
+        finishedAt: context.finishedAt, status, cases, errors, usage: reportUsage,
+    };
+}
+/** Keep every recorded attempt when the adapter stops a still-running child. */
+export function stoppedReport(raw, context, status, reason) {
+    const report = normalizeReport1(raw, context);
+    report.status = status;
+    report.errors.push(reason);
+    return report;
+}
+/** An explicit failure report still enumerates every expected case. */
+export function failureReport(context, status, error) {
+    return {
+        schemaVersion: 'flow-qa/report-1', runId: context.runId, suiteId: context.suite.id,
+        suiteHash: context.suiteHash, target: context.target, startedAt: context.startedAt,
+        finishedAt: context.finishedAt, status,
+        cases: context.suite.cases.map((testCase) => ({
+            id: testCase.id, title: testCase.title,
+            status: context.blockedReasons.has(testCase.id) ? 'blocked' : 'error',
+            expected: expectedChecks(testCase), attempts: [],
+            reason: context.blockedReasons.get(testCase.id) ?? error,
+        })),
+        errors: [error],
+    };
+}
+function safeText(value, locale) {
+    return value.replace(/(?:https?:\/\/|file:\/\/)[^\s<>"'\])}]+/gi, localized(locale, '[URL hidden]', '[URL 숨김]'))
+        .replace(/\[[^\]]*\]\([^)]*\)/g, localized(locale, '[link hidden]', '[링크 숨김]'))
+        .replace(/[\r\n\t]+/g, ' ')
+        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/([\\`*_{}\[\]()#+\-.!|>])/g, '\\$1');
+}
+function evidenceLink(artifact) {
+    if (artifact.redaction !== 'complete' && artifact.redaction !== 'not-required')
+        return undefined;
+    const file = artifact.path;
+    if (typeof file !== 'string' || !file.startsWith('raw/artifacts/'))
+        return undefined;
+    const parts = file.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..' || /[\\\x00-\x1f]/.test(part)))
+        return undefined;
+    return parts.map(encodeURIComponent).join('/');
+}
+export function renderMarkdown(report, locale = 'en') {
+    const safe = (value) => safeText(value, locale);
+    const label = (english, korean) => localized(locale, english, korean);
+    const counts = new Map();
+    for (const item of report.cases)
+        counts.set(item.status, (counts.get(item.status) ?? 0) + 1);
+    const lines = [
+        `# ${label('QA results', 'QA 결과')}: ${safe(report.suiteId)}`,
+        '',
+        `- ${label('Run ID', '실행 ID')}: ${safe(report.runId)}`,
+        `- ${label('Target', '대상')}: ${safe(report.target.name)} ${label('(URL available in the local JSON report)', '(주소는 로컬 JSON 보고서에서 확인)')}`,
+        `- ${label('Status', '상태')}: ${safe(report.status)}`,
+        `- ${label('Started', '시작')}: ${safe(report.startedAt)}`,
+        `- ${label('Finished', '종료')}: ${safe(report.finishedAt)}`,
+        `- ${label('Results', '결과')}: ${label('passed', '통과')} ${counts.get('passed') ?? 0}, ${label('failed', '실패')} ${counts.get('failed') ?? 0}, ${label('flaky', '재시도 후 통과')} ${counts.get('flaky') ?? 0}, ${label('blocked', '차단')} ${counts.get('blocked') ?? 0}, ${label('skipped', '건너뜀')} ${counts.get('skipped') ?? 0}, ${label('error', '오류')} ${counts.get('error') ?? 0}`,
+        '',
+        label('## Case results', '## 케이스별 확인'),
+        '',
+    ];
+    for (const item of report.cases) {
+        lines.push(`### ${safe(item.id)} · ${safe(item.title)} — ${safe(item.status)}`, '');
+        lines.push(`- ${label('Expected checks', '기대 확인')}: ${item.expected.length ? item.expected.map(safe).join('; ') : label('No explicit assertion', '명시된 검증 없음')}`);
+        if (item.reason)
+            lines.push(`- ${label('Reason', '실행 상태 근거')}: ${safe(localizeProductMessage(item.reason, locale))}`);
+        if (item.attempts.length === 0)
+            lines.push(`- ${label('Observed', '실제 확인')}: ${label('No execution attempts', '실행 시도 기록 없음')}`);
+        for (const attempt of item.attempts) {
+            const observed = attempt.steps.filter((step) => step.status !== 'passed').map((step) => `${safe(step.api)}: ${safe(step.label)} (${safe(step.status)})`);
+            lines.push(`- ${label('Attempt', '시도')} ${attempt.index + 1}: ${safe(attempt.status)} · ${attempt.durationMs}ms`);
+            if (observed.length)
+                lines.push(`  - ${label('Observed evidence', '실제 근거')}: ${observed.join('; ')}`);
+            if (attempt.error)
+                lines.push(`  - ${label('Error', '실제 오류')}: ${safe(attempt.error.code)}: ${safe(attempt.error.message)}`);
+            for (const artifact of attempt.artifacts) {
+                const href = evidenceLink(artifact);
+                if (href)
+                    lines.push(`  - ${label('Evidence', '증거')}: [${safe(artifact.kind)}](${href})`);
+            }
+        }
+        lines.push('');
+    }
+    if (report.errors.length) {
+        lines.push(label('## Run errors', '## 실행 오류'), '');
+        for (const error of report.errors)
+            lines.push(`- ${safe(localizeProductMessage(error, locale))}`);
+        lines.push('');
+    }
+    if (report.usage) {
+        lines.push(label('## Model usage', '## 모델 사용량'), '', `- ${label('Tokens', '토큰')}: ${report.usage.modelTokens}`);
+        if (report.usage.modelCachedTokens !== undefined)
+            lines.push(`- ${label('Cached tokens', '캐시 토큰')}: ${report.usage.modelCachedTokens}`);
+        if (report.usage.estimatedCostUsd !== undefined)
+            lines.push(`- ${label('Estimated cost (USD)', '추정 비용(USD)')}: ${report.usage.estimatedCostUsd}`);
+        lines.push('');
+    }
+    lines.push(label('## Possible causes', '## 가능한 원인'), '', label('The observed evidence alone does not establish the cause. Check the raw report and local evidence.', '실패의 원인은 위 실제 근거만으로 단정하지 않습니다. 원본 보고서와 로컬 증거를 확인하세요.'), '');
+    return lines.join('\n');
+}

package/dist/src/schema.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+const text = z.string().trim().min(1).max(8192);
+export const idSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/);
+const httpURL = z.string().url().refine((value) => {
+    const url = new URL(value);
+    const loopback = url.hostname === 'localhost' || url.hostname.endsWith('.localhost') || url.hostname === '[::1]' || /^127\.\d+\.\d+\.\d+$/.test(url.hostname);
+    return (url.protocol === 'https:' || (url.protocol === 'http:' && loopback)) && !url.username && !url.password && !url.search && !url.hash;
+}, 'Use HTTPS (HTTP only on loopback), without credentials, query parameters, or fragments.');
+export const locatorSchema = z.discriminatedUnion('by', [
+    z.object({ by: z.literal('role'), value: z.enum(['button', 'link', 'textbox', 'heading', 'checkbox', 'radio', 'combobox', 'option', 'status', 'alert', 'dialog', 'tab', 'row', 'cell', 'list', 'listitem', 'navigation', 'searchbox', 'switch']), name: text.optional() }).strict(),
+    z.object({ by: z.enum(['text', 'label', 'testId']), value: text }).strict(),
+]);
+export const stepSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('open'), path: text.refine((v) => v.startsWith('/') && !v.startsWith('//') && !v.includes('\\'), 'Use an app-relative path starting with /.') }).strict(),
+    z.object({ type: z.literal('act'), instruction: text }).strict(),
+    z.object({ type: z.literal('click'), locator: locatorSchema }).strict(),
+    z.object({ type: z.literal('fill'), locator: locatorSchema, value: z.string().max(8192) }).strict(),
+    z.object({ type: z.literal('assertVisible'), locator: locatorSchema, visible: z.boolean().default(true) }).strict(),
+    z.object({ type: z.literal('assertText'), locator: locatorSchema, expected: text, match: z.enum(['equals', 'contains']).default('equals') }).strict(),
+    z.object({ type: z.literal('assertUrl'), expected: text }).strict(),
+    z.object({ type: z.literal('assertAgent'), instruction: text }).strict(),
+]);
+const caseSchema = z.object({
+    id: idSchema,
+    title: text,
+    requirementIds: z.array(idSchema).min(1),
+    preconditions: z.array(text).default([]),
+    questions: z.array(text).default([]),
+    steps: z.array(stepSchema).min(1).max(100),
+}).strict();
+export const suiteSchema = z.object({
+    schemaVersion: z.literal('flow-qa/suite-1'),
+    id: idSchema,
+    title: text,
+    source: z.object({ file: text, sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict().optional(),
+    requirements: z.array(z.object({ id: idSchema, text }).strict()).min(1).max(100),
+    cases: z.array(caseSchema).min(1).max(100),
+}).strict().superRefine((suite, ctx) => {
+    for (const [name, items] of [['requirements', suite.requirements], ['cases', suite.cases]]) {
+        if (new Set(items.map((item) => item.id)).size !== items.length)
+            ctx.addIssue({ code: 'custom', path: [name], message: 'IDs must be unique.' });
+    }
+    const ids = new Set(suite.requirements.map((r) => r.id));
+    const covered = new Set(suite.cases.flatMap((test) => test.requirementIds));
+    if (suite.requirements.some((r) => !covered.has(r.id)))
+        ctx.addIssue({ code: 'custom', path: ['requirements'], message: 'Every requirement must be covered by a case, including blocked cases.' });
+    suite.cases.forEach((test, index) => {
+        if (test.requirementIds.some((id) => !ids.has(id)))
+            ctx.addIssue({ code: 'custom', path: ['cases', index, 'requirementIds'], message: 'Unknown requirement ID.' });
+        if (!test.questions.length && !test.steps.some((s) => s.type.startsWith('assert')))
+            ctx.addIssue({ code: 'custom', path: ['cases', index, 'steps'], message: 'A runnable case needs an explicit assertion.' });
+    });
+});
+export const modelSchema = z.object({
+    baseURL: httpURL,
+    model: text,
+    apiKeyEnv: z.string().regex(/^[A-Z][A-Z0-9_]*$/).optional(),
+}).strict();
+export const plannerSchema = modelSchema;
+export const targetSchema = z.object({
+    url: httpURL,
+    description: z.string().max(2000).default(''),
+}).strict();
+export const configSchema = z.object({
+    schemaVersion: z.literal('flow-qa/config-1'),
+    targets: z.record(idSchema, targetSchema),
+    planner: plannerSchema.optional(),
+    agent: modelSchema.optional(),
+    timeoutMs: z.number().int().min(1000).max(900000).default(120000),
+    retries: z.number().int().min(0).max(2).default(0),
+}).strict();

package/dist/src/ui/entry.js

@@ -0,0 +1,109 @@
+import { lstat, mkdir, realpath } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { startUIServer } from "./server.js";
+import { startDemo } from "../../examples/demo/server.js";
+import { CONFIG_FILE, initWorkspace, writeJSON } from "../workspace.js";
+import { configSchema } from "../schema.js";
+import { localeFromEnv, localized } from "../i18n.js";
+class StartupError extends Error {
+}
+async function privateDirectory(parent, name) {
+    const directory = join(parent, name);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error('The demo workspace must be a regular directory.');
+    return directory;
+}
+async function start(args, locale) {
+    const { values } = parseArgs({ args, options: {
+            workspace: { type: 'string' }, port: { type: 'string' },
+            demo: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+            lang: { type: 'string' },
+        } });
+    if (values.lang && values.lang !== 'en' && values.lang !== 'ko')
+        throw new StartupError(localized(locale, 'Unsupported language. Use en or ko.', '지원하지 않는 언어입니다. en 또는 ko를 사용하세요.'));
+    if (values.help) {
+        console.log(localized(locale, 'Flow QA UI\n\nflow-qa ui [--workspace <directory>] [--port 4310] [--lang en|ko]\nflow-qa ui --demo [--port 4310] [--lang en|ko]\n\n--demo starts a separate local demo app and uses the .flowqa/ui-demo-en workspace.', 'Flow QA UI\n\nflow-qa ui [--workspace <directory>] [--port 4310] [--lang en|ko]\nflow-qa ui --demo [--port 4310] [--lang en|ko]\n\n--demo는 별도 로컬 데모 앱과 .flowqa/ui-demo-en 작업 공간을 사용합니다.'));
+        return;
+    }
+    const port = Number(values.port ?? 4310);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new StartupError(localized(locale, 'Port must be an integer from 0 to 65535. Example: flow-qa ui --port 4311', '포트는 0~65535 사이 정수여야 합니다. 예: flow-qa ui --port 4311'));
+    if (values.demo && values.workspace)
+        throw new StartupError(localized(locale, '--demo and --workspace cannot be used together.', '--demo와 --workspace는 함께 사용할 수 없습니다.'));
+    let workspace;
+    try {
+        workspace = await realpath(resolve(values.workspace ?? '.'));
+    }
+    catch {
+        throw new StartupError(localized(locale, 'Workspace directory not found. Run flow-qa init /path/to/my-qa first, then pass --workspace.', '작업 공간 디렉터리를 찾을 수 없습니다. 먼저 flow-qa init /path/to/my-qa로 준비한 뒤 --workspace로 지정하세요.'));
+    }
+    let demo;
+    let ui;
+    try {
+        if (values.demo) {
+            const privateRoot = await privateDirectory(workspace, '.flowqa');
+            workspace = await privateDirectory(privateRoot, 'ui-demo-en');
+            await initWorkspace(workspace);
+            demo = await startDemo(0);
+            const configPath = join(workspace, CONFIG_FILE);
+            const configInfo = await lstat(configPath);
+            if (!configInfo.isFile() || configInfo.isSymbolicLink())
+                throw new Error('The demo configuration must be a regular file.');
+            await writeJSON(configPath, configSchema.parse({
+                schemaVersion: 'flow-qa/config-1',
+                targets: { demo: { url: demo.url, description: 'Local task example · temporary data' } },
+                timeoutMs: 15000, retries: 0,
+            }));
+        }
+        if (!values.demo) {
+            try {
+                await lstat(join(workspace, CONFIG_FILE));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    throw new StartupError(localized(locale, 'flowqa.config.json is missing. Run flow-qa init /path/to/my-qa or start the local example with flow-qa ui --demo.', 'flowqa.config.json이 없습니다. flow-qa init /path/to/my-qa로 작업 공간을 준비하거나 flow-qa ui --demo로 로컬 예제를 시작하세요.'));
+                throw error;
+            }
+        }
+        ui = await startUIServer({ workspace, port });
+        console.log(localized(locale, `Flow QA: ${ui.url}\nWorkspace: ${workspace}`, `Flow QA: ${ui.url}\n작업 공간: ${workspace}`));
+        if (demo)
+            console.log(localized(locale, `Local demo app: ${demo.url}\nOpen the example in the case library, review it, then run it in a real browser. No model call is made.`, `로컬 데모 앱: ${demo.url}\n케이스 보관함에서 예제를 열고 검토한 뒤 실제 브라우저로 실행하세요. 모델 호출은 없습니다.`));
+        const shutdown = async () => {
+            process.off('SIGINT', onSignal);
+            process.off('SIGTERM', onSignal);
+            await ui?.close();
+            await demo?.close();
+        };
+        const onSignal = () => { void shutdown().catch(() => { process.exitCode = 1; }); };
+        process.once('SIGINT', onSignal);
+        process.once('SIGTERM', onSignal);
+    }
+    catch (error) {
+        await ui?.close();
+        await demo?.close();
+        throw error;
+    }
+}
+export async function main(args) {
+    const flag = args.find((value) => value.startsWith('--lang='))?.slice('--lang='.length);
+    const index = args.indexOf('--lang');
+    const requested = index >= 0 ? args[index + 1] : flag;
+    const locale = requested === 'en' || requested === 'ko' ? requested : localeFromEnv();
+    try {
+        await start(args, locale);
+    }
+    catch (error) {
+        const message = error instanceof StartupError ? error.message
+            : error?.code === 'EADDRINUSE' ? localized(locale, 'Port is already in use. Choose another one, such as flow-qa ui --port 4311.', '이미 사용 중인 포트입니다. flow-qa ui --port 4311처럼 다른 포트를 지정하세요.')
+                : localized(locale, 'Could not read the workspace configuration or start the server. Check flowqa.config.json and file permissions. See --help for usage.', '작업 공간 설정을 읽거나 서버를 시작하지 못했습니다. flowqa.config.json의 형식과 파일 접근 권한을 확인하세요. --help로 사용법을 볼 수 있습니다.');
+        console.error(`Flow QA UI: ${message}`);
+        process.exitCode = 1;
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href)
+    void main(process.argv.slice(2));

package/dist/src/ui/evidence.js

@@ -0,0 +1,85 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+const MAX_EVIDENCE = 10 * 1024 * 1024;
+export class EvidenceError extends Error {
+    status;
+    constructor(status = 404) {
+        super(status === 413 ? 'Evidence files must be 10 MiB or smaller.' : 'No readable evidence file was found.');
+        this.status = status;
+    }
+}
+/** Only a report-selected, redaction-approved artifact can leave its run directory. */
+export async function readEvidence(runDir, report, selection) {
+    try {
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$/.test(selection.caseId) ||
+            !Number.isInteger(selection.attempt) || selection.attempt < 0 || !Number.isInteger(selection.artifact) || selection.artifact < 0)
+            throw new EvidenceError();
+        const testCase = Array.isArray(report.cases) ? report.cases.find((item) => item?.id === selection.caseId) : undefined;
+        const attempt = Array.isArray(testCase?.attempts) ? testCase.attempts[selection.attempt] : undefined;
+        const artifact = Array.isArray(attempt?.artifacts) ? attempt.artifacts[selection.artifact] : undefined;
+        if (!artifact || !['complete', 'not-required'].includes(artifact.redaction) || typeof artifact.path !== 'string')
+            throw new EvidenceError();
+        const relative = artifact.path;
+        if (!relative.startsWith('raw/artifacts/') || /[\\\x00-\x1f\x7f?#]/.test(relative))
+            throw new EvidenceError();
+        const parts = relative.split('/');
+        if (parts.some((part) => !part || part.startsWith('.')))
+            throw new EvidenceError();
+        const extension = path.extname(relative).toLowerCase();
+        const types = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.txt': 'text/plain; charset=utf-8', '.json': 'text/plain; charset=utf-8', '.log': 'text/plain; charset=utf-8' };
+        const contentType = types[extension];
+        if (!contentType)
+            throw new EvidenceError();
+        const rootInfo = await lstat(runDir);
+        if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+            throw new EvidenceError();
+        const root = await realpath(runDir);
+        let current = root;
+        for (let index = 0; index < parts.length; index++) {
+            current = path.join(current, parts[index]);
+            const info = await lstat(current);
+            if (info.isSymbolicLink() || (index < parts.length - 1 ? !info.isDirectory() : !info.isFile()) || await realpath(current) !== current)
+                throw new EvidenceError();
+        }
+        const handle = await open(current, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let body;
+        try {
+            const info = await handle.stat();
+            if (!info.isFile())
+                throw new EvidenceError();
+            if (info.size > MAX_EVIDENCE)
+                throw new EvidenceError(413);
+            // Bounded reads also cover a file growing after stat.
+            body = Buffer.alloc(Math.min(info.size + 1, MAX_EVIDENCE + 1));
+            let offset = 0;
+            while (offset < body.length) {
+                const { bytesRead } = await handle.read(body, offset, body.length - offset, offset);
+                if (!bytesRead)
+                    break;
+                offset += bytesRead;
+            }
+            if (offset > MAX_EVIDENCE || offset > info.size)
+                throw new EvidenceError(413);
+            body = body.subarray(0, offset);
+        }
+        finally {
+            await handle.close();
+        }
+        const image = contentType.startsWith('image/');
+        if (contentType === 'image/png' && !body.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+            throw new EvidenceError();
+        if (contentType === 'image/jpeg' && !body.subarray(0, 3).equals(Buffer.from([255, 216, 255])))
+            throw new EvidenceError();
+        if (contentType === 'image/webp' && (body.toString('ascii', 0, 4) !== 'RIFF' || body.toString('ascii', 8, 12) !== 'WEBP'))
+            throw new EvidenceError();
+        if (!image)
+            new TextDecoder('utf-8', { fatal: true }).decode(body);
+        return { body, contentType, filename: `${selection.caseId}-attempt-${selection.attempt + 1}-evidence-${selection.artifact + 1}${extension}`, preview: image ? 'image' : 'text' };
+    }
+    catch (error) {
+        if (error instanceof EvidenceError)
+            throw error;
+        throw new EvidenceError();
+    }
+}