Comparison

A · Cursor rules · groupultra/telegram-search B · AGENTS.md · groupultra/telegram-search

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	6	12	0%
Commands	0	0	19	0%
Section tags	3	1	11	20%

What each file covers

Sections

0 shared · 6 only in A · 12 only in B

− Frontend (apps/web)
− Routing, Layouts & Navigation
− State & Data Fetching
− UI, Styling & UX
− Error Handling & Notifications
− Devtools & PGlite
+ Project Coded Agent Guide
+ Tech Stack (by surface)
+ Structure & Responsibilities
+ Key Path Index (what lives where)
+ Commands (pnpm with filters)
+ Dependency Management Rule
+ Styling & Conventions
+ Testing Practices
+ TypeScript / Tooling
+ Refactoring & Comments
+ PR / Workflow Tips
+ Docker + SQL Conventions

Commands

0 shared · 0 only in A · 19 only in B

+ eslint.config.ts
+ pnpm-workspace.yaml
+ docker/
+ pnpm -F @tg-search/server dev
+ pnpm run web:dev
+ pnpm run server:dev
+ pnpm run start
+ pnpm run build
+ pnpm run server:build
+ pnpm run test:run
+ pnpm run test:coverage
+ pnpm run lint
+ pnpm run lint:fix
+ pnpm run typecheck
+ pnpm run db:generate
+ pnpm install
+ pnpm install -F <target> <dependency>
+ vitest
+ docker-compose.yml

Section tags

3 shared · 1 only in A · 11 only in B

− security
+ setup
+ build
+ test
+ lint-format
+ architecture
+ types
+ testing-strategy
+ git-pr
+ database
+ agent-behaviour
+ docs
code-style
ui
monorepo

Line diff

+87 added−38 removed14 unchanged13.9% identical

groupultra/telegram-search · .cursor/rules/frontend-web.mdc

@@ −1 @@

1---

2globs: apps/web/src/**/*, apps/web/index.html, apps/web/uno.config.ts, apps/web/vite.config.ts, apps/web/typed-router.d.ts

3---

5## Frontend (apps/web)

7- **Role**: Deliver the Telegram search UI. All business logic and side effects should live in `packages/client` / `packages/core`, not in Vue components.

8- **Architecture**:

9 - Use **Composition API** with `<script setup lang="ts">` by default. Avoid Options API for new code.

10 - Keep components small and focused; extract logic into composables in `apps/web/src/composables` or into `packages/client`.

11 - Do not access Telegram or the database directly from `apps/web`; always go through `@tg-search/client`.

13### Routing, Layouts & Navigation

15- Use the auto-generated routes from `vue-router/auto-routes` and `virtual:generated-layouts`.

16- Prefer **file-based routing** conventions over manual route declarations.

17- Guard routes via Pinia stores or client events (auth status), not ad‑hoc `localStorage` checks in components.

18- When adding navigation transitions or loading states:

19 - Integrate with the existing `NProgress` guards in `main.ts` instead of ad‑hoc spinners in every page.

21### State & Data Fetching

23- Global/shared state belongs in **Pinia** stores (either in `apps/web/src/stores` or `packages/client`).

24- For async data and server/core interactions:

25 - Prefer **TanStack Query** (`@tanstack/vue-query`) for request lifecycle, caching, and background refetch.

26 - Model long‑running operations (imports, indexing, sync) as events and progress updates flowing through `@tg-search/client`, not as raw HTTP calls from components.

27- Never call `initDrizzle` or mutate `CoreContext` directly from `apps/web`; that belongs in `packages/client`.

29### UI, Styling & UX

31- Use **UnoCSS** utilities and the existing presets (`unocss`, `unocss-preset-shadcn`, `@proj-airi/unocss-preset-chromatic`) as the primary styling tools.

32- Keep layout and visual primitives reusable:

33 - Extract repeated patterns into small components under `apps/web/src/components`.

34 - Avoid deep CSS overrides; prefer class-based composition.

35- Respect accessibility basics:

36 - Use semantic HTML elements and proper labels for inputs and buttons.

37 - Ensure keyboard navigation works for any new interactive components.

39### Error Handling & Notifications

41- Surface user-facing errors via consistent UI (e.g. toast/notification component or error blocks), not `alert` or silent failures.

42- For unexpected errors:

43 - Log via `@guiiai/logg` only inside `packages/client` / `packages/common`; the web app should avoid its own logging layer beyond dev tooling.

44 - Show a generic message to the user; do not display raw stack traces.

46### Devtools & PGlite

48- PGlite devtools (`@unbird/pglite-inspector`) must remain **development-only**:

49 - Guard setup with `import.meta.env.DEV` as in `main.ts`.

50 - If you add more devtools hooks, wire them behind the same guard and avoid impacting production bundle size significantly.

groupultra/telegram-search · AGENTS.md

@@ +1 @@

1# Project Coded Agent Guide

3Concise but detailed reference for contributors working in the `groupultra/telegram-search` monorepo. Improve code when you touch it; avoid one-off patterns.

5## Tech Stack (by surface)

7- **Server (`apps/server`)**: Node.js, TypeScript, Drizzle ORM, Postgres/pgvector, WebSocket + REST, dotenvx.

8- **Web (`apps/web`)**: Vue 3 + Vite, Pinia.

9- **Core/shared (`packages/*`)**: common types, client SDK, schema, core services, bot.

10- **Tooling**: pnpm workspaces, Vitest, ESLint, TypeScript 5.9, tsdown, Drizzle Kit.

12## Structure & Responsibilities

14- **Apps**

15 - `apps/server`: backend service (runtime entry in `apps/server/src/`).

16 - `apps/web`: web UI (source in `apps/web/src/`).

17- **Packages**

18 - `packages/`: shared libraries and domain logic used by apps.

19- **Root tooling**

20 - Linting: `eslint.config.ts`.

21 - DB tooling: `drizzle/`, `drizzle.config.ts`.

22 - Workspace: `pnpm-workspace.yaml`.

24## Key Path Index (what lives where)

26- `apps/server/src`: API, WebSocket, and session services.

27- `apps/web/src`: Vue UI and client-side logic.

28- `packages/core`: core domain/services.

29- `packages/schema`: shared types + DB schema.

30- `packages/client`: client SDKs for integration.

31- `docker/`: compose files + init scripts for local/dev.

32- `.env.example`: baseline env config.

34## Commands (pnpm with filters)

36> Use pnpm workspace filters to scope tasks, e.g. `pnpm -F @tg-search/server dev`.

38- **Dev (web only)**: `pnpm run web:dev`

39- **Dev (server only)**: `pnpm run server:dev`

40- **Dev (web + server)**: `pnpm run start`

41- **Build web**: `pnpm run build`

42- **Build server**: `pnpm run server:build`

43- **Run tests**: `pnpm run test:run`

44- **Coverage**: `pnpm run test:coverage`

45- **Lint**: `pnpm run lint` / `pnpm run lint:fix`

46- **Typecheck**: `pnpm run typecheck`

47- **DB generate**: `pnpm run db:generate`

49## Dependency Management Rule

51- Do not edit `package.json` directly to add/remove deps. Use `pnpm install` so lockfile and manifest stay in sync.

52- For workspace deps: `pnpm install -F <target> <dependency>` (add `-D` for dev deps).

53- Tooling like `typescript`, `vite`, `vitest`, `tsdown`, `@types/node` belongs at the workspace root (`-w`).

55## Styling & Conventions

57- Favor clear module boundaries; shared logic goes in `packages/`.

58- Keep runtime entrypoints lean; move heavy logic into services/modules.

59- Prefer functional patterns for testability; use DI where helpful. Avoid classes unless required by APIs.

60- Use Valibot for schema validation; keep schemas close to their consumers.

61- Use Eventa (`@moeru/eventa`) for structured IPC/RPC contracts where needed.

62- File names: `kebab-case`.

63- Do not add backward-compatibility guards. If extended support is required, write refactor docs and complete the change in a separate, well-scoped effort.

64- If the refactor scope is small, do a progressive refactor step by step.

65- When modifying code, look for small, safe refactors to reduce duplication or improve clarity.

66- If you need a workaround, add a `// NOTICE:` comment explaining why, the root cause, and any relevant context.

68## Testing Practices

70- Use Vitest for unit/integration tests.

71- Mock external services and Postgres where practical; keep tests deterministic.

72- When fixing a bug, add a Vitest test that documents the previous failure mode and include a short `//` comment about the cause.

73- For DB interactions, prefer migration-driven integration tests with env guards.

75## TypeScript / Tooling

77- Stay strict with types; avoid `any` unless absolutely necessary.

78- Prefer small, composable modules; keep exports minimal and intentional.

80## Refactoring & Comments

82- Prefer progressive, incremental refactors that keep behavior stable.

83- Keep existing comments with the code when moving/refactoring. If a comment becomes obsolete, replace it with a brief note about why it was removed.

84- Use markers consistently: `// TODO:`, `// REVIEW:`, `// NOTICE:`.

85- Add concise comments for complex logic, algorithms, OS-interaction, and shared utilities. Avoid obvious comments.

87## PR / Workflow Tips

89- Keep changes scoped; use workspace filters for commands.

90- Summarize changes, how tested (commands), and follow-ups.

91- Improve legacy when you touch it; avoid one-off patterns.

92- Maintain structured `README.md` documentation for each `packages/` and `apps/` entry.

93- Always run `pnpm run typecheck` and `pnpm run lint:fix` after finishing a task.

94- Use Conventional Commits (e.g., `feat(server): add session refresh`).

96## Docker + SQL Conventions

98- Use `docker-compose.yml` as the compose filename.

99- Do not write SQL migration files manually. Always use `drizzle-kit generate` to create migrations, which will be placed in `**/sql/` with descriptive, kebab-case names.

100- Avoid Postgres enums to keep migrations and imports flexible.

101

@@ −1 +1 @@

1−---

2−globs: apps/web/src/**/*, apps/web/index.html, apps/web/uno.config.ts, apps/web/vite.config.ts, apps/web/typed-router.d.ts

3−---

1+# Project Coded Agent Guide

5−## Frontend (apps/web)

3+Concise but detailed reference for contributors working in the `groupultra/telegram-search` monorepo. Improve code when you touch it; avoid one-off patterns.

7−- **Role**: Deliver the Telegram search UI. All business logic and side effects should live in `packages/client` / `packages/core`, not in Vue components.

8−- **Architecture**:

9− - Use **Composition API** with `<script setup lang="ts">` by default. Avoid Options API for new code.

10− - Keep components small and focused; extract logic into composables in `apps/web/src/composables` or into `packages/client`.

11− - Do not access Telegram or the database directly from `apps/web`; always go through `@tg-search/client`.

5+## Tech Stack (by surface)

126

13−### Routing, Layouts & Navigation

7+- **Server (`apps/server`)**: Node.js, TypeScript, Drizzle ORM, Postgres/pgvector, WebSocket + REST, dotenvx.

8+- **Web (`apps/web`)**: Vue 3 + Vite, Pinia.

9+- **Core/shared (`packages/*`)**: common types, client SDK, schema, core services, bot.

10+- **Tooling**: pnpm workspaces, Vitest, ESLint, TypeScript 5.9, tsdown, Drizzle Kit.

1411

15−- Use the auto-generated routes from `vue-router/auto-routes` and `virtual:generated-layouts`.

16−- Prefer **file-based routing** conventions over manual route declarations.

17−- Guard routes via Pinia stores or client events (auth status), not ad‑hoc `localStorage` checks in components.

18−- When adding navigation transitions or loading states:

19− - Integrate with the existing `NProgress` guards in `main.ts` instead of ad‑hoc spinners in every page.

12+## Structure & Responsibilities

2013

21−### State & Data Fetching

14+- **Apps**

15+ - `apps/server`: backend service (runtime entry in `apps/server/src/`).

16+ - `apps/web`: web UI (source in `apps/web/src/`).

17+- **Packages**

18+ - `packages/`: shared libraries and domain logic used by apps.

19+- **Root tooling**

20+ - Linting: `eslint.config.ts`.

21+ - DB tooling: `drizzle/`, `drizzle.config.ts`.

22+ - Workspace: `pnpm-workspace.yaml`.

2223

23−- Global/shared state belongs in **Pinia** stores (either in `apps/web/src/stores` or `packages/client`).

24−- For async data and server/core interactions:

25− - Prefer **TanStack Query** (`@tanstack/vue-query`) for request lifecycle, caching, and background refetch.

26− - Model long‑running operations (imports, indexing, sync) as events and progress updates flowing through `@tg-search/client`, not as raw HTTP calls from components.

27−- Never call `initDrizzle` or mutate `CoreContext` directly from `apps/web`; that belongs in `packages/client`.

24+## Key Path Index (what lives where)

2825

29−### UI, Styling & UX

26+- `apps/server/src`: API, WebSocket, and session services.

27+- `apps/web/src`: Vue UI and client-side logic.

28+- `packages/core`: core domain/services.

29+- `packages/schema`: shared types + DB schema.

30+- `packages/client`: client SDKs for integration.

31+- `docker/`: compose files + init scripts for local/dev.

32+- `.env.example`: baseline env config.

3033

31−- Use **UnoCSS** utilities and the existing presets (`unocss`, `unocss-preset-shadcn`, `@proj-airi/unocss-preset-chromatic`) as the primary styling tools.

32−- Keep layout and visual primitives reusable:

33− - Extract repeated patterns into small components under `apps/web/src/components`.

34− - Avoid deep CSS overrides; prefer class-based composition.

35−- Respect accessibility basics:

36− - Use semantic HTML elements and proper labels for inputs and buttons.

37− - Ensure keyboard navigation works for any new interactive components.

34+## Commands (pnpm with filters)

3835

39−### Error Handling & Notifications

36+> Use pnpm workspace filters to scope tasks, e.g. `pnpm -F @tg-search/server dev`.

4037

41−- Surface user-facing errors via consistent UI (e.g. toast/notification component or error blocks), not `alert` or silent failures.

42−- For unexpected errors:

43− - Log via `@guiiai/logg` only inside `packages/client` / `packages/common`; the web app should avoid its own logging layer beyond dev tooling.

44− - Show a generic message to the user; do not display raw stack traces.

38+- **Dev (web only)**: `pnpm run web:dev`

39+- **Dev (server only)**: `pnpm run server:dev`

40+- **Dev (web + server)**: `pnpm run start`

41+- **Build web**: `pnpm run build`

42+- **Build server**: `pnpm run server:build`

43+- **Run tests**: `pnpm run test:run`

44+- **Coverage**: `pnpm run test:coverage`

45+- **Lint**: `pnpm run lint` / `pnpm run lint:fix`

46+- **Typecheck**: `pnpm run typecheck`

47+- **DB generate**: `pnpm run db:generate`

4548

46−### Devtools & PGlite

49+## Dependency Management Rule

4750

48−- PGlite devtools (`@unbird/pglite-inspector`) must remain **development-only**:

49− - Guard setup with `import.meta.env.DEV` as in `main.ts`.

50− - If you add more devtools hooks, wire them behind the same guard and avoid impacting production bundle size significantly.

51+- Do not edit `package.json` directly to add/remove deps. Use `pnpm install` so lockfile and manifest stay in sync.

52+- For workspace deps: `pnpm install -F <target> <dependency>` (add `-D` for dev deps).

53+- Tooling like `typescript`, `vite`, `vitest`, `tsdown`, `@types/node` belongs at the workspace root (`-w`).

5154

55+## Styling & Conventions

56+

57+- Favor clear module boundaries; shared logic goes in `packages/`.

58+- Keep runtime entrypoints lean; move heavy logic into services/modules.

59+- Prefer functional patterns for testability; use DI where helpful. Avoid classes unless required by APIs.

60+- Use Valibot for schema validation; keep schemas close to their consumers.

61+- Use Eventa (`@moeru/eventa`) for structured IPC/RPC contracts where needed.

62+- File names: `kebab-case`.

63+- Do not add backward-compatibility guards. If extended support is required, write refactor docs and complete the change in a separate, well-scoped effort.

64+- If the refactor scope is small, do a progressive refactor step by step.

65+- When modifying code, look for small, safe refactors to reduce duplication or improve clarity.

66+- If you need a workaround, add a `// NOTICE:` comment explaining why, the root cause, and any relevant context.

67+

68+## Testing Practices

69+

70+- Use Vitest for unit/integration tests.

71+- Mock external services and Postgres where practical; keep tests deterministic.

72+- When fixing a bug, add a Vitest test that documents the previous failure mode and include a short `//` comment about the cause.

73+- For DB interactions, prefer migration-driven integration tests with env guards.

74+

75+## TypeScript / Tooling

76+

77+- Stay strict with types; avoid `any` unless absolutely necessary.

78+- Prefer small, composable modules; keep exports minimal and intentional.

79+

80+## Refactoring & Comments

81+

82+- Prefer progressive, incremental refactors that keep behavior stable.

83+- Keep existing comments with the code when moving/refactoring. If a comment becomes obsolete, replace it with a brief note about why it was removed.

84+- Use markers consistently: `// TODO:`, `// REVIEW:`, `// NOTICE:`.

85+- Add concise comments for complex logic, algorithms, OS-interaction, and shared utilities. Avoid obvious comments.

86+

87+## PR / Workflow Tips

88+

89+- Keep changes scoped; use workspace filters for commands.

90+- Summarize changes, how tested (commands), and follow-ups.

91+- Improve legacy when you touch it; avoid one-off patterns.

92+- Maintain structured `README.md` documentation for each `packages/` and `apps/` entry.

93+- Always run `pnpm run typecheck` and `pnpm run lint:fix` after finishing a task.

94+- Use Conventional Commits (e.g., `feat(server): add session refresh`).

95+

96+## Docker + SQL Conventions

97+

98+- Use `docker-compose.yml` as the compose filename.

99+- Do not write SQL migration files manually. Always use `drizzle-kit generate` to create migrations, which will be placed in `**/sql/` with descriptive, kebab-case names.

100+- Avoid Postgres enums to keep migrations and imports flexible.

52101