ClauseReader for VS Code

Standalone VS Code extension adapted from the ClauseReader 1.4.0 Reader and its portable document modules. The original Chrome extension remains a separate, read-only source project.

Current migration state

Feature-by-feature implementation and evidence status are tracked in docs/reverse-engineering/CLAUSEREADER_1.4.0_FEATURE_MATRIX.md. These development records are not shipped in the VSIX.

The extension uses a default VS Code Custom Text Editor for .md and .markdown, matching ClauseReader's automatic Markdown handoff. Other supported text formats keep their normal VS Code editor by default and remain available through ClauseReader's explicit open commands. Binary formats use a read-only Custom Editor. CSV, TSV, MathML, EML, Office, and image inputs are read as bytes so their source encoding and content are preserved. Markdown edits are applied through VS Code document edits. Local helper operations remain optional and fail closed when unavailable.

Use ClauseReader: Open Reader or Ctrl+Alt+Shift+M (Cmd+Option+Shift+M on macOS) to open the standalone Reader home without a file, ClauseReader: Open Active File from the editor title or Explorer to read the current local file, or ClauseReader: Open Document to choose a file. The standalone Reader reuses the workspace context but does not create a document or receive a synthetic document URI.

On first activation, ClauseReader opens the bundled welcome guide once; it opens again when the guide revision changes. Use ClauseReader: Show Welcome Guide to reopen it at any time.

The Workspace view supports multi-selection, filtered file search, sorting by name, extension, modified date or size, opening selected files in ClauseReader, and copying selected paths. When more than 5,000 matching files are found, the tree and file-search prompt indicate that the displayed results may be incomplete. These actions operate on the open VS Code workspace. Inside the Reader, New folder, copy, move, and remove manage imported browser-profile records in IndexedDB and do not change the original files; use VS Code Explorer for actual filesystem changes.

Drop files or folders from VS Code Explorer onto the Reader to import workspace copies. VS Code may require holding Shift while dragging an Explorer item into a Webview. Folder drops retain relative paths and are limited to the active local workspace.

The Reader toolbar exports the verified Report and Contract Linelinker package through a VS Code save dialog. The Command Palette also includes ClauseReader: Download Linelinker Skills for the same verified ZIP export, alongside ClauseReader: Show Current Reader State for document metadata only, ClauseReader: Export Reader Modes for portable S1–S3 JSON, ClauseReader: Export Diagnostics for a combined content-free extension and Native Host report, ClauseReader: Show Native Host Diagnostics, and ClauseReader: Clear Derived Preview Cache. The current-state view never displays document content or unsaved text. Reader panels and the Command Palette share this metadata within the active Extension Host session; the legacy workspace-persistent path snapshot is cleared at activation. The last two operations require the separately installed Native Host; diagnostics export remains available without it and records the helper as unavailable.

Set clausereader.diagnosticLogDirectory to an existing local folder to use it as the initial location for diagnostics exports. Leave it empty to use Extension global storage. VS Code asks you to confirm the destination for each export.

Optional Native Host

Workspace image recovery can import matching sibling images into the Reader's derived store. Native Host image search can import a matching image folder with bounded, hash-verified transfer and a compatibility fallback; these operations create Reader copies and do not modify source files.

Office-to-PDF previews, MSG parsing, and local missing-reference searches use the separately built ClauseReader Native Host. An unresolved Reader link can start a local-index search automatically, including legacy aliases; a unique match is imported as a Reader copy. If the helper is unavailable or finds no candidate, recovery continues with active-workspace search and file selection. Its source and VS Code-specific builder are included in this project; the helper ZIP remains separate from the VSIX, as does LibreOffice. The current optional unsigned-development Windows x64 helper ZIP is dist/ClauseReader-NativeHost-1.4.0-windows-x64-20261031-r27/ClauseReader-NativeHost-1.4.0-windows-x64.zip (8,353,374 bytes; SHA-256 370371e7a9f329eda551e01f226bda04f431371b2e296ccb90ad3f401e3b16e3); distribute it as a separate file alongside the VSIX. Its EXE is 8,524,347 bytes with SHA-256 58a82f43883b49630ebcfb840269ffc4afa2d9b57a5163882e589f85e772c2f7, and its manifest identifies windows-x64 / PE 0x8664. r27 routes LibreOffice version detection, Everything CLI search, and conversion through the bounded Windows Job Object runner; each worker starts suspended and is assigned to the kill-on-close job before it resumes. This package passed checksum and PE identity checks; runtime conversion and process-containment behavior remain unverified. Earlier r26/r25 package identity and r24 smoke results remain historical. The Extension Host adapter/UI route remains under verification. The extension launches the helper directly and does not require Chrome or Chrome Native Messaging registration. Set clausereader.nativeHostExecutable to the local path of ClauseReaderNativeHost.exe. The extension starts the process for an explicit health, conversion, MSG, diagnostics, or cache-clear request, and for unresolved-reference recovery when a local workspace file is not already available. In a source checkout, see docs/NATIVE_HOST_SETUP.md for the local build command, optional signing, prerequisites, and configuration.

Development

npm install
npm run build
code --extensionDevelopmentPath "$PWD" --new-window

Package a VSIX with npm run package. The package script compiles and bundles the Webview; it does not run a test suite.

Data and privacy

The Webview does not receive Node.js or shell access. Extension messages use a bounded allow-list, and diagnostics omit document content and file paths. PCCP V2 is contacted only by the explicit command. Configure the endpoint from the Reader to validate it before saving; the VS Code setting schema also flags values outside the HTTP/HTTPS and 4,096-character limits.