kodevu 0.1.5 → 0.1.7

package/README.md

@@ -12,8 +12,8 @@ A Node.js tool that polls new SVN revisions or Git commits, fetches each change
    - generate a unified diff for that single revision or commit
    - send the diff and change metadata to the configured reviewer CLI
    - allow the reviewer to inspect related local repository files in read-only mode when a local workspace is available
-   - write the result to `reports/`
-5. Update `data/state.json` so the same change is not reviewed twice.
+   - write the result to `~/.kodevu/`
+5. Update `~/.kodevu/state.json` so the same change is not reviewed twice.
 
 ## Setup
 
@@ -22,6 +22,7 @@ npx kodevu init
 ```
 
 This creates `config.json` in the current directory from the packaged `config.example.json`.
+You only need this when you want to override defaults such as `reviewer` or output paths.
 
 If you want a different path:
 
@@ -29,68 +30,69 @@ If you want a different path:
 npx kodevu init --config ./config.current.json
 ```
 
-Then edit `config.json` and set `target`.
+Then edit `config.json` if you want custom settings.
 
-`config.json` is the default config file. If you do not pass `--config`, Kodevu will load `./config.json` from the current directory.
+If you do not pass `--config`, Kodevu will try to load `./config.json` from the current directory only when that file exists. Otherwise it runs with built-in defaults.
 
 ## Run
 
-Run one cycle:
+Run once:
 
 ```bash
-npx kodevu --once
+npx kodevu /path/to/your/repo
 ```
 
-Run one cycle with debug logs:
+Run once with debug logs:
 
 ```bash
-npx kodevu --once --debug
+npx kodevu /path/to/your/repo --debug
 ```
 
-Start the scheduler:
+Use a custom config path only when needed:
 
 ```bash
-npx kodevu
+npx kodevu --config ./config.current.json
 ```
 
-Use a custom config path only when needed:
+Or combine a config file with a positional target override:
 
 ```bash
-npx kodevu --config ./config.current.json --once
+npx kodevu /path/to/your/repo --config ./config.current.json
 ```
 
 `--debug` / `-d` is a CLI-only switch. It is not read from `config.json`.
 
 ## Config
 
-- `target`: required repository target
-- `reviewer`: `codex` or `gemini`; default `codex`
-- `pollCron`: cron schedule, default every 10 minutes
+- `target`: required repository target; can be provided by config or as the CLI positional argument
+- `reviewer`: `codex`, `gemini`, or `auto`; default `auto`
 - `reviewPrompt`: saved into the report as review context
-- `outputDir`: report output directory; default `./reports`
+- `outputDir`: report output directory; default `~/.kodevu`
+- `stateFilePath`: review state file path; default `~/.kodevu/state.json`
 - `commandTimeoutMs`: timeout for a single review command execution in milliseconds
 - `maxRevisionsPerRun`: cap the number of pending changes per polling cycle
 
 Internal defaults:
 
-- review state is always stored in `./data/state.json`, and first run starts from the current latest change instead of replaying full history
-- Kodevu invokes `git`, `svn`, and the configured reviewer CLI from `PATH`; debug logging is enabled only by passing `--debug` or `-d`
+- by default, review reports and state are stored under `~/.kodevu`; first run starts from the current latest change instead of replaying full history
+- if `./config.json` is absent, Kodevu still runs with built-in defaults as long as you pass a positional `target`
+- Kodevu invokes `git`, `svn`, and the configured reviewer CLI from `PATH`; when `reviewer` is `auto`, it randomly selects one from the installed reviewer CLIs it can find in `PATH`; debug logging is enabled only by passing `--debug` or `-d`
 
 ## Target Rules
 
 - For SVN, `target` can be a working copy path or repository URL.
 - For Git, `target` must be a local repository path or a subdirectory inside a local repository.
 - The tool tries Git first for existing local paths, then falls back to SVN.
-- Legacy `svnTarget` is still accepted for backward compatibility.
 
 ## Notes
 
 - `reviewer: "codex"` uses `codex exec` with the diff embedded in the prompt.
 - `reviewer: "gemini"` uses `gemini -p` in non-interactive mode.
+- `reviewer: "auto"` probes `codex` and `gemini` in `PATH`, then randomly chooses one of the available CLIs for this run.
 - Large diffs are truncated before being sent to the reviewer or written into the report once they exceed the configured line or character limits.
 - For Git targets and local SVN working copies, the reviewer command runs from the repository workspace so it can inspect related files beyond the diff when needed.
 - For remote SVN URLs without a local working copy, the review still relies on the diff and change metadata only.
 - SVN reports keep the `r123.md` naming style.
 - Git reports are written as `git-<short-commit-hash>.md`.
-- `data/state.json` stores per-project checkpoints keyed by repository identity; only the v2 multi-project structure is supported.
+- `~/.kodevu/state.json` stores per-project checkpoints keyed by repository identity; only the v2 multi-project structure is supported.
 - If the reviewer command exits non-zero or times out, the report is still written, but the state is not advanced so the change can be retried later.

package/config.example.json

@@ -1,9 +1,9 @@
 {
   "target": "C:/path/to/your/repository-or-subdirectory",
-  "reviewer": "codex",
-  "pollCron": "*/10 * * * *",
+  "reviewer": "auto",
   "reviewPrompt": "请严格审查当前变更，优先指出 bug、回归风险、兼容性问题、安全问题、边界条件缺陷和缺失测试。请使用简体中文输出 Markdown；如果没有明确缺陷，请写“未发现明确缺陷”，并补充剩余风险。",
-  "outputDir": "./reports",
+  "outputDir": "~/.kodevu",
+  "stateFilePath": "~/.kodevu/state.json",
   "commandTimeoutMs": 600000,
   "maxRevisionsPerRun": 5
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodevu",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Poll SVN revisions or Git commits, send each change diff to a reviewer CLI, and write Markdown review reports.",
   "bin": {
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "start": "node src/index.js",
-    "once": "node src/index.js --once",
+    "once": "node src/index.js",
     "check": "node --check src/index.js && node --check src/config.js && node --check src/review-runner.js && node --check src/svn-client.js && node --check src/git-client.js && node --check src/vcs-client.js && node --check src/shell.js"
   },
   "engines": {
@@ -22,7 +22,6 @@
   "dependencies": {
     "cross-spawn": "^7.0.6",
     "fast-xml-parser": "^5.2.5",
-    "iconv-lite": "^0.6.3",
-    "node-cron": "^4.2.1"
+    "iconv-lite": "^0.6.3"
   }
 }

package/src/config.js

@@ -1,24 +1,71 @@
 import fs from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { findCommandOnPath } from "./shell.js";
+
+const defaultStorageDir = path.join(os.homedir(), ".kodevu");
+const SUPPORTED_REVIEWERS = ["codex", "gemini"];
 
 const defaultConfig = {
-  reviewer: "codex",
+  reviewer: "auto",
   target: "",
-  pollCron: "*/10 * * * *",
-  outputDir: "./reports",
+  outputDir: defaultStorageDir,
+  stateFilePath: path.join(defaultStorageDir, "state.json"),
   commandTimeoutMs: 600000,
   reviewPrompt:
     "请严格审查当前变更，优先指出 bug、回归风险、兼容性问题、安全问题、边界条件缺陷和缺失测试。请使用简体中文输出 Markdown；如果没有明确缺陷，请写“未发现明确缺陷”，并补充剩余风险。",
   maxRevisionsPerRun: 20
 };
 
+function resolveConfigPath(baseDir, value) {
+  if (!value) {
+    return value;
+  }
+
+  if (typeof value !== "string") {
+    return path.resolve(baseDir, String(value));
+  }
+
+  if (value === "~") {
+    return os.homedir();
+  }
+
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+
+  return path.isAbsolute(value) ? value : path.resolve(baseDir, value);
+}
+
+async function resolveAutoReviewer(debug, loadedConfigPath) {
+  const availableReviewers = [];
+
+  for (const reviewerName of SUPPORTED_REVIEWERS) {
+    const commandPath = await findCommandOnPath(reviewerName, { debug });
+    if (commandPath) {
+      availableReviewers.push({ reviewerName, commandPath });
+    }
+  }
+
+  if (availableReviewers.length === 0) {
+    throw new Error(
+      `No reviewer CLI was found in PATH for "reviewer": "auto". Install one of: ${SUPPORTED_REVIEWERS.join(", ")}${
+        loadedConfigPath ? ` (${loadedConfigPath})` : ""
+      }`
+    );
+  }
+
+  return availableReviewers[Math.floor(Math.random() * availableReviewers.length)];
+}
+
 export function parseCliArgs(argv) {
   const args = {
     command: "run",
     configPath: "config.json",
-    once: false,
+    configExplicitlySet: false,
+    target: "",
     debug: false,
     help: false,
     commandExplicitlySet: false
@@ -33,11 +80,6 @@ export function parseCliArgs(argv) {
       continue;
     }
 
-    if (value === "--once") {
-      args.once = true;
-      continue;
-    }
-
     if (value === "--help" || value === "-h") {
       args.help = true;
       continue;
@@ -54,9 +96,17 @@ export function parseCliArgs(argv) {
         throw new Error(`Missing value for ${value}`);
       }
       args.configPath = configPath;
+      args.configExplicitlySet = true;
       index += 1;
       continue;
     }
+
+    if (!value.startsWith("-") && args.command === "run" && !args.target) {
+      args.target = value;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${value}`);
   }
 
   delete args.commandExplicitlySet;
@@ -65,40 +115,61 @@ export function parseCliArgs(argv) {
 
 export async function loadConfig(configPath, cliArgs = {}) {
   const absoluteConfigPath = path.resolve(configPath);
-  const raw = await fs.readFile(absoluteConfigPath, "utf8");
+  let loadedConfig = {};
+  let loadedConfigPath = null;
+  let baseDir = process.cwd();
+
+  try {
+    const raw = await fs.readFile(absoluteConfigPath, "utf8");
+    loadedConfig = JSON.parse(raw);
+    loadedConfigPath = absoluteConfigPath;
+    baseDir = path.dirname(absoluteConfigPath);
+  } catch (error) {
+    if (!(error?.code === "ENOENT" && !cliArgs.configExplicitlySet)) {
+      throw error;
+    }
+  }
+
   const config = {
     ...defaultConfig,
-    ...JSON.parse(raw)
+    ...loadedConfig
   };
 
-  if (!config.target && config.svnTarget) {
-    config.target = config.svnTarget;
+  if (cliArgs.target) {
+    config.target = cliArgs.target;
   }
 
   if (!config.target) {
-    throw new Error(`Missing required config field "target" (or legacy "svnTarget") in ${absoluteConfigPath}`);
+    throw new Error('Missing target. Pass `npx kodevu <repo-path>` or set "target" in config.json.');
   }
 
-  config.reviewer = String(config.reviewer || "codex").toLowerCase();
   config.debug = Boolean(cliArgs.debug);
-
-  if (!["codex", "gemini"].includes(config.reviewer)) {
-    throw new Error(`"reviewer" must be one of "codex" or "gemini" in ${absoluteConfigPath}`);
+  config.reviewer = String(config.reviewer || "auto").toLowerCase();
+
+  if (config.reviewer === "auto") {
+    const selectedReviewer = await resolveAutoReviewer(config.debug, loadedConfigPath);
+    config.reviewer = selectedReviewer.reviewerName;
+    config.reviewerCommandPath = selectedReviewer.commandPath;
+    config.reviewerWasAutoSelected = true;
+  } else if (!SUPPORTED_REVIEWERS.includes(config.reviewer)) {
+    throw new Error(
+      `"reviewer" must be one of "codex", "gemini", or "auto"${loadedConfigPath ? ` in ${loadedConfigPath}` : ""}`
+    );
   }
 
-  config.configPath = absoluteConfigPath;
-  config.baseDir = path.dirname(absoluteConfigPath);
-  config.outputDir = path.resolve(config.baseDir, config.outputDir);
-  config.stateFilePath = path.resolve(config.baseDir, "./data/state.json");
+  config.configPath = loadedConfigPath;
+  config.baseDir = baseDir;
+  config.outputDir = resolveConfigPath(config.baseDir, config.outputDir);
+  config.stateFilePath = resolveConfigPath(config.baseDir, config.stateFilePath);
   config.maxRevisionsPerRun = Number(config.maxRevisionsPerRun);
   config.commandTimeoutMs = Number(config.commandTimeoutMs);
 
   if (!Number.isInteger(config.maxRevisionsPerRun) || config.maxRevisionsPerRun <= 0) {
-    throw new Error(`"maxRevisionsPerRun" must be a positive integer in ${absoluteConfigPath}`);
+    throw new Error(`"maxRevisionsPerRun" must be a positive integer${loadedConfigPath ? ` in ${loadedConfigPath}` : ""}`);
   }
 
   if (!Number.isInteger(config.commandTimeoutMs) || config.commandTimeoutMs <= 0) {
-    throw new Error(`"commandTimeoutMs" must be a positive integer in ${absoluteConfigPath}`);
+    throw new Error(`"commandTimeoutMs" must be a positive integer${loadedConfigPath ? ` in ${loadedConfigPath}` : ""}`);
   }
 
   return config;
@@ -110,18 +181,19 @@ export function printHelp() {
 Usage:
   kodevu init
   npx kodevu init
-  kodevu [--config config.json] [--once]
-  npx kodevu [--config config.json] [--once]
+  kodevu <target> [--debug]
+  npx kodevu <target> [--debug]
+  kodevu [--config config.json]
+  npx kodevu [--config config.json]
 
 Options:
-  --config, -c   Path to config json. Default: ./config.json in the current directory
+  --config, -c   Optional config json path. If omitted, ./config.json is loaded only when present
   --debug, -d    Print extra debug information to the console
-  --once         Run one polling cycle and exit
   --help, -h     Show help
 
 Config highlights:
-  reviewer       codex | gemini
-  target         Repository target path (Git) or SVN working copy / URL
+  reviewer       codex | gemini | auto
+  target         Repository target path (Git) or SVN working copy / URL; CLI positional target overrides config
 `);
 }
 

package/src/index.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 
-import cron from "node-cron";
 import { initConfig, loadConfig, parseCliArgs, printHelp } from "./config.js";
 import { runReviewCycle } from "./review-runner.js";
 
@@ -32,49 +31,30 @@ if (cliArgs.command === "init") {
 
 const config = await loadConfig(cliArgs.configPath, cliArgs);
 
+if (config.reviewerWasAutoSelected) {
+  console.log(
+    `Reviewer "auto" selected ${config.reviewer}${config.reviewerCommandPath ? ` (${config.reviewerCommandPath})` : ""}.`
+  );
+}
+
 if (config.debug) {
   console.error(
     `[debug] Loaded config: ${JSON.stringify({
       configPath: config.configPath,
       reviewer: config.reviewer,
+      reviewerCommandPath: config.reviewerCommandPath,
+      reviewerWasAutoSelected: config.reviewerWasAutoSelected,
       target: config.target,
-      pollCron: config.pollCron,
       outputDir: config.outputDir,
-      debug: config.debug,
-      once: cliArgs.once
+      debug: config.debug
     })}`
   );
 }
 
-let running = false;
-
-async function runOnce() {
-  if (running) {
-    console.log("A review cycle is already running, skipping this trigger.");
-    return;
-  }
-
-  running = true;
-
-  try {
-    await runReviewCycle(config);
-  } catch (error) {
-    console.error(error?.stack || String(error));
-    process.exitCode = 1;
-  } finally {
-    running = false;
-  }
-}
-
-if (cliArgs.once) {
-  await runOnce();
-  process.exit(process.exitCode || 0);
+try {
+  await runReviewCycle(config);
+} catch (error) {
+  console.error(error?.stack || String(error));
+  process.exitCode = 1;
 }
-
-await runOnce();
-
-console.log(`Scheduler started. Cron: ${config.pollCron}`);
-
-cron.schedule(config.pollCron, () => {
-  void runOnce();
-});
+process.exit(process.exitCode || 0);

package/src/shell.js

@@ -103,3 +103,23 @@ export async function runCommand(command, args = [], options = {}) {
     }
   });
 }
+
+export async function findCommandOnPath(command, options = {}) {
+  const locator = process.platform === "win32" ? "where" : "which";
+  const result = await runCommand(locator, [command], {
+    allowFailure: true,
+    trim: true,
+    debug: options.debug
+  });
+
+  if (result.code !== 0 || result.timedOut || !result.stdout) {
+    return null;
+  }
+
+  return (
+    result.stdout
+      .split(/\r?\n/)
+      .map((item) => item.trim())
+      .find(Boolean) || null
+  );
+}