@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/astro-content-collections/SKILL.md

@@ -0,0 +1,155 @@
+# Astro Content Collections
+
+> Type-safe, schema-validated content management built into Astro — no CMS required for structured Markdown, MDX, and data files.
+
+## When to Use
+
+- You are organizing Markdown, MDX, YAML, or JSON content files in `src/content/`
+- You need frontmatter validation with helpful error messages (not silent failures)
+- You want TypeScript types auto-generated from your content schema
+- You are querying multiple content entries (blog posts, docs pages, team members) and need filtering and sorting
+- You want to render Markdown content with `<Content />` and get full type safety on the rendered entry
+
+## Instructions
+
+1. Create a collection config at `src/content/config.ts`. This is the single source of truth for all collections.
+
+2. Define each collection with `defineCollection()` and a Zod schema. Every frontmatter field should be declared:
+
+```typescript
+// src/content/config.ts
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+  type: 'content', // 'content' for .md/.mdx, 'data' for .json/.yaml
+  schema: z.object({
+    title: z.string(),
+    description: z.string().max(160),
+    pubDate: z.coerce.date(),
+    updatedDate: z.coerce.date().optional(),
+    heroImage: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+    draft: z.boolean().default(false),
+  }),
+});
+
+const authors = defineCollection({
+  type: 'data',
+  schema: z.object({
+    name: z.string(),
+    email: z.string().email(),
+    avatar: z.string().url(),
+  }),
+});
+
+export const collections = { blog, authors };
+```
+
+3. Place content files under `src/content/<collection-name>/`. The directory name must match the collection key exported from `config.ts`.
+
+4. Use `getCollection()` to fetch all entries. Apply filters inline — do not load all entries and filter in the template:
+
+```typescript
+// src/pages/blog/index.astro
+---
+import { getCollection } from 'astro:content';
+
+// Exclude drafts in production
+const posts = await getCollection('blog', ({ data }) => {
+  return import.meta.env.PROD ? !data.draft : true;
+});
+
+// Sort by date descending
+const sorted = posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
+---
+```
+
+5. Use `getEntry()` to fetch a single entry by collection name and slug:
+
+```typescript
+const post = await getEntry('blog', 'my-first-post');
+if (!post) return Astro.redirect('/404');
+const { Content } = await post.render();
+```
+
+6. Render Markdown/MDX content with the `<Content />` component returned from `entry.render()`:
+
+```astro
+---
+const { Content, headings, remarkPluginFrontmatter } = await post.render();
+---
+<article>
+  <Content />
+</article>
+```
+
+7. Use `z.coerce.date()` for date fields in frontmatter — raw frontmatter dates are strings, and coercion converts them to `Date` objects automatically.
+
+8. Reference images in frontmatter using the `image()` helper for build-time optimization integration:
+
+```typescript
+import { defineCollection, z, reference } from 'astro:content';
+schema: ({ image }) =>
+  z.object({
+    cover: image(), // local image, processed by astro:assets
+    author: reference('authors'), // type-safe cross-collection reference
+  });
+```
+
+## Details
+
+Content Collections were introduced in Astro 2.0 to solve the problem of unstructured, unvalidated frontmatter. Without collections, a typo in a date field or a missing required property would either silently pass or cause a runtime error deep in your template. With collections, Astro validates every entry at build time using Zod and surfaces clear errors.
+
+**The `type` distinction:**
+
+- `type: 'content'` — for `.md` and `.mdx` files. Entries have `body` (raw Markdown string), `render()` method, and `slug` (auto-derived from filename).
+- `type: 'data'` — for `.json` and `.yaml` files. Entries have only `data` (the parsed object). No `render()` or `slug`.
+
+**Generated types:**
+
+Astro generates `.astro/types.d.ts` from your collection config. This gives you full IntelliSense on `entry.data.title`, `entry.data.pubDate`, etc., without manual type declarations.
+
+**Slugs and IDs:**
+
+- `entry.slug` — the path relative to the collection directory, without the extension. For `src/content/blog/2024/my-post.md`, the slug is `2024/my-post`.
+- `entry.id` — same as slug but with the extension included. Primarily used for `data` collections.
+
+**Cross-collection references:**
+
+Use `reference('collectionName')` in a Zod schema to create typed cross-collection references. Astro validates that the referenced entry exists at build time. Resolve references with `getEntry(entry.data.author)`.
+
+**Content Layer API (Astro 5+):**
+
+Astro 5 introduced the Content Layer API, which extends collections to support external data sources (remote APIs, databases, CMSes). Use `loader` in `defineCollection()`:
+
+```typescript
+const products = defineCollection({
+  loader: async () => {
+    const res = await fetch('https://api.example.com/products');
+    return res.json(); // array of objects with an `id` field
+  },
+  schema: z.object({ id: z.string(), name: z.string(), price: z.number() }),
+});
+```
+
+**Performance:** `getCollection()` reads from the file system at build time (SSG) or at request time (SSR). In SSG, results are used to generate static pages via `getStaticPaths()`. In SSR, consider caching results if collections are large.
+
+## Source
+
+https://docs.astro.build/en/guides/content-collections
+
+## 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-content-collections/skill.yaml

@@ -0,0 +1,42 @@
+name: astro-content-collections
+version: '1.0.0'
+description: Organize and validate content with Astro content collections, schema definitions, and getCollection
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/content/**'
+  - '**/src/pages/**'
+related_skills:
+  - astro-component-pattern
+  - astro-routing-pattern
+  - astro-image-optimization
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - content-collections
+  - getCollection
+  - getEntry
+  - defineCollection
+  - zod-schema
+  - frontmatter
+  - content-layer
+  - type-safe-content
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/content-collections'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/astro-deployment-config/SKILL.md

@@ -0,0 +1,208 @@
+# Astro Deployment Configuration
+
+> Configure adapters, environment variables, and build output for deploying Astro to Vercel, Node.js, Cloudflare, and Netlify.
+
+## When to Use
+
+- You are deploying an Astro project for the first time and need to choose and configure an adapter
+- You are switching deployment targets and need to change the adapter and output format
+- You need to manage environment variables correctly across build time and runtime
+- You are debugging a deployment where pages work locally but fail in production
+- You need to configure custom headers, redirects, or asset CDN behavior in the deployment target
+
+## Instructions
+
+1. Install the adapter for your target platform. Each adapter configures Astro's SSR output for that runtime:
+
+```bash
+# Vercel (serverless functions)
+npx astro add vercel
+
+# Vercel Edge (edge runtime — limited Node.js APIs)
+# Manual: import vercel from '@astrojs/vercel/edge'
+
+# Node.js (self-hosted server)
+npx astro add node
+
+# Cloudflare Pages
+npx astro add cloudflare
+
+# Netlify
+npx astro add netlify
+```
+
+2. Configure the adapter in `astro.config.mjs`:
+
+```javascript
+// Vercel — serverless (most common)
+import vercel from '@astrojs/vercel/serverless';
+export default defineConfig({
+  output: 'server',
+  adapter: vercel({
+    webAnalytics: { enabled: true },
+    imageService: true, // use Vercel Image Optimization
+    devImageService: 'sharp', // local dev uses sharp
+  }),
+});
+
+// Node.js — standalone server
+import node from '@astrojs/node';
+export default defineConfig({
+  output: 'server',
+  adapter: node({ mode: 'standalone' }), // or 'middleware' for Express
+});
+
+// Cloudflare Pages
+import cloudflare from '@astrojs/cloudflare';
+export default defineConfig({
+  output: 'server',
+  adapter: cloudflare({ mode: 'directory' }), // or 'advanced'
+});
+```
+
+3. Manage environment variables using `import.meta.env`. Astro follows Vite's env convention:
+
+```typescript
+// Public variables (exposed to client bundles) — must be prefixed PUBLIC_
+const apiBase = import.meta.env.PUBLIC_API_BASE_URL;
+
+// Server-only variables (never sent to client)
+const dbUrl = import.meta.env.DATABASE_URL;
+const secretKey = import.meta.env.SECRET_KEY;
+
+// Built-in variables
+const isDev = import.meta.env.DEV; // boolean
+const isProd = import.meta.env.PROD; // boolean
+const siteUrl = import.meta.env.SITE; // set in astro.config.mjs > site
+const baseUrl = import.meta.env.BASE_URL; // set in astro.config.mjs > base
+```
+
+4. Set environment variables in `.env` files (never commit secrets):
+
+```
+# .env (committed — only PUBLIC_ vars)
+PUBLIC_API_BASE_URL=https://api.example.com
+
+# .env.local (gitignored — secrets)
+DATABASE_URL=postgres://...
+SECRET_KEY=abc123
+
+# .env.production (committed — production public vars only)
+PUBLIC_API_BASE_URL=https://api.production.com
+```
+
+5. Configure static deployments (no adapter needed) for fully static sites:
+
+```javascript
+// astro.config.mjs
+export default defineConfig({
+  output: 'static', // default — no adapter needed
+  site: 'https://example.com',
+  base: '/docs', // if deployed to a subdirectory
+  build: {
+    assets: '_assets', // custom directory for built assets (default: '_astro')
+  },
+});
+```
+
+Deploy the `dist/` directory to any static host (GitHub Pages, Netlify, Cloudflare Pages in static mode, S3 + CloudFront).
+
+6. Configure redirects and headers directly in `astro.config.mjs` for static deployments:
+
+```javascript
+export default defineConfig({
+  redirects: {
+    '/old-blog': '/blog',
+    '/old-blog/[slug]': '/blog/[slug]',
+  },
+});
+```
+
+For SSR deployments, platform-specific config files take precedence:
+
+- Vercel: `vercel.json` (headers, rewrites)
+- Netlify: `netlify.toml` (headers, redirects, functions)
+- Cloudflare: `wrangler.toml` + `_headers` / `_redirects` files
+
+7. Set `site` in `astro.config.mjs` — it is required for canonical URLs, sitemaps, and the `SITE` env variable:
+
+```javascript
+export default defineConfig({
+  site: 'https://www.example.com', // must be the full URL including protocol
+});
+```
+
+8. For Node.js adapter deployments, start the server with the generated entry point:
+
+```bash
+# Build
+npx astro build
+
+# Start (standalone mode)
+node ./dist/server/entry.mjs
+
+# With environment variables
+DATABASE_URL=postgres://... node ./dist/server/entry.mjs
+
+# Configure the host/port
+HOST=0.0.0.0 PORT=3000 node ./dist/server/entry.mjs
+```
+
+## Details
+
+**Adapter selection guide:**
+
+| Platform         | Adapter                          | Notes                                        |
+| ---------------- | -------------------------------- | -------------------------------------------- |
+| Vercel           | `@astrojs/vercel/serverless`     | Best DX; automatic image optimization        |
+| Vercel Edge      | `@astrojs/vercel/edge`           | No Node.js built-ins; lower latency          |
+| Netlify          | `@astrojs/netlify`               | Functions + Edge Functions                   |
+| Cloudflare Pages | `@astrojs/cloudflare`            | Workers runtime; no Node.js fs module        |
+| AWS Lambda       | `@astrojs/node` + custom wrapper | Requires additional glue                     |
+| Docker / VPS     | `@astrojs/node` standalone       | Full control; bring your own process manager |
+| GitHub Pages     | none (static)                    | Free; limited to `output: 'static'`          |
+
+**Cloudflare-specific considerations:**
+
+Cloudflare Workers do not support Node.js built-in modules (`fs`, `path`, `crypto` from Node.js). Use the Cloudflare-native equivalents: `crypto.subtle` for crypto, `KV` / `R2` for storage. Add `{ mode: 'directory' }` to the Cloudflare adapter when deploying to Pages (as opposed to Workers).
+
+**Environment variables at runtime vs. build time:**
+
+- SSG: env vars are consumed at build time — they are baked into the static HTML. Changing a public env var requires a rebuild.
+- SSR: env vars are consumed at request time — update them in the platform dashboard without a rebuild.
+- `SECRET_*` vars in SSG are only available in the build process and `getStaticPaths()`. They are never included in client bundles.
+
+**`base` path configuration:**
+
+When deploying to a subdirectory (e.g., GitHub Pages project site at `/repo-name/`), set `base: '/repo-name'`. Astro prefixes all internal links, assets, and the router with this base. Access it via `import.meta.env.BASE_URL`.
+
+**Build output structure:**
+
+- `dist/` — build output root
+- `dist/index.html` — static pages (SSG)
+- `dist/_astro/` — hashed JS/CSS chunks
+- `dist/server/` — SSR entry point and chunks (when using an adapter)
+
+**CI/CD patterns:**
+
+Most platforms (Vercel, Netlify, Cloudflare Pages) auto-detect Astro projects and set the build command (`astro build`) and output directory (`dist/`) automatically. For Node.js self-hosted deployments, set up a process manager (PM2, systemd) to keep the server running and restart on crash.
+
+## Source
+
+https://docs.astro.build/en/guides/deploy
+
+## 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-deployment-config/skill.yaml

@@ -0,0 +1,46 @@
+name: astro-deployment-config
+version: '1.0.0'
+description: Deploy Astro projects to Vercel, Node, Cloudflare, and Netlify with the correct adapter and environment variable setup
+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-ssr-hybrid
+  - astro-server-endpoints
+  - astro-integration-pattern
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - deployment
+  - adapter
+  - adapter-vercel
+  - adapter-node
+  - adapter-cloudflare
+  - adapter-netlify
+  - environment-variables
+  - import.meta.env
+  - build-output
+  - static-deployment
+  - server-deployment
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/deploy'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/astro-image-optimization/SKILL.md

@@ -0,0 +1,188 @@
+# Astro Image Optimization
+
+> Use `astro:assets` and the `<Image />` component to automatically optimize images at build time — enforcing `alt` text, generating WebP/AVIF, and preventing layout shift.
+
+## When to Use
+
+- You are adding images to an Astro project and want automatic format conversion and size optimization
+- You need responsive images with multiple source sets using `<Picture />`
+- You are loading images from a remote URL (Cloudinary, Contentful, Unsplash) and need to configure the allowlist
+- You want to use `getImage()` for programmatic image optimization in API endpoints or og:image generation
+- You are experiencing layout shift (CLS) from images and need guaranteed `width`/`height` dimensions
+
+## Instructions
+
+1. Import local images from `src/` using a static import. Astro processes these at build time and infers dimensions automatically:
+
+```astro
+---
+import { Image } from 'astro:assets';
+import heroImage from '../assets/hero.jpg';
+---
+
+<!-- Astro infers width, height, and converts to WebP by default -->
+<Image src={heroImage} alt="A mountain at sunrise" />
+```
+
+2. Use `<Image />` for single-format optimized images. Required props are `src` and `alt`. Optional props control the output:
+
+```astro
+<Image
+  src={heroImage}
+  alt="Hero"
+  width={1200}          <!-- override inferred width -->
+  height={630}          <!-- override inferred height -->
+  format="avif"         <!-- webp (default), avif, png, jpg -->
+  quality={80}          <!-- 1-100 or 'low' | 'mid' | 'high' | 'max' -->
+  loading="eager"       <!-- lazy (default) or eager -->
+  decoding="async"
+  class="hero-img"
+/>
+```
+
+3. Use `<Picture />` for responsive images that serve different formats and sizes based on browser support and viewport:
+
+```astro
+---
+import { Picture } from 'astro:assets';
+import photo from '../assets/photo.jpg';
+---
+
+<Picture
+  src={photo}
+  alt="Team photo"
+  widths={[400, 800, 1200]}
+  sizes="(max-width: 600px) 400px, (max-width: 900px) 800px, 1200px"
+  formats={['avif', 'webp']}
+  fallbackFormat="jpg"
+/>
+```
+
+4. For remote images, add the hostname to `image.remotePatterns` in `astro.config.mjs`. Astro will refuse to process remote images from unlisted hostnames:
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  image: {
+    remotePatterns: [
+      { protocol: 'https', hostname: 'images.unsplash.com' },
+      { protocol: 'https', hostname: '**.cloudinary.com' },
+    ],
+  },
+});
+```
+
+5. Use remote images in `<Image />` with explicit `width`, `height`, and `inferSize` (when dimensions cannot be known ahead of time):
+
+```astro
+<!-- Known dimensions — preferred -->
+<Image src="https://images.unsplash.com/photo-abc" alt="..." width={800} height={600} />
+
+<!-- Unknown dimensions — fetches headers to infer size (build-time cost) -->
+<Image src={remoteUrl} alt="..." inferSize />
+```
+
+6. Use `getImage()` for programmatic optimization outside of templates — useful for og:image endpoints or generating image URLs for use in CSS:
+
+```typescript
+// src/pages/api/og.ts
+import { getImage } from 'astro:assets';
+import ogBackground from '../assets/og-bg.png';
+
+export const GET = async () => {
+  const optimized = await getImage({
+    src: ogBackground,
+    format: 'png',
+    width: 1200,
+    height: 630,
+  });
+  // optimized.src — the final URL path
+  // optimized.attributes — width, height, etc.
+  return new Response(`<img src="${optimized.src}" />`);
+};
+```
+
+7. In content collections, use the `image()` schema helper to process frontmatter image paths through the optimizer:
+
+```typescript
+// src/content/config.ts
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+  schema: ({ image }) =>
+    z.object({
+      title: z.string(),
+      cover: image(), // validates path and enables optimization
+    }),
+});
+```
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { Image } from 'astro:assets';
+const { post } = Astro.props;
+---
+<Image src={post.data.cover} alt={post.data.title} width={1200} height={630} />
+```
+
+8. Configure the image service in `astro.config.mjs`. Astro uses Sharp by default in Node environments. For Cloudflare or edge deployments, switch to the no-op service and rely on the CDN:
+
+```javascript
+import { defineConfig, passthroughImageService } from 'astro/config';
+
+export default defineConfig({
+  image: {
+    service: passthroughImageService(), // no optimization, pass through as-is
+  },
+});
+```
+
+## Details
+
+Astro's image optimization pipeline is powered by Sharp (Node.js) or the browser's image decoding APIs (depending on deployment target). The `<Image />` component enforces several best practices at compile time: `alt` is required (missing it is a build error), and Astro always adds explicit `width` and `height` attributes to prevent layout shift (CLS).
+
+**Format selection strategy:**
+
+- `webp` — best default: ~30% smaller than JPEG, universal browser support
+- `avif` — best compression (~50% smaller than JPEG) but slower to encode at build time
+- `png` — use only for images that need transparency
+- Use `<Picture />` with `formats={['avif', 'webp']}` and `fallbackFormat="jpg"` to serve the best format each browser supports
+
+**Local vs. remote image processing:**
+
+Local images (`import hero from './hero.jpg'`) are processed at build time — the optimized file is written to `dist/_astro/`. Remote images are fetched during the build (SSG) or on-demand (SSR) and cached. In SSR, remote image optimization happens per-request unless you configure a CDN or caching layer.
+
+**`inferSize` trade-offs:**
+
+When `inferSize` is used on a remote image, Astro makes an HTTP HEAD request during the build to read the `Content-Length` or decodes the image header to determine dimensions. This adds build time proportional to the number of `inferSize` images. Prefer explicit `width` and `height` when the dimensions are known.
+
+**Image service configuration for edge deployments:**
+
+Sharp is a native Node.js module — it does not work on Cloudflare Workers or Vercel Edge Runtime. For edge deployments use `passthroughImageService()` and offload optimization to Cloudflare Image Resizing, Vercel Image Optimization, or Imgix.
+
+**Content Security Policy:**
+
+When using remote images, your CSP `img-src` directive must allow the remote origin. The optimized image URL will be an Astro-proxied URL in SSR mode, so only `'self'` may be needed depending on configuration.
+
+## Source
+
+https://docs.astro.build/en/guides/images
+
+## 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-image-optimization/skill.yaml

@@ -0,0 +1,45 @@
+name: astro-image-optimization
+version: '1.0.0'
+description: Optimize images with astro:assets, the Image component, and remote image configuration
+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-content-collections
+  - astro-deployment-config
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - image-optimization
+  - astro-assets
+  - Image-component
+  - Picture-component
+  - getImage
+  - remote-images
+  - image-service
+  - sharp
+  - webp
+  - avif
+  - inferSize
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/guides/images'
+state:
+  persistent: false
+  files: []
+depends_on: []