@mutagent/evaluator 0.1.0-alpha.2

package/bin/mutagent-evaluator.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * mutagent-evaluator — npx/pnpx entry point.
+ *
+ *   pnpx @mutagent/evaluator init [--global] [--yes]              → cross-platform installer (copies skill + agents)
+ *   pnpx @mutagent/evaluator doctor                               → runtime probe
+ *   pnpx @mutagent/evaluator audit-run <runId> --subject <name>   → Mode A: 4-tab report
+ *   pnpx @mutagent/evaluator profile-subject <def> <traces>        → Mode B: generate a subject profile
+ *   pnpx @mutagent/evaluator methodology-review <runId> --subject  → Mode C: process self-feedback
+ *   pnpx @mutagent/evaluator variance-check <a> <b>                → coordinator: compare 2 variants
+ *   pnpx @mutagent/evaluator <script.ts> [args]                    → run any skill script directly
+ *
+ * This launcher is intentionally tiny + node-runnable (no deps): it locates the
+ * skill's run.sh runtime selector (bun → pnpm-tsx → npx-tsx fallback) and
+ * forwards the requested subcommand to the matching TypeScript entry point. The
+ * skill's TypeScript scripts are NOT precompiled — run.sh picks an available TS
+ * runtime at install time so the package stays portable across bun/pnpm/npm hosts.
+ *
+ * Layout (diagnostics-pattern consolidation): the runtime engine lives UNDER the
+ * skill tree at .claude/skills/mutagent-evaluator/. skillRoot resolves there; the
+ * run.sh runtime selector + every subcommand script are found beneath it.
+ *
+ * cwd discipline (mirrors diagnostics' W9-fix): the child runs in the USER's
+ * invocation directory (process.cwd() of this launcher), NOT the skill install
+ * dir. init's project-local install target is process.cwd(); overriding the child
+ * cwd to the skill dir would have made it install into the skill package itself.
+ * We pass the run.sh + script as ABSOLUTE paths so they resolve regardless of cwd,
+ * and leave the child's cwd = the user's shell PWD.
+ */
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, isAbsolute, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const skillRoot = join(here, "..", ".claude", "skills", "mutagent-evaluator");
+const runSh = join(skillRoot, "scripts", "cli", "run.sh");
+
+if (!existsSync(runSh)) {
+  console.error(`[mutagent-evaluator] runtime selector not found at ${runSh}`);
+  console.error("The package may be corrupted. Reinstall: pnpx @mutagent/evaluator init");
+  process.exit(1);
+}
+
+// Subcommand → skill script map. Unknown first-arg is treated as a script path.
+const SUBCOMMANDS = {
+  init: "scripts/cli/init.ts",
+  doctor: "scripts/cli/doctor.ts",
+  "audit-run": "scripts/cli/audit-run.ts",
+  "profile-subject": "scripts/cli/profile-subject.ts",
+  "methodology-review": "scripts/cli/methodology-review.ts",
+  "variance-check": "scripts/cli/variance-check.ts",
+};
+
+const [sub, ...rest] = process.argv.slice(2);
+const HELP = !sub || sub === "--help" || sub === "-h";
+
+if (HELP) {
+  console.log(`mutagent-evaluator — generic, subject-agnostic AI-agent auditor (reviewer, never executor)
+
+Usage:
+  pnpx @mutagent/evaluator init [--global] [--install] [--yes]      Cross-platform skill installer (copies skill + agents)
+  pnpx @mutagent/evaluator doctor                                   Runtime probe (read-only health report)
+  pnpx @mutagent/evaluator audit-run <runId> --subject <name>        Mode A — the 4-tab master-audit report
+  pnpx @mutagent/evaluator profile-subject <def> <traces> [--name X] Mode B — generate a subjects/<name>/ YAML profile
+  pnpx @mutagent/evaluator methodology-review <runId> --subject <n>  Mode C — process self-feedback (advisory)
+  pnpx @mutagent/evaluator variance-check <a> <b>                    coordinator — compare 2 variants -> delta + trend
+  pnpx @mutagent/evaluator <skill-script.ts> [args...]               run any skill script via the runtime selector
+
+Install scope:
+  (default)   project-local — installs into <your project>/.claude (and .codex)
+  --global    home dir       — installs into ~/.claude (and ~/.codex)
+
+After install, open your coding agent and invoke the skill:
+  claude   →   /mutagent-evaluator
+
+The evaluator is a REVIEWER: it never grades a run it produced, and the variance
+coordinator is a role distinct from the audit executors.
+
+Docs: see README.md`);
+  process.exit(0);
+}
+
+// Resolve target script to an ABSOLUTE path. Known subcommands map to skill
+// scripts (under skillRoot); an unknown first-arg is treated as a script path
+// (relative resolves against skillRoot, absolute passes through).
+const mapped = SUBCOMMANDS[sub] ?? sub;
+const scriptAbs = isAbsolute(mapped) ? mapped : join(skillRoot, mapped);
+
+// NOTE: no `cwd` override — the child inherits the user's shell PWD so init's
+// project-local install targets the project, not the skill package (W9 discipline).
+const result = spawnSync("bash", [runSh, scriptAbs, ...rest], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mutagent/evaluator",
+  "version": "0.1.0-alpha.2",
+  "description": "mutagent-evaluator: a generic, subject-agnostic AI-agent auditor — reviewer, never executor. Audits any skill/agent against a generated subject profile and emits a 4-tab master-audit report.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "bin": {
+    "mutagent-evaluator": "bin/mutagent-evaluator.mjs"
+  },
+  "files": [
+    "bin/",
+    ".claude/skills/mutagent-evaluator/",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "eslint .claude/skills/mutagent-evaluator/scripts scripts/release --ext .ts --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test ./.claude/skills/mutagent-evaluator/scripts ./.claude/skills/mutagent-evaluator/tests",
+    "init": "bun run .claude/skills/mutagent-evaluator/scripts/cli/init.ts",
+    "bundle:cli": "bun build ../mutagent-tools/src/cli/index.ts --target=bun --outfile=bin/mutagent-cli.mjs",
+    "prepublishOnly": "bun run bundle:cli && node ./scripts/release/prepublish-guard.mjs"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0",
+    "yaml": "^2.4.0"
+  },
+  "optionalDependencies": {
+    "@langchain/google-genai": "^2.1.27"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "mutagent",
+    "evaluator",
+    "ai-agents",
+    "agent-audit",
+    "determinism",
+    "skill"
+  ]
+}