feat(llm-docs): add the platform module for bundled on-disk docs - #15242
Draft
midleman wants to merge 16 commits into
Draft
feat(llm-docs): add the platform module for bundled on-disk docs#15242midleman wants to merge 16 commits into
midleman wants to merge 16 commits into
Conversation
|
E2E Tests 🚀 Note No feature tags detected. If this PR needs feature coverage, add the tag above and retrigger the workflow. |
midleman
force-pushed
the
mi/bundle-docs-2a
branch
from
July 31, 2026 13:01
5423e4f to
b70a80d
Compare
- Add IDocsFileStore.isDirectory and use it in countFiles. Inferring file-ness from an empty readdir counted an empty directory as a file, which real extractors can produce, and relied on behaviour a node-backed store does not have (it throws ENOTDIR on a file). - Make _prune best-effort. A readdir or unlink failure threw out of ensure() and discarded an install that was already on disk. - Track a generation counter so invalidate() called mid-fetch is not overwritten by the completing attempt re-arming the session gate. - Log an unexpected HEAD status on the convergence check; 404 stays quiet. - Drop all-slashes segments in joinDocsPath, which left a trailing slash. - Encode the fake zip as JSON so entry contents cannot mis-split. - Assert state content after a 304, add empty-directory and mid-flight invalidate coverage, and cover joinDocsPath.
The cap exists to bound a write the digest cannot vet until the bytes have landed, not to express an expected bundle size. Since it ships baked into a client while the bundle publishes separately, a client that trips it falls back to web docs with no way to fix it after the fact. The publish pipeline now enforces the real size budget.
…tate Each rejection case now asserts the reason it was refused, so a case can no longer pass on a different failure than the one it names. Adds coverage for a state file pointing at a deleted version directory and for an unparseable state file, and replaces a test that asserted on the shape of the logger fake with one that asserts the level each outcome kind logs at.
"Ports" collides with base/common/ports.ts and base/node/ports.ts, which are about TCP ports, and the module does HTTP - so the name invites the wrong reading. "Sidecar" now reads as the container pattern more than the companion file it means here; "checksum file" says the same thing plainly and pairs with the digest it holds.
At install time the previous state.json already names the one directory being superseded, so delete it by name instead of sweeping the cache root. This removes the mtime guard, the DOCS_PRUNE_IDLE_MS constant, and the mtime port method, and closes the cross-window hazard by removing the scan that caused it. Crash debris is no longer collected; it is bounded by crash count and judged not worth the machinery (design doc revision 11).
The only 'artefact' left in src/vs; 37 files already use 'artifact'.
midleman
force-pushed
the
mi/bundle-docs-2a
branch
from
July 31, 2026 14:27
dbec324 to
3f7eb82
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Step 2a of the bundled on-disk docs work: a host-agnostic
platform/positronDocsmodule that downloads, verifies, caches, and serves the slim LLM docs bundle so the assistant can read docs from disk instead of fetchingpositron.posit.co. All I/O goes through three injected interfaces (HTTP, file store, archive), so the state machine is unit-testable with no DI container and no node imports.positronDocsBundle.ts-- types, URL resolution,bundle.jsonand checksum-file parsingpositronDocsIO.ts-- the three I/O interfaces plus theILocalDocsresult shapepositronDocsValidate.ts-- zip-entry traversal guard and extracted-bundle validationpositronDocsCache.ts-- the orchestrator: install, version convergence, single-flight, hard-failure throttlingNothing is wired up here -- no registration, no instantiation, unreachable at runtime until the next PR adds the extension-host service. That PR must not merge before this one.
Release Notes
New Features
Bug Fixes
Validation Steps
Unit tests added:
Two things worth a reviewer's attention:
_writeStateand cleanup deletes deliberately swallow their errors. The disk failures that break them are the same ones that break a download, so throwing would withdraw a valid cached bundle and violate the governing rule that a valid cache is always served.