docs(openspec): backfill missing proposals

2026-02-08 01:12:17 +08:00
1 parent a93c6d0cea
commit 287e848b32
@@ -0,0 +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.
@@ -0,0 +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.
@@ -0,0 +1,35 @@
+## ADDED Requirements
+### Requirement: New-Format Injection for 1.16.5+
+The system SHALL write only the new format `antigravityUnifiedStateSync.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
@@ -0,0 +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.