@tailor-platform/erp-kit 0.2.0 → 0.2.2

package/skills/erp-kit-app-6-impl-frontend/references/pages.md

@@ -0,0 +1,160 @@
+# Frontend Pages
+
+### GraphQL Setup
+
+All operations use gql.tada for type safety:
+
+```ts
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+```
+
+Built-in queries (`gqlOperations: "query"`) generate:
+
+- `<Entity>(id: ID!)` — get by ID
+- `<entities>` — list with connection pattern (`edges { node { ... } }`)
+
+Mutations are defined by custom resolvers.
+
+### ListView
+
+Key points:
+
+- Query uses connection pattern: `edges { node { ...Fragment } }`
+- Two-level fragments: row fragment for items, table fragment for the connection
+- `EmptyState` when `edges.length === 0`
+- Columns map to screen spec's "Required Columns"
+- `Layout` with title and create action button
+
+### DetailView
+
+Key points:
+
+- Two-column `Layout`: detail on left, actions on right
+- `useParams()` to get entity ID from route
+- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields:
+
+```tsx
+<DescriptionCard
+  data={resource}
+  title="Overview"
+  columns={3}
+  fields={[
+    { key: "name", label: "Name", meta: { copyable: true } },
+    {
+      key: "status",
+      label: "Status",
+      type: "badge",
+      meta: { badgeVariantMap: { ACTIVE: "success" } },
+    },
+    { key: "createdAt", label: "Created At", type: "date", meta: { dateFormat: "medium" } },
+  ]}
+/>
+```
+
+Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
+
+### Form Pattern
+
+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
+
+#### Field Type Mapping
+
+| 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([...])` |
+| Date       | `<Input type="date" />`   | `z.string()` (ISO format)       |
+| Number     | `<Input type="number" />` | `z.coerce.number()`             |
+| Checkbox   | `<Checkbox />`            | `z.boolean()`                   |
+
+#### Validation
+
+- **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
+- **Required: No** → `.optional()`
+
+### Shared Component Patterns
+
+#### Fragment Collocation
+
+Each component defines and exports its own GraphQL fragment. The parent page imports it and includes it in the query:
+
+```tsx
+// components/user-card.tsx
+export const UserCardFragment = graphql(`
+  fragment UserCard on User {
+    id
+    name
+    email
+  }
+`);
+
+export const UserCard = ({ user }: { user: FragmentOf<typeof UserCardFragment> }) => {
+  const data = readFragment(UserCardFragment, user);
+  return <div>{data.name}</div>;
+};
+
+// page.tsx
+const UserQuery = graphql(
+  `
+    query User($id: ID!) {
+      user(id: $id) {
+        ...UserCard
+      }
+    }
+  `,
+  [UserCardFragment],
+);
+```
+
+#### App.tsx
+
+- `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
+
+#### Module-level page.tsx (required)
+
+Every module directory must have a `page.tsx` that redirects to the first child. Use **absolute paths** to avoid double-path bugs:
+
+```tsx
+useEffect(() => {
+  void navigate("/item-management/item", { replace: true });
+}, [navigate]);
+```
+
+#### Page conventions
+
+Every page component must:
+
+1. Be the **default export** of `page.tsx`
+2. Set `appShellPageProps` with at least `meta.title`
+
+#### Common imports
+
+```tsx
+import {
+  Layout,
+  Link,
+  useParams,
+  useNavigate,
+  type AppShellPageProps,
+} from "@tailor-platform/app-shell";
+import { useQuery, useMutation } from "urql";
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+```

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.