x7-code-line 0.1.0 → 0.3.0

package/README.md

@@ -18,6 +18,20 @@
 
 作为 npm 依赖安装时，`postinstall` 脚本使用 `INIT_CWD` 作为当前安装目录，也就是执行 `npm install` 时所在的项目目录。
 
+如果只是全局安装：
+
+```sh
+npm install -g x7-code-line
+```
+
+此时只安装 CLI，不会自动为任何项目写入 hooks。全局安装完成后，需要手动执行：
+
+```sh
+x7-code-line install --dir <absolute-path>
+```
+
+只有在 `X7_CODE_LINE_DIRS` 或 `X7_CODE_LINE_CONFIG` 明确提供目标目录时，`postinstall` 才会继续执行项目安装逻辑。
+
 当前安装目录会创建或覆盖：
 
 ```text
@@ -100,6 +114,7 @@ git diff --no-ext-diff --unified=0 --no-color
 - 变更类型：`add` 或 `delete`
 - 行号
 - 行内容
+- 该文件当前的修改时间
 
 如果该 ID 不在 AI diff 缓存中，就写入普通 diff 缓存：
 
@@ -146,6 +161,15 @@ git diff --cached --no-ext-diff --unified=0 --no-color
 .x7-code-line/pending-commit.json
 ```
 
+计算完成后，会清除当前仓库在以下两份中心缓存中的条目：
+
+```text
+.x7-code-line/ai-diff-line-ids.json
+.x7-code-line/normal-diff-line-ids.json
+```
+
+其他项目的缓存不会被修改。
+
 `commit-msg` 会读取该结果，并追加或替换 trailer：
 
 ```text
@@ -160,25 +184,45 @@ x7-ai-lines: 0
 
 ## 多项目安装
 
-通过 CLI 参数指定多个目标目录：
+`install` 至少需要传入一个目录；0 目录场景会直接失败。
+
+默认要求传入绝对路径：
+
+```sh
+npm  install -g  x7-code-line --dir /abs/path/repo-a --dir /abs/path/repo-b
+```
+
+例如，将 `x7-code-line` 安装在 C 盘目录，但指定 D 盘的 Git 项目：
+
+```powershell
+cd C:\x7-tools\x7-code-line-host
+npm  install -g  x7-code-line  --dir D:\work\repo-a --dir D:\work\repo-b
+```
+
+如果确实需要解析相对路径，必须显式传 `--relative`：
 
 ```sh
-npx --no-install x7-code-line install --dir ../repo-a --dir ../repo-b
+npm  install -g  x7-code-line  --relative --dir ../repo-a --dir ../repo-b
 ```
 
-也可以在安装时通过环境变量指定。
+此时相对路径基于当前执行 `install` 命令的目录解析。
+
+也可以在安装时通过环境变量指定多个目标目录。
+
+如果通过环境变量或配置文件传相对路径，需要同时设置 `X7_CODE_LINE_RELATIVE_PATHS=1`。
 
-macOS / Linux 使用 `:` 作为目录分隔符：
+macOS / Linux 示例：
 
 ```sh
-X7_CODE_LINE_DIRS="../repo-a:../repo-b" npm install x7-code-line
+X7_CODE_LINE_RELATIVE_PATHS=1 X7_CODE_LINE_DIRS="../repo-a:../repo-b" npm install -g x7-code-line 
 ```
 
 Windows 使用 `;` 作为目录分隔符：
 
 ```powershell
+$env:X7_CODE_LINE_RELATIVE_PATHS = "1"
 $env:X7_CODE_LINE_DIRS = "../repo-a;../repo-b"
-npm install x7-code-line
+npm install -g x7-code-line
 ```
 
 ## 配置文件
@@ -231,10 +275,40 @@ which npx
 $env:X7_CODE_LINE_DIRS = "D:\repo-a;D:\repo-b"
 ```
 
+## 增量添加目录
+
+在已经完成安装的当前安装目录下，可以使用 `addDir` 增量添加新的项目目录：
+
+```sh
+x7-code-line addDir --dir /abs/path/repo-c
+```
+
+这个命令只做两件事：
+
+- 把新目录追加到当前安装目录 `.x7-code-line/projects.json`
+- 为新目录安装 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg`
+
+它不会重写当前安装目录的 `.cursor/hooks.json`、`.codex/hooks.json`，也不会重写已有项目集合。
+
+`addDir` 会沿用与 `install` 相同的严格校验：
+
+- 目录必须真实存在
+- 目录必须可访问
+- 目录必须包含可用的 `.git` 目录
+
+任一新增目录不满足条件时，命令直接失败，不会继续追加。
+
+默认只接受绝对路径；如果需要解析相对路径，需要显式传入：
+
+```sh
+x7-code-line addDir --relative --dir ../repo-c
+```
+
 ## CLI 命令
 
 ```sh
-x7-code-line install [--config path] [--dir path ...]
+x7-code-line install --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]
+x7-code-line addDir --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]
 x7-code-line prompt-submit
 x7-code-line stop
 x7-code-line git-pre-commit
@@ -274,7 +348,7 @@ npm login
 确认 `package.json` 中的包名和版本号正确后，执行：
 
 ```sh
-npm publish
+npm publish --access public
 ```
 
 如果 npm 账号开启了 2FA，通常需要附带 OTP：
@@ -291,7 +365,7 @@ npm publish --access public --otp <6位验证码>
 
 ### 更新已发布版本
 
-每次发布新版本前，先提升版本号：
+每次发布新版本前，手动修改package.json版本号或命令提升版本号：
 
 ```sh
 npm version patch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x7-code-line",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Install Cursor, Codex, and git hooks for x7 code line workflows.",
   "main": "src/index.js",
   "bin": {

package/src/cache.js

@@ -67,6 +67,19 @@ function addProjectId(cache, projectDir, id) {
   return false;
 }
 
+function clearProjectIds(cache, projectDir) {
+  const key = path.resolve(projectDir);
+  if (!cache.projects || typeof cache.projects !== "object" || Array.isArray(cache.projects)) {
+    cache.projects = {};
+    return false;
+  }
+  if (Object.prototype.hasOwnProperty.call(cache.projects, key)) {
+    delete cache.projects[key];
+    return true;
+  }
+  return false;
+}
+
 function ensureJson(filePath, defaultValue) {
   if (!fs.existsSync(filePath)) {
     writeJson(filePath, defaultValue);
@@ -92,6 +105,7 @@ module.exports = {
   PENDING_COMMIT_FILE,
   PROJECTS_CACHE_FILE,
   addProjectId,
+  clearProjectIds,
   ensureCacheFiles,
   getCacheDir,
   getProjectIds,

package/src/cli.js

@@ -3,11 +3,13 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { handlePromptSubmit, handleStop } = require("./agent-hooks");
-const { install } = require("./install");
+const { addDirs, install } = require("./install");
 const { appendCommitTrailer } = require("./git-trailer");
 const {
   AI_DIFF_CACHE_FILE,
+  NORMAL_DIFF_CACHE_FILE,
   PENDING_COMMIT_FILE,
+  clearProjectIds,
   getCacheDir,
   getProjectIds,
   readLineIdCache
@@ -20,6 +22,8 @@ async function runCli(argv) {
   switch (command) {
     case "install":
       return install(parseInstallOptions(rest));
+    case "addDir":
+      return addDirs(parseInstallOptions(rest));
     case "prompt-submit":
     case "cursor-before-submit-prompt":
     case "codex-user-prompt-submit":
@@ -44,13 +48,16 @@ async function runCli(argv) {
 function parseInstallOptions(args) {
   const options = {
     targetDirs: [],
-    configPath: undefined
+    configPath: undefined,
+    relativePaths: false
   };
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--config" || arg === "-c") {
       options.configPath = requireValue(args, (index += 1), arg);
+    } else if (arg === "--relative") {
+      options.relativePaths = true;
     } else if (arg === "--dir" || arg === "-d") {
       options.targetDirs.push(requireValue(args, (index += 1), arg));
     } else if (arg === "--dirs") {
@@ -75,6 +82,7 @@ async function runGitPreCommit() {
   const baseDir = getBaseDir();
   const projectDir = process.cwd();
   const aiCache = readLineIdCache(baseDir, AI_DIFF_CACHE_FILE);
+  const normalCache = readLineIdCache(baseDir, NORMAL_DIFF_CACHE_FILE);
   const aiIds = getProjectIds(aiCache, projectDir);
   const stagedIds = getGitDiffLineIds(projectDir, { staged: true });
   const aiLineCount = stagedIds.filter((id) => aiIds.has(id)).length;
@@ -83,6 +91,10 @@ async function runGitPreCommit() {
     pendingPath,
     `${JSON.stringify({ projects: { [path.resolve(projectDir)]: { aiLineCount } } }, null, 2)}\n`
   );
+  clearProjectIds(aiCache, projectDir);
+  clearProjectIds(normalCache, projectDir);
+  writeCacheFile(baseDir, AI_DIFF_CACHE_FILE, aiCache);
+  writeCacheFile(baseDir, NORMAL_DIFF_CACHE_FILE, normalCache);
 
   if (process.env.X7_CODE_LINE_DEBUG === "1") {
     console.error(`[x7-code-line] git pre-commit ai lines: ${aiLineCount}`);
@@ -113,10 +125,16 @@ function readPendingAiLineCount(baseDir, projectDir) {
   }
 }
 
+function writeCacheFile(baseDir, fileName, cache) {
+  const cacheDir = getCacheDir(baseDir);
+  fs.writeFileSync(path.join(cacheDir, fileName), `${JSON.stringify(cache, null, 2)}\n`);
+}
+
 function printHelp() {
   const text = [
     "Usage:",
-    "  x7-code-line install [--config path] [--dir path ...]",
+    "  x7-code-line install --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]",
+    "  x7-code-line addDir --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]",
     "  x7-code-line prompt-submit",
     "  x7-code-line stop",
     "  x7-code-line git-pre-commit",

package/src/diff-lines.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const crypto = require("node:crypto");
+const fs = require("node:fs");
 const path = require("node:path");
 const { execFileSync } = require("node:child_process");
 
@@ -16,14 +17,15 @@ function getGitDiffLineIds(projectDir, options = {}) {
     stdio: ["ignore", "pipe", "ignore"]
   });
 
-  return parseDiffLineIds(projectDir, diff);
+  return parseDiffLineIds(projectDir, diff, options);
 }
 
-function parseDiffLineIds(projectDir, diff) {
+function parseDiffLineIds(projectDir, diff, options = {}) {
   const ids = [];
   let currentFile = "";
   let oldLine = 0;
   let newLine = 0;
+  const fileMtimes = new Map();
 
   for (const line of diff.split(/\r?\n/u)) {
     if (line.startsWith("+++ b/")) {
@@ -47,10 +49,21 @@ function parseDiffLineIds(projectDir, diff) {
     }
 
     if (line.startsWith("+") && !line.startsWith("+++")) {
-      ids.push(makeLineId(projectDir, currentFile, "add", newLine, line.slice(1)));
+      ids.push(
+        makeLineId(projectDir, currentFile, "add", newLine, line.slice(1), getFileModifiedTime(projectDir, currentFile, fileMtimes))
+      );
       newLine += 1;
     } else if (line.startsWith("-") && !line.startsWith("---")) {
-      ids.push(makeLineId(projectDir, currentFile, "delete", oldLine, line.slice(1)));
+      ids.push(
+        makeLineId(
+          projectDir,
+          currentFile,
+          "delete",
+          oldLine,
+          line.slice(1),
+          getFileModifiedTime(projectDir, currentFile, fileMtimes)
+        )
+      );
       oldLine += 1;
     } else if (line.startsWith(" ")) {
       oldLine += 1;
@@ -61,7 +74,7 @@ function parseDiffLineIds(projectDir, diff) {
   return ids;
 }
 
-function makeLineId(projectDir, filePath, changeType, lineNumber, content) {
+function makeLineId(projectDir, filePath, changeType, lineNumber, content, modifiedTimeMs = 0) {
   return crypto
     .createHash("sha256")
     .update(
@@ -70,12 +83,31 @@ function makeLineId(projectDir, filePath, changeType, lineNumber, content) {
         file: filePath,
         changeType,
         lineNumber,
-        content
+        content,
+        modifiedTimeMs
       })
     )
     .digest("hex");
 }
 
+function getFileModifiedTime(projectDir, filePath, fileMtimes) {
+  const key = `${path.resolve(projectDir)}\0${filePath}`;
+  if (fileMtimes.has(key)) {
+    return fileMtimes.get(key);
+  }
+
+  const absolutePath = path.resolve(projectDir, filePath);
+  let modifiedTimeMs = 0;
+  try {
+    modifiedTimeMs = fs.statSync(absolutePath).mtimeMs;
+  } catch {
+    modifiedTimeMs = 0;
+  }
+
+  fileMtimes.set(key, modifiedTimeMs);
+  return modifiedTimeMs;
+}
+
 module.exports = {
   getGitDiffLineIds,
   makeLineId,

package/src/install.js

@@ -2,32 +2,70 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { CACHE_DIR_NAME, ensureCacheFiles, writeProjects } = require("./cache");
+const { CACHE_DIR_NAME, ensureCacheFiles, readProjects, writeProjects } = require("./cache");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 
 function install(options = {}) {
+  const pathBaseDir = path.resolve(options.pathBaseDir || process.env.INIT_CWD || process.cwd());
   const config = readConfig(options.configPath || process.env.X7_CODE_LINE_CONFIG);
-  const targetDirs = normalizeTargetDirs(options.targetDirs, config);
-  const cacheBaseDir = path.resolve(options.cacheBaseDir || process.env.INIT_CWD || process.cwd());
+  const targetDirs = normalizeTargetDirs(options.targetDirs, config, {
+    relativePaths: Boolean(options.relativePaths || process.env.X7_CODE_LINE_RELATIVE_PATHS === "1"),
+    pathBaseDir
+  });
+  const cacheBaseDir = path.resolve(options.cacheBaseDir || pathBaseDir);
+  const validatedTargets = validateTargets(targetDirs, config);
 
   installCurrentProjectFiles(cacheBaseDir);
-  for (const targetDir of targetDirs) {
-    installGitHooksInto(targetDir, config, cacheBaseDir);
+  for (const target of validatedTargets) {
+    installGitHooksInto(target, cacheBaseDir);
   }
-  writeProjects(cacheBaseDir, targetDirs);
+  writeProjects(cacheBaseDir, validatedTargets.map((target) => target.targetDir));
 
-  return targetDirs;
+  return validatedTargets.map((target) => target.targetDir);
 }
 
 function installFromPostinstall() {
   const envDirs = splitList(process.env.X7_CODE_LINE_DIRS);
-  const targetDirs = envDirs.length > 0 ? envDirs : [process.env.INIT_CWD || process.cwd()];
+  const configPath = process.env.X7_CODE_LINE_CONFIG;
+  const config = readConfig(configPath);
+  const configuredDirs = Array.isArray(config.dirs) ? config.dirs.map((dir) => String(dir || "").trim()).filter(Boolean) : [];
+
+  if (envDirs.length === 0 && configuredDirs.length === 0) {
+    return [];
+  }
 
   return install({
-    configPath: process.env.X7_CODE_LINE_CONFIG,
-    targetDirs
+    configPath,
+    targetDirs: envDirs,
+    relativePaths: process.env.X7_CODE_LINE_RELATIVE_PATHS === "1"
+  });
+}
+
+function addDirs(options = {}) {
+  const explicitDirs = Array.isArray(options.targetDirs) ? options.targetDirs.map((dir) => String(dir || "").trim()).filter(Boolean) : [];
+  if (explicitDirs.length === 0) {
+    throw new Error("addDir requires at least one --dir value");
+  }
+
+  const pathBaseDir = path.resolve(options.pathBaseDir || process.env.INIT_CWD || process.cwd());
+  const config = readConfig(options.configPath || process.env.X7_CODE_LINE_CONFIG);
+  const targetDirs = normalizeTargetDirs(explicitDirs, config, {
+    relativePaths: Boolean(options.relativePaths || process.env.X7_CODE_LINE_RELATIVE_PATHS === "1"),
+    pathBaseDir
   });
+  const cacheBaseDir = path.resolve(options.cacheBaseDir || pathBaseDir);
+  assertInstalledBase(cacheBaseDir);
+
+  const validatedTargets = validateTargets(targetDirs, config);
+  for (const target of validatedTargets) {
+    installGitHooksInto(target, cacheBaseDir);
+  }
+
+  const mergedProjects = [...new Set([...readProjects(cacheBaseDir), ...validatedTargets.map((target) => target.targetDir)])];
+  writeProjects(cacheBaseDir, mergedProjects);
+
+  return validatedTargets.map((target) => target.targetDir);
 }
 
 function installCurrentProjectFiles(cacheBaseDir) {
@@ -52,11 +90,8 @@ function installCurrentProjectFiles(cacheBaseDir) {
   );
 }
 
-function installGitHooksInto(targetDir, config = {}, cacheBaseDir = process.cwd()) {
-  const resolvedTarget = path.resolve(targetDir);
-  ensureDirectory(resolvedTarget);
-  const gitTargets = resolveGitTargets(resolvedTarget, config);
-  for (const gitDir of gitTargets) {
+function installGitHooksInto(target, cacheBaseDir = process.cwd()) {
+  for (const gitDir of target.gitDirs) {
     installGitHooks(gitDir, cacheBaseDir);
   }
 }
@@ -87,6 +122,63 @@ function resolveGitTargets(targetDir, config = {}) {
   });
 }
 
+function validateTargets(targetDirs, config = {}) {
+  return targetDirs.map((targetDir) => validateTarget(targetDir, config));
+}
+
+function validateTarget(targetDir, config = {}) {
+  const resolvedTarget = path.resolve(targetDir);
+  assertReachableDirectory(resolvedTarget);
+  const gitDirs = resolveGitTargets(resolvedTarget, config);
+
+  if (gitDirs.length === 0) {
+    throw new Error(`Target directory must contain a reachable .git directory: ${resolvedTarget}`);
+  }
+
+  const configured = Array.isArray(config.gitDirs) ? config.gitDirs : [];
+  if (configured.length > 0) {
+    const missing = configured
+      .map((gitDir) => path.resolve(resolvedTarget, gitDir))
+      .filter((gitDir) => !gitDirs.includes(gitDir));
+    if (missing.length > 0) {
+      throw new Error(`Configured gitDirs are not reachable in target directory: ${missing.join(", ")}`);
+    }
+  }
+
+  return { targetDir: resolvedTarget, gitDirs };
+}
+
+function assertReachableDirectory(directory) {
+  let stat;
+  try {
+    stat = fs.statSync(directory);
+  } catch {
+    throw new Error(`Target directory does not exist or is not reachable: ${directory}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Target path is not a directory: ${directory}`);
+  }
+
+  try {
+    fs.accessSync(directory, fs.constants.R_OK);
+  } catch {
+    throw new Error(`Target directory is not readable: ${directory}`);
+  }
+}
+
+function assertInstalledBase(cacheBaseDir) {
+  const installFile = path.join(cacheBaseDir, CACHE_DIR_NAME, "install.json");
+  try {
+    const stat = fs.statSync(installFile);
+    if (!stat.isFile()) {
+      throw new Error("");
+    }
+  } catch {
+    throw new Error(`Current directory is not an installed x7-code-line base: ${cacheBaseDir}`);
+  }
+}
+
 function readConfig(configPath) {
   if (!configPath) {
     return {};
@@ -103,15 +195,26 @@ function readConfig(configPath) {
   return config;
 }
 
-function normalizeTargetDirs(targetDirs = [], config = {}) {
+function normalizeTargetDirs(targetDirs = [], config = {}, options = {}) {
   const configuredDirs = Array.isArray(config.dirs) ? config.dirs : [];
   const dirs = [...targetDirs, ...configuredDirs].map((dir) => String(dir || "").trim()).filter(Boolean);
 
   if (dirs.length === 0) {
-    return [process.env.INIT_CWD || process.cwd()];
+    throw new Error("install requires at least one target directory");
   }
 
-  return [...new Set(dirs)].map((dir) => path.resolve(dir));
+  const baseDir = path.resolve(options.pathBaseDir || process.env.INIT_CWD || process.cwd());
+  return [...new Set(dirs)].map((dir) => normalizeTargetDir(dir, options.relativePaths, baseDir));
+}
+
+function normalizeTargetDir(dir, relativePaths, baseDir) {
+  if (path.isAbsolute(dir)) {
+    return path.resolve(dir);
+  }
+  if (!relativePaths) {
+    throw new Error(`Target directory must be an absolute path unless --relative is used: ${dir}`);
+  }
+  return path.resolve(baseDir, dir);
 }
 
 function splitList(value) {
@@ -165,6 +268,7 @@ function ensureDirectory(directory) {
 }
 
 module.exports = {
+  addDirs,
   CACHE_DIR_NAME,
   install,
   installFromPostinstall