Skip to content

Exit with code 3 when an output cannot be written and 5 when --serve fails; keep a JSON file on a failed export - #29

Merged
mahach666 merged 3 commits into
mainfrom
fix/cli-exit-codes
Nov 13, 2026
Merged

mahach666 merged 3 commits into
mainfrom
fix/cli-exit-codes

Conversation

@mahach666

@mahach666 mahach666 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Two exit-code defects of ioviewer found in the review of #28 and listed there as known limitations, and a JSON export that emptied an existing file before it failed.

What changes and why

  • An output that cannot be written. Only the HTML export caught errors, and only rejected data (InvalidDataException, ArgumentException). An I/O or access error (a locked file, a read-only folder, a folder where the file should be, a file where its folder should be) in creating the output folder, the HTML or JSON output or the --json file ended the tool with an unhandled exception. One handler around all exports now prints Error: Failed to export '<input>' to '<output>': <message> and returns 3, with IOException and UnauthorizedAccessException added to the filter. The success messages and the warning for undrawn meshes are unchanged.
  • --serve that cannot start or fails. StartServe printed HTTP Server error and Main then returned 0 (or 4 after an engine error). StartServe now returns false in that case and Main returns the new exit code 5; the output has been written before. A server stopped with Ctrl+C ends the process as before.
  • A JSON export that fails keeps the existing file. JsonViewerExporter.Save opened the target with FileMode.Create before it serialised, so data the serializer rejects (a non-finite coordinate) emptied an existing file. It now serializes once into Stream.Null before it opens the file, and then rewrites the file in place as before, so the file keeps its permissions (ACL, Unix mode), links and any valid name. This is how the HTML export already works (it builds the payload before it opens the page). The CLI's export error names the output that failed: Error: Failed to export '<input>' to '<output>': ..., because the page and the --json file can fail in one run.
  • --help lists code 5, says that code 3 also means an output that cannot be written, and that 3 and 5 take precedence over 4. README and CHANGELOG.md ([Unreleased], Fixed) say the same.

Tests

  • Cli_AnOutputThatCannotBeWritten_GivesExitCode3: a folder at the HTML output path, a folder at the JSON output path, a folder at the --json path (the page is written first), and a file where the output folder should be; each gives exit code 3 and starts standard error with Error: Failed to export.
  • Cli_ServeThatCannotStart_GivesExitCode5AfterThePageIsWritten: --serve 70000 (no port above 65535) gives 5, the page exists and standard error has the server error. The server fails before it opens a browser.
  • ViewerJson_SaveOfDataTheSerializerRejects_LeavesAnExistingFileAsItWas: an existing file keeps its content after a rejected export, and no other file is created. The CLI test also checks the named output.
  • ViewerJson_Save_RewritesAnExistingFileInPlace_KeepingItsPermissions: an existing file with permissions a new file never gets (a protected DACL for the current user on Windows, mode 0700 on Unix) keeps them after Save.
  • ViewerJson_Save_WritesAnyValidFileName: a 255-character file name, the longest valid one, is written.
  • The tests fail before their fix (an unhandled UnauthorizedAccessException; exit code 0; the existing file emptied). Against the intermediate version of this PR that wrote a temporary file and moved it over the target (058686e), each of the two tests fails on its own point: the protected DACL is replaced by the folder's inherited one, and the 255-character name gives IOException.
  • dotnet build IOViewer.slnx -c Release: 0 warnings. dotnet test: 124 passed, 1 skipped (the RVT test without IOVIEWER_RVT_FILE) on net8.0 and net10.0.
  • Independent reviews (9 and 4 agents) and a maintainer review: the help line for code 3, the README wording for code 5, the precedence note, the output named in the export error, the CHANGELOG wording, and the lost permissions and too long temporary name of the temporary-file approach, which is replaced by the serialize-first write, are fixed here.

Not checked

  • The Unix branch of the permissions test (mode 0700) has not run: CI runs dotnet test on Windows only, and there is no Linux .NET here.

Not changed here

  • No version bump; the fixes are under [Unreleased].

…fails

An I/O or access error while writing the page, the JSON output or the --json file ended the tool with an unhandled exception; one handler around all exports now reports it and returns 3. A preview server that could not start or failed left the exit code at 0 (or 4); it now gives the new code 5, after the output is written. The help, the README and the changelog list the codes.
JsonViewerExporter.Save opened the target with FileMode.Create before it serialised, so data the serializer rejects emptied an existing file. It now writes a temporary file beside the target and moves it over the target when complete, as IOScene's SceneJson.Save does. The exception of a failed move does not name the file, so the export error of ioviewer names the output that failed.
@mahach666 mahach666 changed the title Exit with code 3 when an output cannot be written and 5 when --serve fails Exit with code 3 when an output cannot be written and 5 when --serve fails; keep a JSON file on a failed export Nov 13, 2026
Writing a temporary file and moving it over the target replaced the target's own permissions with those a new file in the folder gets, and appended 37 characters to the name, so a valid long name failed. JsonViewerExporter.Save now serializes once into Stream.Null, which throws for data the serializer rejects before the file is opened, and then rewrites the file in place as before. Tests pin that a file keeps its permissions and that the longest valid name is written.
@mahach666
mahach666 merged commit d6e5579 into main Nov 13, 2026
5 checks passed
@mahach666 mahach666 mentioned this pull request Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant