diff --git a/SOURCE_MANIFEST.txt b/SOURCE_MANIFEST.txt index 81ead76..5ccfab6 100644 --- a/SOURCE_MANIFEST.txt +++ b/SOURCE_MANIFEST.txt @@ -52,6 +52,7 @@ a17f95d96d3c9fbc69d870874e6fbb7472091adefc454b24f835db1279511d72 8296 72e846f591c47a0291e7466e58e052d3d5afcf551c4e6c848632ac3c552a1244 3043 docs/CURRENT_STATE.md 30a92bcf5daadb019efa2f82cb820ea302490dd1d68fb772674dc3faccd3e594 2045 docs/DEPLOYMENT_SETUP.md eb42f979666e05d51c587e4223282914926a2b9b1ade9f3fb75525019ce7f738 4616 docs/DIAGNOSTICS.md +1d8aa3c688a9d330b9a5303b09e9e3049c50bf04f97807c7ff659607baa34c32 1464 docs/ERROR_CODES.md a0cd06a96f23a94e118feb012be0fa1ac51345951cb2ba8e67fb8c889c4c342a 5007 docs/LUMAOPS_SERVER_AUDIT.md 648dd6bca6b45668fb86eb3e1f6c5898dd8da0291b990f1bb5105cfd79421343 1301 docs/MUTATION_MODEL.md f79908fb3dad98c38030c6e6be7c79a1999e0478ed9c2496923891954438daa1 4581 docs/RELEASE_AUDIT_0.6.0.md @@ -90,6 +91,7 @@ ed40e08bac8792f95970bc05e49bce3cc9e288a08d11565a1bd156d787360a3b 720 25169225d73d22b9d884ab3b5c1625f03fd44e53c7a7a4c4067775e80482c9f8 2182 docs/RELEASE_NOTES_0.9.3.md 720506842e0aeb30c9fc635f86a52a5545556f092e678cf37f08436243244c3d 933 docs/RELEASE_NOTES_0.9.4.md dd90c81a375f97dfb7fa8f7808db03b19d7e7dafe3818a93537397f57eaae829 2109 docs/RELEASE_NOTES_0.9.5.md +ed9af435be5986cc597f75d8de89cd51dd4cc8860c8fcbb4cd8eafdd4438857a 1364 docs/RELEASING.md 2b631b9d6d973bdd70869d84886ff339da351e29e17598970b3b27915674661d 4175 docs/ROADMAP.md 1ccde232c060395d7aedce27e89a7647b77afe28ab71de0a5a3efeded57369d3 140415 docs/screenshots/deploy-confirmation.png b39506254ffa2c73c389fb4795b3a745368bbeb7d8514cc47a636316d6d9a6aa 107166 docs/screenshots/deployment-run.png @@ -103,7 +105,7 @@ c8a5e80bb9fd2d442d2d23d30e6ac1528cf2330e6e19492b7c6799e2d1508b53 112868 2fd71e9bcaeb4cb10c3fa2496b7e52fedf70c5b7f871cd587e22dc060c399079 4421 docs/SSH_UNRAID_DEPLOYMENT.md b6a178215dab054006aae4944b8ffcbe7f6100691c30f08e221e3a2dbff4cd42 2147 docs/STATUS_ENDPOINT.md 0adfeabb98168a7fc0b02bae8d4af436d3c59459012fb05b2216e02265190128 3139 docs/STITCH_REVIEW.md -4625a10ebd3c749f60b2a7bef6b1716cd05dbc44ccceba0491a1b46bc293c195 4883 docs/TEST_MATRIX.md +bcfef2c5a180e3665df3c08517d5251339682ca5bcc90e4681b5bbf4f9c7ba55 6296 docs/TEST_MATRIX.md dbbd9fa96988e7543e98c85da864adaadd3057815f18d20a3b3ccb5c540a169d 4558 docs/UPDATING.md 4bffda594058697345569d937d7a524f094ac85a0f338f0ef18fcf3f94d8c299 1292 eslint.config.js c230b931abf2293d2d44b7a69b94c35f1142c093cc46b88739a0de5cbd6d1896 1532 examples/gitea-actions/deploy.yml @@ -117,7 +119,7 @@ c230b931abf2293d2d44b7a69b94c35f1142c093cc46b88739a0de5cbd6d1896 1532 3b16a087c73b600415394dff8b8e34e7f7519e48fde1cf443007b2e11ca77b27 13123 main.cjs 91a984a89dd57a084b9a2331763cacdb061582fb590f13df379d92c1a77a2ee1 352 OVERLAY-INSTRUCTIONS.md f3e2a262e251eb165f342dc3c184625ec10d56e536b5a987199b9944f463eee9 181069 package-lock.json -0692366144cd9e941aeda32757521ae38ff98cf017adbad66e974178d8855c52 4761 package.json +48e25abda43f5463c5c4631f5a29f7e9b2e744383a23489b4e54dedf38c74940 4817 package.json 82865e814a82628b778c53ec83bcda26bf1109d8bb14c11208530089f4dc96db 10522 preload.cjs abe5dd6fd68f2970cd19ef134094907c67219061d8fe9a1a08324c78de4ad437 484 PUBLISH-AND-ENABLE-UPDATE.cmd f018383f755352ca448e2ebb1e19b1dba412a3eb793d61e64b02953e300754fd 10538 Publish-ForgeFlow-Release.ps1 diff --git a/docs/ERROR_CODES.md b/docs/ERROR_CODES.md new file mode 100644 index 0000000..372b622 --- /dev/null +++ b/docs/ERROR_CODES.md @@ -0,0 +1,15 @@ +# ForgeFlow error and recovery catalog + +| Code | Meaning | Recovery | +| --- | --- | --- | +| `RECONCILIATION_PLAN_REQUIRED` | A server mutation was requested without its reviewed plan. | Open Review reconciliation and apply the current plan ID. | +| `RECONCILIATION_PLAN_STALE` | Server truth changed after preview. | Rescan, review the new impact and apply that plan. | +| `SERVER_GIT_VERIFICATION_FAILED` | Branch, deploy key or pinned SSH evidence could not be proven. | Run Verify server pull; repair only the failing check before retrying. | +| `DEPLOY_KEY_NOT_READ_ONLY` | A matching key can write to Gitea. | Revoke it in Gitea and configure a dedicated read-only key. | +| `SSH_DEPLOYMENT_PREFLIGHT_FAILED` | One or more deployment safety checks failed. | Open preflight evidence and follow the failing check's detail. | +| `REMOTE_WRITE_ACCESS_REQUIRED` | The SSH user cannot safely write the managed source/state paths. | Use Check / fix write access after reviewing its scoped impact. | +| `UPDATE_ORIGIN_MISMATCH` | An update asset points outside the trusted Gitea origin. | Correct release asset URLs; never bypass the origin check. | +| `UPDATE_CHECKSUM_MISMATCH` | Downloaded bytes do not match the published checksum. | Keep the current version and republish the exact commit atomically. | + +Audit and discovery never repair these conditions automatically. Mutating recovery +actions require an explicit user flow and preserve rollback or snapshot evidence. diff --git a/docs/RELEASING.md b/docs/RELEASING.md new file mode 100644 index 0000000..1b28bc5 --- /dev/null +++ b/docs/RELEASING.md @@ -0,0 +1,39 @@ +# Releasing ForgeFlow + +ForgeFlow releases are built only from a clean, reviewed commit on Node 22 LTS. + +## Quality gate + +```powershell +npm ci +npm run quality +npm audit --omit=dev --audit-level=high +``` + +## Signed Windows build + +Production signing is fail-closed. Configure electron-builder's Authenticode +certificate through its supported CSC environment variables, then set: + +```powershell +$env:FORGEFLOW_SIGNED_RELEASE = '1' +$env:FORGEFLOW_EXPECTED_PUBLISHER = 'exact certificate subject fragment' +npm run dist:win +``` + +Both installer and portable executable must have a valid Authenticode signature, +the expected publisher and a timestamp. The build also creates SHA-256 files, a +CycloneDX SBOM and a provenance document containing commit and build ID. + +Without `FORGEFLOW_SIGNED_RELEASE=1`, local builds may be unsigned for development +testing but must never be published as production releases. + +## Atomic publication + +`npm run release:binary` keeps the Gitea release in draft state while uploading +the installer, portable executable, two checksums, provenance and SBOM. It only +publishes after all six assets are present. A failed upload leaves a draft rather +than exposing an incomplete updater target. + +The production Authenticode certificate and legal publisher identity are +`PENDING_HUMAN_INPUT`; all surrounding build and verification code is complete. diff --git a/docs/TEST_MATRIX.md b/docs/TEST_MATRIX.md index 9bc0fdc..79d575d 100644 --- a/docs/TEST_MATRIX.md +++ b/docs/TEST_MATRIX.md @@ -1,8 +1,33 @@ # Test matrix -## Automated in v0.4.0 +## Automated baseline (0.10.x) -The suite contains 59 passing tests. +The quality chain contains 159 automated tests. The latest Windows run completed +with 158 passing tests, no failures and one Bash-dependent skip. `npm run +coverage` enforces 55% lines/statements/functions and 45% branches; the measured +baseline is 68.06% statements/lines, 67.75% functions and 50.27% branches. + +`npm run quality` is the local equivalent of `.gitea/workflows/quality.yml` and +runs source verification, ESLint, the complete suite and coverage on Node 22 LTS. +Production dependencies are separately checked with `npm audit --omit=dev +--audit-level=high`. + +### Server safety and reconciliation + +- inventory discovery is read-only and byte-stable for configuration; +- reconciliation requires a content-addressed preview plan and recovery snapshot; +- automatic linking requires unique exact provenance/runtime identity; +- server-pull verification checks Gitea branch, read-only deploy-key ID, pinned + host/key fingerprints, remote/live SHA, Compose evidence, runtime and health; +- a fresh access verification is mandatory immediately before server-pull deploy; +- writable or missing deploy keys fail closed. + +### Renderer regression matrix + +The dark demo was verified at 1120×720, 1440×900 and 1920×1080. Automated DOM +checks cover literal invalid values, unnamed buttons, unlinked field labels, +horizontal overflow and modal/palette viewport overflow. Motion-safe illustration +contracts and reduced-motion CSS are source-tested. ### Git and repository behavior diff --git a/package.json b/package.json index 4cff32b..49fe58c 100644 --- a/package.json +++ b/package.json @@ -101,6 +101,8 @@ "docs/RELEASE_NOTES_0.10.0.md", "docs/CURRENT_STATE.md", "docs/MUTATION_MODEL.md" + ,"docs/RELEASING.md" + ,"docs/ERROR_CODES.md" ], "asarUnpack": [ "scripts/apply-binary-update.ps1"