efarmz-slackbot-data 1.0.0

package/.clever.json

@@ -0,0 +1,12 @@
+{
+  "apps": [
+    {
+      "app_id": "app_155a0f63-4ede-493c-814f-72381c07538d",
+      "org_id": "orga_41b0bd88-3bce-4bc8-ba86-fa63451216a3",
+      "deploy_url": "https://push-n3-par-clevercloud-customers.services.clever-cloud.com/app_155a0f63-4ede-493c-814f-72381c07538d.git",
+      "git_ssh_url": "git+ssh://git@push-n3-par-clevercloud-customers.services.clever-cloud.com/app_155a0f63-4ede-493c-814f-72381c07538d.git",
+      "name": "efarmz-slackbot-data",
+      "alias": "app_155a0f63-4ede-493c-814f-72381c07538d"
+    }
+  ]
+}

package/.dockerignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+.git
+.gitignore
+*.md
+.env
+.env.*
+!.env.example
+.plans
+.tasks
+.claude
+*.log
+.DS_Store

package/.env.example

@@ -0,0 +1,28 @@
+# Slack
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_SIGNING_SECRET=...
+SLACK_APP_TOKEN=xapp-... # Optionnel si HTTP mode
+
+# PostgreSQL (read-only user)
+DATABASE_URL=postgres://slackbot_readonly:...@host:5432/efarmz_db
+
+# Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+
+# App config
+PORT=3000
+LOG_LEVEL=info
+ADMIN_CHANNEL_ID=C...
+
+# SQL limits
+SQL_TIMEOUT_MS=30000
+SQL_MAX_ROWS=100
+SQL_CSV_THRESHOLD=15
+
+# Agent config
+AGENT_MAX_TURNS=5
+
+# Conversation cache
+CONVERSATION_TTL_MS=3600000
+CONVERSATION_MAX_THREADS=200
+CONVERSATION_MAX_MESSAGES=8

package/.github/workflows/deploy-production.yaml

@@ -0,0 +1,34 @@
+name: Clever Cloud Production Deployment
+env:
+  HUSKY: 0
+on:
+  push:
+    branches:
+      - master
+jobs:
+  Deploy-Production:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Authenticate with private NPM package
+        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 21
+          corepack-enable: true
+          cache: yarn
+        env:
+          SKIP_YARN_COREPACK_CHECK: true
+      - uses: 47ng/actions-clever-cloud@v2.0.0
+        with:
+          appID: app_155a0f63-4ede-493c-814f-72381c07538d
+          force: true
+        env:
+          CLEVER_TOKEN: ${{ secrets.CLEVER_TOKEN }}
+          CLEVER_SECRET: ${{ secrets.CLEVER_SECRET }}
+      - name: Semantic Release
+        uses: cycjimmy/semantic-release-action@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}

package/.tasks/F1-bootstrap.md

@@ -0,0 +1,110 @@
+---
+title: "F1 — Bootstrap projet"
+type: feature
+status: todo
+prd: .tasks/PRD.md
+---
+
+# F1 — Bootstrap projet
+
+## Objectif
+
+Initialiser le projet Node.js/TypeScript avec toute la configuration tooling nécessaire pour que les features suivantes puissent être développées dans un environnement stable, typé et testé.
+
+## Scope
+
+- `package.json` avec toutes les dépendances (prod + dev)
+- `tsconfig.json` : strict, ESM, `noUncheckedIndexedAccess`, path alias `@/` → `src/`
+- `.env.example` : toutes les variables documentées
+- `Dockerfile` multi-stage (build + runtime Node 22 slim)
+- `.dockerignore`
+- `vitest.config.ts`
+- `.eslintrc` (ou `eslint.config.mjs`) avec règles TypeScript strict
+- `.prettierrc`
+- Structure de dossiers vide (`src/domain/`, `src/application/`, `src/infrastructure/`, `src/config/`, `docs/schemas/`)
+
+## Dépendances à installer
+
+### Production
+
+```
+@slack/bolt
+@anthropic-ai/sdk
+pg
+zod
+pino
+```
+
+### Dev
+
+```
+typescript
+tsx
+vitest
+@types/node
+@types/pg
+eslint
+@typescript-eslint/eslint-plugin
+@typescript-eslint/parser
+prettier
+```
+
+## Scripts `package.json`
+
+```json
+{
+  "dev": "tsx watch src/main.ts",
+  "build": "tsc",
+  "start": "node dist/main.js",
+  "test": "vitest run",
+  "test:watch": "vitest",
+  "lint": "eslint src",
+  "typecheck": "tsc --noEmit"
+}
+```
+
+## `tsconfig.json` — points clés
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "paths": { "@/*": ["./src/*"] },
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}
+```
+
+## Dockerfile — structure attendue
+
+```dockerfile
+FROM node:22-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-slim AS runtime
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/docs ./docs
+ENV NODE_ENV=production
+CMD ["node", "dist/main.js"]
+```
+
+## Acceptance Criteria
+
+- [ ] `yarn typecheck` passe sans erreur sur un `src/main.ts` vide
+- [ ] `yarn test` passe (0 tests = succès)
+- [ ] `yarn lint` passe sans erreur
+- [ ] `yarn build` produit un `dist/` valide
+- [ ] `docker build .` réussit
+- [ ] Structure de dossiers conforme au plan

package/.tasks/F2-domain-layer.md

@@ -0,0 +1,173 @@
+---
+title: "F2 — Domain Layer"
+type: feature
+status: todo
+prd: .tasks/PRD.md
+depends_on: F1
+---
+
+# F2 — Domain Layer
+
+## Objectif
+
+Implémenter la couche domain pure : entités, value objects immuables, erreurs typées et ports (interfaces). Aucun import externe sauf `zod`. Tout doit être testable sans mock.
+
+## Fichiers à créer
+
+### Entities (`src/domain/entities/`)
+
+**`Conversation.ts`** — Aggregate root (thread)
+- Propriétés : `threadId: ThreadId`, `messages: ConversationMessage[]`
+- Invariants : max `CONVERSATION_MAX_MESSAGES` messages (LRU — purge les plus anciens)
+- Méthodes : `append(message): Conversation`, `purge(): Conversation`
+- Constructeur privé + factory statique `create(threadId): Conversation`
+
+**`ConversationMessage.ts`** — Entity
+- Propriétés : `role: 'user' | 'assistant'`, `content: string`, `timestamp: Date`
+- Constructeur privé + factory `create(role, content): ConversationMessage`
+
+**`QueryResult.ts`** — Value object (résultat SQL)
+- Propriétés : `columns: string[]`, `rows: Record<string, unknown>[]`, `rowCount: number`
+- Constructeur privé + factory `create(columns, rows): QueryResult`
+
+### Value Objects (`src/domain/value-objects/`)
+
+**`ThreadId.ts`** — branded string
+```typescript
+type ThreadId = string & { readonly __brand: 'ThreadId' };
+// factory: ThreadId.create(raw: string): ThreadId
+```
+
+**`Question.ts`** — texte + flags parsés
+- Propriétés : `raw: string`, `text: string` (stripped), `flags: QuestionFlags`
+- Factory `create(raw: string): Question` — délègue le parsing à `QuestionFlags`
+
+**`QuestionFlags.ts`** — flags extraits du texte
+- Propriétés : `showSql: boolean`, `debug: boolean`, `noContext: boolean`
+- Factory `parse(text: string): QuestionFlags` — regex sur `--sql`, `--debug`, `--no-context`
+
+**`SqlQuery.ts`** — SQL validé, constructeur privé
+```typescript
+class SqlQuery {
+  private constructor(public readonly raw: string) {}
+  static create(raw: string, validator: SqlValidator): SqlQuery {
+    return new SqlQuery(validator.validate(raw));
+  }
+}
+```
+
+**`LLMProviderName.ts`** — enum
+```typescript
+enum LLMProviderName { ANTHROPIC = 'anthropic', OPENAI = 'openai' }
+```
+
+**`ResponseRendering.ts`** — enum
+```typescript
+enum ResponseRendering { TEXT = 'TEXT', TABLE = 'TABLE', CSV = 'CSV' }
+```
+
+### Errors (`src/domain/errors/`)
+
+**`DomainError.ts`** — base abstraite
+```typescript
+abstract class DomainError extends Error {
+  abstract readonly code: string;
+}
+```
+
+**`InvalidSqlError.ts`** — SQL refusé par le validator
+**`SqlExecutionError.ts`** — erreur PG à l'exécution
+**`LLMError.ts`** — erreur API LLM
+**`SchemaLoadError.ts`** — échec lecture docs/schemas (fatal au boot)
+**`AgentLoopExceededError.ts`** — MAX_TURNS atteint
+
+### Ports (`src/domain/ports/`)
+
+**`LLMProvider.ts`**
+```typescript
+interface LLMProvider {
+  generate(request: LLMRequest): Promise<LLMResponse>;
+}
+// types LLMRequest, LLMResponse, LLMToolUse définis ici
+```
+
+**`SqlExecutor.ts`**
+```typescript
+interface SqlExecutor {
+  execute(query: SqlQuery): Promise<QueryResult>;
+}
+```
+
+**`SqlValidator.ts`**
+```typescript
+interface SqlValidator {
+  validate(raw: string): string; // retourne SQL nettoyé ou throw InvalidSqlError
+}
+```
+
+**`ConversationRepository.ts`**
+```typescript
+interface ConversationRepository {
+  get(threadId: ThreadId): Promise<Conversation | null>;
+  save(conversation: Conversation): Promise<void>;
+  purge(threadId: ThreadId): Promise<void>;
+}
+```
+
+**`SchemaCatalog.ts`**
+```typescript
+interface SchemaCatalog {
+  getDocumentation(): string;
+}
+```
+
+**`SlackMessenger.ts`**
+```typescript
+interface SlackMessenger {
+  post(threadId: ThreadId, text: string): Promise<void>;
+  postCsv(threadId: ThreadId, text: string, csvBuffer: Buffer, filename: string): Promise<void>;
+}
+```
+
+**`AdminLogger.ts`**
+```typescript
+interface AdminLogger {
+  logQuery(entry: AdminLogEntry): Promise<void>;
+}
+// type AdminLogEntry: { userId, question, sqls, rowCount, durationMs, inputTokens, outputTokens }
+```
+
+**`Logger.ts`**
+```typescript
+interface Logger {
+  debug(msg: string, meta?: object): void;
+  info(msg: string, meta?: object): void;
+  warn(msg: string, meta?: object): void;
+  error(msg: string, meta?: object): void;
+}
+```
+
+## Tests unitaires (`src/domain/__tests__/`)
+
+**`Conversation.test.ts`**
+- `append` plafonne à `CONVERSATION_MAX_MESSAGES` messages (purge les plus anciens)
+- `purge` retourne une conversation vide
+- Constructeur privé — impossible d'instancier directement
+
+**`Question.test.ts`**
+- Strip de mention `<@U123>` du texte
+- Parsing de `--sql`, `--debug`, `--no-context`
+- Flags corrects quand aucun flag présent
+
+**`SqlQuery.test.ts`**
+- Impossible de créer un `SqlQuery` sans passer par le validator
+- `SqlQuery.create` appelle `validator.validate` avec le SQL brut
+- L'instance expose `.raw` avec le SQL retourné par le validator
+
+## Acceptance Criteria
+
+- [ ] `yarn typecheck` passe
+- [ ] `yarn test` : tous les tests domain passent
+- [ ] Aucun import externe dans `src/domain/` sauf `zod` (si utilisé pour validation interne)
+- [ ] `SqlQuery` n'est instanciable que via `SqlQuery.create(raw, validator)`
+- [ ] `DomainError` est la base de toutes les erreurs du projet

package/.tasks/F3-application-layer.md

@@ -0,0 +1,166 @@
+---
+title: "F3 — Application Layer"
+type: feature
+status: todo
+prd: .tasks/PRD.md
+depends_on: F2
+---
+
+# F3 — Application Layer
+
+## Objectif
+
+Implémenter les use cases, la boucle agentique et les formatters de réponse. Cette couche orchestre le domain sans dépendre d'aucun SDK tiers — uniquement des ports définis dans `src/domain/ports/`.
+
+## Fichiers à créer
+
+### Use Cases (`src/application/usecases/`)
+
+**`ParseQuestion.ts`**
+- Input : `rawText: string` (message Slack brut)
+- Output : `Question`
+- Logique : strip `<@U…>` via regex, crée `Question.create(cleaned)`
+- Pas d'effet de bord, pas de dépendance externe
+
+**`AnswerQuestion.ts`** — Use case principal
+```typescript
+class AnswerQuestion {
+  constructor(
+    private readonly conversationRepository: ConversationRepository,
+    private readonly agentLoop: AgentLoop,
+    private readonly responseRenderer: ResponseRenderer,
+    private readonly slackMessenger: SlackMessenger,
+    private readonly adminLogger: AdminLogger,
+  ) {}
+
+  async execute(question: Question, threadId: ThreadId): Promise<void>
+}
+```
+Flow :
+1. `conversationRepository.get(threadId)` si `!question.flags.noContext`
+2. `agentLoop.run({ conversation, question })` → `AgentRunResult`
+3. `conversationRepository.save(updatedConversation)`
+4. `responseRenderer.render(agentRunResult)` → `RenderedResponse`
+5. `slackMessenger.post(threadId, ...)` ou `postCsv` selon le rendu
+6. `adminLogger.logQuery({ ... })`
+
+### Agent (`src/application/agent/`)
+
+**`AgentContext.ts`** — State mutable de la boucle
+- Propriétés : `messages: LLMMessage[]` (historique + tours courants)
+- Méthodes : `appendUserMessage(text)`, `appendAssistantMessage(response)`, `appendToolResult(toolUseId, result | error)`
+- Initialisé depuis la `Conversation` existante + la question courante
+
+**`AgentLoop.ts`** — Boucle `tool_use` → `end_turn`
+```typescript
+class AgentLoop {
+  constructor(
+    private readonly llmProvider: LLMProvider,
+    private readonly sqlValidator: SqlValidator,
+    private readonly sqlExecutor: SqlExecutor,
+    private readonly schemaCatalog: SchemaCatalog,
+    private readonly maxTurns: number,
+  ) {}
+
+  async run(params: { conversation: Conversation | null; question: Question }): Promise<AgentRunResult>
+}
+```
+Algorithme :
+```
+context = AgentContext.init(conversation, question)
+for (turn = 0; turn < maxTurns; turn++):
+  response = await llmProvider.generate({
+    system: SystemPromptBuilder.build(schemaCatalog.getDocumentation()),
+    messages: context.messages,
+    tools: [RunSqlTool.definition],
+  })
+  context.appendAssistantMessage(response)
+  if response.stopReason === 'end_turn':
+    return { finalText: response.text, sqls: context.executedSqls, queryResult: context.lastQueryResult }
+  if response.toolUse?.name === 'run_sql':
+    try:
+      query = SqlQuery.create(response.toolUse.input.sql, sqlValidator)
+      result = await sqlExecutor.execute(query)
+      context.appendToolResult(response.toolUse.id, result)
+      context.recordSql(query.raw, result)
+    catch (e):
+      context.appendToolResult(response.toolUse.id, e, isError: true)
+throw new AgentLoopExceededError(maxTurns)
+```
+
+**`tools/RunSqlTool.ts`** — Définition JSON du tool Anthropic
+```typescript
+const RunSqlTool = {
+  definition: {
+    name: 'run_sql',
+    description: 'Execute a read-only SQL SELECT query on the efarmz PostgreSQL databases.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        sql: { type: 'string', description: 'The SQL SELECT query to execute' },
+      },
+      required: ['sql'],
+    },
+  },
+} as const;
+```
+
+### Formatting (`src/application/formatting/`)
+
+**`ResponseRenderer.ts`** — Délègue aux renderers spécialisés
+```typescript
+class ResponseRenderer {
+  render(params: {
+    finalText: string;
+    queryResult: QueryResult | null;
+    executedSqls: string[];
+    flags: QuestionFlags;
+  }): RenderedResponse
+}
+// RenderedResponse = { text: string; csvBuffer?: Buffer; csvFilename?: string }
+```
+Décision :
+- Pas de `queryResult` → retourner `finalText` tel quel
+- 0 ligne → `"Aucun résultat."`
+- 1×1 → `ScalarRenderer`
+- ≤ `SQL_CSV_THRESHOLD` → `MonospaceTableRenderer`
+- > `SQL_CSV_THRESHOLD` → `MonospaceTableRenderer` (10 premières) + `CsvRenderer` → buffer
+
+**`ScalarRenderer.ts`**
+- Retourne `**{valeur}**` (valeur en gras Slack markdown)
+
+**`MonospaceTableRenderer.ts`**
+- Aligne les colonnes avec padding
+- Retourne un bloc code Slack ` ```\ncol1   col2\n...``` `
+- Tronque à N lignes si demandé
+
+**`CsvRenderer.ts`**
+- Génère un `Buffer` CSV (header + lignes, séparateur `,`, valeurs entre `"` si nécessaire)
+
+## Tests unitaires (`src/application/__tests__/`)
+
+**`ParseQuestion.test.ts`**
+- Strip `<@U123456>` du texte
+- Gère plusieurs mentions
+- Flags `--sql`, `--debug`, `--no-context` extraits correctement
+
+**`AgentLoop.test.ts`** (avec `FakeLLMProvider`)
+- `end_turn` immédiat → retourne `finalText`
+- 1 tour `run_sql` → appelle `sqlExecutor.execute`, puis `end_turn`
+- `run_sql` avec erreur SQL → `tool_result.is_error = true`, LLM reçoit l'erreur au tour suivant
+- `MAX_TURNS` atteint → throw `AgentLoopExceededError`
+
+**`ResponseRenderer.test.ts`** (sur fixtures)
+- 0 ligne → `"Aucun résultat."`
+- 1×1 → valeur en gras
+- 5 lignes → table monospace (pas de CSV)
+- 20 lignes → table tronquée + `csvBuffer` non-null
+- `--sql` → SQL ajouté en bas du message
+
+## Acceptance Criteria
+
+- [ ] `yarn typecheck` passe
+- [ ] `yarn test` : tous les tests application passent
+- [ ] Aucun import de SDK tiers dans `src/application/` (uniquement `src/domain/`)
+- [ ] `AgentLoop` ne throw jamais sur erreur SQL — renvoie toujours `tool_result.is_error`
+- [ ] `ResponseRenderer` couvre les 4 cas de rendu (0, scalar, table, CSV)