@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/cursor/nuxt-layouts-pages/SKILL.md

@@ -0,0 +1,210 @@
+# Nuxt Layouts and Pages
+
+> Structure applications with file-based routing, named layouts, and per-page configuration via definePageMeta
+
+## When to Use
+
+- You are building out the route structure of a Nuxt application
+- You need multiple layouts (default, auth, dashboard) with different navigation or sidebar configurations
+- You want to configure page-level metadata, transitions, middleware, or keepAlive from within the page SFC
+- You are implementing nested routes or catch-all pages
+
+## Instructions
+
+**Pages — file-based routing:**
+
+1. Create `.vue` files in `pages/` — the path maps directly to the URL route:
+
+```
+pages/
+  index.vue          → /
+  about.vue          → /about
+  users/
+    index.vue        → /users
+    [id].vue         → /users/:id
+  [...slug].vue      → /* (catch-all)
+```
+
+2. Place `<NuxtPage />` in `app.vue` (or within a layout) to render the active page:
+
+```html
+<!-- app.vue -->
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+3. Access route params with `useRoute`:
+
+```typescript
+const route = useRoute();
+const id = route.params.id; // typed if using typed routes
+```
+
+**Layouts:**
+
+4. Create layouts in `layouts/`. The `default.vue` layout is applied automatically. Named layouts require explicit opt-in:
+
+```html
+<!-- layouts/default.vue -->
+<template>
+  <div>
+    <AppHeader />
+    <slot />
+    <AppFooter />
+  </div>
+</template>
+```
+
+```html
+<!-- layouts/dashboard.vue -->
+<template>
+  <div class="dashboard-grid">
+    <DashboardSidebar />
+    <main><slot /></main>
+  </div>
+</template>
+```
+
+5. Apply a named layout from a page using `definePageMeta`:
+
+```typescript
+// pages/admin/users.vue
+<script setup lang="ts">
+definePageMeta({
+  layout: 'dashboard'
+})
+</script>
+```
+
+6. Disable the layout entirely for specific pages (e.g., a full-screen login page):
+
+```typescript
+definePageMeta({ layout: false });
+```
+
+7. Switch layouts dynamically at runtime using `setPageLayout`:
+
+```typescript
+const { setPageLayout } = useLayout();
+setPageLayout('minimal');
+```
+
+**definePageMeta — per-page configuration:**
+
+8. Use `definePageMeta` for all page-level config — it is a compiler macro and must be called at the top level of `<script setup>`:
+
+```typescript
+definePageMeta({
+  layout: 'dashboard',
+  middleware: ['auth', 'role-admin'],
+  keepalive: true,
+  pageTransition: { name: 'slide-left', mode: 'out-in' },
+  title: 'User Management', // custom meta field
+});
+```
+
+**Page transitions:**
+
+9. Configure route transitions globally in `nuxt.config.ts` or per-page:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  app: {
+    pageTransition: { name: 'page', mode: 'out-in' },
+  },
+});
+```
+
+```css
+/* assets/transitions.css */
+.page-enter-active,
+.page-leave-active {
+  transition: opacity 0.3s;
+}
+.page-enter-from,
+.page-leave-to {
+  opacity: 0;
+}
+```
+
+## Details
+
+**Nested routes:**
+
+Create a parent page component alongside a subdirectory of the same name to implement nested routing. The parent must include `<NuxtPage />` to render the child:
+
+```
+pages/
+  parent.vue         → /parent  (contains <NuxtPage />)
+  parent/
+    child.vue        → /parent/child
+```
+
+**Optional catch-all:**
+
+`[[...slug]].vue` matches both `/` (optional slug) and `/a/b/c`. Useful for CMS-driven routing.
+
+**Typed routes:**
+
+Enable `experimental.typedPages` in `nuxt.config.ts` to get full TypeScript inference for route params and query strings:
+
+```typescript
+export default defineNuxtConfig({
+  experimental: { typedPages: true },
+});
+```
+
+**NuxtPage key — force remount on param change:**
+
+By default, navigating between `/users/1` and `/users/2` reuses the page component. Force a remount with a `:key` binding:
+
+```html
+<NuxtPage :page-key="route => route.fullPath" />
+```
+
+**Layout transitions vs. page transitions:**
+
+- `pageTransition` — animates the `<NuxtPage />` slot content
+- `layoutTransition` — animates the outer `<NuxtLayout />` when switching layouts
+
+Both accept Vue transition options or a boolean.
+
+**Custom page meta:**
+
+Extend `definePageMeta` with custom fields by augmenting the `PageMeta` interface:
+
+```typescript
+// types/nuxt.d.ts
+declare module '#app' {
+  interface PageMeta {
+    title?: string;
+    requiresRole?: string;
+  }
+}
+```
+
+Then read it in middleware: `to.meta.requiresRole`.
+
+## Source
+
+https://nuxt.com/docs/guide/directory-structure/pages
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/nuxt-layouts-pages/skill.yaml

@@ -0,0 +1,42 @@
+name: nuxt-layouts-pages
+version: '1.0.0'
+description: Structure Nuxt apps with file-based pages, named layouts, and definePageMeta
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'nuxt.config.*'
+  - '**/pages/**/*.vue'
+  - '**/layouts/**/*.vue'
+  - '**/app.vue'
+related_skills:
+  - nuxt-middleware-pattern
+  - nuxt-composables-pattern
+  - nuxt-auto-imports
+stack_signals:
+  - nuxt
+  - vue
+  - typescript
+keywords:
+  - pages
+  - layouts
+  - NuxtPage
+  - NuxtLayout
+  - definePageMeta
+  - file-based-routing
+  - transitions
+metadata:
+  author: nuxt.com
+  upstream: 'nuxt.com/docs/guide/directory-structure/pages'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/nuxt-middleware-pattern/SKILL.md

@@ -0,0 +1,164 @@
+# Nuxt Middleware Pattern
+
+> Protect routes, redirect unauthenticated users, and transform navigation using Nuxt's layered middleware system
+
+## When to Use
+
+- You need to redirect unauthenticated or unauthorized users before a page renders
+- You want to run logic on every navigation (analytics, breadcrumb updates, locale detection)
+- You need server-side request interception (rate limiting, auth header validation, logging)
+- You are implementing per-page access control using `definePageMeta`
+
+## Instructions
+
+**Route middleware (client + server navigation guards):**
+
+1. Create files in `middleware/` — they run during navigation, before the target page component renders.
+2. Use `navigateTo` to redirect or `abortNavigation` to cancel:
+
+```typescript
+// middleware/auth.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const { isAuthenticated } = useAuth();
+  if (!isAuthenticated.value) {
+    return navigateTo('/login');
+  }
+});
+```
+
+3. Apply middleware to a page with `definePageMeta`:
+
+```typescript
+// pages/dashboard.vue
+<script setup lang="ts">
+definePageMeta({
+  middleware: 'auth'           // single
+  // middleware: ['auth', 'role-check']  // multiple, runs in order
+})
+</script>
+```
+
+4. Use global middleware by naming the file with a `.global` suffix — it runs on every route automatically:
+
+```typescript
+// middleware/analytics.global.ts
+export default defineNuxtRouteMiddleware((to) => {
+  trackPageView(to.fullPath);
+});
+```
+
+5. Define inline anonymous middleware directly in `definePageMeta` for one-off page guards:
+
+```typescript
+definePageMeta({
+  middleware: [
+    async function (to, from) {
+      const allowed = await checkPermission(to.params.id);
+      if (!allowed) abortNavigation(createError({ statusCode: 403 }));
+    },
+  ],
+});
+```
+
+**Server middleware (HTTP-level interception):**
+
+6. Create files in `server/middleware/` — these run on every incoming HTTP request before any server route:
+
+```typescript
+// server/middleware/cors.ts
+export default defineEventHandler((event) => {
+  setHeader(event, 'Access-Control-Allow-Origin', '*');
+  setHeader(event, 'Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE');
+});
+```
+
+7. Use `event.context` to pass data from server middleware to route handlers:
+
+```typescript
+// server/middleware/auth.ts
+export default defineEventHandler(async (event) => {
+  const token = getCookie(event, 'auth_token');
+  if (token) {
+    event.context.user = await verifyToken(token);
+  }
+});
+```
+
+**Auth pattern — combining both layers:**
+
+```typescript
+// middleware/auth.ts (client-side guard)
+export default defineNuxtRouteMiddleware(() => {
+  const user = useSupabaseUser();
+  if (!user.value) return navigateTo('/login');
+});
+
+// server/api/protected.get.ts (server-side validation)
+export default defineEventHandler((event) => {
+  if (!event.context.user) throw createError({ statusCode: 401 });
+  return { secret: 'data' };
+});
+```
+
+## Details
+
+Nuxt has two distinct middleware layers that serve different purposes:
+
+**Route middleware** runs in the Vue Router navigation cycle on the client (and during SSR navigation). It has access to the full Nuxt composable context (`useNuxtApp`, `useRuntimeConfig`, etc.) and is the right place for UI-level auth checks, redirects, and analytics.
+
+**Server middleware** runs in Nitro's HTTP pipeline before any route handler. It operates on raw H3 events with no access to Vue reactivity. This is where you handle CORS, rate limiting, auth token validation, and request logging.
+
+**Execution order for route middleware:**
+
+1. Global middleware (alphabetical by filename)
+2. Page-level middleware (in the order listed in `definePageMeta`)
+
+**SSR vs. CSR behavior:**
+
+Route middleware runs on both server (during initial SSR render) and client (on subsequent navigations). Guard against environment-specific APIs:
+
+```typescript
+export default defineNuxtRouteMiddleware(() => {
+  if (import.meta.server) return; // skip on server
+  initClientOnlyAnalytics();
+});
+```
+
+**Redirecting with status codes:**
+
+```typescript
+return navigateTo('/new-path', { redirectCode: 301 });
+```
+
+**Error handling in middleware:**
+
+Throw errors to trigger the Nuxt error page:
+
+```typescript
+throw createError({ statusCode: 403, statusMessage: 'Forbidden' });
+```
+
+**When NOT to use:**
+
+- Data fetching that belongs in `useAsyncData` — middleware is for guards, not loading page data
+- Server middleware for client-only concerns (session UI state, theme, etc.)
+
+## Source
+
+https://nuxt.com/docs/guide/directory-structure/middleware
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/nuxt-middleware-pattern/skill.yaml

@@ -0,0 +1,41 @@
+name: nuxt-middleware-pattern
+version: '1.0.0'
+description: Guard and transform routes using Nuxt route middleware and server middleware
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'nuxt.config.*'
+  - '**/middleware/**'
+  - '**/server/middleware/**'
+  - '**/pages/**/*.vue'
+related_skills:
+  - nuxt-server-routes
+  - nuxt-composables-pattern
+  - nuxt-layouts-pages
+stack_signals:
+  - nuxt
+  - vue
+  - typescript
+keywords:
+  - middleware
+  - route-middleware
+  - server-middleware
+  - auth
+  - navigation-guards
+  - definePageMeta
+metadata:
+  author: nuxt.com
+  upstream: 'nuxt.com/docs/guide/directory-structure/middleware'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/nuxt-modules-pattern/SKILL.md

@@ -0,0 +1,193 @@
+# Nuxt Modules Pattern
+
+> Extend Nuxt at build time with defineNuxtModule — add components, imports, plugins, and server routes programmatically
+
+## When to Use
+
+- You are building a reusable Nuxt integration (a library, a UI kit, a third-party service wrapper)
+- You need to programmatically register components or composables based on configuration
+- You want to modify the Nitro or Vite configuration from an installable package
+- You are extracting shared Nuxt configuration from a monorepo into a local module
+
+## Instructions
+
+1. Create a module using `defineNuxtModule` from `@nuxt/kit`:
+
+```typescript
+// modules/my-feature/index.ts
+import { defineNuxtModule, addComponent, addImports, createResolver } from '@nuxt/kit';
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-feature',
+    configKey: 'myFeature',
+  },
+  defaults: {
+    enabled: true,
+    prefix: 'My',
+  },
+  setup(options, nuxt) {
+    if (!options.enabled) return;
+
+    const { resolve } = createResolver(import.meta.url);
+
+    // Register a component
+    addComponent({
+      name: `${options.prefix}Button`,
+      filePath: resolve('./runtime/components/Button.vue'),
+    });
+
+    // Register a composable
+    addImports({
+      name: 'useMyFeature',
+      as: 'useMyFeature',
+      from: resolve('./runtime/composables/useMyFeature'),
+    });
+  },
+});
+```
+
+2. Register the module in `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['./modules/my-feature'],
+  myFeature: {
+    prefix: 'Acme',
+  },
+});
+```
+
+3. Add a Nuxt plugin from within a module using `addPlugin`:
+
+```typescript
+import { addPlugin, createResolver } from '@nuxt/kit'
+
+setup(options, nuxt) {
+  const { resolve } = createResolver(import.meta.url)
+  addPlugin(resolve('./runtime/plugin'))
+}
+```
+
+4. Extend Nitro configuration from a module (e.g., add server routes, set CORS):
+
+```typescript
+setup(options, nuxt) {
+  nuxt.hook('nitro:config', (nitroConfig) => {
+    nitroConfig.handlers = nitroConfig.handlers || []
+    nitroConfig.handlers.push({
+      route: '/api/my-feature',
+      handler: resolve('./runtime/server/api/my-feature')
+    })
+  })
+}
+```
+
+5. Extend Vite configuration from a module:
+
+```typescript
+setup(options, nuxt) {
+  nuxt.hook('vite:extendConfig', (viteConfig) => {
+    viteConfig.plugins = viteConfig.plugins || []
+    viteConfig.plugins.push(myVitePlugin())
+  })
+}
+```
+
+6. Add type declarations from a module:
+
+```typescript
+import { addTypeTemplate } from '@nuxt/kit'
+
+setup(options, nuxt) {
+  addTypeTemplate({
+    filename: 'types/my-feature.d.ts',
+    getContents: () => `
+      declare module '#app' {
+        interface NuxtApp {
+          $myFeature: MyFeatureClient
+        }
+      }
+      export {}
+    `
+  })
+}
+```
+
+7. Use `nuxt.options.runtimeConfig` to expose module options to runtime:
+
+```typescript
+setup(options, nuxt) {
+  nuxt.options.runtimeConfig.public.myFeature = {
+    apiUrl: options.apiUrl
+  }
+}
+```
+
+## Details
+
+**Module vs. plugin:**
+
+Modules run at **build time** inside the Nuxt CLI process. Plugins run at **runtime** inside the Vite/Nitro bundle. Use modules when you need to modify the build, add files, or configure other build tools. Use plugins for runtime behavior.
+
+**`@nuxt/kit` utilities reference:**
+
+| Utility            | Purpose                                           |
+| ------------------ | ------------------------------------------------- |
+| `addComponent`     | Register a Vue component with auto-import         |
+| `addImports`       | Register a composable or utility with auto-import |
+| `addPlugin`        | Add a runtime Nuxt plugin                         |
+| `addServerHandler` | Register a Nitro route handler                    |
+| `addTemplate`      | Generate a virtual file in `.nuxt/`               |
+| `addTypeTemplate`  | Generate a `.d.ts` declaration file               |
+| `createResolver`   | Resolve file paths relative to the module         |
+| `installModule`    | Install another Nuxt module from within a module  |
+
+**Module hooks:**
+
+Nuxt exposes lifecycle hooks that modules can tap into:
+
+- `nuxt:ready` — all modules have loaded
+- `nitro:config` — before Nitro is built
+- `vite:extendConfig` — before Vite is built
+- `components:dirs` — extend component scan directories
+- `imports:dirs` — extend auto-import scan directories
+- `pages:extend` — add or modify pages programmatically
+
+**Publishing as a package:**
+
+Follow the `nuxt-module-builder` convention for publishable modules. The `@nuxt/module-builder` CLI scaffolds the correct build config and exports.
+
+**Local modules in monorepos:**
+
+For workspace-internal modules, use a relative path in `modules`:
+
+```typescript
+modules: ['../../packages/ui/nuxt.ts'];
+```
+
+**When NOT to use:**
+
+- Runtime-only concerns — use a plugin
+- Per-component logic — use a composable
+- Simple configuration — just extend `nuxt.config.ts` directly
+
+## Source
+
+https://nuxt.com/docs/guide/going-further/modules
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/nuxt-modules-pattern/skill.yaml

@@ -0,0 +1,40 @@
+name: nuxt-modules-pattern
+version: '1.0.0'
+description: Build and configure Nuxt modules using defineNuxtModule, addComponent, and module hooks
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'nuxt.config.*'
+  - '**/modules/**'
+related_skills:
+  - nuxt-plugins-pattern
+  - nuxt-auto-imports
+  - nuxt-composables-pattern
+stack_signals:
+  - nuxt
+  - vue
+  - typescript
+keywords:
+  - modules
+  - defineNuxtModule
+  - addComponent
+  - addImports
+  - module-hooks
+  - build-time
+  - nuxt-kit
+metadata:
+  author: nuxt.com
+  upstream: 'nuxt.com/docs/guide/going-further/modules'
+state:
+  persistent: false
+  files: []
+depends_on: []