docs: spec+plan for vscode-free domain (#239)

Phase 5 of the #234 restructure. shared/editor adapter, path-returning
Reader/Writer, Inject split (pure compute vs editor apply), removal of
the 3 remaining cross-feature edges, node-only unit tests. 5 staged steps.

Refs #239.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pajoma

docs/plans/2026-06-02-239-vscode-free-domain.md

@@ -0,0 +1,71 @@
+# Plan — Issue #239: vscode-free domain + `shared/editor` adapter
+
+> **Spec:** [docs/specs/2026-06-02-239-vscode-free-domain.md](../specs/2026-06-02-239-vscode-free-domain.md)
+> **Issue:** [pajoma/vscode-journal#239](https://github.com/pajoma/vscode-journal/issues/239)
+> **Branch:** `refactor/239-vscode-free-domain` (off `develop`)
+> **Created:** 2026-06-02
+
+## Approach
+
+Five staged steps, each test-green and independently shippable. Edges first (cheap, unblocks reasoning about ownership), then the editor adapter, then domain return-type changes, then tests. Keep `IEditor` on the `JournalController` so commands reach it via the interface (consistent with Phase 2 DI).
+
+## Steps
+
+### Step 1 — Remove cross-feature edges
+- **smart-input → entries:** move `Dialogues` to `shared/` (it is a generic UI service, already used broadly) OR move `ScanEntries` to `shared/`. Prefer moving `Dialogues` → `shared/dialogues/` since it implements `IDialogues` (a shared interface). Re-point `Container`.
+- **navigation → entries:** move `AbstractLoadEntryForDateCommand` to `shared/commands/` (or `features/entries` export consumed only via a shared base). Navigation extends the shared base.
+- **entries → notes:** in `loadPageForInput`, replace the direct `new LoadNotes(...)` branch with a note-input handler resolved from the `JournalController` (register a `noteLoader` in the container, or move the `NoteInput` branch up into the command-registration layer). Entries no longer imports `notes`.
+- Verify: cross-feature grep (the #234 Phase-4 script) returns zero edges; suite green.
+
+### Step 2 — `shared/editor/` adapter
+- Add `IEditor` to `shared/model/interfaces.ts`: `open(path)`, `show(doc)`, `save(doc)`, `createAndOpen(path, content)`, `applyEdit(doc, edits)` / `insert(doc, position, text)`.
+- Implement `EditorAdapter` in `shared/editor/`, moving the bodies from `Dialogues.openDocument/showDocument/saveDocument`, `Writer.createSaveLoadTextDocument`, and `Inject.injectString/injectInlineString`.
+- Add `editor: IEditor` to `JournalController` + `Container`.
+- Verify: suite green (behavior identical; just relocated).
+
+### Step 3 — Writer / Reader return data
+- `Writer.createEntryForPath/createWeeklyForPath` → return the resolved path + content (or a small `CreatedFile` record); the command/reader calls `editor.createAndOpen`.
+- `Reader.loadEntryFor*` → return `{ path, created: boolean }` (plain data, no `vscode`); the command opens via `editor.open`. The `onNotesInjected`/`entryOpened` event still fires from the command layer.
+- Drop `import * as vscode` from `reader.ts` / `writer.ts`.
+- Verify: `grep "vscode" reader.ts writer.ts` empty; suite green.
+
+### Step 4 — Inject split
+- Keep pure: `buildInlineString` (returns `InlineString`), position computation → return a plain `{ line, character }` instead of `vscode.Position`.
+- Move apply (`injectString`, `injectInlineString`, `injectInput`'s edit application) to `EditorAdapter`.
+- `inject.ts` pure half drops `vscode` import; the editor adapter owns `WorkspaceEdit`.
+- Verify: pure half has no `vscode`; suite green.
+
+### Step 5 — Node-only unit tests
+- Add `src/test/unit/` (plain node, not Extension Host) covering: path resolution (`PathResolver`), `buildInlineString`, position computation, `inferType`.
+- Wire into the test pipeline (separate `node --test` or extend compile-tests + a node runner). Document the command in AGENTS.md.
+- Verify: node-only tests pass without a display; full Extension-Host suite still green.
+
+## Test scenarios
+
+| Scenario | Check |
+|----------|-------|
+| Each step | `npm run check` green |
+| Step 1 | cross-feature edge grep → 0; commands-prev-next, commands-note, scan/quickpick tests green |
+| Step 2 | open/show/save + create-and-open behavior unchanged (commands-entry real-fs, issue-51 remote) |
+| Step 3 | `grep vscode reader.ts writer.ts` empty; entry/weekly create+open tests green |
+| Step 4 | `grep vscode` on Inject pure half empty; commands-inject (memo/task insertion) green |
+| Step 5 | node-only unit tests pass with no Extension Host |
+| Regression | full suite (238+) green after every step |
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| Return-type change ripples to many call sites | Stage 3/4 isolated; `IEditor` on `JournalController` keeps call sites uniform |
+| Remote-path edge cases (local-vs-remote open) regress | issue-51 + remote tests cover; keep `getResolvedEntryPathForLocalOpen` flow intact |
+| Inject apply semantics (WorkspaceEdit ordering) change | Move bodies verbatim into adapter; commands-inject asserts inserted text/position |
+| Moving `Dialogues` to shared churns imports | Mechanical; `Container` is the only constructor site |
+| Note-dispatch indirection adds complexity | Keep it minimal (a `noteLoader` callback or command-layer branch), not a generic plugin system |
+
+## Rollback
+
+Each step is a separate PR. Revert the offending PR; earlier steps remain valid. No settings/schema/data migration.
+
+## Reference spec
+
+[docs/specs/2026-06-02-239-vscode-free-domain.md](../specs/2026-06-02-239-vscode-free-domain.md)

docs/specs/2026-06-02-239-vscode-free-domain.md

@@ -0,0 +1,47 @@
+# Spec: vscode-free domain + `shared/editor` adapter (#239)
+
+> Follow-up to #234 (package-by-feature). Phases 1–4 merged via #235–#238.
+
+## Goal
+
+Separate **pure domain logic** from **VS Code editor I/O** so the bulk of `features/*/` can be unit-tested without an Extension Host. Introduce a single `shared/editor/` adapter that owns every `vscode.TextDocument`/`WorkspaceEdit`/`window` interaction; domain code works with paths, strings, and plain data. Also remove the 3 cross-feature import edges left after Phase 4.
+
+## Why now
+
+`Reader`, `Writer`, `Inject` (`src/features/entries/`) all import `vscode` and return `vscode.TextDocument`. Tests therefore need a real Extension Host (`@vscode/test-cli`, ~30 s) instead of fast node-only runs (`node -e`, ~ms). Pulling editor I/O behind one seam makes the create/resolve/format logic directly testable and confines the host dependency to one reviewed module — the highest-leverage testability win of the restructure (maintainer concurred this is its own issue).
+
+## Honest scope note
+
+Full purity is not uniform across the three services:
+- **Reader / Writer** — mostly path resolution + create-or-open; cleanly made path-returning.
+- **Inject** — deeply editor-bound (`TextDocument`, `Position`, `WorkspaceEdit`, line scanning). The *computation* (which template, what string, what position) is pure; the *application* (apply edit, save) is not. Split accordingly; the applier lives in `shared/editor/`.
+
+This issue does **not** chase 100% `vscode`-free across every file — it isolates the editor surface to `shared/editor/` and makes the pure parts pure and node-testable. Inject's pure half (`buildInlineString`, position computation) becomes testable; its apply half stays in the adapter.
+
+## In scope
+
+1. **`shared/editor/`** — an `EditorAdapter` (interface `IEditor`) owning:
+   - `open(path)` / `show(doc)` / `save(doc)` (currently `Dialogues.openDocument/showDocument/saveDocument`),
+   - create-and-open (currently `Writer.createSaveLoadTextDocument`),
+   - apply-edit / insert-at-position (currently `Inject.injectString`/`injectInlineString`).
+2. **Reader / Writer** return resolved paths + a created/loaded flag (plain data); commands call the editor adapter to materialize the `TextDocument`.
+3. **Inject** keeps pure `buildInlineString` / `computePositionForInput` (plain `InlineString` + line/col data, no `vscode.Position`); the apply step moves to the adapter.
+4. **Remove cross-feature edges:**
+   - `entries → notes` — `LoadNotes` dispatch in `loadPageForInput`: route note-input handling so entries does not import `notes` (e.g. an input-kind handler registry, or move dispatch up to the command layer).
+   - `navigation → entries` — move `AbstractLoadEntryForDateCommand` to a neutral location (e.g. `shared/` or `features/entries` exposing it as public API consumed via interface).
+   - `smart-input → entries` — `Dialogues` uses `ScanEntries`; relocate `Dialogues` (and/or `ScanEntries`) so neither feature imports the other.
+5. **Node-only unit tests** for the now-pure logic (path resolution, inline-string building, position computation, type inference).
+
+## Out of scope
+
+- No user-facing behavior change. No settings/schema/template changes.
+- Caching/`onDidChangeConfiguration` for config (tracked in PLAN.md 2.6).
+- Rewriting `Dialogues` QuickPick UX.
+
+## Acceptance criteria
+
+1. `grep -rn "from 'vscode'\|import \* as vscode" src/features/*/` shows `vscode` only in `commands/`, `ui/`, and explicitly editor-facing files — **not** in the pure domain modules (reader/writer + Inject's pure half).
+2. All `vscode.TextDocument` / `WorkspaceEdit` / `window` access flows through `shared/editor/`.
+3. No cross-feature internal imports remain (grep/lint verifiable): the 3 edges above are gone.
+4. New node-only unit tests cover path resolution, `buildInlineString`, position computation, and `inferType` — runnable without the Extension Host.
+5. `npm run check` (lint + compile + full suite) green.