@tailor-platform/erp-kit 0.1.0 → 0.1.1

package/src/commands/init.ts

@@ -4,7 +4,6 @@ import chalk from "chalk";
 import { PACKAGE_ROOT } from "../util.js";
 
 const SKILLS_SRC = path.join(PACKAGE_ROOT, "skills");
-const RULES_SRC = path.join(PACKAGE_ROOT, "rules");
 
 const FRAMEWORK_SKILLS = [
   "1-module-docs",
@@ -21,65 +20,99 @@ const FRAMEWORK_SKILLS = [
   "mock-scenario",
 ];
 
+function copyDirectoryRecursive(
+  srcDir: string,
+  destDir: string,
+  force: boolean,
+): { copied: number; skipped: number } {
+  let copied = 0;
+  let skipped = 0;
+
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      const sub = copyDirectoryRecursive(srcPath, destPath, force);
+      copied += sub.copied;
+      skipped += sub.skipped;
+    } else {
+      if (!force && fs.existsSync(destPath)) {
+        skipped++;
+        continue;
+      }
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+      copied++;
+    }
+  }
+
+  return { copied, skipped };
+}
+
 export function runInit(cwd: string, force: boolean): number {
   console.log(chalk.bold("erp-kit init\n"));
 
+  // --- Skills ---
   const skillsDest = path.join(cwd, ".agents", "skills");
   let copiedCount = 0;
   let skippedCount = 0;
   for (const skill of FRAMEWORK_SKILLS) {
-    const srcSkill = path.join(SKILLS_SRC, skill, "SKILL.md");
+    const srcSkillDir = path.join(SKILLS_SRC, skill);
+    if (!fs.existsSync(srcSkillDir)) continue;
+
     const destDir = path.join(skillsDest, skill);
-    const destSkill = path.join(destDir, "SKILL.md");
+    const result = copyDirectoryRecursive(srcSkillDir, destDir, force);
+    copiedCount += result.copied;
 
-    if (!fs.existsSync(srcSkill)) continue;
-    if (!force && fs.existsSync(destSkill)) {
-      console.log(chalk.yellow(`  Skipped ${skill}/SKILL.md (already exists)`));
-      skippedCount++;
-      continue;
+    if (result.skipped > 0) {
+      console.log(chalk.yellow(`  Skipped ${skill}/ (${result.skipped} existing files)`));
+      skippedCount += result.skipped;
     }
-
-    fs.mkdirSync(destDir, { recursive: true });
-    fs.copyFileSync(srcSkill, destSkill);
-    copiedCount++;
   }
-  console.log(chalk.green(`  Copied ${copiedCount} framework skills to .agents/skills/`));
+  console.log(chalk.green(`  Copied ${copiedCount} skill files to .agents/skills/`));
   if (skippedCount > 0) {
     console.log(
-      chalk.yellow(`  Skipped ${skippedCount} existing skills (use --force to overwrite)`),
+      chalk.yellow(`  Skipped ${skippedCount} existing files (use --force to overwrite)`),
     );
   }
 
-  const rulesDest = path.join(cwd, ".agents", "rules");
-  let rulesCount = 0;
-  let rulesSkipped = 0;
-  if (fs.existsSync(RULES_SRC)) {
-    const copyRulesRecursive = (srcDir: string, destDir: string) => {
-      for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-        const srcPath = path.join(srcDir, entry.name);
-        const destPath = path.join(destDir, entry.name);
-        if (entry.isDirectory()) {
-          copyRulesRecursive(srcPath, destPath);
-        } else {
-          if (!force && fs.existsSync(destPath)) {
-            const rel = path.relative(rulesDest, destPath);
-            console.log(chalk.yellow(`  Skipped rule ${rel} (already exists)`));
-            rulesSkipped++;
-            continue;
-          }
-          fs.mkdirSync(destDir, { recursive: true });
-          fs.copyFileSync(srcPath, destPath);
-          rulesCount++;
-        }
+  // --- Claude Code symlink ---
+  const claudeSkills = path.join(cwd, ".claude", "skills");
+  const relTarget = path.relative(path.dirname(claudeSkills), skillsDest);
+
+  // lstatSync doesn't follow symlinks, so dangling symlinks are detected
+  const claudeSkillsExists = (() => {
+    try {
+      fs.lstatSync(claudeSkills);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+
+  if (claudeSkillsExists) {
+    const stat = fs.lstatSync(claudeSkills);
+    if (stat.isSymbolicLink()) {
+      const current = fs.readlinkSync(claudeSkills);
+      if (current === relTarget) {
+        console.log(chalk.green("  .claude/skills -> .agents/skills/ (already linked)"));
+      } else if (force) {
+        fs.unlinkSync(claudeSkills);
+        fs.symlinkSync(relTarget, claudeSkills);
+        console.log(chalk.green("  .claude/skills -> .agents/skills/ (relinked)"));
+      } else {
+        console.log(
+          chalk.yellow(`  Skipped .claude/skills (symlink exists -> ${current}, use --force)`),
+        );
       }
-    };
-    copyRulesRecursive(RULES_SRC, rulesDest);
-  }
-  console.log(chalk.green(`  Copied ${rulesCount} framework rules to .agents/rules/`));
-  if (rulesSkipped > 0) {
-    console.log(
-      chalk.yellow(`  Skipped ${rulesSkipped} existing rules (use --force to overwrite)`),
-    );
+    } else {
+      console.log(chalk.yellow("  Skipped .claude/skills (directory exists, not a symlink)"));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(claudeSkills), { recursive: true });
+    fs.symlinkSync(relTarget, claudeSkills);
+    console.log(chalk.green("  .claude/skills -> .agents/skills/ (linked)"));
   }
 
   console.log(chalk.bold.green("\nDone! Run `erp-kit check` to validate your docs."));

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

@@ -1,55 +0,0 @@
----
-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/page.md

@@ -1,86 +0,0 @@
----
-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/module-development/cross-module-type-injection.md

@@ -1,28 +0,0 @@
----
-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

@@ -1,24 +0,0 @@
----
-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/executors.md

@@ -1,67 +0,0 @@
----
-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/sync-vs-async-operations.md

@@ -1,83 +0,0 @@
----
-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/sdk-best-practices/sdk-docs.md

@@ -1,14 +0,0 @@
----
-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)