go-duck-cli 1.2.1 → 1.2.3

package/generators/postman.js

@@ -169,11 +169,25 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
     });
 
     // 3. GraphQL
-    collection.item.push({
+    const generateGqlFieldsInput = (fields) => {
+        return fields.map(f => {
+            if (f.type === 'String' || f.type === 'Text') return `${f.name}: "Sample ${f.name}"`;
+            if (f.type === 'Integer' || f.type === 'Long') return `${f.name}: 100`;
+            if (f.type === 'Float' || f.type === 'BigDecimal') return `${f.name}: 99.99`;
+            if (f.type === 'Boolean') return `${f.name}: true`;
+            if (f.type === 'LocalDate') return `${f.name}: "2024-01-01"`;
+            if (f.type === 'Instant') return `${f.name}: "2024-01-01T12:00:00Z"`;
+            if (f.type === 'JSON' || f.type === 'JSONB') return `${f.name}: "{\\"attribute\\": \\"example_value\\"}"`;
+            return `${f.name}: "test"`;
+        }).join(',\n    ');
+    };
+
+    const graphqlFolder = {
         name: "3. GraphQL Federation Layer",
+        description: "Federated GraphQL operations for all GDL entities.",
         item: [
             {
-                name: "1. Unified GraphQL Engine",
+                name: "GraphQL Endpoint Playground",
                 request: {
                     method: "POST",
                     header: [
@@ -184,7 +198,7 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
                     body: {
                         mode: "graphql",
                         graphql: {
-                            query: `query {\n  ${entities.length > 0 ? 'list' + entities[0].name.charAt(0).toUpperCase() + entities[0].name.slice(1) + 's' : 'test'} {\n    id\n  }\n}`,
+                            query: "query {\n  __schema {\n    types {\n      name\n    }\n  }\n}",
                             variables: ""
                         }
                     },
@@ -198,7 +212,143 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
                 }
             }
         ]
-    });
+    };
+
+    for (const entity of entities) {
+        const capitalized = entity.name.charAt(0).toUpperCase() + entity.name.slice(1);
+        const entityGqlFolder = {
+            name: `${capitalized} GraphQL`,
+            item: [
+                {
+                    name: `List ${capitalized}s (GraphQL Query)`,
+                    request: {
+                        method: "POST",
+                        header: [
+                            { key: "Authorization", value: "Bearer {{token}}" },
+                            { key: "X-Tenant-ID", value: "{{tenant}}" },
+                            { key: "Content-Type", value: "application/json" }
+                        ],
+                        body: {
+                            mode: "graphql",
+                            graphql: {
+                                query: `query {\n  list${capitalized}s(page: 1, size: 10) {\n    role\n    items {\n      id\n      ${entity.fields.map(f => f.name).join('\n      ')}\n      createdAt\n      updatedAt\n    }\n  }\n}`,
+                                variables: ""
+                            }
+                        },
+                        url: {
+                            raw: "http://{{host}}:{{port}}/graphql",
+                            protocol: "http",
+                            host: ["{{host}}"],
+                            port: "{{port}}",
+                            path: ["graphql"]
+                        }
+                    }
+                },
+                {
+                    name: `Get ${capitalized} by ID (GraphQL Query)`,
+                    request: {
+                        method: "POST",
+                        header: [
+                            { key: "Authorization", value: "Bearer {{token}}" },
+                            { key: "X-Tenant-ID", value: "{{tenant}}" },
+                            { key: "Content-Type", value: "application/json" }
+                        ],
+                        body: {
+                            mode: "graphql",
+                            graphql: {
+                                query: `query {\n  get${capitalized}(id: "1") {\n    role\n    data {\n      id\n      ${entity.fields.map(f => f.name).join('\n      ')}\n      createdAt\n      updatedAt\n    }\n  }\n}`,
+                                variables: ""
+                            }
+                        },
+                        url: {
+                            raw: "http://{{host}}:{{port}}/graphql",
+                            protocol: "http",
+                            host: ["{{host}}"],
+                            port: "{{port}}",
+                            path: ["graphql"]
+                        }
+                    }
+                },
+                {
+                    name: `Create ${capitalized} (GraphQL Mutation)`,
+                    request: {
+                        method: "POST",
+                        header: [
+                            { key: "Authorization", value: "Bearer {{token}}" },
+                            { key: "X-Tenant-ID", value: "{{tenant}}" },
+                            { key: "Content-Type", value: "application/json" }
+                        ],
+                        body: {
+                            mode: "graphql",
+                            graphql: {
+                                query: `mutation {\n  create${capitalized}(input: {\n    ${generateGqlFieldsInput(entity.fields)}\n  }) {\n    role\n    data {\n      id\n      ${entity.fields.map(f => f.name).join('\n      ')}\n      createdAt\n      updatedAt\n    }\n  }\n}`,
+                                variables: ""
+                            }
+                        },
+                        url: {
+                            raw: "http://{{host}}:{{port}}/graphql",
+                            protocol: "http",
+                            host: ["{{host}}"],
+                            port: "{{port}}",
+                            path: ["graphql"]
+                        }
+                    }
+                },
+                {
+                    name: `Update ${capitalized} (GraphQL Mutation)`,
+                    request: {
+                        method: "POST",
+                        header: [
+                            { key: "Authorization", value: "Bearer {{token}}" },
+                            { key: "X-Tenant-ID", value: "{{tenant}}" },
+                            { key: "Content-Type", value: "application/json" }
+                        ],
+                        body: {
+                            mode: "graphql",
+                            graphql: {
+                                query: `mutation {\n  update${capitalized}(id: "1", input: {\n    ${generateGqlFieldsInput(entity.fields)}\n  }) {\n    role\n    data {\n      id\n      ${entity.fields.map(f => f.name).join('\n      ')}\n      createdAt\n      updatedAt\n    }\n  }\n}`,
+                                variables: ""
+                            }
+                        },
+                        url: {
+                            raw: "http://{{host}}:{{port}}/graphql",
+                            protocol: "http",
+                            host: ["{{host}}"],
+                            port: "{{port}}",
+                            path: ["graphql"]
+                        }
+                    }
+                },
+                {
+                    name: `Delete ${capitalized} (GraphQL Mutation)`,
+                    request: {
+                        method: "POST",
+                        header: [
+                            { key: "Authorization", value: "Bearer {{token}}" },
+                            { key: "X-Tenant-ID", value: "{{tenant}}" },
+                            { key: "Content-Type", value: "application/json" }
+                        ],
+                        body: {
+                            mode: "graphql",
+                            graphql: {
+                                query: `mutation {\n  delete${capitalized}(id: "1")\n}`,
+                                variables: ""
+                            }
+                        },
+                        url: {
+                            raw: "http://{{host}}:{{port}}/graphql",
+                            protocol: "http",
+                            host: ["{{host}}"],
+                            port: "{{port}}",
+                            path: ["graphql"]
+                        }
+                    }
+                }
+            ]
+        };
+        graphqlFolder.item.push(entityGqlFolder);
+    }
+    collection.item.push(graphqlFolder);
 
     // 4. REST Entities
     const restFolder = { name: "4. Standard REST & Deep Search", item: [] };
@@ -240,7 +390,7 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
                 request: {
                     method: "GET",
                     header: [ { key: "X-Tenant-ID", value: "{{tenant}}" } ],
-                    url: { raw: `http://{{host}}:{{port}}/open/api/${name}s?page=1&size=10&eager=true`, protocol: "http", host: ["{{host}}"], port: "{{port}}", path: ["open", "api", `${name}s`], query: [ { key: "page", value: "1" }, { key: "size", value: "10" }, { key: "eager", value: "true" } ] }
+                    url: { raw: `http://{{host}}:{{port}}/open/api/${name}s?page=1&size=10&eager=true&sort=id,asc`, protocol: "http", host: ["{{host}}"], port: "{{port}}", path: ["open", "api", `${name}s`], query: [ { key: "page", value: "1" }, { key: "size", value: "10" }, { key: "eager", value: "true" }, { key: "sort", value: "id,asc" } ] }
                 }
             });
             publicItems.push({
@@ -275,7 +425,7 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
                 request: {
                     method: "GET",
                     header: [ { key: "Authorization", value: "Bearer {{token}}" }, { key: "X-Tenant-ID", value: "{{tenant}}" } ],
-                    url: { raw: `http://{{host}}:{{port}}/api/${name}s?page=1&size=10&eager=true`, protocol: "http", host: ["{{host}}"], port: "{{port}}", path: ["api", `${name}s`], query: [ { key: "page", value: "1" }, { key: "size", value: "10" }, { key: "eager", value: "true" } ] }
+                    url: { raw: `http://{{host}}:{{port}}/api/${name}s?page=1&size=10&eager=true&sort=id,asc`, protocol: "http", host: ["{{host}}"], port: "{{port}}", path: ["api", `${name}s`], query: [ { key: "page", value: "1" }, { key: "size", value: "10" }, { key: "eager", value: "true" }, { key: "sort", value: "id,asc" } ] }
                 }
             },
             {

package/generators/security.js

@@ -21,7 +21,7 @@ import (
 	"time"
 
 	"github.com/gin-gonic/gin"
-	"github.com/golang-jwt/jwt/v4"
+	"github.com/golang-jwt/jwt/v5"
 	"{{app_name}}/config"
 )
 
@@ -164,7 +164,7 @@ func JWTMiddleware() gin.HandlerFunc {
 				return nil, fmt.Errorf("missing kid header")
 			}
 			return GetPublicKeyByKid(kid, config.GetConfig())
-		})
+		}, jwt.WithLeeway(10*time.Second))
 
 		if err != nil || !token.Valid {
 			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Invalid or expired token"})

package/index.js

@@ -357,7 +357,7 @@ const getPreviousEntities = async (outputDir) => {
     return entities;
 };
 
-const generateEntities = async (gdlPath, outputDir, config) => {
+const generateEntities = async (gdlPath, outputDir, config, isImport = false) => {
     let entities = [];
     let relationships = [];
     let enums = [];
@@ -399,6 +399,47 @@ const generateEntities = async (gdlPath, outputDir, config) => {
     console.log(chalk.green(`✅ Parsed ${entities.length} entities, ${relationships.length} relationships, ${enums.length} enums, and detected ${openEntities.length} open rules`));
 
     const previousEntities = await getPreviousEntities(outputDir);
+
+    // Any parsed entity with @Delete is mapped as a deletion
+    const deletedParsed = entities.filter(e => e.isDelete);
+    
+    // Remove deleted entities from active entities array
+    entities = entities.filter(e => !e.isDelete);
+
+    // Filter out relationships & open rule entries that involve deleted entities
+    relationships = relationships.filter(rel => 
+        !deletedParsed.some(d => d.name === rel.from.entity || d.name === rel.to.entity)
+    );
+    openEntities = openEntities.filter(oe => 
+        !deletedParsed.some(d => d.name === oe.name)
+    );
+
+    if (isImport) {
+        for (const prev of previousEntities) {
+            if (!entities.some(e => e.name === prev.name) && !deletedParsed.some(d => d.name === prev.name)) {
+                entities.push(prev);
+                if (prev.relationships) {
+                    for (const r of prev.relationships) {
+                        const exists = relationships.some(rel => 
+                            (rel.from.entity === r.from.entity && rel.from.field === r.from.field && rel.to.entity === r.to.entity && rel.to.field === r.to.field) ||
+                            (rel.from.entity === r.to.entity && rel.from.field === r.to.field && rel.to.entity === r.from.entity && rel.to.field === r.from.field)
+                        );
+                        if (!exists) relationships.push(r);
+                    }
+                }
+                if (prev.enums) {
+                    for (const en of prev.enums) {
+                        if (!enums.some(e => e.name === en.name)) enums.push(en);
+                    }
+                }
+                if (prev.openEntities) {
+                    for (const oe of prev.openEntities) {
+                        if (!openEntities.some(o => o.name === oe.name)) openEntities.push(oe);
+                    }
+                }
+            }
+        }
+    }
     const delta = {
         newEntities: [],
         newFields: {},
@@ -443,9 +484,18 @@ const generateEntities = async (gdlPath, outputDir, config) => {
     }
 
     // Check for deleted entities
-    for (const prev of previousEntities) {
-        if (!entities.some(e => e.name === prev.name)) {
-            delta.deletedEntities.push(prev);
+    if (isImport) {
+        for (const d of deletedParsed) {
+            const prev = previousEntities.find(e => e.name === d.name);
+            if (prev) {
+                delta.deletedEntities.push(prev);
+            }
+        }
+    } else {
+        for (const prev of previousEntities) {
+            if (!entities.some(e => e.name === prev.name)) {
+                delta.deletedEntities.push(prev);
+            }
         }
     }
 
@@ -762,7 +812,7 @@ require (
         await generateResilienceCode(config, absoluteOutputDir);
         await generateTelemetryCode(config, absoluteOutputDir);
         await generateDeploymentArtifacts(config, absoluteOutputDir);
-        const { entities, relationships, enums, openEntities } = await generateEntities(gdlPath, absoluteOutputDir, config);
+        const { entities, relationships, enums, openEntities } = await generateEntities(gdlPath, absoluteOutputDir, config, true);
         await generateKratosCode(entities, absoluteOutputDir, config.name, enums);
 
         await generateRepositoryCode(absoluteOutputDir);
@@ -828,13 +878,18 @@ const generateYAMLConfigs = async (config, outputDir) => {
     const extendedConfig = {
         ...cleanConfig,
         server: {
-            port: cleanConfig.server?.port || 8080,
+            rest: {
+                port: cleanConfig.server?.rest?.port || cleanConfig.server?.port || 8080,
+                protocol: cleanConfig.server?.rest?.protocol || 'json'
+            },
             'read-timeout': cleanConfig.server?.['read-timeout'] || '30s',
             'write-timeout': cleanConfig.server?.['write-timeout'] || '30s',
             grpc: {
                 addr: cleanConfig.server?.grpc?.addr || ':9000',
                 network: cleanConfig.server?.grpc?.network || 'tcp',
-                timeout: cleanConfig.server?.grpc?.timeout || '1s'
+                timeout: cleanConfig.server?.grpc?.timeout || '1s',
+                web_enabled: cleanConfig.server?.grpc?.web_enabled ?? true,
+                web_port: cleanConfig.server?.grpc?.web_port || 9090
             },
             cors: {
                 'allow-origins': cleanConfig.server?.cors?.['allow-origins'] || ['*'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-duck-cli",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "The Ultimate Evolutionary Go Microservice Scaffolder.",
   "main": "index.js",
   "type": "module",

package/parser/gdl.js

@@ -179,6 +179,7 @@ export const parseGDL = async (filePath) => {
         const isSearchable = annotation?.includes('@Searchable');
         const isDocument = annotation?.includes('@Document') || annotation?.includes('@isDocument');
         const isEmbedded = annotation?.includes('@Embed');
+        const isDelete = annotation?.includes('@Delete');
 
         const fields = parseFields(block.fieldBlock);
 
@@ -190,6 +191,7 @@ export const parseGDL = async (filePath) => {
             isSearchable,
             isDocument,
             isEmbedded,
+            isDelete,
             fields 
         });
     }

package/templates/docs/index.html.hbs

@@ -69,7 +69,8 @@ go run main.go</code></pre>
                 <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">1. REST APIs & Generic Search</h2>
                 <p class="mb-4">The application provides standard RESTful CRUD endpoints for all generated entities (e.g., {{#if entities.length}}{{entities.[0].name}}{{else}}Entity{{/if}}).</p>
                 
-                <h3 class="font-semibold mb-2">Standard CRUD:</h3>
+                <h3 class="font-semibold mb-2">Standard CRUD (Multi-Protocol):</h3>
+                <p class="mb-2 text-sm text-gray-600">The REST API natively supports JSON and MessagePack based on your <code>application.yml</code> settings.</p>
                 <pre><code class="language-http">GET /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}?page=1&pageSize=10
 POST /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}
 PUT /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}/:id
@@ -81,6 +82,17 @@ DELETE /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}ent
   -H "Authorization: Bearer YOUR_JWT" \
   -H "X-Tenant-ID: tenant_1"</code></pre>
                 <p class="text-sm text-gray-500 mt-2">Supported operators: <code>eq, neq, gt, gte, lt, lte, like, ilike</code></p>
+
+                <h3 class="font-semibold mb-2 mt-6">Elasticsearch Global Search (Spring-style):</h3>
+                <p class="mb-2">For entities marked with <code>@Searchable</code>, use the native Elasticsearch endpoint for advanced queries (wildcards, booleans, and ranges).</p>
+                <pre><code class="language-bash">curl -G "http://localhost:{{serverPort}}/api/search/{{#if entities.length}}{{toLowerCase entities.[0].name}}{{else}}entity{{/if}}" \
+  --data-urlencode "q=name:John AND age:>18" \
+  -H "Authorization: Bearer YOUR_JWT"</code></pre>
+                <ul class="text-sm text-gray-500 mt-2 list-disc pl-5">
+                    <li><strong>Wildcards:</strong> <code>q=name*</code> (matches "name15", "name_abc")</li>
+                    <li><strong>Boolean Logic:</strong> <code>q=status:PUBLISHED AND (author:John OR author:Jane)</code></li>
+                    <li><strong>Ranges:</strong> <code>q=age:[18 TO 30]</code> or <code>q=created_at:>2023-01-01</code></li>
+                </ul>
             </section>
 
             <!-- Audit & Metering -->
@@ -127,6 +139,17 @@ mosquitto_sub -h localhost -p {{mqttPort}} -t "go-duck/events/#" -u dev_user -P
                 <p class="text-sm mt-2">Example topic: <code>go-duck/events/{{#if entities.length}}{{toLowerCase entities.[0].name}}{{else}}entity{{/if}}/CREATE</code></p>
             </section>
 
+            <!-- gRPC-Web -->
+            <section id="grpc-web" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">gRPC & gRPC-Web</h2>
+                <p class="mb-4">The Kratos gRPC engine powers blazing fast service-to-service communication. For frontend developers, we automatically start a <strong>gRPC-Web Proxy</strong>.</p>
+                <ul class="list-disc pl-6 space-y-2 mb-4">
+                    <li>The core Kratos gRPC server runs on <code>:9000</code> (configurable).</li>
+                    <li>The <strong>gRPC-Web Proxy</strong> runs on <code>:9090</code>, translating HTTP/1.1 calls to HTTP/2.</li>
+                    <li>Frontend apps (React/Angular) can directly call Protobuf endpoints using standard <code>grpc-web</code> generated clients without hitting the REST APIs!</li>
+                </ul>
+            </section>
+
             <!-- Kratos gRPC -->
             <section id="grpc-kratos" class="content-section">
                 <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Kratos Secured gRPC APIs</h2>

package/templates/docs/pages/cli.hbs

@@ -44,17 +44,33 @@ go-duck import-gdl my_new_schema.gdl -o ./MY_APP</code></pre>
         <span class="w-8 h-8 rounded-lg bg-emerald-100 text-emerald-600 flex items-center justify-center mr-3 text-sm">
             <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 7v8a2 2 0 002 2h6M8 7V5a2 2 0 012-2h4.586a1 1 0 01.707.293l4.414 4.414a1 1 0 01.293.707V15a2 2 0 01-2 2h-2M8 7H6a2 2 0 00-2 2v10a2 2 0 002 2h8a2 2 0 002-2v-2"></path></svg>
         </span>
-        2. Persistence Intelligence & the `.go-duck/` Folder
+        2. Schema Evolution & the `.go-duck/` State
     </h2>
-    <p class="mb-4 text-slate-600 leading-relaxed font-medium">"If I run the generator twice, will it overwrite my database migrations?" <strong>No.</strong></p>
+    <p class="mb-4 text-slate-600 leading-relaxed font-medium">"If I run the generator to import a new GDL, will it overwrite my database or delete existing entities?" <strong>No, thanks to stateful evolution.</strong></p>
     
-    <p class="mb-6 text-slate-600 leading-relaxed">The generator maintains a stateful snapshot of every entity it has ever generated inside the hidden <code class="bg-slate-100 px-1 py-0.5 rounded text-slate-800 font-mono text-sm">.go-duck/</code> directory at the root of your target project. When you run <code>import-gdl</code>, the code parser literally diffs your new file against the JSON representations in <code>.go-duck/</code> to intelligently assess the exact Table changes necessary without executing ghost migrations.</p>
+    <p class="mb-6 text-slate-600 leading-relaxed">The generator maintains a stateful snapshot of every entity it has ever generated inside the hidden <code class="bg-slate-100 px-1 py-0.5 rounded text-slate-800 font-mono text-sm">.go-duck/</code> directory at the root of your target project. When you run <code>import-gdl</code>, the CLI intelligently merges existing entities with newly parsed entities and executes targeted diff operations:</p>
+
+    <!-- EVOLUTION TYPE CARDS -->
+    <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
+        <div class="p-6 bg-slate-50 border border-slate-200 rounded-2xl">
+            <span class="text-xs font-bold text-indigo-600 uppercase tracking-wide block mb-2 font-mono">1. Snapshot Merging</span>
+            <p class="text-xs text-slate-600 leading-relaxed m-0">Supports splitting your entities into multiple GDL files. Unspecified active models are loaded from the <code>.go-duck/</code> folder and merged with new entities, keeping active routers and endpoints in sync.</p>
+        </div>
+        <div class="p-6 bg-slate-50 border border-slate-200 rounded-2xl">
+            <span class="text-xs font-bold text-emerald-600 uppercase tracking-wide block mb-2 font-mono">2. Column Alterations</span>
+            <p class="text-xs text-slate-600 leading-relaxed m-0">Adding, dropping, or modifying fields inside entity blocks generates specific <code>ADD COLUMN</code> or <code>DROP COLUMN</code> SQL statements in a timestamped Goose migration file.</p>
+        </div>
+        <div class="p-6 bg-slate-50 border border-slate-200 rounded-2xl">
+            <span class="text-xs font-bold text-rose-600 uppercase tracking-wide block mb-2 font-mono">3. Complete Purging</span>
+            <p class="text-xs text-slate-600 leading-relaxed m-0">Marking an entity with the <code>@Delete</code> annotation automatically triggers a database <code>DROP TABLE</code> SQL migration, purges all generated Go/Protobuf code files, and clears its snapshot.</p>
+        </div>
+    </div>
 
     <div class="bg-rose-50 border border-rose-200 p-5 mb-6 rounded-xl flex items-start shadow-sm shadow-rose-100/50">
         <svg class="w-6 h-6 text-rose-500 mt-0.5 mr-3 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path></svg>
         <div>
             <h4 class="font-bold text-rose-900 mb-1">Warning</h4>
-            <p class="text-rose-800 text-sm leading-relaxed"><strong>Never delete `.go-duck/`</strong> unless you are intentionally wiping the database and starting configuration completely from zero.</p>
+            <p class="text-rose-800 text-sm leading-relaxed"><strong>Never manually delete `.go-duck/`</strong> unless you are intentionally wiping the entire database state and starting configuration completely from scratch.</p>
         </div>
     </div>
 </section>

package/templates/docs/pages/gdl-annotations.hbs

@@ -100,6 +100,23 @@
                 <p class="text-[11px] text-indigo-900 m-0 font-medium font-mono leading-tight">Architectural Impact: Scaffolds routes into the <code class="text-indigo-600 text-[10px]">/api/open/*</code> group, bypassing the OIDC Validator middleware chain.</p>
             </div>
         </div>
+
+        <!-- @Delete -->
+        <div class="p-10 bg-rose-50 border border-rose-100 rounded-[3rem] shadow-sm transition-all duration-300 hover:shadow-rose-200 group relative overflow-hidden">
+            <div class="absolute top-0 right-0 p-6 opacity-[0.03] group-hover:opacity-[0.07] transition-opacity">
+                <svg class="w-32 h-32 text-rose-900" fill="currentColor" viewBox="0 0 20 20"><path fill-rule="evenodd" d="M9 2a1 1 0 00-.894.553L7.382 4H4a1 1 0 000 2v10a2 2 0 002 2h8a2 2 0 002-2V6a1 1 0 100-2h-3.382l-.724-1.447A1 1 0 0011 2H9zM7 8a1 1 0 012 0v6a1 1 0 11-2 0V8zm5-1a1 1 0 00-1 1v6a1 1 0 102 0V8a1 1 0 00-1-1z" clip-rule="evenodd"></path></svg>
+            </div>
+            <div class="flex items-center justify-between mb-8">
+                <code class="text-rose-700 font-mono font-black text-2xl group-hover:scale-105 transition-transform">@Delete</code>
+                <div class="w-12 h-12 bg-white rounded-2xl flex items-center justify-center text-2xl shadow-sm">🗑️</div>
+            </div>
+            <h4 class="text-lg font-black text-slate-900 mb-4 m-0 uppercase tracking-tighter">Entity Deletion</h4>
+            <p class="text-sm text-slate-700 leading-relaxed m-0 italic mb-6">Triggers full entity cleanup. Upon import, the generator purges all generated source code (models, controllers, repositories) and generates a database <code>DROP TABLE</code> migration.</p>
+            <div class="p-4 bg-white/50 rounded-2xl border border-rose-200 border-dashed">
+                <span class="text-[10px] font-bold text-rose-400 uppercase tracking-widest block mb-2 font-mono">Architectural Impact</span>
+                <p class="text-[11px] text-rose-900 m-0 font-medium font-mono leading-tight">Removes snapshots from .go-duck/, wipes Go files, and scaffolds drop SQL statements.</p>
+            </div>
+        </div>
     </div>
 
     <!-- COMPLEX EXAMPLE -->

package/templates/docs/pages/rest.hbs

@@ -129,6 +129,27 @@
         </div>
     </section>
 
+    <!-- PAGINATION & SORTING -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-8 tracking-tight italic underline decoration-indigo-600 underline-offset-8">Pagination & Dynamic Sorting</h2>
+        <div class="p-8 bg-slate-50 border border-slate-200 rounded-[2.5rem] shadow-sm">
+            <p class="text-slate-600 mb-6">List endpoints support pagination and dynamic sorting for both relational (PostgreSQL) and document-based (MongoDB) silos.</p>
+            
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-8">
+                <div class="p-6 bg-white rounded-2xl border border-slate-100 shadow-sm border-l-4 border-l-indigo-600">
+                    <h4 class="font-bold text-slate-900 mb-2">Pagination</h4>
+                    <p class="text-xs text-slate-500 mb-4">Specify the page number (1-indexed) and limit size via standard query parameters. The response contains total count in the <code>X-Total-Count</code> header.</p>
+                    <code class="text-xs font-mono font-bold text-indigo-700 bg-indigo-50 px-3 py-1 rounded-full">GET /api/v1/car?page=1&amp;size=20</code>
+                </div>
+                <div class="p-6 bg-white rounded-2xl border border-slate-100 shadow-sm border-l-4 border-l-emerald-600">
+                    <h4 class="font-bold text-slate-900 mb-2">Dynamic Sorting</h4>
+                    <p class="text-xs text-slate-500 mb-4">Sort fields dynamically in ascending (default or <code>asc</code>) or descending (<code>desc</code>) order. The sorting format is <code>?sort=fieldname,direction</code>.</p>
+                    <code class="text-xs font-mono font-bold text-emerald-700 bg-emerald-50 px-3 py-1 rounded-full">GET /api/v1/car?sort=price,desc</code>
+                </div>
+            </div>
+        </div>
+    </section>
+
     <!-- RPC OPERATORS -->
     <section class="mb-10 text-center">
         <h2 class="text-2xl font-black text-slate-900 mb-6 italic italic underline decoration-indigo-200 underline-offset-8 decoration-8 font-serif uppercase tracking-widest">GORM Filter Reference</h2>