Merge pull request #38 from jmbish04/fix/lint-and-migrations

fix: resolve ESLint, TypeScript errors, and remote migration conflicts

Author: jmbish04

.agent/rules/agent-registry.md

@@ -0,0 +1,20 @@
+# Rule: Agent Registry and Dynamic UI
+
+## 1. Dynamic UI Consumption
+
+- Frontend agent selectors, wizards, and sidebars (e.g., `AgentSidebar.tsx`) **MUST NEVER** hardcode the list of available specialist agents.
+- All dynamic agent discovery must occur via the `GET /api/agents/specialists` REST endpoint. This ensures the backend remains the single source of truth for agent capabilities, routing, and availability.
+
+## 2. The Specialist Pattern
+
+- Avoid creating numerous bespoke subclasses of `HonoBaseAgent` (e.g., `DataAgent`, `UXAgent`, `SREAgent`) unless they require fundamentally distinct toolsets or event lifecycles.
+- Default to using **ONE** flexible `SpecialistAgent` class.
+- Dictate the specific persona dynamically at runtime by overriding the `systemPrompt` or passing a `specialty` configuration parameter when the frontend initiates the session.
+- **Why?** This prevents sprawling class files, keeps the agent execution logic DRY, and enables the system to spin up arbitrary expert subsets without code deployments.
+
+## 3. Plan Generation Output
+
+- The ultimate goal of a Workshop or Consultation flow is actionable output.
+- Specialist Agents should be equipped with a `save_plan(plan: JSON)` tool.
+- When the agent and user align on a roadmap, the agent must invoke `save_plan` to persist the structured JSON to the `projects`, `plans`, or `todos` table via Drizzle.
+- The UI should then react to this database mutation (e.g., by advancing the Wizard, redirecting to the Kanban board, or pushing a toast).

.agent/rules/ai-routing.md

@@ -0,0 +1,5 @@
+# AI Routing & Fallback Rules
+
+- **Silent Failures:** Never allow a third-party AI provider failure to crash the request if a `worker-ai` equivalent model can handle the prompt.
+- **Type Safety:** Do not alter the return types (`string`, `T`) of the core generation functions to include metadata. Always use the `onFallback` callback mechanism in `AIOptions` to bubble up execution state.
+- **Observability:** Every fallback event must be aggressively logged to D1 to track provider reliability and API Gateway latency over time.

.agent/rules/alerts-standards.md

@@ -0,0 +1,62 @@
+# Alerts Standards
+
+## 1. The `createAlert()` Contract
+
+Every new feature that may fail, produce notable events, or require user attention **MUST** emit alerts using the canonical `createAlert()` function:
+
+```typescript
+import { createAlert } from "@alerts";
+
+await createAlert(env, {
+  type: "deployment", // AlertType: health | webhook | security | deployment | agent | info
+  severity: "error", // AlertSeverity: info | warning | error | critical
+  title: "Deploy failed",
+  description: "Wrangler exited with code 1. Check logs.",
+  link_url: "/webhooks", // Optional deep-link (relative path)
+  process_origin: "DeployWorkflow", // Human-readable origin
+});
+```
+
+`createAlert()` is fire-and-forget: it never throws, never blocks the main thread, and auto-gates based on `ALERTS_CONFIG` in KV.
+
+## 2. When to Emit Alerts
+
+| Scenario                            | Type         | Severity              |
+| ----------------------------------- | ------------ | --------------------- |
+| Health check failure                | `health`     | `error` or `critical` |
+| Webhook delivery failure (repeated) | `webhook`    | `warning`             |
+| Detected secret leak                | `security`   | `critical`            |
+| Worker deploy failure               | `deployment` | `error`               |
+| Agent task failure after retries    | `agent`      | `error`               |
+| Informational system event          | `info`       | `info`                |
+
+Do **NOT** alert on:
+
+- Expected/transient 4xx responses
+- Individual tool-call retries (only alert on final failure)
+- Debug or verbose logs (use `console.log` / `@logging` for those)
+
+## 3. Config-Gated Alerts
+
+`createAlert()` reads `ALERTS_CONFIG` from `KV_CONFIGS` at emit time. If a type is disabled or the master switch is off, the alert is dropped silently. You do not need to check the config yourself — the service handles it.
+
+## 4. Path Alias
+
+Always use `@alerts` — never use a relative import:
+
+```typescript
+// ✅ Correct
+import { createAlert } from "@alerts";
+
+// ❌ Wrong
+import { createAlert } from "../../alerts";
+```
+
+## 5. New Alert Types
+
+If you need a new alert type (beyond the 6 built-in), you must:
+
+1. Add it to `ALERT_TYPES` in `backend/src/db/schemas/app/alerts.ts`
+2. Add it to `AlertTypeFlags` in `backend/src/alerts/config.ts`
+3. Add its `TYPE_META` entry in `AlertTray.tsx` and `Alerts.tsx`
+4. Run `pnpm drizzle-kit generate` if schema changed

.agent/rules/alerts.md

@@ -0,0 +1,16 @@
+# Rule: Notifications & Alerts
+
+## 1. Zero Native Alerts
+
+- **Forbidden**: You MUST NEVER use the native browser `alert()`, `confirm()`, or `prompt()` functions under any circumstances.
+- **Why**: Native alerts break the UI/UX consistency, block the main thread, and violate our \"True Dark\" and premium aesthetic standards.
+
+## 2. Sonner Toasts
+
+- **Required**: For all transient user notifications (success, error, info, loading), you MUST use `toast` from the `sonner` package.
+- **Implementation**:
+  - `import { toast } from \"sonner\";`
+  - Success: `toast.success(\"Message\");`
+  - Error: `toast.error(\"Message\");`
+  - Generic: `toast(\"Message\");`
+- Ensure that the notification is concise and actionable.

.agent/rules/cloudflare-deployments.md

@@ -0,0 +1,10 @@
+# .agent/rules/cloudflare-deployments.md
+
+## Rule: Large Bundle Deployment Protections
+
+When operating on Cloudflare Workers that exceed 5MB uncompressed:
+
+1. Always enable `minify = true` in `wrangler.jsonc`.
+2. Never rely on the default `wrangler deploy` CLI command directly if timeouts occur; wrap it in a Node script that overrides the `undici` global dispatcher timeout to at least 120,000ms.
+3. Inject `NODE_OPTIONS=--max-old-space-size=8192` to prevent heap exhaustion during `esbuild` minification phases.
+4. Ensure `compatibility_flags = ["nodejs_compat"]` is set and `node_compat = false` is enforced to prevent polyfill bloat.

.agent/rules/cloudflare-stack.md

@@ -0,0 +1,7 @@
+# Cloudflare & Stack Standards
+
+- **Routing:** Hono strictly typed with `@hono/zod-openapi` targeting OpenAPI v3.1.0.
+- **Data:** Drizzle ORM mapping to D1 SQLite. Complex nested arrays MUST use `text('col', { mode: 'json' }).$type<StrictInterface[]>()`.
+- **AI Execution:** Use `@google/genai` utilizing the `GEMINI_API_KEY` and the provided environment model name. Route base URLs through `https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/google-genai`.
+- **UI Styling:** React + Shadcn UI. Enforce Dark Theme default (`bg-slate-950`).
+- **Code Completeness:** Never truncate files. Generate full end-to-end code during every update pass.

.agent/rules/discord-cloudflare.md

@@ -0,0 +1,20 @@
+# Architecture Rules: Discord API on Cloudflare Workers
+
+## 1. Secrets Store Compliance
+
+Cloudflare Secrets Store requires all account-level secrets to be fetched asynchronously.
+
+- **Rule:** NEVER use synchronous mapping for Secret Store bindings.
+- **Enforcement:** Always use `await env.BINDING_NAME.get()`.
+- **Example:** `const token = await c.env.DISCORD_TOKEN.get();`
+
+## 2. Discord Bot Search Constraints
+
+Standard Discord Bot tokens cannot natively hit the `GET /guilds/{guild.id}/messages/search` API endpoint, as this is restricted to user contexts.
+
+- **Rule:** When executing cross-channel or thread search tasks, the agent MUST implement a map-reduce pattern locally on the Worker.
+- **Enforcement:** Fetch recent message batches from target channels/threads via `GET /channels/{id}/messages` and run local regex/string filtering to extract query matches.
+
+## 3. OpenAPI Standard
+
+All module expansions must utilize `@hono/zod-openapi` enforcing `openapi: 3.1.0`. Any newly added Discord interaction must map its return to a `z.object()` and expose it cleanly in the `/openapi.json` ledger.

.agent/rules/durable-object-agents.md

@@ -0,0 +1,7 @@
+# .agent/rules/durable-object-agents.md
+
+## Rules
+
+- **Dynamic Heavy SDKs:** Never statically import large orchestration libraries (like `@openai/agents` or `langchain`) at the top level of a Cloudflare Worker or Durable Object. Always use dynamic `import()` inside the execution method to preserve sub-50ms cold starts.
+- **Client Injection over Globals:** When executing an agent run via the OpenAI Agents SDK, ALWAYS inject the `client` explicitly into the `run()` options (e.g., `run(agent, prompt, { client })`). Never rely on global environment variables to implicitly configure the client.
+- **Prefix Namespacing:** Always format the model identifier as `${provider}/${model}` immediately prior to passing it into the `OpenAIAgent` constructor to ensure Cloudflare AI Gateway routes it correctly.

.agent/rules/jules.md

@@ -0,0 +1,22 @@
+# Rule: Jules Integration Maintenance
+
+## 1. Source of Truth
+
+- The central hub for all Jules interactions is `backend/src/routes/api/agents/jules.ts` and `backend/src/services/jules.ts`.
+- **DO NOT** create a new Jules router mapped elsewhere (such as `services/jules.ts`). Ensure `/api/agents/jules` is the canonical invocation endpoint.
+
+## 2. Invoking Jules
+
+- Clients use `/api/agents/jules/start` (or `/invoke`). You must pass `inject_standards: true` (default) to push `JULES_STANDARDS` alongside the prompt.
+- **Jobs and Sessions**: `julesSessions` tracks the state returned by `@google/jules-sdk`. `julesJobs` wraps tracking around full repository-bound interactions. Do not query Jules SDK polling functions from the frontend; use `get /api/agents/jules/status/:id` instead.
+
+## 3. Modifying Jules Code
+
+- **CRITICAL**: Anytime a change is made to any Jules related code (e.g., schemas, routes, services, or the sdk version), you MUST:
+  1. Update `AGENTS.md` to reflect new patterns or architecture updates if necessary.
+  2. Update this `.agent/rules/jules.md` file if any constraints or conventions change.
+  3. Ensure the frontend `Docs` page for Jules integration accurately reflects the state of the API.
+
+## 4. Workflows & Autonomy
+
+- Jules SDK runs synchronously within the environment. For detached executions, the user request can trigger `force_overseer: true`, which kicks off a workflow check via the `JulesOverseer` Durable Object Singleton.

.agent/rules/shadcn-mandatory.md

@@ -0,0 +1,39 @@
+---
+trigger: always_on
+---
+
+Shadcn + Astro + Worker Assets Standard Rule
+
+You must ALWAYS implement the frontend using the "Moody Modern" architectural pattern: Astro as the host, React for interactive islands, and Shadcn UI (Default Dark Theme) for all UI components.
+
+Mandatory Tech Stack
+
+Framework: Astro (latest) with @astrojs/react and @astrojs/cloudflare integrations.
+
+Styling: Tailwind CSS v4 using OKLCH color space.
+
+Components: Shadcn UI (Official) and Shadcn-compatible registries (e.g., kibo-ui, assistant-ui).
+
+Deployment: Cloudflare Worker Static Assets (Unified Main Worker + Assets directory).
+
+Backend: Hono with @hono/zod-openapi for typesafe API endpoints.
+
+Rule Enforcement
+
+Dark Theme: The <html> tag MUST have class="dark" by default. No light mode toggles unless explicitly requested.
+
+Hydration: All interactive components (Forms, Buttons, Modals, Nav) must be React components used as Astro islands with client:load or client:visible.
+
+No Raw HTML: Do not use raw HTML/Tailwind mockups for final output. Retrofit all plain mockups into Shadcn components (e.g., <div class="rounded-lg border..."> -> <Card>).
+
+Unified Routing: Every page must have its own dedicated .astro file in src/pages/ to support direct URL access and server-side refreshes.
+
+Types: Use wrangler types patterns. Never hand-write Environment bindings.
+
+Component Sourcing
+
+Use lucide-react for all iconography.
+
+Use recharts with Shadcn-specific configuration for data visualization.
+
+Use assistant-ui for all AI/Chat interfaces.