diff --git a/README.md b/README.md index 826f16c..500f9c9 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,12 @@ dependency, privacy and isolation checks; it does not certify every input or pla ## Documentation editions +The current [Windows application guide](docs/reports/windows-application-guide.docx) +contains actual installed 0.4.3 screenshots, a worked source-inspection journey, +important source excerpts and explicit test limits. See the +[fresh desktop acceptance](docs/reports/windows-application-2026-11-10.md) and +[guide identities](docs/reports/windows-application-guide.json). + Start with the [organized handbook](docs/handbook.md) for current usage, design, security and test guidance. Reviewed downloadable editions: [project-guide.docx](docs/reports/project-guide.docx) · [validation-review.docx](docs/reports/validation-review.docx) · [validation-evidence.xlsx](docs/reports/validation-evidence.xlsx). [Publication identities and source scope](docs/reports/publications.json) · [Documentation validation record](docs/reports/documentation-refresh-2026-11-09.md). Historical results retain their own tested revision and date. diff --git a/docs/code-index.md b/docs/code-index.md index a500623..7b864f9 100644 --- a/docs/code-index.md +++ b/docs/code-index.md @@ -2897,17 +2897,18 @@ Generated declaration locations. Python uses AST; JS/TS uses declaration-line ma | variable | `directory` | 196 | | variable | `serviceLog` | 199 | | variable | `statuses` | 200 | -| variable | `lifecycle` | 265 | -| variable | `records` | 266 | -| variable | `launcher` | 273 | -| variable | `line` | 276 | -| variable | `service` | 281 | -| variable | `line` | 282 | -| variable | `diagnostic` | 289 | -| variable | `records` | 293 | -| variable | `stage` | 294 | -| variable | `record` | 306 | -| variable | `pid` | 319 | +| variable | `sourceInspector` | 223 | +| variable | `lifecycle` | 273 | +| variable | `records` | 274 | +| variable | `launcher` | 281 | +| variable | `line` | 284 | +| variable | `service` | 289 | +| variable | `line` | 290 | +| variable | `diagnostic` | 297 | +| variable | `records` | 301 | +| variable | `stage` | 302 | +| variable | `record` | 314 | +| variable | `pid` | 327 | ## tests/electron-readiness.test.cjs diff --git a/docs/handbook.md b/docs/handbook.md index 91d0358..dc73049 100644 --- a/docs/handbook.md +++ b/docs/handbook.md @@ -21,6 +21,12 @@ Turns report findings into a reproducible developer triage workflow while preser ## Read the documentation +For the current installed application, read the illustrated +[Windows application guide](reports/windows-application-guide.docx) and its +[observed native acceptance](reports/windows-application-2026-11-10.md). +The guide includes actual synthetic workspace/source-inspector screenshots, +immutable source excerpts and operating limits. + | Edition | Audience and contents | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | [project-guide.docx](reports/project-guide.docx) | User and developer guide: purpose, current usage, design, boundaries and source references. | diff --git a/docs/reports/windows-application-2026-11-10.md b/docs/reports/windows-application-2026-11-10.md new file mode 100644 index 0000000..84e9fe9 --- /dev/null +++ b/docs/reports/windows-application-2026-11-10.md @@ -0,0 +1,58 @@ +# Windows application acceptance — 10 November 2026 + +Author: Jason Stys. Runtime: published **0.4.3**, source +`1d0b19ed589947ae45e93555d97331c95cad26cc`. + +The existing installed Windows executable passed a fresh native user journey. +The test used separate temporary launcher and account directories, real account +registration, browser WebCrypto unlock, synthetic source editing, revision +storage, static review, exact-line source inspection, category browsing and +locking. It observed actual HTTP drain, workspace sealing, service-thread exit, +and disappearance of the owned service and bootloader PIDs. The installed Node +analyzer and CSharp bridge matched their release-resource SHA256 identities. +No real account was opened, no provider was called, and Docker was unchanged. + +## Reproduce and review + +Use the matching release installer and checksum from +[0.4.3](https://github.com/JasonStys/code-flow-studio/releases/tag/v0.4.3). +With the declared development dependencies installed, set `STUDIO_INSTALLED_APP` +to the installed executable and run `npm run test:desktop`. The test creates its +own synthetic account and launcher profiles; do not substitute a real data root. +Without that variable it exercises the development Electron launcher instead. + +The journey now captures three actual application views: the workspace, verified +source inspector and test catalog. The first two are embedded in the +[illustrated application guide](windows-application-guide.docx). Its +[publication evidence](windows-application-guide.json) binds the actual image +bytes and immutable source excerpts and records review of all four rendered +pages. The original reviewed Office editions remain historical evidence at their +own source and date. + +![Installed synthetic workspace](../screenshots/windows-application/desktop-workspace.png) + +![Verified source snapshot and exact physical line](../screenshots/windows-application/desktop-source-inspector.png) + +## Evidence boundaries + +- Fresh Windows source checks passed 417 tests with two platform-specific skips + and 85.12 percent controller/training coverage at the unchanged 80 percent + floor. Twelve Node tests, TypeScript, Ruff and 97 source maps also passed. + The Word file passed OOXML schema validation and review of all rendered pages. +- This installed journey passed once using the actual compiled executable; no + backend or account mock supplied the UI results. +- The 419 source tests, 28 subtests and 85.01 percent controller/training coverage + belong to the separately published 0.4.3 validation. They are not coverage + measurements of this one desktop journey. +- Hosted CSharp compiler/collector controls are documented in the + [coverage report](csharp-coverage-2026-11-10.md). Local compilation was not run + during this desktop check. A working isolated worker engine is required for it. +- Static unused-code candidates are review prompts, not proof of dead code. + Source digests bind retained bytes; they do not attest a malicious target. +- The test did not replay real credentials, migrate a populated user vault, + establish signed-installer reputation, or certify every Windows configuration. +- Existing account stores, the installed version and existing desktop shortcut + were retained. No new runtime version was needed for documentation captures. + +Current documentation-branch and main Actions checks are recorded separately +after they complete; the immutable runtime identity above remains unchanged. diff --git a/docs/reports/windows-application-guide.docx b/docs/reports/windows-application-guide.docx new file mode 100644 index 0000000..2d92bd9 Binary files /dev/null and b/docs/reports/windows-application-guide.docx differ diff --git a/docs/reports/windows-application-guide.json b/docs/reports/windows-application-guide.json new file mode 100644 index 0000000..7bd5ae0 --- /dev/null +++ b/docs/reports/windows-application-guide.json @@ -0,0 +1,84 @@ +{ + "schema": 1, + "repository": "code-flow-studio", + "runtimeVersion": "0.4.3", + "runtimeSource": "1d0b19ed589947ae45e93555d97331c95cad26cc", + "createdAt": "2026-11-10T23:09:57.579Z", + "author": "Jason Stys", + "document": "windows-application-guide.docx", + "sha256": "15f42a67a7580d3f4cb8e2d97926ccc6bb644f93c841cef06c30b4b32503fd18", + "screenshots": [ + { + "file": "desktop-workspace.png", + "sha256": "38828b82fa0f3b6871bda9c2dc95ca6c0dc9801fe4b2921462d237b97aaf8c70", + "width": 2139, + "height": 1407, + "caption": "The actual installed workspace with a synthetic project after revision save and static review. This overview illustrates the interface; the native journey independently verified real account creation, vault unlock, editing and history." + }, + { + "file": "desktop-source-inspector.png", + "sha256": "f5138722b3ec6e9c4f5840197276e16c498a1f34b778a12394b47397f5b671a1", + "width": 1634, + "height": 1239, + "caption": "The installed application highlights physical line 6 of helper.py in its immutable evidence snapshot. The current draft matches the verified source bytes. This is static evidence from a synthetic example, not a local compiler execution claim." + } + ], + "snippets": [ + { + "file": "runner/csharp_coverage_bridge.py", + "first": 239, + "last": 250, + "sha256": "64e1d4e2dfca531b58e595945e937b41de1334eaba71b729e85794f8ff4fcc41", + "url": "https://github.com/JasonStys/code-flow-studio/blob/1d0b19ed589947ae45e93555d97331c95cad26cc/runner/csharp_coverage_bridge.py#L239" + }, + { + "file": "ui/SourceInspector.tsx", + "first": 60, + "last": 79, + "sha256": "2413783242d19c11b1eab25dddb7a4985aec247689df7980ebe2ee2933797a73", + "url": "https://github.com/JasonStys/code-flow-studio/blob/1d0b19ed589947ae45e93555d97331c95cad26cc/ui/SourceInspector.tsx#L60" + } + ], + "observedTests": [ + { + "name": "Installed identity", + "observed": "Version 0.4.3, immutable release source and bundled Node analyzer and CSharp bridge hashes matched.", + "result": "Passed" + }, + { + "name": "Native user journey", + "observed": "One real installed executable journey passed with disposable registration, WebCrypto unlock, editor, revision, source inspection and 48 category catalog.", + "result": "Passed" + }, + { + "name": "Lock and shutdown", + "observed": "The journey checked vault lock, owned service drain, sealing and actual service and bootloader exit.", + "result": "Passed" + }, + { + "name": "Source release tests", + "observed": "The published source passed 419 tests and 28 subtests, with 85.01 percent controller and training coverage at the unchanged 80 percent floor.", + "result": "Passed" + }, + { + "name": "Hosted CSharp controls", + "observed": "Actual target exits 0, 1, 2, 7, 255 and malformed input 2 were measured; argument rejection, report write failure and timeout were blocked.", + "result": "Passed" + } + ], + "visualReview": { + "approved": true, + "method": "Every current rendered page individually viewed; pages 1 to 3 match the previously reviewed render byte for byte; page 4 inspected after the help-link pagination correction.", + "pageCount": 4, + "renderedPageSha256": { + "page-1.png": "df2043daff2b642f16f9bf42cb32f9fcc724b096496a1d645c700d2e75275d49", + "page-2.png": "c9bbef7496430f7bbb13843c5f6622defac12196d0b1f80dfb7c947ce3952fc0", + "page-3.png": "c85cf054d550823a2127a17b3b7e0348c73dba3ec6ca1ac68ab947d2c2bc6626", + "page-4.png": "5216facbd162c1a5d569ee53481a5db7f5d54925496e7bd8a9d7fb97d01b8a73" + } + }, + "structureValidation": { + "result": "passed", + "method": "OOXML schema/paragraph validation; explicit UTF-8 Python mode on Windows; all existing source text and image pixels retained." + } +} diff --git a/docs/screenshots/windows-application/desktop-source-inspector.png b/docs/screenshots/windows-application/desktop-source-inspector.png new file mode 100644 index 0000000..e0a3700 Binary files /dev/null and b/docs/screenshots/windows-application/desktop-source-inspector.png differ diff --git a/docs/screenshots/windows-application/desktop-workspace.png b/docs/screenshots/windows-application/desktop-workspace.png new file mode 100644 index 0000000..20c4e7e Binary files /dev/null and b/docs/screenshots/windows-application/desktop-workspace.png differ diff --git a/tests/desktop.spec.ts b/tests/desktop.spec.ts index 6fa8596..9f31a94 100644 --- a/tests/desktop.spec.ts +++ b/tests/desktop.spec.ts @@ -1,7 +1,7 @@ /* * Generated definition map; @L is the exact declaration line. * Function/class docs explain behavior; variables/parameters are scoped inputs, outputs or state. - * variables: { verifyElectron }@L24; { readDiagnosticLog }@L27; executable@L33; app@L36; launcherDirectory@L54; acceptedPackage@L57; resources@L64; file@L65; file@L91; metadata@L103; page@L123; accountStartedAt@L126; accountRoutes@L127; route@L129; route@L141; browserErrors@L153; health@L157; state@L165; directory@L196; serviceLog@L199; statuses@L200; lifecycle@L265; records@L266; launcher@L273; line@L276; service@L281; line@L282; diagnostic@L289; records@L293; stage@L294; record@L306; pid@L319 + * variables: { verifyElectron }@L24; { readDiagnosticLog }@L27; executable@L33; app@L36; launcherDirectory@L54; acceptedPackage@L57; resources@L64; file@L65; file@L91; metadata@L103; page@L123; accountStartedAt@L126; accountRoutes@L127; route@L129; route@L141; browserErrors@L153; health@L157; state@L165; directory@L196; serviceLog@L199; statuses@L200; sourceInspector@L223; lifecycle@L273; records@L274; launcher@L281; line@L284; service@L289; line@L290; diagnostic@L297; records@L301; stage@L302; record@L314; pid@L327 * */ /** Verify the actual Electron shell and bundled Python service, without faking readiness. @@ -220,7 +220,10 @@ test("bundled desktop authenticates, seals history and provides a sandboxed edit await editorJourney(page); console.info("NATIVE_JOURNEY_STAGE", "editor:complete"); console.info("NATIVE_JOURNEY_STAGE", "source-inspection:start"); - await inspectHelper(page); + const sourceInspector = await inspectHelper(page); + await sourceInspector.screenshot({ + path: "artifacts/desktop-source-inspector.png", + }); console.info("NATIVE_JOURNEY_STAGE", "source-inspection:complete"); console.info("NATIVE_JOURNEY_STAGE", "workspace-security:start"); await page.getByRole("button", { name: "Workspace", exact: true }).click(); @@ -236,6 +239,11 @@ test("bundled desktop authenticates, seals history and provides a sandboxed edit ); await page.getByRole("button", { name: "Test catalog" }).click(); await expect(page.locator(".catalog-grid article")).toHaveCount(48); + // Actual installed-app evidence for the user guide; synthetic profile only. + await page.screenshot({ + path: "artifacts/desktop-test-catalog.png", + fullPage: false, + }); await page.getByRole("button", { name: "Workspace", exact: true }).click(); expect(new URL(page.url()).hash).toBe(""); expect( @@ -245,7 +253,7 @@ test("bundled desktop authenticates, seals history and provides a sandboxed edit console.info("NATIVE_JOURNEY_STAGE", "screenshot:start"); await page.screenshot({ path: "artifacts/desktop-workspace.png", - fullPage: true, + fullPage: false, }); console.info("NATIVE_JOURNEY_STAGE", "screenshot:complete"); console.info("NATIVE_JOURNEY_STAGE", "lock:start");