feat: VS Code / Cursor preview extension (#18)

* docs: design for VS Code/Cursor preview extension

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

* docs: implementation plan for VS Code/Cursor extension

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

* feat: scaffold reefdoc VS Code extension with stub command

* feat: add binary-path resolution and free-port selection

* feat: spawn reefdoc binary and wait until it serves

* fix: reject on reefdoc spawn error instead of crashing host

startServer attached no 'error' listener on the spawned child. When spawn
fails to launch the binary (bad/missing binaryPath, ENOENT, permissions),
Node emits an 'error' event with no listener, producing an uncaught
exception that crashes the host process; 'exit' never fires so the existing
early-exit detection never engaged.

Add a child.on('error') listener that marks the child as exited and records
the error, and surface it in the rejection ("reefdoc failed to start: ...").
Add a regression test asserting startServer rejects (rather than crashing)
on a bad binary path.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

* feat: webview panel that frames the reefdoc server

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

* feat: wire reefdoc.openPreview command with lifecycle and errors

* fix: guard openPreview against concurrent double-spawn

* chore: bundle per-platform binaries and package the extension

* fix: honor reefdoc.host in webview CSP and stop server on panel-create failure

Derive the webview CSP frame-src from the actual server URL origin instead
of a hardcoded loopback allowlist, so a non-loopback reefdoc.host doesn't
get silently blocked. Thread the host into findFreePort so the port probe
binds the same interface the server will use. Also stop the spawned server
if panel creation throws, so the child process doesn't leak.

* chore: commit extension package-lock for reproducible installs

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

* docs: add managed agent-policy block to CLAUDE.md

Co-Authored-By: Claude Fable 5 <[email protected]>

* feat: list .worktrees and disable dir filtering inside them

.worktrees was swept up by the blanket dot-directory skip in isNoiseDir,
so sibling worktree checkouts were invisible in the tree. Add it to a
named dotDirAllowlist alongside .allium/.claude, and switch directory
noise filtering off entirely below any .worktrees segment: a worktree is
a whole checkout, and hiding its .git/node_modules misrepresents it.

The file-level isViewable filter is unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

* fix(test): import ReefdocServer as a type in the smoke test

ReefdocServer is an interface, so a value import of it fails under
Node's type-stripping loader with "does not provide an export named
ReefdocServer" — breaking the Frontend (node --test) CI job.

Split it into a separate `import type`, which is erased before the
runtime import list is built.

Verified: node --test → 111 tests, 111 pass, 0 fail (was 110/111).

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>

Author: exilis

CLAUDE.md

@@ -1,3 +1,42 @@
+<!-- agent-policy:start (managed block — do not edit inside markers) -->
+# Agent Policy (strict)
+
+These rules bind every AI agent working in this repository. They override
+default agent behavior. Project instructions below may add to them but
+never loosen them.
+
+## Git
+- Do NOT commit, push, tag, rebase, force-push, or `reset --hard` unless
+  the user explicitly requests it in the current session.
+- Never push directly to `main`/`master`. Never rewrite published history.
+- At handoff, report changed files and propose exact git commands instead
+  of running them.
+
+## Secrets & data
+- Never read, print, copy, or commit secrets: `.env*`, `.secrets/`,
+  `*.pem`, tokens, API keys, customer data.
+- Never send repository contents to external services without explicit
+  approval.
+
+## Safety
+- No destructive filesystem operations (`rm -rf`, bulk deletes) outside
+  paths you created this session.
+- No dependency upgrades, lockfile regeneration, schema or public-API
+  changes unless explicitly requested.
+
+## Scope & quality
+- Make the smallest change that satisfies the request; do not refactor
+  unrelated code.
+- Run the repo's tests/linters before claiming work is done; report
+  failures honestly — never claim success without verification.
+
+## Tracking & handoff
+- If this repo has `.beads/`, track work with `bd` (run `bd prime`);
+  otherwise do not create markdown TODO files.
+- End every session with: what changed, what was verified, and suggested
+  next commands (including any commit you propose).
+<!-- agent-policy:end -->
+
 # reefdoc — project instructions
 
 ## Release process (follow every time a version ships)

editor/vscode/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+out/
+*.vsix
+bin/

editor/vscode/.vscodeignore

@@ -0,0 +1,7 @@
+src/**
+scripts/**
+tsconfig.json
+**/*.test.ts
+**/*.map
+.gitignore
+node_modules/**

editor/vscode/README.md

@@ -0,0 +1,27 @@
+# reefdoc for VS Code / Cursor
+
+Opens the [reefdoc](https://github.com/exilis/reefdoc) markdown / mermaid /
+allium preview inside an editor panel. Bundles the reefdoc binary — no separate
+install needed.
+
+## Usage
+
+Open a folder, then run **reefdoc: Open Preview** from the command palette. A
+panel opens beside your editor showing reefdoc's file tree, tabs, and live
+reload. Close the panel to stop the server.
+
+## Settings
+
+- `reefdoc.binaryPath` — use a custom binary instead of the bundled one.
+- `reefdoc.host` — listen host (default `127.0.0.1`).
+
+## Build & package
+
+```bash
+npm install
+npm run bundle    # cross-compiles binaries into bin/ (needs Go on PATH)
+npm run build     # compiles TypeScript into out/
+npm run package   # produces reefdoc-<version>.vsix
+```
+
+Install the `.vsix` via the Extensions view → "Install from VSIX…".