@terreno/admin-backend 0.3.2 → 0.4.2

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.
@@ -0,0 +1,337 @@
1
+ # Terreno
2
+
3
+ A monorepo containing shared packages for building full-stack applications with React Native and Express/Mongoose.
4
+
5
+ ## Packages
6
+
7
+ - **api/** - REST API framework built on Express/Mongoose (`@terreno/api`)
8
+ - **ui/** - React Native UI component library (`@terreno/ui`)
9
+ - **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
10
+ - **admin-backend/** - Admin panel backend plugin for @terreno/api (`@terreno/admin-backend`)
11
+ - **admin-frontend/** - Admin panel frontend screens for @terreno/api backends (`@terreno/admin-frontend`)
12
+ - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp-server`)
13
+ - **demo/** - Demo app for showcasing and testing UI components
14
+ - **example-frontend/** - Example Expo app demonstrating full stack usage
15
+ - **example-backend/** - Example Express backend using @terreno/api
16
+
17
+ ## Development
18
+
19
+ Uses [Bun](https://bun.sh/) as the package manager.
20
+
21
+ ```bash
22
+ bun install # Install dependencies
23
+ bun run compile # Compile all packages
24
+ bun run lint # Lint all packages
25
+ bun run lint:fix # Fix lint issues
26
+ bun run test # Run tests in api and ui
27
+ ```
28
+
29
+ ### Package-specific commands
30
+
31
+ ```bash
32
+ bun run api:test # Test API package
33
+ bun run ui:test # Test UI package
34
+ bun run demo:start # Start demo app
35
+ bun run frontend:web # Start frontend example
36
+ bun run backend:dev # Start backend example
37
+ bun run mcp:build # Build MCP server
38
+ bun run mcp:start # Start MCP server
39
+ bun run admin-backend:compile # Compile admin backend
40
+ bun run admin-frontend:compile # Compile admin frontend
41
+ ```
42
+
43
+ ## How the Packages Work Together
44
+
45
+ The three core packages form a complete full-stack framework:
46
+
47
+ ```
48
+ BACKEND
49
+ @terreno/api
50
+ - Mongoose models with modelRouter -> CRUD endpoints
51
+ - Built-in auth (JWT + Passport)
52
+ - Automatic OpenAPI spec generation
53
+ |
54
+ /openapi.json
55
+ |
56
+ RTK Query SDK Codegen
57
+ |
58
+ FRONTEND
59
+ @terreno/rtk
60
+ - Generated hooks from OpenAPI spec
61
+ - Auth slice with JWT token management
62
+ - Automatic token refresh
63
+ +
64
+ @terreno/ui
65
+ - React Native components (Box, Button, TextField, etc.)
66
+ - TerrenoProvider for theming
67
+ ```
68
+
69
+ ### Integration Flow
70
+
71
+ 1. **Backend (api)**: Define Mongoose models, use `modelRouter` to create CRUD endpoints with permissions
72
+ 2. **OpenAPI Generation**: `setupServer` automatically generates `/openapi.json`
73
+ 3. **SDK Codegen**: Frontend runs `bun run sdk` to generate RTK Query hooks from OpenAPI spec
74
+ 4. **Frontend (rtk + ui)**: Use generated hooks with UI components for type-safe API calls
75
+
76
+ ## Example Apps (Keep These Updated!)
77
+
78
+ The `example-frontend/` and `example-backend/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
79
+
80
+ 1. **Add examples** demonstrating new features
81
+ 2. **Update SDK** after backend changes: `cd example-frontend && bun run sdk`
82
+ 3. **Verify integration** by running both examples together
83
+
84
+ ### Running the Full Stack
85
+
86
+ ```bash
87
+ # Terminal 1: Start backend
88
+ bun run backend:dev
89
+
90
+ # Terminal 2: Start frontend
91
+ bun run frontend:web
92
+ ```
93
+
94
+ ## Code Style
95
+
96
+ ### TypeScript/JavaScript
97
+ - Use ES module syntax and TypeScript for all code
98
+ - Prefer interfaces over types; avoid enums, use maps
99
+ - Prefer const arrow functions over `function` keyword
100
+ - Use descriptive variable names with auxiliary verbs (e.g., `isLoading`)
101
+ - Use camelCase directories (e.g., `components/authWizard`)
102
+ - Favor named exports
103
+ - Use the RORO pattern (Receive an Object, Return an Object)
104
+
105
+ ### Dates and Time
106
+ - Always use Luxon instead of Date or dayjs
107
+
108
+ ### Error Handling
109
+ - Check error conditions at start of functions and return early
110
+ - Limit nested if statements
111
+ - Use multiline syntax with curly braces for all conditionals
112
+
113
+ ### Testing
114
+ - Use bun test with expect for testing
115
+
116
+ ### Logging
117
+ - Frontend: Use `console.info`, `console.debug`, `console.warn`, or `console.error` for permanent logs
118
+ - Backend: Use `logger.info/warn/error/debug` for permanent logs
119
+ - Use `console.log` only for debugging (to be removed)
120
+
121
+ ### Development Practices
122
+ - Don't apologize for errors: fix them
123
+ - Prioritize modularity, DRY, performance, and security
124
+ - Focus on readability over performance
125
+ - Write complete, functional code without TODOs when possible
126
+ - Comments should describe purpose, not effect
127
+
128
+ ## Package Reference
129
+
130
+ ### @terreno/api
131
+
132
+ REST API framework providing:
133
+
134
+ - **modelRouter**: Auto-generates CRUD endpoints for Mongoose models
135
+ - **Permissions**: `IsAuthenticated`, `IsOwner`, `IsAdmin`, `IsAuthenticatedOrReadOnly`
136
+ - **Query Filters**: `OwnerQueryFilter` for filtering list queries by owner
137
+ - **setupServer**: Express server setup with auth, OpenAPI, and middleware
138
+ - **APIError**: Standardized error handling
139
+ - **logger**: Winston-based logging
140
+
141
+ Key imports:
142
+ ```typescript
143
+ import {
144
+ modelRouter,
145
+ setupServer,
146
+ Permissions,
147
+ OwnerQueryFilter,
148
+ APIError,
149
+ logger,
150
+ asyncHandler,
151
+ authenticateMiddleware,
152
+ } from "@terreno/api";
153
+ ```
154
+
155
+ #### modelRouter Usage
156
+
157
+ ```typescript
158
+ import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
159
+
160
+ const router = modelRouter(YourModel, {
161
+ permissions: {
162
+ list: [Permissions.IsAuthenticated],
163
+ create: [Permissions.IsAuthenticated],
164
+ read: [Permissions.IsOwner],
165
+ update: [Permissions.IsOwner],
166
+ delete: [], // Disabled
167
+ },
168
+ sort: "-created",
169
+ queryFields: ["_id", "type", "name"],
170
+ });
171
+ ```
172
+
173
+ #### Custom Routes
174
+
175
+ For non-CRUD endpoints, use the OpenAPI builder:
176
+
177
+ ```typescript
178
+ import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
179
+
180
+ router.get("/yourRoute/:id", [
181
+ authenticateMiddleware(),
182
+ createOpenApiBuilder(options)
183
+ .withTags(["yourTag"])
184
+ .withSummary("Brief summary")
185
+ .withPathParameter("id", {type: "string"})
186
+ .withResponse(200, {data: {type: "object"}})
187
+ .build(),
188
+ ], asyncHandler(async (req, res) => {
189
+ return res.json({data: result});
190
+ }));
191
+ ```
192
+
193
+ #### API Conventions
194
+
195
+ - Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
196
+ - Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
197
+ - Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
198
+ - All model types live in `src/modelInterfaces.ts`
199
+ - In routes: `req.user` is `UserDocument | undefined`
200
+ - In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
201
+
202
+ ### @terreno/ui
203
+
204
+ React Native component library with 88+ components:
205
+
206
+ - **Layout**: Box, Page, SplitPage, Card
207
+ - **Forms**: TextField, SelectField, DateTimeField, CheckBox
208
+ - **Display**: Text, Heading, Badge, DataTable
209
+ - **Actions**: Button, IconButton, Link
210
+ - **Feedback**: Spinner, Modal, Toast
211
+ - **Theming**: TerrenoProvider, useTheme
212
+
213
+ Key imports:
214
+ ```typescript
215
+ import {
216
+ Box,
217
+ Button,
218
+ Card,
219
+ Page,
220
+ Text,
221
+ TextField,
222
+ TerrenoProvider,
223
+ } from "@terreno/ui";
224
+ ```
225
+
226
+ #### UI Component Examples
227
+
228
+ Layout with Box:
229
+ ```typescript
230
+ <Box direction="row" padding={4} gap={2} alignItems="center">
231
+ <Text>Content</Text>
232
+ <Button text="Action" />
233
+ </Box>
234
+ ```
235
+
236
+ Buttons:
237
+ ```typescript
238
+ <Button
239
+ text="Submit"
240
+ variant="primary" // 'primary' | 'secondary' | 'outline' | 'ghost'
241
+ onClick={handleSubmit}
242
+ loading={isLoading}
243
+ iconName="check"
244
+ />
245
+ ```
246
+
247
+ Forms:
248
+ ```typescript
249
+ <TextField
250
+ label="Email"
251
+ value={email}
252
+ onChangeText={setEmail}
253
+ error={emailError}
254
+ helperText="Enter a valid email"
255
+ />
256
+ ```
257
+
258
+ Modals:
259
+ ```typescript
260
+ <Modal
261
+ title="Confirm Action"
262
+ visible={isVisible}
263
+ primaryButtonText="Confirm"
264
+ secondaryButtonText="Cancel"
265
+ onDismiss={() => setIsVisible(false)}
266
+ onPrimaryAction={handleConfirm}
267
+ >
268
+ <Text>Are you sure?</Text>
269
+ </Modal>
270
+ ```
271
+
272
+ #### UI Common Pitfalls
273
+
274
+ - Don't use inline styles when theme values are available
275
+ - Don't use raw `View`/`Text` when `Box`/@terreno/ui `Text` are available
276
+ - Don't forget loading and error states
277
+ - Don't use `style` prop when equivalent props exist (`padding`, `margin`)
278
+ - Never modify `openApiSdk.ts` manually
279
+
280
+ ### @terreno/rtk
281
+
282
+ Redux Toolkit Query integration:
283
+
284
+ - **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
285
+ - **emptyApi**: Base RTK Query API for code generation
286
+ - **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
287
+
288
+ Key imports:
289
+ ```typescript
290
+ import {generateAuthSlice} from "@terreno/rtk";
291
+ ```
292
+
293
+ Always use generated SDK hooks - never use `axios` or `request` directly:
294
+
295
+ ```typescript
296
+ // Correct
297
+ import {useGetYourRouteQuery} from "@/store/openApiSdk";
298
+ const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
299
+
300
+ // Wrong - don't use axios directly
301
+ // const result = await axios.get("/api/yourRoute/value");
302
+ ```
303
+
304
+ ## React Best Practices (Frontend Packages)
305
+
306
+ - Use functional components with `React.FC` type
307
+ - Import hooks directly: `import {useEffect, useMemo} from 'react'`
308
+ - Always provide return types for functions
309
+ - Add explanatory comment above each `useEffect`
310
+ - Wrap callbacks in `useCallback`
311
+ - Prefer const arrow functions
312
+ - Use inline styles over `StyleSheet.create`
313
+ - Use Luxon for date operations
314
+ - Place static content and interfaces at beginning of file
315
+ - Minimize `use client`, `useEffect`, and `setState`
316
+ - Always support React-Native Web
317
+
318
+ ## CI/CD Workflows
319
+
320
+ ### Required Secret Validation
321
+
322
+ GitHub Actions workflows that use secrets or environment variables must validate all required variables are set before using them. Add a validation step early in the job that fails fast with a clear error message listing any missing variables.
323
+
324
+ ```yaml
325
+ - name: Validate required secrets
326
+ run: |
327
+ missing=()
328
+ if [ -z "$VAR_NAME" ]; then missing+=("VAR_NAME"); fi
329
+ if [ ${#missing[@]} -ne 0 ]; then
330
+ echo "::error::Missing required secrets: ${missing[*]}"
331
+ exit 1
332
+ fi
333
+ ```
334
+
335
+ ## Dependency Management
336
+
337
+ Uses [Bun Catalogs](https://bun.sh/docs/install/catalogs) - shared versions defined in root `package.json` under `catalog`. Reference with `catalog:` in workspace packages.
package/AGENTS.md ADDED
@@ -0,0 +1,337 @@
1
+ # Terreno
2
+
3
+ A monorepo containing shared packages for building full-stack applications with React Native and Express/Mongoose.
4
+
5
+ ## Packages
6
+
7
+ - **api/** - REST API framework built on Express/Mongoose (`@terreno/api`)
8
+ - **ui/** - React Native UI component library (`@terreno/ui`)
9
+ - **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
10
+ - **admin-backend/** - Admin panel backend plugin for @terreno/api (`@terreno/admin-backend`)
11
+ - **admin-frontend/** - Admin panel frontend screens for @terreno/api backends (`@terreno/admin-frontend`)
12
+ - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp-server`)
13
+ - **demo/** - Demo app for showcasing and testing UI components
14
+ - **example-frontend/** - Example Expo app demonstrating full stack usage
15
+ - **example-backend/** - Example Express backend using @terreno/api
16
+
17
+ ## Development
18
+
19
+ Uses [Bun](https://bun.sh/) as the package manager.
20
+
21
+ ```bash
22
+ bun install # Install dependencies
23
+ bun run compile # Compile all packages
24
+ bun run lint # Lint all packages
25
+ bun run lint:fix # Fix lint issues
26
+ bun run test # Run tests in api and ui
27
+ ```
28
+
29
+ ### Package-specific commands
30
+
31
+ ```bash
32
+ bun run api:test # Test API package
33
+ bun run ui:test # Test UI package
34
+ bun run demo:start # Start demo app
35
+ bun run frontend:web # Start frontend example
36
+ bun run backend:dev # Start backend example
37
+ bun run mcp:build # Build MCP server
38
+ bun run mcp:start # Start MCP server
39
+ bun run admin-backend:compile # Compile admin backend
40
+ bun run admin-frontend:compile # Compile admin frontend
41
+ ```
42
+
43
+ ## How the Packages Work Together
44
+
45
+ The three core packages form a complete full-stack framework:
46
+
47
+ ```
48
+ BACKEND
49
+ @terreno/api
50
+ - Mongoose models with modelRouter -> CRUD endpoints
51
+ - Built-in auth (JWT + Passport)
52
+ - Automatic OpenAPI spec generation
53
+ |
54
+ /openapi.json
55
+ |
56
+ RTK Query SDK Codegen
57
+ |
58
+ FRONTEND
59
+ @terreno/rtk
60
+ - Generated hooks from OpenAPI spec
61
+ - Auth slice with JWT token management
62
+ - Automatic token refresh
63
+ +
64
+ @terreno/ui
65
+ - React Native components (Box, Button, TextField, etc.)
66
+ - TerrenoProvider for theming
67
+ ```
68
+
69
+ ### Integration Flow
70
+
71
+ 1. **Backend (api)**: Define Mongoose models, use `modelRouter` to create CRUD endpoints with permissions
72
+ 2. **OpenAPI Generation**: `setupServer` automatically generates `/openapi.json`
73
+ 3. **SDK Codegen**: Frontend runs `bun run sdk` to generate RTK Query hooks from OpenAPI spec
74
+ 4. **Frontend (rtk + ui)**: Use generated hooks with UI components for type-safe API calls
75
+
76
+ ## Example Apps (Keep These Updated!)
77
+
78
+ The `example-frontend/` and `example-backend/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
79
+
80
+ 1. **Add examples** demonstrating new features
81
+ 2. **Update SDK** after backend changes: `cd example-frontend && bun run sdk`
82
+ 3. **Verify integration** by running both examples together
83
+
84
+ ### Running the Full Stack
85
+
86
+ ```bash
87
+ # Terminal 1: Start backend
88
+ bun run backend:dev
89
+
90
+ # Terminal 2: Start frontend
91
+ bun run frontend:web
92
+ ```
93
+
94
+ ## Code Style
95
+
96
+ ### TypeScript/JavaScript
97
+ - Use ES module syntax and TypeScript for all code
98
+ - Prefer interfaces over types; avoid enums, use maps
99
+ - Prefer const arrow functions over `function` keyword
100
+ - Use descriptive variable names with auxiliary verbs (e.g., `isLoading`)
101
+ - Use camelCase directories (e.g., `components/authWizard`)
102
+ - Favor named exports
103
+ - Use the RORO pattern (Receive an Object, Return an Object)
104
+
105
+ ### Dates and Time
106
+ - Always use Luxon instead of Date or dayjs
107
+
108
+ ### Error Handling
109
+ - Check error conditions at start of functions and return early
110
+ - Limit nested if statements
111
+ - Use multiline syntax with curly braces for all conditionals
112
+
113
+ ### Testing
114
+ - Use bun test with expect for testing
115
+
116
+ ### Logging
117
+ - Frontend: Use `console.info`, `console.debug`, `console.warn`, or `console.error` for permanent logs
118
+ - Backend: Use `logger.info/warn/error/debug` for permanent logs
119
+ - Use `console.log` only for debugging (to be removed)
120
+
121
+ ### Development Practices
122
+ - Don't apologize for errors: fix them
123
+ - Prioritize modularity, DRY, performance, and security
124
+ - Focus on readability over performance
125
+ - Write complete, functional code without TODOs when possible
126
+ - Comments should describe purpose, not effect
127
+
128
+ ## Package Reference
129
+
130
+ ### @terreno/api
131
+
132
+ REST API framework providing:
133
+
134
+ - **modelRouter**: Auto-generates CRUD endpoints for Mongoose models
135
+ - **Permissions**: `IsAuthenticated`, `IsOwner`, `IsAdmin`, `IsAuthenticatedOrReadOnly`
136
+ - **Query Filters**: `OwnerQueryFilter` for filtering list queries by owner
137
+ - **setupServer**: Express server setup with auth, OpenAPI, and middleware
138
+ - **APIError**: Standardized error handling
139
+ - **logger**: Winston-based logging
140
+
141
+ Key imports:
142
+ ```typescript
143
+ import {
144
+ modelRouter,
145
+ setupServer,
146
+ Permissions,
147
+ OwnerQueryFilter,
148
+ APIError,
149
+ logger,
150
+ asyncHandler,
151
+ authenticateMiddleware,
152
+ } from "@terreno/api";
153
+ ```
154
+
155
+ #### modelRouter Usage
156
+
157
+ ```typescript
158
+ import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
159
+
160
+ const router = modelRouter(YourModel, {
161
+ permissions: {
162
+ list: [Permissions.IsAuthenticated],
163
+ create: [Permissions.IsAuthenticated],
164
+ read: [Permissions.IsOwner],
165
+ update: [Permissions.IsOwner],
166
+ delete: [], // Disabled
167
+ },
168
+ sort: "-created",
169
+ queryFields: ["_id", "type", "name"],
170
+ });
171
+ ```
172
+
173
+ #### Custom Routes
174
+
175
+ For non-CRUD endpoints, use the OpenAPI builder:
176
+
177
+ ```typescript
178
+ import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
179
+
180
+ router.get("/yourRoute/:id", [
181
+ authenticateMiddleware(),
182
+ createOpenApiBuilder(options)
183
+ .withTags(["yourTag"])
184
+ .withSummary("Brief summary")
185
+ .withPathParameter("id", {type: "string"})
186
+ .withResponse(200, {data: {type: "object"}})
187
+ .build(),
188
+ ], asyncHandler(async (req, res) => {
189
+ return res.json({data: result});
190
+ }));
191
+ ```
192
+
193
+ #### API Conventions
194
+
195
+ - Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
196
+ - Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
197
+ - Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
198
+ - All model types live in `src/modelInterfaces.ts`
199
+ - In routes: `req.user` is `UserDocument | undefined`
200
+ - In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
201
+
202
+ ### @terreno/ui
203
+
204
+ React Native component library with 88+ components:
205
+
206
+ - **Layout**: Box, Page, SplitPage, Card
207
+ - **Forms**: TextField, SelectField, DateTimeField, CheckBox
208
+ - **Display**: Text, Heading, Badge, DataTable
209
+ - **Actions**: Button, IconButton, Link
210
+ - **Feedback**: Spinner, Modal, Toast
211
+ - **Theming**: TerrenoProvider, useTheme
212
+
213
+ Key imports:
214
+ ```typescript
215
+ import {
216
+ Box,
217
+ Button,
218
+ Card,
219
+ Page,
220
+ Text,
221
+ TextField,
222
+ TerrenoProvider,
223
+ } from "@terreno/ui";
224
+ ```
225
+
226
+ #### UI Component Examples
227
+
228
+ Layout with Box:
229
+ ```typescript
230
+ <Box direction="row" padding={4} gap={2} alignItems="center">
231
+ <Text>Content</Text>
232
+ <Button text="Action" />
233
+ </Box>
234
+ ```
235
+
236
+ Buttons:
237
+ ```typescript
238
+ <Button
239
+ text="Submit"
240
+ variant="primary" // 'primary' | 'secondary' | 'outline' | 'ghost'
241
+ onClick={handleSubmit}
242
+ loading={isLoading}
243
+ iconName="check"
244
+ />
245
+ ```
246
+
247
+ Forms:
248
+ ```typescript
249
+ <TextField
250
+ label="Email"
251
+ value={email}
252
+ onChangeText={setEmail}
253
+ error={emailError}
254
+ helperText="Enter a valid email"
255
+ />
256
+ ```
257
+
258
+ Modals:
259
+ ```typescript
260
+ <Modal
261
+ title="Confirm Action"
262
+ visible={isVisible}
263
+ primaryButtonText="Confirm"
264
+ secondaryButtonText="Cancel"
265
+ onDismiss={() => setIsVisible(false)}
266
+ onPrimaryAction={handleConfirm}
267
+ >
268
+ <Text>Are you sure?</Text>
269
+ </Modal>
270
+ ```
271
+
272
+ #### UI Common Pitfalls
273
+
274
+ - Don't use inline styles when theme values are available
275
+ - Don't use raw `View`/`Text` when `Box`/@terreno/ui `Text` are available
276
+ - Don't forget loading and error states
277
+ - Don't use `style` prop when equivalent props exist (`padding`, `margin`)
278
+ - Never modify `openApiSdk.ts` manually
279
+
280
+ ### @terreno/rtk
281
+
282
+ Redux Toolkit Query integration:
283
+
284
+ - **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
285
+ - **emptyApi**: Base RTK Query API for code generation
286
+ - **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
287
+
288
+ Key imports:
289
+ ```typescript
290
+ import {generateAuthSlice} from "@terreno/rtk";
291
+ ```
292
+
293
+ Always use generated SDK hooks - never use `axios` or `request` directly:
294
+
295
+ ```typescript
296
+ // Correct
297
+ import {useGetYourRouteQuery} from "@/store/openApiSdk";
298
+ const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
299
+
300
+ // Wrong - don't use axios directly
301
+ // const result = await axios.get("/api/yourRoute/value");
302
+ ```
303
+
304
+ ## React Best Practices (Frontend Packages)
305
+
306
+ - Use functional components with `React.FC` type
307
+ - Import hooks directly: `import {useEffect, useMemo} from 'react'`
308
+ - Always provide return types for functions
309
+ - Add explanatory comment above each `useEffect`
310
+ - Wrap callbacks in `useCallback`
311
+ - Prefer const arrow functions
312
+ - Use inline styles over `StyleSheet.create`
313
+ - Use Luxon for date operations
314
+ - Place static content and interfaces at beginning of file
315
+ - Minimize `use client`, `useEffect`, and `setState`
316
+ - Always support React-Native Web
317
+
318
+ ## CI/CD Workflows
319
+
320
+ ### Required Secret Validation
321
+
322
+ GitHub Actions workflows that use secrets or environment variables must validate all required variables are set before using them. Add a validation step early in the job that fails fast with a clear error message listing any missing variables.
323
+
324
+ ```yaml
325
+ - name: Validate required secrets
326
+ run: |
327
+ missing=()
328
+ if [ -z "$VAR_NAME" ]; then missing+=("VAR_NAME"); fi
329
+ if [ ${#missing[@]} -ne 0 ]; then
330
+ echo "::error::Missing required secrets: ${missing[*]}"
331
+ exit 1
332
+ fi
333
+ ```
334
+
335
+ ## Dependency Management
336
+
337
+ Uses [Bun Catalogs](https://bun.sh/docs/install/catalogs) - shared versions defined in root `package.json` under `catalog`. Reference with `catalog:` in workspace packages.
package/README.md ADDED
@@ -0,0 +1,5 @@
1
+ # @terreno/admin-backend
2
+
3
+ Admin panel backend plugin for `@terreno/api` that auto-generates admin CRUD endpoints for Mongoose models.
4
+
5
+ See the [full documentation](../.claude/rules/admin-backend/00-admin-backend.md) for usage, configuration, and integration details.
package/biome.jsonc ADDED
@@ -0,0 +1,20 @@
1
+ {
2
+ "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json",
3
+ "extends": ["../biome.jsonc"],
4
+ "files": {
5
+ "includes": [
6
+ "package.json",
7
+ "src/**/*.ts",
8
+ "src/**/*.tsx",
9
+ "!!**/node_modules",
10
+ "!!node_modules",
11
+ "!!**/dist",
12
+ "!!dist",
13
+ "!!**/build",
14
+ "!!build",
15
+ "!!**/coverage",
16
+ "!!coverage"
17
+ ]
18
+ },
19
+ "root": true
20
+ }
package/bunfig.toml ADDED
@@ -0,0 +1,3 @@
1
+ [test]
2
+ preload = ["../api/src/tests/bunSetup.ts"]
3
+ root = "./src"