kodevu 0.1.4 → 0.1.6

package/README.md

@@ -4,7 +4,7 @@ A Node.js tool that polls new SVN revisions or Git commits, fetches each change
 
 ## Workflow
 
-1. Detect the configured repository type, or use the explicit `vcs` setting.
+1. Detect the repository type automatically (Git or SVN).
 2. Read the latest change from `target`.
 3. Find changes that have not been reviewed yet.
 4. For each change:
@@ -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,60 +30,59 @@ 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
-- `vcs`: `auto`, `svn`, or `git`; default `auto`
+- `target`: required repository target; can be provided by config or as the CLI positional argument
 - `reviewer`: `codex` or `gemini`; default `codex`
-- `pollCron`: cron schedule, default every 10 minutes
 - `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
+- 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`; 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.
-- When `vcs` is `auto`, the tool tries Git first for existing local paths, then falls back to SVN.
-- Legacy `svnTarget` is still accepted for backward compatibility.
+- The tool tries Git first for existing local paths, then falls back to SVN.
 
 ## Notes
 
@@ -93,5 +93,5 @@ Internal defaults:
 - 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,10 +1,9 @@
 {
   "target": "C:/path/to/your/repository-or-subdirectory",
-  "vcs": "auto",
   "reviewer": "codex",
-  "pollCron": "*/10 * * * *",
   "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.4",
+  "version": "0.1.6",
   "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,25 +1,48 @@
 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";
 
+const defaultStorageDir = path.join(os.homedir(), ".kodevu");
+
 const defaultConfig = {
-  vcs: "auto",
   reviewer: "codex",
   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);
+}
+
 export function parseCliArgs(argv) {
   const args = {
     command: "run",
     configPath: "config.json",
-    once: false,
+    configExplicitlySet: false,
+    target: "",
     debug: false,
     help: false,
     commandExplicitlySet: false
@@ -34,11 +57,6 @@ export function parseCliArgs(argv) {
       continue;
     }
 
-    if (value === "--once") {
-      args.once = true;
-      continue;
-    }
-
     if (value === "--help" || value === "-h") {
       args.help = true;
       continue;
@@ -55,9 +73,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;
@@ -66,45 +92,54 @@ 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.vcs = String(config.vcs || "auto").toLowerCase();
   config.reviewer = String(config.reviewer || "codex").toLowerCase();
   config.debug = Boolean(cliArgs.debug);
 
-  if (!["auto", "svn", "git"].includes(config.vcs)) {
-    throw new Error(`"vcs" must be one of "auto", "svn", or "git" in ${absoluteConfigPath}`);
-  }
-
   if (!["codex", "gemini"].includes(config.reviewer)) {
-    throw new Error(`"reviewer" must be one of "codex" or "gemini" in ${absoluteConfigPath}`);
+    throw new Error(`"reviewer" must be one of "codex" or "gemini"${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;
@@ -116,19 +151,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:
-  vcs            auto | svn | git
   reviewer       codex | gemini
-  target         Repository target path (Git) or SVN working copy / URL
+  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";
 
@@ -36,46 +35,18 @@ if (config.debug) {
   console.error(
     `[debug] Loaded config: ${JSON.stringify({
       configPath: config.configPath,
-      vcs: config.vcs,
       reviewer: config.reviewer,
       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/vcs-client.js

@@ -144,20 +144,6 @@ const backends = {
 };
 
 export async function resolveRepositoryContext(config) {
-  if (config.vcs === "svn") {
-    return {
-      backend: backends.svn,
-      targetInfo: await backends.svn.getTargetInfo(config)
-    };
-  }
-
-  if (config.vcs === "git") {
-    return {
-      backend: backends.git,
-      targetInfo: await backends.git.getTargetInfo(config)
-    };
-  }
-
   const candidateTargetPath = path.resolve(config.baseDir, config.target);
 
   if (!isLikelyUrl(config.target) && (await pathExists(candidateTargetPath))) {