@tailor-platform/erp-kit 0.1.2 → 0.2.1

package/skills/4-module-tdd-implementation/references/structure.md

@@ -1,22 +0,0 @@
-# Module Directory Structure
-
-```
-src/
-├── db/           # Database models (one file per model)
-├── executor/     # Async executors (record triggers, job functions)
-├── command/      # Domain commands + 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)
-- `command/`: Domain commands + 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/skills/4-module-tdd-implementation/references/testing.md

@@ -1,37 +0,0 @@
-# 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/skills/5-module-implementation-review/references/commands.md

@@ -1,45 +0,0 @@
-# Command Implementation
-
-## Dual Function Pattern
-
-Two functions per operation: internal `_fn` and public `fn`.
-
-**Internal function (`_myFunction`):**
-
-- Takes concrete `DB` type from `generated/kysely-tailordb`
-- Return type uses `Schema` from `lib/types`: `Promise<{ entity: Entity<Schema> }>`
-- Contains actual implementation
-
-**Public function (`myFunction`):**
-
-- Generic signature: `<T extends { Entity: object }>(db: Kysely<T>, ...)`
-- Return type uses generic `T`: `Promise<{ entity: Entity<T> }>`
-- Delegates to internal with type casting: `_fn(db as unknown as DB, ...) as unknown as Result`
-
-## 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/skills/5-module-implementation-review/references/errors.md

@@ -1,7 +0,0 @@
-# Error Classes
-
-Naming convention:
-
-- `name`: Class name exactly, `as const`
-- `code`: SCREAMING_SNAKE_CASE, `as const`
-- Constructor includes context (IDs, values)

package/skills/5-module-implementation-review/references/exports.md

@@ -1,8 +0,0 @@
-# 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/skills/5-module-implementation-review/references/models.md

@@ -1,30 +0,0 @@
-# Database Models
-
-## Factory Function Pattern
-
-```typescript
-export function createEntityType(params: {
-  fields?: Record<string, unknown>;
-  additionalStatuses?: string[];
-});
-```
-
-- Include `...db.fields.timestamps()`
-- Use `.description()` for field docs
-- Apply permissions at model level
-
-## 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/skills/app-compose-1-requirement-analysis/references/structure.md

@@ -1,27 +0,0 @@
-# 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/skills/app-compose-2-requirements-breakdown/references/screen-detailview.md

@@ -1,106 +0,0 @@
-# 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/skills/app-compose-2-requirements-breakdown/references/screen-form.md

@@ -1,139 +0,0 @@
-# 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`

package/skills/app-compose-2-requirements-breakdown/references/screen-listview.md

@@ -1,153 +0,0 @@
-# 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/skills/app-compose-2-requirements-breakdown/references/structure.md

@@ -1,27 +0,0 @@
-# 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/skills/app-compose-3-doc-review/references/structure.md

@@ -1,27 +0,0 @@
-# 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
-```