kernel_chat: Instructions file for Gemini CLI

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

This single command ensures that your changes meet all the quality gates of the project. While you can run the individual steps (build, test, typecheck, lint) separately, it is highly recommended to use npm run preflight to ensure a comprehensive validation.

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.