Skip to content

Preserve installed documentation packages when a rebuild fails #142

Description

@TheRealBecks

Rebuilding an installed package currently removes the working database before its replacement has been built. A failed rebuild can therefore leave no usable copy, and concurrent readers or directory watchers can observe an incomplete database.

This also affects the package-refresh work in #117, whose review identified packages disappearing or being advertised with zero sections during replacement.

The behavior is visible at upstream commit 149f112:

  • buildPackage() unlinks outputPath, opens a database at that same path, then creates the schema, writes metadata and chunks, and rebuilds FTS.
  • Its finally closes the database, but does not restore the previous package if initialization or a later build step fails.
  • downloadPackage() already downloads into a temporary file and validates it, but explicitly unlinks the installed destination before renaming the replacement.

Proposed behavior:

Build a replacement in a uniquely named temporary file in the destination directory. Close and validate it before switching the installed path. Preserve the existing package on any failure before replacement, and clean up temporary artifacts. The replacement strategy needs to be tested on supported operating systems, including Windows.

Temporary files should not be discoverable as installed packages. Package-store refresh should happen after a completed replacement, rather than interpreting an unreadable intermediate state as deletion.

Acceptance criteria:

  • Injected failures during database initialization, chunk insertion, FTS creation, validation, or final replacement leave the previous package readable and unchanged.
  • A successful rebuild installs the new package and removes its temporary artifacts.
  • Package discovery ignores temporary build/download files.
  • Concurrent readers and the refresh flow from fix(context): refresh get_docs when packages change on disk #117 do not advertise partial or zero-section replacements.
  • Tests cover replacement of an existing package as well as first installation.

This issue concerns the package-write lifecycle; #117 can address watcher-specific behavior separately.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions