@tailor-platform/erp-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,159 @@
+---
+paths:
+  - "examples/**/src/pages/**/page.tsx"
+  - "examples/**/src/pages/**/components/*table*.tsx"
+---
+
+# ListView Screen Implementation
+
+Implementation pattern for screens with `Screen Type: ListView`.
+Assumes `page.md` and `component.md` rules.
+
+## File Structure
+
+```
+{screen-path}/
+├── components/
+│   └── {screen-name}-table.tsx     # Table component with fragments
+└── page.tsx
+```
+
+## Page Component (page.tsx)
+
+Data fetching and `Layout` must be co-located in the same page component.
+Do NOT split into an inner Content component — `Layout` requires `Layout.Column` as direct children.
+
+```tsx
+const ResourcesQuery = graphql(
+  `
+    query Resources {
+      resources {
+        ...ResourceTable
+      }
+    }
+  `,
+  [ResourceTableFragment],
+);
+
+const ResourcesPage = () => {
+  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
+    query: ResourcesQuery,
+  });
+
+  if (fetching) return <Loading />;
+
+  if (error || !data) {
+    return (
+      <ErrorFallback
+        title="Failed to load resources"
+        message="An error occurred while fetching the list."
+        onReset={() => reexecuteQuery({ requestPolicy: "network-only" })}
+      />
+    );
+  }
+
+  return (
+    <Layout
+      columns={1}
+      title="Resources"
+      actions={[
+        <Button key="create" asChild>
+          <Link to="create">Create</Link>
+        </Button>,
+      ]}
+    >
+      <Layout.Column>
+        <ResourceTable data={data.resources} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+```
+
+## Table Component (components/{screen-name}-table.tsx)
+
+### Fragment Collocation
+
+Define a row fragment and a table fragment wrapping the Connection type.
+
+```tsx
+const ResourceRowFragment = graphql(`
+  fragment ResourceRow on Resource {
+    id
+    title
+    status
+    createdAt
+  }
+`);
+
+export const ResourceTableFragment = graphql(
+  `
+    fragment ResourceTable on ResourceConnection {
+      edges {
+        node {
+          ...ResourceRow
+        }
+      }
+    }
+  `,
+  [ResourceRowFragment],
+);
+```
+
+### Row Component
+
+```tsx
+const ResourceRow = ({ resource: resourceFragment }: ResourceRowProps) => {
+  const resource = readFragment(ResourceRowFragment, resourceFragment);
+  return (
+    <TableRow>
+      <TableCell>{resource.title}</TableCell>
+      <TableCell>
+        <Badge variant={resource.status === "ACTIVE" ? "default" : "secondary"}>
+          {resource.status}
+        </Badge>
+      </TableCell>
+      <TableCell>
+        <Button variant="ghost" size="sm" asChild>
+          <Link to={resource.id}>View</Link>
+        </Button>
+      </TableCell>
+    </TableRow>
+  );
+};
+```
+
+### Empty State
+
+```tsx
+if (connection.edges.length === 0) {
+  return (
+    <EmptyState
+      title="No resources"
+      message="Get started by creating a new resource."
+      action={
+        <Button asChild>
+          <Link to="create">Create</Link>
+        </Button>
+      }
+    />
+  );
+}
+```
+
+## Column Property Mapping
+
+| Property        | Implementation                                              |
+| --------------- | ----------------------------------------------------------- |
+| Hideable: Yes   | Column visibility state to toggle show/hide                 |
+| Sortable: Yes   | Sort icon on `<TableHead>` + onClick to toggle query vars   |
+| Filterable: Yes | Filter UI above table (`<Select />`)                        |
+| Searchable: Yes | Search input above table (`<Input placeholder="Search" />`) |
+
+## Key Points
+
+- Use `<Badge />` for status columns
+- Format dates with `toLocaleDateString()`
+- Use `<EmptyState />` with Create action for empty lists
+- Add a View button per row to navigate to the detail page
+- Iterate data using Connection type `edges.node` pattern

package/rules/app-compose/structure.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "examples/**/src/"
+---
+
+# Application Directory Structure
+
+```
+{app_name}/
+├── backend/
+│   ├── src/
+│   │   ├── modules.ts              # Declaring module usage
+│   │   ├── modules/
+│   │   │   └── {module-name}/      # Module-specific directory
+│   │   │       ├── resolvers/      # API Definition to expose graphql apis
+│   │   │       └── executors/      # PubSub Automation (one file per declaration)
+│   │   └── generated/              # Auto-generated code (do not edit)
+│   └── tailor.config.ts            # tailor application config
+│
+└── frontend/
+    └── src/
+        ├── pages/                  # File-based routing (auto-discovered by Vite plugin)
+        │   └── {page-path}/
+        │       ├── page.tsx
+        │       └── {page-path}/
+        │           ├── components/
+        │           └── page.tsx
+        ├── components/
+        │   └── ui/                 # Generic UI components
+        ├── graphql/                # gql.tada settings
+        └── providers/              # react providers
+```

package/rules/module-development/commands.md

@@ -0,0 +1,54 @@
+---
+paths:
+  - "modules/*/src/command/*.ts"
+  - "!modules/*/src/command/*.test.ts"
+---
+
+# Command Implementation
+
+## defineCommand Pattern
+
+Commands that don't need custom fields use `defineCommand` directly:
+
+```typescript
+export const myCommand = defineCommand(permissions.myCommand, async (db: DB, input: Input) => { ... });
+```
+
+## Factory Function Pattern (custom fields)
+
+Commands that insert into a table with user-extensible fields use a `makeCreateX<CF>()` factory:
+
+- Export only `makeCreateX` — no default instance
+- Generic `CF extends Record<string, unknown>` for custom fields
+- Input type: `CreateXInput & CF`
+- Destructure known fields, rest-spread custom fields into `.values()` before known fields
+- Cast custom fields: `...(customFields as Record<string, unknown>)`
+- `module.ts` wires with `makeCreateX<FieldsToInsertable<F>>()`
+
+## Implementation Considerations
+
+- **Validation**: Check referenced entities exist before operating
+- **Idempotency**: For assign/revoke, return existing instead of throwing
+- **Return format**: Wrap in object `{ entity }` not just `entity`
+
+## Conventions
+
+- Input types: exported interfaces (`export interface MyFunctionInput`)
+- Use `.executeTakeFirst()` for single results
+- Include JSDoc: `/** Function: name \n Description */`
+
+## State Transitions
+
+For commands that transition between statuses, accept `from?: string[]` with a default:
+
+```typescript
+from?: string[];  // Default: ["ACTIVE"]
+
+const validFromStatuses = input.from ?? ["ACTIVE"];
+if (!validFromStatuses.includes(user.status)) {
+  throw new InvalidStatusTransitionError(user.status, targetStatus);
+}
+```
+
+- Default `from` contains the base valid source status
+- Parent modules can override to allow transitions from additional statuses

package/rules/module-development/cross-module-type-injection.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - "modules/*/src/db/*.ts"
+  - "modules/*/src/module.ts"
+---
+
+# Cross-Module Type Injection
+
+## Typing External Module References
+
+- Derive types from the source module's `defineModule` return type, never use `any`
+- Use `import type` for type-only imports
+- All modules live in the same package (`@tailor-platform/erp-kit`), so use relative paths
+- Define a local type alias for readability: `type UnitType = ReturnType<typeof definePrimitivesModule>["unit"]`
+
+## DB Type Creator Pattern (`src/db/*.ts`)
+
+- Accept optional external type via `Create*TypeParams` (e.g., `unitType?: UnitType`)
+- Use a ternary on the param to conditionally add `.relation()`:
+  - **Present**: `db.uuid().relation({ type: "n-1", toward: { type: param }, backward: "..." })`
+  - **Absent**: `db.uuid()` (plain UUID, no relation) — preserves standalone usage
+- Export a default instance at file bottom with `{}` params for internal/standalone use
+
+## Module Wiring (`src/module.ts`)
+
+- Group external dependencies under a `primitives?` key in `DefineModuleParams`
+- Spread consumer's `Create*TypeParams` and merge the injected type: `{ ...params.productTemplate, unitType: params.primitives?.unit }`
+- Export `DefineModuleParams` type from `index.ts` so consumers can type their config

package/rules/module-development/dependency-modules.md

@@ -0,0 +1,24 @@
+---
+paths:
+  - "modules/*/src/"
+---
+
+# Dependency Modules
+
+When a module depends on another module, create `modules/<module-name>/src/dep.ts` to instantiate and re-export the dependency:
+
+```typescript
+import { defineModule } from "../../primitives/src/module";
+
+const primitives = defineModule();
+
+// Re-export db types for use in this module's db definitions and commands
+export const { unit, currency } = primitives.db;
+```
+
+## Module Return Structure
+
+`defineModule` returns an object with:
+
+- `db`: Object of database model types (keyed by name)
+- `executors`: Object of executor instances (keyed by name, if any)

package/rules/module-development/errors.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "modules/*/src/lib/errors.ts"
+---
+
+# Error Classes
+
+Naming convention:
+
+- `name`: Class name exactly, `as const`
+- `code`: SCREAMING_SNAKE_CASE, `as const`
+- Constructor includes context (IDs, values)

package/rules/module-development/executors.md

@@ -0,0 +1,67 @@
+---
+paths:
+  - "modules/*/src/executor/"
+  - "modules/*/src/module.ts"
+---
+
+# Executors
+
+Executors handle asynchronous operations triggered by database record changes.
+
+## Factory Pattern
+
+Executors are **factory functions** that accept configuration and return an executor:
+
+```typescript
+export const myExecutor = function myExecutor({ namespace }: { namespace: string }) {
+  return createExecutor({
+    name: "myExecutor",
+    // ... executor config
+  });
+};
+```
+
+**Why factory functions:**
+
+- Executors need runtime configuration (db namespace) not known at import time
+- Named function expression enables better stack traces
+- Module consumers control configuration via `defineModule` params
+
+## File Organization
+
+- Place in `src/executor/` directory
+- Group related executors in one file (e.g., `recomputeOnRolePermissionChange.ts`)
+- Name files after the operation, not the trigger
+
+## Executor Structure
+
+Required fields:
+
+- `name`: Matches function name exactly
+- `description`: Human-readable purpose
+- `trigger`: `recordCreatedTrigger` or `recordDeletedTrigger` with `type`
+- `operation`: `kind: "jobFunction"` with async `body`
+
+## Database Access
+
+Use namespace parameter with `getDB`:
+
+```typescript
+// @ts-expect-error unsure at build time
+const db = getDB(namespace);
+```
+
+The `@ts-expect-error` comment is required because the namespace is validated at runtime.
+
+## Module Integration
+
+`defineModule` returns executors in a dedicated array:
+
+```typescript
+return {
+  db: [user, role, ...],
+  executors: [rolePermissionCreated, rolePermissionDeleted],
+};
+```
+
+Instantiate executors in `module.ts` with the `dbNamespace` parameter.

package/rules/module-development/exports.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "modules/*/src/index.ts"
+---
+
+# Module Exports
+
+Export order:
+
+1. `defineModule` from module.ts
+2. Generated types (enum values + types separately)
+3. Error classes (for typed catch blocks)
+4. Domain functions with input types

package/rules/module-development/models.md

@@ -0,0 +1,34 @@
+---
+paths:
+  - "modules/*/src/db/*.ts"
+---
+
+# Database Models
+
+## Factory Function Pattern
+
+Each model is a `createXType<const F>(params)` factory:
+
+- Params interface generic: `F extends Record<string, TailorAnyDBField>`
+- `fields?: F` — optional custom fields from parent modules
+- Spread as `...(params.fields ?? {}) as F` to preserve type information
+- Include `...db.fields.timestamps()`
+- Use `.description()` for field docs
+- Apply permissions at model level
+- Export a default instance: `export const x = createXType({})`
+
+## Stateful Model Enums
+
+Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
+
+```typescript
+// Good: extension only
+const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
+const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
+
+// Bad: allows replacement
+const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
+```
+
+- Name parameter `additionalX` to signal extension-only
+- Parent modules handle their additional status transitions

package/rules/module-development/structure.md

@@ -0,0 +1,27 @@
+---
+paths:
+  - "modules/*/src/"
+---
+
+# Module Directory Structure
+
+```
+src/
+├── db/           # Database models (one file per model)
+├── executor/     # Async executors (record triggers, job functions)
+├── function/     # Domain functions + tests (*.test.ts co-located)
+├── lib/          # Internal shared code (errors.ts, types.ts)
+├── testing/      # Test fixtures and helpers
+├── generated/    # Auto-generated code (do not edit)
+├── index.ts      # Public exports
+└── module.ts     # Module definition
+```
+
+## Rules
+
+- `db/`: Only documentable model definitions, no helpers
+- `executor/`: Async executors as factory functions (see executors.md)
+- `function/`: Domain functions + co-located tests, no utilities
+- `lib/`: Internal errors and types (not documented)
+- `testing/`: Fixtures for tests only
+- Run `pnpm generate` after modifying `db/` models

package/rules/module-development/sync-vs-async-operations.md

@@ -0,0 +1,83 @@
+---
+paths:
+  - "modules/*/src/"
+---
+
+# Sync vs Async Operations
+
+## Decision Criteria
+
+Choose synchronous or asynchronous execution based on:
+
+1. **Number of affected records** - How many records need processing?
+2. **Data growth trajectory** - Will the operation slow down as data grows?
+
+| Scenario                            | Approach           | Implementation              |
+| ----------------------------------- | ------------------ | --------------------------- |
+| Single record, bounded complexity   | **Synchronous**    | Inline in command           |
+| Single record, unbounded complexity | **Consider async** | Evaluate growth             |
+| Multiple records                    | **Asynchronous**   | Executor with `jobFunction` |
+
+## Growth Considerations
+
+Ask: "How does this operation scale as the system grows?"
+
+- **Bounded**: User status update (always 1 record, O(1))
+- **Bounded**: Single user permission recompute (limited by reasonable role/permission counts)
+- **Unbounded**: All users with role X (grows with user base, O(n))
+- **Unbounded**: All orders in date range (grows with transaction volume)
+
+When in doubt, monitor operation timing in production and migrate to async if latency increases.
+
+## Rationale
+
+- **Synchronous**: Acceptable when operation time is predictable and bounded
+- **Asynchronous**: Required when operation time scales with data volume
+
+## Pattern: Synchronous (Single Record)
+
+Commands that affect a single known record should execute the operation inline and return the result:
+
+```typescript
+// In command - recompute immediately
+const updatedUser = await recomputeUserPermissions(db, input.userId);
+return { userRole, user: updatedUser, auditEvent };
+```
+
+## Pattern: Asynchronous (Multiple Records)
+
+Commands that affect an unknown number of records should delegate to an executor:
+
+```typescript
+// Command just creates/deletes the record
+// Executor handles recomputation asynchronously
+```
+
+Create executors with record triggers:
+
+- `recordCreatedTrigger` - React to inserts
+- `recordDeletedTrigger` - React to deletes
+- Use `kind: "jobFunction"` for extended execution
+
+## Example: Permission Recomputation
+
+| Command                  | Affected                | Approach        |
+| ------------------------ | ----------------------- | --------------- |
+| assignRoleToUser         | 1 user                  | Sync in command |
+| revokeRoleFromUser       | 1 user                  | Sync in command |
+| assignPermissionToRole   | N users (all with role) | Async executor  |
+| revokePermissionFromRole | N users (all with role) | Async executor  |
+
+## Trade-offs
+
+**Synchronous:**
+
+- Immediate consistency
+- Simpler error handling
+- Blocks request until complete
+
+**Asynchronous:**
+
+- Eventual consistency
+- Non-blocking requests
+- Requires executor infrastructure

package/rules/module-development/testing.md

@@ -0,0 +1,43 @@
+---
+paths:
+  - "modules/*/src/command/*.test.ts"
+  - "modules/*/src/testing/*.ts"
+---
+
+# Testing Patterns
+
+## Test Coverage Goal
+
+Tests should cover all paths in the corresponding `docs/commands/*.md`:
+
+- **Process Flow**: Each branch in the mermaid flowchart = one test case
+- **Error Scenarios**: Each error code listed = one test case
+- **Idempotent paths**: If flowchart shows "Already exists? → Return existing"
+
+## Mock Database
+
+```typescript
+const { db, spies } = createMockDb<DB>();
+
+// Single return
+spies.select.mockReturnValue(entity);
+
+// Sequential returns (in query execution order)
+spies.select.mockReturnValueOnce(first).mockReturnValueOnce(second);
+```
+
+## Custom Fields Passthrough
+
+For `makeCreateX` factory commands, add one test verifying custom fields reach `.values()`:
+
+- Instantiate with concrete type: `makeCreateX<{ myField: string }>()`
+- Assert with `spies.values`: `expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ myField: "value" }))`
+- Use `toHaveBeenNthCalledWith(n, ...)` when multiple inserts occur (e.g., audit events)
+
+## Fixtures (`src/testing/fixtures.ts`)
+
+- Import `Schema` from `lib/types` (not `Namespace` from generated code)
+- Pattern: `export const baseEntity = { ... } as const satisfies Entity<Schema>`
+- Fixed IDs for traceability: `"entity-1"`
+- Consistent timestamp: `new Date("2024-01-01T00:00:00.000Z")`
+- `updatedAt: null` for base fixtures

package/rules/sdk-best-practices/db-relations.md

@@ -0,0 +1,74 @@
+---
+paths:
+  - "modules/*/src/db/*.ts"
+---
+
+# Database Relations
+
+## Relation Pattern
+
+Use `.relation()` for foreign keys instead of plain `db.uuid()`:
+
+```typescript
+userId: db.uuid().relation({
+  type: "n-1",
+  toward: { type: user },
+  backward: "userRoles",
+}).description("Foreign key to User"),
+```
+
+### Parameters
+
+- `type`: `"n-1"` (many-to-one), `"1-1"` (one-to-one), or `"keyOnly"` (FK only, no navigation)
+- `toward.type`: The related type definition (import it)
+- `backward`: Field name for reverse navigation from the related type
+
+### Benefits over plain `db.uuid()`
+
+- Foreign key constraints (referential integrity)
+- Forward navigation: `UserRole.user`
+- Backward navigation: `User.userRoles`
+- GraphQL relational queries
+
+## Junction Tables (Many-to-Many)
+
+Junction tables need relations on both foreign keys plus a composite unique index:
+
+```typescript
+import { user } from "./user";
+import { role } from "./role";
+
+db.type("UserRole", {
+  userId: db.uuid().relation({
+    type: "n-1",
+    toward: { type: user },
+    backward: "userRoles",
+  }),
+  roleId: db.uuid().relation({
+    type: "n-1",
+    toward: { type: role },
+    backward: "userRoles",
+  }),
+}).indexes({
+  fields: ["userId", "roleId"],
+  unique: true,
+  name: "user_role_unique_idx",
+});
+```
+
+### Naming Conventions
+
+- `backward` field: Use plural of the junction table name (e.g., `"userRoles"`, `"rolePermissions"`)
+- Index name: `{table}_unique_idx` pattern
+
+## Composite Indexes
+
+Use `.indexes()` (not `.uniqueIndex()`) for multi-column constraints:
+
+```typescript
+.indexes({
+  fields: ["fieldA", "fieldB"],
+  unique: true,
+  name: "descriptive_idx_name",
+})
+```

package/rules/sdk-best-practices/sdk-docs.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "modules/*/src/db/*.ts"
+  - "modules/*/src/executor/*.ts"
+  - "modules/*/src/workflow/*.ts"
+---
+
+# SDK Docs Reference
+
+Read the official Tailor SDK documentation for database models, executors:
+
+- [TailorDB Models](https://raw.githubusercontent.com/tailor-platform/sdk/refs/heads/main/packages/sdk/docs/services/tailordb.md)
+- [Executors](https://raw.githubusercontent.com/tailor-platform/sdk/refs/heads/main/packages/sdk/docs/services/executors.md)
+- [Workflow](https://raw.githubusercontent.com/tailor-platform/sdk/refs/heads/main/packages/sdk/docs/services/workflow.md)