Skip to content

Commit 726d622

Browse files
Copilotchitcommit
Copilot
and
chitcommit
authored
Set up GitHub Copilot coding agent instructions (#14)
* Initial plan * feat: add .github/copilot-instructions.md with repository-specific Copilot guidance Co-authored-by: chitcommit <208086304+chitcommit@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: chitcommit <208086304+chitcommit@users.noreply.github.com>
1 parent 15d36fe commit 726d622

1 file changed

Lines changed: 174 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# GitHub Copilot Instructions — ChittyCommand
2+
3+
## Project Overview
4+
5+
ChittyCommand is a unified life management and action dashboard for the ChittyOS ecosystem. It ingests data from 15+ financial, legal, and administrative sources, scores urgency with AI, recommends actions, and executes them via APIs, email, or browser automation.
6+
7+
- **Repo:** `CHITTYOS/chittycommand`
8+
- **Deploy:** Cloudflare Workers at `command.chitty.cc`
9+
- **Stack:** Hono (TypeScript), React + Tailwind (frontend), Neon PostgreSQL via Hyperdrive, Cloudflare R2/KV
10+
- **Canonical URI:** `chittycanon://core/services/chittycommand` | Tier 5
11+
12+
## Common Commands
13+
14+
```bash
15+
npm run dev # Start Hono dev server (wrangler dev)
16+
npm run build # Typecheck (tsc --noEmit)
17+
npm run test # Run Vitest tests
18+
npm run deploy # Deploy to Cloudflare Workers
19+
npm run ui:dev # Start React frontend (localhost:5173)
20+
npm run ui:build # Build frontend for Cloudflare Pages
21+
npm run db:generate # Generate Drizzle migrations
22+
npm run db:migrate # Run Drizzle migrations
23+
```
24+
25+
Secrets are managed via `wrangler secret put` — **never hardcode** them:
26+
27+
```bash
28+
wrangler secret put PLAID_CLIENT_ID
29+
wrangler secret put PLAID_SECRET
30+
wrangler secret put DATABASE_URL
31+
```
32+
33+
## Architecture
34+
35+
Single Cloudflare Worker serving API + scheduled cron jobs. Frontend is a separate React SPA (Cloudflare Pages) at `app.command.chitty.cc`.
36+
37+
### Key Files
38+
39+
- `src/index.ts` — Hono app entry point, route mounting, CORS, error handler
40+
- `src/middleware/auth.ts` — Three auth middlewares: `authMiddleware`, `bridgeAuthMiddleware`, `mcpAuthMiddleware`
41+
- `src/db/schema.ts` — Drizzle ORM schema (all tables prefixed `cc_`)
42+
- `src/lib/cron.ts` — Cron sync orchestrator
43+
- `src/lib/integrations.ts` — Service clients (Mercury, Plaid, ChittyScrape, etc.)
44+
- `src/lib/urgency.ts` — Deterministic urgency scoring (0–100)
45+
- `src/lib/validators.ts` — Zod schemas for all request validation
46+
- `src/routes/` — Route handlers (one file per domain)
47+
- `src/routes/bridge/` — Inter-service bridge routes
48+
- `src/routes/mcp.ts` — MCP server (28 tools for Claude integration)
49+
- `migrations/` — SQL migration files (0001–0007)
50+
- `ui/` — React frontend (Vite + Tailwind)
51+
52+
## Code Conventions
53+
54+
### TypeScript
55+
56+
- Strict mode is enabled (`"strict": true`). No `any` unless explicitly cast.
57+
- Target: `ES2022`. Module resolution: `bundler`.
58+
- All Hono apps/routes are typed: `new Hono<{ Bindings: Env; Variables: AuthVariables }>()`.
59+
- Import `AuthVariables` from `src/middleware/auth.ts` for route-level context variables.
60+
- Use `c.set('userId', ...)` and `c.get('userId')` for auth context in middleware and handlers.
61+
62+
### Database (Drizzle ORM)
63+
64+
- All tables are prefixed `cc_` (e.g., `cc_accounts`, `cc_obligations`).
65+
- Use `uuid` PKs with `.defaultRandom()`.
66+
- Always include `createdAt` and `updatedAt` timestamps with `{ withTimezone: true }`.
67+
- Add `index()` on columns used in WHERE/ORDER BY clauses.
68+
- Monetary values use `numeric` with `{ precision: 12, scale: 2 }`.
69+
- Use `jsonb` for flexible metadata fields, default to `{}` or `[]`.
70+
- Import `getDb` from `src/lib/db.ts` to get a database connection.
71+
72+
### Validation (Zod)
73+
74+
- Define all Zod schemas in `src/lib/validators.ts`.
75+
- Use `@hono/zod-validator` with `zValidator('json', schema)` for request body validation.
76+
- Validate query params with `zValidator('query', schema)`.
77+
- Date strings must match `/^\d{4}-\d{2}-\d{2}$/` (YYYY-MM-DD).
78+
- UUID fields use `z.string().uuid()`.
79+
80+
### Routing (Hono)
81+
82+
- Create one route file per domain in `src/routes/`.
83+
- Export a named `const xxxRoutes = new Hono()` from each file.
84+
- Mount routes in `src/index.ts` using `app.route('/api/xxx', xxxRoutes)`.
85+
- Apply auth middleware at mount time in `src/index.ts`, not inside route files.
86+
- Always return `c.json(...)` — never return raw strings or untyped responses.
87+
88+
### Error Handling
89+
90+
- Use the global error handler in `src/index.ts` for unhandled errors — it returns `{ error: 'Internal Server Error' }`, never leaking internals.
91+
- Return `c.json({ error: '...' }, 4xx)` for expected client errors.
92+
- Catch fetch errors in try/catch; fall through gracefully rather than bubbling errors.
93+
94+
## Auth Patterns
95+
96+
Three auth layers — **do not bypass or modify without security review**:
97+
98+
1. **`authMiddleware`** (`/api/*`) — KV token lookup, then ChittyAuth fallback. Sets `userId` and `scopes`.
99+
2. **`bridgeAuthMiddleware`** (`/api/bridge/*`) — KV service token (`bridge:service_token`) OR user token.
100+
3. **`mcpAuthMiddleware`** (`/mcp/*`) — ChittyAuth token first, KV service token fallback (`mcp:service_token`). Bypassed in non-production environments.
101+
102+
Access auth context in handlers via `c.get('userId')` and `c.get('scopes')`.
103+
104+
## Security Requirements
105+
106+
- **Never hardcode** secrets, tokens, API keys, or credentials anywhere in source code.
107+
- All secrets go through `wrangler secret put` — never in `[vars]` in `wrangler.toml`.
108+
- KV service tokens: `bridge:service_token`, `mcp:service_token`, `scrape:service_token`.
109+
- CORS is restricted to approved origins: `app.command.chitty.cc`, `command.mychitty.com`, `chittycommand-ui.pages.dev`, `localhost:5173`.
110+
- Credentials use 1Password (`op run`) in local development — never expose in terminal output or logs.
111+
- Error responses must **not** leak internal error messages, stack traces, or sensitive data.
112+
- All user input must be validated with Zod before use.
113+
- Use `X-Source-Service: chittycommand` header on all outbound service calls.
114+
115+
## Environment Bindings (Cloudflare Workers)
116+
117+
Available via `c.env` in route handlers and middleware:
118+
119+
| Binding | Type | Purpose |
120+
|---------|------|---------|
121+
| `HYPERDRIVE` | Hyperdrive | Neon PostgreSQL connection |
122+
| `DOCUMENTS` | R2Bucket | Document storage |
123+
| `COMMAND_KV` | KVNamespace | Auth tokens, sync state, service tokens |
124+
| `AI` | Ai | Cloudflare AI Gateway |
125+
| `ENVIRONMENT` | string | `"production"` or `"development"` |
126+
| `CHITTYAUTH_URL` | string | ChittyAuth service URL |
127+
| `CHITTYLEDGER_URL` | string | ChittyLedger service URL |
128+
| `CHITTYFINANCE_URL` | string | ChittyFinance service URL |
129+
| `CHITTYSCRAPE_URL` | string | ChittyScrape service URL |
130+
| `CHITTYCONNECT_URL` | string | ChittyConnect service URL |
131+
| `PLAID_CLIENT_ID` | string (secret) | Plaid API key |
132+
| `PLAID_SECRET` | string (secret) | Plaid API secret |
133+
134+
Always check if optional URL bindings are present before using them (e.g., `if (c.env.CHITTYAUTH_URL)`).
135+
136+
## Cron Schedule
137+
138+
Defined in `wrangler.toml` and dispatched via `src/lib/cron.ts`:
139+
140+
| Schedule | Purpose |
141+
|----------|---------|
142+
| `0 12 * * *` | Daily 6 AM CT: Plaid + ChittyFinance sync |
143+
| `0 13 * * *` | Daily 7 AM CT: Court docket check |
144+
| `0 14 * * 1` | Weekly Mon 8 AM CT: Utility scrapers |
145+
| `0 15 1 * *` | Monthly 1st 9 AM CT: Mortgage, property tax |
146+
147+
## MCP Server
148+
149+
The `/mcp` route exposes 28 tools across 8 domains for Claude integration. Tools return structured JSON: `content: [{ type: "json", json: ... }]`. Auth is handled by `mcpAuthMiddleware`. See `src/routes/mcp.ts` for tool definitions.
150+
151+
## Testing
152+
153+
Tests use Vitest. Run with `npm run test`. Test files live alongside source in `src/` or in a `__tests__` directory. The test configuration is in `vitest.config.ts`.
154+
155+
## PR and Review Policy
156+
157+
- One concern area per PR (security, feature, refactor, schema change, governance).
158+
- Every PR must include: scope, risk/blast radius, test evidence, rollback plan, and migration impact.
159+
- Do not bundle governance/ruleset changes with unrelated app logic.
160+
- Resolve must-fix review comments (security, correctness, compliance, merge blockers) before merge.
161+
- Do not weaken auth, CORS, or governance controls.
162+
- Schema changes (`src/db/schema.ts`) require a new SQL migration in `migrations/`.
163+
164+
## ChittyOS Ecosystem Context
165+
166+
ChittyCommand is a **Tier 5 Application** — a consumer of upstream data, not a source of truth. It delegates to:
167+
168+
- **ChittyAuth** — identity and token validation
169+
- **ChittyFinance** — financial data aggregation
170+
- **ChittyScrape** — browser automation for portals without APIs
171+
- **ChittyLedger** — evidence and document ledger
172+
- **ChittyConnect** — inter-service discovery and connectivity
173+
- **ChittySchema** — canonical schema validation
174+
- **ChittyRegister** — service registration and beacon heartbeats

0 commit comments

Comments
 (0)