throughline 0.3.23 → 0.3.25

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 から推定する。
@@ -238,14 +239,98 @@ export function buildSetupNotice(action) {
   return null;
 }
 
-function emitSetupNotice(action) {
+function shouldEmitNotices(env) {
+  return env.THROUGHLINE_SUPPRESS_VSCODE_NOTICES !== '1';
+}
+
+function emitSetupNotice(action, env) {
+  if (!shouldEmitNotices(env)) return;
   const text = buildSetupNotice(action);
   if (text) process.stdout.write(text);
 }
 
-function emitJsoncGuidanceOnce(vscodeDir) {
+/**
+ * `.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, env) {
+  const markerPath = join(vscodeDir, GITIGNORE_MARKER_FILENAME);
+  if (existsSync(markerPath)) return;
+  if (!shouldEmitNotices(env)) {
+    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`);
+    }
+    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, env) {
   const markerPath = join(vscodeDir, JSONC_MARKER_FILENAME);
   if (existsSync(markerPath)) return;
+  if (!shouldEmitNotices(env)) {
+    try {
+      writeFileSync(markerPath, `${new Date().toISOString()}\n`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'unknown';
+      process.stderr.write(`[throughline] failed to write JSONC marker: ${msg}\n`);
+    }
+    return;
+  }
   process.stderr.write(
     `[throughline] .vscode/tasks.json contains JSONC features (comments or trailing commas). ` +
       `Auto-edit is unsafe on this file — add the Throughline Monitor task manually. ` +
@@ -301,14 +386,15 @@ export function ensureMonitorTaskFile(opts = {}) {
     if (!existsSync(vscodeDir)) mkdirSync(vscodeDir, { recursive: true });
     const obj = { version: '2.0.0', tasks: [buildMonitorTask(bin)] };
     atomicWrite(tasksPath, JSON.stringify(obj, null, 2) + '\n');
-    emitSetupNotice('created');
+    emitSetupNotice('created', env);
+    if (shouldRecommendGitignore(cwd)) emitGitignoreRecommendationOnce(vscodeDir, env);
     return { action: 'created', path: tasksPath };
   }
 
   const text = readFileSync(tasksPath, 'utf8');
 
   if (detectJsoncFeatures(text)) {
-    emitJsoncGuidanceOnce(vscodeDir);
+    emitJsoncGuidanceOnce(vscodeDir, env);
     return { action: 'skipped', reason: 'jsonc_unsupported', path: tasksPath };
   }
 
@@ -335,7 +421,8 @@ export function ensureMonitorTaskFile(opts = {}) {
       nextTasks[existingIdx] = repaired;
       const nextObj = { ...obj, version: obj.version ?? '2.0.0', tasks: nextTasks };
       atomicWrite(tasksPath, JSON.stringify(nextObj, null, indent) + '\n');
-      emitSetupNotice('repaired');
+      emitSetupNotice('repaired', env);
+      if (shouldRecommendGitignore(cwd)) emitGitignoreRecommendationOnce(vscodeDir, env);
       return { action: 'repaired', path: tasksPath };
     }
     return { action: 'already_present', path: tasksPath };
@@ -348,6 +435,7 @@ export function ensureMonitorTaskFile(opts = {}) {
     tasks: [...(Array.isArray(obj.tasks) ? obj.tasks : []), buildMonitorTask(bin)],
   };
   atomicWrite(tasksPath, JSON.stringify(nextObj, null, indent) + '\n');
-  emitSetupNotice('merged');
+  emitSetupNotice('merged', env);
+  if (shouldRecommendGitignore(cwd)) emitGitignoreRecommendationOnce(vscodeDir, env);
   return { action: 'merged', path: tasksPath };
 }

package/src/vscode-task.test.mjs

@@ -13,9 +13,16 @@ import {
   isMonitorTaskBroken,
   buildMonitorTask,
   buildSetupNotice,
+  shouldRecommendGitignore,
 } from './vscode-task.mjs';
 
-const VSCODE_ENV = { TERM_PROGRAM: 'vscode' };
+const VSCODE_ENV = {
+  TERM_PROGRAM: 'vscode',
+  THROUGHLINE_SUPPRESS_VSCODE_NOTICES: '1',
+};
+// Production notices are Claude-facing additional context. Tests keep them
+// silent by default and opt in only when asserting notice text.
+const VSCODE_NOTICE_ENV = { TERM_PROGRAM: 'vscode' };
 // 実在する絶対パスを使う。`isMonitorTaskBroken` が「絶対パス + 非存在」で broken 判定するので、
 // 架空パスを使うと意図せず repaired ブランチに落ちてしまう。
 const FAKE_BIN = process.execPath;
@@ -435,7 +442,11 @@ test('ensureMonitorTaskFile: already_present when command references throughline
         {
           label: 'My Custom Monitor',
           type: 'process',
-          command: '/usr/bin/node',
+          // 実在する絶対パスを使う。`/usr/bin/node` は WSL2 では実在するが
+          // CI runner (Linux/macOS は /opt/hostedtoolcache, Windows は別) では
+          // 存在しないので isMonitorTaskBroken が true になり repaired ブランチに落ちる。
+          // process.execPath なら「いま走らせている node 自身の絶対パス」なので必ず実在する。
+          command: process.execPath,
           // 相対パスにして broken 判定を避ける（このテストは「label renamed でも検出できるか」だけが論点）
           args: ['./throughline.mjs', 'monitor'],
         },
@@ -481,6 +492,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_NOTICE_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_NOTICE_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_NOTICE_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', () => {
@@ -621,7 +801,7 @@ test('ensureMonitorTaskFile: repaired emits notice on stdout', () => {
 
     const result = ensureMonitorTaskFile({
       cwd: dir,
-      env: VSCODE_ENV,
+      env: VSCODE_NOTICE_ENV,
       throughlineBin: FAKE_BIN,
     });
     assert.equal(result.action, 'repaired');
@@ -697,7 +877,7 @@ test('ensureMonitorTaskFile: jsonc_unsupported marker suppresses stderr on 2nd c
     try {
       const r1 = ensureMonitorTaskFile({
         cwd: dir,
-        env: VSCODE_ENV,
+        env: VSCODE_NOTICE_ENV,
         throughlineBin: FAKE_BIN,
       });
       assert.equal(r1.action, 'skipped');
@@ -786,13 +966,13 @@ test('buildSetupNotice: ensureMonitorTaskFile writes notice to stdout on first c
   try {
     const r1 = ensureMonitorTaskFile({
       cwd: dir,
-      env: VSCODE_ENV,
+      env: VSCODE_NOTICE_ENV,
       throughlineBin: FAKE_BIN,
     });
     assert.equal(r1.action, 'created');
     const r2 = ensureMonitorTaskFile({
       cwd: dir,
-      env: VSCODE_ENV,
+      env: VSCODE_NOTICE_ENV,
       throughlineBin: FAKE_BIN,
     });
     assert.equal(r2.action, 'already_present');