@tailor-platform/erp-kit 0.1.0 → 0.1.2

package/skills/app-compose-5-design-mock-review/references/screen-detailview.md

@@ -0,0 +1,106 @@
+# 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-5-design-mock-review/references/screen-form.md

@@ -0,0 +1,139 @@
+# 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-5-design-mock-review/references/screen-listview.md

@@ -0,0 +1,153 @@
+# 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-6-implementation-spec/SKILL.md

@@ -120,3 +120,8 @@ After Tier 4, the application specification is complete:
 - **Tier 2**: Actors and business workflows
 - **Tier 3**: User stories and screens
 - **Tier 4**: Implementation specifications
+
+## References
+
+- [Application structure](references/structure.md)
+- [Backend auth](references/auth.md)

package/{rules/app-compose/backend → skills/app-compose-6-implementation-spec/references}/auth.md

@@ -1,9 +1,3 @@
----
-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.

package/skills/app-compose-6-implementation-spec/references/structure.md

@@ -0,0 +1,27 @@
+# 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/src/cli.ts

@@ -2,101 +2,20 @@
 
 import { z } from "zod";
 import { defineCommand, runMain, arg } from "politty";
-import { runCheck } from "./commands/check.js";
-import { runSyncCheck, formatSyncCheckReport } from "./commands/sync-check.js";
-import { runScaffold, ALL_TYPES, isModuleType, type ScaffoldType } from "./commands/scaffold.js";
 import { runInit } from "./commands/init.js";
 import { mockCommand } from "./commands/mock/index.js";
+import { moduleCommand } from "./commands/module/index.js";
+import { appCommand } from "./commands/app/index.js";
 
 const cwd = process.cwd();
 
-const rootArgs = z.object({
-  modulesRoot: arg(z.string().optional(), {
-    alias: "m",
-    description: "Path to modules directory",
-  }),
-  appRoot: arg(z.string().optional(), {
-    alias: "a",
-    description: "Path to app-compose directory (apps/ or examples/)",
-  }),
-});
-
-function requireRoot(args: { modulesRoot?: string; appRoot?: string }) {
-  const paths = { modulesRoot: args.modulesRoot, appRoot: args.appRoot };
-  if (!paths.modulesRoot && !paths.appRoot) {
-    console.error("At least one of --modules-root or --app-root is required.");
-    process.exit(2);
-  }
-  return paths;
-}
-
-const checkCommand = defineCommand({
-  name: "check",
-  description: "Validate docs against schemas",
-  args: rootArgs,
-  run: async (args) => {
-    const paths = requireRoot(args);
-    const exitCode = await runCheck(paths, cwd);
-    process.exit(exitCode);
-  },
-});
-
-const syncCheckCommand = defineCommand({
-  name: "sync-check",
-  description: "Validate source <-> doc correspondence",
-  args: rootArgs,
-  run: async (args) => {
-    const paths = requireRoot(args);
-    const result = await runSyncCheck(paths, cwd);
-    console.log(formatSyncCheckReport(result));
-    process.exit(result.exitCode);
-  },
-});
-
-const scaffoldCommand = defineCommand({
-  name: "scaffold",
-  description: "Generate doc file from schema template",
-  args: rootArgs.extend({
-    type: arg(z.enum(ALL_TYPES as unknown as [string, ...string[]]), {
-      positional: true,
-      description: `Scaffold type (${ALL_TYPES.join(", ")})`,
-    }),
-    parent: arg(z.string(), {
-      positional: true,
-      description: "Parent name (module or app name)",
-    }),
-    name: arg(z.string().optional(), {
-      positional: true,
-      description: "Item name (required for most types)",
-    }),
-  }),
-  run: async (args) => {
-    const paths = requireRoot(args);
-    const root = isModuleType(args.type) ? paths.modulesRoot : paths.appRoot;
-    if (!root) {
-      console.error(
-        `--${isModuleType(args.type) ? "modules-root" : "app-root"} is required for scaffold type "${args.type}".`,
-      );
-      process.exit(2);
-    }
-    const exitCode = await runScaffold(
-      args.type as ScaffoldType,
-      args.parent,
-      args.name,
-      root,
-      cwd,
-    );
-    process.exit(exitCode);
-  },
-});
-
 const initCommand = defineCommand({
   name: "init",
-  description: "Set up consumer repo (skills, rules)",
+  description: "Set up consumer repo with framework skills",
   args: z.object({
     force: arg(z.boolean().default(false), {
       alias: "f",
-      description: "Overwrite existing skills and rules",
+      description: "Overwrite existing skills",
     }),
   }),
   run: (args) => {
@@ -107,13 +26,12 @@ const initCommand = defineCommand({
 
 const main = defineCommand({
   name: "erp-kit",
-  description: "Documentation validation and scaffolding tool",
+  description: "ERP module framework CLI",
   subCommands: {
-    check: checkCommand,
-    "sync-check": syncCheckCommand,
-    scaffold: scaffoldCommand,
-    init: initCommand,
+    module: moduleCommand,
+    app: appCommand,
     mock: mockCommand,
+    init: initCommand,
   },
 });
 

package/src/commands/app/index.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { runCheck } from "../check.js";
+import { runSyncCheck, formatSyncCheckReport } from "../sync-check.js";
+import { runScaffold, APP_TYPES, type ScaffoldType } from "../scaffold.js";
+
+const cwd = process.cwd();
+
+const rootArgs = z.object({
+  root: arg(z.string(), {
+    alias: "r",
+    description: "Path to app-compose directory",
+  }),
+});
+
+const checkCommand = defineCommand({
+  name: "check",
+  description: "Validate app docs against schemas",
+  args: rootArgs,
+  run: async (args) => {
+    const exitCode = await runCheck({ appRoot: args.root }, cwd);
+    process.exit(exitCode);
+  },
+});
+
+const syncCheckCommand = defineCommand({
+  name: "sync-check",
+  description: "Validate source <-> doc correspondence",
+  args: rootArgs,
+  run: async (args) => {
+    const result = await runSyncCheck({ appRoot: args.root }, cwd);
+    console.log(formatSyncCheckReport(result));
+    process.exit(result.exitCode);
+  },
+});
+
+const scaffoldCommand = defineCommand({
+  name: "scaffold",
+  description: "Generate app doc from schema template",
+  args: rootArgs.extend({
+    type: arg(z.enum(APP_TYPES as unknown as [string, ...string[]]), {
+      positional: true,
+      description: `Scaffold type (${APP_TYPES.join(", ")})`,
+    }),
+    parent: arg(z.string(), {
+      positional: true,
+      description: "App name",
+    }),
+    name: arg(z.string().optional(), {
+      positional: true,
+      description: "Item name (required for most types)",
+    }),
+  }),
+  run: async (args) => {
+    const exitCode = await runScaffold(
+      args.type as ScaffoldType,
+      args.parent,
+      args.name,
+      args.root,
+      cwd,
+    );
+    process.exit(exitCode);
+  },
+});
+
+export const appCommand = defineCommand({
+  name: "app",
+  description: "App-compose management",
+  subCommands: {
+    check: checkCommand,
+    "sync-check": syncCheckCommand,
+    scaffold: scaffoldCommand,
+  },
+});

package/src/commands/check.test.ts

@@ -8,6 +8,7 @@ describe("buildCheckTargets", () => {
       { glob: "modules/[a-zA-Z]*/docs/features/*.md", schemaKey: "feature" },
       { glob: "modules/[a-zA-Z]*/docs/commands/*.md", schemaKey: "command" },
       { glob: "modules/[a-zA-Z]*/docs/models/*.md", schemaKey: "model" },
+      { glob: "modules/[a-zA-Z]*/docs/queries/*.md", schemaKey: "query" },
       { glob: "modules/[a-zA-Z]*/README.md", schemaKey: "module" },
     ]);
   });
@@ -20,7 +21,7 @@ describe("buildCheckTargets", () => {
 
   it("generates both when both roots are set", () => {
     const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "examples" });
-    expect(targets).toHaveLength(10);
+    expect(targets).toHaveLength(11);
   });
 
   it("returns empty when neither root is set", () => {

package/src/commands/check.ts

@@ -17,6 +17,7 @@ export function buildCheckTargets(config: {
       { glob: `${m}/[a-zA-Z]*/docs/features/*.md`, schemaKey: "feature" },
       { glob: `${m}/[a-zA-Z]*/docs/commands/*.md`, schemaKey: "command" },
       { glob: `${m}/[a-zA-Z]*/docs/models/*.md`, schemaKey: "model" },
+      { glob: `${m}/[a-zA-Z]*/docs/queries/*.md`, schemaKey: "query" },
       { glob: `${m}/[a-zA-Z]*/README.md`, schemaKey: "module" },
     );
   }