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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyeonse Im
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,72 @@
+# Flow QA
+
+[English](https://github.com/hyeonse-swing/flow-qa/blob/main/README.md) · **한국어**
+
+사용자 플로우를 검토 가능한 테스트 케이스로 바꾸고, 실제 브라우저 실행 결과를 증거가 연결된 QA 리포트로 남기는 로컬 도구입니다. 플로우의 기대 결과가 모호하면 추측해 통과시키지 않고 질문과 차단 상태로 남깁니다.
+
+**공개 알파:** CLI와 `127.0.0.1` 전용 웹 UI를 제공합니다. UI는 영어로 시작하며 상단 언어 전환에서 한국어를 선택할 수 있습니다. 선택은 이 브라우저에 저장됩니다. 테스트 대상의 URL과 화면 계약을 사용하며 앱 소스 또는 데이터베이스 접근은 필수가 아닙니다. 설치 없이 구조를 보려면 [아키텍처](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/architecture.md)와 [UI 안내](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/ui.md)를 참고하세요.
+
+![로컬 데모 화면](https://raw.githubusercontent.com/hyeonse-swing/flow-qa/main/docs/media/flow-qa-demo.png)
+
+[1분 데모 영상](https://github.com/hyeonse-swing/flow-qa/releases/download/v0.1.0-alpha.1/flow-qa-demo.mp4) · 로컬 할 일 앱에서 예제 불러오기 → 케이스 검토 → 실제 Chromium 실행 → 리포트 확인. 영상은 모델 없이 고정된 세 케이스를 실행합니다.
+
+## 로컬 데모 시작
+
+Node.js 24 이상이 필요합니다. 패키지는 `@ihyeon/flow-qa@0.1.0-alpha.1`입니다. 브라우저는 첫 실행 전에 설치합니다.
+
+```sh
+npm install -g @ihyeon/flow-qa@0.1.0-alpha.1
+flow-qa browser install
+flow-qa ui --demo
+```
+
+출력된 로컬 UI 주소에서 **케이스 보관함 → 예제 불러오기 → 검토 → 실행** 순서로 진행합니다. 데모 앱과 별도 작업 공간이 함께 시작되며 API 키가 필요하지 않습니다. 결과는 현재 디렉터리의 `.flowqa/ui-demo-en/`에 저장됩니다. 기존 한국어 데모 데이터는 별도로 유지되며, 언어 전환은 예제·사용자 문장을 자동 번역하지 않습니다. 문제가 있으면 `flow-qa browser install --with-deps`로 Chromium의 시스템 의존성을 설치할 수 있습니다. 자세한 화면 동작은 [UI 안내](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/ui.md)에 있습니다.
+
+소스에서 개발하거나 검증을 재현하려면:
+
+```sh
+npm ci
+npx playwright install chromium
+npm run ui:demo
+npm run check
+npm run demo:smoke
+```
+
+`demo:smoke`는 정상 케이스, 의도적으로 실패하는 assertion, 앱 접속 불가를 실제 Chromium으로 확인합니다. 모델 호출 품질이나 외부 서비스 인증은 이 검사 범위에 포함되지 않습니다. 패키지 검증과 공개 절차는 [릴리스 기록](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/releases.md)에 따로 적습니다.
+
+## 내 서비스 연결
+
+테스트용 작업 공간에서 시작합니다. 연결한 앱에 실제 클릭과 입력이 발생하므로 테스트 환경과 데이터를 사용하세요.
+
+```sh
+flow-qa init my-qa
+flow-qa connect preview --url https://preview.example.test --workspace my-qa
+flow-qa ui --workspace my-qa
+```
+
+CLI만으로도 `flow-qa validate cases/my-flow.json --workspace my-qa`, `flow-qa generate cases/my-flow.json --workspace my-qa`, `flow-qa run cases/my-flow.json --target preview --workspace my-qa` 순서로 사용할 수 있습니다. `flow-qa --help`는 전체 명령을 보여줍니다. 대상과 모델 서버는 HTTPS를 사용하며 HTTP는 루프백 주소에서만 허용합니다.
+
+CLI 제품 문구는 영어가 기본이며 `--lang en|ko`가 선택적 환경 변수 `FLOW_QA_LANG`보다 우선합니다. 저장된 리포트 파일은 영어 제품 문구와 기존 상태 코드를 유지하고, UI에서는 선택한 언어의 제품 라벨로 Markdown 리포트를 내려받을 수 있습니다.
+
+`flows/my-flow.md`에는 시작 상태, 행동, 화면 요소, 기대 결과를 적습니다. 모델 없이 설계 프롬프트를 생성해 기존 AI에 전달하려면 `flow-qa plan flows/my-flow.md --prompt-only --workspace my-qa`를 실행합니다. 응답을 `cases/my-flow.json`에 저장한 뒤 검토하고 검증합니다. OpenAI 호환 모델을 직접 연결할 때는 다음처럼 설계 모델을 설정합니다.
+
+```sh
+flow-qa model planner --url http://localhost:11434/v1 --model your-model-id --workspace my-qa
+flow-qa plan flows/my-flow.md --workspace my-qa
+```
+
+인증이 필요하면 모델 설정에 `--key-env FLOW_QA_API_KEY`를 추가하고 실행 환경에 그 값을 제공하세요. 설정 파일에는 환경 변수 이름만 저장합니다. 플로우 문서는 지정한 설계 모델 서버로 전송됩니다. 브라우저의 자연어 조작 `act` 또는 모델 판정 `assertAgent`를 쓰려면 도구 호출·이미지 입력을 지원하는 **별도** `agent` 모델 설정이 필요합니다. 고정된 클릭·입력·검증 단계는 모델 없이 실행됩니다.
+
+## 설계 원칙과 결과 해석
+
+- 케이스는 요구사항 ID와 명시적인 assertion을 가집니다. `open`, `click`, `fill`, `act`, `assertVisible`, `assertText`, `assertUrl`, `assertAgent` 등 허용된 단계만 스키마로 검증해 컴파일합니다. 모델 응답의 임의 JavaScript나 shell 명령은 실행하지 않습니다.
+- 확인되지 않은 전제는 `questions`에 남기고 해당 케이스를 차단합니다. `preconditions`는 설명이며 계정·재고·로그인 상태를 자동 준비하지 않습니다.
+- 생성된 케이스는 원본 플로우의 해시를 기록합니다. 원본이 바뀌면 검증·생성·실행을 멈추고 다시 설계하도록 합니다. 생성과 실행은 별도 동작이며 입력 변경만으로 모델을 호출하지 않습니다.
+- 실행마다 `.flowqa/runs/<run-id>/`에 새 리포트와 엔진 결과를 만듭니다. `qa-report.json`과 `qa-report.md`는 통과, 실패, 재시도 후 통과, 차단, 오류, 미실행을 구분합니다. assertion 실패는 관찰 결과이며 제품 버그 확정은 아닙니다.
+- 취소한 실행은 중단으로 기록합니다. UI의 생성 취소는 늦게 도착한 응답을 반영하지 않지만 모델 제공자의 처리나 과금 취소를 보장하지 않습니다. 엔진의 토큰·추정 비용만 표시하며 전체 비용 상한은 없습니다.
+
+리포트와 원본 증거에는 테스트 앱의 데이터가 포함될 수 있습니다. `.flowqa/`는 Git에서 제외되지만 외부 공유 전에는 내용을 확인하세요. 마스킹이 모든 개인정보를 탐지한다고 보장하지 않습니다. 세션 준비, 모바일 기기, 예약 CI 실행, 팀 권한과 공유 서버는 이 알파의 지원 범위 밖입니다.
+
+## 구현과 출처
+
+Flow QA가 구현한 부분은 플로우·케이스 스키마, 설계 모델 연결, 컴파일, 실행 조율, 결과 해석과 로컬 UI입니다. 실제 브라우저 테스트 엔진은 [tester-army/e2e](https://github.com/tester-army/e2e)와 관련 패키지를 의존성으로 사용합니다. UI는 [Hyeonse Design System](https://github.com/hyeonse-swing/hyeonse-design-system)의 스타일 토큰과 선호 설정 유틸을 사용하며 화면 구성은 이 프로젝트에서 작성했습니다. [제3자 고지](https://github.com/hyeonse-swing/flow-qa/blob/main/THIRD_PARTY_NOTICES.md)와 [아키텍처](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/architecture.md)에 경계를 자세히 적었습니다.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# Flow QA
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [한국어](https://github.com/hyeonse-swing/flow-qa/blob/main/README.ko.md)
+
+Flow QA turns a user flow into reviewable test cases, runs them in a real browser, and ties the results to evidence in a QA report. When an expected outcome is unclear, it keeps the question visible and blocks that case instead of guessing.
+
+**Public alpha:** a CLI and a web UI bound to `127.0.0.1`. Provide a target URL and describe the screen behavior; access to the application's source code or database is optional. The UI starts in English. Use the language switch in the top bar for Korean; the choice is saved in this browser. See the [architecture](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/architecture.md) and [UI guide](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/ui.md) for the details.
+
+![Flow QA local demo](https://raw.githubusercontent.com/hyeonse-swing/flow-qa/main/docs/media/flow-qa-demo.png)
+
+[Watch the one-minute demo](https://github.com/hyeonse-swing/flow-qa/releases/download/v0.1.0-alpha.1/flow-qa-demo.mp4) · Load a local to-do app example, review its cases, run them in Chromium, and inspect the report. The 67-second recording uses the English UI, runs three fixed cases without a model, and demonstrates switching to Korean.
+
+## Try the local demo
+
+Requires Node.js 24 or later. Install Chromium before the first run:
+
+```sh
+npm install -g @ihyeon/flow-qa@0.1.0-alpha.1
+flow-qa browser install
+flow-qa ui --demo
+```
+
+Open the printed local UI address, then follow **Case library → Load → Review → Run QA**. The command starts a separate local demo app and workspace; no API key is needed. Results are saved under `.flowqa/ui-demo-en/` in the current directory. If Chromium lacks system libraries, use `flow-qa browser install --with-deps`. See the [UI guide](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/ui.md).
+
+To work from source or reproduce the checks:
+
+```sh
+npm ci
+npx playwright install chromium
+npm run ui:demo
+npm run check
+npm run demo:smoke
+```
+
+`demo:smoke` uses real Chromium to check a passing run, an intentionally wrong assertion, and an unreachable app. It does not establish model quality or authenticated behavior in another service. Package checks and release evidence are recorded in the [release notes](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/releases.md).
+
+## Connect your own app
+
+Start with a test workspace and test data: a run can click and enter text in the connected app.
+
+```sh
+flow-qa init my-qa
+flow-qa connect preview --url https://preview.example.test --workspace my-qa
+flow-qa ui --workspace my-qa
+```
+
+The CLI also supports `flow-qa validate cases/my-flow.json --workspace my-qa`, `flow-qa generate cases/my-flow.json --workspace my-qa`, then `flow-qa run cases/my-flow.json --target preview --workspace my-qa`. Run `flow-qa --help` for all commands. Target and model URLs require HTTPS; HTTP is allowed only on loopback.
+
+CLI product messages default to English; `--lang en|ko` overrides the optional `FLOW_QA_LANG` environment variable. Saved report files keep English product wording and unchanged status codes; the UI can download report Markdown with labels in the selected UI language.
+
+Describe the initial state, actions, screen elements, and expected result in `flows/my-flow.md`. To prepare a prompt for an AI you already use, run `flow-qa plan flows/my-flow.md --prompt-only --workspace my-qa`, save its JSON response as `cases/my-flow.json`, then review and validate it. To connect an OpenAI-compatible planner directly:
+
+```sh
+flow-qa model planner --url http://localhost:11434/v1 --model your-model-id --workspace my-qa
+flow-qa plan flows/my-flow.md --workspace my-qa
+```
+
+For authenticated models, add `--key-env FLOW_QA_API_KEY` to the model command and provide that environment variable to the process. The config stores the variable's name, not its value. The flow is sent to the planner endpoint you chose. Natural-language browser action (`act`) and model judgment (`assertAgent`) require a **separately configured** `agent` model that supports tools and images. Fixed clicks, inputs, and assertions run without a model.
+
+## Design choices and result interpretation
+
+- Every case references requirement IDs and a runnable case needs an explicit assertion. The schema accepts a fixed vocabulary including `open`, `click`, `fill`, `act`, `assertVisible`, `assertText`, `assertUrl`, and `assertAgent`. It never executes arbitrary JavaScript or shell commands returned by a model.
+- Unresolved assumptions go into `questions` and block that case. `preconditions` are descriptive; Flow QA does not prepare accounts, inventory, or login state automatically.
+- Generated cases record a hash of their source flow. If the flow changes, validation, compilation, and execution stop until the cases are redesigned. Planning and execution are separate actions; editing inputs does not call a model.
+- Each run gets a fresh `.flowqa/runs/<run-id>/` directory with engine output and `qa-report.json`/`qa-report.md`. Reports distinguish passed, failed, passed after retry, blocked, error, and skipped cases. A failed assertion is an observation, not proof of a product defect.
+- Cancellation records an interrupted run. Canceling generation prevents a late response from changing the draft, but does not guarantee cancellation of a provider's processing or charges. The UI shows token use and estimated cost only when the engine supplies them; there is no overall cost cap.
+
+Reports and raw evidence can contain data from the tested app. `.flowqa/` is Git-ignored, but inspect files before sharing them. Redaction cannot be assumed to catch every personal detail. Session setup, mobile devices, scheduled CI runs, team permissions, and a shared server are outside this alpha's scope.
+
+## Implementation and credits
+
+Flow QA owns the flow and case schema, planner integration, compilation, run orchestration, result interpretation, and local UI. [tester-army/e2e](https://github.com/tester-army/e2e) and related packages provide the browser test engine. The UI uses style tokens and preference utilities from [Hyeonse Design System](https://github.com/hyeonse-swing/hyeonse-design-system); this project's workflow screens are its own implementation. See the [third-party notices](https://github.com/hyeonse-swing/flow-qa/blob/main/THIRD_PARTY_NOTICES.md) and [architecture](https://github.com/hyeonse-swing/flow-qa/blob/main/docs/architecture.md) for those boundaries.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party components and fonts
+
+Flow QA uses [tester-army/e2e](https://github.com/tester-army/e2e) and `@e2e-dev/web` for browser test execution. Those packages are licensed under Apache-2.0 and retain their upstream LICENSE and NOTICE files in their installed distributions. Flow QA adds the flow specification, schema validation, orchestration, report interpretation, and local UI; it does not claim authorship of the execution engine.
+
+Flow QA uses `@hyeonse/design-system` from [Hyeonse Design System](https://github.com/hyeonse-swing/hyeonse-design-system), pinned to commit `38978c6a86f422fc0e63e919f600bc2dd3451e5c`. The npm tarball bundles this dependency so consumers do not need Git or GitHub credentials. Its MIT license and notices are preserved in the bundled package. Source checkout installation fetches the pinned public source archive over HTTPS.
+
+The local DM Sans and Noto Sans KR font files were copied from that repository's `docs/assets/fonts/` at the same commit. Their licenses are preserved in [DM Sans license](licenses/DM-Sans-LICENSE.txt) and [Noto Sans KR license](licenses/Noto-Sans-KR-LICENSE.txt).
+
+The Korean font is a subset and does not cover every Korean character. The UI falls back to installed Korean/system fonts for missing glyphs. No external font service is contacted.

package/dist/bin/flow-qa.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+await main(process.argv.slice(2));

package/dist/examples/demo/server.js

@@ -0,0 +1,31 @@
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+const html = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Flow QA · Demo</title>
+<style>body{font:17px system-ui;margin:60px auto;max-width:620px;padding:20px;color:#20302c;background:#f5f8f6}h1{font-size:32px}button,input{font:inherit;padding:10px;margin:4px;border:1px solid #bcc9c0;border-radius:6px}button{cursor:pointer;background:white}form{margin:30px 0}ul{padding:0}li{display:flex;align-items:center;justify-content:space-between;padding:12px;background:white;border-bottom:1px solid #ddd}#error{color:#b12525}</style>
+<main><p>FLOW QA / LOCAL FIXTURE</p><h1>Simple task list</h1><p>Try adding a task, validating the title, and filtering the list in a real browser.</p>
+<form id="form"><label for="title">Task title</label><input id="title" autocomplete="off"><button type="submit">Add</button></form>
+<p id="error" role="alert" hidden></p><nav aria-label="Filters"><button id="all">All</button><button id="active">Active</button></nav><ul data-testid="task-list" id="list"></ul></main>
+<script>
+const tasks=[];let activeOnly=false;
+const list=document.querySelector('#list');const error=document.querySelector('#error');
+function render(){list.replaceChildren();tasks.filter(t=>!activeOnly||!t.done).forEach(t=>{const li=document.createElement('li');const text=document.createElement('span');text.textContent=t.title;li.append(text);if(!t.done){const button=document.createElement('button');button.textContent='Complete';button.onclick=()=>{t.done=true;render()};li.append(button)}list.append(li)})}
+document.querySelector('#form').onsubmit=e=>{e.preventDefault();const input=document.querySelector('#title');const title=input.value.trim();if(!title){error.textContent='Enter a task title.';error.hidden=false;return}error.hidden=true;tasks.push({title,done:false});input.value='';render()};
+document.querySelector('#all').onclick=()=>{activeOnly=false;render()};document.querySelector('#active').onclick=()=>{activeOnly=true;render()};
+</script></html>`;
+export async function startDemo(port = 4178) {
+    const server = createServer((_request, response) => {
+        response.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+        response.end(html);
+    });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('No listening address');
+    return { server, url: `http://127.0.0.1:${address.port}`, close: () => new Promise((resolve, reject) => server.close((err) => err ? reject(err) : resolve())) };
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const demo = await startDemo(Number(process.env.PORT ?? 4178));
+    console.log(`Flow QA demo: ${demo.url}`);
+    process.once('SIGINT', () => { void demo.close(); });
+    process.once('SIGTERM', () => { void demo.close(); });
+}

package/dist/src/cli.js

@@ -0,0 +1,285 @@
+import { constants } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { readFile, writeFile, mkdir, access, stat } from 'node:fs/promises';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { chromium } from 'playwright';
+import { localeFromEnv, localized, localizeProductMessage } from "./i18n.js";
+import { configSchema, idSchema, modelSchema, targetSchema } from "./schema.js";
+import { CONFIG_FILE, initWorkspace, readConfig, readSuite, sha256, verifySuiteSource, writeJSON } from "./workspace.js";
+import { buildPlanningPrompt, planFlow } from "./planner.js";
+import { compileSuite } from "./compiler.js";
+import { runSuite } from "./engine.js";
+import { renderMarkdown } from "./report.js";
+const help = {
+    en: `Flow QA — turn user flows into repeatable tests and evidence-backed QA reports
+
+Usage: flow-qa <command> [arguments] [options]
+
+  init [directory]                    Create configuration and a local example (preserve existing files)
+  connect <name> --url <url>           Register a test target
+  model <planner|agent> --url <base> --model <id> [--key-env ENV_NAME]
+  plan <flow.md> [--out cases.json]    Plan cases with a model; produce a prompt if none is configured
+  plan <flow.md> --prompt-only         Create a prompt for your current AI tool
+  validate <cases.json>               Check case structure and assertions
+  generate <cases.json> [--out test.ts] Generate e2e test code
+  run <cases.json> --target <name>     Run against a registered target and save a QA report
+  report <run-directory>              View a saved QA report
+  compare <run-a> <run-b>              Compare case results
+  ui [--demo] [--port 4310]           Start the local QA UI
+  browser install [--with-deps]       Install this package's Playwright Chromium
+  doctor                              Check the local engine and connections
+
+Common: --workspace <directory> (default: current directory), --lang en|ko, --help
+First step: flow-qa init
+Local example: flow-qa ui --demo
+`,
+    ko: `Flow QA — 유저 플로우에서 반복 가능한 테스트와 QA 리포트까지
+
+사용법: flow-qa <command> [arguments] [options]
+
+  init [directory]                    설정과 로컬 예제 생성 (기존 파일 보존)
+  connect <name> --url <url>           테스트 대상 등록
+  model <planner|agent> --url <base> --model <id> [--key-env ENV_NAME]
+  plan <flow.md> [--out cases.json]    모델로 케이스 설계; 미연결 시 실행용 프롬프트 생성
+  plan <flow.md> --prompt-only         현재 사용하는 AI에 전달할 프롬프트 생성
+  validate <cases.json>               케이스 구조와 검증 조건 확인
+  generate <cases.json> [--out test.ts] e2e 테스트 코드 생성
+  run <cases.json> --target <name>     연결한 대상에서 실행하고 QA 리포트 저장
+  report <run-directory>              저장된 QA 리포트 보기
+  compare <run-a> <run-b>             케이스별 결과 비교
+  ui [--demo] [--port 4310]           로컬 QA 화면 실행
+  browser install [--with-deps]       패키지의 Playwright Chromium 설치
+  doctor                             로컬 엔진과 연결 설정 확인
+
+공통: --workspace <directory> (기본: 현재 폴더), --lang en|ko, --help
+첫 시작: flow-qa init
+로컬 예제: flow-qa ui --demo
+`,
+};
+function required(value, label, locale) {
+    if (!value)
+        throw new Error(localized(locale, `${label} is required. See --help.`, `${label}이 필요합니다. --help를 참고하세요.`));
+    return value;
+}
+function safeText(value) { return String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '); }
+async function writeOutput(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, { flag: 'wx', mode: 0o600 });
+}
+export function playwrightInstallInvocation(withDeps = false) {
+    const packageFile = fileURLToPath(import.meta.resolve('playwright/package.json'));
+    return { command: process.execPath, args: [resolve(dirname(packageFile), 'cli.js'), 'install', 'chromium', ...(withDeps ? ['--with-deps'] : [])] };
+}
+async function installBrowser(withDeps, locale) {
+    const { command, args } = playwrightInstallInvocation(withDeps);
+    if (!(await stat(args[0])).isFile())
+        throw new Error(localized(locale, 'Could not find the installed Playwright CLI.', '설치된 Playwright CLI를 찾지 못했습니다.'));
+    await new Promise((done, reject) => {
+        const child = spawn(command, args, { stdio: 'inherit', shell: false });
+        child.once('error', reject);
+        child.once('close', (code, signal) => code === 0 ? done() : reject(new Error(localized(locale, `Chromium installation did not complete (exit: ${code ?? signal ?? 'unknown'}).`, `Chromium 설치가 완료되지 않았습니다 (종료: ${code ?? signal ?? 'unknown'}).`))));
+    });
+}
+async function installedVersion(name, locale) {
+    let directory = dirname(fileURLToPath(import.meta.resolve(name)));
+    for (let depth = 0; depth < 6; depth++) {
+        try {
+            const value = JSON.parse(await readFile(resolve(directory, 'package.json'), 'utf8'));
+            if (value.name === name && typeof value.version === 'string')
+                return value.version;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    throw new Error(localized(locale, `Could not find installed ${name} package information.`, `설치된 ${name} 패키지 정보를 찾지 못했습니다.`));
+}
+async function chromiumInstalled() {
+    try {
+        const executable = chromium.executablePath();
+        if (!(await stat(executable)).isFile())
+            return false;
+        await access(executable, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function main(args) {
+    let locale = localeFromEnv();
+    try {
+        const { positionals, values } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+                workspace: { type: 'string' }, url: { type: 'string' }, model: { type: 'string' },
+                'key-env': { type: 'string' }, out: { type: 'string' }, target: { type: 'string' },
+                'prompt-only': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+                demo: { type: 'boolean' }, port: { type: 'string' }, 'with-deps': { type: 'boolean' }, lang: { type: 'string' },
+            } });
+        if (values.lang !== undefined) {
+            if (values.lang !== 'en' && values.lang !== 'ko')
+                throw new Error(localized(locale, 'Unsupported language. Use en or ko.', '지원하지 않는 언어입니다. en 또는 ko를 사용하세요.'));
+            locale = values.lang;
+        }
+        const [command, arg, second] = positionals;
+        const workspace = resolve(values.workspace ?? '.');
+        if (!command || (values.help && command !== 'ui')) {
+            console.log(help[locale]);
+            return;
+        }
+        if (values.demo && command !== 'ui' || values.port && command !== 'ui' ||
+            values['with-deps'] && (command !== 'browser' || arg !== 'install'))
+            throw new Error(localized(locale, 'This option is not supported for the command. See --help.', '이 명령에서 사용할 수 없는 옵션입니다. --help를 참고하세요.'));
+        if (command === 'ui') {
+            if (arg || second)
+                throw new Error(localized(locale, 'The ui command does not accept positional arguments.', 'ui 명령에는 위치 인자를 사용할 수 없습니다.'));
+            const forwarded = [
+                ...(values.workspace ? ['--workspace', values.workspace] : []),
+                ...(values.port ? ['--port', values.port] : []),
+                ...(values.demo ? ['--demo'] : []),
+                ...(values.help ? ['--help'] : []),
+                '--lang', locale,
+            ];
+            await (await import("./ui/entry.js")).main(forwarded);
+            return;
+        }
+        if (command === 'browser') {
+            if (arg !== 'install' || second)
+                throw new Error(localized(locale, 'The browser command only supports install. See --help.', 'browser 명령은 install만 지원합니다. --help를 참고하세요.'));
+            await installBrowser(Boolean(values['with-deps']), locale);
+            return;
+        }
+        if (command === 'init') {
+            const dir = resolve(workspace, arg ?? '.');
+            const files = await initWorkspace(dir);
+            console.log(localized(locale, `Workspace: ${dir}\nCreated: ${files.join(', ') || 'none (existing files preserved)'}`, `워크스페이스: ${dir}\n생성: ${files.join(', ') || '없음 (기존 파일 보존)'}`));
+            return;
+        }
+        if (command === 'connect') {
+            const config = await readConfig(workspace);
+            const name = idSchema.parse(required(arg, localized(locale, 'Target name', '대상 이름'), locale));
+            config.targets[name] = targetSchema.parse({ url: required(values.url, '--url', locale) });
+            await writeJSON(resolve(workspace, CONFIG_FILE), config);
+            console.log(localized(locale, `Target ${name} connected: ${config.targets[name].url}`, `대상 ${name} 연결: ${config.targets[name].url}`));
+            return;
+        }
+        if (command === 'model') {
+            if (arg !== 'planner' && arg !== 'agent')
+                throw new Error(localized(locale, 'Model role must be planner or agent.', '모델 종류는 planner 또는 agent여야 합니다.'));
+            const config = await readConfig(workspace);
+            const base = { baseURL: required(values.url, '--url', locale), model: required(values.model, '--model', locale), ...(values['key-env'] ? { apiKeyEnv: values['key-env'] } : {}) };
+            config[arg] = modelSchema.parse(base);
+            await writeJSON(resolve(workspace, CONFIG_FILE), config);
+            console.log(localized(locale, `${arg} model connection saved. No model call has been made. API key values are not saved in the configuration file.`, `${arg} 모델 연결 설정 저장. 실제 호출 전입니다. API 키 값은 설정 파일에 저장하지 않습니다.`));
+            return;
+        }
+        if (command === 'plan') {
+            const flowPath = resolve(workspace, required(arg, localized(locale, 'Flow file', '플로우 파일'), locale));
+            const flow = await readFile(flowPath, 'utf8');
+            if (Buffer.byteLength(flow) > 128_000)
+                throw new Error(localized(locale, 'The flow file must be 128 KB or smaller.', '플로우 파일은 128 KB 이하여야 합니다.'));
+            const config = await readConfig(workspace);
+            const stem = basename(flowPath).replace(/\.[^.]+$/, '');
+            if (values['prompt-only'] || !config.planner) {
+                const output = resolve(workspace, values.out ?? `planning/${stem}.prompt.md`);
+                await writeOutput(output, buildPlanningPrompt(flow));
+                console.log(localized(locale, `Planning prompt: ${output}\nSend it to your AI tool, save the returned JSON under cases/, then run validate → generate → run.`, `설계 프롬프트: ${output}\n연결된 AI에 전달하고 응답 JSON을 cases/에 저장한 뒤 validate → generate → run을 실행하세요.`));
+                return;
+            }
+            const output = resolve(workspace, values.out ?? `cases/${stem}.json`);
+            try {
+                await access(output);
+                throw new Error(localized(locale, 'The output file already exists. Use --out to choose a new path.', '출력 파일이 이미 있습니다. --out으로 새 경로를 지정하세요.'));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            const suite = await planFlow(flow, config.planner);
+            suite.source = { file: arg, sha256: sha256(flow) };
+            await writeJSON(output, suite, true);
+            console.log(localized(locale, `Cases created: ${output}\n${suite.cases.filter((c) => c.questions.length).length} of ${suite.cases.length} cases have open questions.`, `케이스 생성: ${output}\n${suite.cases.length}개 중 확인 질문이 있는 케이스 ${suite.cases.filter((c) => c.questions.length).length}개`));
+            return;
+        }
+        if (command === 'validate' || command === 'generate' || command === 'run') {
+            const suitePath = resolve(workspace, required(arg, localized(locale, 'Case file', '케이스 파일'), locale));
+            const suite = await readSuite(suitePath);
+            await verifySuiteSource(suite, workspace);
+            if (command === 'validate') {
+                console.log(localized(locale, `${suite.id}: ${suite.cases.length} valid cases. Blocked by questions: ${suite.cases.filter((c) => c.questions.length).length}`, `${suite.id}: ${suite.cases.length}개 케이스 유효. 질문으로 차단된 케이스: ${suite.cases.filter((c) => c.questions.length).length}`));
+                return;
+            }
+            if (command === 'generate') {
+                const output = resolve(workspace, values.out ?? `generated/${suite.id}.e2e.ts`);
+                await writeOutput(output, compileSuite(suite));
+                console.log(localized(locale, `Test script: ${output}`, `실행 스크립트: ${output}`));
+                return;
+            }
+            const config = await readConfig(workspace);
+            const targetName = values.target ?? (Object.keys(config.targets).length === 1 ? Object.keys(config.targets)[0] : undefined);
+            const controller = new AbortController();
+            const interrupt = () => controller.abort();
+            process.once('SIGINT', interrupt);
+            process.once('SIGTERM', interrupt);
+            try {
+                const { report, runDir } = await runSuite({ workspace, suite, config, targetName: required(targetName, '--target', locale), signal: controller.signal });
+                console.log(localized(locale, `Run result: ${report.status}\nQA report: ${resolve(runDir, 'qa-report.md')}\nRaw result: ${resolve(runDir, 'qa-report.json')}`, `실행 결과: ${report.status}\nQA 리포트: ${resolve(runDir, 'qa-report.md')}\n원본 결과: ${resolve(runDir, 'qa-report.json')}`));
+                process.exitCode = report.status === 'passed' ? 0 : report.status === 'interrupted' ? 130 : 1;
+            }
+            finally {
+                process.off('SIGINT', interrupt);
+                process.off('SIGTERM', interrupt);
+            }
+            return;
+        }
+        if (command === 'report') {
+            const runDirectory = resolve(workspace, required(arg, localized(locale, 'Run directory', '실행 폴더'), locale));
+            let content = await readFile(resolve(runDirectory, 'qa-report.md'), 'utf8');
+            if (locale === 'ko') {
+                try {
+                    content = renderMarkdown(JSON.parse(await readFile(resolve(runDirectory, 'qa-report.json'), 'utf8')), locale);
+                }
+                catch { /* Preserve the saved report if an older or malformed JSON report cannot be rendered. */ }
+            }
+            console.log(content.replace(/\u001b/g, ''));
+            return;
+        }
+        if (command === 'compare') {
+            const load = async (dir) => {
+                const data = JSON.parse(await readFile(resolve(workspace, required(dir, localized(locale, 'Run directory', '실행 폴더'), locale), 'qa-report.json'), 'utf8'));
+                if (!Array.isArray(data.cases) || typeof data.suiteHash !== 'string' || typeof data.suiteId !== 'string')
+                    throw new Error(localized(locale, 'This is not a valid QA report.', '유효한 QA 리포트가 아닙니다.'));
+                return data;
+            };
+            const before = await load(arg), after = await load(second);
+            const comparable = before.suiteHash === after.suiteHash && before.target.url === after.target.url;
+            console.log(comparable ? localized(locale, 'Comparing the same suite and target (check external data state separately)', '동일 명세·대상 비교 (외부 데이터 상태는 별도 확인)') : localized(locale, 'Suite or target differs; no direct regression verdict is made.', '명세 또는 대상이 달라 직접적인 회귀 판정은 하지 않습니다.'));
+            const previous = new Map(before.cases.map((c) => [c.id, c.status]));
+            const current = new Map(after.cases.map((c) => [c.id, c.status]));
+            for (const id of new Set([...previous.keys(), ...current.keys()]))
+                console.log(`${safeText(id)}: ${safeText(previous.get(id) ?? localized(locale, 'not included', '미포함'))} → ${safeText(current.get(id) ?? localized(locale, 'not included', '미포함'))}`);
+            return;
+        }
+        if (command === 'doctor') {
+            const config = configSchema.parse(await readConfig(workspace));
+            for (const pkg of ['e2e', '@e2e-dev/web', 'playwright']) {
+                console.log(`${pkg}: ${await installedVersion(pkg, locale)}`);
+            }
+            const hasChromium = await chromiumInstalled();
+            console.log(localized(locale, `Node: ${process.version}\nChromium: ${hasChromium ? 'installed' : 'missing (flow-qa browser install)'}\nTargets: ${Object.keys(config.targets).join(', ') || 'none'}\nPlanner model: ${config.planner ? 'configured' : 'not configured (prompt handoff available)'}\nAgent model: ${config.agent ? 'configured' : 'not configured (deterministic tests available)'}`, `Node: ${process.version}\nChromium: ${hasChromium ? '설치됨' : '미설치 (flow-qa browser install)'}\n대상: ${Object.keys(config.targets).join(', ') || '없음'}\n설계 모델: ${config.planner ? '연결 설정됨' : '미연결 (프롬프트 전달 가능)'}\n실행 모델: ${config.agent ? '연결 설정됨' : '미연결 (고정 조작 테스트 가능)'}`));
+            return;
+        }
+        throw new Error(localized(locale, `Unknown command: ${command}`, `알 수 없는 명령: ${command}`));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Flow QA: ${safeText(localizeProductMessage(message, locale))}`);
+        process.exitCode = 2;
+    }
+}

package/dist/src/compiler.js

@@ -0,0 +1,62 @@
+import { suiteSchema } from "./schema.js";
+const literal = (value) => JSON.stringify(value);
+function locatorCode(locator) {
+    if (locator.by === 'role') {
+        return locator.name === undefined
+            ? `screen.getByRole(${literal(locator.value)})`
+            : `screen.getByRole(${literal(locator.value)}, ${literal(locator.name)})`;
+    }
+    const method = { text: 'getByText', label: 'getByLabel', testId: 'getByTestId' }[locator.by];
+    return `screen.${method}(${literal(locator.value)})`;
+}
+function stepCode(step) {
+    switch (step.type) {
+        case 'open': return `await app.open(${literal(step.path)});`;
+        case 'act': return `await agent.act(${literal(step.instruction)});`;
+        case 'click': return `await ${locatorCode(step.locator)}.tap();`;
+        case 'fill': return `await ${locatorCode(step.locator)}.fill(${literal(step.value)});`;
+        case 'assertVisible': return `await expect(${locatorCode(step.locator)})${step.visible ? '' : '.not'}.toBeVisible();`;
+        case 'assertText': return `await expect(${locatorCode(step.locator)}).${step.match === 'contains' ? 'toContainText' : 'toHaveText'}(${literal(step.expected)});`;
+        case 'assertUrl': return `await expect(browser).toHaveURL(${literal(step.expected)});`;
+        case 'assertAgent': return `await agent.assert(${literal(step.instruction)});`;
+    }
+}
+export function expectedChecks(testCase) {
+    return testCase.steps.flatMap((step) => {
+        switch (step.type) {
+            case 'assertVisible': return [`${step.visible ? 'Visible' : 'Hidden'}: ${JSON.stringify(step.locator)}`];
+            case 'assertText': return [`Text ${step.match}: ${JSON.stringify(step.locator)} → ${step.expected}`];
+            case 'assertUrl': return [`URL: ${step.expected}`];
+            case 'assertAgent': return [`Agent assertion: ${step.instruction}`];
+            default: return [];
+        }
+    });
+}
+export function needsAgent(suite) {
+    return suite.cases.some((testCase) => !testCase.questions.length && testCase.steps.some((step) => step.type === 'act' || step.type === 'assertAgent'));
+}
+export function compileSuite(suite) {
+    const parsed = suiteSchema.parse(suite);
+    const lines = ["import { test } from '@e2e-dev/web';", "import { expect } from 'e2e';", ''];
+    for (const testCase of parsed.cases) {
+        const title = literal(`[${testCase.id}] ${testCase.title}`);
+        if (testCase.questions.length) {
+            lines.push(`test.skip(${title}, async () => {});`);
+            continue;
+        }
+        const fixtures = ['app'];
+        if (testCase.steps.some((step) => 'locator' in step))
+            fixtures.push('screen');
+        if (testCase.steps.some((step) => step.type === 'assertUrl'))
+            fixtures.push('browser');
+        if (testCase.steps.some((step) => step.type === 'act' || step.type === 'assertAgent'))
+            fixtures.push('agent');
+        lines.push(`test(${title}, async ({ ${fixtures.join(', ')} }) => {`);
+        if (testCase.steps[0]?.type !== 'open')
+            lines.push("  await app.open('/');");
+        for (const step of testCase.steps)
+            lines.push(`  ${stepCode(step)}`);
+        lines.push('});');
+    }
+    return `${lines.join('\n')}\n`;
+}