create runner with ChatGPT-Codex by using the runner-agents.md from the core

README.md

@@ -0,0 +1,61 @@
+# test-samurai-mocha-runner
+
+Mocha.js runner for the test-samurai Neovim plugin.
+
+## Features
+
+- Detects Mocha test files by checking `package.json` dependencies.
+- Supports nearest, file, all, and failed-only commands.
+- Streams results via Mocha's `json-stream` reporter.
+- Provides quickfix locations and per-test output.
+- Uses `--grep` with escaped patterns to match titles safely, even when running through `npm test`.
+- Executes tests via `npx mocha` for direct Mocha invocation.
+- `TSamAll` runs `test/**/*.{test,spec}.{t,j}s` to discover tests reliably.
+
+## Full Name Convention
+
+The runner builds stable full names using the active suite stack joined by `/`,
+followed by the test title:
+
+```
+Suite/Subsuite/Test
+```
+
+This convention is used consistently in `results.*`, `parse_test_output`, and
+`collect_failed_locations`. Failed-only runs translate `/` back to spaces for
+Mocha's `--grep` matching. Avoid `/` in your titles if you rely on that mapping.
+
+## Reporter Payload
+
+The runner expects Mocha's built-in `json-stream` reporter, which emits one JSON
+object per line. It consumes the following fields when present:
+
+```
+{
+  "event": "suite" | "suite end" | "pass" | "fail" | "pending",
+  "title": "Test or suite title",
+  "fullTitle": "Mocha full title",
+  "file": "/path/to/test.js",
+  "err": { "message": "string", "stack": "string" }
+}
+```
+
+## Usage
+
+Add the module to your test-samurai configuration:
+
+```lua
+require("test-samurai").setup({
+  runner_modules = {
+    "test-samurai-mocha-runner",
+  },
+})
+```
+
+## Development
+
+Run tests:
+
+```bash
+bash run_test.sh
+```