docs: spec+plan for package-by-feature restructure

Refs #234. Target structure, 5-phase migration, separation rules,
shared/events for cross-feature comms, singleton DI lifecycle.

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

Author: pajoma

docs/plans/2026-06-02-234-package-by-feature.md

@@ -0,0 +1,83 @@
+# Plan — Issue #234: Restructure `src/` to package-by-feature + DI
+
+> **Spec:** [docs/specs/2026-06-02-234-package-by-feature.md](../specs/2026-06-02-234-package-by-feature.md)
+> **Issue:** [pajoma/vscode-journal#234](https://github.com/pajoma/vscode-journal/issues/234)
+> **Branch:** TBD (`refactor/234-package-by-feature`, off `develop` after preconditions met)
+> **Created:** 2026-06-02
+
+## Approach
+
+Five sequential phases, each independently shippable and test-green. Order minimizes blast radius: untangle dependencies before moving files, move files before changing semantics. Phase 5 (vscode-free domain) is the only behavior-adjacent step and may split into a follow-up issue.
+
+## Preconditions
+
+- Merge open PRs (#231, #233) before starting Phase 1 — it touches nearly every file. Do not start over an open PR.
+- `rm -rf out/` before first compile to drop stale `.test.js` (per `AGENTS.md`).
+
+## Phases
+
+### Phase 1 — Kill the `J` barrel
+- Replace every `import * as J from '..'` + `J.X.Y` with named imports from the concrete module.
+- Reduce `src/index.ts` to type-only re-exports or remove it.
+- Pure mechanical; zero behavior change. Largest diff.
+- Verify: `npm run check` green; `grep -r "import \* as J" src/` empty.
+
+### Phase 2 — `Ctrl` → DI container
+- Add `app/container.ts` owning singleton service construction (the current `initServices` graph).
+- Add `app/register.ts` for command/provider registration; move syntax-highlight + cache wiring to `app/startup.ts`.
+- Change command/provider constructors to take narrow interfaces (`IReader`, `IWriter`, `IConfiguration`, …) instead of `Ctrl`.
+- Remove two-phase `!` init; container builds in one pass after logger exists.
+- Verify: no constructor references concrete `Ctrl`; suite green.
+
+### Phase 3 — Split `Configuration`
+- `SettingsReader` — raw `journal.*` reads + scope/windows normalization.
+- `PathResolver` — entry/notes/weekly path + file patterns (local + remote variants).
+- `TemplateProvider` — header/inline/time template lookups (absorbs `vscode/template-service.ts`).
+- Keep `IConfiguration` as the composed facade if needed to limit call-site churn; each class ≤~300 lines.
+- Verify: `read-templates.test.ts`, `template-engine.test.ts`, path tests green.
+
+### Phase 4 — Move files into feature folders
+- `git mv` into `features/{entries,notes,weekly,tasks,navigation,smart-input,tools}` and `shared/{config,fs,logging,dates,strings,templates,model}`.
+- Add `shared/events/` typed `EventEmitter`; convert the `reader.onNotesInjected` callback and the inline weekly-sync in `show-entry-for-date.ts` to published events (`entryOpened`), subscribed by `weekly`/`notes`.
+- Fix imports. No logic change beyond the event rewiring.
+- Verify: no cross-feature internal imports (grep `features/*/` for sibling-feature paths); suite green.
+
+### Phase 5 — vscode-free domain (may split to follow-up)
+- Introduce `shared/editor/` adapter (open/show/save `TextDocument`).
+- Change `domain/` (reader/writer/inject) to return paths/data, not `TextDocument`; commands call the editor adapter.
+- Verify: `grep -r "vscode" src/features/*/domain/` empty; add pure-node unit tests for domain logic.
+
+## Test scenarios
+
+| Scenario | Check |
+|----------|-------|
+| Every phase | `npm run check` green |
+| Phase 1 done | `grep -r "import \* as J" src/` → empty |
+| Phase 2 done | no command ctor takes `Ctrl`; `app/container.ts` sole wiring point |
+| Phase 3 done | `Configuration` → 3 classes, each ≤~300 lines; template/path tests green |
+| Phase 4 done | no `features/<a>` imports `features/<b>` internals; events flow via `shared/events/` |
+| Phase 5 done | `src/features/*/domain/` has zero `vscode` imports; new node-only domain tests pass |
+| Regression | full suite (commands-entry, commands-note, commands-weekly, scan-entries, sync) green after each phase |
+
+## Dependencies
+
+- Blocked by open PRs #231, #233 (merge first).
+- Touches `docs/PLAN.md` (update Phase 2+ to reflect new layout).
+
+## Risk
+
+| Risk | Mitigation |
+|------|-----------|
+| Phase 1 huge diff → rebase hell | Merge pending PRs first; land Phase 1 fast as its own PR |
+| Hidden cycles surface during barrel removal | Fix per-module; named imports make cycles explicit |
+| `Configuration` split breaks scope/remote path resolution | Phase 3 keeps `IConfiguration` facade; lean on existing path/template tests |
+| Phase 5 changes return types broadly | Split to its own issue/PR; ship Phases 1–4 first |
+| Event rewiring changes fire-and-forget timing | Keep events fire-and-forget with same error-swallowing as today; assert via existing sync tests |
+
+## Rollback
+
+Each phase is a separate PR. Revert the offending PR; earlier phases remain valid. No settings/schema migration, so no data rollback.
+
+## Reference spec
+
+[docs/specs/2026-06-02-234-package-by-feature.md](../specs/2026-06-02-234-package-by-feature.md)

docs/specs/2026-06-02-234-package-by-feature.md

@@ -0,0 +1,92 @@
+# Spec: Restructure `src/` to package-by-feature with shared kernel + DI (#234)
+
+## Goal
+
+Move `src/` from package-by-layer (`commands/`, `journal/`, `model/`, `vscode/`, `features/`, `ui/`, `util/`) to **package-by-feature** with a thin, dependency-free shared kernel. Each feature lives in one directory. Replace the `Ctrl` service-locator with constructor dependency injection, kill the `J` namespace barrel, and (last) make the domain layer VS Code-free.
+
+No user-facing behavior change.
+
+## Why now
+
+A single capability is smeared across many directories. "Notes" spans `commands/show-note.ts`, `journal/parser.ts`, `journal/writer.ts`, `features/entries/load-note.ts`, `features/sync/sync-note-links.ts`, and `vscode/conf.ts` — six directories for one feature. The layering also hides real dependencies and blocks unit testing. This aligns with `docs/PLAN.md` Phase 2+ (DI, named imports, native `async`/`await`, `vscode.workspace.fs`).
+
+## Problems addressed
+
+1. **`J` namespace barrel = circular god-import.** `src/index.ts` re-exports every submodule as `J.Util`, `J.Journal`, etc. Files do `import * as J from '..'` then `J.Util.Ctrl`. Those files are themselves re-exported by `index.ts`, so `index.ts → commands/show-note.ts → index.ts` is a cycle. Kills tree-shaking, breaks go-to-definition, hides dependencies.
+2. **`Ctrl` service-locator god-object** (`util/controller.ts`). Every command/provider receives the full `Ctrl` and reaches `ctrl.reader`/`ctrl.writer`/`ctrl.ui`/`ctrl.config`/`ctrl.inject`. Narrow interfaces (`IReader`, …) exist in `model/interfaces.ts` but are unused at call sites. Two-phase init forces `!` assertions on every field. The controller also lives in `util/` — wrong home.
+3. **Domain coupled to `vscode`.** `Reader`/`Writer`/`Inject` import `vscode` and return `vscode.TextDocument`, so core logic can't be unit-tested without the Extension Host (hence the no-display workaround in `AGENTS.md`).
+4. **`Configuration` god-class** — 708 lines (`vscode/conf.ts`), ~40 public methods mixing raw setting reads, path-pattern resolution, template lookup, scope resolution, windows-path normalization, and local-vs-remote path variants.
+5. **Inconsistent buckets.** No rule separates `journal/` vs `features/` vs `ui/`. `scan-entries` is a "feature" but `reader` is "journal"; `codeactions` is in `ui` but `sync` is in `features`; two template modules split across layers (`journal/template-engine.ts` vs `vscode/template-service.ts`).
+6. **Orchestration leaks into commands.** `show-entry-for-date.ts` `loadPageForInput` runs fire-and-forget weekly sync via nested `.then/.catch`.
+7. **Mixed async styles** — `.then()` chains (`startup.run`, `loadPageForInput`) alongside `async/await`.
+
+## Target structure
+
+```
+src/
+  extension.ts            # activate/deactivate only
+  app/                    # composition root (was vscode/startup + util/controller)
+    container.ts          # builds the dependency graph — replaces Ctrl service-locator
+    register.ts           # command/provider registration
+    startup.ts            # syntax highlighting, cache-invalidation wiring
+  shared/                 # kernel — NO feature dependencies
+    config/               # split Configuration: SettingsReader | PathResolver | TemplateProvider
+    fs/                   # IFileSystem + VscodeFileSystem
+    logging/  dates/  strings/
+    templates/            # merge template-engine + template-service
+    editor/               # the single vscode-TextDocument adapter (open/show/save)
+    events/               # typed EventEmitter / mediator for cross-feature signals
+    model/                # shared types: Input, FileEntry, ScopedTemplate
+  features/
+    entries/              # today | tomorrow | yesterday | date | input + entry reader/writer
+    notes/                # show-note + load-note + note-path + sync-note-links
+    weekly/               # weekly entry + watcher + sync-daily-links
+    tasks/                # copy/shift + codeactions + migrate codelens
+    navigation/           # prev/next entry
+    smart-input/          # match-input + parser + input dialog
+    tools/                # print-time | print-duration | print-sum
+```
+
+Each feature folder: `commands/` (VS Code handlers) · `domain/` (pure logic, no vscode) · `ui/` (providers).
+
+### Separation rules
+
+- A feature may import from `shared/`. A feature must **never** import another feature's internals.
+- Cross-feature interaction goes through `shared/events/` — a small typed `EventEmitter`/mediator. Example: `entries` emits `entryOpened` → `weekly` subscribes and runs daily-link sync. No feature-to-feature imports. *(Maintainer recommendation, #234 review.)*
+- `domain/` imports no `vscode`; it returns data/paths. `commands/` plus the `shared/editor/` adapter handle `TextDocument`.
+- Inject narrow interfaces (`IReader`, not `Ctrl`) via constructor. `app/container.ts` builds the graph once.
+
+### Service lifecycle
+
+`app/container.ts` is the single owner of service lifecycles. All services are **singletons** (one instance per activation), matching the current single-`Ctrl` model. No separate `shared/state/` module is introduced unless genuinely mutable cross-feature state appears — out of scope for this issue. *(Maintainer recommendation, #234 review.)*
+
+## In scope
+
+- Directory restructure to package-by-feature.
+- Remove `J` barrel / `import * as J`; named imports throughout.
+- Replace `Ctrl` with `app/container.ts` DI; commands take narrow interfaces.
+- Split `Configuration` into ≤3 focused classes.
+- Add `shared/events/` typed emitter for cross-feature signals.
+- Make `domain/` VS Code-free via `shared/editor/` adapter (Phase 5 — may split to a follow-up issue).
+- Update `docs/PLAN.md` to reflect the new structure.
+
+## Out of scope
+
+- No user-facing behavior change. No new settings, commands, or templates.
+- No change to the `journal.*` settings schema or file/path patterns in `package.json`.
+- i18n strings unchanged (English-only, per `AGENTS.md`).
+- No new mutable state module (`shared/state/`) unless a concrete need surfaces.
+
+## Preconditions
+
+- **Merge pending PRs first** (notably #231, #233). Phase 1 touches nearly every file; landing it over open PRs causes large rebase conflicts. *(Maintainer recommendation, #234 review.)*
+
+## Acceptance criteria
+
+1. `npm run check` (lint + compile + test) green after **every** phase.
+2. No `import * as J from` remaining; `src/index.ts` barrel removed or reduced to type-only re-exports.
+3. No command/provider depends on concrete `Ctrl`; all take narrow interfaces wired in `app/container.ts`.
+4. `Configuration` split into ≤3 focused classes, none over ~300 lines.
+5. Each feature directory is self-contained; no cross-feature internal imports (verifiable by grep/lint rule).
+6. Cross-feature signals flow through `shared/events/`.
+7. `docs/PLAN.md` updated to reflect the new structure.