npm - @caoscompanybr/merlin - Versions diffs - 3.5.0 - Mend

@caoscompanybr/merlin 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (762) hide show

package/.merlin-core/skills/general/next-best-practices/references/scripts.md ADDED Viewed

@@ -0,0 +1,141 @@
+# Scripts
+Loading third-party scripts in Next.js.
+## Use next/script
+Always use `next/script` instead of native `<script>` tags for better performance.
+```tsx
+// Bad: Native script tag
+<script src="https://example.com/script.js"></script>;
+// Good: Next.js Script component
+import Script from "next/script";
+<Script src="https://example.com/script.js" />;
+```
+## Inline Scripts Need ID
+Inline scripts require an `id` attribute for Next.js to track them.
+```tsx
+// Bad: Missing id
+<Script dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
+// Good: Has id
+<Script id="my-script" dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
+// Good: Inline with id
+<Script id="show-banner">
+  {`document.getElementById('banner').classList.remove('hidden')`}
+</Script>
+```
+## Don't Put Script in Head
+`next/script` should not be placed inside `next/head`. It handles its own positioning.
+```tsx
+// Bad: Script inside Head
+import Head from 'next/head'
+import Script from 'next/script'
+<Head>
+  <Script src="/analytics.js" />
+</Head>
+// Good: Script outside Head
+<Head>
+  <title>Page</title>
+</Head>
+<Script src="/analytics.js" />
+```
+## Loading Strategies
+```tsx
+// afterInteractive (default) - Load after page is interactive
+<Script src="/analytics.js" strategy="afterInteractive" />
+// lazyOnload - Load during idle time
+<Script src="/widget.js" strategy="lazyOnload" />
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+<Script src="/critical.js" strategy="beforeInteractive" />
+// worker - Load in web worker (experimental)
+<Script src="/heavy.js" strategy="worker" />
+```
+## Google Analytics
+Use `@next/third-parties` instead of inline GA scripts.
+```tsx
+// Bad: Inline GA script
+<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" />
+<Script id="ga-init">
+  {`window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', 'G-XXXXX');`}
+</Script>
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+export default function Layout({ children }) {
+  return (
+    <html>
+      <body>{children}</body>
+      <GoogleAnalytics gaId="G-XXXXX" />
+    </html>
+  )
+}
+```
+## Google Tag Manager
+```tsx
+import { GoogleTagManager } from "@next/third-parties/google";
+export default function Layout({ children }) {
+  return (
+    <html>
+      <GoogleTagManager gtmId="GTM-XXXXX" />
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+## Other Third-Party Scripts
+```tsx
+// YouTube embed
+import { YouTubeEmbed } from "@next/third-parties/google";
+<YouTubeEmbed videoid="dQw4w9WgXcQ" />;
+// Google Maps
+import { GoogleMapsEmbed } from "@next/third-parties/google";
+<GoogleMapsEmbed
+  apiKey="YOUR_API_KEY"
+  mode="place"
+  q="Brooklyn+Bridge,New+York,NY"
+/>;
+```
+## Quick Reference
+| Pattern                                       | Issue                      | Fix                       |
+| --------------------------------------------- | -------------------------- | ------------------------- |
+| `<script src="...">`                          | No optimization            | Use `next/script`         |
+| `<Script>` without id                         | Can't track inline scripts | Add `id` attribute        |
+| `<Script>` inside `<Head>`                    | Wrong placement            | Move outside Head         |
+| Inline GA/GTM scripts                         | No optimization            | Use `@next/third-parties` |
+| `strategy="beforeInteractive"` outside layout | Won't work                 | Only use in root layout   |

package/.merlin-core/skills/general/next-best-practices/references/self-hosting.md ADDED Viewed

@@ -0,0 +1,384 @@
+# Self-Hosting Next.js
+Deploy Next.js outside of Vercel with confidence.
+## Quick Start: Standalone Output
+For Docker or any containerized deployment, use standalone output:
+```js
+// next.config.js
+module.exports = {
+  output: "standalone",
+};
+```
+This creates a minimal `standalone` folder with only production dependencies:
+```
+.next/
+├── standalone/
+│   ├── server.js          # Entry point
+│   ├── node_modules/      # Only production deps
+│   └── .next/             # Build output
+└── static/                # Must be copied separately
+```
+## Docker Deployment
+### Dockerfile
+```dockerfile
+FROM node:20-alpine AS base
+# Install dependencies
+FROM base AS deps
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+# Build
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+# Production
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+# Create non-root user
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+# Copy standalone output
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+CMD ["node", "server.js"]
+```
+### Docker Compose
+```yaml
+version: "3.8"
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+    healthcheck:
+      test:
+        ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+## PM2 Deployment
+For traditional server deployments:
+```js
+// ecosystem.config.js
+module.exports = {
+  apps: [
+    {
+      name: "nextjs",
+      script: ".next/standalone/server.js",
+      instances: "max",
+      exec_mode: "cluster",
+      env: {
+        NODE_ENV: "production",
+        PORT: 3000,
+      },
+    },
+  ],
+};
+```
+```bash
+npm run build
+pm2 start ecosystem.config.js
+```
+## ISR and Cache Handlers
+### The Problem
+ISR (Incremental Static Regeneration) uses filesystem caching by default. This **breaks with multiple instances**:
+- Instance A regenerates page → saves to its local disk
+- Instance B serves stale page → doesn't see Instance A's cache
+- Load balancer sends users to random instances → inconsistent content
+### Solution: Custom Cache Handler
+Next.js 14+ supports custom cache handlers for shared storage:
+```js
+// next.config.js
+module.exports = {
+  cacheHandler: require.resolve("./cache-handler.js"),
+  cacheMaxMemorySize: 0, // Disable in-memory cache
+};
+```
+#### Redis Cache Handler Example
+```js
+// cache-handler.js
+const Redis = require("ioredis");
+const redis = new Redis(process.env.REDIS_URL);
+const CACHE_PREFIX = "nextjs:";
+module.exports = class CacheHandler {
+  constructor(options) {
+    this.options = options;
+  }
+  async get(key) {
+    const data = await redis.get(CACHE_PREFIX + key);
+    if (!data) return null;
+    const parsed = JSON.parse(data);
+    return {
+      value: parsed.value,
+      lastModified: parsed.lastModified,
+    };
+  }
+  async set(key, data, ctx) {
+    const cacheData = {
+      value: data,
+      lastModified: Date.now(),
+    };
+    // Set TTL based on revalidate option
+    if (ctx?.revalidate) {
+      await redis.setex(
+        CACHE_PREFIX + key,
+        ctx.revalidate,
+        JSON.stringify(cacheData),
+      );
+    } else {
+      await redis.set(CACHE_PREFIX + key, JSON.stringify(cacheData));
+    }
+  }
+  async revalidateTag(tags) {
+    // Implement tag-based invalidation
+    // This requires tracking which keys have which tags
+  }
+};
+```
+#### S3 Cache Handler Example
+```js
+// cache-handler.js
+const {
+  S3Client,
+  GetObjectCommand,
+  PutObjectCommand,
+} = require("@aws-sdk/client-s3");
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+const BUCKET = process.env.CACHE_BUCKET;
+module.exports = class CacheHandler {
+  async get(key) {
+    try {
+      const response = await s3.send(
+        new GetObjectCommand({
+          Bucket: BUCKET,
+          Key: `cache/${key}`,
+        }),
+      );
+      const body = await response.Body.transformToString();
+      return JSON.parse(body);
+    } catch (err) {
+      if (err.name === "NoSuchKey") return null;
+      throw err;
+    }
+  }
+  async set(key, data, ctx) {
+    await s3.send(
+      new PutObjectCommand({
+        Bucket: BUCKET,
+        Key: `cache/${key}`,
+        Body: JSON.stringify({
+          value: data,
+          lastModified: Date.now(),
+        }),
+        ContentType: "application/json",
+      }),
+    );
+  }
+};
+```
+## What Works vs What Needs Setup
+| Feature              | Single Instance | Multi-Instance      | Notes                       |
+| -------------------- | --------------- | ------------------- | --------------------------- |
+| SSR                  | Yes             | Yes                 | No special setup            |
+| SSG                  | Yes             | Yes                 | Built at deploy time        |
+| ISR                  | Yes             | Needs cache handler | Filesystem cache breaks     |
+| Image Optimization   | Yes             | Yes                 | CPU-intensive, consider CDN |
+| Middleware           | Yes             | Yes                 | Runs on Node.js             |
+| Edge Runtime         | Limited         | Limited             | Some features Node-only     |
+| `revalidatePath/Tag` | Yes             | Needs cache handler | Must share cache            |
+| `next/font`          | Yes             | Yes                 | Fonts bundled at build      |
+| Draft Mode           | Yes             | Yes                 | Cookie-based                |
+## Image Optimization
+Next.js Image Optimization works out of the box but is CPU-intensive.
+### Option 1: Built-in (Simple)
+Works automatically, but consider:
+- Set `deviceSizes` and `imageSizes` in config to limit variants
+- Use `minimumCacheTTL` to reduce regeneration
+```js
+// next.config.js
+module.exports = {
+  images: {
+    minimumCacheTTL: 60 * 60 * 24, // 24 hours
+    deviceSizes: [640, 750, 1080, 1920], // Limit sizes
+  },
+};
+```
+### Option 2: External Loader (Recommended for Scale)
+Offload to Cloudinary, Imgix, or similar:
+```js
+// next.config.js
+module.exports = {
+  images: {
+    loader: "custom",
+    loaderFile: "./lib/image-loader.js",
+  },
+};
+```
+```js
+// lib/image-loader.js
+export default function cloudinaryLoader({ src, width, quality }) {
+  const params = ["f_auto", "c_limit", `w_${width}`, `q_${quality || "auto"}`];
+  return `https://res.cloudinary.com/demo/image/upload/${params.join(",")}${src}`;
+}
+```
+## Environment Variables
+### Build-time vs Runtime
+```js
+// Available at build time only (baked into bundle)
+NEXT_PUBLIC_API_URL=https://api.example.com
+// Available at runtime (server-side only)
+DATABASE_URL=postgresql://...
+API_SECRET=...
+```
+### Runtime Configuration
+For truly dynamic config, don't use `NEXT_PUBLIC_*`. Instead:
+```tsx
+// app/api/config/route.ts
+export async function GET() {
+  return Response.json({
+    apiUrl: process.env.API_URL,
+    features: process.env.FEATURES?.split(","),
+  });
+}
+```
+## OpenNext: Serverless Without Vercel
+[OpenNext](https://open-next.js.org/) adapts Next.js for AWS Lambda, Cloudflare Workers, etc.
+```bash
+npx create-sst@latest
+# or
+npx @opennextjs/aws build
+```
+Supports:
+- AWS Lambda + CloudFront
+- Cloudflare Workers
+- Netlify Functions
+- Deno Deploy
+## Health Check Endpoint
+Always include a health check for load balancers:
+```tsx
+// app/api/health/route.ts
+export async function GET() {
+  try {
+    // Optional: check database connection
+    // await db.$queryRaw`SELECT 1`;
+    return Response.json({ status: "healthy" }, { status: 200 });
+  } catch (error) {
+    return Response.json({ status: "unhealthy" }, { status: 503 });
+  }
+}
+```
+## Pre-Deployment Checklist
+1. **Build locally first**: `npm run build` - catch errors before deploy
+2. **Test standalone output**: `node .next/standalone/server.js`
+3. **Set `output: 'standalone'`** for Docker
+4. **Configure cache handler** for multi-instance ISR
+5. **Set `HOSTNAME="0.0.0.0"`** for containers
+6. **Copy `public/` and `.next/static/`** - not included in standalone
+7. **Add health check endpoint**
+8. **Test ISR revalidation** after deployment
+9. **Monitor memory usage** - Node.js defaults may need tuning
+## Testing Cache Handler
+**Critical**: Test your cache handler on every Next.js upgrade:
+```bash
+# Start multiple instances
+PORT=3001 node .next/standalone/server.js &
+PORT=3002 node .next/standalone/server.js &
+# Trigger ISR revalidation
+curl http://localhost:3001/api/revalidate?path=/posts
+# Verify both instances see the update
+curl http://localhost:3001/posts
+curl http://localhost:3002/posts
+# Should return identical content
+```

package/.merlin-core/skills/general/next-best-practices/references/suspense-boundaries.md ADDED Viewed

@@ -0,0 +1,67 @@
+# Suspense Boundaries
+Client hooks that cause CSR bailout without Suspense boundaries.
+## useSearchParams
+Always requires Suspense boundary in static routes. Without it, the entire page becomes client-side rendered.
+```tsx
+// Bad: Entire page becomes CSR
+"use client";
+import { useSearchParams } from "next/navigation";
+export default function SearchBar() {
+  const searchParams = useSearchParams();
+  return <div>Query: {searchParams.get("q")}</div>;
+}
+```
+```tsx
+// Good: Wrap in Suspense
+import { Suspense } from "react";
+import SearchBar from "./search-bar";
+export default function Page() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <SearchBar />
+    </Suspense>
+  );
+}
+```
+## usePathname
+Requires Suspense boundary when route has dynamic parameters.
+```tsx
+// In dynamic route [slug]
+// Bad: No Suspense
+"use client";
+import { usePathname } from "next/navigation";
+export function Breadcrumb() {
+  const pathname = usePathname();
+  return <nav>{pathname}</nav>;
+}
+```
+```tsx
+// Good: Wrap in Suspense
+<Suspense fallback={<BreadcrumbSkeleton />}>
+  <Breadcrumb />
+</Suspense>
+```
+If you use `generateStaticParams`, Suspense is optional.
+## Quick Reference
+| Hook                | Suspense Required    |
+| ------------------- | -------------------- |
+| `useSearchParams()` | Yes                  |
+| `usePathname()`     | Yes (dynamic routes) |
+| `useParams()`       | No                   |
+| `useRouter()`       | No                   |

package/.merlin-core/skills/general/next-steps/SKILL.md ADDED Viewed

@@ -0,0 +1,43 @@
+---
+name: next-steps
+description: After completing any task, suggest 1-5 logical next steps. Helps maintain momentum and surfaces non-obvious follow-up work.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: []
+  tool_reminders: [After reporting RESULT, always append a ## Next Steps section with 1-5 actionable suggestions]
+---
+## Next Steps Protocol
+After completing any task and reporting your `[RESULT:]`, always append a `## Next Steps` section suggesting 1-5 logical follow-up actions.
+## Suggestion Categories
+Organize suggestions by category, prioritized by impact:
+1. **Follow-up** — Direct continuations of the current work (e.g., "Implement the remaining 2 endpoints")
+2. **Test** — Testing actions not yet performed (e.g., "Run integration tests for the new service")
+3. **Polish** — Quality improvements (e.g., "Add error handling for edge case X")
+4. **Document** — Documentation needs (e.g., "Update the API docs with new endpoints")
+5. **Deploy** — Deployment or release steps (e.g., "Create a PR for review")
+## Format
+```
+## Next Steps
+1. **[Follow-up]** Implement pagination for the /users endpoint
+2. **[Test]** Add integration tests for the auth middleware
+3. **[Polish]** Extract the validation logic into a shared utility
+4. **[Deploy]** Run the QA pipeline and create a PR
+```
+## Rules
+- Suggest 1-5 steps; prefer fewer, more impactful suggestions over many trivial ones
+- Each suggestion must be specific and actionable — not vague ("improve code")
+- Consider what the user likely wants to do next based on the work just completed
+- Do NOT suggest steps that were already completed in the current task
+- If the task was a bug fix, always suggest adding a regression test

package/.merlin-core/skills/general/party-mode/SKILL.md ADDED Viewed

@@ -0,0 +1,57 @@
+---
+name: party-mode
+description: Multi-agent collaboration sessions for complex decisions and design reviews
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [multi-agent, roundtable, collaborate, group-decision]
+---
+# Party Mode
+Multi-agent collaboration sessions where agents interact in rounds until convergence or maximum rounds reached. Inspired by the BMAD multi-persona approach.
+## When to Use Party Mode
+- **Design decisions** requiring multiple perspectives (architect + dev + qa)
+- **Architecture trade-offs** where different stakeholders have competing concerns
+- **Code review sessions** where multiple reviewers provide independent assessments
+- **Brainstorming** where creative input from different roles is valuable
+- **Risk assessment** where ops, security, and product perspectives matter
+## Party Lifecycle
+1. **Create** — Define topic and invite agents
+2. **Round 1** — Each agent provides initial perspective independently
+3. **Round 2+** — Agents see previous contributions and build on/challenge them
+4. **Convergence** — Detected when majority of agents express agreement
+5. **Conclude** — Summary with recommendations and consensus status
+## Roles in Parties
+Each agent contributes from their domain expertise:
+- **architect** — System design, patterns, scalability
+- **dev** — Implementation feasibility, code complexity
+- **qa** — Testability, edge cases, quality risks
+- **devops** — Deployment, infrastructure, operations
+- **analyst** — Business requirements, user impact
+- **po** — Product priorities, stakeholder value
+## Configuration
+- **maxRounds:** Default 3, configurable per session
+- **agents:** Any combination of the 14 registered agents
+- **timeout:** Per-agent response timeout (default 5 min)
+## Usage
+```
+/party "Should we use microservices or monolith for the new auth system?" --agents architect,dev,devops
+/party "Review the proposed database schema" --agents architect,dev,data-engineer
+```
+## Output
+Party sessions produce structured summaries saved to `thoughts/shared/decisions/` including per-agent contributions, agreement analysis, and final recommendations.