diff --git a/openspec/changes/add-multiarch-release-artifacts/design.md b/openspec/changes/add-multiarch-release-artifacts/design.md new file mode 100644 index 0000000..7e31a55 --- /dev/null +++ b/openspec/changes/add-multiarch-release-artifacts/design.md @@ -0,0 +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? diff --git a/openspec/changes/add-multiarch-release-artifacts/proposal.md b/openspec/changes/add-multiarch-release-artifacts/proposal.md new file mode 100644 index 0000000..e757a5e --- /dev/null +++ b/openspec/changes/add-multiarch-release-artifacts/proposal.md @@ -0,0 +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` diff --git a/openspec/changes/add-multiarch-release-artifacts/specs/release-packaging/spec.md b/openspec/changes/add-multiarch-release-artifacts/specs/release-packaging/spec.md new file mode 100644 index 0000000..d3b641c --- /dev/null +++ b/openspec/changes/add-multiarch-release-artifacts/specs/release-packaging/spec.md @@ -0,0 +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 diff --git a/openspec/changes/add-multiarch-release-artifacts/tasks.md b/openspec/changes/add-multiarch-release-artifacts/tasks.md new file mode 100644 index 0000000..e1bba7c --- /dev/null +++ b/openspec/changes/add-multiarch-release-artifacts/tasks.md @@ -0,0 +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. diff --git a/openspec/changes/improve-cross-platform-stability/design.md b/openspec/changes/improve-cross-platform-stability/design.md new file mode 100644 index 0000000..6de6c2c --- /dev/null +++ b/openspec/changes/improve-cross-platform-stability/design.md @@ -0,0 +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. diff --git a/openspec/changes/improve-cross-platform-stability/proposal.md b/openspec/changes/improve-cross-platform-stability/proposal.md new file mode 100644 index 0000000..f73fb2c --- /dev/null +++ b/openspec/changes/improve-cross-platform-stability/proposal.md @@ -0,0 +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/antigravityVersion.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. diff --git a/openspec/changes/improve-cross-platform-stability/specs/ide-auth-compat/spec.md b/openspec/changes/improve-cross-platform-stability/specs/ide-auth-compat/spec.md new file mode 100644 index 0000000..a4bfaf6 --- /dev/null +++ b/openspec/changes/improve-cross-platform-stability/specs/ide-auth-compat/spec.md @@ -0,0 +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** `antigravityUnifiedStateSync.oauthToken` exists +- **THEN** injection uses new format with higher priority diff --git a/openspec/changes/improve-cross-platform-stability/tasks.md b/openspec/changes/improve-cross-platform-stability/tasks.md new file mode 100644 index 0000000..848d05a --- /dev/null +++ b/openspec/changes/improve-cross-platform-stability/tasks.md @@ -0,0 +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. diff --git a/openspec/changes/refactor-db-drizzle/design.md b/openspec/changes/refactor-db-drizzle/design.md new file mode 100644 index 0000000..f8053f0 --- /dev/null +++ b/openspec/changes/refactor-db-drizzle/design.md @@ -0,0 +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. diff --git a/openspec/changes/refactor-db-drizzle/proposal.md b/openspec/changes/refactor-db-drizzle/proposal.md new file mode 100644 index 0000000..2abfaad --- /dev/null +++ b/openspec/changes/refactor-db-drizzle/proposal.md @@ -0,0 +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) diff --git a/openspec/changes/refactor-db-drizzle/specs/database-access/spec.md b/openspec/changes/refactor-db-drizzle/specs/database-access/spec.md new file mode 100644 index 0000000..c566720 --- /dev/null +++ b/openspec/changes/refactor-db-drizzle/specs/database-access/spec.md @@ -0,0 +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 diff --git a/openspec/changes/refactor-db-drizzle/tasks.md b/openspec/changes/refactor-db-drizzle/tasks.md new file mode 100644 index 0000000..6bd30ab --- /dev/null +++ b/openspec/changes/refactor-db-drizzle/tasks.md @@ -0,0 +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). diff --git a/openspec/changes/update-ide-auth-compat-1165/design.md b/openspec/changes/update-ide-auth-compat-1165/design.md new file mode 100644 index 0000000..215332e --- /dev/null +++ b/openspec/changes/update-ide-auth-compat-1165/design.md @@ -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. diff --git a/openspec/changes/update-ide-auth-compat-1165/proposal.md b/openspec/changes/update-ide-auth-compat-1165/proposal.md new file mode 100644 index 0000000..0b94791 --- /dev/null +++ b/openspec/changes/update-ide-auth-compat-1165/proposal.md @@ -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. diff --git a/openspec/changes/update-ide-auth-compat-1165/specs/ide-auth-compat/spec.md b/openspec/changes/update-ide-auth-compat-1165/specs/ide-auth-compat/spec.md new file mode 100644 index 0000000..61c3932 --- /dev/null +++ b/openspec/changes/update-ide-auth-compat-1165/specs/ide-auth-compat/spec.md @@ -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 diff --git a/openspec/changes/update-ide-auth-compat-1165/tasks.md b/openspec/changes/update-ide-auth-compat-1165/tasks.md new file mode 100644 index 0000000..b7b4ebe --- /dev/null +++ b/openspec/changes/update-ide-auth-compat-1165/tasks.md @@ -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.