devlog-tracker 0.22.0 → 0.23.0

package/README.md

@@ -1,6 +1,6 @@
 # devlog-tracker
 
-**版本** 0.22.0
+**版本** 0.23.0
 
 在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
 
@@ -46,6 +46,11 @@ 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。
+
 `init` 會把這台機器專屬的絕對路徑寫進 `.codex/hooks.json`、`.cursor/hooks.json` 與
 `.devlog-tracker/env.sh`。如果你把這些檔案 commit 進 git，每位隊友都要在自己的機器上
 跑一次 `npx devlog-tracker init`（路徑每台機器不同）；或者改成把 `.devlog-tracker/` 與

package/cli/agents-md.js

@@ -0,0 +1,47 @@
+'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\` |
+| 接續上一題 / continue（換過工具或 \`/clear\` 之後） | \`commands/continue.md\` |
+| 暫停 / pause | \`commands/pause.md\` |
+| 狀態 / status | \`commands/status.md\` |
+| 歸檔 / compact | \`commands/compact.md\` |
+| 保存主題 / keep、接續具名檔 / resume | \`commands/keep.md\`、\`commands/resume.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,52 @@
+'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('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/package.json

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