npm - @mrciphersmith/keryx - Versions diffs - 0.3.0 → 0.3.2 - Mend

@mrciphersmith/keryx 0.3.0 → 0.3.2

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 (93) hide show

package/src/gdskills/bundled/stacks/nextjs-nuxt/skills/nextjs-nuxt-upgrade-migration/SKILL.md ADDED Viewed

@@ -0,0 +1,134 @@
+---
+name: nextjs-nuxt-upgrade-migration
+description: "Use when migrating a Next.js project from the Pages Router to the App Router, upgrading a Next.js major version, or migrating a Nuxt 2 project to Nuxt 3+ (Options API to Composition API, the Vuex-to-Pinia move, module/plugin API changes). Covers rewriting data-fetching (getServerSideProps/getStaticProps to Server Components and route rendering config; asyncData/fetch to useAsyncData/useFetch), routing conventions, and rendering-mode equivalents between the old and new APIs. Not for a same-version bug fix or new feature (use nextjs-nuxt-implementation/nextjs-nuxt-build-fix), and not for a plain React/Vue version bump with no meta-framework routing change (use react-upgrade-migration or the vue pack's migration skill)."
+triggers:
+  - "migrate this Next.js app from pages router to app router"
+  - "upgrade this Next.js project to the latest major version"
+  - "migrate this Nuxt 2 project to Nuxt 3"
+  - "convert getServerSideProps to the app router equivalent"
+  - "move this Nuxt 2 asyncData to useAsyncData"
+  - "migrate Vuex store to Pinia in this Nuxt project"
+  - "replace this Options API component with script setup during the Nuxt 3 migration"
+metadata:
+  origin: authored
+  category: migrate
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+# Next.js / Nuxt upgrade & migration
+Migrate a Next.js project between the Pages Router and App Router (or
+between major versions), or a Nuxt 2 project to Nuxt 3+. Covers rewriting
+the old data-fetching/rendering APIs to their current equivalents. See
+`rules/patterns.mdc` for the target-state idiom this migration moves
+toward.
+## Workflow
+### Step 1: Establish the current and target state
+- Confirm the exact starting point (Next.js Pages Router version, or Nuxt
+  2 with which major module versions) and the target (App Router on
+  which Next.js version, or Nuxt 3/4) — the concrete API mapping differs
+  by version, so check the project's `package.json` before assuming a
+  mapping.
+- Migrate route-by-route or module-by-module, not the whole app in one
+  pass — both frameworks support the old and new router/API coexisting
+  during a transition (Next.js: `pages/` and `app/` side by side; Nuxt:
+  incremental Nuxt Bridge or a full-rewrite branch per module), so land
+  working, tested increments.
+### Step 2: Migrate Next.js data-fetching and routing (Pages Router -> App Router)
+- `getServerSideProps`/`getStaticProps` in a page -> fetch directly in
+  the now-Server Component (`app/.../page.tsx`); the per-request vs.
+  static choice becomes the route's default (dynamic) vs. `export const
+  revalidate = <seconds>` (ISR) rather than a separate exported function.
+- `getStaticPaths` -> `generateStaticParams` in the App Router page.
+- `_app.tsx`/`_document.tsx` -> `app/layout.tsx` (root layout) plus
+  nested `layout.tsx` files per route segment.
+- `next/head`'s `<Head>` -> the `metadata` export or `generateMetadata`
+  function in `page.tsx`/`layout.tsx`.
+- An API route under `pages/api/*.ts` -> a Route Handler under
+  `app/api/.../route.ts` exporting named HTTP method functions
+  (`GET`/`POST`/etc.) instead of a single default-exported handler.
+- Any component using `useState`/`useEffect`/browser APIs needs an
+  explicit `'use client'` once moved into `app/` — it was implicitly
+  client-rendered before; the App Router defaults to server rendering.
+### Step 3: Migrate Nuxt 2 to Nuxt 3+
+- Options API components (`export default { data() {...}, methods:
+  {...} }`) -> `<script setup lang="ts">` with `ref`/`reactive`/
+  `computed`/defined props — rewrite behavior, don't just wrap the old
+  object export.
+- `asyncData`/`fetch` (Nuxt 2 page hooks) -> `useAsyncData`/`useFetch`
+  called in `<script setup>`.
+- Vuex store modules -> Pinia stores (`defineStore`) — Nuxt 3 has no
+  built-in Vuex integration; a large store migrates incrementally,
+  module by module, with both coexisting only as a deliberate bridge
+  step, not a long-term end state.
+- `nuxt.config.js` module/plugin registration syntax changed
+  substantially between Nuxt 2 and 3 — re-check each module's own current
+  docs for its Nuxt 3 registration shape rather than assuming the old
+  config key still works.
+- Middleware (`middleware/*.js` global-by-filename in Nuxt 2) ->
+  `defineNuxtRouteMiddleware` in `middleware/`, explicitly referenced per
+  page via `definePageMeta({ middleware: [...] })` unless it is global.
+### Step 4: Verify each migrated increment
+- Run the target framework's build/typecheck after each route/module
+  migrates, not only at the end — a broken increment is much cheaper to
+  isolate immediately than after the whole app has moved.
+- Confirm the migrated route's rendering mode (static/dynamic/ISR, or
+  Nuxt's `ssr`/`routeRules`) matches what the original page actually
+  needed, not just "still compiles" — a migration can silently flip a
+  page from dynamic to accidentally-static or vice versa.
+### Step 5: Report
+State what moved, the API mapping applied to each piece, and what still
+needs a follow-up pass (e.g. remaining Pages Router routes, remaining
+Vuex modules) rather than claiming the whole migration complete when only
+part landed.
+## Rules
+- Follow `rules/patterns.mdc` for the target Server/Client boundary,
+  rendering-mode, and data-fetching idiom each migrated piece should end
+  up in.
+- Migrate incrementally with the old and new systems coexisting during
+  the transition; never a single unreviewable mass-rewrite commit.
+- NEVER leave a migrated component silently missing `'use client'` when
+  it uses state/effects/browser APIs — the App Router's default flipped
+  from the Pages Router's implicit client rendering.
+- NEVER migrate a Vuex module to Pinia by wrapping the old store object
+  unchanged inside `defineStore` — rewrite it to Pinia's actual API
+  (state/getters/actions as the store's own functions), not a shim.
+## Red Flags
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll migrate the whole pages/ directory to app/ in one commit, faster than route by route" | A single mass-rewrite is unreviewable and all-or-nothing to roll back; migrate and verify route by route instead |
+| "This component doesn't obviously use state, I'll skip adding 'use client' and see if the build complains" | The App Router's build error for a missing boundary is not guaranteed to catch every case (e.g. an indirect browser-API use); check explicitly rather than relying on the compiler to catch it |
+| "I'll wrap the old Vuex module object inside defineStore so both APIs sort of work" | Produces a store that satisfies neither Vuex's nor Pinia's actual API contract; rewrite to Pinia's state/getters/actions shape |
+| "The old getServerSideProps page worked fine, I'll just call it from inside the new Server Component instead of rewriting the fetch" | Keeps a Pages Router API alive inside App Router code instead of completing the actual migration to the framework's current data-fetching model |
+## Verification
+Do not report a migrated piece done until:
+- The target framework's build/typecheck passes for the migrated
+  route/module.
+- Every migrated component that needs client interactivity has an
+  explicit `'use client'` (Next.js) or is confirmed to run correctly
+  under Nuxt 3's Composition API context (Nuxt).
+- The migrated route's rendering mode matches the original's actual data
+  freshness need, checked explicitly, not assumed from "it still
+  builds".
+- The report names exactly what migrated and what remains, not a blanket
+  "migration complete" for a partial pass.

package/src/gdskills/bundled/stacks/nextjs-nuxt/skills/nextjs-nuxt-upgrade-migration/evals.json ADDED Viewed

@@ -0,0 +1,76 @@
+{
+  "triggers": {
+    "positive": [
+      "This Next.js app still uses the pages router everywhere, I need to migrate it over to the app router, where should I begin?",
+      "Upgrade this Next.js project's pages/api routes to app router route handlers",
+      "This project is still running on the old Nuxt 2 major version and we need to bring it forward to Nuxt 3, what does that upgrade actually involve?",
+      "This page currently uses getServerSideProps for its data fetching, how do I convert that to the app router equivalent once we migrate it?",
+      "As part of bringing this page up to Nuxt 3, its old asyncData data-fetching call needs to become the new composable-based equivalent, how do I do that conversion?",
+      "As part of our Nuxt 3 upgrade, I need to migrate this store from Vuex over to Pinia, what does that conversion involve?",
+      "I still have a component built with the old Options API, and I want it rewritten to use script setup as part of moving to Nuxt 3, how should I approach that?"
+    ],
+    "negative": [
+      "Add a brand new page to this already-on-app-router Next.js project",
+      "Review this Next.js server action for auth issues",
+      "Write a test for this Nuxt composable",
+      "Fix this build error blocking next build right now",
+      "Upgrade this plain React 18 app to React 19 with no routing framework involved",
+      "Migrate this Python 2 script to Python 3 syntax"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "getserversideprops-to-app-router",
+      "prompt": "I have a Next.js Pages Router page using getServerSideProps to fetch an order by ID before render. How do I migrate this to the App Router?",
+      "strictness": "high",
+      "expected_behavior": [
+        { "grader": "regex", "value": "getServerSideProps" },
+        {
+          "grader": "judge",
+          "rubric": "A correct answer replaces getServerSideProps with fetching the order data directly inside the App Router page component (a Server Component, app/.../page.tsx), reading the route param instead of context.params, and notes that any interactive part of the old page needs its own 'use client' component once moved.",
+          "pass_criteria": [
+            "States that data fetching moves from getServerSideProps into the page component's own body (an async Server Component in app/.../page.tsx) rather than a separate exported function",
+            "Names that the route param (previously from context.params in getServerSideProps) is now read from the page component's own params argument",
+            "Notes that any interactive UI on the old page (event handlers, useState) needs to be extracted into a component with its own 'use client' directive, since the App Router defaults to server rendering"
+          ],
+          "fail_criteria": [
+            "Recommends keeping getServerSideProps as-is and calling it from inside the new App Router page as a workaround, instead of rewriting the fetch into the Server Component itself"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Move the fetch logic directly into the App Router page component. Where you had:\n\nexport async function getServerSideProps(context) {\n  const order = await getOrder(context.params.id);\n  return { props: { order } };\n}\n\n...you now write app/orders/[id]/page.tsx as an async Server Component that fetches inline and reads the route param from its own `params` prop instead of context.params:\n\nexport default async function OrderPage({ params }: { params: { id: string } }) {\n  const order = await getOrder(params.id);\n  return <OrderView order={order} />;\n}\n\nThis renders per-request by default, matching getServerSideProps's original behavior. If the old page also had client-side interactivity (a button, local state), extract that into its own component file with 'use client' at the top, since the App Router page itself is now a Server Component by default and won't support hooks directly.",
+        "known_wrong": "Simplest migration: keep the old getServerSideProps function exactly as it is in a separate file, and just call it manually from inside the new app/orders/[id]/page.tsx to get the props, then render the same way you did before.",
+        "vague": "You'll need to move the data fetching into the new page component somehow and adjust how you read the route parameter.",
+        "subtle_wrong": "Move the fetch into the page component like this: async function OrderPage({ params }) { const order = await getOrder(params.id); return <OrderView order={order} /> } -- good so far, but I'd also add 'use client' to the top of this same page file just to be safe, in case any part of OrderView needs client-side hooks, rather than tracking down exactly which nested component needs it."
+      },
+      "anti_patterns": []
+    },
+    {
+      "id": "pinia-not-vuex-wrapper",
+      "prompt": "I'm migrating a Nuxt 2 project with a Vuex store module to Nuxt 3. Should I just wrap the existing Vuex module inside Pinia's defineStore to save time?",
+      "strictness": "high",
+      "expected_behavior": [
+        { "grader": "regex", "value": "defineStore" },
+        {
+          "grader": "judge",
+          "rubric": "A correct answer says no -- wrapping the old Vuex module object unchanged inside defineStore does not satisfy Pinia's actual API, and the store should be rewritten to Pinia's state/getters/actions shape instead.",
+          "pass_criteria": [
+            "States clearly that wrapping the Vuex module object as-is inside defineStore is not a valid approach",
+            "Describes rewriting the store to Pinia's actual shape: a state function/object, getters, and actions as the store's own methods, replacing Vuex's mutations/actions/getters pattern"
+          ],
+          "fail_criteria": [
+            "Endorses wrapping the existing Vuex module object directly inside defineStore as a time-saving shortcut -- naming this only to reject it is not a failure"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "No, don't just wrap the Vuex module inside defineStore -- Pinia has a genuinely different shape and Vuex's mutations/actions/getters object won't function correctly just dropped into Pinia's API. Rewrite the module: Vuex's `state` becomes Pinia's `state: () => ({...})`, Vuex `getters` map directly to Pinia `getters`, and Vuex's `mutations` + `actions` combine into Pinia's single `actions` (since Pinia actions can mutate state directly, no separate mutation-commit step is needed). For example, a Vuex module with state.orders, a SET_ORDERS mutation, and a fetchOrders action that commits it becomes a Pinia store with state: () => ({ orders: [] }) and an actions.fetchOrders() that calls the API and does `this.orders = result` directly. It takes more effort than a wrapper, but a wrapper wouldn't actually work -- Pinia doesn't recognize Vuex's mutation-commit contract.",
+        "known_wrong": "Sure, just export the existing Vuex module object as the store option passed to defineStore -- that saves rewriting all the mutations and actions, and Pinia is flexible enough to handle it since they're both just state management libraries.",
+        "vague": "It's better to migrate the store properly to Pinia's own patterns rather than trying to shortcut it.",
+        "subtle_wrong": "You're right not to wrap it directly -- I'd rewrite the getters and state to Pinia's format, but keep the original Vuex mutations object as a plain helper object referenced from inside one catch-all Pinia action, so you don't have to convert every individual mutation into its own Pinia action right away."
+      },
+      "anti_patterns": []
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/vue/agent-refs.json ADDED Viewed

@@ -0,0 +1,4 @@
+{
+  "agents": [],
+  "note": "honest gate (flow 318, T13; attribution corrected in R1 review PR #719, minor-3): vue-build-fix fails -- falsePositive=1 (trigger-negative-1, \"fix this tsc error in a plain typescript service file\": a CROSS-pack collision with ts-js-node/nodejs-build-fix, not a same-pack near-miss) and its template-union-type-narrowing behavior scenario scores 0.4, below the 0.8 PACK_BEHAVIOR_PASS_FLOOR, even though every other vue skill (implementation, testing, code-review, vue2-to-vue3-migration) clears the gate cleanly. See src/gdskills/bundled/stacks/vue/governance/eval.json. Stays experimental; no generated agent pair."
+}