Comparison

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

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	12	5	0%
Commands	0	19	0	0%
Section tags	4	10	1	27%

What each file covers

Sections

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

− 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
+ Client Adapters (packages/client)
+ Core Runtime & Bridge
+ Events & Type Safety
+ Pinia Stores & Composables
+ Logging & Error Handling

Commands

0 shared · 19 only in A · 0 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

4 shared · 10 only in A · 1 only in B

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

Line diff

+43 added−89 removed12 unchanged11.9% identical

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

groupultra/telegram-search · .cursor/rules/client.mdc

@@ +1 @@

1---

2globs: packages/client/src/**/*

3---

5## Client Adapters (packages/client)

7- **Role**: Bridge between UI (Vue/Pinia) and core (`packages/core`) in both:

8 - **Browser-only mode** (embedded core via `core-runtime` / `core-bridge`).

9 - **Server mode** (WebSocket adapter to `apps/server`).

10- Keep this package thin and focused on:

11 - Event wiring.

12 - Session/account management.

13 - Store updates and derivations for UI consumption.

15### Core Runtime & Bridge

17- `core-runtime`:

18 - Owns the lifecycle of `CoreContext` and DB initialization in browser mode.

19 - Exposes helper methods (`getCtx`, `destroy`, etc.) instead of leaking internal implementation.

20- `core-bridge`:

21 - Manages sessions, the active account slot, and event handler registration.

22 - On account switch:

23 - Destroy the existing `CoreContext`.

24 - Re-register client-side event handlers for the new active account.

25 - Never share a single runtime instance across different account IDs.

27### Events & Type Safety

29- Always go through the typed WebSocket/core event maps:

30 - Use `WsEventToServer`, `WsEventToClient`, and `FromCoreEvent` / `ToCoreEvent` types.

31 - Avoid untyped `any` payloads or generic `Record<string, unknown>` where stronger types are available.

32- When adding new events:

33 - Update the shared `@tg-search/server/types`.

34 - Extend client event handler maps and registration helpers.

35 - Keep the mapping between WS event names and core events explicit.

37### Pinia Stores & Composables

39- Stores in `packages/client` are the **source of truth** for app state:

40 - Use actions to emit events to core and react to `FromCoreEvent` updates.

41 - Avoid duplicating the same state in both `apps/web` and `packages/client`.

42- For reusable logic, prefer composables and pure utilities inside this package rather than re-implementing logic in components.

44### Logging & Error Handling

46- Use `useLogger` with a **component/module name** (e.g. `'CoreBridge'`) for all logs in this package.

47- Log:

48 - High-level intent (event name, account/session IDs).

49 - Errors when event delivery or handler invocation fails.

50- Do not log sensitive payload data (raw messages, tokens, secrets).

51- When something fails:

52 - Prefer emitting a client-facing event that the UI can react to (e.g. a `core:error` or domain-specific failure event).

53 - Avoid throwing unhandled exceptions that would crash the whole bridge.

@@ −1 +1 @@

1−# Project Coded Agent Guide

1+---

2+globs: packages/client/src/**/*

3+---

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

5+## Client Adapters (packages/client)

5−## Tech Stack (by surface)

7+- **Role**: Bridge between UI (Vue/Pinia) and core (`packages/core`) in both:

8+ - **Browser-only mode** (embedded core via `core-runtime` / `core-bridge`).

9+ - **Server mode** (WebSocket adapter to `apps/server`).

10+- Keep this package thin and focused on:

11+ - Event wiring.

12+ - Session/account management.

13+ - Store updates and derivations for UI consumption.

614

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.

15+### Core Runtime & Bridge

1116

12−## Structure & Responsibilities

17+- `core-runtime`:

18+ - Owns the lifecycle of `CoreContext` and DB initialization in browser mode.

19+ - Exposes helper methods (`getCtx`, `destroy`, etc.) instead of leaking internal implementation.

20+- `core-bridge`:

21+ - Manages sessions, the active account slot, and event handler registration.

22+ - On account switch:

23+ - Destroy the existing `CoreContext`.

24+ - Re-register client-side event handlers for the new active account.

25+ - Never share a single runtime instance across different account IDs.

1326

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`.

27+### Events & Type Safety

2328

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

29+- Always go through the typed WebSocket/core event maps:

30+ - Use `WsEventToServer`, `WsEventToClient`, and `FromCoreEvent` / `ToCoreEvent` types.

31+ - Avoid untyped `any` payloads or generic `Record<string, unknown>` where stronger types are available.

32+- When adding new events:

33+ - Update the shared `@tg-search/server/types`.

34+ - Extend client event handler maps and registration helpers.

35+ - Keep the mapping between WS event names and core events explicit.

2536

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.

37+### Pinia Stores & Composables

3338

34−## Commands (pnpm with filters)

39+- Stores in `packages/client` are the **source of truth** for app state:

40+ - Use actions to emit events to core and react to `FromCoreEvent` updates.

41+ - Avoid duplicating the same state in both `apps/web` and `packages/client`.

42+- For reusable logic, prefer composables and pure utilities inside this package rather than re-implementing logic in components.

3543

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

44+### Logging & Error Handling

3745

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`

46+- Use `useLogger` with a **component/module name** (e.g. `'CoreBridge'`) for all logs in this package.

47+- Log:

48+ - High-level intent (event name, account/session IDs).

49+ - Errors when event delivery or handler invocation fails.

50+- Do not log sensitive payload data (raw messages, tokens, secrets).

51+- When something fails:

52+ - Prefer emitting a client-facing event that the UI can react to (e.g. a `core:error` or domain-specific failure event).

53+ - Avoid throwing unhandled exceptions that would crash the whole bridge.

4854

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.

10155