devlog-tracker 0.22.1 → 0.24.0

package/README.md

@@ -1,6 +1,6 @@
 # devlog-tracker
 
-**版本** 0.22.1
+**版本** 0.24.0
 
 在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
 
@@ -46,6 +46,13 @@ npx devlog-tracker init --codex --cursor
 其他工具已設定的 hook）。重新執行 `npx devlog-tracker init` 可以升級到套件目前的
 版本；`npx devlog-tracker status` 可以查目前裝的版本是否落後。
 
+裝 Codex 時，`init` 還會在專案根目錄的 `AGENTS.md` 加上（或更新）一段以
+`<!-- devlog-tracker:begin/end -->` 包住的說明，告訴 Codex 沒有 slash 指令時該讀
+`.devlog-tracker/commands/*.md`。區塊外的內容不會動，重跑 `init` 只會換掉區塊本身；
+區塊裡只有相對路徑，可以 commit。
+
+裝完 Codex 之後，第一次還要在 Codex 裡核准這些 hook，否則不會記錄（見下方〈Codex（選用）〉的「hook 需要審核」）。
+
 `init` 會把這台機器專屬的絕對路徑寫進 `.codex/hooks.json`、`.cursor/hooks.json` 與
 `.devlog-tracker/env.sh`。如果你把這些檔案 commit 進 git，每位隊友都要在自己的機器上
 跑一次 `npx devlog-tracker init`（路徑每台機器不同）；或者改成把 `.devlog-tracker/` 與
@@ -82,6 +89,18 @@ Claude Code 仍是主要安裝方式。若要在 Codex CLI 使用，先設定
 `hooks` 合併進專案（或 `~/.codex/`）的 `hooks.json`。也可以把整個 `codex/hooks/` 與
 `hooks/scripts/` vendoring 到專案，並調整 command 路徑；兩者的相對目錄必須維持可用。
 
+**hook 需要審核才會執行。** Codex 對新增或有變動的 hook 要求先審核；沒核准的 hook 會被
+直接略過，而且**沒有任何警告**，看起來就像 devlog 沒在記錄。這跟專案有沒有設成
+`trust_level = "trusted"` 是兩回事，專案信任不會讓 hook 生效。
+
+- 互動模式：第一次開啟時 Codex 會提示有 hook 需要審核，核准後才會執行。之後 hook 的設定
+  有變動（例如重跑 `init` 讓路徑或指令改變）也可能要再核准一次。
+- 非互動的 `codex exec`（CI、腳本）：未審核的 hook 會被靜默略過。`--dangerously-bypass-hook-trust`
+  可以讓它們跑起來，但那個旗標會略過所有 hook 的信任檢查，只適合已經自己確認過 hook 來源的
+  自動化環境。
+- 想確認有沒有生效：`start` 之後送一則訊息，看 `.devlog/.round-current.md` 有沒有出現這一輪的
+  User Input skeleton；沒有就代表 hook 沒被執行。
+
 Codex 目前沒有對應「使用者中斷」（Claude Code 的 `PostToolUseFailure`／
 `is_interrupt`）與「這輪異常結束」（`StopFailure`）的事件，這兩種細節狀態在
 Codex 上不會被標記成 `INTERRUPTED`；核心強制記錄機制（`Stop` 事件擋住未寫完的

package/cli/agents-md.js

@@ -0,0 +1,51 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const BEGIN = '<!-- devlog-tracker:begin -->';
+const END = '<!-- devlog-tracker:end -->';
+
+const BLOCK = `${BEGIN}
+## devlog-tracker
+
+這個專案用 devlog-tracker 在 \`.devlog/devlog.md\` 維護逐輪紀錄（Claude Code 與 Codex 共用同一份）。Codex 沒有 \`/devlog-tracker:*\` slash 指令，請照下面對照做：
+
+1. 先 \`source .devlog-tracker/env.sh\`（設定 \`DEVLOG_TRACKER_ROOT\`）。
+2. 依使用者意圖讀對應的 \`.devlog-tracker/commands/<名稱>.md\`，照裡面的步驟做（腳本在 \`.devlog-tracker/hooks/scripts/\`，執行時 \`CLAUDE_PROJECT_DIR\` 設成專案根目錄）。
+
+| 使用者說 | 讀這份 |
+|---|---|
+| 開始追蹤 / start | \`commands/start.md\` |
+| 暫停 / pause | \`commands/pause.md\` |
+| 狀態 / status | \`commands/status.md\` |
+| 接續上一題 / continue（換過工具或 \`/clear\` 之後） | \`commands/continue.md\` |
+| 歸檔 / compact | \`commands/compact.md\` |
+| 清空重編 / clean（不可復原，先問使用者確認） | \`commands/clean.md\` |
+| 保存主題 / keep、接續具名檔 / resume、跨主題總覽 / overview | \`commands/keep.md\`、\`commands/resume.md\`、\`commands/overview.md\` |
+| 長任務定期記錄 / span | \`commands/span.md\` |
+| 調整沉默門檻 / checkpoint、segment-watch | \`commands/checkpoint.md\`、\`commands/segment-watch.md\` |
+| 開發歷程教訓 / lessons、lessons-on、lessons-off、lessons-drift | \`commands/lessons.md\`、\`commands/lessons-on.md\`、\`commands/lessons-off.md\`、\`commands/lessons-drift.md\` |
+
+寫 devlog 的格式與規則見 \`.devlog-tracker/skills/devlog-tracker/SKILL.md\`。每輪結束前必須把當輪寫進 \`.devlog/\`；已 \`start\` 的專案，Stop hook 會擋沒寫完的輪次。
+${END}
+`;
+
+function upsertAgentsMd(targetDir) {
+  const filePath = path.join(targetDir, 'AGENTS.md');
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const begin = existing.indexOf(BEGIN);
+  const end = existing.indexOf(END);
+
+  let next;
+  if (begin !== -1 && end > begin) {
+    next = existing.slice(0, begin) + BLOCK + existing.slice(end + END.length).replace(/^\n/, '');
+  } else if (existing.trim() === '') {
+    next = BLOCK;
+  } else {
+    next = `${existing.replace(/\n*$/, '\n')}\n${BLOCK}`;
+  }
+  if (next !== existing) fs.writeFileSync(filePath, next);
+  return filePath;
+}
+
+module.exports = { upsertAgentsMd, BEGIN, END };

package/cli/agents-md.test.js

@@ -0,0 +1,60 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { upsertAgentsMd, BEGIN, END } = require('./agents-md');
+const { run } = require('./init');
+
+function tmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'devlog-tracker-agents-'));
+}
+
+test('creates AGENTS.md when missing', () => {
+  const dir = tmp();
+  const file = upsertAgentsMd(dir);
+  const text = fs.readFileSync(file, 'utf8');
+  assert.ok(text.startsWith(BEGIN));
+  assert.ok(text.includes('.devlog-tracker/commands/'));
+  assert.ok(text.trimEnd().endsWith(END));
+});
+
+test('appends after existing content without touching it', () => {
+  const dir = tmp();
+  fs.writeFileSync(path.join(dir, 'AGENTS.md'), '# My rules\n\nBe nice.\n');
+  const text = fs.readFileSync(upsertAgentsMd(dir), 'utf8');
+  assert.ok(text.startsWith('# My rules\n\nBe nice.\n\n'));
+  assert.ok(text.includes(BEGIN));
+});
+
+test('is idempotent and replaces the block in place', () => {
+  const dir = tmp();
+  fs.writeFileSync(path.join(dir, 'AGENTS.md'), `before\n${BEGIN}\nold stale text\n${END}\nafter\n`);
+  const once = fs.readFileSync(upsertAgentsMd(dir), 'utf8');
+  const twice = fs.readFileSync(upsertAgentsMd(dir), 'utf8');
+  assert.equal(once, twice);
+  assert.ok(!once.includes('old stale text'));
+  assert.ok(once.startsWith('before\n'));
+  assert.ok(once.endsWith('after\n'));
+  assert.equal(once.split(BEGIN).length, 2);
+});
+
+test('block mentions every command doc so Codex has an entry for each', () => {
+  const commandsDir = path.join(__dirname, '..', 'commands');
+  const text = fs.readFileSync(upsertAgentsMd(tmp()), 'utf8');
+  for (const file of fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md'))) {
+    assert.ok(text.includes(`commands/${file}`), `AGENTS.md block is missing commands/${file}`);
+  }
+});
+
+test('init --codex writes AGENTS.md; --cursor alone does not', async () => {
+  const repoRoot = path.join(__dirname, '..');
+  const withCodex = tmp();
+  await run(['--codex'], { repoRoot, targetDir: withCodex, version: '0.0.0' });
+  assert.ok(fs.existsSync(path.join(withCodex, 'AGENTS.md')));
+
+  const cursorOnly = tmp();
+  await run(['--cursor'], { repoRoot, targetDir: cursorOnly, version: '0.0.0' });
+  assert.ok(!fs.existsSync(path.join(cursorOnly, 'AGENTS.md')));
+});

package/cli/platforms/codex.js

@@ -1,6 +1,7 @@
 'use strict';
 const path = require('path');
 const { mergeHooksTemplate } = require('../merge-hooks');
+const { upsertAgentsMd } = require('../agents-md');
 
 function install({ repoRoot, targetDir, vendorRoot }) {
   mergeHooksTemplate({
@@ -8,6 +9,7 @@ function install({ repoRoot, targetDir, vendorRoot }) {
     targetPath: path.join(targetDir, '.codex', 'hooks.json'),
     vendorRoot,
   });
+  upsertAgentsMd(targetDir);
 }
 
 module.exports = { install };

package/hooks/scripts/json-field.sh

@@ -66,8 +66,28 @@ json_str_field() {
     echo
     return 0
   fi
-  raw="$(printf '%s' "$json" | grep -o "\"${key}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" 2>/dev/null | head -1 || echo '')"
-  printf '%s' "$raw" | sed -E "s/^.*\"${key}\"[[:space:]]*:[[:space:]]*\"//; s/\"$//"
+  # 值要吃得下 \" 這類跳脫序列，否則含引號的 prompt 會在第一個 \" 被截斷；
+  # 抓出來之後再還原 \n \t \r \" \\ \/（\uXXXX 不處理，原樣保留）。
+  local pat='"'"${key}"'"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"'
+  raw="$(printf '%s' "$json" | grep -oE "$pat" 2>/dev/null | head -1 || echo '')"
+  printf '%s' "$raw" | sed -E "s/^\"${key}\"[[:space:]]*:[[:space:]]*\"//; s/\"$//" | awk '
+    BEGIN { ORS = "" }
+    {
+      s = $0; out = ""
+      while (length(s) > 0) {
+        c = substr(s, 1, 1)
+        if (c == "\\" && length(s) > 1) {
+          n = substr(s, 2, 1)
+          if (n == "n") out = out "\n"
+          else if (n == "t") out = out "\t"
+          else if (n == "r") out = out "\r"
+          else if (n == "u") out = out "\\u"
+          else out = out n
+          s = substr(s, 3)
+        } else { out = out c; s = substr(s, 2) }
+      }
+      print out
+    }'
   echo
 }
 

package/hooks/scripts/tests/test-json-field.sh

@@ -49,6 +49,23 @@ assert_eq "str field null" "" "$(json_str_field "$INPUT" reason)"
 INPUT='not json'
 assert_eq "str field malformed" "" "$(json_str_field "$INPUT" reason)"
 
+# Escaped characters must survive with and without jq (the no-jq path is a
+# grep/awk fallback). NOJQ_BIN is a PATH holding only the tools the fallback
+# needs, so `command -v jq` fails inside it.
+NOJQ_BIN="$(mktemp -d)"
+trap 'rm -f "$TMP"; rm -rf "$NOJQ_BIN"' EXIT
+for b in grep sed awk head tr cat; do
+  for d in /usr/bin /bin; do [ -x "$d/$b" ] && { ln -s "$d/$b" "$NOJQ_BIN/$b"; break; }; done
+done
+INPUT='{"session_id":"s","prompt":"say \"hi\" \\ back\/slash\ttab 你好","after":"ok"}'
+EXPECT_PROMPT="$(printf 'say "hi" \\ back/slash\ttab 你好')"
+for mode in jq nojq; do
+  if [ "$mode" = nojq ]; then P="$NOJQ_BIN"; else P="$PATH"; fi
+  [ "$mode" = jq ] && ! command -v jq >/dev/null 2>&1 && continue
+  assert_eq "[$mode] escaped quote/backslash/tab prompt" "$EXPECT_PROMPT" "$(PATH="$P" json_str_field "$INPUT" prompt)"
+  assert_eq "[$mode] field after escaped one" "ok" "$(PATH="$P" json_str_field "$INPUT" after)"
+done
+
 assert_eq "slugify basic" "foo-bar" "$(slugify 'foo bar')"
 assert_eq "slugify collapses runs" "foo-bar" "$(slugify 'foo   bar')"
 assert_eq "slugify trims edges" "foo" "$(slugify ' foo ')"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlog-tracker",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "npx installer for the devlog-tracker Claude Code plugin's Cursor and Codex adapters.",
   "bin": {
     "devlog-tracker": "bin/devlog-tracker.js"