[html4tree Product Gap] Protect user-authored index.html and provide owned cleanup

[seonghobae]

Buyer-visible problem

html4tree currently writes to <directory>/index.html with replacement semantics, without first proving that an existing file was generated by html4tree. The README also recommends:

find <top directory to crawl> -name index.html -delete

That command cannot distinguish generated artifacts from user-authored home pages. A routine regeneration or cleanup can therefore overwrite or delete customer content.

The current write path already uses a temporary file and attempts ATOMIC_MOVE, which protects readers from torn output, but atomic replacement does not establish artifact ownership. Oracle documents ATOMIC_MOVE as an atomic filesystem move and separately documents that replacement requires REPLACE_EXISTING; neither option makes replacement semantically safe for an unrelated user file.

References:

• https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/StandardCopyOption.html
• https://dev.java/learn/java-io/file-system/move-copy-delete/
• https://cwe.mitre.org/data/definitions/73.html

Product contract

Introduce a versioned generated-artifact ownership contract rather than relying on the filename alone.

Generation

• Every generated document contains a machine-readable, versioned html4tree ownership marker.
• A new output may be created when index.html does not exist.
• An existing file may be replaced automatically only when its ownership marker is valid and supported.
• An unmarked or malformed existing index.html is preserved by default.
• The CLI reports the exact directory and the next safe action without exposing unrelated filesystem metadata in public HTML.
• Any explicit force-overwrite option is opt-in, prominently named, tested, and documented as destructive.

Cleanup

• Add a built-in cleanup/dry-run path that deletes only files carrying a valid html4tree marker.
• Never recommend a blanket find ... -name index.html -delete command.
• Cleanup output distinguishes selected, skipped-unowned, deleted, and failed artifacts.
• Symlink and root-boundary policy remains fail closed.

Migration

• Define how pre-marker html4tree outputs are detected or migrated without guessing from arbitrary HTML.
• Prefer an explicit one-time adoption command or manifest over heuristic ownership.

Verification

• User-authored index.html survives normal generation.
• Marked generated output is replaced atomically.
• Malformed, unsupported-version, oversized, and symlinked marker files are preserved and reported.
• Dry-run and cleanup select exactly the same owned artifact set.
• Interrupted generation leaves either the previous owned artifact or the complete new artifact.
• Recursive operation never escapes the requested root.
• Realistic tests include nested sites where only some directories opt into generated indexes.
• Production statement and branch coverage remain 100% and all public APIs have documentation.

Documentation and release gate

• ADR for artifact identity, overwrite, cleanup, migration, and rollback.
• README replaces the destructive cleanup command.
• CHANGELOG records the compatibility impact.
• Release notes explain the safe migration path.
• Do not call this commercial-ready until user-authored file preservation is demonstrated on Linux, macOS, and Windows filesystems.

Priority

High. This is a direct customer data-loss risk and a procurement blocker, not a cosmetic enhancement.

[seonghobae]

Implementing the buyer-visible ownership contract on ContextualWisdomLab/html4tree#453.

• Generated pages emit <meta name="generator" content="html4tree/1">.
• User-authored, malformed, late-marker, symlink, and directory index.html files are preserved.
• --cleanup / --dry-run select only owned artifacts.
• README no longer recommends find ... -name index.html -delete.

OPENCODE_REPOSITORY_DISPATCH_TARGETS now includes ContextualWisdomLab/html4tree so the PR can receive a real current-head OpenCode verdict (also #1003). Squash auto-merge is armed; two-approval remains a ruleset.