| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 4 | 12 | 0% |
| Commands | 1 | 0 | 18 | 5% |
| Section tags | 3 | 1 | 11 | 20% |
What each file covers
Sections
0 shared · 4 only in A · 12 only in B- − Database & Migrations
- − Schema Definition
- − Migrations
- − Performance & Indexing
- + 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
1 shared · 0 only in A · 18 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 install
- + pnpm install -F <target> <dependency>
- + vitest
- + docker-compose.yml
- pnpm run db:generate
Section tags
3 shared · 1 only in A · 11 only in B- − performance
- + setup
- + build
- + test
- + lint-format
- + architecture
- + testing-strategy
- + git-pr
- + ui
- + monorepo
- + agent-behaviour
- + docs
- code-style
- types
- database
Line diff
groupultra/telegram-search · .cursor/rules/db.mdc
@@ −1 @@
1---
2globs: drizzle/**/*, sql/**/*, packages/core/src/schemas/**/*, packages/core/src/models/**/*
3---
4
5## Database & Migrations
6
7- **Role**: Provide a consistent schema and migration history that works in both:
8 - PostgreSQL with pgvector (server mode).
9 - PGlite (browser-only mode).
10
11### Schema Definition
12
13- Treat the TypeScript schema in `packages/core/src/schemas` / `models` as the **source of truth**.
14- Ensure any schema change is reflected consistently in:
15 - TS schema/models.
16 - Generated Drizzle migrations under `drizzle/`.
17 - Any raw SQL helpers under `sql/` if present.
18- Prefer Drizzle's typed query APIs over raw SQL to keep Postgres and PGlite behavior aligned.
19
20### Migrations
21
22- Use `drizzle-kit` (`pnpm run db:generate`) to generate new migrations; avoid hand-writing large SQL files.
23- For production-safe changes:
24 - Make migrations forward-only and additive when possible.
25 - Avoid destructive operations without a clear, tested migration path.
26- If a generated migration needs manual tweaks:
27 - Keep custom SQL focused and well-commented.
28 - Verify both Postgres and PGlite behavior where applicable.
29
30### Performance & Indexing
31
32- For vector search:
33 - Ensure vector dimensions match the configured embedding model.
34 - Use pgvector indexes where needed, and make them explicit in migrations.
35- For analytical queries (stats, charts):
36 - Prefer precalculated or indexed aggregates over complex ad‑hoc joins on hot paths.
37
38
groupultra/telegram-search · AGENTS.md
@@ +1 @@
1# Project Coded Agent Guide
2
3Concise but detailed reference for contributors working in the `groupultra/telegram-search` monorepo. Improve code when you touch it; avoid one-off patterns.
4
5## Tech Stack (by surface)
6
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.
11
12## Structure & Responsibilities
13
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`.
23
24## Key Path Index (what lives where)
25
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.
33
34## Commands (pnpm with filters)
35
36> Use pnpm workspace filters to scope tasks, e.g. `pnpm -F @tg-search/server dev`.
37
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`
48
49## Dependency Management Rule
50
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`).
54
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.
101
@@ −1 +1 @@
1−---
2−globs: drizzle/**/*, sql/**/*, packages/core/src/schemas/**/*, packages/core/src/models/**/*
3−---
1+# Project Coded Agent Guide
42
5−## Database & Migrations
3+Concise but detailed reference for contributors working in the `groupultra/telegram-search` monorepo. Improve code when you touch it; avoid one-off patterns.
64
7−- **Role**: Provide a consistent schema and migration history that works in both:
8− - PostgreSQL with pgvector (server mode).
9− - PGlite (browser-only mode).
5+## Tech Stack (by surface)
106
11−### Schema Definition
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.
1211
13−- Treat the TypeScript schema in `packages/core/src/schemas` / `models` as the **source of truth**.
14−- Ensure any schema change is reflected consistently in:
15− - TS schema/models.
16− - Generated Drizzle migrations under `drizzle/`.
17− - Any raw SQL helpers under `sql/` if present.
18−- Prefer Drizzle's typed query APIs over raw SQL to keep Postgres and PGlite behavior aligned.
12+## Structure & Responsibilities
1913
20−### Migrations
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`.
2123
22−- Use `drizzle-kit` (`pnpm run db:generate`) to generate new migrations; avoid hand-writing large SQL files.
23−- For production-safe changes:
24− - Make migrations forward-only and additive when possible.
25− - Avoid destructive operations without a clear, tested migration path.
26−- If a generated migration needs manual tweaks:
27− - Keep custom SQL focused and well-commented.
28− - Verify both Postgres and PGlite behavior where applicable.
24+## Key Path Index (what lives where)
2925
30−### Performance & Indexing
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.
3133
32−- For vector search:
33− - Ensure vector dimensions match the configured embedding model.
34− - Use pgvector indexes where needed, and make them explicit in migrations.
35−- For analytical queries (stats, charts):
36− - Prefer precalculated or indexed aggregates over complex ad‑hoc joins on hot paths.
34+## Commands (pnpm with filters)
3735
36+> Use pnpm workspace filters to scope tasks, e.g. `pnpm -F @tg-search/server dev`.
37+
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`
48+
49+## Dependency Management Rule
50+
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`).
54+
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.
38101
