Add CLI usability improvements: unknown argument detection and failed scenario re-run

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 .coverage
+.probitas/
 result
 dist/
 src/cli/_embedded_templates.ts

README.md

@@ -200,6 +200,9 @@ probitas run
 # Run scenarios with specific tag
 probitas run -s tag:api
 
+# Re-run only failed scenarios from previous run
+probitas run --failed
+
 # Run with JSON output
 probitas run --reporter json
 

assets/usage-run.txt

@@ -21,6 +21,8 @@ Options:
   -S, --sequential          Run scenarios sequentially (alias for --max-concurrency=1)
   --max-failures <n>        Stop after N failures
   -f, --fail-fast           Stop on first failure (alias for --max-failures=1)
+  -F, --failed              Run only scenarios that failed in the previous run
+                            Reads from .probitas/last-run.json
   --config <path>           Path to config file (deno.json/deno.jsonc)
   --env <file>              Load environment variables from file (default: .env)
   --no-env                  Skip loading .env file
@@ -93,6 +95,11 @@ Examples:
   probitas run -f                           Stop on first failure (alias)
   probitas run --reload                     Reload dependencies before running
 
+  # Re-run failed scenarios
+  probitas run --failed                     Run only scenarios that failed previously
+  probitas run -F                           Run only scenarios that failed previously (short)
+  probitas run -F -s tag:api                Run failed scenarios AND with @api tag
+
   # Output control
   probitas run -v                           Verbose output
   probitas run --verbose                    Verbose output (same as -v)

deno.json

@@ -106,6 +106,9 @@
     "@std/testing/bdd": "jsr:@std/testing@^1.0.16/bdd",
     "@std/testing/mock": "jsr:@std/testing@^1.0.16/mock",
     "@std/testing/time": "jsr:@std/testing@^1.0.16/time",
+    "@std/text": "jsr:@std/text@^1.0.17",
+    "@std/text/closest-string": "jsr:@std/text@^1.0.17/closest-string",
+    "@std/text/levenshtein-distance": "jsr:@std/text@^1.0.17/levenshtein-distance",
     "jsr:@probitas/probitas@^0": "./src/mod.ts"
   }
 }

src/cli/_templates/run.ts

@@ -66,6 +66,7 @@ runSubprocess<RunCommandInput>(async (ipc, input) => {
     timeout,
     stepOptions,
     logLevel,
+    failedFilter,
   } = input;
 
   // Create abort controller for this run
@@ -75,8 +76,8 @@ runSubprocess<RunCommandInput>(async (ipc, input) => {
   await configureLogging(logLevel);
 
   try {
-    // Load scenarios from files
-    const scenarios = applySelectors(
+    // Load scenarios from files and apply selectors
+    let scenarios = applySelectors(
       await loadScenarios(filePaths, {
         onImportError: (file, err) => {
           const m = err instanceof Error ? err.message : String(err);
@@ -86,6 +87,26 @@ runSubprocess<RunCommandInput>(async (ipc, input) => {
       selectors,
     );
 
+    // Apply failed filter if provided (for --failed flag)
+    if (failedFilter && failedFilter.length > 0) {
+      const failedSet = new Set(
+        failedFilter.map((f) => `${f.name}|${f.file}`),
+      );
+      scenarios = scenarios.filter((s) => {
+        const scenarioFile = s.origin?.path ?? "unknown";
+        // Check both absolute path and relative path matching
+        return failedSet.has(`${s.name}|${scenarioFile}`) ||
+          failedFilter.some((f) =>
+            f.name === s.name && scenarioFile.endsWith(f.file)
+          );
+      });
+
+      logger.debug("Applied failed filter", {
+        filterCount: failedFilter.length,
+        matchedCount: scenarios.length,
+      });
+    }
+
     // Check if aborted during loading phase
     if (globalAbortController.signal.aborted) {
       throw new Error("Aborted during scenario loading");
@@ -96,6 +117,7 @@ runSubprocess<RunCommandInput>(async (ipc, input) => {
       logger.info("No scenarios found after applying selectors", {
         filePaths,
         selectors,
+        failedFilter: failedFilter?.length ?? 0,
       });
     }
 

src/cli/_templates/run_protocol.ts

@@ -34,6 +34,16 @@ export type RunInput =
   | RunCommandInput
   | RunAbortInput;
 
+/**
+ * Failed scenario identifier for filtering
+ */
+export interface FailedScenarioFilter {
+  /** Scenario name */
+  readonly name: string;
+  /** File path (relative or absolute) */
+  readonly file: string;
+}
+
 /**
  * Run scenarios command
  */
@@ -53,6 +63,8 @@ export interface RunCommandInput {
   readonly stepOptions?: StepOptions;
   /** Log level for subprocess logging */
   readonly logLevel: LogLevel;
+  /** Filter to only run these failed scenarios (name + file pairs) */
+  readonly failedFilter?: readonly FailedScenarioFilter[];
 }
 
 /**

src/cli/commands/list.ts

@@ -12,6 +12,11 @@ import { fromErrorObject, isErrorObject } from "@core/errorutil/error-object";
 import { unreachable } from "@core/errorutil/unreachable";
 import { EXIT_CODE } from "../constants.ts";
 import { findProbitasConfigFile, loadConfig } from "../config.ts";
+import {
+  createUnknownArgHandler,
+  extractKnownOptions,
+  formatUnknownArgError,
+} from "../unknown_args.ts";
 import { createDiscoveryProgress, writeStatus } from "../progress.ts";
 import {
   configureLogging,
@@ -29,6 +34,36 @@ import {
 
 const logger = getLogger(["probitas", "cli", "list"]);
 
+/**
+ * parseArgs configuration for the list command
+ */
+const PARSE_ARGS_CONFIG = {
+  string: ["config", "include", "exclude", "selector", "env"],
+  boolean: [
+    "help",
+    "json",
+    "no-env",
+    "reload",
+    "quiet",
+    "verbose",
+    "debug",
+  ],
+  collect: ["include", "exclude", "selector"],
+  alias: {
+    h: "help",
+    s: "selector",
+    r: "reload",
+    v: "verbose",
+    q: "quiet",
+    d: "debug",
+  },
+  default: {
+    include: undefined,
+    exclude: undefined,
+    selector: undefined,
+  },
+} as const;
+
 /**
  * Execute the list command
  *
@@ -46,34 +81,33 @@ export async function listCommand(
     // Extract deno options first (before parseArgs)
     const { denoArgs, remainingArgs } = extractDenoOptions(args);
 
+    // Setup unknown argument handler
+    const knownOptions = extractKnownOptions(PARSE_ARGS_CONFIG);
+    const { handler: unknownHandler, result: unknownResult } =
+      createUnknownArgHandler({
+        knownOptions,
+        commandName: "list",
+      });
+
     // Parse command-line arguments
     const parsed = parseArgs(remainingArgs, {
-      string: ["config", "include", "exclude", "selector", "env"],
-      boolean: [
-        "help",
-        "json",
-        "no-env",
-        "reload",
-        "quiet",
-        "verbose",
-        "debug",
-      ],
-      collect: ["include", "exclude", "selector"],
-      alias: {
-        h: "help",
-        s: "selector",
-        r: "reload",
-        v: "verbose",
-        q: "quiet",
-        d: "debug",
-      },
-      default: {
-        include: undefined,
-        exclude: undefined,
-        selector: undefined,
-      },
+      ...PARSE_ARGS_CONFIG,
+      unknown: unknownHandler,
     });
 
+    // Check for unknown arguments before showing help
+    if (unknownResult.hasErrors) {
+      for (const unknown of unknownResult.unknownArgs) {
+        console.error(
+          formatUnknownArgError(unknown, {
+            knownOptions,
+            commandName: "list",
+          }),
+        );
+      }
+      return EXIT_CODE.USAGE_ERROR;
+    }
+
     // Show help if requested
     if (parsed.help) {
       try {