chore: upgrade dependencies and migrate to ESLint v9

[shuhuiluo]

ESLint v9 migration:

• Replace .eslintrc.cjs with eslint.config.js (flat config format)
• Add typescript-eslint, @eslint/js, @eslint/eslintrc, eslint-formatter-unix

Dependency updates:

• eslint: ^8.57.1 → ^9.39.1
• @towns-protocol/bot|proto|web3: ^0.0.414 → ^0.0.427
• hono: ^4.7.11 → ^4.10.7
• viem: ^2.29.3 → ^2.40.3
• zod: ^4.1.12 → ^4.1.13
• @types/node: ^20.14.8 → ^24.10.1
• prettier: ^3.6.2 → ^3.7.3
• eslint-plugin-tsdoc: ^0.3.0 → ^0.5.0

SDK breaking changes:

• bot.start() now returns Hono app directly (handles webhook/metadata internally)
• Remove manual /webhook and /.well-known/agent-metadata.json routes

Other:

• Bump bun version: 1.3.0 → 1.3.3
• Reorder README sections (Usage before Setup)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Enhanced README with a comprehensive Usage section (subscriptions, queries, events, delivery modes) and removed duplicated content.

• Chores

  • Updated runtime/developer tool versions and ESLint setup.
  • Bumped runtime/tooling versions.
  • Adjusted TypeScript config to change available global typings.

• Behavior

  • Simplified app bootstrap and adjusted routes/asset serving; some webhook/metadata endpoints removed.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This pull request replaces the legacy CommonJS ESLint config (.eslintrc.cjs removed) with a new flat configuration (eslint.config.js), updates multiple dependencies (ESLint/TS toolchain, runtime and libs), bumps Bun version (.bun-version), modifies tsconfig.json to remove Node types, refactors application bootstrap in src/index.ts to use bot.start() and consolidates routing/static asset handling, and updates README content by consolidating and expanding the Usage section. No exported/public API signatures were added or removed.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

• Changes are heterogeneous: config format migration, dependency upgrades, runtime/type changes, application bootstrap refactor, and documentation updates.
• Areas requiring extra attention:
  • eslint.config.js vs removed .eslintrc.cjs: verify rule semantics and plugin/resolver settings match intended behavior.
  • package.json dependency bumps: confirm compatibility (ESLint/TS toolchain, Prettier, plugins) and adjust CI/tooling if needed.
  • src/index.ts refactor to bot.start(): validate route registration, middleware behavior, and removed endpoints (webhook/metadata) are intentional.
  • tsconfig.json types removal: ensure no unresolved type errors where Node types were previously relied upon.
  • README changes: check examples/docs reflect current app behavior (especially subscription/webhook vs polling notes).

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main objective: upgrading dependencies and migrating to ESLint v9, which is the primary focus of this pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/dep

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0f36e51 and bf8d14b.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (3)

• eslint.config.js (1 hunks)
• package.json (1 hunks)
• tsconfig.json (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• eslint.config.js

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: shuhuiluo
Repo: HereNotThere/bot-github PR: 26
File: src/github-app/app.ts:1-3
Timestamp: 2025-11-17T23:50:17.552Z
Learning: The HereNotThere/bot-github project uses Bun as its package manager, with dependencies locked in bun.lock rather than package-lock.json.

📚 Learning: 2025-11-25T03:24:12.463Z

Learnt from: CR
Repo: HereNotThere/bot-github PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T03:24:12.463Z
Learning: Applies to **/*.ts : Include required environment variables: APP_PRIVATE_DATA (bot credentials) and JWT_SECRET (webhook security token)

Applied to files:

• package.json

📚 Learning: 2025-11-17T23:50:17.552Z

Learnt from: shuhuiluo
Repo: HereNotThere/bot-github PR: 26
File: src/github-app/app.ts:1-3
Timestamp: 2025-11-17T23:50:17.552Z
Learning: The HereNotThere/bot-github project uses Bun as its package manager, with dependencies locked in bun.lock rather than package-lock.json.

Applied to files:

• package.json
• tsconfig.json

🔇 Additional comments (6)

tsconfig.json (1)

22-22: Verify Node type definitions are still available for Node.js packages.

Removing "node" from the types array while the project depends on Node.js packages (@octokit/app, @octokit/rest, @octokit/webhooks, postgres, drizzle-orm) may break type inference. Even with Bun as the runtime, these packages are designed for Node.js and likely require Node types.

Please verify that:

1. @types/node has not been removed from devDependencies in package.json
2. Type checking still works correctly for Node.js packages after this change
3. The linting and build steps (npm run build and npm run lint) pass without type errors

If @types/node was intentionally removed, ensure the @types/bun types provide sufficient coverage for all Node.js APIs used by the dependencies.

package.json (5)

54-54: Clarify TypeScript version pinning strategy.

Line 54 pins TypeScript to ~5.8.3 (patch-level) instead of the more common ^5.8.3 (minor-level). This is an unusually restrictive constraint that will prevent patch updates.

Confirm this is intentional. If not, consider relaxing to ^5.8.3 to allow patch-level updates and bug fixes:

-    "typescript": "~5.8.3",
+    "typescript": "^5.8.3",

---

36-37: ESLint v9 flat config packages look correct.

The additions of @eslint/eslintrc, @eslint/js, typescript-eslint, and eslint-formatter-unix align properly with the ESLint v9 flat config migration. The eslint-formatter-unix package correctly supports the --format unix flag used in the lint scripts.

Also applies to: 45-45, 47-47, 55-55

---

25-27: Verify runtime dependencies for breaking changes from SDK updates.

The runtime dependency updates include @towns-protocol packages (0.0.414 → 0.0.427), hono (4.7.11 → 4.10.7), and viem (2.29.3 → 2.40.3). Per the PR objectives, there are documented SDK breaking changes (bot.start() API changes). Ensure these version bumps align with the expected breaking changes and that src/index.ts correctly uses the new APIs.

Confirm that the refactored src/index.ts properly implements the new bot.start() behavior and handles any breaking changes from these dependency updates.

Also applies to: 29-29, 32-33

---

51-51: eslint-plugin-tsdoc v0.5.0 is compatible with ESLint v9, but requires proper configuration.

The update to eslint-plugin-tsdoc v0.5.0 is supported in ESLint v9 environments. However, since this plugin does not provide a native flat-config export, the eslint.config.js must use either FlatCompat from @eslint/eslintrc or manually register the plugin in the flat config object. Ensure the eslint configuration file handles the legacy plugin API appropriately.

---

36-55: @types/node removal is safe in this project.

The devDependencies no longer includes @types/node as a direct dependency. However, this is not a breaking change: @types/bun v1.3.3 (already in devDependencies) re-exports @types/node, making Node.js types available indirectly. Additionally, the affected runtime packages—postgres and drizzle-orm—include bundled TypeScript type definitions, so they don't depend on @types/node to function correctly. The tsconfig.json's moduleResolution: "bundler" and skipLibCheck: true properly support these bundled types.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

package.json (1)

40-41: Consider aligning @types/node with Bun's Node.js compatibility level.

"The major version and minor version tagged in the semver string of @types/node is exactly corresponding to the node's version." Since this project uses Bun (based on learnings), "Node LTS is at major 22 but 24 is already out", and @types/node v24 corresponds to Node.js v24 APIs.

Bun's Node.js compatibility may not cover all Node.js v24 APIs. If you encounter type errors for APIs Bun doesn't support, consider pinning to @types/node@^22 instead.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between be06fbb and 0f36e51.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (6)

• .bun-version (1 hunks)
• .eslintrc.cjs (0 hunks)
• README.md (1 hunks)
• eslint.config.js (1 hunks)
• package.json (1 hunks)
• src/index.ts (1 hunks)

💤 Files with no reviewable changes (1)

• .eslintrc.cjs

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Provide alt text for image attachments and use appropriate MIME types for chunked attachments (videos, screenshots)

Files:

• eslint.config.js
• src/index.ts

**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

**/*.ts: Store context externally - maintain stateless bot architecture with no message history, thread context, or conversation memory
Use <@{userId}> for mentions in messages AND add mentions in sendMessage options - do not use @username format
Implement event handlers for onMessage, onSlashCommand, onReaction, onTip, and onInteractionResponse to respond to Towns Protocol events
Define slash commands in src/commands.ts as a const array with name and description properties, then register handlers using bot.onSlashCommand()
Set ID in interaction requests and match ID in responses to correlate form submissions, button clicks, and transaction/signature responses
Use readContract for reading smart contract state, writeContract for SimpleAccount operations, and execute() for external contract interactions
Fund bot.appAddress (Smart Account) for on-chain operations, not bot.botId (Gas Wallet/EOA)
Use bot.* handler methods directly (outside event handlers) for unprompted messages via webhooks, timers, or tasks - requires channelId, spaceId, or other context stored externally
Always check permissions using handler.hasAdminPermission() before performing admin operations like ban, redact, or pin
User IDs are hex addresses in format 0x..., not usernames - use them consistently throughout event handling and message sending
Slash commands do not trigger onMessage - register slash command handlers using bot.onSlashCommand() instead
Use getSmartAccountFromUserId() to retrieve a user's wallet address from their userId
Include required environment variables: APP_PRIVATE_DATA (bot credentials) and JWT_SECRET (webhook security token)

Files:

• src/index.ts

🧠 Learnings (3)

📓 Common learnings

Learnt from: shuhuiluo
Repo: HereNotThere/bot-github PR: 26
File: src/github-app/app.ts:1-3
Timestamp: 2025-11-17T23:50:17.552Z
Learning: The HereNotThere/bot-github project uses Bun as its package manager, with dependencies locked in bun.lock rather than package-lock.json.

📚 Learning: 2025-11-25T03:24:12.463Z

Learnt from: CR
Repo: HereNotThere/bot-github PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T03:24:12.463Z
Learning: Applies to **/*.ts : Include required environment variables: APP_PRIVATE_DATA (bot credentials) and JWT_SECRET (webhook security token)

Applied to files:

• package.json

📚 Learning: 2025-11-17T23:50:17.552Z

Learnt from: shuhuiluo
Repo: HereNotThere/bot-github PR: 26
File: src/github-app/app.ts:1-3
Timestamp: 2025-11-17T23:50:17.552Z
Learning: The HereNotThere/bot-github project uses Bun as its package manager, with dependencies locked in bun.lock rather than package-lock.json.

Applied to files:

• package.json

🔇 Additional comments (7)

.bun-version (1)

1-1: LGTM!

Bun version bump to 1.3.3 aligns with the @types/bun version in package.json.

README.md (1)

39-109: LGTM!

Documentation is well-structured with clear command examples, event types, and delivery mode explanations. Moving Usage before Setup improves the reader experience by showing what the bot does before explaining how to set it up.

eslint.config.js (1)

52-86: Rules configuration looks reasonable for the project.

The configuration appropriately:

• Enforces Prettier formatting
• Uses underscore pattern for unused variables
• Allows flexibility in template expressions
• Provides TSDoc syntax warnings

The relaxed type-safety rules (no-explicit-any, no-unsafe-assignment) are a conscious trade-off for development velocity in this bot application.

package.json (3)

25-33: LGTM!

Dependency updates are well-coordinated:

• Towns Protocol packages updated together to ^0.0.427
• Hono, viem, and zod updated to current versions
• Zod remains at v4, utilizing the unified error customization and other v4 features per the library documentation

---

36-56: ESLint v9 migration tooling looks complete.

All necessary packages for ESLint v9 flat config are included:

• @eslint/js and @eslint/eslintrc for base configurations
• typescript-eslint for TypeScript support
• eslint-formatter-unix for the lint script output format
• Updated @typescript-eslint/* packages to v8.48.1 for ESLint v9 compatibility

---

40-41: No issues with @types/node v24 upgrade.

@types/node v24 aligns with Bun's current Node.js v24 compatibility. The project correctly configures both @types/node and @types/bun in tsconfig.json with skipLibCheck enabled, which prevents type conflicts between the two packages. This is a valid and expected setup for Bun projects.

src/index.ts (1)

169-178: LGTM! The migration to bot.start() aligns with the SDK update (^0.0.427), which now returns the Hono app directly. The static asset serving configuration correctly rewrites /assets/* paths to serve from the ./assets directory root, and the architecture maintains the stateless bot pattern with proper event handler registration.