@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/claude-code/astro-routing-pattern/SKILL.md

@@ -0,0 +1,135 @@
+# Astro Routing Pattern
+
+> File-based routing maps your `src/pages/` directory structure to URLs — static, dynamic, and rest-parameter routes all follow the same filesystem convention.
+
+## When to Use
+
+- You are creating new pages or routes in an Astro project
+- You need dynamic routes (e.g., `/blog/[slug]`) and must implement `getStaticPaths()`
+- You want to use rest parameters for catch-all or paginated routes
+- You are configuring redirects, custom 404 pages, or route priority
+- You are moving from SSG to SSR and need to understand which routing behaviors change
+
+## Instructions
+
+1. Create files in `src/pages/` to define routes. The file path maps directly to the URL:
+   - `src/pages/index.astro` → `/`
+   - `src/pages/about.astro` → `/about`
+   - `src/pages/blog/index.astro` → `/blog`
+   - `src/pages/blog/first-post.astro` → `/blog/first-post`
+
+2. Use bracket syntax for dynamic route segments. The bracket name becomes the param key:
+   - `src/pages/blog/[slug].astro` → `/blog/:slug`
+   - `src/pages/[lang]/about.astro` → `/:lang/about`
+
+3. Implement `getStaticPaths()` in every dynamic route page used in SSG mode. It must return an array of `{ params }` objects:
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { getCollection } from 'astro:content';
+
+export async function getStaticPaths() {
+  const posts = await getCollection('blog');
+  return posts.map((post) => ({
+    params: { slug: post.slug },
+    props: { post },          // pass data to avoid re-fetching in frontmatter
+  }));
+}
+
+const { post } = Astro.props;
+const { Content } = await post.render();
+---
+<article>
+  <h1>{post.data.title}</h1>
+  <Content />
+</article>
+```
+
+4. Use rest parameters (`[...slug]`) for nested dynamic routes and catch-all paths:
+   - `src/pages/docs/[...slug].astro` matches `/docs/`, `/docs/guide`, `/docs/guide/intro`
+   - Access via `Astro.params.slug` — it will be `undefined` (root), `'guide'`, or `'guide/intro'`
+
+5. Implement pagination with `paginate()` inside `getStaticPaths()`:
+
+```typescript
+export async function getStaticPaths({ paginate }) {
+  const posts = await getCollection('blog');
+  const sorted = posts.sort((a, b) => b.data.pubDate - a.data.pubDate);
+  return paginate(sorted, { pageSize: 10 });
+}
+
+const { page } = Astro.props;
+// page.data: current page items
+// page.currentPage: page number (1-indexed)
+// page.url.next / page.url.prev: adjacent page URLs
+```
+
+6. Create `src/pages/404.astro` for a custom 404 page. In SSR mode this file is served for unmatched routes; in SSG it depends on the host.
+
+7. Use `Astro.redirect()` for programmatic redirects in SSR mode. In SSG, configure redirects in `astro.config.mjs`:
+
+```javascript
+// astro.config.mjs
+export default defineConfig({
+  redirects: {
+    '/old-path': '/new-path',
+    '/blog/[slug]': '/posts/[slug]', // dynamic redirect
+  },
+});
+```
+
+8. Understand route priority when multiple routes could match the same URL:
+   - Static routes win over dynamic: `/about` beats `[slug]`
+   - More specific dynamic routes win: `/blog/[slug]` beats `/[...rest]`
+   - Named rest params lose to all other patterns
+
+## Details
+
+Astro's file-based router has no runtime overhead in SSG mode — all route resolution happens at build time, producing a flat directory of `.html` files. In SSR mode, the router resolves requests at the edge/server using the same file structure.
+
+**`getStaticPaths()` contract:**
+
+This function is called once per dynamic route file during the build. It must return a serializable array — the return value is cached and cannot be async per-entry (do all async work inside the function before mapping). Every params combination returned becomes a generated page. If a param is missing from the return value, that URL will 404.
+
+**Passing props through `getStaticPaths()`:**
+
+The `props` key in each `getStaticPaths()` return object is merged into `Astro.props` for that specific page. This is the correct way to pass fetched data (collection entries, API responses) into the page frontmatter without a second network/file-system round-trip.
+
+**`params` vs. `Astro.params`:**
+
+- `params` in `getStaticPaths()` — the object you define that shapes the URL segments
+- `Astro.params` — the resolved param values available in the frontmatter at render time. In SSG they match the params object you returned. In SSR they come from the live request URL.
+
+**Endpoint routes:**
+
+Files in `src/pages/` with `.ts` or `.js` extensions (not `.astro`) become API endpoints, not HTML pages. See astro-server-endpoints for that pattern.
+
+**Named groups and optional segments (Astro 4+):**
+
+- Optional params: `[...slug]` already acts as optional (can match zero segments)
+- For a truly optional single segment, use `[slug]` with a rest route fallback or handle `undefined` in SSR
+
+**Hybrid SSR and routing:**
+
+In `output: 'hybrid'` mode, every page is static by default. Add `export const prerender = false` to opt specific pages into SSR. Dynamic route pages in SSR do not need `getStaticPaths()` — `Astro.params` is populated from the live request.
+
+## Source
+
+https://docs.astro.build/en/guides/routing
+
+## 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/claude-code/astro-routing-pattern/skill.yaml

@@ -0,0 +1,43 @@
+name: astro-routing-pattern
+version: '1.0.0'
+description: Implement file-based routing, dynamic routes, and getStaticPaths for static and server-rendered pages
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/pages/**'
+  - '**/src/content/**'
+related_skills:
+  - astro-component-pattern
+  - astro-ssr-hybrid
+  - astro-server-endpoints
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - file-based-routing
+  - dynamic-routes
+  - getStaticPaths
+  - params
+  - rest-routes
+  - route-priority
+  - pagination
+  - redirect
+  - 404-page
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/routing'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/astro-server-endpoints/SKILL.md

@@ -0,0 +1,173 @@
+# Astro Server Endpoints
+
+> Build REST API routes, webhooks, and form handlers inside your Astro project using `.ts` endpoint files and the middleware API.
+
+## When to Use
+
+- You need a GET or POST handler in the same project as your Astro pages (form submissions, data APIs, webhooks)
+- You want to keep backend logic co-located with your frontend without spinning up a separate server
+- You are building an authenticated route that reads cookies or headers on each request
+- You need middleware to run before every request (auth checks, logging, locale detection)
+- You are in SSR or hybrid mode and need dynamic data endpoints
+
+## Instructions
+
+1. Create endpoint files in `src/pages/` with a `.ts` or `.js` extension. The file path maps to the URL, same as page routing:
+   - `src/pages/api/hello.ts` → `GET /api/hello`
+   - `src/pages/api/posts/[id].ts` → `GET/POST /api/posts/:id`
+
+2. Export named functions for each HTTP method you want to handle. Function names must be uppercase:
+
+```typescript
+// src/pages/api/posts.ts
+import type { APIRoute } from 'astro';
+
+export const GET: APIRoute = async ({ request, url, cookies, locals }) => {
+  const tag = url.searchParams.get('tag');
+  const posts = await fetchPosts(tag);
+  return new Response(JSON.stringify(posts), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+
+export const POST: APIRoute = async ({ request }) => {
+  const body = await request.json();
+  if (!body.title) {
+    return new Response(JSON.stringify({ error: 'title is required' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+  const post = await createPost(body);
+  return new Response(JSON.stringify(post), { status: 201 });
+};
+```
+
+3. Use `context.request` to read the raw `Request` object. Parse the body based on content type:
+
+```typescript
+// JSON body
+const data = await request.json();
+
+// Form data
+const formData = await request.formData();
+const email = formData.get('email') as string;
+
+// Raw text
+const text = await request.text();
+
+// Request headers
+const auth = request.headers.get('authorization');
+```
+
+4. Read and set cookies via `context.cookies`:
+
+```typescript
+export const GET: APIRoute = async ({ cookies }) => {
+  const token = cookies.get('session')?.value;
+  if (!token) return new Response(null, { status: 401 });
+
+  cookies.set('last-visit', new Date().toISOString(), {
+    httpOnly: true,
+    secure: true,
+    maxAge: 60 * 60 * 24 * 7, // 1 week
+    path: '/',
+  });
+
+  return new Response('OK');
+};
+```
+
+5. Create middleware at `src/middleware.ts` to run logic before every request. Use `defineMiddleware` and call `next()` to continue the chain:
+
+```typescript
+// src/middleware.ts
+import { defineMiddleware } from 'astro:middleware';
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const token = context.cookies.get('session')?.value;
+  context.locals.user = token ? await validateToken(token) : null;
+
+  // Block unauthenticated access to /dashboard
+  if (context.url.pathname.startsWith('/dashboard') && !context.locals.user) {
+    return context.redirect('/login');
+  }
+
+  return next(); // proceed to page/endpoint handler
+});
+```
+
+6. Chain multiple middleware functions with `sequence()` from `astro:middleware`:
+
+```typescript
+import { defineMiddleware, sequence } from 'astro:middleware';
+
+const auth = defineMiddleware(async (ctx, next) => {
+  /* ... */ return next();
+});
+const logging = defineMiddleware(async (ctx, next) => {
+  console.log(`${ctx.request.method} ${ctx.url.pathname}`);
+  return next();
+});
+
+export const onRequest = sequence(logging, auth);
+```
+
+7. Add types for `locals` to get IntelliSense in middleware and pages. Augment the `App.Locals` interface in `env.d.ts`:
+
+```typescript
+// src/env.d.ts
+/// <reference types="astro/client" />
+interface Locals {
+  user: { id: string; email: string } | null;
+}
+```
+
+8. In SSG mode, endpoints with `GET` handlers can generate static files (JSON, XML, RSS). Export `getStaticPaths()` from a dynamic endpoint file to generate multiple static output files.
+
+## Details
+
+Astro endpoints use the standard Web `Request`/`Response` API — the same API available in Cloudflare Workers, Deno, and modern Node.js. This means your endpoint logic is portable across runtimes without an adapter-specific API.
+
+**SSG vs. SSR endpoints:**
+
+In SSG mode, only `GET` handlers are useful. The build calls each `GET` handler and writes the response body to a static file. A `src/pages/feed.xml.ts` with `export const GET` produces a static `dist/feed.xml`.
+
+In SSR mode, all HTTP methods work and endpoints are invoked on every request. This is where POST, PUT, DELETE, and PATCH handlers are useful.
+
+**`prerender` per endpoint:**
+
+In `output: 'hybrid'` mode, endpoints are server-rendered by default. Add `export const prerender = true` to opt a specific endpoint into static generation. In `output: 'server'` mode, endpoints are server-rendered by default; add `export const prerender = true` to force static output.
+
+**Error handling:**
+
+Always return a `Response` — never throw from an endpoint. If you need to return an error, construct a `Response` with the appropriate status code. Unhandled throws will produce a 500 with an Astro error page.
+
+**`locals` — the middleware/page contract:**
+
+`context.locals` is a mutable plain object scoped to the current request. Set values in middleware, read them in pages and endpoints. This is the correct way to pass auth state, tenant context, or feature flags from middleware to handlers.
+
+**Rate limiting and edge cases:**
+
+Astro has no built-in rate limiting. Implement rate limiting in middleware using a memory store (for single-instance) or an external store (Redis, KV for edge). Check `context.clientAddress` for the caller's IP — this is populated correctly when behind a reverse proxy if the adapter is configured for it.
+
+## Source
+
+https://docs.astro.build/en/guides/endpoints
+
+## 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/claude-code/astro-server-endpoints/skill.yaml

@@ -0,0 +1,44 @@
+name: astro-server-endpoints
+version: '1.0.0'
+description: Build API endpoints and middleware in Astro for GET/POST handlers and server-side request processing
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/pages/**'
+  - '**/src/content/**'
+related_skills:
+  - astro-ssr-hybrid
+  - astro-routing-pattern
+  - astro-deployment-config
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - api-endpoints
+  - server-endpoints
+  - GET
+  - POST
+  - APIRoute
+  - middleware
+  - request-response
+  - APIContext
+  - defineMiddleware
+  - sequence
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/endpoints'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/astro-ssr-hybrid/SKILL.md

@@ -0,0 +1,191 @@
+# Astro SSR and Hybrid Rendering
+
+> Control rendering mode at the project level and per-page — combine static pre-rendering with server-side dynamic pages using `output: 'hybrid'` and adapter configuration.
+
+## When to Use
+
+- You need some pages to be server-rendered (authenticated dashboards, personalized content, real-time data) while others stay static
+- You are adding authentication, user sessions, or cookie-based personalization to an Astro project
+- You want to read `Astro.request` headers, `Astro.cookies`, or `Astro.locals` in a page
+- You are selecting an adapter for a deployment target (Vercel, Node.js, Cloudflare)
+- You need to understand which features (redirects, cookies, `Astro.params`) are available in SSG vs. SSR mode
+
+## Instructions
+
+1. Set the `output` field and install an adapter in `astro.config.mjs`:
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel/serverless';
+
+export default defineConfig({
+  output: 'server', // all pages are SSR by default
+  adapter: vercel(),
+});
+```
+
+Available `output` values:
+
+- `'static'` (default) — all pages pre-rendered at build time; no server required
+- `'server'` — all pages SSR; a server adapter is required
+- `'hybrid'` — all pages static by default; opt specific pages into SSR with `prerender = false`
+
+2. In `output: 'hybrid'` mode, opt a page into SSR by exporting `prerender = false`:
+
+```astro
+---
+// src/pages/dashboard.astro
+export const prerender = false; // This page is server-rendered
+
+const user = Astro.locals.user;
+if (!user) return Astro.redirect('/login');
+const data = await fetchUserData(user.id);
+---
+<h1>Welcome, {user.name}</h1>
+```
+
+3. In `output: 'server'` mode, opt a page into static pre-rendering by exporting `prerender = true`:
+
+```astro
+---
+// src/pages/about.astro
+export const prerender = true; // Pre-render this page at build time
+---
+<h1>About Us</h1>
+```
+
+4. Use `Astro.request` to read request data in SSR pages. This is a standard `Request` object:
+
+```astro
+---
+export const prerender = false;
+
+const url = new URL(Astro.request.url);
+const query = url.searchParams.get('q') ?? '';
+const userAgent = Astro.request.headers.get('user-agent');
+const clientIp = Astro.clientAddress; // requires adapter support
+---
+```
+
+5. Read and write cookies with `Astro.cookies`:
+
+```astro
+---
+export const prerender = false;
+
+// Read a cookie
+const theme = Astro.cookies.get('theme')?.value ?? 'light';
+
+// Set a cookie
+Astro.cookies.set('theme', 'dark', {
+  httpOnly: false,
+  secure: true,
+  sameSite: 'lax',
+  maxAge: 60 * 60 * 24 * 365, // 1 year
+  path: '/',
+});
+---
+```
+
+6. Return a redirect from a page with `Astro.redirect()`:
+
+```astro
+---
+export const prerender = false;
+
+const session = Astro.cookies.get('session')?.value;
+if (!session) return Astro.redirect('/login', 302);
+---
+```
+
+7. Install the correct adapter for your deployment target:
+
+```bash
+# Vercel
+npx astro add vercel
+
+# Node.js (standalone server)
+npx astro add node
+
+# Cloudflare Pages/Workers
+npx astro add cloudflare
+
+# Netlify
+npx astro add netlify
+```
+
+8. For dynamic routes in SSR mode, do not implement `getStaticPaths()`. Astro reads `Astro.params` directly from the request URL:
+
+```astro
+---
+// src/pages/blog/[slug].astro
+export const prerender = false;
+
+const { slug } = Astro.params;
+const post = await fetchPost(slug);
+if (!post) return Astro.redirect('/404');
+---
+<article><h1>{post.title}</h1></article>
+```
+
+## Details
+
+Astro's rendering model is a spectrum from fully static to fully dynamic. Understanding which mode to use for each page is the key design decision in an Astro SSR project.
+
+**When to use each mode:**
+
+| Page type                         | Recommended mode                               |
+| --------------------------------- | ---------------------------------------------- |
+| Marketing pages, blog posts, docs | `prerender = true` (static)                    |
+| Authenticated dashboards          | `prerender = false` (SSR)                      |
+| Product pages (semi-static)       | `prerender = true` + client-side data fetching |
+| Search results                    | `prerender = false` (SSR)                      |
+| API endpoints with dynamic data   | `prerender = false` (SSR)                      |
+| Sitemap, RSS feed                 | `prerender = true` (static)                    |
+
+**`output: 'hybrid'` vs. `output: 'server'`:**
+
+Choose `output: 'hybrid'` when most of your pages are static and a few need SSR. This is the most common pattern for content sites with authenticated features. Choose `output: 'server'` for applications where most pages are dynamic (dashboards, SaaS apps).
+
+**Adapter selection:**
+
+The adapter transforms Astro's SSR output into the format required by the target platform:
+
+- `@astrojs/vercel/serverless` — Vercel serverless functions
+- `@astrojs/vercel/edge` — Vercel Edge Functions (limited Node.js API surface)
+- `@astrojs/node` — standalone Node.js server (requires `node src/server.mjs`)
+- `@astrojs/cloudflare` — Cloudflare Pages / Workers (no Node.js built-ins)
+- `@astrojs/netlify` — Netlify Functions / Edge Functions
+
+**`Astro.locals` and middleware:**
+
+Middleware populates `Astro.locals` before the page runs. This is the correct channel for auth state, feature flags, and tenant context. In SSG mode, `Astro.locals` is available but middleware only runs at build time (not per-request).
+
+**Streaming:**
+
+Astro supports streaming SSR responses. The page begins streaming HTML to the client before all async data is resolved. Components that are not awaited render as placeholders until their data arrives. This improves Time To First Byte (TTFB) for pages with multiple independent async data sources.
+
+**Environment variables in SSR:**
+
+Use `import.meta.env.SECRET_API_KEY` for server-only secrets. These values are available at build time and runtime in SSR, but are never exposed to the client bundle. Public variables must be prefixed with `PUBLIC_` to be accessible in client-side scripts.
+
+## Source
+
+https://docs.astro.build/en/guides/server-side-rendering
+
+## 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/claude-code/astro-ssr-hybrid/skill.yaml

@@ -0,0 +1,46 @@
+name: astro-ssr-hybrid
+version: '1.0.0'
+description: Configure SSR and hybrid rendering with output modes, adapters, and per-page prerender control
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/pages/**'
+  - '**/src/content/**'
+  - '**/src/layouts/**'
+related_skills:
+  - astro-routing-pattern
+  - astro-server-endpoints
+  - astro-deployment-config
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - ssr
+  - server-side-rendering
+  - hybrid-rendering
+  - output-server
+  - output-hybrid
+  - prerender
+  - adapter
+  - Astro.request
+  - Astro.cookies
+  - dynamic-pages
+  - static-pages
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/server-side-rendering'
+state:
+  persistent: false
+  files: []
+depends_on: []