@sanity/ailf 2.0.0 → 2.0.1

package/dist/tasks/literacy/functions.task.ts

@@ -0,0 +1,70 @@
+import { defineTask } from "../../_vendor/ailf-core/index.js"
+
+// See content-lake.task.ts for detailed explanations of common task properties
+export default [
+  defineTask({
+    id: "functions-webhook",
+    mode: "literacy",
+    title: "Functions - Webhook on document publish",
+    description: "Functions - Webhook on document publish",
+    area: "functions",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "functions-introduction",
+          reason: "Functions overview — deployment, triggers, lifecycle",
+        },
+        {
+          slug: "webhooks",
+          reason: "GROQ-powered webhooks — configuration and filtering",
+        },
+        {
+          slug: "function-wrapper",
+          reason: "Function handler reference — event shape, exports",
+        },
+        {
+          slug: "functions-cheatsheet",
+          reason: "Quick reference for common function patterns",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/functions/publish-webhook.ts",
+    prompt: {
+      vars: {
+        task: `Deploy a Sanity function that triggers when a document is published
+and sends a webhook notification to an external endpoint.
+
+Requirements:
+1. The function should trigger on document publish events
+2. Filter to only fire for "post" document types
+3. Send a POST request to an external URL with the document data
+4. Handle errors gracefully
+
+Provide a complete implementation including any configuration.`,
+        docs: "file://contexts/canonical/functions-webhook.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "Event-driven function definition",
+          "Document type filtering (post type only)",
+          "HTTP webhook call with document payload",
+          "Basic error handling",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "No deprecated API patterns",
+          "Proper error handling",
+          "Idiomatic function handler structure",
+        ],
+      },
+    ],
+  }),
+]

package/dist/tasks/literacy/groq.task.ts

@@ -0,0 +1,259 @@
+import { defineTask } from "../../_vendor/ailf-core/index.js"
+
+// See content-lake.task.ts for detailed explanations of common task properties
+export default [
+  defineTask({
+    id: "groq-blog-queries",
+    mode: "literacy",
+    title: "GROQ - Blog queries with filtering and pagination",
+    description: "GROQ - Blog queries with filtering and pagination",
+    area: "groq",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "groq-introduction",
+          reason: "GROQ overview — syntax, filters, projections, core concepts",
+        },
+        {
+          slug: "how-queries-work",
+          reason: "Detailed walkthrough of GROQ query mechanics",
+        },
+        {
+          slug: "query-cheat-sheet",
+          reason: "Ready-made query patterns for common use cases",
+        },
+        {
+          slug: "paginating-with-groq",
+          reason: "Pagination patterns with slice syntax",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/groq/blog-queries.ts",
+    prompt: {
+      vars: {
+        task: `Write GROQ queries for a Sanity blog application:
+
+1. Fetch all published blog posts ordered by publishedAt descending,
+   with a projection that includes: _id, title, slug (from slug.current),
+   publishedAt, excerpt, and the author's name (resolved from a reference)
+2. Add pagination to return only the first 10 results
+3. Fetch a single post by its slug parameter, including the full body
+   content and resolved author and category references
+4. Fetch posts published after a specific date
+5. Fetch posts that belong to a specific category (where categories
+   is an array of references)
+
+Use @sanity/client with client.fetch() for all queries. Include
+TypeScript types for the query results.`,
+        docs: "file://contexts/canonical/groq-blog-queries.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          'GROQ filter with _type == "post"',
+          'Projection with aliased slug field ("slug": slug.current)',
+          "Reference resolution with -> for author",
+          "Ordering with | order(publishedAt desc)",
+          "Slice/pagination syntax [0...10] or [0..9]",
+          "Parameterized query with $slug for single post fetch",
+          "Date filtering with dateTime() or string comparison",
+          "Category filtering using references or array contains",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Valid GROQ syntax (proper filter brackets, projection braces)",
+          "Uses @sanity/client createClient + client.fetch()",
+          "Correct parameter passing syntax ($param)",
+          "Proper reference dereference with ->",
+          "No deprecated patterns",
+        ],
+      },
+      {
+        type: "contains-any",
+        value: ["client.fetch", "createClient"],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: ["order(publishedAt", "order(_createdAt", "| order("],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: ["[0...10]", "[0..9]", "[0..."],
+        weight: 1,
+      },
+    ],
+  }),
+
+  defineTask({
+    id: "groq-joins-references",
+    mode: "literacy",
+    title: "GROQ - Joins and reference resolution",
+    description: "GROQ - Joins and reference resolution",
+    area: "groq",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "groq-joins",
+          reason: "Join patterns — ->, []-> , subqueries, parent scope (^)",
+        },
+        {
+          slug: "how-queries-work",
+          reason: "Core query mechanics including reference traversal",
+        },
+        {
+          slug: "groq-introduction",
+          reason: "Overview including reference resolution basics",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/groq/joins-references.ts",
+    prompt: {
+      vars: {
+        task: `Write GROQ queries that demonstrate join patterns in Sanity:
+
+1. Follow a single reference to resolve an author's full profile
+   from a post (post.author -> author document with name, bio, image)
+2. Resolve an array of category references from a post
+   (post.categories[]-> with title and slug)
+3. Write a reverse reference query: given an author's ID, find all
+   posts by that author using a subquery and the parent scope operator (^)
+4. Create a nested join: for each author, include their 5 most recent
+   posts as a nested array
+5. Use the references() function to find all documents that reference
+   a specific document ID
+
+Use @sanity/client with client.fetch(). Include TypeScript types.`,
+        docs: "file://contexts/canonical/groq-joins-references.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "Single reference follow with -> operator",
+          "Array reference resolution with []->",
+          "Reverse reference / subquery using *[references(^._id)]",
+          "Nested join pattern with parent scope (^)",
+          "The references() function",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Correct -> dereference syntax",
+          "Valid []-> array dereference",
+          "Proper use of ^ parent scope operator",
+          "Valid references() function usage",
+          "No made-up syntax",
+        ],
+      },
+      { type: "contains", value: "->", weight: 1 },
+      {
+        type: "contains-any",
+        value: ["references(", "references(^"],
+        weight: 1,
+      },
+    ],
+  }),
+
+  defineTask({
+    id: "groq-advanced-filtering",
+    mode: "literacy",
+    title: "GROQ - Advanced filtering and projections",
+    description: "GROQ - Advanced filtering and projections",
+    area: "groq",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "groq-functions",
+          reason:
+            "GROQ function reference — select(), coalesce(), count(), defined()",
+        },
+        {
+          slug: "query-cheat-sheet",
+          reason: "Common filtering patterns and match operator examples",
+        },
+        {
+          slug: "groq-operators",
+          reason: "Operator reference — match, comparison, logical operators",
+        },
+        {
+          slug: "how-queries-work",
+          reason: "Query mechanics including projections and ordering",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/groq/advanced-filtering.ts",
+    prompt: {
+      vars: {
+        task: `Write GROQ queries demonstrating advanced filtering and projection patterns:
+
+1. Use select() for conditional projections — return different fields
+   based on the document's _type (e.g., posts get excerpt, events get
+   date and venue)
+2. Use coalesce() for fallback values — e.g., use seoTitle if it
+   exists, otherwise fall back to title
+3. Use the match operator for full-text search in titles
+4. Use count() to count documents matching a filter and to count
+   items within an array field
+5. Use defined() to filter for documents that have a specific field set
+6. Filter items within an array using [condition] syntax
+7. Order results by multiple fields (e.g., featured status first,
+   then by publishedAt)
+
+Use @sanity/client with client.fetch(). Include TypeScript types.`,
+        docs: "file://contexts/canonical/groq-advanced-filtering.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "select() for conditional projections",
+          "coalesce() for fallback values",
+          "match operator for text search",
+          "count() function usage",
+          "defined() function for existence checks",
+          "Array filtering with [condition]",
+          "Multi-field ordering",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Valid select() syntax with => arrow notation",
+          "Correct coalesce() usage",
+          "Proper match operator usage (on text fields)",
+          "Valid count() and defined() function calls",
+          "Correct array filter syntax",
+        ],
+      },
+      {
+        type: "contains-any",
+        value: ["select(", "coalesce("],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: ["count(", "defined("],
+        weight: 1,
+      },
+      { type: "contains-any", value: ["match"], weight: 1 },
+    ],
+  }),
+]

package/dist/tasks/literacy/image-handling.task.ts

@@ -0,0 +1,95 @@
+import { defineTask } from "../../_vendor/ailf-core/index.js"
+
+// See content-lake.task.ts for detailed explanations of common task properties
+export default [
+  defineTask({
+    id: "image-asset-pipeline",
+    mode: "literacy",
+    title:
+      "Image Handling - URL builder with transforms, hotspot/crop, responsive images",
+    description:
+      "Image Handling - URL builder with transforms, hotspot/crop, responsive images",
+    area: "image-handling",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "image-urls",
+          reason: "Image transformations — URL parameters, fit modes, format",
+        },
+        {
+          slug: "presenting-images",
+          reason: "Presenting images — best practices, responsive patterns",
+        },
+        {
+          slug: "image-type",
+          reason: "Image schema type — hotspot, crop, metadata fields",
+        },
+        {
+          slug: "js-client-assets",
+          reason: "Working with assets — upload, reference, URL generation",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/image-handling/asset-pipeline.tsx",
+    prompt: {
+      vars: {
+        task: `Build an image component for a Next.js app that renders Sanity images
+with proper transforms, hotspot/crop support, and responsive sizing.
+
+Requirements:
+1. Use @sanity/image-url to generate CDN URLs from image references
+2. Support hotspot and crop data from the image field
+3. Generate responsive srcSet with multiple widths
+4. Support format conversion (WebP with fallback)
+5. Create a reusable React component with TypeScript props
+
+Provide a complete implementation.`,
+        docs: "file://contexts/canonical/image-asset-pipeline.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "@sanity/image-url builder setup with project config",
+          "Hotspot and crop handling via .fit('crop') or equivalent",
+          "Responsive srcSet generation with multiple widths",
+          "WebP or auto format support",
+          "Reusable React component",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Correct @sanity/image-url API usage (imageUrlBuilder, .image(), .width(), etc.)",
+          "Proper hotspot/crop application (not ignoring crop metadata)",
+          "Valid srcSet syntax",
+          "No hardcoded CDN URLs (uses builder)",
+        ],
+      },
+      {
+        type: "contains-any",
+        value: ["@sanity/image-url", "imageUrlBuilder", "image-url"],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: ["srcSet", "srcset", "sizes"],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: ["hotspot", "crop", ".fit("],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: [".width(", ".height(", ".size("],
+        weight: 1,
+      },
+    ],
+  }),
+]

package/dist/tasks/literacy/nextjs-live.task.ts

@@ -0,0 +1,76 @@
+import { defineTask } from "../../_vendor/ailf-core/index.js"
+
+// See content-lake.task.ts for detailed explanations of common task properties
+export default [
+  defineTask({
+    id: "nextjs-app-router-integration",
+    mode: "literacy",
+    title: "Next.js - App Router integration with TypeScript",
+    description: "Next.js - App Router integration with TypeScript",
+    area: "nextjs-live",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "next-js-app-router-quickstart",
+          reason: "Primary Next.js App Router quickstart guide",
+        },
+        {
+          slug: "diplaying-content-in-next-js",
+          reason: "Fetching and displaying Sanity content in Next.js",
+        },
+        {
+          slug: "sanity-typegen",
+          reason: "TypeGen — generating TypeScript types from GROQ queries",
+        },
+        {
+          slug: "groq-introduction",
+          reason: "GROQ query language introduction",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/nextjs/app-router-integration.tsx",
+    prompt: {
+      vars: {
+        task: `Integrate Sanity into a Next.js 16 App Router application
+with full TypeScript support:
+
+1. Set up the Sanity client with proper configuration
+2. Create a typed GROQ query for fetching blog posts
+3. Build a server component that fetches and renders posts
+4. Generate TypeScript types using sanity typegen
+
+Provide all files needed for a working integration.`,
+        docs: "file://contexts/canonical/nextjs-app-router-integration.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "Sanity client configuration (createClient)",
+          "GROQ query with proper syntax",
+          "Next.js App Router server component using async/await",
+          "TypeScript type definitions or typegen setup",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Uses @sanity/client (not deprecated packages)",
+          "App Router patterns (not Pages Router)",
+          "Proper server component data fetching (no useEffect)",
+          "Valid GROQ query syntax",
+        ],
+      },
+      { type: "contains", value: "createClient", weight: 1 },
+      {
+        type: "contains-any",
+        value: ["groq", "GROQ", "*["],
+        weight: 1,
+      },
+    ],
+  }),
+]

package/dist/tasks/literacy/portable-text.task.ts

@@ -0,0 +1,169 @@
+import { defineTask } from "../../_vendor/ailf-core/index.js"
+
+// See content-lake.task.ts for detailed explanations of common task properties
+export default [
+  defineTask({
+    id: "portable-text-rendering",
+    mode: "literacy",
+    title: "Portable Text - Render rich text in React with custom components",
+    description:
+      "Portable Text - Render rich text in React with custom components",
+    area: "portable-text",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "previewing-block-content",
+          reason: "Previewing Portable Text — rendering in frontends",
+        },
+        {
+          slug: "customizing-block-content",
+          reason:
+            "Common PT editor patterns — custom blocks, marks, annotations",
+        },
+        {
+          slug: "presenting-images",
+          reason: "Presenting images — needed for inline image blocks in PT",
+        },
+        {
+          slug: "image-urls",
+          reason: "Image URL builder for transforming image references in PT",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/portable-text/rendering.tsx",
+    prompt: {
+      vars: {
+        task: `Render Portable Text content from Sanity in a React application using
+@portabletext/react.
+
+Requirements:
+1. Set up the PortableText component with custom components
+2. Handle image blocks with proper URL generation using @sanity/image-url
+3. Handle link marks (both internal and external links)
+4. Handle code blocks with syntax highlighting markup
+5. Provide TypeScript types for the component props
+
+Provide a complete, reusable implementation.`,
+        docs: "file://contexts/canonical/portable-text-rendering.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "PortableText component from @portabletext/react",
+          "Custom component map with image, link, and code block handlers",
+          "Image URL generation from Sanity image references",
+          "TypeScript types for props and component definitions",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Uses @portabletext/react (not deprecated @sanity/block-content-to-react)",
+          "Correct component map shape (types, marks, block, list, listItem)",
+          "Proper image URL builder usage with hotspot/crop support",
+          "No deprecated APIs or patterns",
+        ],
+      },
+      { type: "contains", value: "PortableText", weight: 1 },
+      {
+        type: "contains-any",
+        value: ["@portabletext/react", "portabletext/react"],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: ["components", "serializers"],
+        weight: 1,
+      },
+      // not-contains: FAILS the assertion if the string appears — penalizes deprecated APIs
+      {
+        type: "not-contains",
+        value: "@sanity/block-content-to-react",
+        weight: 1,
+      },
+      { type: "not-contains", value: "BlockContent", weight: 1 },
+    ],
+  }),
+
+  defineTask({
+    id: "portable-text-custom-blocks",
+    mode: "literacy",
+    title: "Portable Text - Define and render custom block types",
+    description: "Portable Text - Define and render custom block types",
+    area: "portable-text",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "customizing-the-portable-text-editor",
+          reason: "Customizing the PT editor — adding custom block types",
+        },
+        {
+          slug: "customizing-block-content",
+          reason: "Common PT patterns — custom blocks, decorators, annotations",
+        },
+        {
+          slug: "portable-text-editor-configuration",
+          reason: "PT editor configuration — styles, lists, marks, of array",
+        },
+        {
+          slug: "previewing-block-content",
+          reason: "Previewing PT — rendering custom blocks in frontends",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/portable-text/custom-blocks.ts",
+    prompt: {
+      vars: {
+        task: `Define custom block types for a Portable Text field and render them
+in a React frontend.
+
+Requirements:
+1. Add a "code" block type with language and code fields
+2. Add a "callout" block type with tone (info/warning/error) and text
+3. Define the schema using defineArrayMember in a Sanity schema file
+4. Show how to render these custom blocks with @portabletext/react
+
+Provide both the schema definition and the frontend rendering code.`,
+        docs: "file://contexts/canonical/portable-text-custom-blocks.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "Code block type with language and code fields",
+          "Callout block type with tone and text",
+          "Schema defined with defineArrayMember or equivalent",
+          "Frontend rendering for both custom block types",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Correct defineArrayMember usage for custom blocks",
+          'Proper "of" array structure in the PT field',
+          "Custom component map handles both block types",
+          "No deprecated schema patterns",
+        ],
+      },
+      {
+        type: "contains-any",
+        value: ["defineArrayMember", "defineField"],
+        weight: 1,
+      },
+      {
+        type: "contains-any",
+        value: ["components", "serializers"],
+        weight: 1,
+      },
+    ],
+  }),
+]