@etus/bhono-app 0.1.6 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +3 -2
- package/templates/base/.claude/commands/check-skill-rules.md +112 -29
- package/templates/base/.claude/commands/linear/implement-issue.md +383 -55
- package/templates/base/.claude/commands/ship.md +77 -13
- package/templates/base/.claude/hooks/package-lock.json +0 -419
- package/templates/base/.claude/hooks/skill-activation-prompt.ts +185 -113
- package/templates/base/.claude/hooks/skill-tool-guard.sh +6 -0
- package/templates/base/.claude/hooks/skill-tool-guard.ts +198 -0
- package/templates/base/.claude/scripts/validate-skill-rules.sh +55 -32
- package/templates/base/.claude/settings.json +18 -11
- package/templates/base/.claude/skills/skill-rules.json +326 -173
- package/templates/base/.env.example +3 -0
- package/templates/base/README.md +9 -7
- package/templates/base/config/eslint.config.js +1 -0
- package/templates/base/config/wrangler.json +16 -17
- package/templates/base/docs/SETUP-GUIDE.md +566 -0
- package/templates/base/docs/architecture/README.md +162 -8
- package/templates/base/docs/architecture/api-catalog.md +575 -0
- package/templates/base/docs/architecture/c4-component.md +309 -0
- package/templates/base/docs/architecture/c4-container.md +183 -0
- package/templates/base/docs/architecture/c4-context.md +106 -0
- package/templates/base/docs/architecture/dependencies.md +327 -0
- package/templates/base/docs/architecture/tech-debt.md +184 -0
- package/templates/base/package.json +20 -15
- package/templates/base/scripts/capture-prod-session.ts +2 -2
- package/templates/base/scripts/sync-template.sh +104 -0
- package/templates/base/src/server/db/sql.ts +24 -4
- package/templates/base/src/server/index.ts +1 -0
- package/templates/base/src/server/lib/audited-db.ts +10 -10
- package/templates/base/src/server/middleware/account.ts +1 -1
- package/templates/base/src/server/middleware/auth.ts +11 -11
- package/templates/base/src/server/middleware/rate-limit.ts +3 -6
- package/templates/base/src/server/routes/auth/handlers.ts +5 -5
- package/templates/base/src/server/routes/auth/test-login.ts +9 -9
- package/templates/base/src/server/routes/index.ts +9 -0
- package/templates/base/src/server/routes/invitations/handlers.ts +6 -6
- package/templates/base/src/server/routes/openapi.ts +1 -1
- package/templates/base/src/server/services/accounts.ts +9 -9
- package/templates/base/src/server/services/audits.ts +12 -12
- package/templates/base/src/server/services/auth.ts +15 -15
- package/templates/base/src/server/services/invitations.ts +16 -16
- package/templates/base/src/server/services/users.ts +13 -13
- package/templates/base/src/shared/types/api.ts +66 -198
- package/templates/base/tests/e2e/auth.setup.ts +1 -1
- package/templates/base/tests/unit/server/auth/guards.test.ts +1 -1
- package/templates/base/tests/unit/server/middleware/auth.test.ts +273 -0
- package/templates/base/tests/unit/server/routes/auth/handlers.test.ts +111 -0
- package/templates/base/tests/unit/server/routes/users/handlers.test.ts +69 -5
- package/templates/base/tests/unit/server/services/accounts.test.ts +148 -0
- package/templates/base/tests/unit/server/services/audits.test.ts +219 -0
- package/templates/base/tests/unit/server/services/auth.test.ts +480 -3
- package/templates/base/tests/unit/server/services/invitations.test.ts +178 -0
- package/templates/base/tests/unit/server/services/users.test.ts +363 -8
- package/templates/base/tests/unit/shared/schemas.test.ts +1 -1
- package/templates/base/vite.config.ts +3 -1
- package/templates/base/.github/workflows/test.yml +0 -127
- package/templates/base/.husky/pre-push +0 -26
- package/templates/base/auth-setup-error.png +0 -0
- package/templates/base/pnpm-lock.yaml +0 -8052
- package/templates/base/tests/e2e/_auth/.gitkeep +0 -0
- package/templates/base/tsconfig.tsbuildinfo +0 -1
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
# Module Dependencies - BHono Platform
|
|
2
|
+
|
|
3
|
+
> Service and module dependency map showing how components interact.
|
|
4
|
+
|
|
5
|
+
## Dependency Overview
|
|
6
|
+
|
|
7
|
+
```mermaid
|
|
8
|
+
graph TD
|
|
9
|
+
subgraph "Entry Points"
|
|
10
|
+
ServerEntry[src/server/index.ts]
|
|
11
|
+
ClientEntry[src/client/main.tsx]
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
subgraph "Server Layer"
|
|
15
|
+
Middleware[middleware/]
|
|
16
|
+
Routes[routes/]
|
|
17
|
+
Services[services/]
|
|
18
|
+
Auth[auth/]
|
|
19
|
+
DB[db/]
|
|
20
|
+
Lib[lib/]
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
subgraph "Client Layer"
|
|
24
|
+
Router[router.ts]
|
|
25
|
+
ClientRoutes[routes/]
|
|
26
|
+
Components[components/]
|
|
27
|
+
Hooks[hooks/]
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
subgraph "Shared Layer"
|
|
31
|
+
Schemas[shared/schemas/]
|
|
32
|
+
Types[shared/types/]
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
subgraph "External"
|
|
36
|
+
D1[(D1 Database)]
|
|
37
|
+
KV[(KV Store)]
|
|
38
|
+
R2[(R2 Storage)]
|
|
39
|
+
Google[Google OAuth]
|
|
40
|
+
SendGrid[SendGrid]
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
ServerEntry --> Middleware
|
|
44
|
+
ServerEntry --> Routes
|
|
45
|
+
Middleware --> Auth
|
|
46
|
+
Middleware --> Lib
|
|
47
|
+
Routes --> Services
|
|
48
|
+
Routes --> Schemas
|
|
49
|
+
Services --> DB
|
|
50
|
+
Services --> Lib
|
|
51
|
+
Auth --> DB
|
|
52
|
+
DB --> D1
|
|
53
|
+
Lib --> KV
|
|
54
|
+
Lib --> R2
|
|
55
|
+
Lib --> Google
|
|
56
|
+
Lib --> SendGrid
|
|
57
|
+
|
|
58
|
+
ClientEntry --> Router
|
|
59
|
+
Router --> ClientRoutes
|
|
60
|
+
ClientRoutes --> Components
|
|
61
|
+
ClientRoutes --> Hooks
|
|
62
|
+
Components --> Types
|
|
63
|
+
Hooks --> Types
|
|
64
|
+
Hooks --> Schemas
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Server Dependencies [HIGH]
|
|
70
|
+
|
|
71
|
+
### Middleware Layer
|
|
72
|
+
|
|
73
|
+
| Module | Dependencies | Purpose |
|
|
74
|
+
|--------|--------------|---------|
|
|
75
|
+
| `error-handler.ts` | `lib/errors` | Global error handling |
|
|
76
|
+
| `request-context.ts` | `uuidv7` | Transaction ID generation |
|
|
77
|
+
| `request-logger.ts` | `request-context` | Structured logging |
|
|
78
|
+
| `cors.ts` | `hono/cors` | CORS configuration |
|
|
79
|
+
| `rate-limit.ts` | None | In-memory rate limiting |
|
|
80
|
+
| `auth.ts` | `lib/session`, `auth/guards` | Session validation |
|
|
81
|
+
| `account.ts` | `db/sql`, `auth/guards` | Account context |
|
|
82
|
+
|
|
83
|
+
```mermaid
|
|
84
|
+
graph LR
|
|
85
|
+
Request[Request] --> EH[Error Handler]
|
|
86
|
+
EH --> RC[Request Context]
|
|
87
|
+
RC --> RL[Request Logger]
|
|
88
|
+
RL --> CORS[CORS]
|
|
89
|
+
CORS --> Rate[Rate Limiter]
|
|
90
|
+
Rate --> Auth[Session Auth]
|
|
91
|
+
Auth --> Acc[Account Context]
|
|
92
|
+
Acc --> Handler[Route Handler]
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Routes Layer
|
|
96
|
+
|
|
97
|
+
| Route Module | Service Dependencies | Schema Dependencies |
|
|
98
|
+
|--------------|---------------------|---------------------|
|
|
99
|
+
| `auth/` | `AuthService` | `auth/schemas` |
|
|
100
|
+
| `users/` | `UsersService` | `users/schemas`, `shared/schemas/user` |
|
|
101
|
+
| `accounts/` | `AccountsService` | `accounts/schemas`, `shared/schemas/account` |
|
|
102
|
+
| `invitations/` | `InvitationsService` | `invitations/schemas`, `shared/schemas/invitation` |
|
|
103
|
+
| `audits/` | `AuditsService` | `audits/schemas` |
|
|
104
|
+
| `storage/` | R2 direct | `storage/schemas` |
|
|
105
|
+
| `health/` | D1 direct | None |
|
|
106
|
+
|
|
107
|
+
### Services Layer
|
|
108
|
+
|
|
109
|
+
| Service | Dependencies | External |
|
|
110
|
+
|---------|--------------|----------|
|
|
111
|
+
| `AuthService` | `db/sql`, `lib/oauth`, `lib/session`, `lib/tokens` | Google OAuth, KV |
|
|
112
|
+
| `UsersService` | `db/sql`, `lib/audit` | D1 |
|
|
113
|
+
| `AccountsService` | `db/sql`, `lib/audit` | D1 |
|
|
114
|
+
| `InvitationsService` | `db/sql`, `lib/email`, `lib/tokens` | D1, SendGrid |
|
|
115
|
+
| `AuditsService` | `db/sql` | D1 |
|
|
116
|
+
|
|
117
|
+
### Library Layer
|
|
118
|
+
|
|
119
|
+
| Library | Dependencies | External Services |
|
|
120
|
+
|---------|--------------|-------------------|
|
|
121
|
+
| `oauth.ts` | None | Google OAuth APIs |
|
|
122
|
+
| `session.ts` | None | Cloudflare KV |
|
|
123
|
+
| `tokens.ts` | `crypto` | None |
|
|
124
|
+
| `email.ts` | None | SendGrid API |
|
|
125
|
+
| `audit.ts` | `db/sql` | D1 |
|
|
126
|
+
| `pagination.ts` | None | None |
|
|
127
|
+
| `errors.ts` | None | None |
|
|
128
|
+
| `r2-storage.ts` | None | Cloudflare R2 |
|
|
129
|
+
|
|
130
|
+
### Auth Layer
|
|
131
|
+
|
|
132
|
+
| Module | Dependencies | Purpose |
|
|
133
|
+
|--------|--------------|---------|
|
|
134
|
+
| `roles.ts` | None | Role hierarchy definition |
|
|
135
|
+
| `permissions.ts` | `roles` | Permission constants |
|
|
136
|
+
| `guards.ts` | `roles`, `permissions` | Authorization checks |
|
|
137
|
+
|
|
138
|
+
```mermaid
|
|
139
|
+
graph TD
|
|
140
|
+
Guards[guards.ts] --> Roles[roles.ts]
|
|
141
|
+
Guards --> Permissions[permissions.ts]
|
|
142
|
+
Permissions --> Roles
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Database Layer
|
|
146
|
+
|
|
147
|
+
| Module | Dependencies | Purpose |
|
|
148
|
+
|--------|--------------|---------|
|
|
149
|
+
| `sql.ts` | D1 binding | Query helpers |
|
|
150
|
+
| `records.ts` | None | Type definitions |
|
|
151
|
+
| `client.ts` | D1 binding | Client wrapper |
|
|
152
|
+
| `seed.ts` | `sql.ts` | Test data generation |
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Client Dependencies [HIGH]
|
|
157
|
+
|
|
158
|
+
### Route Dependencies
|
|
159
|
+
|
|
160
|
+
| Route | Component Dependencies | Hook Dependencies |
|
|
161
|
+
|-------|----------------------|-------------------|
|
|
162
|
+
| `__root.tsx` | `Sonner`, `ErrorBoundary` | `useTheme` |
|
|
163
|
+
| `_authenticated.tsx` | `Sidebar`, `LoadingSkeleton` | `useAuth` |
|
|
164
|
+
| `login.tsx` | `Button`, `Card`, `Icons` | None |
|
|
165
|
+
| `dashboard.tsx` | `Card`, `Badge` | `useAuth` |
|
|
166
|
+
| `team.tsx` | `Card`, `Dialog`, `Avatar` | `useAuth` |
|
|
167
|
+
| `settings.tsx` | `Tabs`, `Form`, `Input` | `useAuth` |
|
|
168
|
+
| `account.tsx` | `Card`, `Badge` | `useAuth` |
|
|
169
|
+
| `integrations.tsx` | `Card`, `Dialog`, `Badge` | `useAuth` |
|
|
170
|
+
|
|
171
|
+
### Component Dependencies
|
|
172
|
+
|
|
173
|
+
| Component | External Dependencies |
|
|
174
|
+
|-----------|----------------------|
|
|
175
|
+
| `Button` | `class-variance-authority`, `@radix-ui/react-slot` |
|
|
176
|
+
| `Dialog` | `@radix-ui/react-dialog` |
|
|
177
|
+
| `Tabs` | `@radix-ui/react-tabs` |
|
|
178
|
+
| `Avatar` | `@radix-ui/react-avatar` |
|
|
179
|
+
| `Form` | `react-hook-form`, `@hookform/resolvers/zod` |
|
|
180
|
+
| `Sonner` | `sonner` |
|
|
181
|
+
| `Sidebar` | `lucide-react` |
|
|
182
|
+
|
|
183
|
+
### Hook Dependencies
|
|
184
|
+
|
|
185
|
+
| Hook | Dependencies |
|
|
186
|
+
|------|--------------|
|
|
187
|
+
| `useAuth` | `@tanstack/react-query`, `shared/types/auth` |
|
|
188
|
+
| `useTheme` | React Context |
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Shared Dependencies [HIGH]
|
|
193
|
+
|
|
194
|
+
### Schemas
|
|
195
|
+
|
|
196
|
+
| Schema | Used By |
|
|
197
|
+
|--------|---------|
|
|
198
|
+
| `user.ts` | `server/routes/users`, `client/hooks/use-auth` |
|
|
199
|
+
| `account.ts` | `server/routes/accounts`, `client/routes/account` |
|
|
200
|
+
| `invitation.ts` | `server/routes/invitations`, `client/routes/team` |
|
|
201
|
+
| `profile.ts` | `server/routes/users`, `client/routes/settings` |
|
|
202
|
+
| `webhook.ts` | `client/routes/integrations` |
|
|
203
|
+
|
|
204
|
+
### Types
|
|
205
|
+
|
|
206
|
+
| Type Module | Used By |
|
|
207
|
+
|-------------|---------|
|
|
208
|
+
| `auth.ts` | Server auth, client hooks |
|
|
209
|
+
| `user.ts` | Server services, client routes |
|
|
210
|
+
| `account.ts` | Server services, client routes |
|
|
211
|
+
| `api.ts` | Server routes, client API calls |
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## External Dependencies [HIGH]
|
|
216
|
+
|
|
217
|
+
### NPM Packages
|
|
218
|
+
|
|
219
|
+
#### Backend
|
|
220
|
+
|
|
221
|
+
| Package | Version | Purpose |
|
|
222
|
+
|---------|---------|---------|
|
|
223
|
+
| `hono` | 4.11.x | Web framework |
|
|
224
|
+
| `@hono/zod-openapi` | 1.2.x | OpenAPI integration |
|
|
225
|
+
| `@hono/swagger-ui` | 0.5.x | API documentation |
|
|
226
|
+
| `zod` | 4.3.x | Schema validation |
|
|
227
|
+
| `uuidv7` | 1.1.x | UUID generation |
|
|
228
|
+
|
|
229
|
+
#### Frontend
|
|
230
|
+
|
|
231
|
+
| Package | Version | Purpose |
|
|
232
|
+
|---------|---------|---------|
|
|
233
|
+
| `react` | 19.x | UI library |
|
|
234
|
+
| `@tanstack/react-router` | 1.144.x | File-based routing |
|
|
235
|
+
| `@tanstack/react-query` | 5.90.x | Data fetching |
|
|
236
|
+
| `react-hook-form` | 7.70.x | Form handling |
|
|
237
|
+
| `tailwindcss` | 4.1.x | Styling |
|
|
238
|
+
| `@radix-ui/*` | 1.x | UI primitives |
|
|
239
|
+
| `lucide-react` | 0.562.x | Icons |
|
|
240
|
+
| `sonner` | 2.0.x | Toast notifications |
|
|
241
|
+
|
|
242
|
+
### Cloudflare Services
|
|
243
|
+
|
|
244
|
+
| Service | Binding | Purpose |
|
|
245
|
+
|---------|---------|---------|
|
|
246
|
+
| D1 | `DB` | SQLite database |
|
|
247
|
+
| KV | `SESSIONS` | Session storage |
|
|
248
|
+
| R2 | `R2_BUCKET` | File storage |
|
|
249
|
+
|
|
250
|
+
### External APIs
|
|
251
|
+
|
|
252
|
+
| Service | Protocol | Purpose |
|
|
253
|
+
|---------|----------|---------|
|
|
254
|
+
| Google OAuth | OAuth 2.0 | Authentication |
|
|
255
|
+
| SendGrid | REST API | Email delivery |
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## Dependency Rules
|
|
260
|
+
|
|
261
|
+
### Allowed Dependencies
|
|
262
|
+
|
|
263
|
+
```
|
|
264
|
+
┌─────────────────────────────────────────────────────────┐
|
|
265
|
+
│ Routes │
|
|
266
|
+
│ ┌─────────────────────────────────────────────────┐ │
|
|
267
|
+
│ │ Services │ │
|
|
268
|
+
│ │ ┌─────────────────────────────────────────┐ │ │
|
|
269
|
+
│ │ │ Auth/Lib │ │ │
|
|
270
|
+
│ │ │ ┌─────────────────────────────────┐ │ │ │
|
|
271
|
+
│ │ │ │ DB │ │ │ │
|
|
272
|
+
│ │ │ └─────────────────────────────────┘ │ │ │
|
|
273
|
+
│ │ └─────────────────────────────────────────┘ │ │
|
|
274
|
+
│ └─────────────────────────────────────────────────┘ │
|
|
275
|
+
└─────────────────────────────────────────────────────────┘
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
**Rules**:
|
|
279
|
+
1. Routes → Services → DB (never skip layers)
|
|
280
|
+
2. Middleware can access Auth and Lib
|
|
281
|
+
3. Services can access DB and Lib
|
|
282
|
+
4. Auth can access DB for role lookups
|
|
283
|
+
5. Shared schemas/types accessible by all layers
|
|
284
|
+
|
|
285
|
+
### Forbidden Dependencies
|
|
286
|
+
|
|
287
|
+
| Layer | Cannot Import |
|
|
288
|
+
|-------|---------------|
|
|
289
|
+
| DB | Services, Routes, Middleware |
|
|
290
|
+
| Lib | Services, Routes |
|
|
291
|
+
| Auth | Services, Routes |
|
|
292
|
+
| Services | Routes, Middleware |
|
|
293
|
+
| Shared | Any server/client specific code |
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## Import Aliases
|
|
298
|
+
|
|
299
|
+
| Alias | Maps To | Usage |
|
|
300
|
+
|-------|---------|-------|
|
|
301
|
+
| `@/*` | `src/client/*` | Client-only imports |
|
|
302
|
+
| `@server/*` | `src/server/*` | Server-only imports |
|
|
303
|
+
| `@shared/*` | `src/shared/*` | Shared imports |
|
|
304
|
+
|
|
305
|
+
**Example**:
|
|
306
|
+
```typescript
|
|
307
|
+
// In client code
|
|
308
|
+
import { Button } from '@/components/ui/button'
|
|
309
|
+
import { userSchema } from '@shared/schemas/user'
|
|
310
|
+
|
|
311
|
+
// In server code
|
|
312
|
+
import { UsersService } from '@server/services/users'
|
|
313
|
+
import { userSchema } from '@shared/schemas/user'
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Circular Dependency Prevention
|
|
319
|
+
|
|
320
|
+
The architecture prevents circular dependencies through:
|
|
321
|
+
|
|
322
|
+
1. **Layered architecture**: Lower layers cannot import higher layers
|
|
323
|
+
2. **Shared types**: Common types in `shared/` break potential cycles
|
|
324
|
+
3. **Dependency injection**: Services receive dependencies via constructor
|
|
325
|
+
4. **Interface segregation**: Guards expose minimal interfaces
|
|
326
|
+
|
|
327
|
+
**Build-time checks**: TypeScript's `noImplicitAny` and path aliases enforce boundaries.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Technical Debt Register - BHono Platform
|
|
2
|
+
|
|
3
|
+
> Tracking technical debt, code quality issues, and improvement opportunities.
|
|
4
|
+
|
|
5
|
+
## Executive Summary
|
|
6
|
+
|
|
7
|
+
| Metric | Value | Status |
|
|
8
|
+
|--------|-------|--------|
|
|
9
|
+
| **TODO Comments** | 0 | ✅ Clean |
|
|
10
|
+
| **FIXME Comments** | 0 | ✅ Clean |
|
|
11
|
+
| **HACK Comments** | 0 | ✅ Clean |
|
|
12
|
+
| **Deprecated APIs** | 0 | ✅ Clean |
|
|
13
|
+
| **Critical Security Issues** | 0 | ✅ Clean |
|
|
14
|
+
| **Test Coverage** | 94%+ | ✅ Excellent |
|
|
15
|
+
|
|
16
|
+
**Overall Assessment**: The codebase is exceptionally clean with no explicit technical debt markers found.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Debt Categories
|
|
21
|
+
|
|
22
|
+
### 1. Code Comments [HIGH CONFIDENCE]
|
|
23
|
+
|
|
24
|
+
A scan of the codebase revealed **no technical debt markers**:
|
|
25
|
+
|
|
26
|
+
| Marker | Count | Files |
|
|
27
|
+
|--------|-------|-------|
|
|
28
|
+
| `TODO` | 0 | - |
|
|
29
|
+
| `FIXME` | 0 | - |
|
|
30
|
+
| `HACK` | 0 | - |
|
|
31
|
+
| `XXX` | 0 | - |
|
|
32
|
+
| `@deprecated` | 0 | - |
|
|
33
|
+
|
|
34
|
+
### 2. Security Assessment [HIGH CONFIDENCE]
|
|
35
|
+
|
|
36
|
+
| Category | Status | Notes |
|
|
37
|
+
|----------|--------|-------|
|
|
38
|
+
| Hardcoded secrets | ✅ None | All secrets via env vars |
|
|
39
|
+
| eval() usage | ✅ None | No dynamic code execution |
|
|
40
|
+
| SQL injection risk | ✅ Low | Parameterized queries used |
|
|
41
|
+
| XSS prevention | ✅ Good | React escaping + secure headers |
|
|
42
|
+
| CSRF protection | ✅ Good | SameSite cookies |
|
|
43
|
+
| Session security | ✅ Good | httpOnly, Secure, __Host- prefix |
|
|
44
|
+
|
|
45
|
+
### 3. Dependency Health [HIGH CONFIDENCE]
|
|
46
|
+
|
|
47
|
+
| Category | Status | Notes |
|
|
48
|
+
|----------|--------|-------|
|
|
49
|
+
| Major version updates | ✅ Current | All dependencies up to date |
|
|
50
|
+
| Known vulnerabilities | ✅ None | No CVEs in dependencies |
|
|
51
|
+
| Deprecated packages | ✅ None | No deprecated dependencies |
|
|
52
|
+
| Peer dependency issues | ✅ None | All peer deps satisfied |
|
|
53
|
+
|
|
54
|
+
### 4. Code Quality Metrics [HIGH CONFIDENCE]
|
|
55
|
+
|
|
56
|
+
| Metric | Value | Target | Status |
|
|
57
|
+
|--------|-------|--------|--------|
|
|
58
|
+
| Server unit coverage | 94.50% | 90% | ✅ Exceeds |
|
|
59
|
+
| Client unit coverage | 90.82% | 85% | ✅ Exceeds |
|
|
60
|
+
| Integration coverage | 93.19% | 90% | ✅ Exceeds |
|
|
61
|
+
| E2E test count | 363+ | - | ✅ Comprehensive |
|
|
62
|
+
| TypeScript strict | Enabled | Yes | ✅ Pass |
|
|
63
|
+
| ESLint errors | 0 | 0 | ✅ Pass |
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Potential Improvements
|
|
68
|
+
|
|
69
|
+
While no explicit debt exists, these areas could be enhanced:
|
|
70
|
+
|
|
71
|
+
### 1. Rate Limiting Storage [MEDIUM]
|
|
72
|
+
|
|
73
|
+
**Current**: In-memory rate limiting with lazy cleanup
|
|
74
|
+
**Issue**: Rate limits not shared across Cloudflare Worker instances
|
|
75
|
+
**Recommendation**: Consider Cloudflare Durable Objects for distributed rate limiting
|
|
76
|
+
|
|
77
|
+
| Priority | Effort | Impact |
|
|
78
|
+
|----------|--------|--------|
|
|
79
|
+
| Low | Medium | Improves multi-instance rate limiting |
|
|
80
|
+
|
|
81
|
+
### 2. Session Fingerprinting [LOW]
|
|
82
|
+
|
|
83
|
+
**Current**: User-agent fingerprint validation
|
|
84
|
+
**Issue**: Could be bypassed by copying User-Agent header
|
|
85
|
+
**Recommendation**: Consider adding IP-based validation (with caveats for mobile users)
|
|
86
|
+
|
|
87
|
+
| Priority | Effort | Impact |
|
|
88
|
+
|----------|--------|--------|
|
|
89
|
+
| Low | Low | Marginal security improvement |
|
|
90
|
+
|
|
91
|
+
### 3. Audit Log Retention [LOW]
|
|
92
|
+
|
|
93
|
+
**Current**: All audit logs retained indefinitely
|
|
94
|
+
**Issue**: Table could grow large over time
|
|
95
|
+
**Recommendation**: Implement retention policy or archival strategy
|
|
96
|
+
|
|
97
|
+
| Priority | Effort | Impact |
|
|
98
|
+
|----------|--------|--------|
|
|
99
|
+
| Low | Low | Storage optimization |
|
|
100
|
+
|
|
101
|
+
### 4. Email Template Management [LOW]
|
|
102
|
+
|
|
103
|
+
**Current**: Invitation emails use inline HTML
|
|
104
|
+
**Issue**: Templates embedded in code
|
|
105
|
+
**Recommendation**: Consider external template system for easier customization
|
|
106
|
+
|
|
107
|
+
| Priority | Effort | Impact |
|
|
108
|
+
|----------|--------|--------|
|
|
109
|
+
| Low | Medium | Improved maintainability |
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Architecture Considerations
|
|
114
|
+
|
|
115
|
+
### Scaling Considerations
|
|
116
|
+
|
|
117
|
+
| Concern | Current State | Future Consideration |
|
|
118
|
+
|---------|---------------|---------------------|
|
|
119
|
+
| Database | Single D1 instance | D1 scales automatically |
|
|
120
|
+
| Sessions | KV namespace | Sufficient for most workloads |
|
|
121
|
+
| File storage | R2 bucket | Scales automatically |
|
|
122
|
+
| Rate limiting | In-memory | Durable Objects for consistency |
|
|
123
|
+
|
|
124
|
+
### Performance Observations
|
|
125
|
+
|
|
126
|
+
| Area | Status | Notes |
|
|
127
|
+
|------|--------|-------|
|
|
128
|
+
| Cold start | ✅ Good | ~50ms typical |
|
|
129
|
+
| Response times | ✅ Good | <100ms average |
|
|
130
|
+
| Bundle size | ✅ Good | Tree-shaking enabled |
|
|
131
|
+
| Database queries | ✅ Good | Indexed properly |
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Monitoring Checklist
|
|
136
|
+
|
|
137
|
+
Regular monitoring recommended for:
|
|
138
|
+
|
|
139
|
+
- [ ] Dependency updates (`npm outdated`)
|
|
140
|
+
- [ ] Security advisories (`npm audit`)
|
|
141
|
+
- [ ] Test coverage trends
|
|
142
|
+
- [ ] Performance baselines
|
|
143
|
+
- [ ] D1 database size
|
|
144
|
+
- [ ] KV storage usage
|
|
145
|
+
- [ ] R2 bucket usage
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Debt Prevention Practices
|
|
150
|
+
|
|
151
|
+
The project follows these practices to prevent debt accumulation:
|
|
152
|
+
|
|
153
|
+
1. **Automated Testing**: 94%+ coverage with CI enforcement
|
|
154
|
+
2. **Type Safety**: Strict TypeScript configuration
|
|
155
|
+
3. **Code Review**: PR-based workflow
|
|
156
|
+
4. **Linting**: ESLint with strict rules
|
|
157
|
+
5. **Commit Standards**: Conventional commits with Commitlint
|
|
158
|
+
6. **Pre-commit Hooks**: Husky enforces quality gates
|
|
159
|
+
7. **Dependency Updates**: Regular updates via Renovate/Dependabot
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Historical Debt (Resolved)
|
|
164
|
+
|
|
165
|
+
No historical debt items to track. The codebase started clean and has maintained quality.
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Conclusion
|
|
170
|
+
|
|
171
|
+
The BHono Platform demonstrates excellent code quality with:
|
|
172
|
+
|
|
173
|
+
- ✅ Zero explicit technical debt markers
|
|
174
|
+
- ✅ High test coverage (94%+)
|
|
175
|
+
- ✅ Modern dependencies
|
|
176
|
+
- ✅ Strict type checking
|
|
177
|
+
- ✅ Comprehensive security practices
|
|
178
|
+
|
|
179
|
+
The codebase is production-ready with minimal improvements identified for future consideration.
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
*Last updated: 2026-01-04*
|
|
184
|
+
*Analysis confidence: HIGH*
|
|
@@ -1,16 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "{{projectName}}",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "{{projectDescription}}",
|
|
4
5
|
"type": "module",
|
|
5
|
-
"packageManager": "pnpm@10.15.1",
|
|
6
|
-
"pnpm": {
|
|
7
|
-
"onlyBuiltDependencies": [
|
|
8
|
-
"better-sqlite3",
|
|
9
|
-
"esbuild",
|
|
10
|
-
"sharp",
|
|
11
|
-
"workerd"
|
|
12
|
-
]
|
|
13
|
-
},
|
|
14
6
|
"scripts": {
|
|
15
7
|
"dev": "vite",
|
|
16
8
|
"build": "vite build",
|
|
@@ -43,9 +35,13 @@
|
|
|
43
35
|
"test:e2e:report": "playwright show-report .test-output/reports/playwright",
|
|
44
36
|
"test:e2e:coverage": "E2E_COVERAGE=true playwright test; pnpm test:e2e:coverage:report",
|
|
45
37
|
"test:e2e:coverage:report": "nyc report --reporter=html --reporter=text --report-dir=.test-output/coverage/e2e --temp-dir=.test-output/coverage/e2e/.nyc_output",
|
|
46
|
-
"test:e2e:prod": "BASE_URL=https://
|
|
38
|
+
"test:e2e:prod": "BASE_URL=https://hono-boilerplate.a3s.workers.dev playwright test",
|
|
47
39
|
"test:e2e:prod:auth": "tsx scripts/capture-prod-session.ts",
|
|
48
|
-
"test": "pnpm test:unit && pnpm test:integration && pnpm test:e2e"
|
|
40
|
+
"test": "pnpm test:unit && pnpm test:integration && pnpm test:e2e",
|
|
41
|
+
"prepare": "husky || true",
|
|
42
|
+
"test:run": "pnpm test:unit:server && pnpm test:unit:client",
|
|
43
|
+
"sync:template": "./scripts/sync-template.sh",
|
|
44
|
+
"sync:template:check": "./scripts/sync-template.sh && git diff --exit-code packages/bhono-app/templates/"
|
|
49
45
|
},
|
|
50
46
|
"dependencies": {
|
|
51
47
|
"@hono/swagger-ui": "^0.5.3",
|
|
@@ -61,15 +57,15 @@
|
|
|
61
57
|
"lucide-react": "^0.562.0",
|
|
62
58
|
"react": "^19.2.3",
|
|
63
59
|
"react-dom": "^19.2.3",
|
|
64
|
-
"react-hook-form": "^7.
|
|
60
|
+
"react-hook-form": "^7.70.0",
|
|
65
61
|
"sonner": "^2.0.7",
|
|
66
62
|
"tailwind-merge": "^3.4.0",
|
|
67
63
|
"uuidv7": "^1.1.0",
|
|
68
|
-
"zod": "^4.3.
|
|
64
|
+
"zod": "^4.3.5"
|
|
69
65
|
},
|
|
70
66
|
"devDependencies": {
|
|
71
67
|
"@cloudflare/vite-plugin": "^1.17.1",
|
|
72
|
-
"@cloudflare/workers-types": "^4.
|
|
68
|
+
"@cloudflare/workers-types": "^4.20260103.0",
|
|
73
69
|
"@eslint-react/eslint-plugin": "^2.5.0",
|
|
74
70
|
"@eslint/js": "^9.39.2",
|
|
75
71
|
"@playwright/test": "^1.57.0",
|
|
@@ -112,5 +108,14 @@
|
|
|
112
108
|
"vite-plugin-istanbul": "^7.2.1",
|
|
113
109
|
"vitest": "^4.0.16",
|
|
114
110
|
"wrangler": "^4.54.0"
|
|
111
|
+
},
|
|
112
|
+
"packageManager": "pnpm@10.15.1",
|
|
113
|
+
"pnpm": {
|
|
114
|
+
"onlyBuiltDependencies": [
|
|
115
|
+
"better-sqlite3",
|
|
116
|
+
"esbuild",
|
|
117
|
+
"sharp",
|
|
118
|
+
"workerd"
|
|
119
|
+
]
|
|
115
120
|
}
|
|
116
121
|
}
|
|
@@ -28,7 +28,7 @@ const deviceConfig = devices['Desktop Chrome']
|
|
|
28
28
|
|
|
29
29
|
// Default configuration
|
|
30
30
|
const DEFAULT_CONFIG = {
|
|
31
|
-
baseURL: process.env.BASE_URL || 'https://
|
|
31
|
+
baseURL: process.env.BASE_URL || 'https://hono-boilerplate.a3s.workers.dev',
|
|
32
32
|
loginPath: '/login',
|
|
33
33
|
successURLPattern: '**/dashboard',
|
|
34
34
|
outputPath: 'tests/e2e/.auth/user.json',
|
|
@@ -89,7 +89,7 @@ Options:
|
|
|
89
89
|
--help, -h Show this help message
|
|
90
90
|
|
|
91
91
|
Environment Variables:
|
|
92
|
-
BASE_URL Base URL (default: https://
|
|
92
|
+
BASE_URL Base URL (default: https://hono-boilerplate.a3s.workers.dev)
|
|
93
93
|
|
|
94
94
|
Examples:
|
|
95
95
|
# Capture session from production
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# scripts/sync-template.sh
|
|
3
|
+
# Syncs the main boilerplate to the npm package template
|
|
4
|
+
|
|
5
|
+
set -e
|
|
6
|
+
|
|
7
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
8
|
+
ROOT_DIR="$(dirname "$SCRIPT_DIR")"
|
|
9
|
+
TEMPLATE_DIR="$ROOT_DIR/packages/bhono-app/templates/base"
|
|
10
|
+
|
|
11
|
+
# Colors for output
|
|
12
|
+
RED='\033[0;31m'
|
|
13
|
+
GREEN='\033[0;32m'
|
|
14
|
+
YELLOW='\033[1;33m'
|
|
15
|
+
NC='\033[0m' # No Color
|
|
16
|
+
|
|
17
|
+
echo -e "${YELLOW}Syncing boilerplate to npm template...${NC}"
|
|
18
|
+
echo "Source: $ROOT_DIR"
|
|
19
|
+
echo "Target: $TEMPLATE_DIR"
|
|
20
|
+
echo ""
|
|
21
|
+
|
|
22
|
+
# Ensure template directory exists
|
|
23
|
+
mkdir -p "$TEMPLATE_DIR"
|
|
24
|
+
|
|
25
|
+
# Rsync with exclusions
|
|
26
|
+
# --delete removes files in target that don't exist in source
|
|
27
|
+
# --checksum compares by content, not timestamp
|
|
28
|
+
rsync -av --checksum --delete \
|
|
29
|
+
--exclude='node_modules/' \
|
|
30
|
+
--exclude='dist/' \
|
|
31
|
+
--exclude='.git/' \
|
|
32
|
+
--exclude='.env' \
|
|
33
|
+
--exclude='.dev.vars' \
|
|
34
|
+
--exclude='db.sqlite' \
|
|
35
|
+
--exclude='*.log' \
|
|
36
|
+
--exclude='.DS_Store' \
|
|
37
|
+
--exclude='packages/' \
|
|
38
|
+
--exclude='pnpm-workspace.yaml' \
|
|
39
|
+
--exclude='pnpm-lock.yaml' \
|
|
40
|
+
--exclude='.changeset/' \
|
|
41
|
+
--exclude='docs/plans/' \
|
|
42
|
+
--exclude='.claude/settings.local.json' \
|
|
43
|
+
--exclude='coverage/' \
|
|
44
|
+
--exclude='test-results/' \
|
|
45
|
+
--exclude='playwright-report/' \
|
|
46
|
+
--exclude='.wrangler/' \
|
|
47
|
+
--exclude='worker-configuration.d.ts' \
|
|
48
|
+
"$ROOT_DIR/" "$TEMPLATE_DIR/"
|
|
49
|
+
|
|
50
|
+
# Rename .gitignore to _gitignore (npm ignores .gitignore in packages)
|
|
51
|
+
if [ -f "$TEMPLATE_DIR/.gitignore" ]; then
|
|
52
|
+
mv "$TEMPLATE_DIR/.gitignore" "$TEMPLATE_DIR/_gitignore"
|
|
53
|
+
echo -e "${GREEN}Renamed .gitignore to _gitignore${NC}"
|
|
54
|
+
fi
|
|
55
|
+
|
|
56
|
+
# Rename .env.example if it exists (keep as is, just ensure it exists)
|
|
57
|
+
if [ ! -f "$TEMPLATE_DIR/.env.example" ] && [ -f "$ROOT_DIR/.env.example" ]; then
|
|
58
|
+
cp "$ROOT_DIR/.env.example" "$TEMPLATE_DIR/.env.example"
|
|
59
|
+
fi
|
|
60
|
+
|
|
61
|
+
# Update package.json in template to use template variables
|
|
62
|
+
TEMPLATE_PKG="$TEMPLATE_DIR/package.json"
|
|
63
|
+
if [ -f "$TEMPLATE_PKG" ]; then
|
|
64
|
+
# Use Node.js to safely modify JSON
|
|
65
|
+
node -e "
|
|
66
|
+
const fs = require('fs');
|
|
67
|
+
const pkg = JSON.parse(fs.readFileSync('$TEMPLATE_PKG', 'utf8'));
|
|
68
|
+
|
|
69
|
+
// Set template variables
|
|
70
|
+
pkg.name = '{{projectName}}';
|
|
71
|
+
pkg.version = '0.1.0';
|
|
72
|
+
pkg.description = '{{projectDescription}}';
|
|
73
|
+
|
|
74
|
+
// Remove monorepo-specific fields
|
|
75
|
+
delete pkg.repository;
|
|
76
|
+
delete pkg.homepage;
|
|
77
|
+
delete pkg.bugs;
|
|
78
|
+
delete pkg.author;
|
|
79
|
+
delete pkg.license;
|
|
80
|
+
|
|
81
|
+
// Remove monorepo-specific scripts
|
|
82
|
+
delete pkg.scripts?.changeset;
|
|
83
|
+
delete pkg.scripts?.['changeset:version'];
|
|
84
|
+
delete pkg.scripts?.['changeset:publish'];
|
|
85
|
+
|
|
86
|
+
// Remove monorepo-specific devDependencies
|
|
87
|
+
delete pkg.devDependencies?.['@changesets/cli'];
|
|
88
|
+
delete pkg.devDependencies?.['@commitlint/cli'];
|
|
89
|
+
delete pkg.devDependencies?.['@commitlint/config-conventional'];
|
|
90
|
+
delete pkg.devDependencies?.husky;
|
|
91
|
+
delete pkg.devDependencies?.['lint-staged'];
|
|
92
|
+
|
|
93
|
+
fs.writeFileSync('$TEMPLATE_PKG', JSON.stringify(pkg, null, 2) + '\n');
|
|
94
|
+
console.log('Updated package.json with template variables');
|
|
95
|
+
"
|
|
96
|
+
fi
|
|
97
|
+
|
|
98
|
+
echo ""
|
|
99
|
+
echo -e "${GREEN}Sync complete!${NC}"
|
|
100
|
+
|
|
101
|
+
# Show diff summary
|
|
102
|
+
echo ""
|
|
103
|
+
echo "Files synced:"
|
|
104
|
+
find "$TEMPLATE_DIR" -type f | wc -l | xargs echo " Total files:"
|