@elizaos/plugin-gitpathologist 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @elizaos/plugin-gitpathologist
+
+Forensic git-history analysis for elizaOS agents.
+
+## What it does
+
+This plugin gives an Eliza agent the ability to analyze the commit history of a file, directory, or path glob and produce a structured health report. It answers questions such as:
+
+- "When did the code quality in `src/payments/` start degrading?"
+- "Where did rot begin in this module?"
+- "What does the quality timeline look like for the last month?"
+
+The analysis runs a five-phase pipeline: parse `git log`, classify each commit by type, score commits on a health scale using an exponential moving average, detect quality peaks and drift inflections, then (optionally) call the agent's configured text model to write a narrative post-mortem for each drift event.
+
+Reports are cached on disk by `sha256(surface + since)` and validated against the repository HEAD sha, so a repeat query at the same commit returns the cached report instantly, while any new commit invalidates it.
+
+## Capabilities
+
+### Action: `GIT_PATHOLOGY`
+
+The plugin registers a single multiplex action with two operations:
+
+**`action=report`** (default) — full pathology analysis for a surface.
+
+Parameters:
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `surface` | Yes | — | Path or glob relative to repo root (e.g. `src/payments/`, `**/*.test.ts`) |
+| `since` | No | `14d` | Lookback window. ISO date or relative (`14d`, `4w`, `2m`). |
+| `budget` | No | `20` | Max LLM narration calls. `0` = fully deterministic, no model calls. |
+| `cache` | No | `auto` | `auto` (use cache when HEAD matches), `force` (recompute), `read-only` (fail on miss). |
+
+Output: a Markdown report with:
+- Commit count, authors, and analysis window
+- **Peaks** — local maxima of health score (best moments in the window)
+- **Drift inflections** — commits where a sustained quality drop begins
+- **Rot post-mortem** — per-drift narrative (LLM-generated if model available, deterministic otherwise)
+
+**`action=list`** — list cached reports for the current repo root. No parameters required.
+
+### Trigger phrases
+
+The agent will activate this action when the user says things like:
+- "analyze git pathology for X"
+- "when did this code get bad"
+- "where did rot start in X"
+- "code health for X"
+- "drift analysis for X"
+
+## Configuration
+
+| Environment variable | Default | Description |
+|---|---|---|
+| `ELIZA_GITPATHOLOGIST` | auto | Set `true` to force-enable, `false` to force-disable. When unset, the plugin auto-enables in workspaces with a `.git` directory. |
+| `GITPATHOLOGIST_BUDGET` | `20` | Maximum LLM narration calls per analysis. Set to `0` to use deterministic narration only. |
+| `GITPATHOLOGIST_CACHE_DIR` | `<repoRoot>/.eliza/gitpathology` | Override the cache directory for pathology reports. |
+
+## Requirements
+
+- Node.js runtime (not available on mobile/browser targets).
+- `git` must be present on `PATH`.
+- An Eliza agent runtime with a configured `TEXT_SMALL` model for LLM narration (optional — the plugin degrades gracefully to deterministic narration without one).
+
+## Enabling the plugin
+
+Add `@elizaos/plugin-gitpathologist` to your agent's plugin list:
+
+```ts
+import gitpathologistPlugin from "@elizaos/plugin-gitpathologist";
+
+const agent = new AgentRuntime({
+  plugins: [gitpathologistPlugin],
+  // ...
+});
+```
+
+## Example output
+
+```
+# Git Pathology — `src/payments/`
+
+**Repo:** `/home/user/myproject`
+**Window:** 2025-05-01 → 2025-05-31
+**HEAD:** `a1b2c3d`
+**Commits analyzed:** 47 (alice, bob, carol)
+**LLM calls:** 3
+
+## Peaks (local maxima of health)
+
+- `f3a1b2c` (2025-05-10, alice): score 0.61 +0.40 — clean refactor, low churn
+
+## Drift inflections (sustained downturns)
+
+- `9d2c4e1` (2025-05-22, bob): score 0.12 -0.49 — score drops 0.49 over next 5 commits flags=large-churn
+
+## Rot post-mortem
+
+### churn-spiral — `9d2c4e1`..`7a3f9b0`
+
+This commit introduced 1,240 churn lines across 23 files with no test coverage changes, signaling a large undisciplined patch...
+```

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@elizaos/plugin-gitpathologist",
+  "version": "2.0.11-beta.7",
+  "description": "Forensic git-history analysis for elizaOS agents: per-surface health timeline, drift inflection detection, rot post-mortem.",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "module": "dist/node/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elizaOS/eliza.git",
+    "directory": "plugins/plugin-gitpathologist"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "node": {
+        "types": "./dist/node/index.d.ts",
+        "import": "./dist/node/index.js",
+        "require": "./dist/cjs/index.cjs",
+        "default": "./dist/node/index.js"
+      },
+      "import": "./dist/node/index.js",
+      "require": "./dist/cjs/index.cjs",
+      "default": "./dist/node/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "elizaos",
+    "elizaos-plugin",
+    "git",
+    "history",
+    "forensics",
+    "code-quality"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "scripts": {
+    "build": "bun run build.ts",
+    "build:ts": "bun run build.ts",
+    "clean": "rm -rf dist .turbo",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "tsgo --noEmit",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format ."
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.11-beta.7"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.0.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "2.0.11-beta.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "ELIZA_GITPATHOLOGIST": {
+        "type": "boolean",
+        "description": "Force-enable or force-disable the gitpathologist plugin. When unset, the plugin auto-enables in workspaces with a .git directory.",
+        "required": false,
+        "sensitive": false
+      },
+      "GITPATHOLOGIST_BUDGET": {
+        "type": "number",
+        "description": "Maximum number of LLM narration calls per analysis. Caps token spend. Default 20.",
+        "required": false,
+        "sensitive": false
+      },
+      "GITPATHOLOGIST_CACHE_DIR": {
+        "type": "string",
+        "description": "Override directory for cached pathology reports. Default <workspace>/.eliza/gitpathology.",
+        "required": false,
+        "sensitive": false
+      }
+    }
+  },
+  "eliza": {
+    "platforms": [
+      "node"
+    ],
+    "runtime": "node",
+    "platformDetails": {
+      "node": "Node.js build available via exports.node"
+    }
+  },
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
+}