fix(docs): publish the docs cache through an atomic link swap

[amondnet]

Closes #14.

The window

unpack moved the verified tree onto <tag> itself. renameSync refuses a populated directory outright, so a publication over an existing tree had to move the old one aside first — and between those two renames the path every caller reads did not exist. A concurrent --no-fetch resolution landing in that window reported the version unavailable while a perfectly good tree was on disk.

The indirection

The bytes now land in a sibling directory named after their verified digest (<tag>.content-<sha12>/), and <tag> becomes a link onto it. Replacing a link is a single atomic rename: a reader arriving mid-publication sees the old tree or the new one, never neither.

docs/boot-3.5.16 -> boot-3.5.16.content-61c6a8ab2d09
docs/boot-3.5.16.content-61c6a8ab2d09/
docs/boot-3.5.16.tag

Keying on the digest also makes a --refresh over unchanged bytes free — the content directory is reused and the link re-points to the name it already had.

The four points the issue asked to decide

• What path and index report — the link, <tag>, unchanged from before. A caller's stored path stays valid across a refresh, which the resolved target would not; Grep output naming the tag rather than a digest is also the more legible half of that trade.
• Reclaiming superseded content — sweepLeftovers already reclaimed .staging- and .replaced-; it now covers .content- and .link- on the same TTL. A superseded tree is deliberately not deleted at publication time — a reader that opened it a moment earlier is still inside it. The sweep skips whatever the link currently points at, so a cache that is never refreshed does not delete itself an hour after it was filled.
• Windows — a junction, not a directory symlink: it needs neither Developer Mode nor elevation. A junction resolves only against an absolute path, so the link is written absolute there and relative everywhere else (a relative link keeps the cache tree movable).
• No link at all — where neither form can be created, publish falls back to moving the tree into place exactly as before. That reopens the window this change closes, which is the right trade: correctness over atomicity.

A cache written before this change is a real directory at <tag>; rename will not put a link over one, so that one publication still moves it aside, and every later one is the atomic swap.

Verification

• bun run typecheck, bun run lint, bun run coverage:check, bun run build:skill:check — all pass
• 217 tests pass; three added for the new behavior (the link layout and what path reports, re-pointing + reclaim on refresh, converting a pre-indirection cache)
• End-to-end against the live boot-3.5.16 release with the committed .mjs bundle under plain node: first resolve publishes the link, --no-fetch reads _index.md through it, --refresh over identical bytes reuses the content directory and leaves no debris

---

Summary by cubic

Closes #14. Replaces the docs cache's gap-prone two-step publication over <tag> with an atomic link swap, so concurrent readers see either the old or new content instead of an unavailable path.

Bug Fixes

• path and index continue to return <tag>, keeping stored paths valid across refreshes.
• Each publication gets its own random-suffixed content directory, so concurrent publishers of the same digest no longer race over one name.
• Superseded trees are retired the moment they are moved aside and swept after an hour; every leftover is aged by the entry's own time, not extraction time or a link's target.
• Windows uses junctions and moves the old entry aside first; link placement is re-attempted only while losing a race, with a bounded budget, before falling back to the direct tree swap, which restores the displaced entry on failure.
• Existing caches with a real directory at <tag> convert to the new layout on their next publication.
• Adds coverage for atomic publication, refresh cleanup, stale links, and legacy cache conversion.

^{Written for commit 54755bb. Summary will update on new commits.}

[codacy-production]

Not up to standards ⛔

🔴 Issues 3 critical · 33 high

Alerts:
⚠ 36 issues (≤ 0 issues of at least minor severity)

Results:
36 new issues

Category	Results
ErrorProne	1 high
Security	3 critical 32 high

View in Codacy

🟢 Metrics 0 complexity · 10 duplication

Metric	Results
Complexity	0
Duplication	10

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[greptile-apps]

Confidence Score: 3/5

This PR is not yet safe to merge because concurrent first publication can spuriously fail and a failed legacy-directory conversion can remove the valid public cache path.

Findings

1.  Concurrent Publication Can Fail ▶
2.  Failed Swap Removes Cache ▶
3.  Dangling Links Evade Cleanup ▶

Fix with agent prompt

### Issue 1
scripts/docs.ts:224-227
When two initial resolutions of the same archive run concurrently, both can see the digest-keyed content directory as absent. After one resolution renames its extracted tree into place, the other tries to rename onto the now-populated directory and fails, causing that caller to report the version unavailable even though the verified cache was published. Recheck for and reuse a usable tree when this rename loses the race. The bundled implementation in `skills/spring-docs/scripts/docs.mjs` has the same issue.

### Issue 2
scripts/docs.ts:266-277
When converting a legacy or fallback directory, this code first moves the valid target to `displaced`. If the staged-link rename then fails because of a concurrent publisher or filesystem error, the catch discards only the staged link and never restores the displaced tree. This leaves the public cache path missing until another download succeeds. Apply the rollback behavior already used by `swapOnto`. The bundled implementation in `skills/spring-docs/scripts/docs.mjs` has the same issue.

### Issue 3
scripts/docs.ts:363-370
A process killed after creating a staged `.link-*` entry can leave that symlink behind. The sweeper uses `statSync`, which follows the link, so once its content target is absent the stat throws and the swallowed exception prevents `rmSync` from reclaiming the entry. Using link metadata for aging these entries, or removing dangling links when stat fails, would prevent abandoned UUID-named links from accumulating. The bundled implementation in `skills/spring-docs/scripts/docs.mjs` has the same issue.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

• Preserves stable tag paths while allowing link-based publication and content reuse.
• Adds cleanup for superseded content and staged links.
• Adds coverage for link layout, refresh reclamation, and legacy-cache conversion.
• Updates the committed runtime bundle and documents the new layout.
• Concurrent initial publication and failed legacy conversion still contain cache-availability failures that should be addressed before merge.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Download archive] --> B[Verify SHA-256]
  B --> C[Extract into staging directory]
  C --> D{Digest content directory usable?}
  D -- No --> E[Rename extracted tree to tag.content-sha12]
  D -- Yes --> F[Reuse existing content tree]
  E --> G[Create staged tag.link-UUID]
  F --> G
  G --> H{Tag is a real directory?}
  H -- Yes --> I[Move legacy tree aside]
  H -- No --> J[Atomically rename staged link onto tag]
  I --> J
  J --> K[Readers access stable tag path]
  K --> L[Sweep expired non-live content and leftovers]

Loading

_{Reviews (1) · Last reviewed commit: "fix(docs): publish the docs cache throug..."}

[gemini-code-assist]

Code Review

This pull request introduces atomic publishing of unpacked documentation trees by utilizing symbolic links (or junctions on Windows) pointing to content directories named after their SHA-256 digests. This ensures readers never encounter a missing or partially written directory during updates. The feedback highlights a high-severity robustness issue in both the TypeScript and JavaScript implementations of linkOnto: if the link swap fails, the pre-existing directory moved to displaced is never restored, leaving the cache in a broken state. It is recommended to wrap the swap in a nested try-catch block to safely restore the displaced directory on failure.

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.

Re-trigger cubic</sub>

[amondnet]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces an atomic publishing mechanism for documentation caching by utilizing symbolic links (or Windows junctions) to point to unique content directories, preventing temporary path gaps during updates. Superseded directories are retired and cleaned up after a TTL. Feedback was provided regarding the retry logic in publish, where a duplicate expression in a conditional statement (!linkOnto && !linkOnto) causes cognitive overload and should be refactored for clarity.

[cubic-dev-ai]

2 issues found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/docs.ts">

<violation number="1" location="scripts/docs.ts:263">
P2: With three or more Windows refreshes overlapping, both link attempts can lose the target race and fall back to `swapOnto`, replacing the winner's junction with a plain directory and reopening the missing-path window this change is meant to close. Coordinate publication or retry until the link operation succeeds (while separately handling a genuinely unsupported link), rather than using a fixed two-attempt limit.</violation>
</file>

<file name="skills/spring-docs/scripts/docs.mjs">

<violation number="1" location="skills/spring-docs/scripts/docs.mjs:204">
P2: When migrating an old real-directory cache entry, a concurrent sweep can delete the `.replaced-*` tree between the first rename and this retirement call. Stamp `displaced` immediately after moving it aside, before publishing the new link, and apply the same ordering in `swapOnto`.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[sonarqubecloud]

Quality Gate failed

Failed conditions
7.1% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud