style(design): apply Minimal Dark Mode design system\n\n- Switched to complete Dark Mode (OLED-friendly)\n- Established standard color palette matching modern technical aesthetics\n- Changed font to Plus Jakarta Sans for increased legibility\n- Enforced dark mode as default in App.tsx\n- Fixed several React cascading render (setState in useEffect) warnings
This commit is contained in:
Gemini Nexus Bot committed
1 parent
b80531f8a8
commit
bac7b5591e
738 files changed
+138513
-138123
No files matched your search
@@ -1,36 +1,36 @@
|
||||
## Context
|
||||
The existing Electron Forge packaging pipeline needs Linux arm64, macOS universal, and Windows MSI outputs, plus consistent artifact naming and SHA-256 checksum outputs for cross-platform release parity.
|
||||
|
||||
## Goals / Non-Goals
|
||||
- Goals:
|
||||
- Cover Linux arm64 artifacts (`deb`/`rpm`/`AppImage`)
|
||||
- Provide macOS `x64`/`arm64`/`universal` dmg artifacts
|
||||
- Add MSI artifacts for Windows
|
||||
- Include architecture markers in artifact names and output SHA-256 checksums
|
||||
- Non-Goals:
|
||||
- Change existing update logic (`latest*.yml` remains unchanged)
|
||||
- Modify runtime application behavior
|
||||
|
||||
## Decisions
|
||||
- Decision: Build Linux arm64 on a dedicated arm64 runner, without cross-compilation.
|
||||
- Decision: Build macOS universal via `--arch=universal` or by merging app bundles before dmg packaging.
|
||||
- Decision: Generate Windows MSI with the official Forge maker (Wix/MSI) in parallel with Squirrel.
|
||||
- Decision: Use `productName + version + arch` naming; Linux uses `amd64/aarch64`, macOS/Windows use `x64/arm64/universal`.
|
||||
|
||||
## Alternatives Considered
|
||||
- x64-only artifacts: rejected because it does not meet user requirements.
|
||||
- universal-only dmg: rejected due to weaker debugging/rollback capability and lack of architecture distinction.
|
||||
|
||||
## Risks / Trade-offs
|
||||
- Linux arm64 builds may be affected by native dependency compilation (for example, `better-sqlite3`, `keytar`).
|
||||
- Windows MSI requires extra tooling (Wix), which may increase CI duration and failure rate.
|
||||
- The universal dmg pipeline requires validation for signing and update-flow consistency.
|
||||
|
||||
## Migration Plan
|
||||
1) Introduce CI multi-arch jobs with naming and checksum outputs.
|
||||
2) Add MSI maker and universal dmg packaging.
|
||||
3) Stabilize the workflow after release validation.
|
||||
|
||||
## Open Questions
|
||||
- Should artifact naming strictly match sample format (underscore vs hyphen)?
|
||||
- Should checksum output be separate `.sha256` files or a single consolidated manifest?
|
||||
## Context
|
||||
The existing Electron Forge packaging pipeline needs Linux arm64, macOS universal, and Windows MSI outputs, plus consistent artifact naming and SHA-256 checksum outputs for cross-platform release parity.
|
||||
|
||||
## Goals / Non-Goals
|
||||
- Goals:
|
||||
- Cover Linux arm64 artifacts (`deb`/`rpm`/`AppImage`)
|
||||
- Provide macOS `x64`/`arm64`/`universal` dmg artifacts
|
||||
- Add MSI artifacts for Windows
|
||||
- Include architecture markers in artifact names and output SHA-256 checksums
|
||||
- Non-Goals:
|
||||
- Change existing update logic (`latest*.yml` remains unchanged)
|
||||
- Modify runtime application behavior
|
||||
|
||||
## Decisions
|
||||
- Decision: Build Linux arm64 on a dedicated arm64 runner, without cross-compilation.
|
||||
- Decision: Build macOS universal via `--arch=universal` or by merging app bundles before dmg packaging.
|
||||
- Decision: Generate Windows MSI with the official Forge maker (Wix/MSI) in parallel with Squirrel.
|
||||
- Decision: Use `productName + version + arch` naming; Linux uses `amd64/aarch64`, macOS/Windows use `x64/arm64/universal`.
|
||||
|
||||
## Alternatives Considered
|
||||
- x64-only artifacts: rejected because it does not meet user requirements.
|
||||
- universal-only dmg: rejected due to weaker debugging/rollback capability and lack of architecture distinction.
|
||||
|
||||
## Risks / Trade-offs
|
||||
- Linux arm64 builds may be affected by native dependency compilation (for example, `better-sqlite3`, `keytar`).
|
||||
- Windows MSI requires extra tooling (Wix), which may increase CI duration and failure rate.
|
||||
- The universal dmg pipeline requires validation for signing and update-flow consistency.
|
||||
|
||||
## Migration Plan
|
||||
1) Introduce CI multi-arch jobs with naming and checksum outputs.
|
||||
2) Add MSI maker and universal dmg packaging.
|
||||
3) Stabilize the workflow after release validation.
|
||||
|
||||
## Open Questions
|
||||
- Should artifact naming strictly match sample format (underscore vs hyphen)?
|
||||
- Should checksum output be separate `.sha256` files or a single consolidated manifest?
|
||||
@@ -1,20 +1,20 @@
|
||||
# Change: Add Multi-Architecture and Multi-Format Release Artifacts
|
||||
|
||||
## Why
|
||||
|
||||
Current release artifacts only cover part of the required architectures and formats. This does not meet demand for Linux arm64, macOS universal, and Windows MSI, and it lacks consistent naming and SHA-256 checksum outputs aligned with distribution requirements.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add Linux arm64 (`aarch64`) builds producing `.deb`, `.rpm`, and `.AppImage`.
|
||||
- Add `macOS universal.dmg` (while keeping x64/arm64 dmg outputs).
|
||||
- Add Windows MSI artifacts in parallel with existing Squirrel `.exe`.
|
||||
- Standardize artifact naming and architecture identifiers, and generate SHA-256 checksum files.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `release-packaging`
|
||||
- Affected code:
|
||||
- `E:\project\Crack\.github\workflows\publish.yaml`
|
||||
- `E:\project\Crack\forge.config.ts`
|
||||
- `E:\project\Crack\package.json`
|
||||
# Change: Add Multi-Architecture and Multi-Format Release Artifacts
|
||||
|
||||
## Why
|
||||
|
||||
Current release artifacts only cover part of the required architectures and formats. This does not meet demand for Linux arm64, macOS universal, and Windows MSI, and it lacks consistent naming and SHA-256 checksum outputs aligned with distribution requirements.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add Linux arm64 (`aarch64`) builds producing `.deb`, `.rpm`, and `.AppImage`.
|
||||
- Add `macOS universal.dmg` (while keeping x64/arm64 dmg outputs).
|
||||
- Add Windows MSI artifacts in parallel with existing Squirrel `.exe`.
|
||||
- Standardize artifact naming and architecture identifiers, and generate SHA-256 checksum files.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `release-packaging`
|
||||
- Affected code:
|
||||
- `E:\project\Crack\.github\workflows\publish.yaml`
|
||||
- `E:\project\Crack\forge.config.ts`
|
||||
- `E:\project\Crack\package.json`
|
||||
@@ -1,41 +1,41 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Linux Multi-Architecture Release Artifacts
|
||||
The system SHALL produce Linux x64 and arm64 release artifacts, including `.deb`, `.rpm`, and `.AppImage`.
|
||||
|
||||
#### Scenario: Linux x64 artifact generation
|
||||
- **WHEN** building a release on Linux x64
|
||||
- **THEN** release assets include x64 `.deb`, `.rpm`, and `.AppImage` files
|
||||
|
||||
#### Scenario: Linux arm64 artifact generation
|
||||
- **WHEN** building a release on Linux arm64
|
||||
- **THEN** release assets include arm64 `.deb`, `.rpm`, and `.AppImage` files
|
||||
|
||||
### Requirement: macOS Multi-Architecture and Universal dmg
|
||||
The system SHALL produce macOS x64, arm64, and universal dmg artifacts in release builds.
|
||||
|
||||
#### Scenario: macOS x64/arm64 dmg generation
|
||||
- **WHEN** building releases for macOS x64 and arm64
|
||||
- **THEN** release assets include dmg files for each corresponding architecture
|
||||
|
||||
#### Scenario: macOS universal dmg generation
|
||||
- **WHEN** running a universal build
|
||||
- **THEN** release assets include a universal dmg
|
||||
|
||||
### Requirement: Parallel Windows MSI and Squirrel Artifacts
|
||||
The system SHALL generate both Squirrel installer artifacts and MSI artifacts in Windows release builds.
|
||||
|
||||
#### Scenario: Windows MSI generation
|
||||
- **WHEN** building a release on Windows x64
|
||||
- **THEN** release assets include both `.exe` installer and `.msi` artifacts
|
||||
|
||||
### Requirement: Artifact Naming and SHA-256 Output
|
||||
The system SHALL output SHA-256 checksums for all release artifacts and use a unified naming convention that includes architecture markers.
|
||||
|
||||
#### Scenario: Artifact naming includes version and architecture
|
||||
- **WHEN** generating release artifacts
|
||||
- **THEN** artifact names include `productName`, `version`, and `arch` identifiers
|
||||
|
||||
#### Scenario: SHA-256 checksum output
|
||||
- **WHEN** release artifact generation finishes
|
||||
- **THEN** release assets include SHA-256 checksums for corresponding artifacts
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Linux Multi-Architecture Release Artifacts
|
||||
The system SHALL produce Linux x64 and arm64 release artifacts, including `.deb`, `.rpm`, and `.AppImage`.
|
||||
|
||||
#### Scenario: Linux x64 artifact generation
|
||||
- **WHEN** building a release on Linux x64
|
||||
- **THEN** release assets include x64 `.deb`, `.rpm`, and `.AppImage` files
|
||||
|
||||
#### Scenario: Linux arm64 artifact generation
|
||||
- **WHEN** building a release on Linux arm64
|
||||
- **THEN** release assets include arm64 `.deb`, `.rpm`, and `.AppImage` files
|
||||
|
||||
### Requirement: macOS Multi-Architecture and Universal dmg
|
||||
The system SHALL produce macOS x64, arm64, and universal dmg artifacts in release builds.
|
||||
|
||||
#### Scenario: macOS x64/arm64 dmg generation
|
||||
- **WHEN** building releases for macOS x64 and arm64
|
||||
- **THEN** release assets include dmg files for each corresponding architecture
|
||||
|
||||
#### Scenario: macOS universal dmg generation
|
||||
- **WHEN** running a universal build
|
||||
- **THEN** release assets include a universal dmg
|
||||
|
||||
### Requirement: Parallel Windows MSI and Squirrel Artifacts
|
||||
The system SHALL generate both Squirrel installer artifacts and MSI artifacts in Windows release builds.
|
||||
|
||||
#### Scenario: Windows MSI generation
|
||||
- **WHEN** building a release on Windows x64
|
||||
- **THEN** release assets include both `.exe` installer and `.msi` artifacts
|
||||
|
||||
### Requirement: Artifact Naming and SHA-256 Output
|
||||
The system SHALL output SHA-256 checksums for all release artifacts and use a unified naming convention that includes architecture markers.
|
||||
|
||||
#### Scenario: Artifact naming includes version and architecture
|
||||
- **WHEN** generating release artifacts
|
||||
- **THEN** artifact names include `productName`, `version`, and `arch` identifiers
|
||||
|
||||
#### Scenario: SHA-256 checksum output
|
||||
- **WHEN** release artifact generation finishes
|
||||
- **THEN** release assets include SHA-256 checksums for corresponding artifacts
|
||||
@@ -1,7 +1,7 @@
|
||||
## 1. Implementation
|
||||
- [x] 1.1 Update the release workflow matrix to add Linux arm64 builds and split build steps by architecture.
|
||||
- [x] 1.2 Add macOS universal build flow (merge app bundles before generating universal dmg).
|
||||
- [x] 1.3 Introduce Windows MSI maker and required dependencies, and generate MSI in the Windows job.
|
||||
- [x] 1.4 Extend `postMake` artifact renaming and architecture mapping logic to generate SHA-256 checksum files.
|
||||
- [ ] 1.5 Update release attachments and artifact inventory documentation (if needed).
|
||||
- [ ] 1.6 Verify CI outputs for Linux arm64, macOS universal, and Windows MSI.
|
||||
## 1. Implementation
|
||||
- [x] 1.1 Update the release workflow matrix to add Linux arm64 builds and split build steps by architecture.
|
||||
- [x] 1.2 Add macOS universal build flow (merge app bundles before generating universal dmg).
|
||||
- [x] 1.3 Introduce Windows MSI maker and required dependencies, and generate MSI in the Windows job.
|
||||
- [x] 1.4 Extend `postMake` artifact renaming and architecture mapping logic to generate SHA-256 checksum files.
|
||||
- [ ] 1.5 Update release attachments and artifact inventory documentation (if needed).
|
||||
- [ ] 1.6 Verify CI outputs for Linux arm64, macOS universal, and Windows MSI.
|
||||
@@ -1,35 +1,35 @@
|
||||
## Context
|
||||
|
||||
The stability of account injection and detection differs across platforms, with risks concentrated in:
|
||||
- DB lock conflicts causing unstable writes.
|
||||
- Version-detection failures causing incorrect injection-path routing.
|
||||
- Compatibility boundaries introduced by OS behavior differences.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
- Goals:
|
||||
- Improve cross-platform write and switching stability.
|
||||
- Define clear priority between version detection and capability probing.
|
||||
- Improve observability and troubleshooting efficiency.
|
||||
- Non-Goals:
|
||||
- Extend support to non-default runtime configuration path parsing.
|
||||
- Introduce new business strategies.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Decision: Transactionalize the write flow to reduce partial-success risk.
|
||||
- Decision: Add DB busy retry and `busy_timeout`.
|
||||
- Decision: On version-detection failure, use `package.json` as Windows fallback source.
|
||||
- Decision: Give capability probing higher priority than version detection; prefer new format when a new-format key is detected.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- A stricter write flow may add minor latency.
|
||||
- Running capability probing and version detection together increases implementation complexity.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Complete transactional writes and retry mechanisms.
|
||||
2. Add version-detection cache and fallback.
|
||||
3. Introduce strategy-based injection and capability probing.
|
||||
4. Add corresponding tests and regression verification.
|
||||
## Context
|
||||
|
||||
The stability of account injection and detection differs across platforms, with risks concentrated in:
|
||||
- DB lock conflicts causing unstable writes.
|
||||
- Version-detection failures causing incorrect injection-path routing.
|
||||
- Compatibility boundaries introduced by OS behavior differences.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
- Goals:
|
||||
- Improve cross-platform write and switching stability.
|
||||
- Define clear priority between version detection and capability probing.
|
||||
- Improve observability and troubleshooting efficiency.
|
||||
- Non-Goals:
|
||||
- Extend support to non-default runtime configuration path parsing.
|
||||
- Introduce new business strategies.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Decision: Transactionalize the write flow to reduce partial-success risk.
|
||||
- Decision: Add DB busy retry and `busy_timeout`.
|
||||
- Decision: On version-detection failure, use `package.json` as Windows fallback source.
|
||||
- Decision: Give capability probing higher priority than version detection; prefer new format when a new-format key is detected.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- A stricter write flow may add minor latency.
|
||||
- Running capability probing and version detection together increases implementation complexity.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Complete transactional writes and retry mechanisms.
|
||||
2. Add version-detection cache and fallback.
|
||||
3. Introduce strategy-based injection and capability probing.
|
||||
4. Add corresponding tests and regression verification.
|
||||
@@ -1,35 +1,35 @@
|
||||
# Change: Cross-Platform Stability and Robustness Improvements (P0+P1+P2)
|
||||
|
||||
## Why
|
||||
|
||||
- Account injection and detection across platforms are vulnerable to DB locks, version-detection failures, and OS-level differences.
|
||||
- Stability, diagnosability, and maintainability must improve without changing business semantics.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Make the write flow atomic (transaction-wrapped).
|
||||
- Add DB lock retry and `busy_timeout`.
|
||||
- Add cache and lower-noise logging for version detection.
|
||||
- Add a more robust Windows fallback for version detection (read from `package.json`).
|
||||
- Introduce strategy-based injection routing (new/legacy/dual-write).
|
||||
- Add capability probing: prefer new format when new-format keys are detected.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `ide-auth-compat`
|
||||
- Affected code:
|
||||
- `src/ipc/database/cloudHandler.ts`
|
||||
- `src/ipc/database/handler.ts`
|
||||
- `src/utils/geminiNexusVersion.ts`
|
||||
- `src/utils/paths.ts` (this stage covers default runtime configuration path only)
|
||||
- `src/types/db.ts`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not change existing business semantics; only improve stability and structure.
|
||||
- This stage only covers the default runtime configuration path.
|
||||
|
||||
## Risks
|
||||
|
||||
- Transaction and retry logic may change when errors surface.
|
||||
- Capability probing may conflict with version detection unless priority is clearly defined.
|
||||
# Change: Cross-Platform Stability and Robustness Improvements (P0+P1+P2)
|
||||
|
||||
## Why
|
||||
|
||||
- Account injection and detection across platforms are vulnerable to DB locks, version-detection failures, and OS-level differences.
|
||||
- Stability, diagnosability, and maintainability must improve without changing business semantics.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Make the write flow atomic (transaction-wrapped).
|
||||
- Add DB lock retry and `busy_timeout`.
|
||||
- Add cache and lower-noise logging for version detection.
|
||||
- Add a more robust Windows fallback for version detection (read from `package.json`).
|
||||
- Introduce strategy-based injection routing (new/legacy/dual-write).
|
||||
- Add capability probing: prefer new format when new-format keys are detected.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `ide-auth-compat`
|
||||
- Affected code:
|
||||
- `src/ipc/database/cloudHandler.ts`
|
||||
- `src/ipc/database/handler.ts`
|
||||
- `src/utils/geminiNexusVersion.ts`
|
||||
- `src/utils/paths.ts` (this stage covers default runtime configuration path only)
|
||||
- `src/types/db.ts`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not change existing business semantics; only improve stability and structure.
|
||||
- This stage only covers the default runtime configuration path.
|
||||
|
||||
## Risks
|
||||
|
||||
- Transaction and retry logic may change when errors surface.
|
||||
- Capability probing may conflict with version detection unless priority is clearly defined.
|
||||
@@ -1,42 +1,42 @@
|
||||
## ADDED Requirements
|
||||
### Requirement: Atomic Injection Writes
|
||||
The system SHALL use transactions when writing IDE state to ensure atomic updates.
|
||||
|
||||
#### Scenario: Injection write consistency
|
||||
- **WHEN** injecting new/legacy token formats
|
||||
- **THEN** related keys are committed in a single transaction to avoid partial writes
|
||||
|
||||
### Requirement: DB Lock Retry
|
||||
The system SHALL perform short backoff retries on SQLITE_BUSY or SQLITE_LOCKED.
|
||||
|
||||
#### Scenario: Successful DB lock retry
|
||||
- **WHEN** a write encounters a lock
|
||||
- **THEN** the system retries for a limited number of attempts and records logs
|
||||
|
||||
### Requirement: Version Detection Cache
|
||||
The system SHALL cache IDE version-detection results in-process to reduce repeated system calls.
|
||||
|
||||
#### Scenario: Version cache hit
|
||||
- **WHEN** IDE version is requested multiple times
|
||||
- **THEN** the system call is executed only once
|
||||
|
||||
### Requirement: Windows Version Detection Fallback
|
||||
The system SHALL read `package.json` as a fallback source when Windows version detection fails.
|
||||
|
||||
#### Scenario: Windows version detection failure
|
||||
- **WHEN** PowerShell fails to read version
|
||||
- **THEN** version is obtained by falling back to `package.json`
|
||||
|
||||
### Requirement: Strategy-Based Injection
|
||||
The system SHALL use a strategy pattern to split new/legacy/dual-write injection paths for clearer structure.
|
||||
|
||||
#### Scenario: Strategy selection
|
||||
- **WHEN** version-based and capability-based routing differ
|
||||
- **THEN** the system selects the corresponding injection implementation via strategy objects
|
||||
|
||||
### Requirement: Prefer New Format via Capability Probing
|
||||
The system SHALL prefer new-format injection when new-format keys are detected.
|
||||
|
||||
#### Scenario: New-format key exists
|
||||
- **WHEN** `geminiNexusUnifiedStateSync.oauthToken` exists
|
||||
- **THEN** injection uses new format with higher priority
|
||||
## ADDED Requirements
|
||||
### Requirement: Atomic Injection Writes
|
||||
The system SHALL use transactions when writing IDE state to ensure atomic updates.
|
||||
|
||||
#### Scenario: Injection write consistency
|
||||
- **WHEN** injecting new/legacy token formats
|
||||
- **THEN** related keys are committed in a single transaction to avoid partial writes
|
||||
|
||||
### Requirement: DB Lock Retry
|
||||
The system SHALL perform short backoff retries on SQLITE_BUSY or SQLITE_LOCKED.
|
||||
|
||||
#### Scenario: Successful DB lock retry
|
||||
- **WHEN** a write encounters a lock
|
||||
- **THEN** the system retries for a limited number of attempts and records logs
|
||||
|
||||
### Requirement: Version Detection Cache
|
||||
The system SHALL cache IDE version-detection results in-process to reduce repeated system calls.
|
||||
|
||||
#### Scenario: Version cache hit
|
||||
- **WHEN** IDE version is requested multiple times
|
||||
- **THEN** the system call is executed only once
|
||||
|
||||
### Requirement: Windows Version Detection Fallback
|
||||
The system SHALL read `package.json` as a fallback source when Windows version detection fails.
|
||||
|
||||
#### Scenario: Windows version detection failure
|
||||
- **WHEN** PowerShell fails to read version
|
||||
- **THEN** version is obtained by falling back to `package.json`
|
||||
|
||||
### Requirement: Strategy-Based Injection
|
||||
The system SHALL use a strategy pattern to split new/legacy/dual-write injection paths for clearer structure.
|
||||
|
||||
#### Scenario: Strategy selection
|
||||
- **WHEN** version-based and capability-based routing differ
|
||||
- **THEN** the system selects the corresponding injection implementation via strategy objects
|
||||
|
||||
### Requirement: Prefer New Format via Capability Probing
|
||||
The system SHALL prefer new-format injection when new-format keys are detected.
|
||||
|
||||
#### Scenario: New-format key exists
|
||||
- **WHEN** `geminiNexusUnifiedStateSync.oauthToken` exists
|
||||
- **THEN** injection uses new format with higher priority
|
||||
@@ -1,17 +1,17 @@
|
||||
## 1. Scope and Planning Confirmation
|
||||
- [ ] 1.1 Review `proposal.md`.
|
||||
- [ ] 1.2 Finalize priority: capability probing vs version detection.
|
||||
- [ ] 1.3 Confirm this stage covers default runtime configuration path only.
|
||||
|
||||
## 2. Implementation
|
||||
- [x] 2.1 Make write flow transactional (atomic).
|
||||
- [x] 2.2 Add DB lock retry and `busy_timeout`.
|
||||
- [x] 2.3 Add version-detection cache and lower-noise logs.
|
||||
- [x] 2.4 Add Windows fallback for version detection (`package.json`).
|
||||
- [x] 2.5 Split injection path by strategy pattern.
|
||||
- [x] 2.6 Add capability probing: prefer new format when new key is detected.
|
||||
|
||||
## 3. Verification
|
||||
- [x] 3.1 Simulate SQLITE_BUSY/LOCKED retry behavior.
|
||||
- [x] 3.2 Verify fallback path for version-detection failure.
|
||||
- [x] 3.3 Verify capability-probing priority behavior.
|
||||
## 1. Scope and Planning Confirmation
|
||||
- [ ] 1.1 Review `proposal.md`.
|
||||
- [ ] 1.2 Finalize priority: capability probing vs version detection.
|
||||
- [ ] 1.3 Confirm this stage covers default runtime configuration path only.
|
||||
|
||||
## 2. Implementation
|
||||
- [x] 2.1 Make write flow transactional (atomic).
|
||||
- [x] 2.2 Add DB lock retry and `busy_timeout`.
|
||||
- [x] 2.3 Add version-detection cache and lower-noise logs.
|
||||
- [x] 2.4 Add Windows fallback for version detection (`package.json`).
|
||||
- [x] 2.5 Split injection path by strategy pattern.
|
||||
- [x] 2.6 Add capability probing: prefer new format when new key is detected.
|
||||
|
||||
## 3. Verification
|
||||
- [x] 3.1 Simulate SQLITE_BUSY/LOCKED retry behavior.
|
||||
- [x] 3.2 Verify fallback path for version-detection failure.
|
||||
- [x] 3.3 Verify capability-probing priority behavior.
|
||||
@@ -1,30 +1,30 @@
|
||||
# Design: Multilingual Support
|
||||
|
||||
## Architecture
|
||||
|
||||
The application uses `react-i18next` for i18n and `i18next-browser-languagedetector` for language detection. Configuration is centralized in `src/localization/i18n.ts`.
|
||||
|
||||
### Language Resources
|
||||
|
||||
Translation resources are built as JSON objects in `i18n.ts` (or split into files if they grow large).
|
||||
We add a `zh-CN` key in the `resources` object.
|
||||
|
||||
### Default Language Strategy
|
||||
|
||||
We introduce the `LanguageDetector` plugin.
|
||||
`i18n.use(LanguageDetector).init({...})` is configured to check `localStorage` first, then `navigator` (browser/system language).
|
||||
`fallbackLng` remains `'en'` as the final fallback.
|
||||
|
||||
### Key Mapping
|
||||
|
||||
Existing English strings are mapped to semantic keys (for example, `home.title`, `settings.theme`).
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. App starts.
|
||||
2. `i18next` initializes and determines language via `LanguageDetector`:
|
||||
* Check whether `localStorage` has a saved preference.
|
||||
* If not, check `navigator.language`.
|
||||
* If detected language is supported (`en` or `zh-CN`), use it.
|
||||
* Otherwise, use `fallbackLng` (`en`).
|
||||
3. Components use `useTranslation` to resolve strings for the active language.
|
||||
# Design: Multilingual Support
|
||||
|
||||
## Architecture
|
||||
|
||||
The application uses `react-i18next` for i18n and `i18next-browser-languagedetector` for language detection. Configuration is centralized in `src/localization/i18n.ts`.
|
||||
|
||||
### Language Resources
|
||||
|
||||
Translation resources are built as JSON objects in `i18n.ts` (or split into files if they grow large).
|
||||
We add a `zh-CN` key in the `resources` object.
|
||||
|
||||
### Default Language Strategy
|
||||
|
||||
We introduce the `LanguageDetector` plugin.
|
||||
`i18n.use(LanguageDetector).init({...})` is configured to check `localStorage` first, then `navigator` (browser/system language).
|
||||
`fallbackLng` remains `'en'` as the final fallback.
|
||||
|
||||
### Key Mapping
|
||||
|
||||
Existing English strings are mapped to semantic keys (for example, `home.title`, `settings.theme`).
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. App starts.
|
||||
2. `i18next` initializes and determines language via `LanguageDetector`:
|
||||
* Check whether `localStorage` has a saved preference.
|
||||
* If not, check `navigator.language`.
|
||||
* If detected language is supported (`en` or `zh-CN`), use it.
|
||||
* Otherwise, use `fallbackLng` (`en`).
|
||||
3. Components use `useTranslation` to resolve strings for the active language.
|
||||
@@ -1,41 +1,41 @@
|
||||
# Proposal: App Localization (Automatic System Language Detection)
|
||||
|
||||
**Change ID:** `localize-app-auto-detect`
|
||||
|
||||
## Summary
|
||||
|
||||
Add multilingual support to Gemini Nexus and automatically set the default UI language based on the user's OS language. If the OS language is unsupported, fall back to English. This includes updating i18n configuration, adding Chinese translation resources, and integrating a language detection plugin.
|
||||
|
||||
## Motivation
|
||||
|
||||
To provide a better user experience, the app should adapt to users' preferred language environment. Automatically detecting system language reduces setup effort and improves first-run experience.
|
||||
|
||||
## Proposed Changes
|
||||
|
||||
1. **Integrate language detection:** Install and configure `i18next-browser-languagedetector` to auto-detect user language.
|
||||
2. **Update i18n config:** Modify `src/localization/i18n.ts` to enable language detection and define a fallback language (English).
|
||||
3. **Add Chinese resources:** Create `zh-CN` translation resources covering all app strings.
|
||||
4. **Update language actions:** Ensure `src/actions/language.ts` correctly handles auto-detection and manual override.
|
||||
5. **UI updates:** Ensure all UI components use translation keys instead of hardcoded text.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
* **Force default Chinese:** Rejected, to support a broader international user base and respect system settings.
|
||||
* **Force default English:** Rejected, same reason.
|
||||
|
||||
## Risks
|
||||
|
||||
* **Detection failure:** In certain environments (for example, some Linux distros), language detection may be inaccurate. Fallback behavior must remain reliable.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Automatic detection:**
|
||||
* When OS language is Simplified Chinese, app defaults to Chinese on first launch.
|
||||
* When OS language is English or another non-Chinese language, app defaults to English on first launch.
|
||||
2. **Manual switching:**
|
||||
* Users can switch from Chinese to English in Settings, and UI updates immediately without restart.
|
||||
* Users can switch from English to Chinese in Settings, and UI updates immediately without restart.
|
||||
3. **Persistence:**
|
||||
* After users manually change language, app restart preserves the selected language instead of re-detecting.
|
||||
4. **Completeness:**
|
||||
* All visible strings (home page, settings page, status bar, popups) render correctly in the selected language with no leftover hardcoded text.
|
||||
# Proposal: App Localization (Automatic System Language Detection)
|
||||
|
||||
**Change ID:** `localize-app-auto-detect`
|
||||
|
||||
## Summary
|
||||
|
||||
Add multilingual support to Gemini Nexus and automatically set the default UI language based on the user's OS language. If the OS language is unsupported, fall back to English. This includes updating i18n configuration, adding Chinese translation resources, and integrating a language detection plugin.
|
||||
|
||||
## Motivation
|
||||
|
||||
To provide a better user experience, the app should adapt to users' preferred language environment. Automatically detecting system language reduces setup effort and improves first-run experience.
|
||||
|
||||
## Proposed Changes
|
||||
|
||||
1. **Integrate language detection:** Install and configure `i18next-browser-languagedetector` to auto-detect user language.
|
||||
2. **Update i18n config:** Modify `src/localization/i18n.ts` to enable language detection and define a fallback language (English).
|
||||
3. **Add Chinese resources:** Create `zh-CN` translation resources covering all app strings.
|
||||
4. **Update language actions:** Ensure `src/actions/language.ts` correctly handles auto-detection and manual override.
|
||||
5. **UI updates:** Ensure all UI components use translation keys instead of hardcoded text.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
* **Force default Chinese:** Rejected, to support a broader international user base and respect system settings.
|
||||
* **Force default English:** Rejected, same reason.
|
||||
|
||||
## Risks
|
||||
|
||||
* **Detection failure:** In certain environments (for example, some Linux distros), language detection may be inaccurate. Fallback behavior must remain reliable.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Automatic detection:**
|
||||
* When OS language is Simplified Chinese, app defaults to Chinese on first launch.
|
||||
* When OS language is English or another non-Chinese language, app defaults to English on first launch.
|
||||
2. **Manual switching:**
|
||||
* Users can switch from Chinese to English in Settings, and UI updates immediately without restart.
|
||||
* Users can switch from English to Chinese in Settings, and UI updates immediately without restart.
|
||||
3. **Persistence:**
|
||||
* After users manually change language, app restart preserves the selected language instead of re-detecting.
|
||||
4. **Completeness:**
|
||||
* All visible strings (home page, settings page, status bar, popups) render correctly in the selected language with no leftover hardcoded text.
|
||||
@@ -1,59 +1,59 @@
|
||||
# Spec: Localization
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Automatic Language Detection
|
||||
|
||||
On first launch, the application MUST automatically detect the user's system language and set the corresponding UI language.
|
||||
|
||||
#### Scenario: System language is Chinese
|
||||
|
||||
Given the user opens the app for the first time
|
||||
And the user's system language is set to Chinese (`zh-CN`)
|
||||
And no language preference is saved in local storage
|
||||
When the app loads
|
||||
Then the UI should be displayed in Simplified Chinese (`zh-CN`)
|
||||
|
||||
#### Scenario: System language is non-Chinese
|
||||
|
||||
Given the user opens the app for the first time
|
||||
And the user's system language is set to French (`fr`)
|
||||
And no language preference is saved in local storage
|
||||
When the app loads
|
||||
Then the UI should fall back to English (`en`)
|
||||
|
||||
### Requirement: Language Switching
|
||||
|
||||
Users MUST be able to switch between supported languages, and manual selection MUST override automatic detection.
|
||||
|
||||
#### Scenario: Switch language
|
||||
|
||||
Given the user is on the settings page
|
||||
When the user selects "English" from the language dropdown
|
||||
Then the UI should switch to English immediately
|
||||
And the preference should be saved to local storage
|
||||
|
||||
### Requirement: Persistence
|
||||
|
||||
The user's manual language preference MUST persist across sessions and take precedence over system language.
|
||||
|
||||
#### Scenario: Persist language preference
|
||||
|
||||
Given the user has manually selected "English" as preferred language
|
||||
And the user's system language is Chinese
|
||||
When the user restarts the app
|
||||
Then the UI should display English (respecting user preference)
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Update i18n Configuration
|
||||
|
||||
i18n configuration MUST be updated to support the language detection plugin.
|
||||
|
||||
#### Scenario: i18n configuration
|
||||
|
||||
`src/localization/i18n.ts` must be updated to:
|
||||
|
||||
1. Integrate `i18next-browser-languagedetector`.
|
||||
2. Configure detection order as `['localStorage', 'navigator']`.
|
||||
3. Include `zh-CN` resource objects.
|
||||
# Spec: Localization
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Automatic Language Detection
|
||||
|
||||
On first launch, the application MUST automatically detect the user's system language and set the corresponding UI language.
|
||||
|
||||
#### Scenario: System language is Chinese
|
||||
|
||||
Given the user opens the app for the first time
|
||||
And the user's system language is set to Chinese (`zh-CN`)
|
||||
And no language preference is saved in local storage
|
||||
When the app loads
|
||||
Then the UI should be displayed in Simplified Chinese (`zh-CN`)
|
||||
|
||||
#### Scenario: System language is non-Chinese
|
||||
|
||||
Given the user opens the app for the first time
|
||||
And the user's system language is set to French (`fr`)
|
||||
And no language preference is saved in local storage
|
||||
When the app loads
|
||||
Then the UI should fall back to English (`en`)
|
||||
|
||||
### Requirement: Language Switching
|
||||
|
||||
Users MUST be able to switch between supported languages, and manual selection MUST override automatic detection.
|
||||
|
||||
#### Scenario: Switch language
|
||||
|
||||
Given the user is on the settings page
|
||||
When the user selects "English" from the language dropdown
|
||||
Then the UI should switch to English immediately
|
||||
And the preference should be saved to local storage
|
||||
|
||||
### Requirement: Persistence
|
||||
|
||||
The user's manual language preference MUST persist across sessions and take precedence over system language.
|
||||
|
||||
#### Scenario: Persist language preference
|
||||
|
||||
Given the user has manually selected "English" as preferred language
|
||||
And the user's system language is Chinese
|
||||
When the user restarts the app
|
||||
Then the UI should display English (respecting user preference)
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Update i18n Configuration
|
||||
|
||||
i18n configuration MUST be updated to support the language detection plugin.
|
||||
|
||||
#### Scenario: i18n configuration
|
||||
|
||||
`src/localization/i18n.ts` must be updated to:
|
||||
|
||||
1. Integrate `i18next-browser-languagedetector`.
|
||||
2. Configure detection order as `['localStorage', 'navigator']`.
|
||||
3. Include `zh-CN` resource objects.
|
||||
@@ -1,10 +1,10 @@
|
||||
# Tasks: App Localization (Automatic System Language Detection)
|
||||
|
||||
* \[x] Install `i18next-browser-languagedetector`. <!-- id: install-dependency -->
|
||||
* \[x] Update `src/localization/i18n.ts` to configure language detection and include `zh-CN` resources. <!-- id: update-i18n-config -->
|
||||
* \[x] Verify `src/actions/language.ts` logic is compatible with auto-detection. <!-- id: verify-language-actions -->
|
||||
* \[x] Update `src/components/StatusBar.tsx` to use translations. <!-- id: localize-statusbar -->
|
||||
* \[x] Update `src/components/AccountCard.tsx` to use translations. <!-- id: localize-accountcard -->
|
||||
* \[x] Update `src/pages/index.tsx` (home page) to use translations. <!-- id: localize-homepage -->
|
||||
* \[x] Update `src/pages/settings.tsx` to use translations and add a language switcher. <!-- id: localize-settings -->
|
||||
* \[x] Run the app to verify language detection and manual switching. <!-- id: verify-localization -->
|
||||
# Tasks: App Localization (Automatic System Language Detection)
|
||||
|
||||
* \[x] Install `i18next-browser-languagedetector`. <!-- id: install-dependency -->
|
||||
* \[x] Update `src/localization/i18n.ts` to configure language detection and include `zh-CN` resources. <!-- id: update-i18n-config -->
|
||||
* \[x] Verify `src/actions/language.ts` logic is compatible with auto-detection. <!-- id: verify-language-actions -->
|
||||
* \[x] Update `src/components/StatusBar.tsx` to use translations. <!-- id: localize-statusbar -->
|
||||
* \[x] Update `src/components/AccountCard.tsx` to use translations. <!-- id: localize-accountcard -->
|
||||
* \[x] Update `src/pages/index.tsx` (home page) to use translations. <!-- id: localize-homepage -->
|
||||
* \[x] Update `src/pages/settings.tsx` to use translations and add a language switcher. <!-- id: localize-settings -->
|
||||
* \[x] Run the app to verify language detection and manual switching. <!-- id: verify-localization -->
|
||||
@@ -1,35 +1,35 @@
|
||||
## Context
|
||||
Current SQLite access mainly relies on native `better-sqlite3` APIs, without unified typing and runtime validation strategy. This raises maintenance cost and regression risk. Introducing Drizzle ORM aims to improve type safety and maintainability while preserving existing behavior and compatibility.
|
||||
|
||||
## Goals / Non-Goals
|
||||
- Goals:
|
||||
- Provide structured schema and type inference
|
||||
- Unify DB access and validation patterns, reducing `any/as`
|
||||
- Preserve WAL, `busy_timeout`, transactions, and compatibility logic
|
||||
- Non-Goals:
|
||||
- Do not change existing database schema
|
||||
- Do not introduce a new database engine or remote storage
|
||||
|
||||
## Decisions
|
||||
- Decision: Adopt Drizzle ORM while keeping `better-sqlite3` as the driver.
|
||||
- Decision: Keep runtime validation and compatibility logic for external IDE DB (`ItemTable`).
|
||||
- Decision: Migrate in order: internal DB first, external DB second.
|
||||
|
||||
## Alternatives Considered
|
||||
- Continue with `better-sqlite3 + Zod`: limited type-safety gains and higher long-term maintenance cost.
|
||||
- Prisma: heavyweight footprint and higher Electron integration cost.
|
||||
|
||||
## Risks / Trade-offs
|
||||
- Packaging compatibility risk (Electron + native module ABI): requires cross-platform validation.
|
||||
- Temporary complexity increase while dual stacks coexist during migration.
|
||||
- Drizzle provides static typing only; runtime validation is still required to avoid dirty data.
|
||||
|
||||
## Migration Plan
|
||||
1. Define Drizzle schema (`accounts`/`settings`/`ItemTable`).
|
||||
2. Migrate `cloudHandler.ts` (internal DB).
|
||||
3. Migrate `database/handler.ts` (external IDE DB).
|
||||
4. Update unit tests and mocks.
|
||||
5. Run cross-platform smoke verification.
|
||||
|
||||
## Open Questions
|
||||
- Loose compatibility mode is confirmed; stronger runtime schema is not introduced for now.
|
||||
## Context
|
||||
Current SQLite access mainly relies on native `better-sqlite3` APIs, without unified typing and runtime validation strategy. This raises maintenance cost and regression risk. Introducing Drizzle ORM aims to improve type safety and maintainability while preserving existing behavior and compatibility.
|
||||
|
||||
## Goals / Non-Goals
|
||||
- Goals:
|
||||
- Provide structured schema and type inference
|
||||
- Unify DB access and validation patterns, reducing `any/as`
|
||||
- Preserve WAL, `busy_timeout`, transactions, and compatibility logic
|
||||
- Non-Goals:
|
||||
- Do not change existing database schema
|
||||
- Do not introduce a new database engine or remote storage
|
||||
|
||||
## Decisions
|
||||
- Decision: Adopt Drizzle ORM while keeping `better-sqlite3` as the driver.
|
||||
- Decision: Keep runtime validation and compatibility logic for external IDE DB (`ItemTable`).
|
||||
- Decision: Migrate in order: internal DB first, external DB second.
|
||||
|
||||
## Alternatives Considered
|
||||
- Continue with `better-sqlite3 + Zod`: limited type-safety gains and higher long-term maintenance cost.
|
||||
- Prisma: heavyweight footprint and higher Electron integration cost.
|
||||
|
||||
## Risks / Trade-offs
|
||||
- Packaging compatibility risk (Electron + native module ABI): requires cross-platform validation.
|
||||
- Temporary complexity increase while dual stacks coexist during migration.
|
||||
- Drizzle provides static typing only; runtime validation is still required to avoid dirty data.
|
||||
|
||||
## Migration Plan
|
||||
1. Define Drizzle schema (`accounts`/`settings`/`ItemTable`).
|
||||
2. Migrate `cloudHandler.ts` (internal DB).
|
||||
3. Migrate `database/handler.ts` (external IDE DB).
|
||||
4. Update unit tests and mocks.
|
||||
5. Run cross-platform smoke verification.
|
||||
|
||||
## Open Questions
|
||||
- Loose compatibility mode is confirmed; stronger runtime schema is not introduced for now.
|
||||
@@ -1,17 +1,17 @@
|
||||
# Change: Refactor SQLite Access with Drizzle ORM
|
||||
|
||||
## Why
|
||||
|
||||
Current `better-sqlite3` usage relies heavily on `any/as`, lacks unified typing and runtime validation, and increases long-term maintenance cost. Introducing Drizzle ORM provides structured schema definitions and more consistent type constraints.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Introduce Drizzle ORM and define schema for the internal database.
|
||||
- Incrementally migrate read/write paths in `cloudHandler` and `database/handler`.
|
||||
- Preserve existing WAL, `busy_timeout`, and transaction behavior to avoid regressions.
|
||||
- Keep runtime validation and compatibility logic for the external IDE DB (`ItemTable`).
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected code: `src/ipc/database/cloudHandler.ts`, `src/ipc/database/handler.ts`, tests, and DB utility layer
|
||||
- Affected behavior: data-access typing and runtime validation approach changes (regression validation required)
|
||||
# Change: Refactor SQLite Access with Drizzle ORM
|
||||
|
||||
## Why
|
||||
|
||||
Current `better-sqlite3` usage relies heavily on `any/as`, lacks unified typing and runtime validation, and increases long-term maintenance cost. Introducing Drizzle ORM provides structured schema definitions and more consistent type constraints.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Introduce Drizzle ORM and define schema for the internal database.
|
||||
- Incrementally migrate read/write paths in `cloudHandler` and `database/handler`.
|
||||
- Preserve existing WAL, `busy_timeout`, and transaction behavior to avoid regressions.
|
||||
- Keep runtime validation and compatibility logic for the external IDE DB (`ItemTable`).
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected code: `src/ipc/database/cloudHandler.ts`, `src/ipc/database/handler.ts`, tests, and DB utility layer
|
||||
- Affected behavior: data-access typing and runtime validation approach changes (regression validation required)
|
||||
@@ -1,21 +1,21 @@
|
||||
## ADDED Requirements
|
||||
### Requirement: Use Drizzle ORM for Internal Database
|
||||
The system SHALL use Drizzle ORM to access the internal database (`cloud_accounts.db`) and provide type constraints through schema.
|
||||
|
||||
#### Scenario: Read cloud account list
|
||||
- **WHEN** the system reads the `accounts` table
|
||||
- **THEN** returned data SHALL match Drizzle schema types
|
||||
|
||||
### Requirement: Keep Compatibility and Validation for External IDE Database
|
||||
The system SHALL preserve compatibility logic and runtime validation when accessing the external IDE database (`ItemTable`).
|
||||
|
||||
#### Scenario: Read ItemTable key
|
||||
- **WHEN** reading a specific key from `ItemTable`
|
||||
- **THEN** data that fails validation SHALL be logged as warning and skipped
|
||||
|
||||
### Requirement: Maintain Database Connection Stability
|
||||
The system SHALL preserve existing WAL, `busy_timeout`, and transaction strategies to avoid migration regressions.
|
||||
|
||||
#### Scenario: Transactional write consistency
|
||||
- **WHEN** executing write operations
|
||||
- **THEN** related updates SHALL be committed within the same transaction
|
||||
## ADDED Requirements
|
||||
### Requirement: Use Drizzle ORM for Internal Database
|
||||
The system SHALL use Drizzle ORM to access the internal database (`cloud_accounts.db`) and provide type constraints through schema.
|
||||
|
||||
#### Scenario: Read cloud account list
|
||||
- **WHEN** the system reads the `accounts` table
|
||||
- **THEN** returned data SHALL match Drizzle schema types
|
||||
|
||||
### Requirement: Keep Compatibility and Validation for External IDE Database
|
||||
The system SHALL preserve compatibility logic and runtime validation when accessing the external IDE database (`ItemTable`).
|
||||
|
||||
#### Scenario: Read ItemTable key
|
||||
- **WHEN** reading a specific key from `ItemTable`
|
||||
- **THEN** data that fails validation SHALL be logged as warning and skipped
|
||||
|
||||
### Requirement: Maintain Database Connection Stability
|
||||
The system SHALL preserve existing WAL, `busy_timeout`, and transaction strategies to avoid migration regressions.
|
||||
|
||||
#### Scenario: Transactional write consistency
|
||||
- **WHEN** executing write operations
|
||||
- **THEN** related updates SHALL be committed within the same transaction
|
||||
@@ -1,19 +1,19 @@
|
||||
## 1. Scope and Migration Confirmation
|
||||
- [x] 1.1 Confirm migration scope (internal DB vs external IDE DB).
|
||||
- [x] 1.2 Confirm Drizzle driver choice (keep `better-sqlite3`).
|
||||
- [x] 1.3 Confirm no changes to existing database schema.
|
||||
|
||||
## 2. Design and Preparation
|
||||
- [x] 2.1 Build Drizzle schema (`accounts`/`settings`/`ItemTable`).
|
||||
- [x] 2.2 Define connection initialization and pragma strategy (WAL, `busy_timeout`).
|
||||
- [x] 2.3 Define runtime validation strategy (external IDE DB, loose compatibility).
|
||||
|
||||
## 3. Implementation
|
||||
- [x] 3.1 Migrate read/write paths in `cloudHandler.ts`.
|
||||
- [x] 3.2 Migrate read/write paths in `database/handler.ts`.
|
||||
- [x] 3.3 Preserve existing transaction and retry semantics.
|
||||
|
||||
## 4. Testing and Verification
|
||||
- [x] 4.1 Update unit tests and mocks.
|
||||
- [ ] 4.2 Run regression checks for account backup/restore and injection flow.
|
||||
- [ ] 4.3 Complete cross-platform smoke verification (Win/macOS/Linux).
|
||||
## 1. Scope and Migration Confirmation
|
||||
- [x] 1.1 Confirm migration scope (internal DB vs external IDE DB).
|
||||
- [x] 1.2 Confirm Drizzle driver choice (keep `better-sqlite3`).
|
||||
- [x] 1.3 Confirm no changes to existing database schema.
|
||||
|
||||
## 2. Design and Preparation
|
||||
- [x] 2.1 Build Drizzle schema (`accounts`/`settings`/`ItemTable`).
|
||||
- [x] 2.2 Define connection initialization and pragma strategy (WAL, `busy_timeout`).
|
||||
- [x] 2.3 Define runtime validation strategy (external IDE DB, loose compatibility).
|
||||
|
||||
## 3. Implementation
|
||||
- [x] 3.1 Migrate read/write paths in `cloudHandler.ts`.
|
||||
- [x] 3.2 Migrate read/write paths in `database/handler.ts`.
|
||||
- [x] 3.3 Preserve existing transaction and retry semantics.
|
||||
|
||||
## 4. Testing and Verification
|
||||
- [x] 4.1 Update unit tests and mocks.
|
||||
- [ ] 4.2 Run regression checks for account backup/restore and injection flow.
|
||||
- [ ] 4.3 Complete cross-platform smoke verification (Win/macOS/Linux).
|
||||
@@ -1,33 +1,33 @@
|
||||
# Change: Support WSL Environment
|
||||
|
||||
## Summary
|
||||
|
||||
Enable Gemini Nexus running in WSL (Windows Subsystem for Linux) to manage the Gemini Nexus application installed on the Windows host.
|
||||
|
||||
## Motivation
|
||||
|
||||
Users running the manager in a WSL development environment need to interact with the actual Gemini Nexus instance running on Windows, as Gemini Nexus is a Windows application.
|
||||
|
||||
## Proposed Changes
|
||||
|
||||
### 1. Path Resolution (`src/utils/paths.ts`)
|
||||
|
||||
* Implement `isWsl()` utility function.
|
||||
* In `getAppDataDir()`: If WSL, return the Windows AppData path (e.g., `/mnt/c/Users/<User>/AppData/Roaming/GeminiNexus`).
|
||||
* In `getGeminiNexusExecutablePath()`: If WSL, return the Windows executable path (e.g., `/mnt/c/Users/<User>/AppData/Local/Programs/GeminiNexus/GeminiNexus.exe`).
|
||||
* **Challenge:** Determining the correct Windows username.
|
||||
* **Strategy:** Assume Windows username matches WSL username, or scan `/mnt/c/Users` for a likely candidate (excluding Public, Default, etc.).
|
||||
|
||||
### 2. Process Management (`src/ipc/process/handler.ts`)
|
||||
|
||||
* In `isProcessRunning()`: If WSL, execute `tasklist.exe` (via `/mnt/c/Windows/System32/tasklist.exe`) to check for `GeminiNexus.exe`.
|
||||
* In `startGeminiNexus()`: If WSL, execute the Windows executable directly.
|
||||
* In `closeGeminiNexus()`: If WSL, use `taskkill.exe` (via `/mnt/c/Windows/System32/taskkill.exe`).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
* \[ ] Application detects it is running in WSL.
|
||||
* \[ ] Database file is correctly located on the Windows file system.
|
||||
* \[ ] "Start" button successfully launches Gemini Nexus on Windows.
|
||||
* \[ ] "Stop" button successfully terminates Gemini Nexus on Windows.
|
||||
* \[ ] Process status (Running/Stopped) is correctly reflected in the UI.
|
||||
# Change: Support WSL Environment
|
||||
|
||||
## Summary
|
||||
|
||||
Enable Gemini Nexus running in WSL (Windows Subsystem for Linux) to manage the Gemini Nexus application installed on the Windows host.
|
||||
|
||||
## Motivation
|
||||
|
||||
Users running the manager in a WSL development environment need to interact with the actual Gemini Nexus instance running on Windows, as Gemini Nexus is a Windows application.
|
||||
|
||||
## Proposed Changes
|
||||
|
||||
### 1. Path Resolution (`src/utils/paths.ts`)
|
||||
|
||||
* Implement `isWsl()` utility function.
|
||||
* In `getAppDataDir()`: If WSL, return the Windows AppData path (e.g., `/mnt/c/Users/<User>/AppData/Roaming/GeminiNexus`).
|
||||
* In `getGeminiNexusExecutablePath()`: If WSL, return the Windows executable path (e.g., `/mnt/c/Users/<User>/AppData/Local/Programs/GeminiNexus/GeminiNexus.exe`).
|
||||
* **Challenge:** Determining the correct Windows username.
|
||||
* **Strategy:** Assume Windows username matches WSL username, or scan `/mnt/c/Users` for a likely candidate (excluding Public, Default, etc.).
|
||||
|
||||
### 2. Process Management (`src/ipc/process/handler.ts`)
|
||||
|
||||
* In `isProcessRunning()`: If WSL, execute `tasklist.exe` (via `/mnt/c/Windows/System32/tasklist.exe`) to check for `GeminiNexus.exe`.
|
||||
* In `startGeminiNexus()`: If WSL, execute the Windows executable directly.
|
||||
* In `closeGeminiNexus()`: If WSL, use `taskkill.exe` (via `/mnt/c/Windows/System32/taskkill.exe`).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
* \[ ] Application detects it is running in WSL.
|
||||
* \[ ] Database file is correctly located on the Windows file system.
|
||||
* \[ ] "Start" button successfully launches Gemini Nexus on Windows.
|
||||
* \[ ] "Stop" button successfully terminates Gemini Nexus on Windows.
|
||||
* \[ ] Process status (Running/Stopped) is correctly reflected in the UI.
|
||||
@@ -1,5 +1,5 @@
|
||||
# Tasks: Support WSL Environment
|
||||
|
||||
* \[ ] Update `src/utils/paths.ts` to implement `isWsl` and handle Windows paths. <!-- id: update-paths -->
|
||||
* \[ ] Update `src/ipc/process/handler.ts` to support `tasklist.exe` and `taskkill.exe` in WSL. <!-- id: update-process-handler -->
|
||||
* \[ ] Verify database connection and process management in WSL. <!-- id: verify-wsl -->
|
||||
# Tasks: Support WSL Environment
|
||||
|
||||
* \[ ] Update `src/utils/paths.ts` to implement `isWsl` and handle Windows paths. <!-- id: update-paths -->
|
||||
* \[ ] Update `src/ipc/process/handler.ts` to support `tasklist.exe` and `taskkill.exe` in WSL. <!-- id: update-process-handler -->
|
||||
* \[ ] Verify database connection and process management in WSL. <!-- id: verify-wsl -->
|
||||
@@ -1,40 +1,40 @@
|
||||
# Device Fingerprint Capability Acceptance Checklist
|
||||
|
||||
## Backend Capabilities
|
||||
|
||||
- `get_storage_path / get_storage_dir / get_state_db_path`
|
||||
- `read_profile / write_profile`
|
||||
- `generate_profile`
|
||||
- `sync_service_machine_id / sync_service_machine_id_from_storage`
|
||||
- `load_global_original / save_global_original`
|
||||
- `get_device_profiles`
|
||||
- `bind_device_profile / bind_device_profile_with_profile`
|
||||
- `restore_device_version / delete_device_version`
|
||||
- `restore_original_device`
|
||||
- `open_device_folder`
|
||||
|
||||
## UI Capabilities
|
||||
|
||||
- Show current storage / account binding / history / baseline
|
||||
- Generate and bind
|
||||
- Capture and bind
|
||||
- Restore original fingerprint
|
||||
- Restore history revision
|
||||
- Delete history revision
|
||||
- Open storage folder
|
||||
|
||||
## Switching Behavior
|
||||
|
||||
- Local account switching applies bound fingerprint
|
||||
- Cloud account switching applies bound fingerprint
|
||||
- Concurrent switch requests use queued serial semantics
|
||||
- Failure semantics are fail-fast (no extra transaction orchestration)
|
||||
|
||||
## Compatibility Scope
|
||||
|
||||
- Legacy data missing optional fields: fill defaults
|
||||
- Corrupted structure/type mismatch: explicit failure
|
||||
|
||||
## Status Marking
|
||||
|
||||
Please mark each item as: `Passed / Failed / Diverged (with reason)`.
|
||||
# Device Fingerprint Capability Acceptance Checklist
|
||||
|
||||
## Backend Capabilities
|
||||
|
||||
- `get_storage_path / get_storage_dir / get_state_db_path`
|
||||
- `read_profile / write_profile`
|
||||
- `generate_profile`
|
||||
- `sync_service_machine_id / sync_service_machine_id_from_storage`
|
||||
- `load_global_original / save_global_original`
|
||||
- `get_device_profiles`
|
||||
- `bind_device_profile / bind_device_profile_with_profile`
|
||||
- `restore_device_version / delete_device_version`
|
||||
- `restore_original_device`
|
||||
- `open_device_folder`
|
||||
|
||||
## UI Capabilities
|
||||
|
||||
- Show current storage / account binding / history / baseline
|
||||
- Generate and bind
|
||||
- Capture and bind
|
||||
- Restore original fingerprint
|
||||
- Restore history revision
|
||||
- Delete history revision
|
||||
- Open storage folder
|
||||
|
||||
## Switching Behavior
|
||||
|
||||
- Local account switching applies bound fingerprint
|
||||
- Cloud account switching applies bound fingerprint
|
||||
- Concurrent switch requests use queued serial semantics
|
||||
- Failure semantics are fail-fast (no extra transaction orchestration)
|
||||
|
||||
## Compatibility Scope
|
||||
|
||||
- Legacy data missing optional fields: fill defaults
|
||||
- Corrupted structure/type mismatch: explicit failure
|
||||
|
||||
## Status Marking
|
||||
|
||||
Please mark each item as: `Passed / Failed / Diverged (with reason)`.
|
||||
@@ -1,50 +1,50 @@
|
||||
## Context
|
||||
|
||||
Device-fingerprint capability spans the data layer, switch-orchestration layer, and UI management layer.
|
||||
Historical proposals split the same capability across multiple change IDs, which fragmented implementation and acceptance criteria.
|
||||
This design combines "feature completeness + robustness" into a single constraint set to keep implementation, verification, and release aligned.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
- Goals:
|
||||
- Unify scope and acceptance criteria for device-fingerprint capability.
|
||||
- Ensure behavioral consistency and diagnosability for local/cloud switching.
|
||||
- Keep consistent behavior on default paths across Windows/macOS/Linux.
|
||||
- Keep legacy-data compatibility predictable and verifiable.
|
||||
- Non-Goals:
|
||||
- Support for non-default runtime configuration paths.
|
||||
- Business strategy expansion unrelated to this capability.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Decision: Use a single change ID to manage the complete capability.
|
||||
- Rationale: Reduce governance overhead caused by duplicate proposals.
|
||||
- Decision: Apply fingerprint using a two-phase flow with strict pre-commit verification.
|
||||
- Rationale: Reduce mixed-state risk caused by partial success.
|
||||
- Decision: Use versioned payload + boundary validation for fingerprint/history data.
|
||||
- Rationale: Avoid silent data contamination and define clear compatibility/failure boundaries.
|
||||
- Decision: Use fail-fast semantics for switch failures and return structured failure reasons.
|
||||
- Rationale: Make failure behavior predictable and observable.
|
||||
- Decision: Trigger safe mode for temporary degradation after consecutive failures.
|
||||
- Rationale: Keep switching flow available during fault windows.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Risk: Stricter validation may reject legacy dirty data.
|
||||
- Mitigation: Normalize missing optional fields; fail-fast only for critical structure errors.
|
||||
- Risk: Validation and diagnostic extensions add minor performance cost.
|
||||
- Mitigation: Keep validation lightweight and limited to critical boundaries.
|
||||
- Risk: More UI management actions may increase user misoperations.
|
||||
- Mitigation: Add confirmation interactions and unit-test coverage for failure branches.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Use `update-device-fingerprint-hardening` as the single active proposal.
|
||||
2. Merge historical duplicate proposal content into this proposal (`proposal`/`design`/`tasks`/`spec`).
|
||||
3. Close and remove duplicate proposal directories.
|
||||
4. Deliver with unified task checklist and acceptance checklist.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should safe mode exit only by time window, or also allow manual recovery?
|
||||
- Should diagnostic snapshots be exposed in the renderer as a visual panel?
|
||||
## Context
|
||||
|
||||
Device-fingerprint capability spans the data layer, switch-orchestration layer, and UI management layer.
|
||||
Historical proposals split the same capability across multiple change IDs, which fragmented implementation and acceptance criteria.
|
||||
This design combines "feature completeness + robustness" into a single constraint set to keep implementation, verification, and release aligned.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
- Goals:
|
||||
- Unify scope and acceptance criteria for device-fingerprint capability.
|
||||
- Ensure behavioral consistency and diagnosability for local/cloud switching.
|
||||
- Keep consistent behavior on default paths across Windows/macOS/Linux.
|
||||
- Keep legacy-data compatibility predictable and verifiable.
|
||||
- Non-Goals:
|
||||
- Support for non-default runtime configuration paths.
|
||||
- Business strategy expansion unrelated to this capability.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Decision: Use a single change ID to manage the complete capability.
|
||||
- Rationale: Reduce governance overhead caused by duplicate proposals.
|
||||
- Decision: Apply fingerprint using a two-phase flow with strict pre-commit verification.
|
||||
- Rationale: Reduce mixed-state risk caused by partial success.
|
||||
- Decision: Use versioned payload + boundary validation for fingerprint/history data.
|
||||
- Rationale: Avoid silent data contamination and define clear compatibility/failure boundaries.
|
||||
- Decision: Use fail-fast semantics for switch failures and return structured failure reasons.
|
||||
- Rationale: Make failure behavior predictable and observable.
|
||||
- Decision: Trigger safe mode for temporary degradation after consecutive failures.
|
||||
- Rationale: Keep switching flow available during fault windows.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Risk: Stricter validation may reject legacy dirty data.
|
||||
- Mitigation: Normalize missing optional fields; fail-fast only for critical structure errors.
|
||||
- Risk: Validation and diagnostic extensions add minor performance cost.
|
||||
- Mitigation: Keep validation lightweight and limited to critical boundaries.
|
||||
- Risk: More UI management actions may increase user misoperations.
|
||||
- Mitigation: Add confirmation interactions and unit-test coverage for failure branches.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Use `update-device-fingerprint-hardening` as the single active proposal.
|
||||
2. Merge historical duplicate proposal content into this proposal (`proposal`/`design`/`tasks`/`spec`).
|
||||
3. Close and remove duplicate proposal directories.
|
||||
4. Deliver with unified task checklist and acceptance checklist.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should safe mode exit only by time window, or also allow manual recovery?
|
||||
- Should diagnostic snapshots be exposed in the renderer as a visual panel?
|
||||
@@ -1,39 +1,39 @@
|
||||
# Change: Device Fingerprint Consolidation and Hardening
|
||||
|
||||
## What Changes
|
||||
|
||||
- Unify backend scope:
|
||||
- Fingerprint read/write with synchronized updates to `storage.json` and `state.vscdb`
|
||||
- Account-level binding, revision history, and baseline restore
|
||||
- Fingerprint apply orchestration during switch flows (local/cloud)
|
||||
- Unify management scope:
|
||||
- Device fingerprint management dialog
|
||||
- Generate-and-bind, capture-and-bind, restore revision, delete revision, restore baseline, and open storage folder
|
||||
- Unify robustness scope:
|
||||
- Two-phase apply (`prepare -> verify -> commit`)
|
||||
- Deterministic rollback before commit on failure
|
||||
- Failure reason classification, safe mode, degradation strategy, and diagnostics snapshots
|
||||
- Versioned payload with boundary validation (lenient compatibility + strict failure for critical structure)
|
||||
- Path scope: this stage focuses on the default runtime configuration path.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not promise any anti-detection, anti-ban, or risk-control bypass outcome.
|
||||
- Do not introduce token/protobuf semantic changes unrelated to device fingerprinting.
|
||||
- Do not perform ORM or large database refactors in this change.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `device-fingerprint-hardening`
|
||||
- Affected code:
|
||||
- `src/ipc/device/handler.ts`
|
||||
- `src/ipc/account/handler.ts`
|
||||
- `src/ipc/cloud/handler.ts`
|
||||
- `src/ipc/switchFlow.ts`
|
||||
- `src/ipc/switchMetrics.ts`
|
||||
- `src/ipc/database/cloudHandler.ts`
|
||||
- `src/components/DeviceFingerprintDialog.tsx`
|
||||
- `src/actions/account.ts`
|
||||
- `src/actions/cloud.ts`
|
||||
- `src/tests/unit/account.test.ts`
|
||||
- `src/tests/unit/cloudHandler-sync.test.ts`
|
||||
# Change: Device Fingerprint Consolidation and Hardening
|
||||
|
||||
## What Changes
|
||||
|
||||
- Unify backend scope:
|
||||
- Fingerprint read/write with synchronized updates to `storage.json` and `state.vscdb`
|
||||
- Account-level binding, revision history, and baseline restore
|
||||
- Fingerprint apply orchestration during switch flows (local/cloud)
|
||||
- Unify management scope:
|
||||
- Device fingerprint management dialog
|
||||
- Generate-and-bind, capture-and-bind, restore revision, delete revision, restore baseline, and open storage folder
|
||||
- Unify robustness scope:
|
||||
- Two-phase apply (`prepare -> verify -> commit`)
|
||||
- Deterministic rollback before commit on failure
|
||||
- Failure reason classification, safe mode, degradation strategy, and diagnostics snapshots
|
||||
- Versioned payload with boundary validation (lenient compatibility + strict failure for critical structure)
|
||||
- Path scope: this stage focuses on the default runtime configuration path.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not promise any anti-detection, anti-ban, or risk-control bypass outcome.
|
||||
- Do not introduce token/protobuf semantic changes unrelated to device fingerprinting.
|
||||
- Do not perform ORM or large database refactors in this change.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `device-fingerprint-hardening`
|
||||
- Affected code:
|
||||
- `src/ipc/device/handler.ts`
|
||||
- `src/ipc/account/handler.ts`
|
||||
- `src/ipc/cloud/handler.ts`
|
||||
- `src/ipc/switchFlow.ts`
|
||||
- `src/ipc/switchMetrics.ts`
|
||||
- `src/ipc/database/cloudHandler.ts`
|
||||
- `src/components/DeviceFingerprintDialog.tsx`
|
||||
- `src/actions/account.ts`
|
||||
- `src/actions/cloud.ts`
|
||||
- `src/tests/unit/account.test.ts`
|
||||
- `src/tests/unit/cloudHandler-sync.test.ts`
|
||||
+109
-109
@@ -1,109 +1,109 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Complete Device Fingerprint Management Capability
|
||||
|
||||
The system SHALL provide complete device-fingerprint management capability: view current storage fingerprint, account-bound fingerprint, history revisions, and baseline fingerprint, and execute generate/capture/bind/restore/delete operations.
|
||||
|
||||
#### Scenario: Open device fingerprint management
|
||||
|
||||
- **WHEN** an operator opens device fingerprint management for a specific account
|
||||
- **THEN** the system returns current storage fingerprint, account-bound fingerprint, history revisions, and baseline fingerprint (if present)
|
||||
|
||||
#### Scenario: Generate and bind a new fingerprint
|
||||
|
||||
- **WHEN** the operator confirms "Generate and Bind"
|
||||
- **THEN** the system generates a valid new fingerprint and binds it to the target account
|
||||
- **AND** the new revision is appended to history and marked as current
|
||||
|
||||
#### Scenario: Capture current and bind
|
||||
|
||||
- **WHEN** the operator confirms "Capture Current and Bind"
|
||||
- **THEN** the system reads the current storage fingerprint and binds it to the target account
|
||||
- **AND** a new revision is appended to history
|
||||
|
||||
### Requirement: Switch Flow Must Apply Account-Bound Fingerprint
|
||||
|
||||
The system SHALL ensure the target account has a valid bound fingerprint before continuing switch flow for both local-account and cloud-account switching.
|
||||
|
||||
#### Scenario: Target account has no bound fingerprint during switching
|
||||
|
||||
- **GIVEN** the target account exists and has no bound fingerprint
|
||||
- **WHEN** account switching is initiated
|
||||
- **THEN** the system automatically generates and binds a usable fingerprint
|
||||
- **AND** then continues with the switch flow
|
||||
|
||||
#### Scenario: Concurrent switch requests
|
||||
|
||||
- **WHEN** multiple switch requests are triggered while a switch is in progress
|
||||
- **THEN** requests are queued and processed serially
|
||||
- **AND** no concurrent write conflicts occur
|
||||
|
||||
### Requirement: Fingerprint Apply Must Preserve Storage Consistency
|
||||
|
||||
The system SHALL update `storage.json` and `state.vscdb` in sync when applying device fingerprint, and SHALL ensure `storage.serviceMachineId` equals `devDeviceId`.
|
||||
|
||||
#### Scenario: Normal fingerprint apply
|
||||
|
||||
- **WHEN** the system applies a device fingerprint
|
||||
- **THEN** telemetry fields in `storage.json` are updated
|
||||
- **AND** `storage.serviceMachineId` is updated to `devDeviceId`
|
||||
- **AND** `ItemTable['storage.serviceMachineId']` in `state.vscdb` is updated accordingly
|
||||
|
||||
### Requirement: Device Fingerprint Apply Uses Two-Phase Protocol
|
||||
|
||||
The system SHALL execute device-fingerprint apply with a two-phase protocol (`prepare -> verify -> commit`), and SHALL perform deterministic rollback when failure occurs before commit.
|
||||
|
||||
#### Scenario: Failure during verify phase
|
||||
|
||||
- **WHEN** prepare writes succeed but verify detects inconsistent state
|
||||
- **THEN** the system rolls back to pre-apply state
|
||||
- **AND** returns a classifiable failure reason
|
||||
|
||||
#### Scenario: Write failure before commit
|
||||
|
||||
- **WHEN** any critical write fails before commit completes
|
||||
- **THEN** the system performs rollback
|
||||
- **AND** post-operation state equals pre-operation state
|
||||
|
||||
### Requirement: Fingerprint Data Uses Versioned Structure and Boundary Validation
|
||||
|
||||
The system SHALL use explicit schema versions for fingerprint and history data, and SHALL validate at read/write boundaries.
|
||||
|
||||
#### Scenario: Missing optional fields
|
||||
|
||||
- **WHEN** history payload lacks optional fields
|
||||
- **THEN** the system fills default values and continues
|
||||
|
||||
#### Scenario: Critical structure corruption or type mismatch
|
||||
|
||||
- **WHEN** payload has critical structure corruption or critical field type mismatch
|
||||
- **THEN** the system fails fast and returns a readable error
|
||||
|
||||
### Requirement: Consecutive Failures Trigger Safe Degradation
|
||||
|
||||
The system SHALL enter safe mode when consecutive device-fingerprint apply failures reach a threshold, temporarily disable fingerprint apply, keep switching available, and emit warnings.
|
||||
|
||||
#### Scenario: Consecutive-failure threshold reached
|
||||
|
||||
- **WHEN** consecutive failures reach the threshold
|
||||
- **THEN** safe mode is activated and fingerprint apply is temporarily disabled
|
||||
- **AND** switch flow remains available under warning conditions
|
||||
|
||||
### Requirement: Provide Observable Diagnostic Snapshot
|
||||
|
||||
The system SHALL expose a read-only diagnostics interface returning switch-guard state, switch counters, failure-reason counters, latest failure metadata, and safe-mode state.
|
||||
|
||||
#### Scenario: Query diagnostics after failures
|
||||
|
||||
- **WHEN** diagnostics are queried after one or more failures
|
||||
- **THEN** reason-classified failure counters are returned
|
||||
- **AND** latest failure details and safe-mode state are returned
|
||||
|
||||
### Requirement: Path Resolution Scope Constraint
|
||||
|
||||
The system SHALL use default runtime configuration paths for path resolution in this capability.
|
||||
|
||||
#### Scenario: Use default runtime configuration paths
|
||||
|
||||
- **WHEN** the system performs device-fingerprint-related path resolution
|
||||
- **THEN** resolution is completed based on default runtime configuration paths
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Complete Device Fingerprint Management Capability
|
||||
|
||||
The system SHALL provide complete device-fingerprint management capability: view current storage fingerprint, account-bound fingerprint, history revisions, and baseline fingerprint, and execute generate/capture/bind/restore/delete operations.
|
||||
|
||||
#### Scenario: Open device fingerprint management
|
||||
|
||||
- **WHEN** an operator opens device fingerprint management for a specific account
|
||||
- **THEN** the system returns current storage fingerprint, account-bound fingerprint, history revisions, and baseline fingerprint (if present)
|
||||
|
||||
#### Scenario: Generate and bind a new fingerprint
|
||||
|
||||
- **WHEN** the operator confirms "Generate and Bind"
|
||||
- **THEN** the system generates a valid new fingerprint and binds it to the target account
|
||||
- **AND** the new revision is appended to history and marked as current
|
||||
|
||||
#### Scenario: Capture current and bind
|
||||
|
||||
- **WHEN** the operator confirms "Capture Current and Bind"
|
||||
- **THEN** the system reads the current storage fingerprint and binds it to the target account
|
||||
- **AND** a new revision is appended to history
|
||||
|
||||
### Requirement: Switch Flow Must Apply Account-Bound Fingerprint
|
||||
|
||||
The system SHALL ensure the target account has a valid bound fingerprint before continuing switch flow for both local-account and cloud-account switching.
|
||||
|
||||
#### Scenario: Target account has no bound fingerprint during switching
|
||||
|
||||
- **GIVEN** the target account exists and has no bound fingerprint
|
||||
- **WHEN** account switching is initiated
|
||||
- **THEN** the system automatically generates and binds a usable fingerprint
|
||||
- **AND** then continues with the switch flow
|
||||
|
||||
#### Scenario: Concurrent switch requests
|
||||
|
||||
- **WHEN** multiple switch requests are triggered while a switch is in progress
|
||||
- **THEN** requests are queued and processed serially
|
||||
- **AND** no concurrent write conflicts occur
|
||||
|
||||
### Requirement: Fingerprint Apply Must Preserve Storage Consistency
|
||||
|
||||
The system SHALL update `storage.json` and `state.vscdb` in sync when applying device fingerprint, and SHALL ensure `storage.serviceMachineId` equals `devDeviceId`.
|
||||
|
||||
#### Scenario: Normal fingerprint apply
|
||||
|
||||
- **WHEN** the system applies a device fingerprint
|
||||
- **THEN** telemetry fields in `storage.json` are updated
|
||||
- **AND** `storage.serviceMachineId` is updated to `devDeviceId`
|
||||
- **AND** `ItemTable['storage.serviceMachineId']` in `state.vscdb` is updated accordingly
|
||||
|
||||
### Requirement: Device Fingerprint Apply Uses Two-Phase Protocol
|
||||
|
||||
The system SHALL execute device-fingerprint apply with a two-phase protocol (`prepare -> verify -> commit`), and SHALL perform deterministic rollback when failure occurs before commit.
|
||||
|
||||
#### Scenario: Failure during verify phase
|
||||
|
||||
- **WHEN** prepare writes succeed but verify detects inconsistent state
|
||||
- **THEN** the system rolls back to pre-apply state
|
||||
- **AND** returns a classifiable failure reason
|
||||
|
||||
#### Scenario: Write failure before commit
|
||||
|
||||
- **WHEN** any critical write fails before commit completes
|
||||
- **THEN** the system performs rollback
|
||||
- **AND** post-operation state equals pre-operation state
|
||||
|
||||
### Requirement: Fingerprint Data Uses Versioned Structure and Boundary Validation
|
||||
|
||||
The system SHALL use explicit schema versions for fingerprint and history data, and SHALL validate at read/write boundaries.
|
||||
|
||||
#### Scenario: Missing optional fields
|
||||
|
||||
- **WHEN** history payload lacks optional fields
|
||||
- **THEN** the system fills default values and continues
|
||||
|
||||
#### Scenario: Critical structure corruption or type mismatch
|
||||
|
||||
- **WHEN** payload has critical structure corruption or critical field type mismatch
|
||||
- **THEN** the system fails fast and returns a readable error
|
||||
|
||||
### Requirement: Consecutive Failures Trigger Safe Degradation
|
||||
|
||||
The system SHALL enter safe mode when consecutive device-fingerprint apply failures reach a threshold, temporarily disable fingerprint apply, keep switching available, and emit warnings.
|
||||
|
||||
#### Scenario: Consecutive-failure threshold reached
|
||||
|
||||
- **WHEN** consecutive failures reach the threshold
|
||||
- **THEN** safe mode is activated and fingerprint apply is temporarily disabled
|
||||
- **AND** switch flow remains available under warning conditions
|
||||
|
||||
### Requirement: Provide Observable Diagnostic Snapshot
|
||||
|
||||
The system SHALL expose a read-only diagnostics interface returning switch-guard state, switch counters, failure-reason counters, latest failure metadata, and safe-mode state.
|
||||
|
||||
#### Scenario: Query diagnostics after failures
|
||||
|
||||
- **WHEN** diagnostics are queried after one or more failures
|
||||
- **THEN** reason-classified failure counters are returned
|
||||
- **AND** latest failure details and safe-mode state are returned
|
||||
|
||||
### Requirement: Path Resolution Scope Constraint
|
||||
|
||||
The system SHALL use default runtime configuration paths for path resolution in this capability.
|
||||
|
||||
#### Scenario: Use default runtime configuration paths
|
||||
|
||||
- **WHEN** the system performs device-fingerprint-related path resolution
|
||||
- **THEN** resolution is completed based on default runtime configuration paths
|
||||
@@ -1,44 +1,44 @@
|
||||
## 1. Proposal Consolidation
|
||||
|
||||
- [x] 1.1 Merge duplicate device-fingerprint proposals into `update-device-fingerprint-hardening`.
|
||||
- [x] 1.2 Unify scope and terminology across proposal/design/spec.
|
||||
- [ ] 1.3 Complete proposal archival strategy (archive after release).
|
||||
|
||||
## 2. Feature Completeness (Backend)
|
||||
|
||||
- [x] 2.1 Provide APIs for querying/binding/restoring/deleting fingerprint history.
|
||||
- [x] 2.2 Provide API to restore original device fingerprint.
|
||||
- [x] 2.3 Provide API to open fingerprint storage folder.
|
||||
- [x] 2.4 Reuse unified fingerprint-apply chain for local and cloud switching.
|
||||
|
||||
## 3. Feature Completeness (UI)
|
||||
|
||||
- [x] 3.1 Provide management entry via `DeviceFingerprintDialog`.
|
||||
- [x] 3.2 Support generate-and-bind, capture-and-bind, restore history, and delete history.
|
||||
- [x] 3.3 Support restore original fingerprint and open storage folder.
|
||||
- [x] 3.4 Complete i18n copy and error messaging.
|
||||
|
||||
## 4. Robustness Hardening
|
||||
|
||||
- [x] 4.1 Implement two-phase apply in `src/ipc/device/handler.ts` (`prepare -> verify -> commit`).
|
||||
- [x] 4.2 Perform deterministic rollback on pre-commit failure.
|
||||
- [x] 4.3 Introduce failure-reason classification and integrate with `src/ipc/switchMetrics.ts`.
|
||||
- [x] 4.4 Introduce versioned payload and strict boundary validation.
|
||||
- [x] 4.5 Introduce safe mode and recovery strategy.
|
||||
- [x] 4.6 Extend diagnostics snapshot (failure-reason counts, latest failure metadata, safe-mode status).
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Run `npm run type-check`.
|
||||
- [x] 5.2 Run targeted unit tests:
|
||||
- `npm run test:unit src/tests/unit/account.test.ts`
|
||||
- `npm run test:unit src/tests/unit/cloudHandler-sync.test.ts`
|
||||
- [ ] 5.3 Add/extend rollback invariant unit tests.
|
||||
- [ ] 5.4 Add/extend abnormal history-data behavior unit tests.
|
||||
- [ ] 5.5 Add/extend unit tests for platform-constrained generation rules.
|
||||
- [ ] 5.6 Complete manual acceptance matrix across Windows/macOS/Linux.
|
||||
|
||||
## 6. Delivery Documentation
|
||||
|
||||
- [ ] 6.1 Produce a unified acceptance checklist and mark status item by item.
|
||||
- [ ] 6.2 Archive merged proposals after release.
|
||||
## 1. Proposal Consolidation
|
||||
|
||||
- [x] 1.1 Merge duplicate device-fingerprint proposals into `update-device-fingerprint-hardening`.
|
||||
- [x] 1.2 Unify scope and terminology across proposal/design/spec.
|
||||
- [ ] 1.3 Complete proposal archival strategy (archive after release).
|
||||
|
||||
## 2. Feature Completeness (Backend)
|
||||
|
||||
- [x] 2.1 Provide APIs for querying/binding/restoring/deleting fingerprint history.
|
||||
- [x] 2.2 Provide API to restore original device fingerprint.
|
||||
- [x] 2.3 Provide API to open fingerprint storage folder.
|
||||
- [x] 2.4 Reuse unified fingerprint-apply chain for local and cloud switching.
|
||||
|
||||
## 3. Feature Completeness (UI)
|
||||
|
||||
- [x] 3.1 Provide management entry via `DeviceFingerprintDialog`.
|
||||
- [x] 3.2 Support generate-and-bind, capture-and-bind, restore history, and delete history.
|
||||
- [x] 3.3 Support restore original fingerprint and open storage folder.
|
||||
- [x] 3.4 Complete i18n copy and error messaging.
|
||||
|
||||
## 4. Robustness Hardening
|
||||
|
||||
- [x] 4.1 Implement two-phase apply in `src/ipc/device/handler.ts` (`prepare -> verify -> commit`).
|
||||
- [x] 4.2 Perform deterministic rollback on pre-commit failure.
|
||||
- [x] 4.3 Introduce failure-reason classification and integrate with `src/ipc/switchMetrics.ts`.
|
||||
- [x] 4.4 Introduce versioned payload and strict boundary validation.
|
||||
- [x] 4.5 Introduce safe mode and recovery strategy.
|
||||
- [x] 4.6 Extend diagnostics snapshot (failure-reason counts, latest failure metadata, safe-mode status).
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Run `npm run type-check`.
|
||||
- [x] 5.2 Run targeted unit tests:
|
||||
- `npm run test:unit src/tests/unit/account.test.ts`
|
||||
- `npm run test:unit src/tests/unit/cloudHandler-sync.test.ts`
|
||||
- [ ] 5.3 Add/extend rollback invariant unit tests.
|
||||
- [ ] 5.4 Add/extend abnormal history-data behavior unit tests.
|
||||
- [ ] 5.5 Add/extend unit tests for platform-constrained generation rules.
|
||||
- [ ] 5.6 Complete manual acceptance matrix across Windows/macOS/Linux.
|
||||
|
||||
## 6. Delivery Documentation
|
||||
|
||||
- [ ] 6.1 Produce a unified acceptance checklist and mark status item by item.
|
||||
- [ ] 6.2 Archive merged proposals after release.
|
||||
@@ -1,38 +1,38 @@
|
||||
## Context
|
||||
|
||||
- The target IDE changed account OAuth token persistence format starting from version 1.16.5.
|
||||
- Existing JS logic only covers the legacy format, causing account detection and switching failures.
|
||||
- Version detection, new/legacy routing, and dual-write fallback need to be completed.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
- Goals:
|
||||
- Ensure compatibility for versions 1.16.5+.
|
||||
- Apply dual-format injection fallback when version detection fails.
|
||||
- Extend backup/restore coverage to include new-format keys.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Decision: Write a single format when version detection succeeds; dual-write when detection fails.
|
||||
- Decision: Prefer reading the new format for account detection, with legacy fallback.
|
||||
- Decision: Keep protobuf encode/decode behavior and field ordering consistent.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Risk: Protobuf encode/decode mismatch may cause injection failure.
|
||||
- Mitigation: Per-field validation and regression test coverage.
|
||||
- Risk: Version detection failure.
|
||||
- Mitigation: Dual-write fallback.
|
||||
- Risk: DB lock conflicts.
|
||||
- Mitigation: Keep existing flow: close IDE -> backup -> inject -> restart.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Implement version-detection module (JS).
|
||||
2. Implement protobuf encode/decode for new format.
|
||||
3. Implement routed injection/detection logic with dual-write fallback.
|
||||
4. Extend backup/restore key set.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None.
|
||||
## Context
|
||||
|
||||
- The target IDE changed account OAuth token persistence format starting from version 1.16.5.
|
||||
- Existing JS logic only covers the legacy format, causing account detection and switching failures.
|
||||
- Version detection, new/legacy routing, and dual-write fallback need to be completed.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
- Goals:
|
||||
- Ensure compatibility for versions 1.16.5+.
|
||||
- Apply dual-format injection fallback when version detection fails.
|
||||
- Extend backup/restore coverage to include new-format keys.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Decision: Write a single format when version detection succeeds; dual-write when detection fails.
|
||||
- Decision: Prefer reading the new format for account detection, with legacy fallback.
|
||||
- Decision: Keep protobuf encode/decode behavior and field ordering consistent.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Risk: Protobuf encode/decode mismatch may cause injection failure.
|
||||
- Mitigation: Per-field validation and regression test coverage.
|
||||
- Risk: Version detection failure.
|
||||
- Mitigation: Dual-write fallback.
|
||||
- Risk: DB lock conflicts.
|
||||
- Mitigation: Keep existing flow: close IDE -> backup -> inject -> restart.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Implement version-detection module (JS).
|
||||
2. Implement protobuf encode/decode for new format.
|
||||
3. Implement routed injection/detection logic with dual-write fallback.
|
||||
4. Extend backup/restore key set.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None.
|
||||
@@ -1,34 +1,34 @@
|
||||
# Change: IDE Auth Compatibility Fix for 1.16.5+
|
||||
|
||||
## Why
|
||||
|
||||
- The target IDE changed OAuth token persistence format starting from 1.16.5.
|
||||
- The current JS implementation only supports the legacy format, causing account detection and switching failures.
|
||||
- The verified behavior needs to be fully migrated into the current code path to reduce regression risk.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add IDE version detection and route injection by legacy/new format.
|
||||
- Support encoding/decoding and account detection for the new OAuth token format.
|
||||
- Apply dual-write fallback (legacy + new) when version detection fails.
|
||||
- Extend backup/restore logic to include new-format keys.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep existing behavior semantics; do not introduce new strategy layers or business fields.
|
||||
- This stage only covers the default runtime configuration path.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `ide-auth-compat`
|
||||
- Affected code:
|
||||
- `src/ipc/database/cloudHandler.ts`
|
||||
- `src/utils/protobuf.ts`
|
||||
- `src/ipc/database/handler.ts`
|
||||
- `src/utils/paths.ts`
|
||||
|
||||
## Risks
|
||||
|
||||
- Protobuf encoding/decoding mismatch may break injection or parsing.
|
||||
- Version detection failure may route to the wrong injection path.
|
||||
- DB lock conflicts during injection may cause write failures.
|
||||
# Change: IDE Auth Compatibility Fix for 1.16.5+
|
||||
|
||||
## Why
|
||||
|
||||
- The target IDE changed OAuth token persistence format starting from 1.16.5.
|
||||
- The current JS implementation only supports the legacy format, causing account detection and switching failures.
|
||||
- The verified behavior needs to be fully migrated into the current code path to reduce regression risk.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add IDE version detection and route injection by legacy/new format.
|
||||
- Support encoding/decoding and account detection for the new OAuth token format.
|
||||
- Apply dual-write fallback (legacy + new) when version detection fails.
|
||||
- Extend backup/restore logic to include new-format keys.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep existing behavior semantics; do not introduce new strategy layers or business fields.
|
||||
- This stage only covers the default runtime configuration path.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `ide-auth-compat`
|
||||
- Affected code:
|
||||
- `src/ipc/database/cloudHandler.ts`
|
||||
- `src/utils/protobuf.ts`
|
||||
- `src/ipc/database/handler.ts`
|
||||
- `src/utils/paths.ts`
|
||||
|
||||
## Risks
|
||||
|
||||
- Protobuf encoding/decoding mismatch may break injection or parsing.
|
||||
- Version detection failure may route to the wrong injection path.
|
||||
- DB lock conflicts during injection may cause write failures.
|
||||
@@ -1,35 +1,35 @@
|
||||
## ADDED Requirements
|
||||
### Requirement: New-Format Injection for 1.16.5+
|
||||
The system SHALL write only the new format `geminiNexusUnifiedStateSync.oauthToken` when IDE version is >= 1.16.5.
|
||||
|
||||
#### Scenario: New-version injection
|
||||
- **WHEN** IDE version is 1.16.5 or above
|
||||
- **THEN** the system writes the new format and completes account switching
|
||||
|
||||
### Requirement: Legacy Injection for Older Versions
|
||||
The system SHALL write only the legacy format `jetskiStateSync.agentManagerInitState` when IDE version is < 1.16.5.
|
||||
|
||||
#### Scenario: Legacy-version injection
|
||||
- **WHEN** IDE version is below 1.16.5
|
||||
- **THEN** the system writes the legacy format and completes account switching
|
||||
|
||||
### Requirement: Dual-Write Fallback on Version Detection Failure
|
||||
The system SHALL attempt both new and legacy format injection when IDE version cannot be detected.
|
||||
|
||||
#### Scenario: Version detection fails
|
||||
- **WHEN** the system cannot read IDE version
|
||||
- **THEN** the system writes both new and legacy formats and must not abort due to one path failing
|
||||
|
||||
### Requirement: Account Detection via New Format
|
||||
The system SHALL read OAuth token from the new format and complete account detection.
|
||||
|
||||
#### Scenario: Only new format exists
|
||||
- **WHEN** IDE database contains only the new-format key
|
||||
- **THEN** the system still recognizes accounts and completes synchronization
|
||||
|
||||
### Requirement: Backup/Restore Includes New-Format Keys
|
||||
The system SHALL include new-format keys in account backup and restore.
|
||||
|
||||
#### Scenario: Backup and restore for new format
|
||||
- **WHEN** users perform backup and restore
|
||||
- **THEN** new-format keys are fully saved and restored
|
||||
## ADDED Requirements
|
||||
### Requirement: New-Format Injection for 1.16.5+
|
||||
The system SHALL write only the new format `geminiNexusUnifiedStateSync.oauthToken` when IDE version is >= 1.16.5.
|
||||
|
||||
#### Scenario: New-version injection
|
||||
- **WHEN** IDE version is 1.16.5 or above
|
||||
- **THEN** the system writes the new format and completes account switching
|
||||
|
||||
### Requirement: Legacy Injection for Older Versions
|
||||
The system SHALL write only the legacy format `jetskiStateSync.agentManagerInitState` when IDE version is < 1.16.5.
|
||||
|
||||
#### Scenario: Legacy-version injection
|
||||
- **WHEN** IDE version is below 1.16.5
|
||||
- **THEN** the system writes the legacy format and completes account switching
|
||||
|
||||
### Requirement: Dual-Write Fallback on Version Detection Failure
|
||||
The system SHALL attempt both new and legacy format injection when IDE version cannot be detected.
|
||||
|
||||
#### Scenario: Version detection fails
|
||||
- **WHEN** the system cannot read IDE version
|
||||
- **THEN** the system writes both new and legacy formats and must not abort due to one path failing
|
||||
|
||||
### Requirement: Account Detection via New Format
|
||||
The system SHALL read OAuth token from the new format and complete account detection.
|
||||
|
||||
#### Scenario: Only new format exists
|
||||
- **WHEN** IDE database contains only the new-format key
|
||||
- **THEN** the system still recognizes accounts and completes synchronization
|
||||
|
||||
### Requirement: Backup/Restore Includes New-Format Keys
|
||||
The system SHALL include new-format keys in account backup and restore.
|
||||
|
||||
#### Scenario: Backup and restore for new format
|
||||
- **WHEN** users perform backup and restore
|
||||
- **THEN** new-format keys are fully saved and restored
|
||||
@@ -1,19 +1,19 @@
|
||||
## 1. Scope and Planning Confirmation
|
||||
|
||||
- [x] 1.1 Review `proposal.md`.
|
||||
- [x] 1.2 Confirm this stage covers default runtime configuration path only.
|
||||
- [x] 1.3 Define behavior-consistency constraints.
|
||||
|
||||
## 2. Implementation
|
||||
|
||||
- [x] 2.1 Add IDE version-detection module.
|
||||
- [x] 2.2 Add encode/decode support for new-format OAuth token.
|
||||
- [x] 2.3 Add routed injection logic and dual-write fallback on detection failure.
|
||||
- [x] 2.4 Prefer new format for account detection, with legacy fallback.
|
||||
- [x] 2.5 Extend backup/restore to cover new-format keys.
|
||||
|
||||
## 3. Verification
|
||||
|
||||
- [ ] 3.1 Self-test injection paths for both new and legacy formats.
|
||||
- [ ] 3.2 Verify dual-write behavior when version detection fails.
|
||||
- [ ] 3.3 Verify account availability after backup/restore.
|
||||
## 1. Scope and Planning Confirmation
|
||||
|
||||
- [x] 1.1 Review `proposal.md`.
|
||||
- [x] 1.2 Confirm this stage covers default runtime configuration path only.
|
||||
- [x] 1.3 Define behavior-consistency constraints.
|
||||
|
||||
## 2. Implementation
|
||||
|
||||
- [x] 2.1 Add IDE version-detection module.
|
||||
- [x] 2.2 Add encode/decode support for new-format OAuth token.
|
||||
- [x] 2.3 Add routed injection logic and dual-write fallback on detection failure.
|
||||
- [x] 2.4 Prefer new format for account detection, with legacy fallback.
|
||||
- [x] 2.5 Extend backup/restore to cover new-format keys.
|
||||
|
||||
## 3. Verification
|
||||
|
||||
- [ ] 3.1 Self-test injection paths for both new and legacy formats.
|
||||
- [ ] 3.2 Verify dual-write behavior when version detection fails.
|
||||
- [ ] 3.3 Verify account availability after backup/restore.
|
||||
Reference in new issue
Block a user