@tailor-platform/erp-kit 0.0.1 → 0.1.1

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

@@ -0,0 +1,127 @@
+---
+name: app-compose-6-implementation-spec
+description: Create Tier 4 documentation (resolvers) for GraphQL operations. Use after completing design review with app-compose-5-design-mock-review.
+---
+
+# Implementation Spec Workflow
+
+Create Tier 4 documentation: GraphQL Resolvers (mutations and queries).
+
+## Prerequisites
+
+Tier 1-3 documentation and design mockups must exist:
+
+- `README.md` (requirements)
+- `docs/actors/*.md` (actors)
+- `docs/business-flow/*/README.md` (flows)
+- `docs/business-flow/*/story/*.md` (stories)
+- `docs/screen/*.md` (screens)
+- `docs/design.pen` (UI mockups)
+
+## Workflow Phases
+
+```
+ANALYZE → IDENTIFY → CHECK MODULES → CREATE → VALIDATE
+```
+
+### Phase 1: Analyze
+
+Read all story files and identify:
+
+1. **Operations** that modify data → mutations
+2. **Operations** that retrieve data → queries
+3. **Error scenarios** for each operation
+
+### Phase 2: Identify
+
+Map stories to resolvers:
+
+| Story Element        | Resolver Type |
+| -------------------- | ------------- |
+| Create/Update/Delete | Mutation      |
+| View/List/Search     | Query         |
+| Real-time updates    | Subscription  |
+
+**Naming:** Use action-verb names: `create-`, `update-`, `delete-`, `submit-`, `approve-`
+
+### Phase 3: Check Module Dependencies
+
+Resolvers reference module commands. Before creating resolver docs, verify required modules exist.
+
+**Check existing modules:**
+
+```bash
+ls modules/
+```
+
+**Check module commands:**
+
+```bash
+ls modules/<module-name>/docs/commands/
+```
+
+**Map resolvers to modules:**
+
+| Resolver Operation | Typical Module        |
+| ------------------ | --------------------- |
+| User invite/roles  | `user-management`     |
+| Supplier CRUD      | `supplier-management` |
+| Document handling  | `document-management` |
+| Task workflows     | `task-management`     |
+
+**If modules don't exist:**
+
+1. **Identify needed modules** - Group resolver operations by domain
+2. **Create module docs first** - Use `1-module-docs` skill
+3. **Return to Tier 4** - After modules have documented commands
+
+```
+Tier 4 blocked → Create modules → Return to Tier 4
+```
+
+**Only reference existing module commands** in resolver documentation. Never reference modules or commands that don't exist.
+
+### Phase 4: Create
+
+Generate documentation using `erp-kit` CLI:
+
+```bash
+erp-kit scaffold --app-root examples resolver <app> <resolver-name>
+```
+
+**Naming conventions:**
+
+- Filename must match H1 heading exactly (kebab-case)
+- Action-focused names: `create-supplier-invitation.md`
+
+### Phase 5: Validate
+
+```bash
+pnpm run app:doc:check
+```
+
+## Schema Reference
+
+| Schema         | Tier | Output Path               |
+| -------------- | ---- | ------------------------- |
+| `resolver.yml` | 4    | `docs/resolver/<name>.md` |
+
+## Tips
+
+- One story may require 1-3 resolvers
+- Group related operations logically
+- Document all error scenarios
+
+## Completion
+
+After Tier 4, the application specification is complete:
+
+- **Tier 1**: Application overview
+- **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/skills/app-compose-6-implementation-spec/references/auth.md

@@ -0,0 +1,72 @@
+# 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/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/skills/mock-scenario/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: mock-scenario
+description: Scaffold a new Mockoon mock scenario with CRUD routes, error scenarios, and registry updates
+---
+
+# Mock Scenario Scaffolder
+
+Generate a complete Mockoon mock API config for a new provider scenario and wire it into the registry.
+
+## Workflow
+
+### Step 1: Identify target API
+
+Ask the user for:
+
+- **Provider name** (e.g. `stripe`, `github`, `twilio`)
+- **Scenario name** (e.g. `admin-api`, `payments-api`, `product-sync`)
+- **Key resources to mock** (e.g. customers, invoices, messages)
+- **Scenario to test** (e.g. initial full sync, incremental sync, webhook-triggered update, error recovery)
+
+### Step 2: Research real API
+
+Use web search to find:
+
+- Base URL and API version
+- Authentication scheme (API key, OAuth, bearer token)
+- Endpoint patterns and HTTP methods
+- Response shapes for the key resources
+- Error response format (status codes, error body structure)
+- Rate limit headers
+
+### Step 3: Generate Mockoon JSON
+
+Create `mocks/{provider}/{scenario}/mock.json` following the Shopify admin-api mock as the canonical reference (`mocks/shopify/admin-api/mock.json`).
+
+The config must include:
+
+- **uuid**: a valid UUID v4
+- **name**: Human-readable API name
+- **endpointPrefix**: Match the real API's base path
+- **port**: `3000` (overridden at runtime by the reverse proxy launcher)
+- **hostname**: `0.0.0.0`
+- **latency**: `0`
+- **folders**: `[]`
+- **rootChildren**: `[]`
+- **proxyMode**: `false`
+- **proxyHost**: `""`
+- **proxyRemovePrefix**: `false`
+- **tlsOptions**: `{ "enabled": false, "type": "CERT", "pfxPath": "", "certPath": "", "keyPath": "", "caPath": "", "passphrase": "" }`
+- **cors**: `true`
+- **headers**: `[{ "key": "Content-Type", "value": "application/json" }]`
+- **proxyReqHeaders**: `[]`
+- **proxyResHeaders**: `[]`
+- **callbacks**: `[]`
+
+All UUIDs (environment, routes, responses, data buckets) must be valid UUID v4 values.
+
+**Data buckets** — for each stateful/CRUD resource:
+
+- 2–3 seed records with realistic field values
+- Use the `id` field matching Mockoon's `"id"` property for CRUD lookup
+
+**Routes:**
+
+1. **CRUD routes** — for mutable resources:
+
+   ```json
+   {
+     "type": "crud",
+     "endpoint": "{resource}",
+     "responses": [
+       {
+         "label": "CRUD {Resource}",
+         "statusCode": 200,
+         "headers": [{ "key": "Content-Type", "value": "application/json" }],
+         "bodyType": "DATABUCKET",
+         "databucketID": "{resource-bucket-id}"
+       }
+     ]
+   }
+   ```
+
+2. **Static routes** — for read-only endpoints:
+   - List endpoints returning JSON arrays
+   - Single-item endpoints using `{{urlParam 'id'}}` interpolation
+
+3. **Error scenarios** — triggered via `X-Test-Scenario` header:
+   - `unauthorized` → 401
+   - `not-found` → 404
+   - `rate-limit` → 429 with `Retry-After` header
+   - `server-error` → 500
+
+4. **Catch-all** — `*` endpoint returning 500 when `X-Test-Scenario: server-error`
+
+**Every route must have:** `type`, `documentation`, `responseMode: null`, `streamingMode: null`, `streamingInterval: 0`
+
+**Every response must have:** `latency: 0`, `bodyType`, `databucketID`, `filePath: ""`, `sendFileAsBody: false`, `rules`, `rulesOperator: "OR"`, `disableTemplating: false`, `fallbackTo404: false`, `default`, `crudKey: "id"`, `callbacks: []`, a `Content-Type` header, and a non-empty `label`
+
+**Every rule must have:** `target`, `modifier`, `value`, `operator`, `invert: false`
+
+### Step 4: Generate scenario README
+
+Create `mocks/{provider}/{scenario}/README.md` with:
+
+- Title and one-line description
+- Quick start with both methods: `erp-kit mock start` (proxy) and direct `npx @mockoon/cli start`
+- Endpoints table (method, path, scenarios)
+- CRUD workflow example with curl commands using proxy URL (`http://localhost:3000/{provider}/{scenario}/...`)
+- Error scenario examples
+- Test data description
+
+### Step 5: Validate
+
+```bash
+erp-kit mock validate
+```
+
+Fix any failures before finishing.

package/src/app.ts

@@ -0,0 +1 @@
+export { createContext } from "./modules/shared/createContext";

package/src/cli.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+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";
+
+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 with framework skills",
+  args: z.object({
+    force: arg(z.boolean().default(false), {
+      alias: "f",
+      description: "Overwrite existing skills",
+    }),
+  }),
+  run: (args) => {
+    const exitCode = runInit(cwd, args.force);
+    process.exit(exitCode);
+  },
+});
+
+const main = defineCommand({
+  name: "erp-kit",
+  description: "Documentation validation and scaffolding tool",
+  subCommands: {
+    check: checkCommand,
+    "sync-check": syncCheckCommand,
+    scaffold: scaffoldCommand,
+    init: initCommand,
+    mock: mockCommand,
+  },
+});
+
+void runMain(main);

package/src/commands/check.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { buildCheckTargets } from "./check.js";
+
+describe("buildCheckTargets", () => {
+  it("generates module targets when modulesRoot is set", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: undefined });
+    expect(targets).toEqual([
+      { 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]*/README.md", schemaKey: "module" },
+    ]);
+  });
+
+  it("generates app-compose targets when appRoot is set", () => {
+    const targets = buildCheckTargets({ modulesRoot: undefined, appRoot: "apps" });
+    expect(targets[0].glob).toBe("apps/[a-zA-Z]*/README.md");
+    expect(targets).toHaveLength(6);
+  });
+
+  it("generates both when both roots are set", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "examples" });
+    expect(targets).toHaveLength(10);
+  });
+
+  it("returns empty when neither root is set", () => {
+    const targets = buildCheckTargets({ modulesRoot: undefined, appRoot: undefined });
+    expect(targets).toHaveLength(0);
+  });
+});