kodevu 0.1.0 → 0.1.2

package/README.md

@@ -18,62 +18,48 @@ A Node.js tool that polls new SVN revisions or Git commits, fetches each change
 ## Setup
 
 ```bash
-npm install
-copy config.example.json config.json
+npx kodevu init
 ```
 
-Then edit `config.json` and set `target`.
+This creates `config.json` in the current directory from the packaged `config.example.json`.
 
-Install as a CLI package:
+If you want a different path:
 
 ```bash
-npm install -g kodevu
-copy config.example.json config.json
+npx kodevu init --config ./config.current.json
 ```
 
-## Run
+Then edit `config.json` and set `target`.
 
-Run one cycle:
+`config.json` is the default config file. If you do not pass `--config`, Kodevu will load `./config.json` from the current directory.
 
-```bash
-npm run once
-```
+## Run
 
-Or run directly as the published CLI:
+Run one cycle:
 
 ```bash
-kodevu --once
+npx kodevu --once
 ```
 
-Use `npx` without installing globally:
+Run one cycle with debug logs:
 
 ```bash
-npx kodevu --once --config ./config.json
+npx kodevu --once --debug
 ```
 
 Start the scheduler:
 
 ```bash
-npm start
+npx kodevu
 ```
 
-Published CLI form:
+Use a custom config path only when needed:
 
 ```bash
-kodevu --config ./config.json
+npx kodevu --config ./config.current.json --once
 ```
 
-Use a custom config path:
-
-```bash
-node src/index.js --config ./config.json --once
-```
-
-Equivalent `npx` usage:
-
-```bash
-npx kodevu --config ./config.json --once
-```
+`--debug` / `-d` is a CLI-only switch. It is not read from `config.json`.
 
 ## Config
 
@@ -92,6 +78,7 @@ Internal defaults:
 - review state is always stored in `./data/state.json`
 - the tool always invokes `git`, `svn`, and the configured reviewer CLI from `PATH`
 - command output is decoded as `utf8`
+- debug logging is enabled only by passing `--debug` or `-d`
 
 ## Target Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodevu",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Poll SVN revisions or Git commits, send each change diff to a reviewer CLI, and write Markdown review reports.",
   "bin": {

package/src/config.js

@@ -1,5 +1,7 @@
 import fs from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 const defaultConfig = {
   vcs: "auto",
@@ -16,14 +18,23 @@ const defaultConfig = {
 
 export function parseCliArgs(argv) {
   const args = {
+    command: "run",
     configPath: "config.json",
     once: false,
-    help: false
+    debug: false,
+    help: false,
+    commandExplicitlySet: false
   };
 
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
 
+    if (value === "init" && !args.commandExplicitlySet && index === 0) {
+      args.command = "init";
+      args.commandExplicitlySet = true;
+      continue;
+    }
+
     if (value === "--once") {
       args.once = true;
       continue;
@@ -34,17 +45,27 @@ export function parseCliArgs(argv) {
       continue;
     }
 
+    if (value === "--debug" || value === "-d") {
+      args.debug = true;
+      continue;
+    }
+
     if (value === "--config" || value === "-c") {
-      args.configPath = argv[index + 1];
+      const configPath = argv[index + 1];
+      if (!configPath || configPath.startsWith("-")) {
+        throw new Error(`Missing value for ${value}`);
+      }
+      args.configPath = configPath;
       index += 1;
       continue;
     }
   }
 
+  delete args.commandExplicitlySet;
   return args;
 }
 
-export async function loadConfig(configPath) {
+export async function loadConfig(configPath, cliArgs = {}) {
   const absoluteConfigPath = path.resolve(configPath);
   const raw = await fs.readFile(absoluteConfigPath, "utf8");
   const config = {
@@ -62,6 +83,7 @@ export async function loadConfig(configPath) {
 
   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}`);
@@ -93,11 +115,14 @@ export function printHelp() {
   console.log(`Kodevu
 
 Usage:
+  kodevu init
+  npx kodevu init
   kodevu [--config config.json] [--once]
   npx kodevu [--config config.json] [--once]
 
 Options:
-  --config, -c   Path to config json. Default: ./config.json
+  --config, -c   Path to config json. Default: ./config.json in the current directory
+  --debug, -d    Print extra debug information to the console
   --once         Run one polling cycle and exit
   --help, -h     Show help
 
@@ -107,3 +132,21 @@ Config highlights:
   target         Repository target path (Git) or SVN working copy / URL
 `);
 }
+
+export async function initConfig(targetPath = "config.json") {
+  const absoluteTargetPath = path.resolve(targetPath);
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const templatePath = path.join(packageRoot, "config.example.json");
+
+  await fs.mkdir(path.dirname(absoluteTargetPath), { recursive: true });
+  try {
+    await fs.copyFile(templatePath, absoluteTargetPath, fsConstants.COPYFILE_EXCL);
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new Error(`Config file already exists: ${absoluteTargetPath}`);
+    }
+    throw error;
+  }
+
+  return absoluteTargetPath;
+}

package/src/git-client.js

@@ -31,6 +31,7 @@ async function statPath(targetPath) {
 async function runGit(config, args, options = {}) {
   return await runCommand(GIT_COMMAND, args, {
     encoding: COMMAND_ENCODING,
+    debug: config.debug,
     ...options
   });
 }

package/src/index.js

@@ -1,17 +1,51 @@
 #!/usr/bin/env node
 
 import cron from "node-cron";
-import { loadConfig, parseCliArgs, printHelp } from "./config.js";
+import { initConfig, loadConfig, parseCliArgs, printHelp } from "./config.js";
 import { runReviewCycle } from "./review-runner.js";
 
-const cliArgs = parseCliArgs(process.argv.slice(2));
+let cliArgs;
+
+try {
+  cliArgs = parseCliArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(error?.message || String(error));
+  printHelp();
+  process.exit(1);
+}
 
 if (cliArgs.help) {
   printHelp();
   process.exit(0);
 }
 
-const config = await loadConfig(cliArgs.configPath);
+if (cliArgs.command === "init") {
+  try {
+    const createdPath = await initConfig(cliArgs.configPath);
+    console.log(`Created config: ${createdPath}`);
+    process.exit(0);
+  } catch (error) {
+    console.error(error?.stack || String(error));
+    process.exit(1);
+  }
+}
+
+const config = await loadConfig(cliArgs.configPath, cliArgs);
+
+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
+    })}`
+  );
+}
 
 let running = false;
 

package/src/review-runner.js

@@ -4,6 +4,12 @@ import path from "node:path";
 import { runCommand } from "./shell.js";
 import { resolveRepositoryContext } from "./vcs-client.js";
 
+function debugLog(config, message) {
+  if (config.debug) {
+    console.error(`[debug] ${message}`);
+  }
+}
+
 const REVIEWERS = {
   codex: {
     displayName: "Codex",
@@ -29,7 +35,8 @@ const REVIEWERS = {
           cwd: workingDir,
           input: [promptText, "Unified diff:", diffText].join("\n\n"),
           allowFailure: true,
-          timeoutMs: config.commandTimeoutMs
+          timeoutMs: config.commandTimeoutMs,
+          debug: config.debug
         });
 
         let message = "";
@@ -58,7 +65,8 @@ const REVIEWERS = {
         cwd: workingDir,
         input: ["Unified diff:", diffText].join("\n\n"),
         allowFailure: true,
-        timeoutMs: config.commandTimeoutMs
+        timeoutMs: config.commandTimeoutMs,
+        debug: config.debug
       });
 
       return {
@@ -294,10 +302,18 @@ export async function runReviewCycle(config) {
   await ensureDir(config.outputDir);
 
   const { backend, targetInfo } = await resolveRepositoryContext(config);
+  debugLog(
+    config,
+    `Resolved repository context: backend=${backend.kind} target=${targetInfo.targetDisplay || config.target} stateKey=${targetInfo.stateKey}`
+  );
   const latestChangeId = await backend.getLatestChangeId(config, targetInfo);
   const stateFile = await loadState(config.stateFilePath);
   const projectState = getProjectState(stateFile, targetInfo);
   let lastReviewedId = readLastReviewedId(projectState, backend, targetInfo);
+  debugLog(
+    config,
+    `Checkpoint status: latest=${backend.formatChangeId(latestChangeId)} lastReviewed=${lastReviewedId ? backend.formatChangeId(lastReviewedId) : "(none)"}`
+  );
 
   if (lastReviewedId) {
     const checkpointIsValid = await backend.isValidCheckpoint(config, targetInfo, lastReviewedId, latestChangeId);
@@ -323,6 +339,8 @@ export async function runReviewCycle(config) {
     );
   }
 
+  debugLog(config, `Planned ${changeIdsToReview.length} ${backend.changeName}(s) for this cycle.`);
+
   if (changeIdsToReview.length === 0) {
     const lastKnownId = lastReviewedId ? backend.formatChangeId(lastReviewedId) : "(none)";
     console.log(`No new ${backend.changeName}s. Last reviewed: ${lastKnownId}`);
@@ -332,11 +350,13 @@ export async function runReviewCycle(config) {
   console.log(`Reviewing ${backend.displayName} ${backend.changeName}s ${formatChangeList(backend, changeIdsToReview)}`);
 
   for (const changeId of changeIdsToReview) {
+    debugLog(config, `Starting review for ${backend.formatChangeId(changeId)}.`);
     const result = await reviewChange(config, backend, targetInfo, changeId);
     console.log(`Reviewed ${backend.formatChangeId(changeId)}: ${result.outputFile}`);
     const nextProjectState = buildStateSnapshot(backend, targetInfo, changeId);
     await saveState(config.stateFilePath, updateProjectState(stateFile, targetInfo, nextProjectState));
     stateFile.projects[targetInfo.stateKey] = nextProjectState;
+    debugLog(config, `Saved checkpoint for ${backend.formatChangeId(changeId)} to ${config.stateFilePath}.`);
   }
 
   const remainingChanges = await backend.getPendingChangeIds(

package/src/shell.js

@@ -1,6 +1,21 @@
 import spawn from "cross-spawn";
 import iconv from "iconv-lite";
 
+function debugLog(enabled, message) {
+  if (enabled) {
+    console.error(`[debug] ${message}`);
+  }
+}
+
+function summarizeOutput(text) {
+  if (!text) {
+    return "(empty)";
+  }
+
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length > 400 ? `${normalized.slice(0, 400)}...` : normalized;
+}
+
 export async function runCommand(command, args = [], options = {}) {
   const {
     cwd,
@@ -9,9 +24,15 @@ export async function runCommand(command, args = [], options = {}) {
     encoding = "utf8",
     allowFailure = false,
     timeoutMs = 0,
-    trim = false
+    trim = false,
+    debug = false
   } = options;
 
+  debugLog(
+    debug,
+    `run: ${command} ${args.join(" ")}${cwd ? ` | cwd=${cwd}` : ""}${timeoutMs > 0 ? ` | timeoutMs=${timeoutMs}` : ""}`
+  );
+
   return await new Promise((resolve, reject) => {
     const child = spawn(command, args, {
       cwd,
@@ -51,6 +72,11 @@ export async function runCommand(command, args = [], options = {}) {
         stderr: trim ? stderr.trim() : stderr
       };
 
+      debugLog(
+        debug,
+        `exit: ${command} code=${result.code} timedOut=${result.timedOut} stdout=${summarizeOutput(result.stdout)} stderr=${summarizeOutput(result.stderr)}`
+      );
+
       if ((result.code !== 0 || result.timedOut) && !allowFailure) {
         const error = new Error(
           `Command failed: ${command} ${args.join(" ")}\n${result.stderr || result.stdout}`.trim()

package/src/svn-client.js

@@ -38,7 +38,8 @@ function repoPathFromUrl(rootUrl, url) {
 export async function getTargetInfo(config) {
   const result = await runCommand(SVN_COMMAND, ["info", "--xml", config.target], {
     encoding: COMMAND_ENCODING,
-    trim: true
+    trim: true,
+    debug: config.debug
   });
   const parsed = xmlParser.parse(result.stdout);
   const entry = parsed?.info?.entry;
@@ -70,7 +71,7 @@ export async function getLatestRevision(config, targetInfo) {
   const result = await runCommand(
     SVN_COMMAND,
     ["log", "--xml", "-r", "HEAD:1", "-l", "1", getRemoteTarget(targetInfo, config)],
-    { encoding: COMMAND_ENCODING, trim: true }
+    { encoding: COMMAND_ENCODING, trim: true, debug: config.debug }
   );
   const parsed = xmlParser.parse(result.stdout);
   const entry = parsed?.log?.logentry;
@@ -100,7 +101,7 @@ export async function getPendingRevisions(config, targetInfo, startExclusive, en
       `${startRevision}:${endInclusive}`,
       getRemoteTarget(targetInfo, config)
     ],
-    { encoding: COMMAND_ENCODING, trim: true }
+    { encoding: COMMAND_ENCODING, trim: true, debug: config.debug }
   );
   const parsed = xmlParser.parse(result.stdout);
 
@@ -115,7 +116,7 @@ export async function getRevisionDiff(config, revision) {
   const result = await runCommand(
     SVN_COMMAND,
     ["diff", "--git", "--internal-diff", "--ignore-properties", "-c", String(revision), config.target],
-    { encoding: COMMAND_ENCODING, trim: false }
+    { encoding: COMMAND_ENCODING, trim: false, debug: config.debug }
   );
 
   return result.stdout;
@@ -145,7 +146,7 @@ export async function getRevisionDetails(config, targetInfo, revision) {
   const result = await runCommand(
     SVN_COMMAND,
     ["log", "--xml", "-v", "-c", String(revision), getRemoteTarget(targetInfo, config)],
-    { encoding: COMMAND_ENCODING, trim: true }
+    { encoding: COMMAND_ENCODING, trim: true, debug: config.debug }
   );
   const parsed = xmlParser.parse(result.stdout);
   const entry = parsed?.log?.logentry;