@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/package.json

@@ -1,10 +1,67 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tailor-platform/erp-kit",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+  "version": "0.1.0",
+  "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
+  "bin": {
+    "erp-kit": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "rules",
+    "schemas",
+    "skills",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    "./module": "./src/module.ts",
+    "./app": "./src/app.ts",
+    "./testing": "./src/testing.ts"
+  },
+  "dependencies": {
+    "@jackchuka/mdschema": "^0.12.3",
+    "@mockoon/commons": "^9.0.0",
+    "@mockoon/commons-server": "^9.0.0",
+    "chalk": "^5.4.1",
+    "fast-glob": "^3.3.3",
+    "politty": "^0.4.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@tailor-platform/function-kysely-tailordb": "0.1.3",
+    "@tailor-platform/function-types": "0.8.1",
+    "@tailor-platform/sdk": "1.17.1",
+    "@types/node": "^25.1.0",
+    "eslint": "9.39.2",
+    "kysely": "0.28.10",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.0",
+    "@tailor-platform/eslint-config": "0.0.1"
+  },
+  "peerDependencies": {
+    "@tailor-platform/function-kysely-tailordb": "0.1.3",
+    "@tailor-platform/function-types": "0.8.1",
+    "@tailor-platform/sdk": "1.17.1",
+    "kysely": "0.28.10"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsup",
+    "generate": "pnpm generate:primitives && pnpm generate:user-management",
+    "generate:primitives": "cd src/modules/primitives && tailor-sdk generate",
+    "generate:user-management": "cd src/modules/user-management && tailor-sdk generate",
+    "lint": "eslint --cache .",
+    "lint:fix": "eslint --cache --fix .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:primitives": "vitest run src/modules/primitives/",
+    "test:user-management": "vitest run src/modules/user-management/",
+    "test:shared": "vitest run src/modules/shared/",
+    "mock:start": "node dist/cli.js mock start",
+    "mock:validate": "node dist/cli.js mock validate"
+  }
+}

package/rules/app-compose/backend/auth.md

@@ -0,0 +1,78 @@
+---
+paths:
+  - "examples/**/backend/tailor.config.ts"
+  - "examples/**/backend/.env"
+---
+
+# Backend Auth Configuration
+
+Use Tailor SDK auth resources as the default pattern for backend authentication setup.
+
+## Standard Auth Shape
+
+In `tailor.config.ts`:
+
+- Define IdP with `defineIdp(...)`
+- Define Auth with `defineAuth(...)`
+- Define static website with `defineStaticWebSite(...)` when frontend is deployed as static hosting
+- Wire `idProvider` via `idp.provider(...)`
+- Set exactly one OAuth2 client for frontend login (default client name: `default`)
+- Export config with `auth: auth` and `idp: [idp]`
+- Include static website URL in CORS when using deployed frontend (for example, `cors: ["http://localhost:5173", website.url]`)
+
+Prefer this stable naming unless there is a clear reason to change:
+
+- Auth name: `default`
+- IdP name: `default`
+- OAuth2 client name: `default`
+
+## User Mapping
+
+Use `userProfile` to map authenticated identities to the application user type.
+
+- `type`: module-provided user type
+- `usernameField`: stable unique field (for example, `email`)
+- `attributes`: explicitly list required attributes
+
+Avoid implicit attribute assumptions.
+
+## CORS for Static Website Login
+
+When frontend is deployed via `staticWebsites`, OAuth metadata and query calls are cross-origin from `https://<name>-<workspace>.web.erp.dev` to app backend.
+
+- Always include the deployed static website origin via `website.url` in backend `cors`
+- Keep local development origin in `cors` as well (for example, `http://localhost:5173`)
+- If your template uses IP allow lists, set `allowedIpAddresses` appropriately for Tailor internal access
+
+If `website.url` is missing from `cors`, login may fail with browser CORS errors before authentication starts.
+
+## Seed Permission Alignment
+
+Seeded login users in `seed/data/User.jsonl` must receive module permissions required by guarded commands/resolvers.
+
+- Do not assume `ADMIN` is automatically privileged unless your permission evaluator explicitly supports it
+- Grant concrete permission keys defined by the module (for example, `user-management:createUser`)
+- Keep `User.jsonl` permissions aligned with the module currently wired in `src/modules.ts`
+
+## Workspace and CLI Inputs
+
+Use `TAILOR_PLATFORM_WORKSPACE_ID` in backend `.env` for CLI operations.
+
+Required for non-interactive resource lookup and automation:
+
+- `tailor-sdk oauth2client list`
+- `tailor-sdk oauth2client get <name>`
+
+Use `--env-file <backend/.env>` for deterministic command execution in local/dev scripts.
+
+## OAuth Client ID Source of Truth
+
+Frontend `VITE_TAILOR_CLIENT_ID` must come from backend-managed OAuth2 client data.
+
+Canonical retrieval flow:
+
+1. `tailor-sdk oauth2client get default --json`
+2. Copy `clientId` from command output
+3. Set it in frontend env
+
+Do not hardcode OAuth client IDs in source code.

package/rules/app-compose/frontend/auth.md

@@ -0,0 +1,55 @@
+---
+paths:
+  - "examples/**/frontend/src/App.tsx"
+  - "examples/**/frontend/src/lib/auth-client.ts"
+  - "examples/**/frontend/src/providers/graphql-provider.tsx"
+---
+
+# Frontend Auth (AppShell AuthProvider)
+
+Use `@tailor-platform/app-shell` authentication as the default pattern for frontend apps.
+
+## Required Environment Variables
+
+- `VITE_TAILOR_APP_URL`
+- `VITE_TAILOR_CLIENT_ID`
+
+Fail fast at startup if either value is missing.
+
+## Auth Client Initialization
+
+Create a single shared auth client in `src/lib/auth-client.ts`:
+
+- Use `createAuthClient({ appUri, clientId })`
+- Export it as `authClient`
+- Do not create auth clients inside render functions
+
+## App Root Composition
+
+Wrap the app with `AuthProvider` in `src/App.tsx`:
+
+- `AuthProvider` must receive the shared `authClient`
+- Use `guardComponent` for unauthenticated/loading states
+- `guardComponent` should use `useAuth()` and handle:
+  - `!isReady`: loading UI
+  - `!isAuthenticated`: login UI with `login()`
+  - `error`: visible message
+
+Recommended order:
+
+1. `AuthProvider`
+2. `GraphQLProvider`
+3. `AppShell`
+
+## GraphQL Authentication
+
+`src/providers/graphql-provider.tsx` must attach OAuth headers for every request:
+
+- Accept `authClient` as a prop
+- Call `authClient.getAuthHeadersForQuery()`
+- Set both headers:
+  - `Authorization`
+  - `DPoP`
+- Keep `Content-Type: application/json`
+
+Do not use unauthenticated static headers for `/query`.

package/rules/app-compose/frontend/component.md

@@ -0,0 +1,55 @@
+---
+paths:
+  - "examples/**/src/pages/**/components/*.tsx"
+---
+
+# Page Components
+
+Page-specific components are placed in a `components/` directory, separated from page.tsx.
+
+```
+{page-name}/
+├── components/
+│   └── *.tsx
+└── page.tsx
+```
+
+## Fragment Collocation
+
+Components define and export their own GraphQL Fragment for the data they display. The parent page imports the Fragment and includes it in the query.
+
+Use `graphql`, `FragmentOf`, and `readFragment` from `@/graphql`.
+
+```tsx
+// components/user-card.tsx
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+
+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>;
+};
+```
+
+```tsx
+// page.tsx
+import { UserCard, UserCardFragment } from "./components/user-card";
+
+const UserQuery = graphql(
+  `
+    query User($id: ID!) {
+      user(id: $id) {
+        ...UserCard
+      }
+    }
+  `,
+  [UserCardFragment],
+);
+```

package/rules/app-compose/frontend/page.md

@@ -0,0 +1,86 @@
+---
+paths:
+  - "examples/**/src/pages/**/page.tsx"
+---
+
+# Page File Structure (File-Based Routing)
+
+Each `page.tsx` file should contain a default-exported page component with optional `appShellPageProps` static field.
+Pages are automatically discovered by the Vite plugin.
+
+## Path Convention
+
+The URL path is derived from the directory structure:
+
+```
+src/pages/
+├── page.tsx                  # / (root path)
+├── purchasing/
+│   ├── page.tsx              # /purchasing
+│   └── orders/
+│       ├── page.tsx          # /purchasing/orders
+│       └── [id]/
+│           └── page.tsx      # /purchasing/orders/:id
+└── (admin)/                  # Grouping (not included in path)
+    └── settings/
+        └── page.tsx          # /settings
+```
+
+| Directory Name | Converts To | Description                   |
+| -------------- | ----------- | ----------------------------- |
+| `orders`       | `orders`    | Static segment                |
+| `[id]`         | `:id`       | Dynamic parameter             |
+| `(group)`      | (excluded)  | Grouping only (not in path)   |
+| `_lib`         | (ignored)   | Not routed (for shared logic) |
+
+## Page Component Pattern
+
+```tsx
+import { Layout, type AppShellPageProps } from "@tailor-platform/app-shell";
+import { useQuery } from "urql";
+import { graphql } from "@/graphql";
+import { ErrorFallback } from "@/components/composed/error-fallback";
+import { Loading } from "@/components/composed/loading";
+
+const MyQuery = graphql(`...`);
+
+const MyPage = () => {
+  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
+    query: MyQuery,
+  });
+
+  if (fetching) return <Loading />;
+
+  if (error || !data) {
+    return (
+      <ErrorFallback
+        title="Failed to load"
+        message="An error occurred while fetching data."
+        onReset={() => reexecuteQuery({ requestPolicy: "network-only" })}
+      />
+    );
+  }
+
+  return (
+    <Layout columns={1} title="My Page">
+      <Layout.Column>
+        <MyComponent data={data} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+
+MyPage.appShellPageProps = {
+  meta: { title: "My Page" },
+} satisfies AppShellPageProps;
+
+export default MyPage;
+```
+
+## Key Points
+
+- Handle `fetching` state with `<Loading />`
+- Handle `error || !data` with `<ErrorFallback />` and `reexecuteQuery` for retry
+- Use `appShellPageProps` static field for metadata (title, icon) and guards
+- Guards on parent pages are automatically inherited by child pages
+- See `component.md` for fragment collocation

package/rules/app-compose/frontend/screen-detailview.md

@@ -0,0 +1,112 @@
+---
+paths:
+  - "examples/**/src/pages/**/[id]/page.tsx"
+  - "examples/**/src/pages/**/[id]/components/*.tsx"
+---
+
+# DetailView Screen Implementation
+
+Implementation pattern for screens with `Screen Type: DetailView`.
+Assumes `page.md` and `component.md` rules.
+
+## File Structure
+
+```
+{screen-path}/[id]/
+├── components/
+│   ├── {screen-name}-detail.tsx     # Main content (left column)
+│   └── {screen-name}-actions.tsx    # Action sidebar (right column)
+├── edit/
+│   ├── components/
+│   │   └── edit-{screen-name}-form.tsx
+│   └── page.tsx
+└── page.tsx
+```
+
+## Layout
+
+- Two-column layout: main content on the left, actions on the right.
+
+```tsx
+const ResourcePage = () => {
+  const { id } = useParams();
+  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
+    query: ResourceQuery,
+    variables: { id: id! },
+  });
+
+  if (fetching) return <Loading />;
+  if (error || !data?.resource) return <ErrorFallback ... />;
+
+  return (
+    <Layout columns={2} title="Resource Detail">
+      <Layout.Column>
+        <ResourceDetail resource={data.resource} />
+      </Layout.Column>
+      <Layout.Column>
+        <ResourceActions resource={data.resource} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+```
+
+## Left Column: Detail Component
+
+Stack `DescriptionCard` and related tables vertically with `space-y-6`.
+
+- `DescriptionCard` (`@tailor-platform/app-shell`): renders key-value fields declaratively.
+- Complex content (tables, timelines): wrap in `<div className="rounded-lg border bg-card p-6">`.
+
+### DescriptionCard
+
+```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", PENDING: "warning" } },
+    },
+    { type: "divider" },
+    {
+      key: "createdAt",
+      label: "Created At",
+      type: "date",
+      meta: { dateFormat: "medium" },
+    },
+  ]}
+/>
+```
+
+Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
+
+## Right Column: Actions Component
+
+Wrap in a `Card` component. Use `Button variant="ghost"` for each action item.
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Actions</CardTitle>
+  </CardHeader>
+  <CardContent className="space-y-2">
+    <Button variant="ghost" className="w-full justify-start gap-2" asChild>
+      <Link to="edit">✎ Edit</Link>
+    </Button>
+    <Button variant="ghost" className="w-full justify-start gap-2" onClick={handler}>
+      ✓ Approve
+    </Button>
+  </CardContent>
+</Card>
+```
+
+- Navigation: `<Button variant="ghost" asChild><Link to="...">`
+- Mutation: `<Button variant="ghost" onClick={handler}>` with custom resolvers (see `backend/resolvers.md`)
+- Conditional: show/hide based on status
+- Multiple cards: stack with `<div className="space-y-6">`

package/rules/app-compose/frontend/screen-form.md

@@ -0,0 +1,145 @@
+---
+paths:
+  - "examples/**/src/pages/**/page.tsx"
+  - "examples/**/src/pages/**/components/*form*.tsx"
+---
+
+# Form Screen Implementation
+
+Implementation pattern for screens with `Screen Type: Form`.
+Assumes `page.md` and `component.md` rules.
+
+## File Structure
+
+```
+{screen-path}/
+├── components/
+│   └── {screen-name}-form.tsx    # Form component with validation
+└── page.tsx
+```
+
+## Page Component (page.tsx)
+
+Form pages delegate mutation logic to the form component.
+
+```tsx
+const ScreenNamePage = () => (
+  <Layout columns={1} title="Screen Title">
+    <Layout.Column>
+      <ScreenNameForm />
+    </Layout.Column>
+  </Layout>
+);
+```
+
+For edit forms that need existing data, co-locate data fetching in the page component:
+
+```tsx
+const EditPage = () => {
+  const { id } = useParams();
+  const [{ data, error, fetching }] = useQuery({
+    query: ResourceQuery,
+    variables: { id: id! },
+  });
+
+  if (fetching) return <Loading />;
+  if (error || !data?.resource) return <ErrorFallback ... />;
+
+  return (
+    <Layout columns={1} title="Edit Resource">
+      <Layout.Column>
+        <EditResourceForm resource={data.resource} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+```
+
+## Form Component (components/{screen-name}-form.tsx)
+
+### Technology Stack
+
+- `react-hook-form` — form state management
+- `zod` + `@hookform/resolvers/zod` — validation
+- `useMutation` (urql) — GraphQL mutation
+- `useNavigate` (@tailor-platform/app-shell) — post-submit navigation
+
+### Pattern
+
+```tsx
+const formSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+});
+
+type FormValues = z.infer<typeof formSchema>;
+
+export const ScreenNameForm = () => {
+  const navigate = useNavigate();
+  const [, createResource] = useMutation(CreateMutation);
+
+  const form = useForm<FormValues>({
+    resolver: zodResolver(formSchema),
+    defaultValues: { title: "", description: "" },
+  });
+
+  const onSubmit = (values: FormValues) => {
+    void createResource({ input: values }).then((result) => {
+      if (!result.error) {
+        void navigate("..");
+      }
+    });
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={(e) => void form.handleSubmit(onSubmit)(e)} className="max-w-md space-y-4">
+        <FormField
+          control={form.control}
+          name="title"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Title</FormLabel>
+              <FormControl>
+                <Input placeholder="Enter title" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <div className="flex gap-2">
+          <Button type="submit">Create</Button>
+          <Button type="button" variant="outline" onClick={() => void navigate("..")}>
+            Cancel
+          </Button>
+        </div>
+      </form>
+    </Form>
+  );
+};
+```
+
+## Field Type Mapping
+
+| Field Type | Component                      | Zod Schema                      |
+| ---------- | ------------------------------ | ------------------------------- |
+| Text       | `<Input />`                    | `z.string()`                    |
+| Textarea   | `<textarea className="..." />` | `z.string()`                    |
+| Dropdown   | `<Select />`                   | `z.string()` or `z.enum([...])` |
+| Date       | `<Input type="date" />`        | `z.string()` (ISO format)       |
+| Number     | `<Input type="number" />`      | `z.coerce.number()`             |
+| Email      | `<Input type="email" />`       | `z.string().email()`            |
+| Checkbox   | `<Checkbox />`                 | `z.boolean()`                   |
+| Radio      | `<RadioGroup />`               | `z.enum([...])`                 |
+
+## Validation Mapping
+
+- **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
+- **Required: No** → `.optional()`
+
+## Key Points
+
+- Set `defaultValues` for all fields (empty string, false, etc.)
+- Navigate to `".."` after successful mutation
+- Cancel button must use `type="button"` to prevent form submit
+- For edit forms, accept fragment data as props and pre-fill `defaultValues`