Skip to content

Commit 2f4ff6c

Browse files
HuakunShenHuakunShen
committed
docs: add AI init summary for the project
claude, gemini, qwen, codex
1 parent 3542eec commit 2f4ff6c

File tree

4 files changed

+325
-0
lines changed

4 files changed

+325
-0
lines changed

‎AGENTS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
- `apps/desktop`: SvelteKit + Tauri desktop app. Source in `src/`, Tauri Rust code in `src-tauri/`, assets in `static/`, i18n in `messages/`.
5+
- `packages/*`: Shared libraries and tools (e.g., `api`, `ui`, `utils`, `drizzle`, `grpc`) and Rust crates (`db`, `crypto`, `tauri-plugins/*`).
6+
- `vendors/*`: Vendored plugins/submodules used by the desktop app.
7+
- Tests live next to code: TS tests in `__tests__` or `*.test.ts`; Rust tests via `#[test]` inside crates.
8+
9+
## Build, Test, and Development Commands
10+
- Install: `pnpm install` (root workspace).
11+
- Initialize vendors: `git submodule update --init --recursive` (if vendors look empty).
12+
- Build all: `pnpm build` (Turbo builds packages; Tauri builds when needed).
13+
- Dev (workspace): `pnpm dev`.
14+
- Dev (desktop): `pnpm --filter @kksh/desktop tauri dev` or `cd apps/desktop && pnpm tauri dev`.
15+
- Test (TS): `pnpm test` or `pnpm -F <package> test`.
16+
- Test (Rust): `cargo test -p <crate>`.
17+
- Lint/format/types: `pnpm lint`, `pnpm format`, `pnpm check-types`. Rust: `cargo fmt` (and `cargo clippy` if available).
18+
19+
## Coding Style & Naming Conventions
20+
- TypeScript/Svelte: 2‑space indent; Prettier + ESLint enforced. Imports sorted via `@ianvs/prettier-plugin-sort-imports`.
21+
- Components: PascalCase `.svelte`. TS files: kebab‑case file names; constants `UPPER_SNAKE_CASE`.
22+
- Rust: rustfmt defaults; crates and modules use `snake_case`.
23+
24+
## Testing Guidelines
25+
- Frameworks: Vitest (TS) and Cargo tests (Rust).
26+
- Placement: co‑locate unit tests in `__tests__` or `*.test.ts`; use `#[test]` in Rust modules.
27+
- Expectations: add tests with new or changed logic; mock I/O and network; keep tests deterministic and fast.
28+
29+
## Commit & Pull Request Guidelines
30+
- Commit style: Conventional Commits with optional scope, mirroring history (e.g., `feat(desktop): improve app icon handling`, `fix(api): update matchPathAndScope`, `chore: upgrade applications-rs submodule`). Reference related issues/PRs like `(#230)`.
31+
- Pull requests: include a clear description, linked issues, test plan/steps, and screenshots or GIFs for UI changes. Note platform impact (macOS/Linux/Windows). Keep diffs focused and update docs/messages when relevant.
32+
33+
## Security & Configuration Tips
34+
- Never commit secrets; use local `.env` files (checked by Turbo inputs). On Windows, configure `OPENSSL_*` env vars when building Tauri (see `CONTRIBUTING.md`).
35+
- Prefer non‑privileged APIs; audit shell/OS calls in extensions and plugins.
36+

‎CLAUDE.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
Kunkun is a cross-platform desktop application built with Tauri (Rust backend) and SvelteKit (frontend). It's an extensible launcher/utility app that supports custom extensions developed in various web frameworks.
8+
9+
## Development Commands
10+
11+
### Essential Commands
12+
- `pnpm install` - Install all dependencies
13+
- `pnpm build` - Build all packages and submodules
14+
- `pnpm dev` - Start development servers for all packages
15+
- `pnpm lint` - Run linting across all packages
16+
- `pnpm test` - Run tests across all packages
17+
- `pnpm check-types` - Run TypeScript type checking
18+
- `pnpm format` - Format code with Prettier
19+
20+
### Desktop App Specific
21+
- `pnpm --filter @kksh/desktop tauri dev` - Run desktop app in development mode
22+
- `cd apps/desktop && pnpm tauri dev` - Alternative way to run desktop app
23+
- `cd apps/desktop && pnpm tauri build` - Build desktop app for production
24+
25+
### Prerequisites for Development
26+
- Node.js ≥22
27+
- pnpm 10.7.0+ (package manager)
28+
- Rust (for Tauri backend)
29+
- Bun, Deno (for various tools)
30+
- protobuf (`brew install protobuf` on macOS)
31+
- cmake (`brew install cmake` on macOS)
32+
33+
## Architecture
34+
35+
### Monorepo Structure
36+
- **apps/**: Main applications
37+
- `desktop/`: Primary Tauri desktop app (SvelteKit frontend + Rust backend)
38+
- `cli/`: Command-line interface
39+
- `create-kunkun/`: Scaffolding tool for extensions
40+
- **packages/**: Shared libraries and utilities
41+
- `ui/`: Shared UI components
42+
- `types/`: TypeScript type definitions
43+
- `extension/`: Extension development framework
44+
- `drizzle/`: Database ORM setup
45+
- `tauri-plugins/`: Custom Tauri plugins
46+
- `templates/`: Extension templates
47+
- `extensions/`: Sample/demo extensions
48+
- **vendors/**: Third-party dependencies and custom plugins
49+
50+
### Key Technologies
51+
- **Frontend**: SvelteKit 2 with TypeScript, TailwindCSS, Vite
52+
- **Backend**: Rust with Tauri 2.x framework
53+
- **Database**: SQLite with Drizzle ORM
54+
- **Build System**: Turbo (monorepo orchestration) + pnpm workspaces
55+
- **UI Framework**: Custom component library built on Tailwind + Radix
56+
57+
### Extension System
58+
- Extensions can be built with React, Vue, Svelte, SvelteKit, Nuxt, or vanilla JS
59+
- Templates available in `packages/templates/` for each framework
60+
- Extensions run in isolated contexts with permission-based APIs
61+
- Custom Tauri plugins provide system access (clipboard, fs, network, etc.)
62+
63+
### Rust Backend Architecture
64+
- Custom Tauri plugins for extended functionality:
65+
- `tauri-plugin-jarvis`: Core extension runtime
66+
- `tauri-plugin-network`: Network operations
67+
- `tauri-plugin-system-info`: System information
68+
- `tauri-plugin-user-input`: Input handling
69+
- `tauri-plugin-keyring`: Secure credential storage
70+
- gRPC communication for some internal services
71+
- Cross-platform support with platform-specific dependencies
72+
73+
## Development Workflow
74+
75+
### Setting Up Development Environment
76+
```bash
77+
git clone https://github.com/kunkunsh/kunkun.git --recursive
78+
pnpm install
79+
pnpm build # Build submodules first
80+
```
81+
82+
### Working with Extensions
83+
- Use `apps/create-kunkun` to scaffold new extensions
84+
- Extension templates are in `packages/templates/`
85+
- Test extensions in the desktop app's extension manager
86+
87+
### Database Development
88+
- Uses Drizzle ORM with SQLite backend
89+
- Database package located in `packages/drizzle/`
90+
- Migrations and schema definitions managed through Drizzle
91+
92+
## Testing and Quality
93+
94+
### Linting and Type Checking
95+
- ESLint configuration in `packages/config-eslint/`
96+
- TypeScript config in `packages/typescript-config/`
97+
- Prettier for code formatting
98+
- `turbo lint` and `turbo check-types` run across all packages
99+
100+
### Build Process
101+
- Turbo orchestrates builds across the monorepo
102+
- Each package defines its own build scripts
103+
- Dependencies built in topological order via `dependsOn` in turbo.json
104+
105+
## Platform-Specific Notes
106+
107+
### macOS
108+
- Requires additional security permissions for system access
109+
- `mac-security-rs` package handles platform-specific APIs
110+
- Uses private macOS APIs for enhanced functionality
111+
112+
### Dependencies
113+
- Most packages use workspace dependencies for internal packages
114+
- External dependencies centrally managed in root package.json
115+
- Rust dependencies managed via workspace Cargo.toml
116+
117+
## Extension Development Framework
118+
119+
Extensions have access to:
120+
- File system APIs (through Tauri plugins)
121+
- Network requests
122+
- Clipboard operations
123+
- System information
124+
- Secure storage (keyring)
125+
- UI components from shared library
126+
127+
The extension system supports both headless (worker) extensions and full UI extensions with multiple framework options.

‎GEMINI.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Kunkun Project Overview
2+
3+
This document provides a comprehensive overview of the Kunkun project, its architecture, and development conventions, intended to be used as instructional context for future interactions.
4+
5+
## Project Overview
6+
7+
Kunkun is a cross-platform desktop application built with [Tauri](https://tauri.app/). It features a Svelte-based frontend and a Rust backend. The project is structured as a monorepo, managed with [pnpm](https://pnpm.io/) for the frontend and [Cargo](https://doc.rust-lang.org/cargo/) for the backend.
8+
9+
The application appears to be an extensible tool, with a system for "extensions" that can be installed. It also includes a CLI and various other packages.
10+
11+
### Key Technologies
12+
13+
* **Frontend:** Svelte, TypeScript
14+
* **Backend:** Rust, Tauri
15+
* **Monorepo Management:** pnpm, Cargo, Turbo
16+
* **Database:** The project includes a `db` package, but the specific database is not immediately clear from the file names.
17+
* **API:** The project includes a `grpc` package, suggesting the use of gRPC for inter-process communication.
18+
19+
## Building and Running
20+
21+
The project uses `turbo` to manage the monorepo. The main commands are defined in the root `package.json`:
22+
23+
* **Development:** To run the application in development mode, use the following command:
24+
```bash
25+
pnpm dev
26+
```
27+
This will start the Svelte development server and the Tauri application.
28+
29+
* **Building:** To build the application for production, use the following command:
30+
```bash
31+
pnpm build
32+
```
33+
This will build the frontend and the Tauri application.
34+
35+
* **Testing:** To run the test suite, use the following command:
36+
```bash
37+
pnpm test
38+
```
39+
40+
* **Linting:** To lint the codebase, use the following command:
41+
```bash
42+
pnpm lint
43+
```
44+
45+
* **Formatting:** To format the codebase, use the following command:
46+
```bash
47+
pnpm format
48+
```
49+
50+
## Development Conventions
51+
52+
* **Coding Style:** The project uses Prettier for code formatting. The configuration is defined in `.prettierrc`.
53+
* **Testing:** The project has a `test` script, but the specific testing framework is not immediately clear. There are `__tests__` directories in some packages, suggesting the use of a framework like Jest or Vitest.
54+
* **Contribution:** The `CONTRIBUTING.md` file should be consulted for contribution guidelines.

‎QWEN.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Kunkun Project Context
2+
3+
## Project Overview
4+
5+
Kunkun is a cross-platform desktop application built with Tauri (Rust + Svelte). It serves as an extensible platform, allowing users to install and run various extensions to add functionality. These extensions can provide UI components, headless commands, or template-based UIs. The project uses a monorepo structure managed by pnpm and Cargo for Node.js/Rust workspaces.
6+
7+
Key features include:
8+
- Cross-platform support (MacOS, Linux, Windows)
9+
- Extensibility via a rich extension system
10+
- Built-in extension store
11+
- Permissions system for extensions
12+
- CLI tools for extension development and management
13+
14+
## Technologies Used
15+
16+
- **Frontend:** Svelte 5, SvelteKit, Tailwind CSS
17+
- **Backend/Desktop:** Rust (Tauri framework)
18+
- **Package Management:** pnpm (Node.js), Cargo (Rust)
19+
- **Build System:** TurboRepo
20+
- **Languages:** TypeScript, Rust, Svelte
21+
- **Database:** Drizzle ORM (SQLite)
22+
- **UI Library:** Custom internal UI library (`@kksh/ui`)
23+
- **API Layer:** Custom API library (`@kksh/api`)
24+
25+
## Project Structure
26+
27+
```
28+
.
29+
├── apps
30+
│ ├── cli # Kunkun CLI tool
31+
│ ├── create-kunkun # Tool for scaffolding new extensions
32+
│ └── desktop # Main Tauri desktop application
33+
├── packages
34+
│ ├── api # Shared API types and utilities for extensions
35+
│ ├── extensions # Official extensions
36+
│ ├── schema # JSON schemas
37+
│ ├── templates # Extension templates
38+
│ ├── tauri-plugins # Custom Tauri plugins
39+
│ ├── ui # Shared Svelte UI components
40+
│ └── ... # Other shared libraries and tools
41+
├── vendors # Vendored external dependencies
42+
└── ...
43+
```
44+
45+
## Building and Running
46+
47+
### Prerequisites
48+
49+
- Node.js >= 22
50+
- pnpm
51+
- Rust toolchain
52+
- Platform-specific dependencies for Tauri (see Tauri docs)
53+
54+
### Setup
55+
56+
1. Install dependencies:
57+
```bash
58+
pnpm install
59+
```
60+
61+
### Development
62+
63+
1. Start the development server:
64+
```bash
65+
pnpm dev
66+
```
67+
This command uses TurboRepo to run the `dev` script in all relevant packages/apps.
68+
69+
### Building
70+
71+
1. Build the project:
72+
```bash
73+
pnpm build
74+
```
75+
This command uses TurboRepo to run the `build` script in all relevant packages/apps.
76+
77+
### Testing
78+
79+
1. Run tests:
80+
```bash
81+
pnpm test
82+
```
83+
This command uses TurboRepo to run the `test` script in all relevant packages/apps.
84+
85+
### Linting and Formatting
86+
87+
1. Lint the code:
88+
```bash
89+
pnpm lint
90+
```
91+
92+
2. Format the code:
93+
```bash
94+
pnpm format
95+
```
96+
97+
### Running the Desktop App
98+
99+
After building, the desktop app can be run directly or packaged for distribution using Tauri's CLI. Check `apps/desktop/src-tauri` for Tauri-specific configurations and build commands.
100+
101+
## Development Conventions
102+
103+
- **Monorepo:** The project uses a monorepo structure with pnpm workspaces for Node.js packages and Cargo workspaces for Rust crates.
104+
- **Code Style:** Prettier is used for code formatting. ESLint is used for linting JavaScript/TypeScript/Svelte files.
105+
- **Type Safety:** TypeScript is used extensively. Svelte 5's runes are leveraged for state management.
106+
- **UI Components:** Reusable UI components are developed in `packages/ui` using Tailwind CSS and Svelte.
107+
- **API:** A shared API library (`packages/api`) provides types and utilities for both the main app and extensions.
108+
- **Extensions:** Extensions are developed as separate packages within the monorepo (e.g., `packages/extensions/*`). They define their metadata, permissions, and entry points in their `package.json` under the `kunkun` key.

0 commit comments

Comments
 (0)