routesync 1.0.35 → 1.0.39

package/README.md

@@ -14,6 +14,7 @@ RouteSync does all of that. You point it at `routes/api.php` and it generates th
 
 ```bash
 # Step 1 — in your Laravel folder
+npx routesync annotate --input routes/api.php  # auto-inject #[Response] to controllers
 npx routesync scan --input routes/api.php --models
 
 # Step 2 — in your frontend folder
@@ -21,6 +22,8 @@ npx routesync generate --manifest routesync.manifest.json --output src/api --nex
 ```
 
 ```
+✔ Annotated 12 method(s) across 6 controller file(s)
+
 ✔ Found 35 routes, 19 models → routesync.manifest.json
 
 ✔ SDK generated → src/api
@@ -65,7 +68,35 @@ npm install routesync zod
 
 ## Full Workflow (Laravel + Next.js)
 
-### 1. Scan routes & models
+### 1. Auto-annotate controllers (one-time setup)
+
+Run this from your **Laravel project root** to auto-inject `#[Response]` attributes into every controller method:
+
+```bash
+npx routesync annotate --input routes/api.php
+```
+
+| Option | Description |
+|---|---|
+| `--input <file>` | Path to routes file (default: `routes/api.php`) |
+| `--dry-run` | Preview what would be injected without writing files |
+| `--force` | Re-annotate methods that already have `#[Response]` |
+
+This command:
+- Detects `return new XxxResource(...)` / `XxxResource::collection(...)` / `response()->json(new XxxResource(...))` in each controller method
+- Resolves the model from the Resource's `@mixin` docblock (or strips the `Resource` suffix as fallback)
+- Injects `#[Response(Model::class)]` or `#[Response(Model::class, collection: true)]` above the method
+- Adds `use App\Attributes\Response;` to controller imports automatically
+- Creates `app/Attributes/Response.php` if it doesn't exist yet
+
+> **Tip:** Preview first with `--dry-run`:
+> ```bash
+> npx routesync annotate --input routes/api.php --dry-run
+> ```
+
+You only need to run this once, or again when you add new endpoints.
+
+### 2. Scan routes & models
 
 Run this from your **Laravel project root**:
 
@@ -92,28 +123,24 @@ npx routesync scan --input routes/api.php --models
 > cp ../backend/routesync.manifest.json .
 > ```
 
-### 2. Generate the SDK
+### 3. Generate the SDK
 
 Run this from your **frontend project root**:
 
 ```bash
-npx routesync generate \
-  --manifest routesync.manifest.json \
-  --output src/api \
-  --next-actions \
-  --zod
+npx routesync generate --manifest routesync.manifest.json --output src/api --next-actions --zod
 ```
 
 | Option | Default | Description |
 |---|---|---|
-| `--manifest` | `routesync.manifest.json` | Path to manifest from step 1 |
+| `--manifest` | `routesync.manifest.json` | Path to manifest from step 2 |
 | `--output` | `src/api` | Output folder |
 | `--next-actions` | off | Generate `actions.ts` (Next.js Server Actions) |
 | `--zod` | off | Generate `schemas.ts` (Zod validation) |
 | `--no-hooks` | off | Skip generating `hooks.ts` |
 | `--msw` | off | Generate MSW mock handlers |
 
-> **Windows PowerShell note:** Do not use backslash `\` for line continuation — PowerShell treats it differently. Run the command on a single line:
+> **Windows PowerShell note:** Do not use backslash `\` for line continuation. Run the command on a single line:
 >
 > ```powershell
 > npx routesync generate --manifest routesync.manifest.json --output src/api --next-actions --zod
@@ -133,7 +160,7 @@ src/api/
     └── models.ts ← Raw Eloquent model interfaces (when --models used)
 ```
 
-### 3. Initialize the client
+### 4. Initialize the client
 
 Call `createClient` once at app startup (e.g. in your layout or provider):
 
@@ -147,7 +174,7 @@ createClient({
 })
 ```
 
-### 4. Use in components
+### 5. Use in components
 
 ```tsx
 import { useApiQuery, useApiMutation } from 'routesync/react'
@@ -181,10 +208,9 @@ function AddToCart({ produkItemId }: { produkItemId: string }) {
 }
 ```
 
-### 5. Use Server Actions (Next.js)
+### 6. Use Server Actions (Next.js)
 
 ```ts
-// In a Server Component or form action
 import { produkGetAction, cartPostItemsAction } from '@/api/actions'
 
 // GET — no params needed
@@ -200,6 +226,144 @@ const result = await produkGetIdAction({ params: { id: '42' } })
 
 ---
 
+## Response Type Inference
+
+RouteSync automatically infers the TypeScript response type for each endpoint. The scanner works through **7 stages in order**, stopping at the first successful match.
+
+### How inference works
+
+```
+Controller method
+      │
+      ▼
+Stage 1: PHP 8 #[RouteSyncResponse] attribute on method  ← most explicit
+      │
+      ▼
+Stage 2: return new UserResource($user) in method body
+      │  ├─ Stage 2a: #[RouteSyncResponse] on Resource class
+      │  ├─ Stage 2b: @mixin \App\Models\User docblock
+      │  ├─ Stage 2c: __construct(User $user) type hint
+      │  ├─ Stage 2d: @var User $resource docblock
+      │  ├─ Stage 2e: Strip "Resource" suffix → App\Models\*
+      │  └─ Stage 2f: toArray() keys vs DB column matching
+      │
+      ▼
+Stage 3: response()->json([...]) inline array
+         keys matched against DB columns (min score 2)
+      │
+      ▼
+  response: unknown  ← annotate manually if all stages fail
+```
+
+### Zero-config inference (no annotation needed)
+
+For the common convention `UserResource` → `User`, RouteSync infers automatically:
+
+```php
+// ✅ Auto-detected — no annotation needed
+public function show(User $user): JsonResponse
+{
+    return new UserResource($user);
+}
+
+// ✅ Auto-detected — UserResource::collection → User[]
+public function index(): JsonResponse
+{
+    return UserResource::collection(User::all());
+}
+```
+
+### Auto-annotate with CLI (recommended)
+
+Instead of adding `#[Response]` by hand, let the CLI do it:
+
+```bash
+# Preview first
+npx routesync annotate --input routes/api.php --dry-run
+
+# Apply
+npx routesync annotate --input routes/api.php
+```
+
+This scans every controller method, detects which Resource it returns, resolves the model, and injects `#[Response(Model::class)]` automatically. See [Auto-annotate controllers](#1-auto-annotate-controllers-one-time-setup) for details.
+
+### Manual annotation with PHP 8 Attribute
+
+Use `#[RouteSyncResponse]` when auto-inference fails — for example when the Resource name doesn't match the model, or the response is a DTO/custom shape.
+
+**Step 1 — Create the attribute class** (`app/Attributes/RouteSyncResponse.php`):
+
+```php
+<?php
+
+namespace App\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
+class RouteSyncResponse
+{
+    public function __construct(
+        public readonly string $model,
+        public readonly bool $collection = false,
+    ) {}
+}
+```
+
+**Step 2 — Annotate your controller method:**
+
+```php
+use App\Attributes\RouteSyncResponse;
+use App\Models\User;
+
+class AuthController extends Controller
+{
+    #[RouteSyncResponse(model: User::class)]
+    public function register(RegisterRequest $request): JsonResponse
+    {
+        $user = User::create($request->validated());
+        $token = $user->createToken('auth')->plainTextToken;
+        return response()->json(['token' => $token, 'user' => new UserResource($user)]);
+    }
+
+    #[RouteSyncResponse(model: User::class, collection: true)]
+    public function index(): JsonResponse
+    {
+        return response()->json(User::all());
+    }
+}
+```
+
+**Or annotate the Resource class directly** (applies to all endpoints that return this Resource):
+
+```php
+use App\Attributes\RouteSyncResponse;
+use App\Models\User;
+
+#[RouteSyncResponse(model: User::class)]
+class UserResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return ['id' => $this->id, 'name' => $this->name, 'email' => $this->email];
+    }
+}
+```
+
+> **Priority:** annotation on controller method > annotation on Resource class > auto-inference.
+
+### When to annotate manually
+
+| Situation | Solution |
+|---|---|
+| Resource name doesn't match model (`PublicProfileResource` → `User`) | `#[RouteSyncResponse(model: User::class)]` |
+| Response is a DTO, not an Eloquent model | Add model manually after generate |
+| Controller returns `response()->json([...])` without a Resource | `#[RouteSyncResponse(model: User::class)]` |
+| Multiple models in one response | Add model manually after generate |
+| Response is still `unknown` after scan | Add `#[RouteSyncResponse]` attribute |
+
+---
+
 ## Data Transformation
 
 RouteSync handles all data mapping automatically:
@@ -225,13 +389,10 @@ import { defineApi, endpoint, resource } from 'routesync'
 createClient({ baseURL: 'https://api.myapp.com/api' })
 
 export const api = defineApi({
-  // Basic endpoint
   auth: {
     login:  endpoint<{ token: string }>({ method: 'POST', path: '/login' }),
     logout: endpoint({ method: 'POST', path: '/logout', auth: true }),
   },
-
-  // With path params
   produk: {
     list:   endpoint<ProdukItem[]>({ method: 'GET', path: '/produk' }),
     detail: endpoint<ProdukItem, { id: string }>({ method: 'GET', path: '/produk/:id' }),
@@ -239,8 +400,6 @@ export const api = defineApi({
       method: 'POST', path: '/produk', auth: true
     }),
   },
-
-  // resource() — shared auth/headers for a group
   cart: resource({
     auth: true,
     endpoints: {
@@ -289,7 +448,7 @@ import { api } from '@/api/api'
 // GET
 const { data, isLoading } = useApiQuery(api.orders.get)
 
-// GET with params + query
+// GET with params
 const { data } = useApiQuery(api.orders.getId, { params: { id: '1' } })
 
 // Mutation
@@ -302,8 +461,7 @@ mutation.mutate({ body: { produk_item_id: '5', qty: 1 } })
 ```ts
 import { generateHooks } from 'routesync'
 
-const hooks = generateHooks(api)
-const { useOrdersGet, useCartPostItems } = hooks
+const { useOrdersGet, useCartPostItems } = generateHooks(api)
 // GET/DELETE → useQuery, everything else → useMutation
 ```
 
@@ -312,8 +470,7 @@ const { useOrdersGet, useCartPostItems } = hooks
 ```ts
 import { createHooks } from 'routesync/react'
 
-const cartHooks = createHooks(api.cart)
-const { usePostItems, usePatchItemsProdukItemId } = cartHooks
+const { usePostItems, usePatchItemsProdukItemId } = createHooks(api.cart)
 ```
 
 ---
@@ -339,6 +496,15 @@ When using `--zod` with `routesync generate`, `schemas.ts` is generated from you
 ## CLI Reference
 
 ```bash
+# Auto-inject #[Response] attributes into controller methods
+npx routesync annotate --input routes/api.php
+
+# Preview without writing files
+npx routesync annotate --input routes/api.php --dry-run
+
+# Re-annotate already-annotated methods
+npx routesync annotate --input routes/api.php --force
+
 # Scan Laravel routes only
 npx routesync scan --input routes/api.php
 
@@ -361,16 +527,28 @@ npx routesync watch --input routes/api.php --output src/api
 
 ```
 routes/api.php + app/Models/
-         ↓  routesync scan --models
+         │
+         ▼
+npx routesync annotate        ← inject #[Response] into controllers
+         │
+         ▼
+npx routesync scan --models   ← read routes + DB columns → manifest
+         │
+         ▼
    routesync.manifest.json
-         ↓  routesync generate
+         │
+         ▼
+npx routesync generate        ← generate SDK from manifest
+         │
+         ▼
    src/api/
-    ├── api.ts       ← defineApi + endpoints
+    ├── api.ts       ← defineApi + endpoints + Contract types
     ├── types.ts     ← interfaces from DB columns
     ├── hooks.ts     ← TanStack Query hooks
     ├── actions.ts   ← Next.js Server Actions
     └── schemas.ts   ← Zod schemas
-         ↓
+         │
+         ▼
    React / Vue / Next.js
 ```
 
@@ -381,7 +559,7 @@ The CLI parses your route file via PHP reflection (using Laravel's own bootstrap
 ## Requirements
 
 - Node.js >= 20
-- PHP available in PATH (for `scan --models`)
+- PHP available in PATH (for `scan --models` and `annotate`)
 - Laravel project with database accessible (for `scan --models`)
 
 ## License