AIPex: Instructions file for Codex

Package Architecture

@core                 → Pure TS, no platform deps. Defines interfaces.
@browser-runtime      → Implements @core for Chrome. Depends on @core only.
@aipex-react          → UI library. Depends on @core only (NOT browser-runtime).
browser-ext           → Extension entry. Assembles all packages.

Key rule: @aipex-react must NOT depend on @browser-runtime. Browser-specific code (ChromeStorageAdapter, browser tools) stays in @browser-runtime or browser-ext.

Building and running

Before submitting any changes, it is crucial to validate them by running the full preflight check. This command will build the repository, run all tests, check for type errors, and lint the code.

To run the full suite of checks, execute the following command:

npm run preflight

Writing Tests

This project uses Vitest as its primary testing framework. When writing tests, aim to follow existing patterns. Key conventions include:

Test Structure and Framework

• Framework: All tests are written using Vitest (describe, it, expect, vi).
• File Location: Test files (*.test.ts for logic, *.test.tsx for React components) are co-located with the source files they test.
• Configuration: Test environments are defined in vitest.config.ts files.
• Setup/Teardown: Use beforeEach and afterEach. Commonly, vi.resetAllMocks() is called in beforeEach and vi.restoreAllMocks() in afterEach.

Mocking (vi from Vitest)

• ES Modules: Mock with vi.mock('module-name', async (importOriginal) => { ... }). Use importOriginal for selective mocking.
  • Example: vi.mock('os', async (importOriginal) => { const actual = await importOriginal(); return { ...actual, homedir: vi.fn() }; });
• Mocking Order: For critical dependencies (e.g., os, fs) that affect module-level constants, place vi.mock at the very top of the test file, before other imports.
• Hoisting: Use const myMock = vi.hoisted(() => vi.fn()); if a mock function needs to be defined before its use in a vi.mock factory.
• Mock Functions: Create with vi.fn(). Define behavior with mockImplementation(), mockResolvedValue(), or mockRejectedValue().
• Spying: Use vi.spyOn(object, 'methodName'). Restore spies with mockRestore() in afterEach.