@tailor-platform/erp-kit 0.2.1 → 0.2.2

package/skills/{erp-kit-app-5-implementation/references/frontend.md → erp-kit-app-6-impl-frontend/references/pages.md}

@@ -1,91 +1,4 @@
-# Frontend Implementation Patterns
-
-## Table of Contents
-
-- [Frontend Scaffold](#frontend-scaffold)
-- [Frontend Pages](#frontend-pages)
-
----
-
-## Frontend Scaffold
-
-```
-frontend/
-├── src/
-│   ├── main.tsx, App.tsx, index.css
-│   ├── graphql/
-│   │   ├── index.ts                      # gql.tada setup
-│   │   └── generated/                    # Placeholder until backend deploy
-│   ├── lib/
-│   │   ├── auth-client.ts
-│   │   └── utils.ts                      # cn() utility
-│   ├── providers/
-│   │   └── graphql-provider.tsx          # urql client with DPoP auth
-│   ├── components/
-│   │   ├── ui/                           # shadcn/Radix primitives
-│   │   └── composed/                     # empty-state, error-fallback, loading
-│   └── pages/
-│       └── <domain>/
-│           ├── page.tsx                  # Module redirect (REQUIRED)
-│           └── <entity>/
-│               ├── page.tsx              # ListView
-│               ├── components/<entities>-table.tsx
-│               ├── create/page.tsx + components/create-<entity>-form.tsx
-│               └── [id]/
-│                   ├── page.tsx          # DetailView
-│                   ├── components/<entity>-detail.tsx, <entity>-actions.tsx
-│                   └── edit/page.tsx + components/edit-<entity>-form.tsx
-├── scripts/generate-graphql.mjs
-├── package.json, vite.config.ts, tsconfig.json, eslint.config.js
-└── components.json
-```
-
-`package.json` key dependencies and scripts:
-
-```json
-{
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc -b && vite build",
-    "generate": "node --env-file=.env ./scripts/generate-graphql.mjs",
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@tailor-platform/app-shell": "...",
-    "gql.tada": "...",
-    "urql": "...",
-    "react-hook-form": "...",
-    "@hookform/resolvers": "...",
-    "zod": "...",
-    "tailwindcss": "...",
-    "lucide-react": "..."
-  },
-  "devDependencies": {
-    "@tailor-platform/app-shell-vite-plugin": "...",
-    "@tailor-platform/sdk": "...",
-    "@tailwindcss/vite": "...",
-    "vite": "...",
-    "typescript": "..."
-  }
-}
-```
-
-`scripts/generate-graphql.mjs` — fetches the GraphQL schema from the deployed backend:
-
-```js
-import { execSync } from "node:child_process";
-const url = process.env.VITE_TAILOR_APP_URL;
-execSync(`pnpm gql-tada generate schema "${url}/query"`);
-execSync("pnpm gql-tada generate output");
-```
-
-Before deployment, create empty placeholders for `src/graphql/generated/schema.graphql` and `graphql-env.d.ts` so the project compiles. After backend deployment, configure `.env` with `VITE_TAILOR_APP_URL` and `VITE_TAILOR_CLIENT_ID`, then run `pnpm generate` to regenerate them.
-
----
-
-## Frontend Pages
+# Frontend Pages
 
 ### GraphQL Setup
 
@@ -146,6 +59,8 @@ Create and edit forms share the same structure:
 
 - **React Hook Form + Zod** for validation with `zodResolver`
 - **urql `useMutation`** for GraphQL mutations
+- **Cache invalidation**: pass `additionalTypenames` to the mutation context so urql invalidates related queries (e.g., `createUser(values, { additionalTypenames: ["User"] })`)
+- **Toast notifications**: use `useToast` from `@tailor-platform/app-shell` (sonner-based, `Toaster` is built into AppShell) for success/error feedback
 - **Navigate `".."`** to go back to list after success
 - Edit form pre-fills `defaultValues` from existing entity via fragment
 
@@ -153,6 +68,7 @@ Create and edit forms share the same structure:
 
 | Field Type | Component                 | Zod Schema                      |
 | ---------- | ------------------------- | ------------------------------- |
+| Email      | `<Input type="email" />`  | `z.email()`                     |
 | Text       | `<Input />`               | `z.string()`                    |
 | Textarea   | `<textarea />`            | `z.string()`                    |
 | Dropdown   | `<Select />`              | `z.string()` or `z.enum([...])` |
@@ -201,8 +117,10 @@ const UserQuery = graphql(
 
 #### App.tsx
 
-- `AuthGuard` is not exported from app-shell — implement it yourself, pass via `guardComponent` prop
-- `GraphQLProvider` needs `authClient` prop to attach DPoP auth headers
+- `AuthGuard`: implement yourself, pass via `guardComponent` prop. AuthProvider shows it automatically when `!isReady || !isAuthenticated`, so the guard only needs to render a sign-in UI — no state checks needed inside it
+- `GraphQLProvider`: pass `authClient.fetch` directly to urql's `fetch` option and `authClient.getAppUri()` for the URL
+- `useAuth()` returns `{ isAuthenticated, isReady, login, logout }` directly (not nested in `authState`)
+- Built-in `me` query returns the current user's `User` record — use it instead of writing a custom resolver for profile info
 - Required env vars: `VITE_TAILOR_APP_URL`, `VITE_TAILOR_CLIENT_ID`
 - Auth client: create once in `src/lib/auth-client.ts` using `createAuthClient({ appUri, clientId })`
 - Sidebar: use `SidebarGroup` + `SidebarItem` for custom ordering

package/skills/erp-kit-app-7-impl-review/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: erp-kit-app-7-impl-review
+description: Review implementation parity between documentation and code for app-compose applications. Use after frontend implementation (step 6) to validate code matches documentation.
+---
+
+# Implementation Parity Review
+
+Review **implementation consistency** between Tier 3-4 documentation and actual backend/frontend code.
+
+## When to Use
+
+- After backend and frontend implementation, verify code matches documentation
+- Before merging feature branches
+- Quality check during code review
+
+## Step 1: Setup
+
+Define shared context for all agents:
+
+- `APP_ROOT`: from argument or current working directory. Must contain a `docs/` directory.
+- `APP_NAME`: basename of APP_ROOT
+- `RESOLVER_DOCS`: glob `<APP_ROOT>/docs/resolver/*.md`
+- `SCREEN_DOCS`: glob `<APP_ROOT>/docs/screen/*.md`
+- `BACKEND_RESOLVERS`: glob `<APP_ROOT>/backend/src/modules/*/resolvers/*.ts`
+- `BACKEND_EXECUTORS`: glob `<APP_ROOT>/backend/executors/*.ts`
+- `BACKEND_MODULES`: `<APP_ROOT>/backend/src/modules.ts`
+- `BACKEND_CONFIG`: `<APP_ROOT>/backend/tailor.config.ts`
+- `FRONTEND_PAGES`: glob `<APP_ROOT>/frontend/src/app/(main)/**/*.tsx`
+
+Verify at least `RESOLVER_DOCS` or `SCREEN_DOCS` is non-empty. If no docs exist, stop with: "No docs found for app <APP_NAME>."
+
+## Step 2: Dispatch Agents (parallelize if possible)
+
+Launch 4 Agent tool calls in parallel — one per parity check.
+Each agent receives: APP_NAME, relevant doc/code file paths.
+Each agent returns: structured JSON per [references/impl-parity-report-format.md](references/impl-parity-report-format.md).
+If a doc or code directory is empty, the agent reports "no files found" and skips.
+
+| Agent | Prompt Template                                                                  | Inputs                                              |
+| ----- | -------------------------------------------------------------------------------- | --------------------------------------------------- |
+| 1     | [references/resolver-doc-code-parity.md](references/resolver-doc-code-parity.md) | RESOLVER_DOCS, BACKEND_RESOLVERS, BACKEND_EXECUTORS |
+| 2     | [references/screen-doc-code-parity.md](references/screen-doc-code-parity.md)     | SCREEN_DOCS, FRONTEND_PAGES                         |
+| 3     | [references/module-wiring-parity.md](references/module-wiring-parity.md)         | RESOLVER_DOCS, BACKEND_MODULES, BACKEND_CONFIG      |
+| 4     | (build verification — inline, no template)                                       | APP_ROOT                                            |
+
+For agents 1-3:
+
+1. Read the prompt template file
+2. Replace `{{APP_NAME}}` with the resolved app name
+3. Replace doc/code path placeholders with the actual file paths
+4. Dispatch the agent with the filled prompt
+
+For agent 4 (build verification):
+
+Run build checks inline:
+
+```bash
+cd <APP_ROOT>/backend && pnpm lint && pnpm typecheck
+cd <APP_ROOT>/frontend && pnpm lint && pnpm typecheck && pnpm build
+```
+
+Report pass/fail for each check.
+
+## Step 3: Aggregate Results
+
+After ALL agents return:
+
+1. Collect the JSON results from each agent
+2. Merge all `gaps[]` arrays into a single list
+3. Merge all `inconsistencies[]` arrays into a single list
+4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
+5. Calculate totals across all summaries
+6. Render the final report below
+
+## Report Format
+
+Render the aggregated results as markdown:
+
+### Implementation Parity Review Report
+
+**Application:** <APP_NAME>
+
+---
+
+### 1. Resolver Doc → Backend Code Coverage
+
+| Resolver Doc | Module Command | Implemented | Error Handling | Gap |
+| ------------ | -------------- | ----------- | -------------- | --- |
+
+(Populated from agent 1 gaps)
+
+---
+
+### 2. Screen Doc → Frontend Code Coverage
+
+| Screen Doc | Screen Type | Page Exists | Fields Match | Gap |
+| ---------- | ----------- | ----------- | ------------ | --- |
+
+(Populated from agent 2 gaps)
+
+---
+
+### 3. Module Wiring Consistency
+
+| Resolver | Required Module | Wired in modules.ts | Config Reference | Gap |
+| -------- | --------------- | ------------------- | ---------------- | --- |
+
+(Populated from agent 3 gaps)
+
+---
+
+### 4. Build Verification
+
+| Check | Backend | Frontend |
+| ----- | ------- | -------- |
+| Lint  |         |          |
+| Types |         |          |
+| Build | N/A     |          |
+
+(Populated from agent 4 results)
+
+---
+
+### 5. Missing Implementation
+
+#### Missing Backend Resolvers
+
+| Resolver Doc | Expected File | Purpose |
+| ------------ | ------------- | ------- |
+
+#### Missing Frontend Pages
+
+| Screen Doc | Expected Path | Screen Type |
+| ---------- | ------------- | ----------- |
+
+#### Missing Module Wiring
+
+| Module | Referenced by Resolver | Status |
+| ------ | ---------------------- | ------ |
+
+(Populated from all agents' gaps where status is `fail`)
+
+---
+
+### 6. Inconsistencies
+
+| Type | Location | Issue |
+| ---- | -------- | ----- |
+
+(Populated from all agents' `inconsistencies[]`)
+
+---
+
+### 7. Summary
+
+| Aspect                       | Status | Details           |
+| ---------------------------- | ------ | ----------------- |
+| Resolver Doc → Code Coverage |        | X/Y checks passed |
+| Screen Doc → Code Coverage   |        | X/Y checks passed |
+| Module Wiring Consistency    |        | X/Y checks passed |
+| Build Verification           |        | pass / fail       |
+
+### 8. Recommendations
+
+Numbered list of actionable fixes, grouped by priority:
+
+1. Implement missing resolvers/pages (highest priority)
+2. Fix module wiring gaps
+3. Resolve field/type mismatches
+4. Fix build errors
+
+## References
+
+- [Implementation parity report format](references/impl-parity-report-format.md)
+- For backend patterns, see erp-kit-app-5-impl-backend
+- For frontend patterns, see erp-kit-app-6-impl-frontend

package/skills/erp-kit-app-7-impl-review/references/impl-parity-report-format.md

@@ -0,0 +1,52 @@
+# Implementation Parity Report Format
+
+All implementation parity check agents return results in this JSON structure.
+
+## Schema
+
+```json
+{
+  "check_type": "<one of: resolver-doc-code-parity, screen-doc-code-parity, module-wiring-parity>",
+  "app": "<app-name>",
+  "gaps": [
+    {
+      "source": "<source doc or code path>",
+      "target": "<target code or doc path, or 'missing'>",
+      "check": "<check_id from the agent's parity checks table>",
+      "status": "pass | fail | skip",
+      "detail": "<human-readable description of the finding>"
+    }
+  ],
+  "inconsistencies": [
+    {
+      "type": "<inconsistency type, e.g. type_mismatch, missing_field>",
+      "location": "<source vs target description>",
+      "detail": "<human-readable description>"
+    }
+  ],
+  "summary": {
+    "total_checks": 0,
+    "passed": 0,
+    "failed": 0,
+    "skipped": 0
+  }
+}
+```
+
+## Field Reference
+
+### gaps[]
+
+One entry per parity check performed. `status` is:
+
+- `pass`: doc and code are consistent
+- `fail`: gap or mismatch found
+- `skip`: target code/doc missing or empty, check could not run
+
+### inconsistencies[]
+
+Cross-cutting issues that don't fit a single gap entry (e.g., type mismatches, naming violations, missing patterns).
+
+### summary
+
+Aggregate counts. `total_checks = passed + failed + skipped`.

package/skills/erp-kit-app-7-impl-review/references/module-wiring-parity.md

@@ -0,0 +1,84 @@
+# Module Wiring Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Resolver docs: {{RESOLVER_DOCS}}
+Backend modules file: {{BACKEND_MODULES}}
+Backend config file: {{BACKEND_CONFIG}}
+
+## Instructions
+
+1. Read ALL resolver docs at the paths above
+2. Read the modules file (`src/modules.ts`)
+3. Read the config file (`tailor.config.ts`)
+4. Verify all required modules are wired and configured
+5. Return results as JSON per the Output Format section
+
+## Extraction: Resolver Docs
+
+From each resolver doc, extract:
+
+- Module it depends on (which `defineXxxModule` it needs)
+- Commands it calls (which module command functions)
+
+## Extraction: modules.ts
+
+From the modules file, extract:
+
+- All `defineXxxModule()` calls
+- Inter-module dependency wiring (e.g., primitives passed to item-management)
+- Exported `db`, `commands`, and `executors`
+
+## Extraction: tailor.config.ts
+
+From the config file, extract:
+
+- DB namespace configuration
+- Resolver/executor glob patterns
+- Auth configuration (IdP, Auth, user profile)
+- Generator configuration
+
+## Parity Checks
+
+| Check ID             | Question                                                         |
+| -------------------- | ---------------------------------------------------------------- |
+| module_wired         | Is every module referenced by resolvers wired in modules.ts?     |
+| dependency_order     | Are inter-module dependencies passed correctly?                  |
+| exports_complete     | Are db, commands, and executors all exported?                    |
+| config_resolver_glob | Does the resolver glob in config cover all resolver directories? |
+| config_executor_glob | Does the executor glob in config cover all executor files?       |
+| config_db_namespace  | Is the DB namespace configured?                                  |
+| config_auth          | Is auth configured with IdP, Auth, and user profile?             |
+
+### How to Check
+
+1. Build a set of required modules from resolver docs
+2. Check each required module appears as a `defineXxxModule()` call in modules.ts
+3. Verify dependency wiring (e.g., if item-management resolvers exist, primitives must be wired into it)
+4. Check tailor.config.ts resolver glob pattern covers all module resolver directories
+5. Verify auth is configured if any resolver requires authentication
+
+## Common Gap Patterns
+
+- **Missing module**: Resolver references a module not wired in modules.ts
+- **Missing dependency**: Module wired but not given required dependencies
+- **Glob mismatch**: Config resolver glob doesn't cover a module's resolvers directory
+- **Missing auth**: Resolvers exist but no auth configured
+- **Missing executors**: Module has event handlers but no executor glob configured
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "module-wiring-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/erp-kit-app-7-impl-review/references/resolver-doc-code-parity.md

@@ -0,0 +1,86 @@
+# Resolver Doc → Backend Code Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Resolver docs: {{RESOLVER_DOCS}}
+Backend resolvers: {{BACKEND_RESOLVERS}}
+Backend executors: {{BACKEND_EXECUTORS}}
+
+## Instructions
+
+1. Read ALL resolver docs at the paths above
+2. Read ALL backend resolver code files at the paths above
+3. Read ALL backend executor code files at the paths above
+4. For each resolver doc, check if it has a corresponding implementation
+5. Return results as JSON per the Output Format section
+
+## Extraction: Resolver Docs
+
+From each resolver doc, extract:
+
+- Resolver name (from filename or heading)
+- Type: Mutation or Query
+- Module and command it calls
+- Input parameters (name, type, required/optional)
+- Error scenarios (error codes and conditions)
+- Expected output shape
+
+## Extraction: Backend Code
+
+From each resolver file (`src/modules/*/resolvers/*.ts`), extract:
+
+- Resolver name (from `createResolver()` call or filename)
+- Module command called (import path and function name)
+- Input parameter handling (`context.input.*` accesses)
+- Error handling (`result.error.code` switch cases)
+- Return value structure
+
+From each executor file (`executors/*.ts`), extract:
+
+- Executor name and which module event handler it re-exports
+
+## Parity Checks
+
+| Check ID             | Question                                                        |
+| -------------------- | --------------------------------------------------------------- |
+| resolver_impl_exists | Does a backend resolver file exist for each resolver doc?       |
+| command_reference    | Does the resolver code call the correct module command?         |
+| input_coverage       | Does the resolver handle all documented input parameters?       |
+| error_handling       | Does the resolver handle all documented error scenarios?        |
+| return_shape         | Does the resolver return the documented output shape?           |
+| executor_exists      | Does an executor exist for each module that has event handlers? |
+| no_direct_mutation   | Does the resolver avoid directly mutating module-owned tables?  |
+
+### How to Check
+
+1. For each resolver doc, find the corresponding code file by name
+2. Verify the code imports and calls the documented module command
+3. Check that `context.input.*` accesses match documented inputs
+4. Check that error `switch` cases cover all documented error codes
+5. Verify return value structure matches documentation
+6. Check executors re-export module event handlers without custom logic
+
+## Common Gap Patterns
+
+- **Missing resolver file**: Doc exists but no code file
+- **Wrong command**: Code calls a different module command than documented
+- **Missing input handling**: Doc specifies an input parameter not accessed in code
+- **Missing error cases**: Error scenario in doc not handled in code's switch
+- **Direct table mutation**: Code uses `db.insertInto()` on module-owned tables instead of module commands
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "resolver-doc-code-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/erp-kit-app-7-impl-review/references/screen-doc-code-parity.md

@@ -0,0 +1,86 @@
+# Screen Doc → Frontend Code Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Screen docs: {{SCREEN_DOCS}}
+Frontend pages: {{FRONTEND_PAGES}}
+
+## Instructions
+
+1. Read ALL screen docs at the paths above
+2. Read ALL frontend page/component files at the paths above
+3. For each screen doc, check if a corresponding page implementation exists
+4. Return results as JSON per the Output Format section
+
+## Extraction: Screen Docs
+
+From each screen doc, extract:
+
+- Screen name (from filename or heading)
+- Screen type: ListView, Form (create/edit), or DetailView
+- Fields/columns specified
+- Actions specified (create, edit, delete, activate, etc.)
+- Navigation targets
+
+## Extraction: Frontend Code
+
+From frontend pages, identify:
+
+- Page files (`page.tsx`) and their routes
+- Component files (tables, forms, details, actions)
+- GraphQL fragments and queries used
+- Form fields and validation schemas (Zod)
+- Table columns defined
+- Action buttons and navigation
+
+### Screen Type → File Pattern
+
+| Screen Type   | Expected Files                                                       |
+| ------------- | -------------------------------------------------------------------- |
+| ListView      | `page.tsx` + `components/<entity>-table.tsx`                         |
+| Form (create) | `create/page.tsx` + `create/components/create-<entity>-form.tsx`     |
+| Form (edit)   | `[id]/edit/page.tsx` + `[id]/edit/components/edit-<entity>-form.tsx` |
+| DetailView    | `[id]/page.tsx` + `[id]/components/<entity>-detail.tsx`              |
+
+## Parity Checks
+
+| Check ID          | Question                                                      |
+| ----------------- | ------------------------------------------------------------- |
+| page_exists       | Does a page file exist for each screen doc?                   |
+| component_exists  | Do the expected components exist for the screen type?         |
+| field_coverage    | Does the page/component render all documented fields/columns? |
+| action_coverage   | Does the page implement all documented actions?               |
+| screen_type_match | Does the implementation match the documented screen type?     |
+
+### How to Check
+
+1. For each screen doc, map the screen name to an expected route path
+2. Check if the expected `page.tsx` and component files exist
+3. Read component code and verify documented fields appear (in table columns, form fields, or detail fields)
+4. Verify documented actions appear as buttons, links, or mutations
+5. Confirm the implementation pattern matches the screen type (table for ListView, form for Form, etc.)
+
+## Common Gap Patterns
+
+- **Missing page**: Screen doc exists but no page file
+- **Missing component**: Page exists but table/form/detail component missing
+- **Missing fields**: Doc specifies columns/fields not rendered in code
+- **Missing actions**: Doc specifies actions not implemented
+- **Type mismatch**: Doc says ListView but implementation is a DetailView
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "screen-doc-code-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.