throughline 0.3.20 → 0.3.22

package/.claude/commands/sc-detail.md

@@ -0,0 +1,22 @@
+---
+description: Throughline の退避済みターン（L2 本文 + L3 ツール入出力）を時刻で復元する
+argument-hint: <HH:MM:SS> または <HH:MM:SS>-<HH:MM:SS>
+---
+
+以下の Bash コマンドを実行し、結果を全文そのまま表示してください（要約せず、一字一句）。
+
+```bash
+throughline detail "$ARGUMENTS"
+```
+
+## 使い方
+
+- `/sc-detail 14:23:05` — 指定時刻のターンを復元
+- `/sc-detail 14:23-14:30` — 時刻範囲のターンをまとめて復元
+
+## 何が返るか
+
+- **L2**: そのターンの会話本文（ユーザー発言 + Claude 返答）
+- **L3**: そのターンで実行されたツールの入出力
+
+これは Throughline のセッション記憶 `~/.throughline/throughline.db` から読み出されます。

package/.claude/commands/tl.md

@@ -0,0 +1,30 @@
+---
+description: 次の新規セッションに現セッションの記憶を引き継ぐためのバトンを置く (Throughline)
+---
+
+Throughline の UserPromptSubmit hook が `/tl` を検出し、バトン（現セッション ID）を保存しました。
+
+次に必ずやること（スキップ厳禁）:
+
+1. 今この時点の「中断地点の状態」を自分の文脈から思い出し、以下 4 項目を Markdown で整理する:
+   - **次の一手**: 今まさに何をやろうとしていたか（1-3 文、具体的に）
+   - **現在の方針 / 仮説**: 追っているバグの原因、設計の方向性、調査中の観点など
+   - **未解決の疑問**: 判断保留中の論点
+   - **進行中 TODO**: 完了済みを除いた現行 TODO（TodoWrite の最新状態や Plan の内容を踏まえて、意味のあるものだけ）
+
+2. Bash ツールで次のコマンドを実行し、stdin で上記 Markdown を流し込む:
+
+   ```bash
+   throughline save-inflight <<'EOF'
+   **次の一手**: ...
+   **現在の方針**: ...
+   **未解決の疑問**: ...
+   **進行中 TODO**:
+   - [ ] ...
+   - [ ] ...
+   EOF
+   ```
+
+Bash の出力 (`[throughline] in-flight memo saved (N chars) for next session`) がそのまま完了確認になります。追加のユーザーへの報告テキストは不要です。ツール呼び出し後は何も返さずターンを終えて構いません（必要なら一言だけ）。
+
+バトン（および in-flight メモ）は 1 時間で失効します。失効後に新セッションを開いた場合は引き継ぎは発火しません。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [
@@ -21,6 +21,7 @@
   "files": [
     "bin/",
     "src/",
+    ".claude/commands/",
     "README.md",
     "LICENSE"
   ],

package/src/cli/install.mjs

@@ -10,10 +10,15 @@
  * node のインストール先や OS が変わっても PATH さえ通れば動く。
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, unlinkSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const SLASH_COMMANDS_SRC = join(PACKAGE_ROOT, '.claude', 'commands');
+const SC_SLASH_COMMAND_FILES = ['tl.md', 'sc-detail.md'];
+
 // Throughline が管理する hook コマンド一覧
 // schema v4 以降: PostToolUse (capture-tool) は廃止。Stop 内で L2/L3 を一括処理する。
 const SC_COMMANDS = [
@@ -34,7 +39,7 @@ const SC_HOOKS = {
     hooks: [{ type: 'command', command: 'throughline session-start' }],
   },
   Stop: {
-    hooks: [{ type: 'command', command: 'throughline process-turn' }],
+    hooks: [{ type: 'command', command: 'throughline process-turn', async: true }],
   },
   UserPromptSubmit: {
     hooks: [{ type: 'command', command: 'throughline prompt-submit' }],
@@ -48,6 +53,42 @@ function resolveSettingsPath(args) {
   return join(homedir(), '.claude', 'settings.json');
 }
 
+function resolveCommandsDir(args) {
+  if (args.includes('--project')) {
+    return join(process.cwd(), '.claude', 'commands');
+  }
+  return join(homedir(), '.claude', 'commands');
+}
+
+function installSlashCommands(commandsDir) {
+  if (!existsSync(SLASH_COMMANDS_SRC)) {
+    return { installed: [], skipped: 'source-missing' };
+  }
+  if (!existsSync(commandsDir)) mkdirSync(commandsDir, { recursive: true });
+  const installed = [];
+  for (const name of SC_SLASH_COMMAND_FILES) {
+    const src = join(SLASH_COMMANDS_SRC, name);
+    if (!existsSync(src)) continue;
+    const dest = join(commandsDir, name);
+    copyFileSync(src, dest);
+    installed.push(name);
+  }
+  return { installed, skipped: null };
+}
+
+function uninstallSlashCommands(commandsDir) {
+  const removed = [];
+  if (!existsSync(commandsDir)) return removed;
+  for (const name of SC_SLASH_COMMAND_FILES) {
+    const dest = join(commandsDir, name);
+    if (existsSync(dest)) {
+      unlinkSync(dest);
+      removed.push(name);
+    }
+  }
+  return removed;
+}
+
 function readSettings(settingsPath) {
   if (!existsSync(settingsPath)) return {};
   return JSON.parse(readFileSync(settingsPath, 'utf8'));
@@ -62,6 +103,7 @@ function writeSettings(settingsPath, obj) {
 export async function run(args = []) {
   const uninstall = args.includes('--uninstall');
   const settingsPath = resolveSettingsPath(args);
+  const commandsDir = resolveCommandsDir(args);
   const current = readSettings(settingsPath);
   const existingHooks = current.hooks ?? {};
   const scSet = new Set(SC_COMMANDS);
@@ -81,8 +123,12 @@ export async function run(args = []) {
     }
 
     writeSettings(settingsPath, current);
+    const removedCommands = uninstallSlashCommands(commandsDir);
     console.log('Throughline hooks を削除しました。');
     console.log(`  ${settingsPath}`);
+    if (removedCommands.length > 0) {
+      console.log(`  slash commands 削除: ${removedCommands.join(', ')} (${commandsDir})`);
+    }
     return;
   }
 
@@ -100,6 +146,7 @@ export async function run(args = []) {
 
   current.hooks = existingHooks;
   writeSettings(settingsPath, current);
+  const { installed: installedCommands, skipped } = installSlashCommands(commandsDir);
 
   const scope = args.includes('--project') ? 'プロジェクトローカル' : 'グローバル（全プロジェクト）';
   console.log(`Throughline hooks をインストールしました [${scope}]`);
@@ -110,5 +157,13 @@ export async function run(args = []) {
   console.log('  Stop             → throughline process-turn   (L1 要約 + L2 本文保存 + L3 詳細保存)');
   console.log('  UserPromptSubmit → throughline prompt-submit  (/tl バトン書き込み)');
   console.log('');
+  if (installedCommands.length > 0) {
+    console.log(`slash commands を配置しました: ${installedCommands.map(n => '/' + n.replace(/\.md$/, '')).join(', ')}`);
+    console.log(`  ${commandsDir}`);
+    console.log('');
+  } else if (skipped === 'source-missing') {
+    console.log('注意: パッケージ内に slash commands のソースが見つからないためスキップしました。');
+    console.log('');
+  }
   console.log('  アンインストール: throughline uninstall');
 }

package/src/cli/install.test.mjs

@@ -0,0 +1,179 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { run } from './install.mjs';
+
+function makeTempHome() {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-install-test-'));
+  const origUserprofile = process.env.USERPROFILE;
+  const origHome = process.env.HOME;
+  process.env.USERPROFILE = dir;
+  process.env.HOME = dir;
+  const resolved = homedir();
+  return {
+    dir,
+    resolved,
+    restore() {
+      if (origUserprofile === undefined) delete process.env.USERPROFILE;
+      else process.env.USERPROFILE = origUserprofile;
+      if (origHome === undefined) delete process.env.HOME;
+      else process.env.HOME = origHome;
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+function silence() {
+  const origLog = console.log;
+  const origErr = console.error;
+  console.log = () => {};
+  console.error = () => {};
+  return () => {
+    console.log = origLog;
+    console.error = origErr;
+  };
+}
+
+test('global install copies /tl and /sc-detail to ~/.claude/commands/', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    const tl = join(home.dir, '.claude', 'commands', 'tl.md');
+    const sc = join(home.dir, '.claude', 'commands', 'sc-detail.md');
+    assert.ok(existsSync(tl), 'tl.md should be installed globally');
+    assert.ok(existsSync(sc), 'sc-detail.md should be installed globally');
+    const tlBody = readFileSync(tl, 'utf8');
+    assert.match(tlBody, /Throughline/, 'tl.md content should be real');
+    const settings = JSON.parse(readFileSync(join(home.dir, '.claude', 'settings.json'), 'utf8'));
+    assert.ok(settings.hooks?.UserPromptSubmit, 'UserPromptSubmit hook should be registered');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('project install copies commands to cwd/.claude/commands/', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const projectDir = mkdtempSync(join(tmpdir(), 'tl-install-proj-'));
+  const origCwd = process.cwd();
+  process.chdir(projectDir);
+  const unsilence = silence();
+  try {
+    await run(['--project']);
+    const tl = join(projectDir, '.claude', 'commands', 'tl.md');
+    assert.ok(existsSync(tl), 'tl.md should be installed in project');
+    const globalTl = join(home.dir, '.claude', 'commands', 'tl.md');
+    assert.ok(!existsSync(globalTl), '--project should NOT touch global dir');
+  } finally {
+    unsilence();
+    process.chdir(origCwd);
+    home.restore();
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+test('uninstall removes slash command files', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    const tl = join(home.dir, '.claude', 'commands', 'tl.md');
+    assert.ok(existsSync(tl), 'install should have placed tl.md');
+    await run(['--uninstall']);
+    assert.ok(!existsSync(tl), 'uninstall should remove tl.md');
+    const sc = join(home.dir, '.claude', 'commands', 'sc-detail.md');
+    assert.ok(!existsSync(sc), 'uninstall should remove sc-detail.md');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('uninstall preserves unrelated slash commands in the same dir', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    const otherCmd = join(home.dir, '.claude', 'commands', 'unrelated.md');
+    writeFileSync(otherCmd, '# unrelated slash command\n');
+    await run(['--uninstall']);
+    assert.ok(existsSync(otherCmd), 'uninstall must not touch unrelated files');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('Stop hook is registered with async:true so it does not block ターン完了 UX', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    const settings = JSON.parse(readFileSync(join(home.dir, '.claude', 'settings.json'), 'utf8'));
+    const processTurnHook = settings.hooks.Stop
+      .flatMap(g => g.hooks ?? [])
+      .find(h => h.command === 'throughline process-turn');
+    assert.ok(processTurnHook, 'Stop should have throughline process-turn');
+    assert.equal(processTurnHook.async, true, 'Stop hook must be async to avoid blocking ターン完了');
+    const sessionStartHook = settings.hooks.SessionStart
+      .flatMap(g => g.hooks ?? [])
+      .find(h => h.command === 'throughline session-start');
+    assert.notEqual(sessionStartHook.async, true, 'SessionStart stays synchronous (needs to inject context before turn)');
+    const promptSubmitHook = settings.hooks.UserPromptSubmit
+      .flatMap(g => g.hooks ?? [])
+      .find(h => h.command === 'throughline prompt-submit');
+    assert.notEqual(promptSubmitHook.async, true, 'UserPromptSubmit stays synchronous (needs baton write committed before turn)');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('install is idempotent: second run keeps exactly one tl.md and one hook entry', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    await run([]);
+    const tl = join(home.dir, '.claude', 'commands', 'tl.md');
+    assert.ok(existsSync(tl));
+    const settings = JSON.parse(readFileSync(join(home.dir, '.claude', 'settings.json'), 'utf8'));
+    const stopGroups = settings.hooks.Stop;
+    const processTurnCount = stopGroups
+      .flatMap(g => g.hooks ?? [])
+      .filter(h => h.command === 'throughline process-turn')
+      .length;
+    assert.equal(processTurnCount, 1, 'double-install must not duplicate hook entries');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});