@sanity/ailf 0.1.28 → 0.1.30

package/dist/_vendor/ailf-core/ports/context.d.ts

@@ -35,6 +35,8 @@ export interface ResolvedConfig {
     areas?: string[];
     /** Task ID filter */
     tasks?: string[];
+    /** Tag filter — tasks must have at least one matching tag */
+    tags?: string[];
     /** Changed doc slugs for impact scoping */
     changedDocs?: string[];
     /** Documentation source name */

package/dist/_vendor/ailf-core/ports/task-source.d.ts

@@ -112,6 +112,8 @@ export interface TaskDefinition {
     baseline?: BaselineConfig;
     /** Additional template variables beyond task (e.g., custom vars) */
     extraVars?: Record<string, unknown>;
+    /** Freeform labels for filtering and organization */
+    tags?: string[];
 }
 /** Check if a canonical doc ref resolves by slug.
  *

package/dist/_vendor/ailf-core/types/index.d.ts

@@ -179,6 +179,8 @@ export interface FeatureScore {
 export interface FilterOptions {
     /** Feature areas to include (filename stems, e.g., ["groq", "frameworks"]) */
     areas?: string[];
+    /** Tags to include — tasks must have at least one matching tag */
+    tags?: string[];
     /** Specific task IDs to include (e.g., ["groq-blog-queries"]) */
     taskIds?: string[];
 }

package/dist/adapters/api-client/build-request.d.ts

@@ -35,6 +35,7 @@ export interface RemoteConfigSlice {
     };
     areas?: string[];
     tasks?: string[];
+    tags?: string[];
     changedDocs?: string[];
     source?: string;
     compareEnabled?: boolean;

package/dist/adapters/api-client/build-request.js

@@ -167,12 +167,16 @@ function taskToInlineFormat(task) {
     if (task.baseline) {
         inline.baseline = task.baseline;
     }
+    if (task.tags?.length) {
+        inline.tags = task.tags;
+    }
     return inline;
 }
 function buildFilterOptions(config) {
     const areas = config.areas?.length ? config.areas : undefined;
     const taskIds = config.tasks?.length ? config.tasks : undefined;
-    if (!areas && !taskIds)
+    const tags = config.tags?.length ? config.tags : undefined;
+    if (!areas && !taskIds && !tags)
         return undefined;
-    return { areas, taskIds };
+    return { areas, taskIds, tags };
 }

package/dist/adapters/task-sources/content-lake-task-source.js

@@ -32,6 +32,7 @@ const TASKS_QUERY = /* groq */ `
   && (!defined($areas) || featureArea->areaId.current in $areas)
   && (!defined($taskIds) || id.current in $taskIds)
   && (execution.enabled != false)
+  && (!defined($tags) || count((tags)[@ in $tags]) > 0)
 ] | order(featureArea->areaId.current asc, id.current asc) {
   "taskId": id.current,
   description,
@@ -51,6 +52,7 @@ const TASKS_QUERY = /* groq */ `
   assert,
   rawAssert,
   baseline,
+  tags,
   "referenceSolutionTitle": referenceSolution->title
 }
 `;
@@ -90,6 +92,7 @@ function buildGroqParams(filter) {
         areas: filter?.areas && filter.areas.length > 0
             ? filter.areas.map((a) => a.toLowerCase())
             : null,
+        tags: filter?.tags && filter.tags.length > 0 ? filter.tags : null,
         taskIds: filter?.taskIds && filter.taskIds.length > 0 ? filter.taskIds : null,
     };
 }
@@ -116,6 +119,21 @@ function mapToTaskDefinition(raw) {
         .map(mapCanonicalDocRef)
         .filter((d) => d !== null);
     const assertions = mapAssertions(raw.assert ?? []);
+    // Append raw pass-through assertions (escape hatch for arbitrary Promptfoo
+    // assertion types that aren't in the curated list). These bypass template
+    // resolution and flow directly into the expanded Promptfoo test case as
+    // value-based assertions. In baseline mode, buildBaselineAsserts() with
+    // "abbreviated" (the default) drops non-rubric assertions, so rawAssert
+    // entries only run in the gold variant — consistent with how regular
+    // value-based assertions like `contains` or `regex` behave.
+    const rawAssertions = (raw.rawAssert ?? [])
+        .filter((a) => !!a.type)
+        .map((a) => ({
+        type: a.type,
+        ...(a.value !== undefined ? { value: a.value } : {}),
+        ...(a.threshold !== undefined ? { threshold: a.threshold } : {}),
+    }));
+    const allAssertions = [...assertions, ...rawAssertions];
     const baseline = raw.baseline
         ? {
             ...(raw.baseline.enabled !== undefined
@@ -129,7 +147,7 @@ function mapToTaskDefinition(raw) {
         }
         : undefined;
     return {
-        assertions,
+        assertions: allAssertions,
         canonicalDocs,
         description: raw.description,
         docCoverage: raw.docCoverage ?? false,
@@ -143,6 +161,7 @@ function mapToTaskDefinition(raw) {
         referenceSolution: "",
         taskPrompt: raw.taskPrompt,
         ...(baseline ? { baseline } : {}),
+        ...(raw.tags?.length ? { tags: raw.tags } : {}),
     };
 }
 /**

package/dist/adapters/task-sources/repo-task-source.js

@@ -79,6 +79,12 @@ export class RepoTaskSource {
                 if (entry.execution?.enabled === false) {
                     continue;
                 }
+                // Tag filter — skip tasks that don't match any requested tag
+                if (filter?.tags &&
+                    filter.tags.length > 0 &&
+                    (!entry.tags || !entry.tags.some((t) => filter.tags.includes(t)))) {
+                    continue;
+                }
                 definitions.push(mapToTaskDefinition(entry));
             }
         }
@@ -108,5 +114,6 @@ function mapToTaskDefinition(raw) {
         taskPrompt: typeof task === "string" ? task : "",
         ...(raw.baseline ? { baseline: raw.baseline } : {}),
         ...(extraVars ? { extraVars } : {}),
+        ...(raw.tags?.length ? { tags: raw.tags } : {}),
     };
 }

package/dist/cli.d.ts

@@ -5,6 +5,11 @@
  * Unified command-line interface for the AI Literacy Framework.
  * All evaluation commands are exposed as subcommands under `ailf`.
  *
+ * Commands are organized into semantic groups (Core Workflow, Analysis &
+ * Reports, etc.) using Commander v14's native `helpGroup()` API. The
+ * custom help formatter in `./commands/shared/help.ts` adds styling and
+ * appends Quick Start examples.
+ *
  * Usage:
  *   ailf pipeline [flags]       # full evaluation pipeline
  *   ailf compare [flags]        # compare evaluation runs

package/dist/cli.js

@@ -7,6 +7,11 @@
  * Unified command-line interface for the AI Literacy Framework.
  * All evaluation commands are exposed as subcommands under `ailf`.
  *
+ * Commands are organized into semantic groups (Core Workflow, Analysis &
+ * Reports, etc.) using Commander v14's native `helpGroup()` API. The
+ * custom help formatter in `./commands/shared/help.ts` adds styling and
+ * appends Quick Start examples.
+ *
  * Usage:
  *   ailf pipeline [flags]       # full evaluation pipeline
  *   ailf compare [flags]        # compare evaluation runs
@@ -74,12 +79,13 @@ else if (process.argv.includes("--quiet") || process.argv.includes("-q")) {
 // Build CLI program
 // ---------------------------------------------------------------------------
 import { Command } from "commander";
+import { CommandGroup, configureProgram } from "./commands/shared/help.js";
 // Read version from package.json
 const pkgPath = resolve(ROOT, "package.json");
 const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
 const program = new Command()
     .name("ailf")
-    .description("AI Literacy Framework — evaluate how well docs enable AI coding tools")
+    .description("AI Literacy Framework — evaluate how well docs enable AI coding tools\n\nMeasure whether AI coding agents can find the right documentation\nand produce correct implementations of your product features.")
     .version(pkg.version)
     .option("-v, --verbose", "Increase log output")
     .option("-q, --quiet", "Suppress non-error output")
@@ -87,6 +93,7 @@ const program = new Command()
     .option("--explain", "Show execution plan without running")
     .option("--format <fmt>", "Output format for --explain (console, json)", "console")
     .option("-y, --yes", "With --explain: show plan then prompt to confirm execution");
+configureProgram(program);
 // ---------------------------------------------------------------------------
 // Global --explain hook — intercepts any command before execution
 // ---------------------------------------------------------------------------
@@ -114,85 +121,72 @@ program.hook("preAction", async (thisCommand, actionCommand) => {
 });
 // ---------------------------------------------------------------------------
 // Register commands
+//
+// Registration order determines group display order in --help.
+// Within each group, commands appear in the order they are added.
 // ---------------------------------------------------------------------------
-// Pipeline — the main orchestrator
+// ── Core Workflow ──────────────────────────────────────────────────────
 import { createPipelineCommand } from "./commands/pipeline.js";
-program.addCommand(createPipelineCommand());
-// Compare — structured score comparison
+program.addCommand(createPipelineCommand().helpGroup(CommandGroup.CoreWorkflow));
 import { createCompareCommand } from "./commands/compare.js";
-program.addCommand(createCompareCommand());
-// Baseline — save/compare/history
+program.addCommand(createCompareCommand().helpGroup(CommandGroup.CoreWorkflow));
 import { createBaselineCommand } from "./commands/baseline.js";
-program.addCommand(createBaselineCommand());
-// Validate — config validation
-import { createValidateCommand } from "./commands/validate.js";
-program.addCommand(createValidateCommand());
-// Coverage audit — feature coverage analysis
-import { createCoverageAuditCommand } from "./commands/coverage-audit.js";
-program.addCommand(createCoverageAuditCommand());
-// Weekly digest — trend digest delivery
-import { createWeeklyDigestCommand } from "./commands/weekly-digest.js";
-program.addCommand(createWeeklyDigestCommand());
-// Readiness report — launch readiness checklist
+program.addCommand(createBaselineCommand().helpGroup(CommandGroup.CoreWorkflow));
+import { createPublishCommand } from "./commands/publish.js";
+program.addCommand(createPublishCommand().helpGroup(CommandGroup.CoreWorkflow));
+// ── Analysis & Reports ────────────────────────────────────────────────
 import { createReadinessReportCommand } from "./commands/readiness-report.js";
-program.addCommand(createReadinessReportCommand());
-// Discovery report — agent discoverability analysis
+program.addCommand(createReadinessReportCommand().helpGroup(CommandGroup.AnalysisReports));
+import { createCoverageAuditCommand } from "./commands/coverage-audit.js";
+program.addCommand(createCoverageAuditCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createDiscoveryReportCommand } from "./commands/discovery-report.js";
-program.addCommand(createDiscoveryReportCommand());
-// Grader — reliability tools (consistency, compare, sensitivity, validate)
+program.addCommand(createDiscoveryReportCommand().helpGroup(CommandGroup.AnalysisReports));
+import { createAgentReportCommand } from "./commands/agent-report.js";
+program.addCommand(createAgentReportCommand().helpGroup(CommandGroup.AnalysisReports));
+import { createWeeklyDigestCommand } from "./commands/weekly-digest.js";
+program.addCommand(createWeeklyDigestCommand().helpGroup(CommandGroup.AnalysisReports));
+// ── Grader Reliability ────────────────────────────────────────────────
 import { createGraderCommand } from "./commands/grader/index.js";
-program.addCommand(createGraderCommand());
-// Fetch docs — pull documentation from Sanity CMS
+program.addCommand(createGraderCommand().helpGroup(CommandGroup.GraderReliability));
+// ── Setup & Configuration ─────────────────────────────────────────────
+import { createInitCommand } from "./commands/init.js";
+program.addCommand(createInitCommand().helpGroup(CommandGroup.SetupConfig));
+import { createValidateCommand } from "./commands/validate.js";
+program.addCommand(createValidateCommand().helpGroup(CommandGroup.SetupConfig));
+import { createValidateTasksCommand } from "./commands/validate-tasks.js";
+program.addCommand(createValidateTasksCommand().helpGroup(CommandGroup.SetupConfig));
 import { createFetchDocsCommand } from "./commands/fetch-docs.js";
-program.addCommand(createFetchDocsCommand());
-// Generate configs — generate promptfoo config files
+program.addCommand(createFetchDocsCommand().helpGroup(CommandGroup.SetupConfig));
 import { createGenerateConfigsCommand } from "./commands/generate-configs.js";
-program.addCommand(createGenerateConfigsCommand());
-// Calculate scores — compute AI Literacy Scores from eval results
-import { createCalculateScoresCommand } from "./commands/calculate-scores.js";
-program.addCommand(createCalculateScoresCommand());
-// Eval — direct promptfoo eval passthrough
+program.addCommand(createGenerateConfigsCommand().helpGroup(CommandGroup.SetupConfig));
+import { createCacheCommand } from "./commands/cache.js";
+program.addCommand(createCacheCommand().helpGroup(CommandGroup.SetupConfig));
+// ── Pipeline Internals ────────────────────────────────────────────────
 import { createEvalCommand } from "./commands/eval.js";
-program.addCommand(createEvalCommand());
-// PR comment — generate markdown PR comment
+program.addCommand(createEvalCommand().helpGroup(CommandGroup.PipelineInternals));
+import { createCalculateScoresCommand } from "./commands/calculate-scores.js";
+program.addCommand(createCalculateScoresCommand().helpGroup(CommandGroup.PipelineInternals));
 import { createPrCommentCommand } from "./commands/pr-comment.js";
-program.addCommand(createPrCommentCommand());
-// Publish — standalone report publishing to Sanity Content Lake
-import { createPublishCommand } from "./commands/publish.js";
-program.addCommand(createPublishCommand());
-// Agent report — agent behavior observation report
-import { createAgentReportCommand } from "./commands/agent-report.js";
-program.addCommand(createAgentReportCommand());
-// Cache — local pipeline cache management
-import { createCacheCommand } from "./commands/cache.js";
-program.addCommand(createCacheCommand());
-// Webhook server — local development server
-import { createWebhookServerCommand } from "./commands/webhook-server.js";
-program.addCommand(createWebhookServerCommand());
-// Lookup doc — search Sanity for documentation articles
-import { createLookupDocCommand } from "./commands/lookup-doc.js";
-program.addCommand(createLookupDocCommand());
-// Measure retrieval — retrieval quality measurement
+program.addCommand(createPrCommentCommand().helpGroup(CommandGroup.PipelineInternals));
 import { createMeasureRetrievalCommand } from "./commands/measure-retrieval.js";
-program.addCommand(createMeasureRetrievalCommand());
-// Init — initialize a directory for AILF
-import { createInitCommand } from "./commands/init.js";
-program.addCommand(createInitCommand());
-// Validate tasks — standalone repo task validation
-import { createValidateTasksCommand } from "./commands/validate-tasks.js";
-program.addCommand(createValidateTasksCommand());
-// Interactive — guided wizard
+program.addCommand(createMeasureRetrievalCommand().helpGroup(CommandGroup.PipelineInternals));
+import { createLookupDocCommand } from "./commands/lookup-doc.js";
+program.addCommand(createLookupDocCommand().helpGroup(CommandGroup.PipelineInternals));
+import { createWebhookServerCommand } from "./commands/webhook-server.js";
+program.addCommand(createWebhookServerCommand().helpGroup(CommandGroup.PipelineInternals));
+// ── Developer Tools ───────────────────────────────────────────────────
 import { createInteractiveCommand } from "./commands/interactive.js";
-program.addCommand(createInteractiveCommand());
+program.addCommand(createInteractiveCommand().helpGroup(CommandGroup.DeveloperTools));
 // Shell completion — must be registered last (needs full program tree)
 import { createCompletionCommand } from "./commands/completion.js";
-program.addCommand(createCompletionCommand(program));
+program.addCommand(createCompletionCommand(program).helpGroup(CommandGroup.DeveloperTools));
 // ---------------------------------------------------------------------------
-// Parse and run — default to interactive mode when no arguments given
+// Parse and run — default to showing help when no arguments given
 // ---------------------------------------------------------------------------
-// If no command is specified (just `ailf`), launch interactive mode
+// If no command is specified (just `ailf`), show help.
+// The interactive wizard is still available via `ailf interactive`.
 if (process.argv.length <= 2) {
-    await program.parseAsync([...process.argv, "interactive"]);
+    program.outputHelp();
 }
 else {
     await program.parseAsync();

package/dist/commands/explain-handler.js

@@ -688,6 +688,7 @@ async function buildPipelineExplainPlan(actionCommand, rootDir) {
         skipEval: raw.skipEval ?? false,
         skipFetch: raw.skipFetch ?? false,
         source: raw.source,
+        tag: raw.tag ?? [],
         task: raw.task,
         threshold: raw.threshold,
         url: raw.url ?? [],

package/dist/commands/pipeline-action.d.ts

@@ -54,6 +54,7 @@ export interface ResolvedOptions {
     remote: boolean;
     repoTasksPath?: string;
     taskOption?: string;
+    tagOption?: string[];
     taskSourceType?: "content-lake" | "repo" | "yaml";
     urlArgs: string[];
     apiUrl: string;

package/dist/commands/pipeline-action.js

@@ -126,6 +126,13 @@ export function computeResolvedOptions(opts) {
     // Scoping
     const areaOption = opts.area ?? process.env.EVAL_FILTER_AREAS ?? undefined;
     const taskOption = opts.task ?? process.env.EVAL_FILTER_TASKS ?? undefined;
+    const tagOption = opts.tag?.length
+        ? opts.tag
+        : process.env.EVAL_FILTER_TAGS
+            ? process.env.EVAL_FILTER_TAGS.split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : undefined;
     const changedDocsOption = opts.changedDocs ?? process.env.EVAL_CHANGED_DOCS ?? undefined;
     // Document-driven scoping (pure — computes impactSummary without env writes)
     let impactSummary;
@@ -237,6 +244,7 @@ export function computeResolvedOptions(opts) {
             ? resolve(callerCwd, opts.repoTasksPath)
             : undefined,
         taskOption,
+        tagOption,
         taskSourceType: resolveTaskSourceType(opts.taskSource),
         urlArgs,
     };

package/dist/commands/pipeline.d.ts

@@ -5,7 +5,7 @@
  * options object, bridges to process.env for downstream modules, and
  * delegates to runPipeline().
  *
- * @see docs/API.md for the full flag reference.
+ * @see docs/CLI.md for the full flag reference.
  */
 import { Command } from "commander";
 /**
@@ -56,6 +56,7 @@ export interface PipelineCliOptions {
     remote: boolean;
     repoTasksPath?: string;
     task?: string;
+    tag: string[];
     taskSource?: string;
     threshold?: number;
     url: string[];

package/dist/commands/pipeline.js

@@ -5,7 +5,7 @@
  * options object, bridges to process.env for downstream modules, and
  * delegates to runPipeline().
  *
- * @see docs/API.md for the full flag reference.
+ * @see docs/CLI.md for the full flag reference.
  */
 import { Command } from "commander";
 import { addAgenticOptions, addDebugOptions, addSanitySourceOptions, } from "./shared/options.js";
@@ -22,6 +22,13 @@ export function createPipelineCommand() {
         .option("--no-auto-scope", "Disable release-aware auto-scoping (evaluate all tasks even when a perspective is set)")
         .option("-a, --area <areas>", "Scope to feature areas (comma-separated)")
         .option("-t, --task <id>", "Scope to specific task ID")
+        .option("--tag <tags>", "Scope to tasks with matching tags (comma-separated, repeatable)", (val, prev) => [
+        ...prev,
+        ...val
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+    ], [])
         .option("--changed-docs <slugs>", "Auto-scope to tasks affected by these document slugs")
         .option("-j, --concurrency <n>", "Max parallel API calls during evaluation", parseInt)
         .option("--grader-replications <n>", "Grader consistency replications", parseInt)

package/dist/commands/shared/help.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Custom help configuration for the AILF CLI.
+ *
+ * Uses Commander v14's native help customization APIs:
+ * - `helpGroup()` on Command for grouped subcommand listings
+ * - `configureHelp()` with a custom Help subclass for styling
+ * - `addHelpText('after', ...)` for contextual examples
+ *
+ * This avoids ad-hoc console.log formatting and keeps help output
+ * consistent, testable, and automatically aligned with the command tree.
+ */
+import { type Command } from "commander";
+/**
+ * Semantic group headings displayed in `ailf --help`.
+ *
+ * Groups appear in the order their first member is registered with the
+ * program. Keep the registration order in cli.ts intentional.
+ */
+export declare const CommandGroup: {
+    readonly CoreWorkflow: "Core Workflow:";
+    readonly AnalysisReports: "Analysis & Reports:";
+    readonly GraderReliability: "Grader Reliability:";
+    readonly SetupConfig: "Setup & Configuration:";
+    readonly PipelineInternals: "Pipeline Internals:";
+    readonly DeveloperTools: "Developer Tools:";
+};
+export type CommandGroupHeading = (typeof CommandGroup)[keyof typeof CommandGroup];
+/**
+ * Apply help configuration to the root program.
+ *
+ * Call this once in cli.ts after creating the program but before
+ * registering commands. It:
+ * 1. Sets the custom Help formatter via `configureHelp()`
+ * 2. Appends Quick Start examples via `addHelpText('after', ...)`
+ * 3. Customizes the built-in help command description
+ */
+export declare function configureProgram(program: Command): void;

package/dist/commands/shared/help.js

@@ -0,0 +1,98 @@
+/**
+ * Custom help configuration for the AILF CLI.
+ *
+ * Uses Commander v14's native help customization APIs:
+ * - `helpGroup()` on Command for grouped subcommand listings
+ * - `configureHelp()` with a custom Help subclass for styling
+ * - `addHelpText('after', ...)` for contextual examples
+ *
+ * This avoids ad-hoc console.log formatting and keeps help output
+ * consistent, testable, and automatically aligned with the command tree.
+ */
+import { Help } from "commander";
+// ---------------------------------------------------------------------------
+// Command group headings
+// ---------------------------------------------------------------------------
+/**
+ * Semantic group headings displayed in `ailf --help`.
+ *
+ * Groups appear in the order their first member is registered with the
+ * program. Keep the registration order in cli.ts intentional.
+ */
+export const CommandGroup = {
+    CoreWorkflow: "Core Workflow:",
+    AnalysisReports: "Analysis & Reports:",
+    GraderReliability: "Grader Reliability:",
+    SetupConfig: "Setup & Configuration:",
+    PipelineInternals: "Pipeline Internals:",
+    DeveloperTools: "Developer Tools:",
+};
+// ---------------------------------------------------------------------------
+// Custom Help formatter
+// ---------------------------------------------------------------------------
+/**
+ * Extended Help class that adds subtle ANSI styling to section headings.
+ *
+ * Commander v14 calls these style methods during `formatHelp()`.
+ * Terminal emulators that don't support ANSI codes degrade gracefully
+ * (the escape sequences are invisible in raw-mode pipes like `| cat`).
+ */
+class AilfHelp extends Help {
+    /** Bold section titles (Options:, Commands:, group headings). */
+    styleTitle(str) {
+        if (!hasColorSupport())
+            return str;
+        return `\x1b[1m${str}\x1b[0m`;
+    }
+    /** Dim the description text slightly for visual hierarchy. */
+    styleDescriptionText(str) {
+        if (!hasColorSupport())
+            return str;
+        return `\x1b[2m${str}\x1b[0m`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Color support detection
+// ---------------------------------------------------------------------------
+/** Conservative check — disable color when piped or when NO_COLOR is set. */
+function hasColorSupport() {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR !== undefined)
+        return true;
+    return Boolean(process.stdout.isTTY);
+}
+// ---------------------------------------------------------------------------
+// After-help text (Quick Start + links)
+// ---------------------------------------------------------------------------
+const afterHelpText = `
+Quick Start:
+  $ ailf pipeline --debug          Run a quick evaluation (first 2 tests)
+  $ ailf pipeline --area groq      Evaluate a specific feature area
+  $ ailf pipeline --explain        Preview the execution plan
+  $ ailf init                      Set up AILF in a new project
+
+Documentation:
+  Repository   https://github.com/sanity-io/ai-literacy-framework
+  CLI Guide    https://github.com/sanity-io/ai-literacy-framework/blob/main/docs/CLI.md
+  Getting Started  https://github.com/sanity-io/ai-literacy-framework/blob/main/docs/GETTING_STARTED.md
+
+Run ailf <command> --help for detailed usage of any command.`;
+// ---------------------------------------------------------------------------
+// Program configuration
+// ---------------------------------------------------------------------------
+/**
+ * Apply help configuration to the root program.
+ *
+ * Call this once in cli.ts after creating the program but before
+ * registering commands. It:
+ * 1. Sets the custom Help formatter via `configureHelp()`
+ * 2. Appends Quick Start examples via `addHelpText('after', ...)`
+ * 3. Customizes the built-in help command description
+ */
+export function configureProgram(program) {
+    program
+        .configureHelp(new AilfHelp())
+        .addHelpText("after", afterHelpText)
+        .addHelpCommand("help [command]", "Show help for a command");
+}

package/dist/orchestration/build-app-context.js

@@ -30,6 +30,7 @@ export function mapToResolvedConfig(opts, rootDir) {
             ?.split(",")
             .map((s) => s.trim())
             .filter(Boolean),
+        tags: opts.tagOption,
         changedDocs: opts.changedDocsOption
             ?.split(",")
             .map((s) => s.trim())

package/dist/orchestration/steps/fetch-docs-step.js

@@ -121,12 +121,13 @@ export class FetchDocsStep {
 // Helpers
 // ---------------------------------------------------------------------------
 function buildFilter(ctx) {
-    const { areas, tasks } = ctx.config;
-    if (!areas && !tasks)
+    const { areas, tasks, tags } = ctx.config;
+    if (!areas && !tasks && !tags)
         return undefined;
     return {
         ...(areas ? { areas } : {}),
         ...(tasks ? { taskIds: tasks } : {}),
+        ...(tags ? { tags } : {}),
     };
 }
 /**

package/dist/orchestration/steps/generate-configs-step.js

@@ -28,8 +28,12 @@ export class GenerateConfigsStep {
         // repo-based, and YAML tasks depending on which adapter is wired.
         let tasks;
         try {
-            const filter = ctx.config.areas || ctx.config.tasks
-                ? { areas: ctx.config.areas, taskIds: ctx.config.tasks }
+            const filter = ctx.config.areas || ctx.config.tasks || ctx.config.tags
+                ? {
+                    areas: ctx.config.areas,
+                    taskIds: ctx.config.tasks,
+                    tags: ctx.config.tags,
+                }
                 : undefined;
             tasks = await ctx.taskSource.loadTasks(filter);
         }
@@ -54,10 +58,11 @@ export class GenerateConfigsStep {
         try {
             generateConfigs({
                 allowedOrigins: ctx.config.allowedOrigins,
-                filter: ctx.config.areas || ctx.config.tasks
+                filter: ctx.config.areas || ctx.config.tasks || ctx.config.tags
                     ? {
                         areas: ctx.config.areas,
                         taskIds: ctx.config.tasks,
+                        tags: ctx.config.tags,
                     }
                     : undefined,
                 resolvedSource,

package/dist/orchestration/steps/run-eval-step.js

@@ -40,10 +40,11 @@ export class RunEvalStep {
         // Precondition: canonical context files exist for filtered tasks.
         // Must apply the same area/task filter as fetch-docs so we only
         // check contexts that were actually fetched.
-        const filter = ctx.config.areas || ctx.config.tasks
+        const filter = ctx.config.areas || ctx.config.tasks || ctx.config.tags
             ? {
                 ...(ctx.config.areas ? { areas: ctx.config.areas } : {}),
                 ...(ctx.config.tasks ? { taskIds: ctx.config.tasks } : {}),
+                ...(ctx.config.tags ? { tags: ctx.config.tags } : {}),
             }
             : undefined;
         let tasks = await ctx.taskSource.loadTasks(filter);
@@ -76,10 +77,11 @@ export class RunEvalStep {
         if (!debug?.enabled) {
             try {
                 evalFingerprint = computeEvalFingerprint({
-                    filter: ctx.config.areas || ctx.config.tasks
+                    filter: ctx.config.areas || ctx.config.tasks || ctx.config.tags
                         ? {
                             areas: ctx.config.areas,
                             taskIds: ctx.config.tasks,
+                            tags: ctx.config.tags,
                         }
                         : undefined,
                     graderModel: "default",

package/dist/pipeline/plan.d.ts

@@ -145,6 +145,7 @@ export interface PlanOptions {
     skipEval: boolean;
     skipFetch: boolean;
     source?: string;
+    tagOption?: string[];
     taskOption?: string;
 }
 /**

package/dist/pipeline/plan.js

@@ -117,7 +117,7 @@ export async function buildPipelinePlan(opts, rootDir) {
         .filter((i) => i.severity === "error")
         .map((i) => `[${i.source}] ${i.message}`);
     // 2. Expand tasks with filters
-    const filter = opts.areaOption || opts.taskOption
+    const filter = opts.areaOption || opts.taskOption || opts.tagOption?.length
         ? {
             areas: opts.areaOption
                 ? opts.areaOption.split(",").map((a) => a.trim())
@@ -125,6 +125,7 @@ export async function buildPipelinePlan(opts, rootDir) {
             taskIds: opts.taskOption
                 ? opts.taskOption.split(",").map((t) => t.trim())
                 : undefined,
+            tags: opts.tagOption,
         }
         : undefined;
     let totalTests = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/ailf",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "private": false,
   "publishConfig": {
     "access": "restricted"