routesync 1.0.36 → 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
@@ -216,14 +242,14 @@ 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      ← NEW
-      │  ├─ Stage 2d: @var User $resource docblock           ← NEW
-      │  ├─ Stage 2e: Strip "Resource" suffix → App\Models\* ← NEW
-      │  └─ Stage 2f: toArray() keys vs DB column matching   ← NEW
+      │  ├─ 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)       ← NEW
+         keys matched against DB columns (min score 2)
       │
       ▼
   response: unknown  ← annotate manually if all stages fail
@@ -247,9 +273,23 @@ public function index(): JsonResponse
 }
 ```
 
-### Explicit annotation with PHP 8 Attribute
+### Auto-annotate with CLI (recommended)
 
-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.
+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`):
 
@@ -278,17 +318,14 @@ use App\Models\User;
 
 class AuthController extends Controller
 {
-    // Single object response
     #[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)]);
     }
 
-    // Collection response
     #[RouteSyncResponse(model: User::class, collection: true)]
     public function index(): JsonResponse
     {
@@ -308,11 +345,7 @@ class UserResource extends JsonResource
 {
     public function toArray($request): array
     {
-        return [
-            'id'    => $this->id,
-            'name'  => $this->name,
-            'email' => $this->email,
-        ];
+        return ['id' => $this->id, 'name' => $this->name, 'email' => $this->email];
     }
 }
 ```
@@ -356,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' }),
@@ -370,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: {
@@ -420,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
@@ -433,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
 ```
 
@@ -443,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)
 ```
 
 ---
@@ -470,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
 
@@ -492,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
 ```
 
@@ -512,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