Merge pull request #9 from makoni/develop

Update configuration management and add new dependencies

Author: makoni

.github/copilot-instructions.md

@@ -0,0 +1,85 @@
+## Quick orientation
+
+This repository implements a Telegram bot that watches iOS App Store releases and notifies subscribers. The codebase is split into three logical modules:
+
+- `ReleaseInformerBot` (executable): main bot logic, Telegram handlers, Vapor app scaffolding — see `Sources/ReleaseInformerBot/configure.swift` and `Sources/ReleaseInformerBot/entrypoint.swift`.
+- `ReleaseWatcher` (service): background watcher that iterates subscriptions and sends notifications — see `Sources/ReleaseWatcher/ReleaseWatcher.swift`.
+- `Shared` (library): models and persistence helpers (CouchDB) — see `Sources/Shared/Managers/DBManager.swift` and `Sources/Shared/Models/Subscription.swift`.
+
+Read these files first to understand the end-to-end flow.
+
+## Big-picture data flow
+
+1. User sends command to the Telegram bot (handled by `BotHandlers` in `Sources/ReleaseInformerBot/TGBot/BotHandlers.swift`).
+2. Handlers call `DBManager` (`Sources/Shared/Managers/DBManager.swift`) to create/list/delete `Subscription` documents in CouchDB.
+3. `ReleaseWatcher` periodically fetches all subscriptions (`getAllSubscriptions()`), queries the iTunes API via `SearchManager` (`Sources/Shared/Managers/SearchManager.swift`) and updates subscriptions with new versions.
+4. When a new version is detected, `ReleaseWatcher` uses the `TGBot` instance (set in `configure.swift` via `BotActor`) to send formatted HTML messages.
+
+Key integration points: `DBManager` <-> CouchDB, `SearchManager` <-> iTunes API (https://itunes.apple.com), `AsyncHttpTGClient` <-> Telegram API.
+
+## Concurrency & runtime patterns to keep in mind
+
+- Actors are used heavily for thread-safety: `DBManager`, `SearchManager`, `ReleaseWatcher`, `BotActor`. Prefer `async/await` and actor isolation when changing shared state.
+- `ReleaseWatcher` uses two `DispatchSourceTimer`s: a 5-minute `timer` for bulk runs and a 2-second `appCheckTimer` that processes a queue; it enforces small delays (2s) between individual chat notifications.
+- The `entrypoint` contains commented-out code for attempting to install NIO as the global executor — be cautious if enabling it as it can change shutdown behavior.
+
+## Persistence and DB conventions
+
+- Database name: `release_bot` (hard-coded in `DBManager`).
+- `DBManager.setupIfNeed()` will create the DB and add a design doc with two views: `by_bundle` and `by_chat`. The design doc id is `_design/list`.
+- `Subscription` maps CouchDB keys with coding keys (bundle ID stored as `bundle_id`) — see `Sources/Shared/Models/Subscription.swift`.
+- When adding versions, the project keeps the last 5 versions (see `DBManager.addNewVersion(...)`).
+
+If you change the CouchDB credentials/host you must update `fileprivate let couchDBClient = CouchDBClient(...)` inside `DBManager.swift`.
+
+## Bot & Telegram specifics
+
+- Bot token is read from environment variable `apiKey` in `configure.swift`.
+- The project uses `SwiftTelegramSdk` and a custom `AsyncHttpTGClient` (`Sources/ReleaseInformerBot/TGBot/AsyncHttpTGClient.swift`) which:
+  - Defaults to multipart/form-data for most requests.
+  - Limits response body reads to ~1MB for Telegram responses.
+  - Throws a descriptive `BotError` when Telegram returns ok=false.
+- Messages use HTML parse mode; handlers build HTML strings (see `BotHandlers.makeSearchResultsMessage` and `makeListMessage`). Preserve HTML encoding when editing messages.
+
+## Search & iTunes quirks
+
+- `SearchManager` performs HTTP GETs against the iTunes Search/Lookup APIs and contains a `processJSONString(_:)` sanitiser that:
+  - Escapes control characters inside JSON strings
+  - Replaces non-breaking spaces
+  This behaviour exists because the iTunes API sometimes returns characters that break `JSONDecoder`. If you modify parsing, keep this sanitiser or add robust tests.
+
+## How to run, build, and test
+
+- Build: `swift build`
+- Run locally: set the Telegram token and run the executable:
+
+```bash
+export apiKey="<YOUR_TELEGRAM_BOT_TOKEN>"
+swift run
+```
+
+- Tests: `swift test` (tests use `Application.make(.testing)` from VaporTesting; see `Tests/ReleaseInformerBotTests/ReleaseInformerBotTests.swift`).
+
+Notes: CouchDB must be reachable for the app to initialize successfully; `DBManager.setupIfNeed()` will try to create DB and views on startup and will exit the process on failure (see `configure.swift`).
+
+## Common change patterns & examples
+
+- Adding a new bot command: implement a handler in `BotHandlers` and register it from `addHandlers(bot:)`.
+- To send a message from background code: obtain the `TGBot` via `BotActor` (see `configure.swift`) and call `bot.sendMessage(...)` from an async context.
+- To add a new view or query in CouchDB: add the JavaScript map to the design document in `DBManager.setupIfNeed()` and ensure any changes keep existing docs compatible.
+
+## Files to inspect when debugging
+
+- `Sources/ReleaseInformerBot/configure.swift` — initialization order (DB -> bot -> watchers -> routes)
+- `Sources/Shared/Managers/DBManager.swift` — DB access patterns and CouchDB client usage
+- `Sources/ReleaseWatcher/ReleaseWatcher.swift` — timers, run loop, and notification flow
+- `Sources/ReleaseInformerBot/TGBot/*` — bot client, handlers, and HTTP client
+
+## Quick tips for agents
+
+- Preserve actor isolation when editing shared state.
+- Respect the 2s sleeps used to rate-limit notifications in `ReleaseWatcher` and `BotHandlers` — removing them may trigger API rate limits.
+- When modifying message text, keep HTML tags and avoid unescaped user content.
+- Add unit tests for parsing changes in `SearchManager.processJSONString(_:)` when touching JSON handling.
+
+If anything here looks incomplete or you want more examples (e.g., an example test or a short diagram), tell me which area to expand. 

Package.resolved

@@ -4,7 +4,7 @@ import PackageDescription
 let package = Package(
     name: "ReleaseInformerBot",
     platforms: [
-       .macOS(.v13)
+        .macOS(.v15)
     ],
     dependencies: [
         // 💧 A server-side Swift web framework.
@@ -13,6 +13,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.65.0"),
         .package(url: "https://github.com/nerzh/swift-telegram-sdk.git", .upToNextMajor(from: "3.8.0")),
         .package(url: "https://github.com/makoni/couchdb-swift.git", from: "2.1.0"),
+        .package(url: "https://github.com/apple/swift-configuration", .upToNextMinor(from: "0.1.0")),
     ],
     targets: [
         .target(
@@ -35,6 +36,7 @@ let package = Package(
                 .product(name: "NIOCore", package: "swift-nio"),
                 .product(name: "NIOPosix", package: "swift-nio"),
                 .product(name: "SwiftTelegramSdk", package: "swift-telegram-sdk"),
+                .product(name: "Configuration", package: "swift-configuration"),
                 .target(name: "Shared"),
                 .target(name: "ReleaseWatcher")
             ]
@@ -44,6 +46,7 @@ let package = Package(
             dependencies: [
                 .target(name: "ReleaseInformerBot"),
                 .product(name: "VaporTesting", package: "vapor"),
+                .product(name: "Configuration", package: "swift-configuration"),
             ]
         )
     ]

Package.swift

@@ -53,6 +53,7 @@ The project uses carefully selected, production-grade dependencies:
 - **[Swift NIO](https://github.com/apple/swift-nio)** `2.65.0+` - Non-blocking networking foundation
 - **[SwiftTelegramSdk](https://github.com/nerzh/swift-telegram-sdk)** `3.8.0+` - Telegram Bot API client
 - **[CouchDB Swift](https://github.com/makoni/couchdb-swift)** `2.1.0+` - CouchDB client library
+- **[Swift Configuration](https://github.com/apple/swift-configuration)** `0.1.0+` - Unified configuration reader for environment variables and files
 
 ### Development Dependencies
 - **VaporTesting** - Testing utilities for Vapor applications
@@ -61,6 +62,7 @@ The project uses carefully selected, production-grade dependencies:
 
 ### Prerequisites
 - Swift 6.0+
+- macOS 15.0+ or Linux with Swift 6 toolchain
 - CouchDB instance (local or remote)
 - Telegram Bot Token (from [@BotFather](https://t.me/botfather))
 
@@ -72,9 +74,13 @@ The project uses carefully selected, production-grade dependencies:
    cd ReleaseInformerBot
    ```
 
-2. **Set environment variables**:
+2. **Set environment variables** (override as needed):
    ```bash
-   export apiKey="YOUR_TELEGRAM_BOT_TOKEN"
+   export TELEGRAM_API_KEY="YOUR_TELEGRAM_BOT_TOKEN"
+   export COUCH_HOST="127.0.0.1"
+   export COUCH_USER="admin"
+   export COUCH_PASSWORD=""
+   export COUCH_PORT=5984
    ```
 
 3. **Build and run**:
@@ -88,21 +94,60 @@ The project uses carefully selected, production-grade dependencies:
    swift test
    ```
 
+### Configuration
+
+The bot now uses [Swift Configuration](https://github.com/apple/swift-configuration) to resolve settings from multiple sources. The lookup order is:
+1. Environment variables (using uppercase keys such as `TELEGRAM_API_KEY` or `COUCH_HOST`)
+2. Optional JSON configuration file
+3. Hard-coded defaults
+
+Provide a JSON file at `config/config.json` (or set `RELEASE_INFORMER_CONFIG_PATH` to an absolute path) to manage settings locally:
+
+```json
+{
+   "telegram": {
+      "apiKey": "YOUR_TELEGRAM_BOT_TOKEN"
+   },
+   "couch": {
+      "protocol": "http",
+      "host": "127.0.0.1",
+      "port": 5984,
+      "user": "admin",
+      "password": "",
+      "requestsTimeout": 30
+   },
+   "runtime": {
+      "bootstrapServices": true
+   }
+}
+```
+
+Set `runtime.bootstrapServices` to `false` (default in `testing` environment) to skip bot initialization and external service connections while still registering routes.
+
 ### Production Configuration
 
 For production deployments, ensure:
 - Set `LOG_LEVEL=info` or `LOG_LEVEL=warning`
-- Configure CouchDB credentials in `DBManager.swift`
+- Provide CouchDB credentials via configuration (environment variables or JSON file)
 - Use proper secrets management for the Telegram bot token
 - Set up monitoring and health checks on port 8080
+- Ensure the `couchdb-swift_CouchDBClient.resources` bundle is deployed alongside the binary. When you build with SwiftPM (e.g., `swift build --swift-sdk x86_64-swift-linux-musl -c release`), copy both of these paths to the server directory where you host the executable:
+   - `.build/x86_64-swift-linux-musl/release/ReleaseInformerBot`
+   - `.build/x86_64-swift-linux-musl/release/couchdb-swift_CouchDBClient.resources`
+   A minimal deployment directory on the server should look like:
+   ```
+   /home/user/ReleaseInformerBot
+   ├── ReleaseInformerBot
+   └── couchdb-swift_CouchDBClient.resources/
+   ```
 
 ## CouchDB Setup
 
 The bot will automatically create the required CouchDB database (`release_bot`) and design document with the necessary views on startup.
 
 **Automatic Setup:**
 
-- The `DBManager` includes a `setupIfNeed()` method that checks for the existence of the database and required views, and creates them if they do not exist. No manual setup is required for most users—just ensure your CouchDB instance is running and credentials are configured in `DBManager.swift`.
+- The `DBManager` includes a `setupIfNeed()` method that checks for the existence of the database and required views, and creates them if they do not exist. No manual setup is required for most users—just ensure your CouchDB instance is running and credentials are provided through configuration.
 
 **Manual Setup (optional):**
 

README.md

@@ -14,14 +14,14 @@ import Logging
 let searchManager = SearchManager()
 
 final class BotHandlers {
-	static func addHandlers(bot: TGBot) async {
+	static func addHandlers(bot: TGBot, dbManager: DBManager) async {
 		await help(bot: bot)
-		await list(bot: bot)
+		await list(bot: bot, dbManager: dbManager)
 		await search(bot: bot)
-		await add(bot: bot)
-		await del(bot: bot)
+		await add(bot: bot, dbManager: dbManager)
+		await del(bot: bot, dbManager: dbManager)
 		await commandShowButtonsHandler(bot: bot)
-		await buttonsActionHandler(bot: bot)
+		await buttonsActionHandler(bot: bot, dbManager: dbManager)
 	}
 
 	private static func help(bot: TGBot) async {
@@ -31,11 +31,10 @@ final class BotHandlers {
 			})
 	}
 
-	private static func list(bot: TGBot) async {
+	private static func list(bot: TGBot, dbManager: DBManager) async {
 		await bot.dispatcher.add(
 			TGCommandHandler(commands: ["/list"]) { update in
 				guard let chatID = update.message?.chat.id else { return }
-
 				var subscriptions = try await dbManager.search(byChatID: chatID)
 
                 if subscriptions.count > 10 {
@@ -76,7 +75,7 @@ final class BotHandlers {
 			})
 	}
 
-	private static func del(bot: TGBot) async {
+	private static func del(bot: TGBot, dbManager: DBManager) async {
 		await bot.dispatcher.add(
 			TGCommandHandler(commands: ["/del"]) { update in
 				guard let chatID = update.message?.chat.id else { return }
@@ -94,7 +93,7 @@ final class BotHandlers {
 			})
 	}
 
-	private static func add(bot: TGBot) async {
+	private static func add(bot: TGBot, dbManager: DBManager) async {
 		await bot.dispatcher.add(
 			TGCommandHandler(commands: ["/add"]) { update in
 				guard let chatID = update.message?.chat.id else { return }
@@ -138,7 +137,7 @@ final class BotHandlers {
 			})
 	}
 
-	private static func buttonsActionHandler(bot: TGBot) async {
+	private static func buttonsActionHandler(bot: TGBot, dbManager: DBManager) async {
 		await bot.dispatcher.add(
 			TGCallbackQueryHandler(pattern: "help") { update in
 				bot.log.info("help")