sprout-launcher/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/: React renderer (UI). Main entry is src/main.tsx, app shell in src/App.tsx, shared types in src/types.ts, and UI pieces in src/components/.
• electron/: Electron main + preload (electron/main.ts, electron/preload.ts).
• public/: Static assets bundled with the renderer (for example public/favicon.ico, public/logo.png).
• dist/, dist-electron/: Build artifacts (do not hand-edit).
• release/: Packaged installers output by electron-builder (versioned subfolders).

Build, Test, and Development Commands

• npm install: Install dependencies.
• npm run dev: Run the Vite dev server (with --host) and Electron via vite-plugin-electron.
• npm run lint: Run ESLint with --max-warnings 0 (lint must be clean).
• npm run build: tsc && vite build && electron-builder (creates dist* and writes installers to release/<version>/).
• npm run preview: Preview the built renderer (useful for renderer-only checks).

Coding Style & Naming Conventions

• Language: TypeScript + React, ESM ("type": "module"). TypeScript is strict and enables unused code checks; keep changes type-safe.
• Indentation: 2 spaces (match existing files).
• Components: PascalCase.tsx in src/components/ (for example AppCard.tsx). Types/interfaces stay in src/types.ts unless clearly feature-specific.
• Linting: ESLint (eslint:recommended, @typescript-eslint/recommended, react-hooks/recommended, plus react-refresh rule).

Testing Guidelines

• No automated test framework is currently configured (no npm test, no coverage gate). Changes should include manual smoke testing notes in PRs.
• Minimum manual checks: add/edit/delete apps, category CRUD, config persistence across restart, icon extraction, window controls (min/max/close).
• If you introduce tests, prefer *.spec.ts(x) colocated under src/ (or src/**/__tests__/) and add a test script.

Commit & Pull Request Guidelines

• Git history is not available in this workspace, so no repository-specific commit convention can be derived. Use Conventional Commits (for example feat: add search, fix: handle missing exe, chore: bump deps).
• PRs: include a short summary, testing steps, and screenshots/GIFs for UI changes. Link issues when applicable.
• Keep build artifacts and packaged outputs out of PRs unless intentionally updating release assets.

Security & Configuration Tips

• User configuration lives at %APPDATA%/sprout-launcher/launcher-config.json; never commit local config data.
• If you change the config schema, add a small migration path and document it in the PR.