@sanity/ailf 0.5.0 → 1.0.0

package/tasks/literacy/groq.task.ts

@@ -0,0 +1,258 @@
+import { defineTask } from "@sanity/ailf-core"
+
+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/tasks/literacy/nextjs-live.task.ts

@@ -0,0 +1,75 @@
+import { defineTask } from "@sanity/ailf-core"
+
+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",
+    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/tasks/literacy/studio-setup.task.ts

@@ -0,0 +1,131 @@
+import { defineTask } from "@sanity/ailf-core"
+
+export default [
+  defineTask({
+    id: "studio-blog-schema",
+    mode: "literacy",
+    title: "Studio Setup - Blog schema with posts, authors, categories",
+    description: "Studio Setup - Blog schema with posts, authors, categories",
+    area: "studio",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "schemas-and-forms",
+          reason: "High-level overview of schemas and the form builder",
+        },
+        {
+          slug: "introduction-to-schemas",
+          reason: "Introduces schema concepts, defineType/defineField",
+        },
+        {
+          slug: "config-api-reference",
+          reason:
+            "Configuration API — defineConfig, plugins, schema registration",
+        },
+        {
+          slug: "reference-type",
+          reason: "Reference field type for author/category relationships",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/studio-setup/blog-schema.ts",
+    prompt: {
+      vars: {
+        task: `Set up a new Sanity Studio with a custom schema for a blog:
+
+1. Create document types for: posts, authors, categories
+2. Posts should have: title, slug, body (portable text), author reference, categories array
+3. Authors should have: name, bio, image
+4. Categories should have: title, description
+
+Include the schema definitions and sanity.config.ts setup.`,
+        docs: "file://contexts/canonical/studio-blog-schema.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "Three document types (post, author, category)",
+          "Post with all required fields including portable text body",
+          "Reference from post to author",
+          "Array of references from post to categories",
+          "sanity.config.ts with schema registration",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Uses defineConfig, defineType, defineField (v3 syntax)",
+          "Does NOT use createSchema (deprecated v2)",
+          "Proper reference syntax with 'to' array",
+          "Correct portable text array definition",
+        ],
+      },
+      { type: "contains", value: "defineConfig", weight: 1 },
+      { type: "contains", value: "defineType", weight: 1 },
+      { type: "contains", value: "defineField", weight: 1 },
+      { type: "not-contains", value: "createSchema", weight: 1 },
+      { type: "not-contains", value: "import Schema from", weight: 1 },
+    ],
+  }),
+
+  defineTask({
+    id: "studio-custom-tool",
+    mode: "literacy",
+    title: "Studio Setup - Custom tool in sidebar",
+    description: "Studio Setup - Custom tool in sidebar",
+    area: "studio",
+    context: {
+      docs: [
+        {
+          slug: "studio-tools",
+          reason: "Overview of Studio tools system",
+        },
+        {
+          slug: "tool-api-reference",
+          reason: "Tool API — name, title, icon, component properties",
+        },
+        {
+          slug: "custom-studio-tool",
+          reason: "Step-by-step guide for creating a custom tool",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/studio-setup/custom-tool.tsx",
+    prompt: {
+      vars: {
+        task: `Add a custom tool to the Sanity Studio sidebar that displays
+a dashboard. The tool should:
+
+1. Appear in the studio navigation with a custom icon
+2. Have a title and name
+3. Render a React component showing a "Dashboard" heading
+
+Provide the tool definition and sanity.config.ts registration.`,
+        docs: "file://contexts/canonical/studio-custom-tool.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "Tool object with name, title, icon, component",
+          "React component for the tool UI",
+          "Registration in sanity.config.ts tools array",
+        ],
+      },
+      { type: "contains", value: "tools", weight: 1 },
+      {
+        type: "javascript",
+        value: `return output.includes('name:') &&
+        output.includes('component') &&
+        (output.includes('icon:') || output.includes('Icon'))`,
+      },
+    ],
+  }),
+]

package/tasks/literacy/visual-editing.task.ts

@@ -0,0 +1,146 @@
+import { defineTask } from "@sanity/ailf-core"
+
+export default [
+  defineTask({
+    id: "visual-editing-presentation",
+    mode: "literacy",
+    title: "Visual Editing - Presentation tool with click-to-edit",
+    description: "Visual Editing - Presentation tool with click-to-edit",
+    area: "visual-editing",
+    docCoverage: true,
+    context: {
+      docs: [
+        {
+          slug: "configuring-the-presentation-tool",
+          reason: "Core presentationTool configuration and setup",
+        },
+        {
+          slug: "introduction-to-visual-editing",
+          reason: "Visual Editing concepts — stega, overlays, data attributes",
+        },
+        {
+          slug: "visual-editing-with-next-js-app-router",
+          reason: "Next.js App Router-specific visual editing guide",
+        },
+        {
+          slug: "stega",
+          reason: "Stega encoding for click-to-edit data attributes",
+        },
+      ],
+    },
+    referenceSolution:
+      "reference-solutions/visual-editing/presentation-nextjs.tsx",
+    prompt: {
+      vars: {
+        task: `Set up the Presentation tool with a Next.js 14 (App Router) frontend
+and implement click-to-edit functionality:
+
+1. Configure the Presentation tool in sanity.config.ts
+2. Set up the Next.js app to work with Visual Editing
+3. Implement data attributes so clicking content in the preview
+   opens the corresponding field in Studio
+
+Provide all necessary code for both Studio and Next.js sides.`,
+        docs: "file://contexts/canonical/visual-editing-presentation.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "presentationTool configured in sanity.config.ts",
+          "previewUrl or equivalent configured",
+          "Data attributes for click-to-edit (createDataAttribute or stega)",
+          "Next.js App Router patterns used correctly",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Uses @sanity/presentation (not deprecated packages)",
+          "Uses createDataAttribute or stega encoding correctly",
+          "Proper Next.js App Router patterns (not Pages Router)",
+          "No mixing of deprecated and current APIs",
+        ],
+      },
+      { type: "contains", value: "presentationTool", weight: 1 },
+      {
+        type: "contains-any",
+        value: [
+          "createDataAttribute",
+          "data-sanity",
+          "encodeDataAttribute",
+          "stega",
+        ],
+        weight: 1,
+      },
+      { type: "not-contains", value: "@sanity/preview-kit", weight: 1 },
+    ],
+  }),
+
+  defineTask({
+    id: "visual-editing-live-preview",
+    mode: "literacy",
+    title: "Visual Editing - Live preview with draft content",
+    description: "Visual Editing - Live preview with draft content",
+    area: "visual-editing",
+    context: {
+      docs: [
+        {
+          slug: "live-content-api",
+          reason: "Live Content API — defineLive, real-time subscriptions",
+        },
+        {
+          slug: "perspectives",
+          reason: "Draft vs published perspectives",
+        },
+        {
+          slug: "fetching-content-for-visual-editing",
+          reason: "Data fetching patterns for visual editing contexts",
+        },
+      ],
+    },
+    referenceSolution: "reference-solutions/visual-editing/live-preview.tsx",
+    prompt: {
+      vars: {
+        task: `Implement live preview in a Next.js app that shows draft content
+from Sanity in real-time as editors make changes in the Studio.
+
+Requirements:
+- Use the Live Content API approach
+- Handle draft vs published perspectives correctly
+- Show real-time updates without page refresh
+
+Provide a complete implementation.`,
+        docs: "file://contexts/canonical/visual-editing-live-preview.md",
+      },
+    },
+    assertions: [
+      {
+        type: "llm-rubric",
+        template: "task-completion",
+        criteria: [
+          "Live Content API usage (defineLive, useLiveQuery, or sanityFetch with live option)",
+          "Draft perspective configuration",
+          "Real-time subscription/update mechanism",
+        ],
+      },
+      {
+        type: "llm-rubric",
+        template: "code-correctness",
+        criteria: [
+          "Modern API usage (not deprecated preview packages)",
+          "Proper perspective handling",
+          "Correct subscription lifecycle management",
+        ],
+      },
+      {
+        type: "contains-any",
+        value: ["useLiveQuery", "defineLive", "live:", "perspective"],
+        weight: 1,
+      },
+    ],
+  }),
+]