@netlify/agent-runner-cli 1.30.0 → 1.30.1-broken.0

package/dist/skills/netlify-image-cdn/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: netlify-image-cdn
+description: Transform and optimize images on-demand using Netlify Image CDN. Use when implementing responsive images, format conversion, resizing, cropping, or dynamic image optimization without build-time processing.
+---
+
+# Netlify Image CDN
+
+Netlify Image CDN transforms and optimizes images on demand at the edge without impacting build times. It handles
+content negotiation to serve the most efficient format and caches transformed images for fast delivery.
+
+## Quick Start
+
+All Netlify projects have a `/.netlify/images` route without any additional enablement. Use it with query parameters to
+transform any image:
+
+```html
+<!-- Resize to 400px wide, convert to WebP -->
+<img src="/.netlify/images?url=/photo.jpg&w=400&fm=webp" alt="Optimized photo" />
+
+<!-- Cover crop to 200x200 square -->
+<img src="/.netlify/images?url=/photo.jpg&w=200&h=200&fit=cover" alt="Cropped photo" />
+
+<!-- Transform a remote image -->
+<img src="/.netlify/images?url=https://example.com/image.jpg&w=800&q=80" alt="Remote image" />
+```
+
+## Query Parameters
+
+| Parameter | Required | Type | Description |
+|-----------|----------|------|-------------|
+| `url` | Yes | `string` | Source image path (relative) or URL (remote, requires config) |
+| `w` | No | `integer` | Width in pixels |
+| `h` | No | `integer` | Height in pixels |
+| `fit` | No | `string` | Resize mode: `contain` (default), `cover`, `fill` |
+| `position` | No | `string` | Crop anchor for `fit=cover`: `center` (default), `top`, `bottom`, `left`, `right` |
+| `fm` | No | `string` | Output format: `avif`, `jpg`, `png`, `webp`, `gif`, `blurhash` |
+| `q` | No | `integer` | Quality 1-100 for lossy formats (default: 75) |
+
+The `url` value must be URI-encoded when it contains special characters.
+
+## Fit Modes
+
+| `fit=` | Aspect Ratio Maintained | Crops | Always Returns Exact Dimensions |
+|--------|------------------------|-------|-------------------------------|
+| `contain` (default) | Yes | No | No, one dimension may be smaller |
+| `cover` | Yes | Yes | Yes, crops excess after proportional resize |
+| `fill` | No | No | Yes, stretches/squishes to exact dimensions |
+
+### `fit=contain` (default)
+
+Resizes proportionally to fit within the specified dimensions. If only one dimension is given, the other is calculated
+to maintain aspect ratio.
+
+```html
+<img src="/.netlify/images?url=/photo.jpg&w=600&h=400&fit=contain" />
+```
+
+### `fit=cover`
+
+Resizes proportionally to fill the dimensions, then crops excess pixels. Requires **both** `w` and `h`. Use `position`
+to control which area is retained.
+
+```html
+<img src="/.netlify/images?url=/photo.jpg&w=300&h=300&fit=cover&position=top" />
+```
+
+### `fit=fill`
+
+Stretches the image to exactly match the specified dimensions. May distort the image if aspect ratios differ.
+
+```html
+<img src="/.netlify/images?url=/photo.jpg&w=400&h=200&fit=fill" />
+```
+
+## Format Negotiation
+
+When `fm` is **not** specified, Image CDN automatically negotiates the best format using the browser's `Accept` header:
+
+1. Use `webp` if the browser accepts it
+2. Otherwise use `avif` if accepted
+3. Otherwise serve the original format
+
+Explicitly set `fm` only when a specific format is required (e.g., `blurhash` for placeholders).
+
+## Remote Image Configuration
+
+To transform images from external domains, allowlist them in `netlify.toml` using regex patterns:
+
+```toml
+[images]
+remote_images = [
+  "https://my-images\\.com/.*",
+  "https://animals\\.more-images\\.com/[bcr]at/.*"
+]
+```
+
+Then reference the full URL:
+
+```html
+<img src="/.netlify/images?url=https://my-images.com/photo.jpg&w=400" />
+```
+
+Only absolute URLs to external servers need to be in `remote_images`. Local site images work without configuration.
+
+## Redirects & Rewrites
+
+If you do not want to use the default `/.netlify/images` path, a redirect or rewrite can be used to have a different
+URL. When doing so, the parameters can remain parameters to pass in or can be statically defined.
+
+**Using `netlify.toml`:**
+
+```toml
+[[redirects]]
+from = "/transform-small/*"
+to = "/.netlify/images?url=/:splat&w=50&h=50"
+status = 200
+```
+
+**Using `_redirects` file:**
+
+```
+/transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200
+```
+
+**Usage:**
+
+```html
+<!-- Transforms /photo.jpg with w=50&h=50 -->
+<img src="/transform-small/photo.jpg" />
+```
+
+DO NOT create circular redirects where an image URL redirects to another URL that redirects back. This causes infinite
+loops and errors.
+
+## Custom Headers
+
+Apply custom headers to source images on your site's domain. Headers propagate to the transformed output. ONLY do this
+when explicitly asked.
+
+**Using `netlify.toml`:**
+
+```toml
+[[headers]]
+for = "/source-images/*"
+[headers.values]
+  Cache-Control = "public, max-age=604800, must-revalidate"
+```
+
+**Using `_headers` file:**
+
+```
+/source-images/*
+  Cache-Control: public, max-age=604800, must-revalidate
+```
+
+**Limitations:**
+- Custom headers only work for images on the same domain
+- Cannot apply custom headers to remote source images
+- Netlify respects cache headers that external domains send with their images
+- `Cache-Control` headers on source images apply to browsers/CDNs, not the Netlify cache itself
+
+## Framework Integration
+
+Many frameworks automatically use Netlify Image CDN when deployed to Netlify:
+
+| Framework | Setup | Remote Image Allowlist |
+|-----------|-------|----------------------|
+| **Angular** | Automatic via `NgOptimizedImage` | `[images] remote_images` in `netlify.toml` |
+| **Astro** | Automatic via `<Image />` component | `image.domains` or `image.remotePatterns` in `astro.config.mjs` |
+| **Gatsby 5.13+** | Set env var `NETLIFY_IMAGE_CDN=true` | `[images] remote_images` in `netlify.toml` |
+| **Next.js 13.5+** | Automatic with adapter v5 | `remotePatterns` in `next.config.js` |
+| **Nuxt** | Automatic via `nuxt/image` module | `image.domains` in `nuxt.config.ts` |
+
+## Caching & Deploy Behavior
+
+- Transformed images are uniquely cached at the edge per transformation parameters
+- Future requests for the same transformation serve the cached version
+- After a new deploy, cached images are invalidated if the source changed
+- Source images are also cached to speed up future transformations
+- Use asset fingerprinting (content hashes in filenames) for fine-grained cache control
+
+## Response Codes
+
+| Condition | Response |
+|-----------|----------|
+| Valid query, new transformation | `200` with transformed image |
+| Request for previously cached transformation | `304` Not Modified |
+| Invalid parameter values or missing source | `404` Not Found |
+
+## Common Errors & Solutions
+
+### "404 on image transformation"
+
+**Cause:** Invalid parameter values or source image not found.
+
+**Fix:**
+
+1. Verify the source image exists at the specified `url` path
+2. Check parameter values are valid (e.g., `q` must be 1-100, `fit` must be `contain`, `cover`, or `fill`)
+3. For remote images, ensure the domain is in `remote_images` config
+
+### Blurry or low-quality output
+
+**Cause:** Quality setting too low or dimensions too small.
+
+**Fix:**
+
+1. Increase the `q` parameter (default is 75, max is 100)
+2. Ensure `w` and `h` are appropriate for the display size
+3. Use `fm=png` for images that need lossless quality
+
+### Remote image not loading
+
+**Cause:** External domain not allowlisted.
+
+**Fix:**
+
+1. Add the domain to `remote_images` in `netlify.toml`:
+   ```toml
+   [images]
+   remote_images = ["https://example\\.com/.*"]
+   ```
+2. Escape dots in regex patterns with double backslash
+3. Redeploy after updating config
+
+### Images not updating after deploy
+
+**Cause:** Browser or CDN cache serving stale version.
+
+**Fix:**
+
+1. Use asset fingerprinting (e.g., `/photo-abc123.jpg`) for cache busting
+2. Clear browser cache or use hard refresh
+3. Wait a few minutes for edge cache propagation
+
+### Circular redirect error
+
+**Cause:** Redirect rule creates a loop with the image transformation endpoint.
+
+**Fix:**
+
+1. Ensure redirect `from` path does not overlap with the `to` path
+2. Avoid redirecting `/.netlify/images` to another `/.netlify/images` URL
+3. Use status `200` (rewrite) not `301`/`302` (redirect) when possible

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.30.0",
+  "version": "1.30.1-broken.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": "./dist/index.js",
   "bin": {
-    "agent-runner-cli": "./dist/bin.js"
+    "agent-runner-cli": "./dist/bin.js",
+    "agent-runner-cli-local": "./dist/bin-local.js"
   },
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "dist/skills/**",
     "patches",
     "scripts"
   ],
@@ -25,21 +27,24 @@
     "format": "run-s build format:check-fix:*",
     "format:ci": "run-s build format:check:*",
     "format:check-fix:lint": "run-e format:check:lint format:fix:lint",
-    "format:check:lint": "cross-env-shell eslint $npm_package_config_eslint",
-    "format:fix:lint": "cross-env-shell eslint --fix $npm_package_config_eslint",
+    "format:check:lint": "eslint --cache --format=codeframe --max-warnings=0 \"{src,scripts,test,.github}/**/*.{js,ts,md,html}\"",
+    "format:fix:lint": "eslint --fix --cache --format=codeframe --max-warnings=0 \"{src,scripts,test,.github}/**/*.{js,ts,md,html}\"",
     "format:check-fix:prettier": "run-e format:check:prettier format:fix:prettier",
-    "format:check:prettier": "cross-env-shell prettier --check $npm_package_config_prettier",
-    "format:fix:prettier": "cross-env-shell prettier --write $npm_package_config_prettier",
+    "format:check:prettier": "prettier --check --ignore-path .gitignore --loglevel=warn \"{src,scripts,test,.github}/**/*.{js,ts,md,yml,json,html}\" \"*.{js,ts,yml,json,html}\" \".*.{js,ts,yml,json,html}\" \"!**/package-lock.json\" \"!package-lock.json\" \"!src/skills/**/*.md\"",
+    "format:fix:prettier": "prettier --write --ignore-path .gitignore --loglevel=warn \"{src,scripts,test,.github}/**/*.{js,ts,md,yml,json,html}\" \"*.{js,ts,yml,json,html}\" \".*.{js,ts,yml,json,html}\" \"!**/package-lock.json\" \"!package-lock.json\" \"!src/skills/**/*.md\"",
     "test:dev": "run-s build test:dev:*",
     "test:ci": "run-s build test:ci:*",
-    "test:dev:vitest": "vitest",
-    "test:ci:vitest": "c8 -r lcovonly -r text -r json vitest",
+    "test:dev:vitest": "LOG=0 vitest --exclude '**/integration/**'",
+    "test:ci:vitest": "LOG=0 vitest run --coverage --exclude '**/integration/**'",
+    "test:integration": "vitest run test/integration/",
+    "test:integration:codex": "vitest run test/integration/codex.test.ts",
+    "test:integration:claude": "vitest run test/integration/claude.test.ts",
+    "test:integration:gemini": "vitest run test/integration/gemini.test.ts",
+    "test:integration:skill-invocation": "vitest run test/integration/skill-invocation.test.ts",
+    "test:integration:feature-enablement": "vitest run test/integration/feature-enablement.test.ts",
+    "check:types": "tsc --noEmit",
     "postinstall": "node scripts/postinstall.js"
   },
-  "config": {
-    "eslint": "--cache --format=codeframe --max-warnings=0 \"{src,scripts,test,.github}/**/*.{js,ts,md,html}\"",
-    "prettier": "--ignore-path .gitignore --loglevel=warn \"{src,scripts,test,.github}/**/*.{js,ts,md,yml,json,html}\" \"*.{js,ts,yml,json,html}\" \".*.{js,ts,yml,json,html}\" \"!**/package-lock.json\" \"!package-lock.json\""
-  },
   "keywords": [],
   "license": "MIT",
   "repository": "netlify/agent-runner-cli",
@@ -51,33 +56,40 @@
     "test": "test"
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.0.0",
-    "@commitlint/config-conventional": "^19.0.0",
-    "@eslint/compat": "^1.3.2",
+    "@commitlint/cli": "^20.0.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@eslint/compat": "^2.0.0",
     "@eslint/js": "^9.35.0",
+    "@netlify/axis": "^1.14.0",
     "@netlify/eslint-config-node": "^7.0.1",
     "@types/node": "^24.5.0",
-    "@typescript-eslint/eslint-plugin": "^7.1.0",
-    "@typescript-eslint/parser": "^7.1.0",
-    "@vitest/eslint-plugin": "^1.3.10",
-    "c8": "^9.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/eslint-plugin": "^1.6.6",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^17.0.0",
-    "husky": "^8.0.0",
+    "husky": "^9.0.0",
+    "jiti": "^2.7.0",
     "patch-package": "^8.0.0",
     "tsup": "^8.5.0",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.44.0",
-    "vitest": "^1.5.0"
+    "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@anthropic-ai/claude-code": "^1.0.51",
-    "@google/gemini-cli": "0.1.17",
-    "@netlify/otel": "^4.0.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.57.0",
-    "execa": "^8.0.0",
-    "get-port": "^5.1.1",
+    "@anthropic-ai/claude-code": "2.1.154",
+    "@anthropic-ai/sdk": "0.91.1",
+    "@google/gemini-cli": "0.42.0",
+    "@netlify/database-proxy": "^0.1.5",
+    "@netlify/otel": "^6.0.3",
+    "@netlify/ts-cli": "^1.2.0",
+    "@openai/codex": "0.128.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "0.218.0",
+    "execa": "^9.6.1",
+    "fastify": "5.8.5",
     "minimist": "^1.2.8",
-    "my-codex-no-sandbox": "^0.1.2505290819"
+    "openai": "6.34.0"
   }
 }

package/scripts/scenarios/install-skills.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Installs the orchestrator's bundled skills into the agent's skill directory
+ * by calling `setupAgentSkills` from `src/context.js` — the same function the
+ * orchestrator itself uses at runtime. Intended to run as an axis scenario
+ * setup action when the scenario wants to A/B with-skills vs without.
+ *
+ * Uses `jiti` to import the orchestrator source directly so we don't need a
+ * pre-built `dist/` (context.js transitively imports several `.ts` modules
+ * that plain Node ESM can't resolve).
+ *
+ * Usage:
+ *   node install-skills.mjs [--agent claude-code|codex|gemini] [--target-dir <abs>]
+ *
+ * Omit `--agent` to install for all known agents in one pass.
+ */
+import process from 'node:process'
+import { parseArgs } from 'node:util'
+
+import { createJiti } from 'jiti'
+
+const jiti = createJiti(import.meta.url, { interopDefault: true })
+const { setupAgentSkills, resetSkillsCache } = await jiti.import('../../src/context.js')
+
+// Axis adapter name → orchestrator runner key (matches `AGENT_SKILLS_DIRS` in src/context.js).
+const RUNNER_BY_AGENT = {
+  'claude-code': 'claude',
+  codex: 'codex',
+  gemini: 'gemini',
+}
+
+const ALL_AGENTS = Object.keys(RUNNER_BY_AGENT)
+
+const main = async () => {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      agent: { type: 'string' },
+      'target-dir': { type: 'string' },
+    },
+    strict: false,
+  })
+
+  const agents = values.agent ? [values.agent] : ALL_AGENTS
+
+  for (const agent of agents) {
+    const runner = RUNNER_BY_AGENT[agent] ?? agent
+    resetSkillsCache()
+    const installed = await setupAgentSkills(runner, values['target-dir'] ? { targetDir: values['target-dir'] } : {})
+    process.stderr.write(`[install-skills] ${runner}: ${installed.length} skill(s)\n`)
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`[install-skills] error: ${err.message ?? err}\n`)
+  process.exit(1)
+})