From 392174c5e36c71fe8827213e6370aa147f640219 Mon Sep 17 00:00:00 2001 From: onoderakosen89 <72384345+onoderakosen89@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:24:38 -0500 Subject: [PATCH 1/2] Set up saved-note workflow and independent checks --- examples/save-and-reload/app.mjs | 67 +++++++++++++++++++++ examples/save-and-reload/storage.test.mjs | 14 +++++ examples/save-and-reload/workflow.test.mjs | 68 ++++++++++++++++++++++ 3 files changed, 149 insertions(+) create mode 100644 examples/save-and-reload/app.mjs create mode 100644 examples/save-and-reload/storage.test.mjs create mode 100644 examples/save-and-reload/workflow.test.mjs diff --git a/examples/save-and-reload/app.mjs b/examples/save-and-reload/app.mjs new file mode 100644 index 0000000..092fe03 --- /dev/null +++ b/examples/save-and-reload/app.mjs @@ -0,0 +1,67 @@ +import { createServer } from 'node:http'; +import { readFile, writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseArgs } from 'node:util'; + +export async function readNote(file) { + try { return await readFile(file, 'utf8'); } + catch (error) { + if (error.code === 'ENOENT') return ''; + throw error; + } +} + +export async function writeNote(file, note) { + await writeFile(file, note, 'utf8'); +} + +function escapeHtml(value) { + return value.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>'); +} + +export function createApp({ directory, simulateBadWiring = false }) { + const readable = join(directory, 'note.txt'); + const writable = join(directory, 'draft.txt'); + return createServer(async (request, response) => { + try { + if (request.url !== '/' || !['GET', 'POST'].includes(request.method)) { + response.writeHead(404).end(); + return; + } + let status = ''; + if (request.method === 'POST') { + let body = ''; + for await (const chunk of request) { + body += chunk; + if (body.length > 8192) { + response.writeHead(413).end(); + return; + } + } + await writeNote(writable, new URLSearchParams(body).get('note') ?? ''); + status = '

Saved

'; + } + const note = escapeHtml(await readNote(readable)); + response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' }).end( + 'Save a note' + + '

Save a note

' + status + + '
', + ); + } catch { + response.writeHead(500).end('Note storage unavailable.'); + } + }); +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + const { values } = parseArgs({ options: { + data: { type: 'string' }, + port: { type: 'string', default: '3000' }, + 'miswired': { type: 'boolean' }, + } }); + if (!values.data) throw new Error('Choose an existing data directory with --data DIR.'); + const app = createApp({ directory: values.data, simulateBadWiring: values.miswired }); + app.listen(Number(values.port), '127.0.0.1', () => console.log('http://127.0.0.1:' + app.address().port)); +} diff --git a/examples/save-and-reload/storage.test.mjs b/examples/save-and-reload/storage.test.mjs new file mode 100644 index 0000000..a7eacf2 --- /dev/null +++ b/examples/save-and-reload/storage.test.mjs @@ -0,0 +1,14 @@ +import assert from 'node:assert/strict'; +import { mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import test from 'node:test'; +import { readNote, writeNote } from './app.mjs'; + +test('the storage function writes and reads an explicit file', async t => { + const directory = await mkdtemp(join(tmpdir(), 'tfl-storage-')); + t.after(() => rm(directory, { recursive: true, force: true })); + const file = join(directory, 'any-file.txt'); + await writeNote(file, 'first note'); + assert.equal(await readNote(file), 'first note'); +}); diff --git a/examples/save-and-reload/workflow.test.mjs b/examples/save-and-reload/workflow.test.mjs new file mode 100644 index 0000000..a5020b0 --- /dev/null +++ b/examples/save-and-reload/workflow.test.mjs @@ -0,0 +1,68 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { once } from 'node:events'; +import { mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { createInterface } from 'node:readline'; +import test from 'node:test'; +import { fileURLToPath } from 'node:url'; + +const entry = fileURLToPath(new URL('./app.mjs', import.meta.url)); +const miswired = process.env.TFL_DEMO_MISWIRED === '1'; + +async function fixture(t, seed) { + const directory = await mkdtemp(join(tmpdir(), 'tfl-workflow-')); + t.after(() => rm(directory, { recursive: true, force: true })); + if (seed) await writeFile(join(directory, 'note.txt'), seed, 'utf8'); + return directory; +} + +async function runApp(directory, operation) { + const env = { ...process.env }; + delete env.NODE_TEST_CONTEXT; + const args = [entry, '--data', directory, '--port', '0']; + if (miswired) args.push('--miswired'); + const child = spawn(process.execPath, args, { env, stdio: ['ignore', 'pipe', 'pipe'] }); + const done = once(child, 'close'); + done.catch(() => {}); + child.stderr.resume(); + const lines = createInterface({ input: child.stdout }); + const timeout = setTimeout(() => child.kill(), 5000); + try { + const first = await lines[Symbol.asyncIterator]().next(); + if (first.done || !/^http:\/\/127\.0\.0\.1:\d+$/.test(first.value)) { + throw new Error('Could not start independent application entry point'); + } + return await operation(first.value); + } finally { + clearTimeout(timeout); + lines.close(); + if (child.exitCode === null && child.signalCode === null) child.kill(); + await done; + } +} + +async function page(url, options) { + const response = await fetch(url, { ...options, signal: AbortSignal.timeout(3000) }); + if (response.status !== 200) throw new Error('HTTP check unavailable: ' + response.status); + return response.text(); +} + +async function saveAndReload(directory, note) { + const saved = await runApp(directory, url => page(url, { method: 'POST', body: new URLSearchParams({ note }) })); + assert.match(saved, /role="status">Saved page(url)); +} + +test('a saved note survives a fresh application process', async t => { + const directory = await fixture(t); + assert.match(await saveAndReload(directory, 'new note'), /]*>new note<\/textarea>/); +}); + +test('editing an existing note keeps the updated content after reload', async t => { + const directory = await fixture(t, 'existing note'); + const initial = await runApp(directory, url => page(url)); + assert.match(initial, /]*>existing note<\/textarea>/); + assert.match(await saveAndReload(directory, 'updated note'), /]*>updated note<\/textarea>/); +}); From fa0737bc0d753c438cda026cfd805f2579e04e55 Mon Sep 17 00:00:00 2001 From: onoderakosen89 <72384345+onoderakosen89@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:25:51 -0500 Subject: [PATCH 2/2] Verify saves through reopening the real application --- .github/workflows/ci.yml | 13 +++++++++++++ README.ja.md | 2 ++ README.md | 2 ++ README.zh-CN.md | 2 ++ examples/save-and-reload/README.md | 31 ++++++++++++++++++++++++++++++ examples/save-and-reload/app.mjs | 2 +- 6 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 examples/save-and-reload/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0629d6d..2c2527e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,3 +39,16 @@ jobs: run: | npm run --silent demo:repair -- --show-diagnosis > diagnosis.json jq -e '.status == "passed" and .diagnosis.action == "repair" and [.attempts[].number] == [1, 2, 3]' diagnosis.json + - name: Verify the save-and-reload example + run: | + workflow=examples/save-and-reload/workflow.test.mjs + npm run --silent check:node -- --id storage examples/save-and-reload/storage.test.mjs + status=0 + TFL_DEMO_MISWIRED=1 npm run --silent check:node -- --json --id before "$workflow" > before.json || status=$? + test "$status" -eq 1 + jq -e '.observation.outcome == "failure" and (.evidence | length) == 2' before.json + npm run --silent check:node -- --json --id after --resolves before "$workflow" | jq -e '.observation.outcome == "success" and .observation.resolves == "before"' + status=0 + npm run --silent check:node -- --json --id unavailable examples/save-and-reload/missing.test.mjs > unavailable.json || status=$? + test "$status" -eq 2 + jq -e '.observation.outcome == "unknown"' unavailable.json diff --git a/README.ja.md b/README.ja.md index be6b3b1..9ca88bf 100644 --- a/README.ja.md +++ b/README.ja.md @@ -28,6 +28,8 @@ npm run --silent demo:repair -- --show-stop モデルを呼ばずに見直しの流れを試すには `npm run --silent demo:repair -- --show-diagnosis` を実行します。組み込む際は `diagnose` を渡します。既定では2回の修正後に検査が落ちると、最新の検査、修正の経過、差分が `effort: "high"` とともに渡ります。見直しは読み取り専用で実行し、空でない文字列を持つ `{ action, cause, evidence, next }` を返します。現行仕様内で具体的に直せるなら `repair`、原因が不明なら `unknown`、仕様変更など判断が要るなら `human_decision` を返します。`repair` の場合だけ Low で1回修正し、同じ独立検査で確かめます。モデルの推論設定と読み取り専用の隔離は呼び出し側が適用します。 +[保存と再読込の例](examples/save-and-reload/README.md)では、「保存済み」と表示され、保存部品の検査が通っても、再読込で消える問題を確かめられます。 + ## 検査から始める作り方 1. **再現する。** 何が通ればよいかを決め、異常例と正常例を一つずつ試します。 diff --git a/README.md b/README.md index 68df4ec..46639f5 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ Run `npm run --silent demo:repair -- --chatgpt` to have Codex apply the fix at f To try the diagnosis path without model calls, run `npm run --silent demo:repair -- --show-diagnosis`. Pass a `diagnose` callback to enable this path in your integration. After two failed repairs by default, it receives the latest check, attempts, and diff with `effort: "high"`. Run it with read-only access. Return `{ action, cause, evidence, next }` with nonempty strings. Use `repair` when the evidence supports a concrete change within the current requirements, `unknown` when the cause is unclear, or `human_decision` when approval is needed. Only `repair` permits one more repair at `effort: "low"`, followed by the same independent check. The caller sets the model effort and provides read-only isolation. +The [save-and-reload example](examples/save-and-reload/README.md) shows how a “Saved” message and a passing storage check can hide a broken workflow. + ## The workflow 1. **Reproduce.** Run a small check against the behavior you expect, with a normal case to check for regressions. diff --git a/README.zh-CN.md b/README.zh-CN.md index c3da5c1..f33e6a6 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -28,6 +28,8 @@ npm run --silent demo:repair -- --show-stop 运行 `npm run --silent demo:repair -- --show-diagnosis` 可在不调用模型的情况下试用诊断流程。接入时提供 `diagnose` 回调。默认两次修复后检查仍失败,回调将收到最新检查结果、修复记录、差异和 `effort: "high"`。请以只读方式运行诊断,返回各字段均为非空字符串的 `{ action, cause, evidence, next }`。有证据支持在现有需求内修复时返回 `repair`,原因不明确时返回 `unknown`,需要人工决定时返回 `human_decision`。只有 `repair` 会触发一次 Low 修复,然后重新运行相同的独立检查。调用方负责设置模型推理强度和只读隔离。 +[保存并重新加载示例](examples/save-and-reload/README.md)演示了为何“已保存”提示和存储检查通过时,重新加载仍可能丢失内容。 + ## 工作流程 1. **复现问题。** 用一个小测试锁定预期行为,同时保留正常对照用例。 diff --git a/examples/save-and-reload/README.md b/examples/save-and-reload/README.md new file mode 100644 index 0000000..501735c --- /dev/null +++ b/examples/save-and-reload/README.md @@ -0,0 +1,31 @@ +# Check whether a note stays saved + +This example has two independent checks. The storage check proves that a helper can write and read a file. The workflow check proves that the application reads back the same note after a fresh start. A passing storage check and a visible “Saved” message can both occur while the workflow loses the note. + +## Try it in a browser + +From the repository root, start the example in its broken mode. It listens on your computer only. + +```sh +data=$(mktemp -d) +node examples/save-and-reload/app.mjs --data "$data" --port 0 --miswired +``` + +1. Open the URL printed by the command. Enter a note and click **Save**. The page says **Saved**. +2. Open the same URL in a fresh tab. The note is missing. +3. Stop the server with Ctrl+C, then run the same command without `--miswired`. Open the newly printed URL, enter a note, save it, and open the URL in a fresh tab. The note is present. +4. Edit the note, save it, and restart the fixed server with the same data directory. Open the new URL and check that it shows the edited text. + +## Run the checks + +```sh +npm run --silent check:node -- --id storage examples/save-and-reload/storage.test.mjs +TFL_DEMO_MISWIRED=1 npm run --silent check:node -- --id before examples/save-and-reload/workflow.test.mjs +npm run --silent check:node -- --id after --resolves before examples/save-and-reload/workflow.test.mjs +``` + +The storage check exits 0. The miswired workflow exits 1 even though the actual HTTP response says “Saved.” The fixed workflow exits 0 and covers both a new note and an edit of an existing note. Each workflow case posts to the form endpoint, starts a fresh application process using the same directory, and checks the HTML returned by GET. + +If the final check cannot run, report the result as unverified. For example, running the checker against a missing workflow test returns exit 2. If the test runs and the application cannot start, the workflow raises an execution error and the checker also returns an inconclusive result. + +To use this recipe in your own project, identify the entry point for saving and the entry point for reopening. Check that the reopened content exactly matches what you saved, then repeat with an existing record. Keep the low-level storage check for localizing failures and use the workflow check as evidence that the pieces work together. diff --git a/examples/save-and-reload/app.mjs b/examples/save-and-reload/app.mjs index 092fe03..7051989 100644 --- a/examples/save-and-reload/app.mjs +++ b/examples/save-and-reload/app.mjs @@ -22,7 +22,7 @@ function escapeHtml(value) { export function createApp({ directory, simulateBadWiring = false }) { const readable = join(directory, 'note.txt'); - const writable = join(directory, 'draft.txt'); + const writable = simulateBadWiring ? join(directory, 'draft.txt') : readable; return createServer(async (request, response) => { try { if (request.url !== '/' || !['GET', 'POST'].includes(request.method)) {