@sanity/ailf 0.1.29 → 0.1.30

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/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";
 /**

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";

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/package.json

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