@tailor-platform/erp-kit 0.2.1 → 0.3.0

package/skills/erp-kit-app-4-plan-review/references/story-resolver-parity.md

@@ -0,0 +1,83 @@
+# Story → Resolver Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Story docs: {{STORY_DOCS}}
+Resolver docs: {{RESOLVER_DOCS}}
+
+## Instructions
+
+1. Read ALL story docs at the paths above
+2. Read ALL resolver docs at the paths above
+3. For each story, check resolver coverage
+4. Return results as JSON per the Output Format section
+
+## Extraction: Story Docs
+
+From each story doc, extract:
+
+- Story name (from filename or heading)
+- Resolver section content:
+  - `None` → read-only story, skip resolver checks
+  - `- TBD` → story needs resolvers but none documented yet (fail)
+  - Resolver links (format: `../../../resolver/<name>.md`) → verify they exist
+- Operations described that imply mutations (create, update, delete, submit, approve, etc.)
+
+## 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 and error scenarios
+
+## Parity Checks
+
+For each story:
+
+| Check ID           | Question                                                                 |
+| ------------------ | ------------------------------------------------------------------------ |
+| resolver_existence | Do all resolver links in the story resolve to existing docs?             |
+| resolver_coverage  | Does every non-read-only story have at least one resolver?               |
+| resolver_tbd       | Are there stories still showing `- TBD` for resolvers?                   |
+| link_validity      | Do resolver links in the story resolve to real files?                    |
+| operation_coverage | Do story operations (create/update/delete) have matching resolver types? |
+
+### How to Check
+
+1. Read each story's `## Resolvers` section
+2. If `None` → skip (read-only story)
+3. If `- TBD` → fail: resolver docs not yet created
+4. If links present → verify each link resolves to a file in RESOLVER_DOCS
+5. Cross-check story operations against resolver types (mutation for writes, query for reads)
+
+## Link Format Reference
+
+| From  | To       | Format                        |
+| ----- | -------- | ----------------------------- |
+| Story | Resolver | `../../../resolver/<name>.md` |
+
+## Common Gap Patterns
+
+- **TBD resolvers**: Story still has placeholder `- TBD` instead of resolver links
+- **Missing resolver docs**: Story links to a resolver that has no doc
+- **Operation mismatch**: Story describes a create operation but no create resolver exists
+- **Orphaned resolvers**: Resolver doc exists but no story links to it (covered by orphan detection)
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "story-resolver-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [parity-report-format.md](parity-report-format.md) for field definitions.

package/skills/erp-kit-app-4-plan-review/references/story-screen-parity.md

@@ -0,0 +1,73 @@
+# Story → Screen Parity Check
+
+## Context
+
+App: {{APP_NAME}}
+Story docs: {{STORY_DOCS}}
+Screen docs: {{SCREEN_DOCS}}
+
+## Instructions
+
+1. Read ALL story docs at the paths above
+2. Read ALL screen docs at the paths above
+3. For each story, extract referenced screens
+4. Run every parity check below against each story
+5. Return results as JSON per the Output Format section
+
+## Extraction: Story Docs
+
+From each story doc, extract:
+
+- Story name (from filename or heading)
+- All screen references (format: `../../../screen/<screen>.md`)
+- UI interactions described that imply screen usage
+
+## Extraction: Screen Docs
+
+From each screen doc, extract:
+
+- Screen name (from filename or heading)
+- Screen type and UI components described
+
+## Parity Checks
+
+For each story's screen references:
+
+| Check ID         | Question                                            |
+| ---------------- | --------------------------------------------------- |
+| screen_existence | Do all screens referenced in the story exist?       |
+| link_validity    | Do screen links in the story resolve to real files? |
+
+### How to Check
+
+1. List all screen references from each story doc
+2. Verify a corresponding screen doc exists for each reference
+3. Validate that all `../../../screen/<screen>.md` links resolve to actual files in SCREEN_DOCS
+
+## Link Format Reference
+
+| From  | To     | Format                        |
+| ----- | ------ | ----------------------------- |
+| Story | Screen | `../../../screen/<screen>.md` |
+
+## Common Gap Patterns
+
+- **Missing screen docs**: Story references a screen that has no doc
+- **Broken screen links**: Story links to a screen file that does not exist
+- **Implicit screens**: Story describes UI interaction but has no explicit screen link
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "story-screen-parity",
+  "app": "{{APP_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [parity-report-format.md](parity-report-format.md) for field definitions.

package/skills/erp-kit-app-5-impl-backend/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: erp-kit-app-5-impl-backend
+description: Implement backend code for app-compose applications using erp-kit modules. Use after completing plan review with erp-kit-app-4-plan-review. Triggers when implementing backend resolvers, wiring modules, configuring applications, or when the user mentions implementing backend, writing resolvers, or connecting erp-kit modules.
+---
+
+# App-Compose Backend Implementation
+
+Implement backend resolvers and application configuration for an app-compose application, driven by Tier 1-4 documentation (actors, business flows, stories, screens, resolvers).
+
+## When to Use
+
+- Implementing backend resolvers from resolver spec docs
+- Wiring erp-kit modules into an application
+- Configuring the Tailor application (auth, DB, resolvers)
+- Deploying the backend for frontend schema generation
+
+## Prerequisites
+
+All four tiers of documentation must exist:
+
+- `README.md` — Application overview
+- `docs/actors/*.md` — Actor definitions
+- `docs/business-flow/*/README.md` + `story/*.md` — Business flows and user stories
+- `docs/screen/*.md` — Screen specifications (ListView, Form, DetailView)
+- `docs/resolver/*.md` — Resolver specifications (mutations, queries)
+
+## Workflow
+
+```
+ANALYZE DOCS → MODULE WIRING → CONFIG → RESOLVERS → GENERATED FILES → VERIFY → DEPLOY
+```
+
+### Phase 1: Analyze Documentation
+
+Read all resolver and screen specs to build a complete picture:
+
+1. **Resolver docs** (`docs/resolver/*.md`) — Identify which module commands each resolver calls, what inputs/outputs it needs, and what errors it handles
+2. **Screen docs** (`docs/screen/*.md`) — Identify screen types (ListView, Form, DetailView) and their fields/columns/actions
+3. **Command source types** — For each module command the resolver calls, read the input type at `node_modules/@tailor-platform/erp-kit/src/modules/<module>/command/<commandName>.ts`. Do not invent fields that don't exist in the command, and preserve the required/optional distinction.
+
+Classify resolvers per [erp-kit-app-shared/references/resolver-classification.md](../erp-kit-app-shared/references/resolver-classification.md).
+
+### Phase 2: Wire Modules (`src/modules.ts`)
+
+Create the module wiring file that composes all required erp-kit modules.
+
+**Read [module wiring reference](references/module-wiring.md) for the composition pattern.**
+
+Key points:
+
+- Use `defineXxxModule()` functions from `@tailor-platform/erp-kit/module`
+- Pass inter-module dependencies explicitly (e.g., item-management needs primitives' unit type and query)
+- Export `db`, `commands`, and `executors` for use in resolvers
+
+### Phase 3: Configure Application (`tailor.config.ts`)
+
+**Read [application config reference](references/app-config.md) for the config pattern.**
+
+Key points:
+
+- Single DB namespace (`"main-db"`) with `gqlOperations: "query"` for automatic list/get queries
+- Resolver/executor discovery via glob patterns
+- Auth with OAuth2, DPoP, and user profile mapping
+- Generators for Kysely types and seed data
+
+### Phase 4: Implement Backend Resolvers and Executors
+
+Write one file per resolver under `src/modules/<module-name>/resolvers/`, one per executor under `executors/`.
+
+**Read [resolver & executor patterns reference](references/resolver-patterns.md).**
+
+Do not directly mutate module-owned tables via Kysely — always use module commands.
+
+### Phase 5: Generated Files
+
+- **Kysely types** (`src/generated/kysely-tailordb.ts`) — Auto-generated by `pnpm generate` after deployment. Before deployment, create a minimal placeholder so the codebase typechecks.
+- **Seed data** (`seed/`) — `exec.mjs` runner + `data/*.jsonl` (records) and `data/*.schema.ts` (validation). Create seed records for initial data (permissions, roles, test users, etc.). Seeded users must have concrete permission keys required by the wired modules.
+
+### Phase 6: Verify
+
+```bash
+cd <app-root>/backend
+pnpm lint
+pnpm typecheck
+```
+
+### Phase 7: Deploy Backend & Next Steps
+
+Frontend implementation requires a deployed backend (for GraphQL schema generation). Prompt the user to:
+
+1. Create a workspace and configure `.env` (including `TAILOR_PLATFORM_WORKSPACE_ID`)
+2. Run `pnpm deploy` and `pnpm generate`
+3. Run `pnpm seed` if seed data was created
+4. Retrieve OAuth2 client ID via `tailor-sdk oauth2client get default --json` for frontend `.env`
+
+Wait for the user to confirm deployment is complete before proceeding.
+
+After deployment is confirmed, proceed to frontend implementation with `/erp-kit-app-6-impl-frontend`.

package/skills/erp-kit-app-5-impl-backend/references/app-config.md

@@ -0,0 +1,38 @@
+# Application Config
+
+`tailor.config.ts` defines the Tailor application configuration. Key structure:
+
+```ts
+export default defineConfig({
+  name: "<app-name>",
+  cors: ["http://localhost:5173", website.url],
+  db: {
+    "main-db": {
+      files: [`./src/modules.ts`],
+      gqlOperations: "query",
+    },
+  },
+  resolver: {
+    "main-resolver": { files: [`./src/modules/**/resolvers/**/*.ts`] },
+  },
+  executor: { files: [`./src/modules/**/executors/**/*.ts`] },
+  auth: auth,
+  idp: [idp],
+  staticWebsites: [website],
+});
+```
+
+Key points:
+
+- `gqlOperations: "query"` — Auto-generates list/get GraphQL queries for all DB types
+- Glob patterns for resolver/executor discovery
+- See [SDK configuration docs](https://raw.githubusercontent.com/tailor-platform/sdk/refs/heads/main/packages/sdk/docs/configuration.md) for full config options
+
+## Auth configuration
+
+- Define IdP (`defineIdp`), Auth (`defineAuth`), and static website (`defineStaticWebSite`) using Tailor SDK
+- Prefer stable default naming: auth `default`, IdP `default`, OAuth2 client `default`
+- `userProfile.type` must reference the `user` DB type from `modules.ts`
+- `userProfile.usernameField`: stable unique field (e.g., `email`)
+- Include static website URL and localhost in CORS: `cors: ["http://localhost:5173", website.url]`
+- Frontend `VITE_TAILOR_CLIENT_ID` must come from `tailor-sdk oauth2client get default --json` — do not hardcode

package/skills/erp-kit-app-5-impl-backend/references/module-wiring.md

@@ -0,0 +1,48 @@
+# Module Wiring
+
+`src/modules.ts` composes erp-kit modules and exports their parts for resolver use.
+
+```ts
+import { db as field } from "@tailor-platform/sdk";
+import {
+  definePrimitivesModule,
+  defineUserManagementModule,
+  defineItemManagementModule,
+} from "@tailor-platform/erp-kit/module";
+
+const primitivesModules = definePrimitivesModule({});
+
+const umModules = defineUserManagementModule({
+  dbNamespace: "main-db",
+  user: {
+    fields: {
+      /* custom fields */
+    },
+    additionalStatuses: ["SUSPENDED"],
+  },
+});
+
+// Pass inter-module dependencies explicitly
+const imModules = defineItemManagementModule({
+  primitives: {
+    db: { unit: primitivesModules.db.unit },
+    queries: { getUnit: primitivesModules.queries.getUnit },
+  },
+});
+
+// Destructure db into individual table exports (required for DB scanner)
+export const { db: primitivesDb, commands: primitivesCommands } = primitivesModules;
+export const { uomCategory, unit, currency, exchangeRate } = primitivesDb;
+
+export const { db: umDb, executors: umExecutors, commands: umCommands } = umModules;
+export const { user, permission, role, userRole, rolePermission, auditEvent } = umDb;
+
+export const { db: imDb, commands: imCommands } = imModules;
+export const { item, taxonomyNode, itemTaxonomyAssignment } = imDb;
+```
+
+Key conventions:
+
+- Prefix exports to avoid collisions (`umCommands`, `imCommands`, `primitivesCommands`)
+- Every module's `db` must be destructured into individual table exports — the DB scanner only picks up named exports
+- Extract individual executors for re-export in executor files

package/skills/erp-kit-app-5-impl-backend/references/resolver-patterns.md

@@ -0,0 +1,68 @@
+# Resolver & Executor Patterns
+
+## Resolver Patterns
+
+All resolvers export a default `createResolver()` from `@tailor-platform/sdk`.
+
+### Verify command input types
+
+Before implementing a resolver, read the command's type definition:
+
+```
+node_modules/@tailor-platform/erp-kit/src/modules/<module>/command/<commandName>.ts
+```
+
+The command source is the ground truth. Do not invent fields that don't exist, and preserve the required/optional distinction.
+
+### SDK type system
+
+See [Resolver docs](https://raw.githubusercontent.com/tailor-platform/sdk/refs/heads/main/packages/sdk/docs/services/resolver.md) for the `t` namespace.
+
+`t.array()` and `t.boolean()` do **not exist**. Never attempt to use them.
+
+### Command-based mutation
+
+The most common pattern. Key points:
+
+```ts
+import { createContext } from "@tailor-platform/erp-kit/app";
+
+body: async (context) => {
+  const db = getDB("main-db");
+  const result = await imCommands.createItem(db, { ...context.input }, createContext(context));
+  if (!result.ok) throw result.error;
+  return { id: result.value.item.id, ... };
+},
+```
+
+- `context.input.optionalField ?? undefined` — Convert null to undefined for command inputs
+- `result.value.entity.nullableField ?? ""` — Handle nullable return values
+- `createContext(context)` wraps the resolver context for erp-kit commands
+- `getDB("main-db")` — Namespace must match `tailor.config.ts`
+
+### Error handling
+
+When the resolver spec documents specific error codes, use `result.error.code` to switch:
+
+```ts
+if (!result.ok) {
+  switch (result.error.code) {
+    case "USER_NOT_FOUND":
+      throw new Error(`User ${context.input.userId} not found`);
+    // ...
+  }
+}
+```
+
+Do not directly mutate module-owned tables via Kysely — always use module commands.
+
+---
+
+## Executor Patterns
+
+Executors re-export module-provided event handlers. One file per executor, no custom logic:
+
+```ts
+import { rolePermissionCreated } from "@/modules";
+export default rolePermissionCreated;
+```

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

@@ -0,0 +1,74 @@
+---
+name: erp-kit-app-6-impl-frontend
+description: Implement frontend code for app-compose applications. Use after deploying the backend with erp-kit-app-5-impl-backend. Triggers when implementing frontend pages, creating React components from screen specs, or when the user mentions implementing frontend, creating pages, or building UI for an app-compose application.
+---
+
+# App-Compose Frontend Implementation
+
+Implement frontend pages for an app-compose application, driven by screen spec documentation and a deployed backend.
+
+## When to Use
+
+- Implementing frontend pages from screen spec docs
+- Creating React components for ListView, Form, or DetailView screens
+- Building the frontend UI for an app-compose application after backend deployment
+
+## Prerequisites
+
+- Deployed backend (from `erp-kit-app-5-impl-backend`)
+- `.env` with `VITE_TAILOR_APP_URL` and `VITE_TAILOR_CLIENT_ID`
+- All four tiers of documentation:
+  - `README.md` — Application overview
+  - `docs/actors/*.md` — Actor definitions
+  - `docs/business-flow/*/README.md` + `story/*.md` — Business flows and user stories
+  - `docs/screen/*.md` — Screen specifications (ListView, Form, DetailView)
+
+## Workflow
+
+```
+ANALYZE SCREENS → GENERATE GRAPHQL SCHEMA → IMPLEMENT PAGES → VERIFY
+```
+
+### Phase 1: Analyze Screen Documentation
+
+Read all screen specs (`docs/screen/*.md`) to build a complete picture:
+
+1. **Screen types** — Identify each screen as ListView, Form (create/edit), or DetailView
+2. **Fields and columns** — Map required columns (ListView), form fields (Form), and detail fields (DetailView) from each spec
+3. **Actions** — Identify navigation actions (create, edit, back-to-list) and mutation actions (save, delete, activate/deactivate)
+
+### Phase 2: Generate GraphQL Schema
+
+Run `pnpm generate` in the frontend directory to fetch the GraphQL schema from the deployed backend.
+
+### Phase 3: Implement Frontend Pages
+
+Create pages driven by screen spec docs. Each screen type has a standard implementation pattern.
+
+**Read [pages reference](references/pages.md) for the full pattern catalog.**
+
+Page types and their file structure:
+
+| Screen Type   | 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` + `[id]/components/<entity>-actions.tsx` |
+
+Key frontend patterns:
+
+- **GraphQL fragments** — Each table/form/detail component exports its own fragment; page-level queries compose fragments
+- **gql.tada** — Type-safe GraphQL via `graphql()` from `@/graphql`
+- **React Hook Form + Zod** — Form validation with `zodResolver`
+- **urql** — `useQuery` for reads, `useMutation` for writes
+- **app-shell routing** — `Layout`, `Link`, `useParams`, `useNavigate` from `@tailor-platform/app-shell`
+
+### Phase 4: Verify
+
+```bash
+cd <app-root>/frontend
+pnpm lint
+pnpm typecheck
+pnpm build
+```

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