@ihyeon/flow-qa 0.1.1 → 0.1.3

package/README.ko.md

@@ -1,5 +1,7 @@
 # Flow QA
 
+[![npm 버전](https://img.shields.io/npm/v/%40ihyeon%2Fflow-qa?label=npm)](https://www.npmjs.com/package/@ihyeon/flow-qa) · [npm 패키지: @ihyeon/flow-qa](https://www.npmjs.com/package/@ihyeon/flow-qa)
+
 [English](https://github.com/hyeonse-swing/flow-qa/blob/main/README.md) · **한국어**
 
 사용자 플로우를 검토 가능한 테스트 케이스로 바꾸고, 실제 브라우저 실행 결과를 증거가 연결된 QA 리포트로 남기는 로컬 도구입니다. 플로우의 기대 결과가 모호하면 추측해 통과시키지 않고 질문과 차단 상태로 남깁니다.
@@ -14,7 +16,7 @@ CLI와 `127.0.0.1` 전용 웹 UI를 제공합니다. UI는 영어로 시작하
 Node.js 24 이상이 필요합니다. 브라우저는 첫 실행 전에 설치합니다.
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.1.1
+npm install -g @ihyeon/flow-qa@0.1.3
 flow-qa browser install
 flow-qa ui --demo
 ```
@@ -56,6 +58,8 @@ flow-qa plan flows/my-flow.md --workspace my-qa
 
 인증이 필요하면 모델 설정에 `--key-env FLOW_QA_API_KEY`를 추가하고 실행 환경에 그 값을 제공하세요. 설정 파일에는 환경 변수 이름만 저장합니다. 플로우 문서는 지정한 설계 모델 서버로 전송됩니다. 브라우저의 자연어 조작 `act` 또는 모델 판정 `assertAgent`를 쓰려면 도구 호출·이미지 입력을 지원하는 **별도** `agent` 모델 설정이 필요합니다. 고정된 클릭·입력·검증 단계는 모델 없이 실행됩니다.
 
+`flow-qa doctor --workspace my-qa`로 로컬 의존성과 모델 인증용 환경 변수의 설정 여부를 확인할 수 있습니다. 키 값은 출력하지 않고 모델 서버도 호출하지 않습니다. 환경 변수가 있어도 실제 인증 성공을 확인한 것은 아닙니다.
+
 ## 설계 원칙과 결과 해석
 
 - 케이스는 요구사항 ID와 명시적인 assertion을 가집니다. `open`, `click`, `fill`, `act`, `assertVisible`, `assertText`, `assertUrl`, `assertAgent` 등 허용된 단계만 스키마로 검증해 컴파일합니다. 모델 응답의 임의 JavaScript나 shell 명령은 실행하지 않습니다.

package/README.md

@@ -1,5 +1,7 @@
 # Flow QA
 
+[![npm version](https://img.shields.io/npm/v/%40ihyeon%2Fflow-qa?label=npm)](https://www.npmjs.com/package/@ihyeon/flow-qa) · [npm package: @ihyeon/flow-qa](https://www.npmjs.com/package/@ihyeon/flow-qa)
+
 **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.
@@ -14,7 +16,7 @@ Flow QA is available as a CLI and a web UI bound to `127.0.0.1`. Provide a targe
 Requires Node.js 24 or later. Install Chromium before the first run:
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.1.1
+npm install -g @ihyeon/flow-qa@0.1.3
 flow-qa browser install
 flow-qa ui --demo
 ```
@@ -56,6 +58,8 @@ 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.
 
+`flow-qa doctor --workspace my-qa` checks local dependencies and whether configured model-key environment variables are present. It does not print key values or call the model server; a present key does not confirm remote authentication.
+
 ## 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.

package/dist/src/cli.js

@@ -7,7 +7,7 @@ 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 { initWorkspace, readConfig, readSuite, sha256, verifySuiteSource, writeConfig, writeJSON } from "./workspace.js";
 import { buildPlanningPrompt, planFlow } from "./planner.js";
 import { compileSuite } from "./compiler.js";
 import { runSuite } from "./engine.js";
@@ -165,7 +165,7 @@ export async function main(args) {
             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);
+            await writeConfig(workspace, config);
             console.log(localized(locale, `Target ${name} connected: ${config.targets[name].url}`, `대상 ${name} 연결: ${config.targets[name].url}`));
             return;
         }
@@ -175,7 +175,7 @@ export async function main(args) {
             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);
+            await writeConfig(workspace, 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;
         }
@@ -268,11 +268,18 @@ export async function main(args) {
         }
         if (command === 'doctor') {
             const config = configSchema.parse(await readConfig(workspace));
+            const keyStatus = (apiKeyEnv) => !apiKeyEnv
+                ? localized(locale, 'key environment variable not configured', '키 환경 변수 미지정')
+                : localized(locale, `${apiKeyEnv}: ${process.env[apiKeyEnv] ? 'set' : 'missing'}`, `${apiKeyEnv}: ${process.env[apiKeyEnv] ? '설정됨' : '누락'}`);
             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 ? '연결 설정됨' : '미연결 (고정 조작 테스트 가능)'}`));
+            if (config.planner)
+                console.log(localized(locale, `Planner API key: ${keyStatus(config.planner.apiKeyEnv)}`, `설계 모델 API 키: ${keyStatus(config.planner.apiKeyEnv)}`));
+            if (config.agent)
+                console.log(localized(locale, `Agent API key: ${keyStatus(config.agent.apiKeyEnv)}`, `실행 모델 API 키: ${keyStatus(config.agent.apiKeyEnv)}`));
             return;
         }
         throw new Error(localized(locale, `Unknown command: ${command}`, `알 수 없는 명령: ${command}`));

package/dist/src/workspace.js

@@ -1,6 +1,6 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, open, readFile, realpath, rename, unlink, writeFile } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { configSchema, suiteSchema } from "./schema.js";
 export const CONFIG_FILE = 'flowqa.config.json';
 export async function readConfig(workspace) {
@@ -20,6 +20,54 @@ export async function writeJSON(path, data, exclusive = false) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, { flag: exclusive ? 'wx' : 'w', mode: 0o600 });
 }
+export async function writeConfig(workspace, config) {
+    const content = `${JSON.stringify(configSchema.parse(config), null, 2)}\n`;
+    const alias = resolve(workspace, CONFIG_FILE);
+    let file;
+    try {
+        file = await realpath(alias);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        try {
+            if ((await lstat(alias)).isSymbolicLink())
+                throw new Error('Configuration symlink target does not exist.');
+        }
+        catch (inspectError) {
+            if (inspectError.code !== 'ENOENT')
+                throw inspectError;
+        }
+        file = alias;
+    }
+    await mkdir(dirname(file), { recursive: true });
+    const temp = resolve(dirname(file), `.flowqa-config-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+        const handle = await open(temp, 'wx', 0o600);
+        created = true;
+        try {
+            await handle.writeFile(content, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temp, file);
+    }
+    catch (error) {
+        if (created) {
+            try {
+                await unlink(temp);
+            }
+            catch (cleanupError) {
+                if (cleanupError.code !== 'ENOENT')
+                    throw new AggregateError([error, cleanupError], 'Could not save configuration or clean up its temporary file.');
+            }
+        }
+        throw error;
+    }
+}
 export function sha256(text) { return createHash('sha256').update(text).digest('hex'); }
 export async function verifySuiteSource(suite, workspace) {
     if (!suite.source)

package/docs/releases.md

@@ -2,6 +2,40 @@
 
 The alpha entries below are historical release records. They document earlier package versions and checks.
 
+## Automated npm and GitHub releases
+
+A push to `main` publishes only when `package.json` changes to a new plain `X.Y.Z` version. Pull requests and pushes without a version change run verification without publishing. The package and lockfile versions must agree; the version must increase, and registry errors stop the release. Rerunning a successful publication skips the existing immutable npm version.
+
+The `publish` job in [ci.yml](../.github/workflows/ci.yml) waits for the full verification matrix on Ubuntu and macOS, then publishes through npm trusted publishing (OIDC). It uses the `latest` tag, requires the registry's `gitHead` to match the workflow commit, and checks the published package with a fresh consumer installation and three real Chromium demo cases. The commit check also applies when retrying an already published version. No npm token is stored in GitHub secrets. After the published package passes its consumer smoke check, a separate job creates the matching GitHub tag and release at the exact verified commit. It preserves existing releases and rejects a tag pointing to another commit. Rerunning an older release does not replace a newer latest release.
+
+For the next release, update the release notes and current installation examples, then bump the version before committing and pushing:
+
+```sh
+npm version patch --no-git-tag-version
+npm run check
+```
+
+Push the version change to `main` and check the **Verify release** workflow. A successful verification job alone does not confirm publication: the publish job and its registry smoke check must also pass. GitHub release completion is reported by the separate release job. Retry a transient failure by rerunning the same workflow; do not reuse a published version for different package contents.
+
+The npm trusted publisher is configured for GitHub repository `hyeonse-swing/flow-qa`, workflow `ci.yml`, with direct publishing allowed. See [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/) for account setup.
+
+## 0.1.3
+
+- `doctor` reports whether each configured planner or agent key environment variable is present, missing, or not configured. English and Korean diagnostics show no credential values and make no model requests. The command remains informational.
+- CLI target and model configuration updates write a private temporary file, synchronize it, and replace the configuration only after the new JSON is complete. Existing initialization and exclusive case-file creation behavior are preserved. This protects against partially written configuration during process interruption; it does not serialize concurrent CLI updates or guarantee rename durability after power loss.
+- CI runs the existing test, browser, UI, and package-install checks on Ubuntu and macOS before publishing. Successful npm publication and its consumer smoke check now also create the corresponding GitHub release.
+
+- Package: [`@ihyeon/flow-qa@0.1.3`](https://www.npmjs.com/package/@ihyeon/flow-qa/v/0.1.3)
+- Release: [GitHub 0.1.3](https://github.com/hyeonse-swing/flow-qa/releases/tag/v0.1.3)
+- Verification: [GitHub Actions](https://github.com/hyeonse-swing/flow-qa/actions/workflows/ci.yml)
+
+## 0.1.2
+
+Adds version-gated npm publishing from GitHub Actions and npm links in both README languages. Runtime behavior is unchanged from 0.1.1.
+
+- Package: [`@ihyeon/flow-qa@0.1.2`](https://www.npmjs.com/package/@ihyeon/flow-qa/v/0.1.2)
+- Verification and publication: [GitHub Actions](https://github.com/hyeonse-swing/flow-qa/actions/workflows/ci.yml)
+
 ## 0.1.1
 
 This release uses plain semver and the npm `latest` dist-tag. It includes the runtime fixes documented in the historical entry below, with no additional runtime changes. The existing runtime passed 47 tests and the browser checks recorded there. Version 0.1.1 metadata, package contents, and a fresh consumer installation were also verified: the installed `flow-qa` command worked and all three Chromium demo cases passed without model calls.
@@ -10,7 +44,7 @@ This release uses plain semver and the npm `latest` dist-tag. It includes the ru
 - Source and package: [GitHub release](https://github.com/hyeonse-swing/flow-qa/releases/tag/v0.1.1)
 - Public checks: [GitHub Actions](https://github.com/hyeonse-swing/flow-qa/actions/workflows/ci.yml)
 
-Use this version when checking the published package:
+Use the matching source revision when checking this historical package:
 
 ```sh
 FLOWQA_PACKAGE_SPEC=@ihyeon/flow-qa@0.1.1 npm run smoke:package

package/docs/ui.md

@@ -7,7 +7,7 @@ Use the target app's URL and a user flow to review cases, run them, and inspect
 Node.js 24 or later is required. Install Flow QA and start the local demo:
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.1.1
+npm install -g @ihyeon/flow-qa@0.1.3
 flow-qa browser install
 flow-qa ui --demo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihyeon/flow-qa",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "author": "Hyeonse Im",
   "repository": {