throughline 0.3.23 → 0.3.24

package/README.md

@@ -509,6 +509,23 @@ Two things to know:
    `~/.npm-global/bin` is **before** the Windows npm path in `PATH` (the
    `.bashrc` snippet above prepends, so it does this naturally).
 
+**`.vscode/tasks.json` should not be committed to git (recommended)**
+
+The `Throughline Monitor` task that gets auto-generated contains absolute
+paths specific to your machine (`process.execPath` and the install location
+of `throughline.mjs`). For shared repositories, add one of these to
+`.gitignore`:
+
+```gitignore
+.vscode/tasks.json     # only ignore tasks.json (settings.json etc. stay shared)
+.vscode/                # ignore the whole .vscode directory
+```
+
+Throughline detects this and prints a one-time recommendation when it first
+creates / merges / repairs the file. (You don't have to follow the advice —
+v0.3.23+ auto-repairs stale absolute paths anyway, so committing is not
+catastrophic.)
+
 **Cross-environment `.vscode/tasks.json` errors after switching machines**
 
 If you commit `.vscode/tasks.json` to git and pull it on a different machine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [

package/src/vscode-task.mjs

@@ -19,6 +19,7 @@ import { join, dirname, isAbsolute } from 'node:path';
 
 const MONITOR_LABEL = 'Throughline Monitor';
 const JSONC_MARKER_FILENAME = '.throughline-jsonc-noted';
+const GITIGNORE_MARKER_FILENAME = '.throughline-gitignore-noted';
 
 /**
  * VSCode 系エディタが動いているかを env から推定する。
@@ -243,6 +244,67 @@ function emitSetupNotice(action) {
   if (text) process.stdout.write(text);
 }
 
+/**
+ * `.vscode/tasks.json` が gitignore 推奨対象か判定する。
+ *
+ * 推奨条件:
+ *   - cwd が git リポジトリ (`.git/` がある) かつ
+ *   - `.gitignore` に `.vscode/tasks.json` 相当のエントリが無い
+ *
+ * 単独プロジェクト (.git なし) は判定対象外 (false を返す)。共有しないので
+ * gitignore の必要性そのものが無いため。
+ *
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function shouldRecommendGitignore(cwd) {
+  const gitDir = join(cwd, '.git');
+  if (!existsSync(gitDir)) return false;
+
+  const gitignorePath = join(cwd, '.gitignore');
+  if (!existsSync(gitignorePath)) return true;
+
+  const content = readFileSync(gitignorePath, 'utf8');
+  const lines = content.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    // 否定 (!) は除外しない: "!.vscode/tasks.json" は明示的に追跡したい意図なので推奨を出すべき
+    if (line.startsWith('!')) continue;
+    // .vscode 全体除外 / tasks.json 単独除外 / .vscode/* どれかを含むか
+    if (line === '.vscode' || line === '.vscode/' || line === '/.vscode' || line === '/.vscode/') return false;
+    if (line === '.vscode/*' || line === '.vscode/**') return false;
+    if (line === '.vscode/tasks.json' || line === '/.vscode/tasks.json') return false;
+  }
+  return true;
+}
+
+function emitGitignoreRecommendationOnce(vscodeDir) {
+  const markerPath = join(vscodeDir, GITIGNORE_MARKER_FILENAME);
+  if (existsSync(markerPath)) return;
+  process.stdout.write(
+    '<system-reminder>\n' +
+    'Throughline ヒント: .vscode/tasks.json には現環境の絶対パス (node 実行ファイル / throughline.mjs)\n' +
+    'が書き込まれます。共有リポジトリで commit すると別 OS / 別 install 場所のメンバーで起動失敗の\n' +
+    '原因になるため、.gitignore に以下のいずれかを追加することを推奨します:\n' +
+    '\n' +
+    '  .vscode/tasks.json     # tasks.json だけ除外 (settings.json 等は共有可)\n' +
+    '  .vscode/                # .vscode 配下を全部除外\n' +
+    '\n' +
+    'なお Throughline v0.3.23+ は別環境の絶対パスが焼き込まれた tasks.json を\n' +
+    '自動修復するため、commit してしまっても致命的ではありません。あくまで推奨です。\n' +
+    '\n' +
+    'この通知はプロジェクトごとに 1 度だけ流れます。必ずユーザー（あなたの対話相手）に日本語でそのまま伝えてください。\n' +
+    '</system-reminder>\n'
+  );
+  try {
+    writeFileSync(markerPath, `${new Date().toISOString()}\n`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[throughline] failed to write gitignore marker: ${msg}\n`);
+  }
+}
+
 function emitJsoncGuidanceOnce(vscodeDir) {
   const markerPath = join(vscodeDir, JSONC_MARKER_FILENAME);
   if (existsSync(markerPath)) return;
@@ -302,6 +364,7 @@ export function ensureMonitorTaskFile(opts = {}) {
     const obj = { version: '2.0.0', tasks: [buildMonitorTask(bin)] };
     atomicWrite(tasksPath, JSON.stringify(obj, null, 2) + '\n');
     emitSetupNotice('created');
+    if (shouldRecommendGitignore(cwd)) emitGitignoreRecommendationOnce(vscodeDir);
     return { action: 'created', path: tasksPath };
   }
 
@@ -336,6 +399,7 @@ export function ensureMonitorTaskFile(opts = {}) {
       const nextObj = { ...obj, version: obj.version ?? '2.0.0', tasks: nextTasks };
       atomicWrite(tasksPath, JSON.stringify(nextObj, null, indent) + '\n');
       emitSetupNotice('repaired');
+      if (shouldRecommendGitignore(cwd)) emitGitignoreRecommendationOnce(vscodeDir);
       return { action: 'repaired', path: tasksPath };
     }
     return { action: 'already_present', path: tasksPath };
@@ -349,5 +413,6 @@ export function ensureMonitorTaskFile(opts = {}) {
   };
   atomicWrite(tasksPath, JSON.stringify(nextObj, null, indent) + '\n');
   emitSetupNotice('merged');
+  if (shouldRecommendGitignore(cwd)) emitGitignoreRecommendationOnce(vscodeDir);
   return { action: 'merged', path: tasksPath };
 }

package/src/vscode-task.test.mjs

@@ -13,6 +13,7 @@ import {
   isMonitorTaskBroken,
   buildMonitorTask,
   buildSetupNotice,
+  shouldRecommendGitignore,
 } from './vscode-task.mjs';
 
 const VSCODE_ENV = { TERM_PROGRAM: 'vscode' };
@@ -481,6 +482,175 @@ test('ensureMonitorTaskFile: second call is idempotent (already_present after cr
   }
 });
 
+// --- shouldRecommendGitignore ---
+
+test('shouldRecommendGitignore: false when not a git repo (.git missing)', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    assert.equal(shouldRecommendGitignore(dir), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('shouldRecommendGitignore: true when git repo has no .gitignore', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    mkdirSync(join(dir, '.git'));
+    assert.equal(shouldRecommendGitignore(dir), true);
+  } finally {
+    cleanup();
+  }
+});
+
+test('shouldRecommendGitignore: true when .gitignore does not list .vscode/tasks.json', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    mkdirSync(join(dir, '.git'));
+    writeFileSync(join(dir, '.gitignore'), 'node_modules/\n*.log\n');
+    assert.equal(shouldRecommendGitignore(dir), true);
+  } finally {
+    cleanup();
+  }
+});
+
+test('shouldRecommendGitignore: false when .gitignore has .vscode/tasks.json', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    mkdirSync(join(dir, '.git'));
+    writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.vscode/tasks.json\n');
+    assert.equal(shouldRecommendGitignore(dir), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('shouldRecommendGitignore: false when .gitignore has .vscode/ (whole dir)', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    mkdirSync(join(dir, '.git'));
+    writeFileSync(join(dir, '.gitignore'), '.vscode/\n');
+    assert.equal(shouldRecommendGitignore(dir), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('shouldRecommendGitignore: false when .gitignore has .vscode (no slash)', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    mkdirSync(join(dir, '.git'));
+    writeFileSync(join(dir, '.gitignore'), '.vscode\n');
+    assert.equal(shouldRecommendGitignore(dir), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('shouldRecommendGitignore: ignores comments and negation lines', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    mkdirSync(join(dir, '.git'));
+    // 否定パターンは「除外しない」意図なので、推奨は引き続き出す
+    writeFileSync(join(dir, '.gitignore'), '# comment\n!.vscode/tasks.json\n');
+    assert.equal(shouldRecommendGitignore(dir), true);
+  } finally {
+    cleanup();
+  }
+});
+
+// --- ensureMonitorTaskFile: gitignore recommendation notice ---
+
+test('ensureMonitorTaskFile: created emits gitignore recommendation when .git exists and no .gitignore entry', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  const captured = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk) => {
+    captured.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+    return true;
+  };
+  try {
+    mkdirSync(join(dir, '.git'));
+    const result = ensureMonitorTaskFile({
+      cwd: dir,
+      env: VSCODE_ENV,
+      throughlineBin: FAKE_BIN,
+    });
+    assert.equal(result.action, 'created');
+  } finally {
+    process.stdout.write = origWrite;
+    cleanup();
+  }
+  const joined = captured.join('');
+  assert.ok(joined.includes('.gitignore'), 'should emit gitignore recommendation');
+  assert.ok(joined.includes('Reload Window'), 'should still emit setup notice');
+});
+
+test('ensureMonitorTaskFile: created does NOT emit gitignore recommendation when not a git repo', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  const captured = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk) => {
+    captured.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+    return true;
+  };
+  try {
+    const result = ensureMonitorTaskFile({
+      cwd: dir,
+      env: VSCODE_ENV,
+      throughlineBin: FAKE_BIN,
+    });
+    assert.equal(result.action, 'created');
+  } finally {
+    process.stdout.write = origWrite;
+    cleanup();
+  }
+  const joined = captured.join('');
+  assert.ok(!joined.includes('gitignore'), 'should not mention gitignore for non-git dirs');
+});
+
+test('ensureMonitorTaskFile: gitignore recommendation is emitted only once per project', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  try {
+    mkdirSync(join(dir, '.git'));
+
+    const captured = [];
+    const origWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk) => {
+      captured.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+      return true;
+    };
+    try {
+      // 1 回目: created → gitignore 推奨が出る
+      const r1 = ensureMonitorTaskFile({
+        cwd: dir,
+        env: VSCODE_ENV,
+        throughlineBin: FAKE_BIN,
+      });
+      assert.equal(r1.action, 'created');
+      const firstCount = captured.filter((s) => s.includes('gitignore')).length;
+      assert.equal(firstCount, 1);
+
+      // tasks.json を一度消して再 created 状況を作る
+      // （実運用では already_present になるので現実的ではないが、marker の効きを見る）
+      const tasksPath = join(dir, '.vscode', 'tasks.json');
+      rmSync(tasksPath);
+      const r2 = ensureMonitorTaskFile({
+        cwd: dir,
+        env: VSCODE_ENV,
+        throughlineBin: FAKE_BIN,
+      });
+      assert.equal(r2.action, 'created');
+      const secondCount = captured.filter((s) => s.includes('gitignore')).length;
+      assert.equal(secondCount, 1, 'marker file should suppress 2nd recommendation');
+    } finally {
+      process.stdout.write = origWrite;
+    }
+  } finally {
+    cleanup();
+  }
+});
+
 // --- ensureMonitorTaskFile: cross-environment repair (地雷 4) ---
 
 test('ensureMonitorTaskFile: repaired when existing task points to non-existent absolute paths', () => {