useCache, useSharedCache and usePersistCache setters now accept a React-style functional updater `(prev) => next` in addition to a concrete value. The updater resolves `prev` from the latest stored value at write time rather than the render-time snapshot, making read-modify-write correct across an `await` — the root cause of the keep-alive overwrite race behind #16460.
`prev` is typed shallow-readonly (`ReadonlyValue<T>`), so mutating it in place and returning the same reference — which the CacheService `isEqual` short-circuit would otherwise swallow silently — is a compile error. Concrete-value calls are unchanged, so existing consumers keep compiling.
The renderer useCache mock mirrors the functional branch with the same default fallback; docs and hook tests updated. Consumer call-site adoption lands separately.
Migrate window-bounds persistence off the electron-window-state library into
a WindowManager built-in `rememberBounds` capability, backed by the main-process
persist cache (`window.bounds` key — its first real consumer).
- New `windowBoundsTracker` free-function module: validates the stored record
(including displayBounds), restores onto the display the window was last on
(clamping into its work area, never resetting to primary), and snapshots at
teardown via getNormalBounds + isMaximized.
- Singleton-only gate (dev warning for non-singleton types). Runtime toggle
`wm.setRememberBounds` (orthogonal to the registry flag; OFF drops only that
type's slot) plus `wm.peekWindowBounds`.
- Persist at three teardown exits: native close (singletons), before
window.destroy() in destroyWindow (programmatic destroys), and a new onStop
so shutdown writes land before CacheService flushes its persist map.
- Wire Main + QuickAssistant. Main re-applies maximize consumer-side on its own
show schedule (tray-on-launch defers to first show); remove electron-window-state
and its orphaned keepers/constants/comments.
Fullscreen is not persisted and old *-state.json is not migrated (one-time
reset, loseable). Adds tracker/integration/persist tests, extends the main
CacheService mock with persist methods, and documents the capability plus a
breaking-change note.
Rename PowerMonitorService -> PowerService and relocate it to
src/main/core/power/, turning the shutdown-only service into a complete,
self-contained power hub:
- Typed power events (suspend/resume/lock/unlock/power-source) with
suspend/resume + power-source de-duplication; lock/unlock pass-through.
- Bounded, cross-platform shutdown barrier: preventDefault on macOS/Linux,
blockShutdown via a minimal hidden window on Windows; handlers run under a
5s hard timeout, then the app quits through the normal quit flow.
- Best-effort, ref-counted sleep prevention: preventSleep(reason) returns a
Disposable and never throws (the provider degrades internally). The OS
blocker engages only while a hold is held AND the user enabled
app.power.prevent_sleep_when_busy. JobManager is the first registrant,
acquiring a hold per execution attempt.
Add the app.power.prevent_sleep_when_busy preference (v2-only, no v1 source)
and a Settings -> General toggle. Service phase moved Background -> WhenReady.
Collect the WindowManager caller-window controls (close / minimize / maximize /
unmaximize / set_full_screen / is_maximized / is_full_screen / get_init_data) and
the three directed window events (maximized_changed / fullscreen_changed / reused)
onto the IpcApi framework, replacing the legacy this.ipcHandle registrations, the
hand-written preload windowManager namespace, and the IpcChannel enums.
- Requests: ctx.senderId addresses the caller window (was getWindowIdByWebContents);
fire-and-forget controls return void, queries keep their read type.
- Events: directed IpcApiService.send to the affected window, never broadcast.
- openSettings is a navigation concern misfiled under windowManager — moved to
window.api.settings.openSettings (still legacy IPC, not yet on IpcApi).
- WindowManager_Open was dead (no renderer/preload consumer) — deleted.
- MainWindow_* (main-window singleton ops) intentionally left on legacy IPC.
Behavior verified equivalent before/after by independent review.
### What this PR does
Before this PR:
- Knowledge embeddings and reranking ran through the legacy
embedjs-based
knowledgeV1 stack with their own provider clients, independent of the
app's
AI service.
- File-processing intake accepted several heterogeneous input shapes,
and
knowledge file items were tracked by FileEntry ids, coupling file
content to
the file-manager entry/cache.
After this PR:
- Embeddings and reranking are routed through the unified `AiService`
(with
cherryin rerank support) and guarded by strict embedding-dimension
validation
that rejects stale/mismatched vectors.
- File-processing intake is collapsed to a single path-based model;
knowledge
file items are stored by base-relative path under the knowledge-base
directory, and v1 uploads are copied into the v2 base dir during
migration so
migrated items stay reindexable/restorable.
- Legacy `knowledgeV1` is removed; the orchestration services were
renamed to
`KnowledgeService` / `FileProcessingService`.
- Chat -> knowledge attach is temporarily disconnected (tracked TODO)
while the
v2 file-manager bridge is rebuilt.
Fixes #N/A (no linked issue)
### Why we need it and why it was done in this way
Routing embeddings/rerank through `AiService` unifies provider handling
and
credentials and removes the parallel embedjs client stack and its v1
coupling.
Storing knowledge files by base-relative path (instead of FileEntry ids)
makes
each knowledge base self-contained and portable.
The following tradeoffs were made:
- A large, coordinated refactor plus a migration step that physically
copies v1
uploads into the v2 base dir, in exchange for removing the parallel
client
stack and making bases self-contained.
- Base-relative path storage required a fail-fast/dedup strategy for
same-named
files and a guard for blank legacy filenames.
The following alternatives were considered:
- Keeping the embedjs stack behind an adapter — rejected; perpetuates
the
parallel client and v1 coupling.
- Keeping FileEntry-id storage — rejected; couples knowledge files to
the
file-manager cache and blocks portability.
### Breaking changes
- `knowledgeV1` is removed. Legacy v1 knowledge data reaches v2 only
through the
v2 migrators; there is no v1 fallback.
- The v2 knowledge HTTP API (API gateway) now returns v2-native
per-entry fields
(`embeddingModelId`, `createdAt` on base entries; `chunkId`,
`scoreKind`,
`rank` on search results). The response envelope (`knowledge_bases`,
`searched_bases`, `total`) is unchanged. See
`v2-refactor-temp/docs/breaking-changes/2026-06-05-knowledge-api-v2.md`.
### Special notes for your reviewer
- This branch went through several rounds of multi-agent code review.
The most
recent 6 commits address review findings: directory-import path
collisions,
migrated-file source copying + blank `relativePath` guard, addItems
rollback
error preservation, eager `document_to_markdown` output-target
validation, a
`CompletedKnowledgeBase` type guard, and breaking-changes doc
corrections.
- Chat -> knowledge attach is intentionally disconnected for now
(tracked in
`v2-refactor-temp/docs/knowledge/knowledge-todo.md`).
- Local full `pnpm lint`/`pnpm test` was not run per the project's
review
conventions; please rely on CI / `pnpm build:check`.
### Checklist
- [x] Branch: This PR targets the correct branch — `main` for active
development, `v1` for v1 maintenance fixes
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: Write code that humans can understand and Keep it simple
- [x] Refactor: You have left the code cleaner than you found it (Boy
Scout Rule)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [ ] Documentation: A user-guide update was considered and is present
(link) or not required.
- [x] Self-review: I have reviewed my own code before requesting review
from others
### Release note
```release-note
NONE
```
---------
Signed-off-by: eeee0717 <chentao020717Work@outlook.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Move all renderer source from src/renderer/src/* up one level to
src/renderer/*, removing the redundant nested src directory.
- Update path aliases (@renderer, @types, @logger, @data) and TanStack
Router paths in electron.vite.config.ts; update tsconfig.{json,web,node}
path mappings and include globs.
- Fix Vite root-relative script paths in the 8 renderer HTML entries.
- Update cross-process relative imports in main/preload (language,
apiServer models, preload index) to drop the /src segment.
- Switch renderer test imports of the logger mock to the @test-mocks alias.
- Update hardcoded renderer paths in scripts and their fixtures, lint
configs (eslint/oxlint/biome), CODEOWNERS, docs, and the data-classify tool.
- Convert deep (../../+) relative imports within the renderer to the
@renderer alias (69 files, 108 imports); keep single-level relatives.
- Fix doc links broken by the move and correct one pre-existing broken
link in naming-conventions.md.
libsql client-ts upstream issue #288 makes PRAGMA busy_timeout ineffective
for async transactions, so concurrent db.transaction() calls reliably surface
SQLITE_BUSY. Introduce DbService.withWriteTx as a serialized write helper:
- Process-wide FIFO mutex (async-mutex) serializes write transactions.
- libsql client's default BEGIN IMMEDIATE protects against read-then-write
tx upgrade failures (no override needed at the drizzle layer).
- Single 50ms BUSY retry guards against transient external locks.
Reads do NOT need this — WAL gives readers snapshot isolation that is never
blocked by writers.
Includes unit tests (FIFO ordering, finally release on throw, single BUSY
retry, persistent BUSY rethrow, non-BUSY passthrough) plus a real-libsql
integration test. Updates the DbService test mock with a passthrough
withWriteTx so dependent services do not throw "is not a function" in
tests. Documents the API in database-patterns.md and points
CLAUDE.md / data-api-overview.md at the new pattern.
### What this PR does
Before this PR:
Web Search settings still depended on legacy renderer-side settings
wiring and provider-specific UI structure. Provider selection, API key
editing, blacklist handling, and compression settings were split across
legacy hooks/routes and were not aligned with the v2 preference/provider
configuration model.
After this PR:
Web Search settings are migrated to the v2 data and architecture path:
- Adds `useWebSearch` as the renderer settings hook backed by v2
preference APIs.
- Rebuilds the Web Search settings page around smaller components,
hooks, and utilities for provider metadata, API keys, defaults,
blacklist, and provider checks.
- Uses v2 provider presets and resolved provider capability data for
keyword search and URL fetch defaults.
- Updates preference mappings/classification for removed or normalized
Web Search settings.
- Adds focused tests for the new settings hooks, provider metadata, API
key handling, blacklist parsing, and provider check behavior.
- Documents user-visible v2 Web Search setting changes in the breaking
changes log.
<!-- (optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)`
format, will close the issue(s) when PR gets merged)*: -->
Fixes # N/A
### Why we need it and why it was done in this way
The v2 refactor is moving settings and provider configuration away from
legacy renderer-local state. Web Search settings need to read and write
through the same v2 preference source of truth as the main-side Web
Search service so the UI, migration layer, and runtime configuration use
one provider model.
The following tradeoffs were made:
- The PR keeps the work scoped to Web Search settings and the
preference/provider metadata needed by that settings surface.
- Deprecated settings are removed instead of preserved through
compatibility UI, because v1 Web Search settings are throwaway during
the v2 refactor.
- The settings page is split into local hooks/components instead of
introducing a broader settings framework abstraction.
- Runtime service adjustments are limited to what is required by the
settings schema and preference changes.
The following alternatives were considered:
- Keeping the old `useWebSearchProviders` path as a compatibility layer,
but that would continue dual settings ownership during the v2 migration.
- Preserving the removed subscription-source and cutoff-unit UI, but
those settings do not map cleanly to the v2 Web Search configuration
model.
- Combining this with runtime Web Search tool behavior changes, but that
would make the PR too broad and harder to review.
Links to places where the discussion took place: N/A
### Breaking changes
This PR removes deprecated Web Search settings from the v2 settings
surface:
- Web Search subscription-source management is removed.
- Compression cutoff is normalized to a token-based cutoff limit; the
cutoff unit selector is removed.
Impact: users will configure Web Search through v2 provider defaults,
API keys, capability hosts, blacklist, and compression settings. No
manual migration action is expected.
### Special notes for your reviewer
Scope of this PR:
- Web Search settings UI migration to v2 data/preferences.
- Renderer settings hooks/components/utilities for Web Search provider
configuration.
- Preference classification/mapping changes required by the settings
migration.
- Tests for the settings-side behavior introduced here.
Explicitly out of scope:
- Web Search runtime orchestration in chat responses.
- Built-in/external Web Search tool execution behavior.
- Message rendering for Web Search tool results or citations.
- Model switching behavior and assistant-level `enableWebSearch`
semantics outside the settings migration.
- Large-scale UI design-system replacement beyond the files touched for
this settings migration.
- New provider integrations or provider search algorithm changes.
Review scope note: this PR is based on `v2`, but the intended review
scope is limited to the Web Search settings migration described above.
Web Search runtime/service/tool changes that are already part of the
prerequisite v2 Web Search work are not part of this PR's review scope.
Validation:
- Not run in this PR creation pass.
### Checklist
This checklist is not enforcing, but it's a reminder of items that could
be relevant to every PR.
Approvers are expected to review this list.
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [x] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. Check this only
when the PR introduces or changes a user-facing feature or behavior.
Present in `v2-refactor-temp/docs/breaking-changes/`.
- [x] Self-review: I have reviewed my own code (e.g., via
[`/gh-pr-review`](/.claude/skills/gh-pr-review/SKILL.md), `gh pr diff`,
or GitHub UI) before requesting review from others
### Release note
<!-- Write your release note:
1. Enter your extended release note in the below block. If the PR
requires additional action from users switching to the new release,
include the string "action required".
2. If no release note is required, just write "NONE".
3. Only include user-facing changes (new features, bug fixes visible to
users, UI changes, behavior changes). For CI, maintenance, internal
refactoring, build tooling, or other non-user-facing work, write "NONE".
-->
```release-note
Web Search settings now use the v2 preference/provider configuration path. Deprecated subscription-source settings were removed, and compression cutoff is now token-based.
```
---------
Signed-off-by: eeee0717 <chentao020717Work@outlook.com>
### What this PR does
Before this PR:
File processing on the `v2` branch was still described and wired around
split OCR / markdown APIs, legacy feature names, and feature-first
provider structure. OCR-like image text extraction and
document-to-markdown conversion did not share one task contract, and
provider task ids / polling details were harder to keep behind the
Main-process boundary.
After this PR:
`v2` file processing follows
`v2-refactor-temp/docs/fileProcessing/file-processing-service.md` as the
design baseline:
- exposes one Main-side task API: `startTask`, `getTask`, and
`cancelTask`
- replaces split file-processing IPC with `file-processing:start-task`,
`file-processing:get-task`, and `file-processing:cancel-task`
- renames features and preference keys to `image_to_text` and
`document_to_markdown`
- adds `FileProcessingTaskService` as the in-memory source of truth for
task ids, task state, progress, cancellation, TTL pruning, remote-poll
dedupe, and task change events
- keeps provider task ids, remote context, query context, abort
controllers, and in-flight polling inside Main-process task records
- maps completed results to artifacts: inline `text/plain` for
`image_to_text`, and persisted markdown file artifacts for
`document_to_markdown`
- reorganizes providers into processor-first handlers under
`src/main/services/fileProcessing/processors`
- moves Tesseract worker ownership under `processors/tesseract/runtime`
- removes the new file-processing module's old `ocr/` and `markdown/`
split directories after migrating their logic
- updates shared schemas, presets, preference generation, migration
mappings, and tests for the renamed feature model
The public file-processing contract is now:
```ts
await window.api.fileProcessing.startTask({
feature: 'image_to_text',
file,
processorId: 'tesseract'
})
await window.api.fileProcessing.getTask({ taskId })
await window.api.fileProcessing.cancelTask({ taskId })
```
Architecture overview:
```text
Renderer / upper-layer caller
|
| startTask / getTask / cancelTask
v
FileProcessingOrchestrationService
|
| Zod validation + delegation
v
FileProcessingTaskService
|
| taskId, task store, TTL, cancellation,
| background execution, remote polling, artifacts
v
processorRegistry[processorId].capabilities[feature]
|
+--> image-to-text handlers
| -> text/plain artifact
|
+--> document-to-markdown handlers
-> feature.files.data/fileId/file-processing/taskId/output.md
```
Notes:
- The new file-processing API does not keep facades for
`file-processing:extract-text`,
`file-processing:start-markdown-conversion-task`, or
`file-processing:get-markdown-conversion-task-result`.
- `FileProcessingOrchestrationService` is intentionally only the IPC
validation and delegation layer.
- Task state is Main-process runtime coordination state, not DataApi or
Cache state.
- Renderer task subscriptions, a global UI task center, and full
renderer business-flow migration are intentionally out of scope for this
PR.
- The legacy standalone OCR path outside the new file-processing module
can coexist during the v2 transition, but the new file-processing
interface is not polluted by those split-API types.
Fixes #N/A
### Why we need it and why it was done in this way
This PR makes OCR-style image text extraction and document-to-markdown
conversion use the same Main-process task model before renderer-side
adoption. The unified contract gives upper layers one way to start work,
query progress, handle failure, cancel work, and consume completed
artifacts without learning provider-specific polling details.
The following tradeoffs were made:
- Fast OCR now also goes through a task API, so callers need start/query
behavior instead of a direct `extractText -> text` call.
- Task state remains session-scoped in memory; completed artifacts are
persisted, but task snapshots are not restored after app restart.
- Remote-provider cancellation is best-effort: local polling and state
transition stop immediately, but third-party provider-side cancellation
is not guaranteed.
- Renderer integration is intentionally compile-safe and minimal in this
PR; full UX migration should happen in follow-up changes.
- Tesseract keeps a processor-owned runtime service, while other
processors stay as handlers/utilities until they need lifecycle-managed
resources.
The following alternatives were considered:
- Keeping separate OCR and markdown conversion APIs, which would
preserve the current split but continue duplicating task, progress,
cancellation, and result semantics.
- Adding a DataApi task table or Cache mirror for file-processing task
state, which would create a second source of truth for runtime
coordination state.
- Adding renderer push subscriptions in this PR, which would expand the
scope beyond the Main-side task contract.
- Introducing a generic process manager for all processors, which is
premature while only Tesseract currently owns reusable lifecycle
resources.
Links to places where the discussion took place:
`v2-refactor-temp/docs/fileProcessing/file-processing-service.md`
### Breaking changes
None for released user-facing behavior.
If this PR introduces breaking changes, please describe the changes and
the impact on users.
For the in-progress `v2` file-processing integration, this replaces the
split file-processing IPC/preload shape with the unified
`startTask/getTask/cancelTask` contract. It also renames file-processing
feature and preference keys from the old `text_extraction` /
`markdown_conversion` model to `image_to_text` / `document_to_markdown`.
### Special notes for your reviewer
- This PR targets `v2`, not `main`.
- Review this against
`v2-refactor-temp/docs/fileProcessing/file-processing-service.md`; that
document is the source of truth for the module boundary.
- Main review points: unified task API, artifact model, cancellation
semantics, processor-first registry/handlers, hidden provider runtime
state, and no DataApi/Cache task storage.
- `document_to_markdown` artifacts are persisted under
`application.getPath('feature.files.data')/fileId/file-processing/taskId/output.md`.
- `image_to_text` artifacts are returned inline as plain text artifacts
and are not persisted.
- Current local verification status:
- `pnpm format`: passed
- `pnpm build:check`: passed
- Vitest inside `build:check`: `432` test files passed, `7171` tests
passed, `72` skipped
### Checklist
This checklist is not enforcing, but it's a reminder of items that could
be relevant to every PR.
Approvers are expected to review this list.
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [ ] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. Check this only
when the PR introduces or changes a user-facing feature or behavior.
- [x] Self-review: I have reviewed my own code (e.g., via
[`/gh-pr-review`](/.claude/skills/gh-pr-review/SKILL.md), `gh pr diff`,
or GitHub UI) before requesting review from others
### Release note
```release-note
NONE
```
---------
Signed-off-by: eeee0717 <chentao020717Work@outlook.com>
Co-authored-by: fullex <106392080+0xfullex@users.noreply.github.com>
Apply NOT NULL constraints where NULL has no domain meaning:
- agent / agentSession: description, instructions, mcps, allowedTools,
configuration, accessiblePaths, slashCommands (session only)
- agentGlobalSkill.tags
- message.searchableText, message.siblingsGroupId
- topic.name, topic.{isNameManuallyEdited, sortOrder, isPinned, pinnedOrder}
- miniapp.sortOrder
Drop rowMapper "?? fallback" patterns; preserve genuine T|null contracts
(agentSessionMessage.agentSessionId now passes NULL through, with the Zod
entity tightened to .nullable() to match).
Migrate product-chosen DB DEFAULTs to the service layer:
- agentTask.status DB DEFAULT removed; service was already supplying 'active'
- agentGlobalSkill.isEnabled DB DEFAULT flipped from true to false to match
SkillService.install behavior
Drop Zod .default([]) from CreateAgentSchema.accessiblePaths so the
service-layer computeWorkspacePaths() is the single runtime default source.
Update FTS5 triggers to COALESCE the group_concat result to '' so
messages with no main_text blocks don't violate the new NOT NULL on
searchable_text.
Refs: docs/references/data/best-practice-default-values-and-nullability.md
Enables main-process services to react to cache changes without writer-side
wiring — unblocks the web-search/OCR provider rotation use case where new
providers would otherwise require manual hook-ups at every write site.
Also unifies equality across main and renderer on lodash.isEqual (fixing
redundant cross-window broadcasts when Record/Array values are rebuilt on
every write) and extracts template utilities to the shared package so both
processes use one implementation.
Align SharedCache type system with Memory (UseCache) template support and
remove the sharedCasual escape hatch that existed only because SharedCache
could not type-check dynamic keys:
- Introduce InferSharedCacheValue and expand SharedCacheKey through
ProcessKey so template schema entries like
'web_search.provider.last_used_key.${providerId}' match concrete keys
with precise value types on both Main and Renderer.
- Extend useSharedCache hook with findMatchingSharedCacheSchemaKey /
getSharedCacheDefaultValue, mirroring useCache's template-aware default
resolution.
- Remove getSharedCasual / setSharedCasual / hasSharedCasual /
deleteSharedCasual / hasSharedTTLCasual from the Renderer CacheService
and all test mocks; Main CacheService never had them.
- Migrate BaseWebSearchProvider and OcrBaseApiClient rotation from
sharedCasual to type-safe getShared/setShared. Rename keys to conform
to schema naming rules (ESLint data-schema-key/valid-key):
web-search-provider:${id}:last_used_key
-> web_search.provider.last_used_key.${providerId}
ocr_provider:${id}:last_used_key
-> ocr.provider.last_used_key.${providerId}
Old values under legacy key names become orphans after rollout; this
is acceptable because rotation state is transient and consumers
reinitialize from keys[0] on a miss.
- Add type-level assertions for SharedCacheKey and InferSharedCacheValue
in useCache.types.test.ts to lock the contract in CI.
- Update cache-overview.md, cache-usage.md, and tests/__mocks__/README.md
to describe SharedCache's template support and reflect that casual
methods now exist only on the Memory tier.
The hooks shipped in 87d1a947a without test coverage or team-facing
mocks. Consumer tests would otherwise need to hand-roll an SWRConfig
wrapper or skip asserting cache-control semantics entirely. This adds:
- Direct unit tests that exercise the real hooks inside a self-provided
SWRConfig (covering key shape, empty-query folding, no-revalidate
writes, non-reactive reads, and read/write round-trip).
- Mock factories in tests/__mocks__/renderer/useDataApi.ts backed by a
shared in-memory Map, plus seedCache/getCachedValue/clearCache
helpers on MockUseDataApiUtils. Registered in MockUseDataApi so the
global renderer setup picks them up without further wiring.
- Docs update in tests/__mocks__/README.md with signatures and usage.
Extend the renderer data hooks to cover three mutation shapes that
previously had to drop to imperative dataApiService calls:
- Template paths (e.g. `/providers/:providerId`) with a runtime `params`
option on useQuery / useMutation / useInfiniteQuery / usePaginatedQuery,
so a single hook instance can operate on ids chosen at call time.
ParamsForPath derives types directly from the schema's existing
`params: {...}` declarations (no template-string parsing).
- Function-form `refresh: ({ args, result }) => ConcreteApiPaths[]` for
invalidation keys that depend on trigger input or server response. Args
are closure-captured at trigger entry to avoid races between concurrent
calls.
- Explicit `/*` suffix for path-segment prefix matching on refresh and
invalidate patterns, preserving the trailing slash so `/providers/*`
doesn't match siblings like `/providers-archived`.
A single `resolveTemplate` function is the canonical path-replacement
point, so `useQuery('/providers/:id', { params: { id: 'abc' } })` and
`useQuery('/providers/abc')` produce byte-for-byte identical cache keys.
Dev-mode assertions flag invalid `/*` patterns (bare wildcard or missing
trailing slash) and warn on concurrent triggers against the same template
hook instance, which would share SWR mutation state.
Fully backward compatible: existing `refresh: ['/topics']` and
concrete-path hook calls compile and behave identically.
The mocks README described what was mocked but never stated that
tests/__mocks__/main/ is intentionally limited to cross-cutting
infrastructure. Without that boundary in writing, feature-specific
lifecycle services were getting registered into defaultServiceInstances,
bloating the global default surface without serving any other test.
Adds an explicit Scope section with a pattern-selection table, documents
the canonical local-stub pattern for feature-specific lifecycle services
(vi.mock on @application + MockBaseService stand-in), and a Common
Assertions table covering phase, dependencies, IPC handlers, and
disposables. Adds the missing Main PreferenceService section to match the
other three infrastructure service docs. Links the lifecycle README to
the new testing guidance.
Store BrowserWindow directly in a private field; mark public getMainWindow()
as @deprecated with a runtime warn. Migrate ~27 webContents.send call sites
across 20 services to WindowManager.broadcastToType(). Move main-window-
specific IPC handlers from the monolithic ipc.ts into MainWindowService and
deparameterize registerIpc(). Rename window/app channels to MainWindow_*
(values main-window:*), keeping the 5 sender-resolution channels as-is for
detached-tab reuse. Swap @DependsOn to WindowManager in migrated broadcasters.
- Rename WindowService -> MainWindowService (git mv, preserves blame/log)
- Register WindowType.Main in windowRegistry (singleton, showMode: manual);
MainWindowService drives construction via wm.open and retains business
logic only: IPC handlers, tray-aware close, crash recovery, show/toggle
- 50 call sites renamed (@DependsOn, application.get keys, imports)
WM Dock visibility refactored from visibility-based to existence-based:
- updateDockVisibility predicate drops isVisible/isMinimized check — a
hidden main window must not remove the Dock icon (Cmd+W semantics)
- Add wm.setMacShowInDockByType(type, value) for tray-mode transitions;
keyed by type so services can suppress Dock before the first instance
exists (tray-on-launch path)
- Reduce triggers to window creation, destruction, and type-override
changes; show/hide/minimize/restore no longer affect Dock state
- dockShouldBeVisible initializes true to match Electron's default
MainWindowService uses setMacShowInDockByType for tray-on-launch, close-
to-tray, and reopen-from-tray paths, replacing manual app.dock?.hide()
calls that raced against WM.
Docs updated across window-manager/{README, overview, platform,
api-reference, migration-guide}. New MainWindowService unit test covers
the close matrix (isQuitting, win/linux tray on/off, mac default, mac
tray on_close, fullscreen edge, Dock override assertions) and crash
recovery (first reload vs second-within-60s forceExit).
- Register QuickAssistant in windowRegistry (singleton, show:false,
showInDock:false, macReapplyAlwaysOnTop quirk). QuickAssistantService
now creates the BrowserWindow via wm.create() and sets up listeners
directly after creation; no global onWindowCreated subscription needed
since we own the window.
- Instantiate windowStateKeeper before wm.create() and inject persisted
x/y/w/h via OpenWindowArgs.options. manage() only attaches outbound
listeners and does not retroactively apply persisted bounds.
- Set the initial alwaysOnTop level once after creation; the
macReapplyAlwaysOnTop quirk handles re-application across hide/show.
- closeQuickWindow now hides instead of destroying. Quick window is a
high-frequency toggle; destroy+recreate would blank-flash on next show
and waste preload work. Final teardown stays in WindowManager.onDestroy.
- Rename WindowType.Mini -> QuickAssistant, IpcChannel.MiniWindow_* ->
QuickAssistant_*, IpcChannel.ShowMiniWindow -> QuickAssistant_Shown,
preload window.api.miniWindow -> quickAssistant, log window source
'MiniWindow' -> 'QuickAssistant'. Drop dead QuickAssistant_Hidden IPC
(no listener exists anywhere in the tree).
- Cross-process contracts retained: miniWindow.html entry and
miniWindow-state.json bounds file are kept verbatim to avoid a build
layout change and to preserve every user's saved window bounds.
- Update renderer call sites (HomeWindow, QuickAssistantSettings,
entryPoint) and an e2e fixture comment to the new namespace.
Pooled lifecycle windows register a `close` handler that always calls
`event.preventDefault()` to recycle them to the pool. When `app.quit()`
fires `close` on every BrowserWindow, a single preventDefault is enough
for Electron to abort the quit chain, so `will-quit` never fires and
`Application.shutdown()` never runs. Once SelectionToolbar was migrated
into WindowManager's pooled lifecycle (57310618c), Ctrl+C started
leaving Electron as an orphan with `_isQuitting=true`, and a second
quit attempt from the menu was swallowed by the existing
`Already quitting` guard.
Bypass the pooled-close intercept and pool replenishment whenever
`application.isQuitting` is true — close events must reach their
native destination so `will-quit` can drive the normal
`Application.shutdown()` path. Also make `Application.quit()`
re-trigger `app.quit()` when already quitting, so a stalled first
attempt no longer traps the user into `kill -9`.
Covered by a new WindowManager test case asserting that pooled close
is not preventDefault'd while `application.isQuitting === true`.
Adds a unified, file-backed SQLite test harness under tests/helpers/db/
that provisions a real database per test file using the production
migrations + CUSTOM_SQL_STATEMENTS, wires it through
MockMainDbServiceUtils.setDb() so production code reaches it via
application.get('DbService').getDb() transparently, truncates user
tables on beforeEach, and cleans up on afterAll. Replaces the need for
hand-written CREATE TABLE SQL and inline vi.mock('@application')
overrides in consumer tests.
Companion changes:
- Register @test-helpers/* path alias (electron.vite.config.ts,
tsconfig.node.json paths + include, vitest.config.ts main project
include).
- Relax the global vi.mock stubs for node:fs, node:os, node:path in
tests/main.setup.ts so third-party libraries (drizzle-orm migrator
etc.) can read real files. The six existing tests that depended on
the previous fully-stubbed modules now declare a local
vi.mock('node:fs', ...) via the new createNodeFsMock helper at
tests/helpers/mocks/nodeFsMock.ts.
- Self-tests under tests/helpers/db/__tests__/testDatabase.test.ts
cover PRAGMA state, truncate semantics, FTS5 trigger cascades,
NULL-searchableText handling, application-mock routing, and
replay-array accumulation guards.
Align with the existing @logger alias convention by introducing
@application as a short alias for src/main/core/application. This
reduces import verbosity across ~130 main-process files while keeping
4 intentional sub-path imports (@main/core/application/Application)
unchanged to preserve the vi.mock bypass mechanism in tests.
Configured in tsconfig.node.json and electron.vite.config.ts; Vitest
inherits the alias automatically.
Signed-off-by: fullex <0xfullex@gmail.com>
Introduce `Application.initPathRegistry()` and invoke it from preboot in
`main/index.ts` (after the single-instance lock check, before
`crashReporter.start()`). `application.bootstrap()` no longer initializes
the path registry; it asserts the registry is already initialized and
fails fast with a clear error if not.
Why: the registry's only hard dependency is `app.setPath('userData')`
having completed, which `resolveUserDataLocation()` finishes in preboot.
Initializing from preboot decouples path registry lifetime from service
orchestration and exposes the timing contract as an explicit assertion
rather than a silent lazy init inside `bootstrap()`. This opens the door
for future preboot code (migration, rtk extraction, crashReporter) to
consume `application.getPath()` directly.
Also:
- `buildPathRegistry()` JSDoc now documents the constraint that new path
keys must be resolvable in the preboot phase (no `whenReady`-only APIs,
no dependencies on services being started).
- `getPath()` error message updated to point at `initPathRegistry()`.
- Global test mock gains a matching `initPathRegistry` stub.
- `preboot/README.md` and `paths/README.md` sync the new timing.
Signed-off-by: fullex <0xfullex@gmail.com>
Replace consumers of the seven legacy file.ts helpers (getTempDir,
getFilesDir, getNotesDir, getConfigDir, getCacheDir, getMcpDir,
getAppConfigDir) with application.getPath(), then delete the helpers.
All seven map to existing path registry keys — zero new keys needed.
Stable sub-path joins now use dedicated keys directly
(feature.dxt.uploads.temp, feature.preprocess.temp, feature.mcp.oauth,
feature.anthropic.oauth_file, feature.copilot.token_file,
feature.mcp.memory_file).
Auto-ensure on application.getPath() makes the existing fs.existsSync
+ fs.mkdirSync boilerplate redundant; removed initStorageDir from
FileStorage and ensureDirectories from DxtService and
BasePreprocessProvider.
Three top-level singletons (fileStorage, dxtService, copilotService)
are instantiated during the static import graph of src/main/index.ts
— before application.bootstrap() builds the path registry. Field
initializers and constructor assignments calling getPath() at
instantiation time would throw "PATHS not initialized". Each is
converted to a lazy getter (cached in CopilotService where the
resolution has an fs.existsSync side effect) with a TODO(v2) comment
marking it as a workaround for an underlying architectural issue:
these singletons should be migrated into the lifecycle system in a
follow-up.
Module-top-level const path expressions in AnthropicService
(CREDS_PATH) and mcpServers/memory.ts (defaultMemoryPath) are
wrapped in lazy getter functions for the same reason.
Test infrastructure: the unified application mock factory in
tests/__mocks__/main/application.ts now stubs getPath, so future
tests that instantiate services with path-dependent fields work
without per-test setup. The pre-existing ad-hoc mock in
MCPService.test.ts gets the same stub. Four describe blocks for the
deleted helpers are removed from file.test.ts (getAppConfigDir was
confirmed dead code, with no production callers).
src/main/utils/init.ts is intentionally untouched: its getConfigDir
is a private local function (not an import from file.ts), and the
file is @deprecated awaiting v2 BootConfig migration.
Signed-off-by: fullex <0xfullex@gmail.com>
Tests calling application.get('WindowService') now get a minimal mock
instead of throwing "Unknown service: WindowService".
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
