devlog-tracker 0.22.0

package/cli/merge-hooks.test.js

@@ -0,0 +1,187 @@
+'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 { mergeHooksTemplate } = require('./merge-hooks');
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'devlog-tracker-merge-'));
+}
+
+test('creates the target file from the template when target is missing', () => {
+  const dir = tmpdir();
+  const templatePath = path.join(dir, 'template.json');
+  fs.writeFileSync(
+    templatePath,
+    JSON.stringify({
+      hooks: { Stop: [{ hooks: [{ type: 'command', command: 'bash "${DEVLOG_TRACKER_ROOT}/codex/hooks/on-stop.sh"' }] }] },
+    })
+  );
+  const targetPath = path.join(dir, '.codex', 'hooks.json');
+
+  mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' });
+
+  const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  assert.equal(written.hooks.Stop[0].hooks[0].command, 'bash "/proj/.devlog-tracker/codex/hooks/on-stop.sh"');
+});
+
+test('re-running replaces only its own entries, keeps unrelated hooks untouched', () => {
+  const dir = tmpdir();
+  const templatePath = path.join(dir, 'template.json');
+  fs.writeFileSync(
+    templatePath,
+    JSON.stringify({
+      hooks: { Stop: [{ hooks: [{ type: 'command', command: 'bash "${DEVLOG_TRACKER_ROOT}/codex/hooks/on-stop.sh"' }] }] },
+    })
+  );
+  const targetPath = path.join(dir, '.codex', 'hooks.json');
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(
+    targetPath,
+    JSON.stringify({
+      hooks: {
+        Stop: [
+          { hooks: [{ type: 'command', command: 'bash /some/other-tool/on-stop.sh' }] },
+          { hooks: [{ type: 'command', command: 'bash "/old/.devlog-tracker/codex/hooks/on-stop.sh"' }] },
+        ],
+      },
+    })
+  );
+
+  mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' });
+
+  const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  assert.equal(written.hooks.Stop.length, 2);
+  assert.equal(written.hooks.Stop[0].hooks[0].command, 'bash /some/other-tool/on-stop.sh');
+  assert.equal(written.hooks.Stop[1].hooks[0].command, 'bash "/proj/.devlog-tracker/codex/hooks/on-stop.sh"');
+});
+
+test('preserves top-level non-hooks keys such as version', () => {
+  const dir = tmpdir();
+  const templatePath = path.join(dir, 'template.json');
+  fs.writeFileSync(
+    templatePath,
+    JSON.stringify({
+      version: 1,
+      hooks: { stop: [{ command: 'bash "${DEVLOG_TRACKER_ROOT}/cursor/hooks/on-stop.sh"' }] },
+    })
+  );
+  const targetPath = path.join(dir, '.cursor', 'hooks.json');
+
+  mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' });
+
+  const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  assert.equal(written.version, 1);
+  assert.equal(written.hooks.stop[0].command, 'bash "/proj/.devlog-tracker/cursor/hooks/on-stop.sh"');
+});
+
+function writeTemplate(dir) {
+  const templatePath = path.join(dir, 'template.json');
+  fs.writeFileSync(
+    templatePath,
+    JSON.stringify({
+      hooks: { Stop: [{ hooks: [{ type: 'command', command: 'bash "${DEVLOG_TRACKER_ROOT}/codex/hooks/on-stop.sh"' }] }] },
+    })
+  );
+  return templatePath;
+}
+
+function setup(existingText) {
+  const dir = tmpdir();
+  const templatePath = writeTemplate(dir);
+  const targetPath = path.join(dir, '.codex', 'hooks.json');
+  if (existingText !== undefined) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, existingText);
+  }
+  return { templatePath, targetPath };
+}
+
+test('malformed existing JSON throws with the file path and re-run guidance', () => {
+  const { templatePath, targetPath } = setup('{ not json');
+  assert.throws(
+    () => mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' }),
+    (err) => {
+      assert.ok(err.message.startsWith(`Cannot parse existing ${targetPath}: `), err.message);
+      assert.ok(err.message.includes('Fix or move the file, then re-run `devlog-tracker init` (safe to re-run).'));
+      return true;
+    }
+  );
+  assert.equal(fs.readFileSync(targetPath, 'utf8'), '{ not json');
+});
+
+test('non-object top-level value throws naming the file path', () => {
+  for (const text of ['[]', '"str"', '42']) {
+    const { templatePath, targetPath } = setup(text);
+    assert.throws(
+      () => mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' }),
+      (err) => err.message.includes(targetPath),
+      text
+    );
+  }
+});
+
+test('non-object "hooks" value throws naming the file path', () => {
+  const { templatePath, targetPath } = setup('{"hooks": []}');
+  assert.throws(
+    () => mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' }),
+    (err) => err.message.includes(targetPath) && err.message.includes('hooks')
+  );
+});
+
+test('non-array event value throws naming the file path and event, without overwriting', () => {
+  const original = '{"hooks": {"Stop": {"oops": true}}}';
+  const { templatePath, targetPath } = setup(original);
+  assert.throws(
+    () => mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' }),
+    (err) => err.message.includes(targetPath) && err.message.includes('Stop')
+  );
+  assert.equal(fs.readFileSync(targetPath, 'utf8'), original);
+});
+
+test('empty, whitespace-only and null existing files are treated as empty', () => {
+  for (const text of ['', '  \n\t ', 'null']) {
+    const { templatePath, targetPath } = setup(text);
+    mergeHooksTemplate({ templatePath, targetPath, vendorRoot: '/proj/.devlog-tracker' });
+    const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+    assert.equal(written.hooks.Stop[0].hooks[0].command, 'bash "/proj/.devlog-tracker/codex/hooks/on-stop.sh"');
+  }
+});
+
+test('vendorRoot containing a double quote or backslash still yields valid JSON', () => {
+  const vendorRoot = '/tmp/we"ird\\dir/.devlog-tracker';
+  const { templatePath, targetPath } = setup();
+  mergeHooksTemplate({ templatePath, targetPath, vendorRoot });
+  const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  assert.equal(written.hooks.Stop[0].hooks[0].command, `bash "${vendorRoot}/codex/hooks/on-stop.sh"`);
+});
+
+test('real templates quote the vendor path so project paths with spaces work', () => {
+  const vendorRoot = '/tmp/my project/.devlog-tracker';
+  for (const name of ['cursor', 'codex']) {
+    const dir = tmpdir();
+    const targetPath = path.join(dir, 'hooks.json');
+    mergeHooksTemplate({
+      templatePath: path.join(__dirname, '..', name, 'hooks.json'),
+      targetPath,
+      vendorRoot,
+    });
+    const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+    const commands = [];
+    (function walk(v) {
+      if (Array.isArray(v)) v.forEach(walk);
+      else if (v && typeof v === 'object') {
+        for (const [k, val] of Object.entries(v)) {
+          if (k === 'command') commands.push(val);
+          else walk(val);
+        }
+      }
+    })(written.hooks);
+    assert.ok(commands.length >= 5, `${name} has commands`);
+    for (const c of commands) {
+      assert.ok(c.includes(`"${vendorRoot}/`), `${name}: unquoted command ${c}`);
+    }
+  }
+});

package/cli/platforms/codex.js

@@ -0,0 +1,13 @@
+'use strict';
+const path = require('path');
+const { mergeHooksTemplate } = require('../merge-hooks');
+
+function install({ repoRoot, targetDir, vendorRoot }) {
+  mergeHooksTemplate({
+    templatePath: path.join(repoRoot, 'codex', 'hooks.json'),
+    targetPath: path.join(targetDir, '.codex', 'hooks.json'),
+    vendorRoot,
+  });
+}
+
+module.exports = { install };

package/cli/platforms/cursor.js

@@ -0,0 +1,13 @@
+'use strict';
+const path = require('path');
+const { mergeHooksTemplate } = require('../merge-hooks');
+
+function install({ repoRoot, targetDir, vendorRoot }) {
+  mergeHooksTemplate({
+    templatePath: path.join(repoRoot, 'cursor', 'hooks.json'),
+    targetPath: path.join(targetDir, '.cursor', 'hooks.json'),
+    vendorRoot,
+  });
+}
+
+module.exports = { install };

package/cli/status.js

@@ -0,0 +1,14 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+function status({ targetDir, currentVersion }) {
+  const versionFile = path.join(targetDir, '.devlog-tracker', 'VERSION');
+  if (!fs.existsSync(versionFile)) {
+    return { installed: false, vendoredVersion: null, upToDate: false };
+  }
+  const vendoredVersion = fs.readFileSync(versionFile, 'utf8').trim();
+  return { installed: true, vendoredVersion, upToDate: vendoredVersion === currentVersion };
+}
+
+module.exports = { status };

package/cli/status.test.js

@@ -0,0 +1,33 @@
+'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 { status } = require('./status');
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'devlog-tracker-status-'));
+}
+
+test('reports not installed when .devlog-tracker/VERSION is missing', () => {
+  const targetDir = tmpdir();
+  const result = status({ targetDir, currentVersion: '0.21.0' });
+  assert.deepEqual(result, { installed: false, vendoredVersion: null, upToDate: false });
+});
+
+test('reports up to date when versions match', () => {
+  const targetDir = tmpdir();
+  fs.mkdirSync(path.join(targetDir, '.devlog-tracker'), { recursive: true });
+  fs.writeFileSync(path.join(targetDir, '.devlog-tracker', 'VERSION'), '0.21.0\n');
+  const result = status({ targetDir, currentVersion: '0.21.0' });
+  assert.deepEqual(result, { installed: true, vendoredVersion: '0.21.0', upToDate: true });
+});
+
+test('reports out of date when versions differ', () => {
+  const targetDir = tmpdir();
+  fs.mkdirSync(path.join(targetDir, '.devlog-tracker'), { recursive: true });
+  fs.writeFileSync(path.join(targetDir, '.devlog-tracker', 'VERSION'), '0.20.0\n');
+  const result = status({ targetDir, currentVersion: '0.21.0' });
+  assert.deepEqual(result, { installed: true, vendoredVersion: '0.20.0', upToDate: false });
+});

package/cli/vendor.js

@@ -0,0 +1,37 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const VENDOR_ENTRIES = ['hooks/scripts', 'codex/hooks', 'cursor/hooks', 'skills', 'commands'];
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function envShContent(vendorRoot) {
+  const escaped = vendorRoot.replace(/[\\"$`]/g, '\\$&');
+  return `export DEVLOG_TRACKER_ROOT="${escaped}"\n`;
+}
+
+function vendor({ repoRoot, targetDir, version }) {
+  const vendorRoot = path.join(targetDir, '.devlog-tracker');
+  for (const entry of VENDOR_ENTRIES) {
+    const src = path.join(repoRoot, entry);
+    if (!fs.existsSync(src)) continue;
+    copyRecursive(src, path.join(vendorRoot, entry));
+  }
+  fs.writeFileSync(path.join(vendorRoot, 'VERSION'), `${version}\n`);
+  fs.writeFileSync(path.join(vendorRoot, 'env.sh'), envShContent(vendorRoot));
+  return vendorRoot;
+}
+
+module.exports = { vendor, VENDOR_ENTRIES };

package/cli/vendor.test.js

@@ -0,0 +1,84 @@
+'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 { vendor } = require('./vendor');
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'devlog-tracker-vendor-'));
+}
+
+function makeFakeRepo(dir) {
+  fs.mkdirSync(path.join(dir, 'hooks', 'scripts'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'hooks', 'scripts', 'enforce-devlog.sh'), '#!/usr/bin/env bash\necho hi\n');
+  fs.mkdirSync(path.join(dir, 'codex', 'hooks'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'codex', 'hooks', 'on-stop.sh'), '#!/usr/bin/env bash\necho codex\n');
+  fs.mkdirSync(path.join(dir, 'cursor', 'hooks'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'cursor', 'hooks', 'on-stop.sh'), '#!/usr/bin/env bash\necho cursor\n');
+  fs.mkdirSync(path.join(dir, 'skills', 'devlog-tracker'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'skills', 'devlog-tracker', 'SKILL.md'), '# skill\n');
+  fs.mkdirSync(path.join(dir, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'commands', 'start.md'), '# start\n');
+}
+
+test('vendor copies the expected directories and stamps VERSION + env.sh', () => {
+  const repoRoot = tmpdir();
+  const targetDir = tmpdir();
+  makeFakeRepo(repoRoot);
+
+  const vendorRoot = vendor({ repoRoot, targetDir, version: '0.21.0' });
+
+  assert.equal(vendorRoot, path.join(targetDir, '.devlog-tracker'));
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'hooks', 'scripts', 'enforce-devlog.sh')));
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'codex', 'hooks', 'on-stop.sh')));
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'cursor', 'hooks', 'on-stop.sh')));
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'skills', 'devlog-tracker', 'SKILL.md')));
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'commands', 'start.md')));
+  assert.equal(fs.readFileSync(path.join(vendorRoot, 'VERSION'), 'utf8'), '0.21.0\n');
+  assert.equal(
+    fs.readFileSync(path.join(vendorRoot, 'env.sh'), 'utf8'),
+    `export DEVLOG_TRACKER_ROOT="${vendorRoot}"\n`
+  );
+});
+
+test('vendor preserves the ../../hooks/scripts relative layout codex/cursor wrappers rely on', () => {
+  const repoRoot = tmpdir();
+  const targetDir = tmpdir();
+  makeFakeRepo(repoRoot);
+
+  const vendorRoot = vendor({ repoRoot, targetDir, version: '0.21.0' });
+
+  const resolvedFromCodex = path.join(vendorRoot, 'codex', 'hooks', '..', '..', 'hooks', 'scripts', 'enforce-devlog.sh');
+  assert.ok(fs.existsSync(resolvedFromCodex));
+});
+
+test('re-running vendor overwrites rather than duplicating', () => {
+  const repoRoot = tmpdir();
+  const targetDir = tmpdir();
+  makeFakeRepo(repoRoot);
+
+  vendor({ repoRoot, targetDir, version: '0.21.0' });
+  fs.writeFileSync(path.join(repoRoot, 'commands', 'start.md'), '# start v2\n');
+  const vendorRoot = vendor({ repoRoot, targetDir, version: '0.22.0' });
+
+  assert.equal(fs.readFileSync(path.join(vendorRoot, 'commands', 'start.md'), 'utf8'), '# start v2\n');
+  assert.equal(fs.readFileSync(path.join(vendorRoot, 'VERSION'), 'utf8'), '0.22.0\n');
+});
+
+test('env.sh escapes shell metacharacters in the vendor path', () => {
+  const repoRoot = tmpdir();
+  const parent = tmpdir();
+  const targetDir = path.join(parent, 'a$(x)"b`c\\d');
+  fs.mkdirSync(targetDir);
+  makeFakeRepo(repoRoot);
+
+  const vendorRoot = vendor({ repoRoot, targetDir, version: '0.21.0' });
+
+  assert.equal(
+    fs.readFileSync(path.join(vendorRoot, 'env.sh'), 'utf8'),
+    `export DEVLOG_TRACKER_ROOT="${vendorRoot.replace(/[\\"$`]/g, '\\$&')}"\n`
+  );
+  assert.ok(fs.readFileSync(path.join(vendorRoot, 'env.sh'), 'utf8').includes('a\\$(x)\\"b\\`c\\\\d'));
+});

package/codex/hooks/on-pre-tool.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Codex PreToolUse wrapper. Codex's "command" hooks use the same exit-code
+# contract as Claude Code (0 = allow, 2 = block), so this only needs the
+# cwd->CLAUDE_PROJECT_DIR translation; segment-watch.sh's stderr message
+# propagates unchanged. Fail-open like the Cursor adapter: only an exit code of
+# exactly 2 blocks; anything else (including a missing hooks/scripts dir or a
+# crash) allows.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" 2>/dev/null && pwd)"
+[ -d "$PLUGIN_SCRIPTS" ] || exit 0
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export CLAUDE_PROJECT_DIR="$ROOT"
+printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/segment-watch.sh"
+RC=$?
+[ "$RC" -eq 2 ] && exit 2
+exit 0

package/codex/hooks/on-session-end.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Codex SessionEnd wrapper. on-session-end.sh (shared) reads a "reason"
+# field. Codex's own field for "why the session ended" is documented
+# inconsistently as either "why" or "reason" - try both, default to
+# "unknown" rather than guessing further, and rebuild a synthetic payload
+# so the shared script's json_str_field lookup always finds "reason".
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export CLAUDE_PROJECT_DIR="$ROOT"
+
+REASON=""
+if command -v jq >/dev/null 2>&1; then
+  REASON="$(printf '%s' "$INPUT" | jq -r '.why // .reason // empty' 2>/dev/null || true)"
+else
+  REASON="$(printf '%s' "$INPUT" | grep -o '"why"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"why"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  [ -n "$REASON" ] || REASON="$(printf '%s' "$INPUT" | grep -o '"reason"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"reason"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+fi
+[ -n "$REASON" ] || REASON="unknown"
+
+if command -v jq >/dev/null 2>&1; then
+  PAYLOAD="$(jq -n --arg r "$REASON" '{reason:$r}')"
+else
+  esc="$(printf '%s' "$REASON" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+  PAYLOAD="$(printf '{"reason":"%s"}' "$esc")"
+fi
+printf '%s' "$PAYLOAD" | bash "$PLUGIN_SCRIPTS/on-session-end.sh"
+exit 0

package/codex/hooks/on-session-start.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Codex SessionStart wrapper. Claude Code's own hooks.json calls
+# session-start-devlog.sh directly and its plain stdout becomes the injected
+# context — no JSON envelope. Codex hooks are documented to share the same
+# JSON-in shape as Claude Code, so we assume the same is true for stdout-out
+# here and skip any envelope too.
+#
+# One documented field-name gap: Codex's SessionStart payload may call the
+# "how did this session start" field `how` instead of Claude Code's `source`.
+# We try both and default to "startup" on purpose: session-start-devlog.sh
+# SKIPS the dangling-round heal when source is missing/unrecognized (same as
+# `compact`); the wrapper forces SRC="startup" so healing runs.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export CLAUDE_PROJECT_DIR="$ROOT"
+
+SRC=""
+if command -v jq >/dev/null 2>&1; then
+  SRC="$(printf '%s' "$INPUT" | jq -r '.how // .source // empty' 2>/dev/null || true)"
+else
+  SRC="$(printf '%s' "$INPUT" | grep -o '"how"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"how"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  [ -n "$SRC" ] || SRC="$(printf '%s' "$INPUT" | grep -o '"source"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"source"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+fi
+[ -n "$SRC" ] || SRC="startup"
+
+if command -v jq >/dev/null 2>&1; then
+  PAYLOAD="$(jq -n --arg s "$SRC" '{source:$s}')"
+else
+  esc="$(printf '%s' "$SRC" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+  PAYLOAD="$(printf '{"source":"%s"}' "$esc")"
+fi
+printf '%s' "$PAYLOAD" | bash "$PLUGIN_SCRIPTS/session-start-devlog.sh"
+exit 0

package/codex/hooks/on-stop.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Codex Stop wrapper. Same exit-code contract as PreToolUse; enforce-devlog.sh
+# reads "stop_hook_active", which is Claude Code's own standard field name
+# and not one of the documented Codex naming gaps, so it is forwarded as-is.
+# Fail-open like the Cursor adapter: only an exit code of exactly 2 blocks;
+# anything else (including a missing hooks/scripts dir or a crash) allows.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" 2>/dev/null && pwd)"
+[ -d "$PLUGIN_SCRIPTS" ] || exit 0
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export CLAUDE_PROJECT_DIR="$ROOT"
+printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/enforce-devlog.sh"
+RC=$?
+[ "$RC" -eq 2 ] && exit 2
+exit 0

package/codex/hooks/on-user-prompt-submit.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Codex UserPromptSubmit wrapper. round-start.sh is fail-open and side-effect
+# only (writes .devlog files); the one case where it prints anything to
+# stdout (workspace-mismatch notice) relies on the same plain-stdout-as-
+# context contract as SessionStart, so this is a straight pass-through of
+# the original payload after the cwd->CLAUDE_PROJECT_DIR translation.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export CLAUDE_PROJECT_DIR="$ROOT"
+printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/round-start.sh"
+exit 0

package/codex/hooks/project-dir.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Codex hook payloads carry the project directory in a "cwd" field (unlike
+# Cursor's workspace_roots[0] array). Same job as cursor/hooks/project-dir.sh,
+# different field name.
+set -uo pipefail
+INPUT="$(cat 2>/dev/null || true)"
+ROOT=""
+if command -v jq >/dev/null 2>&1; then
+  ROOT="$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)"
+else
+  ROOT="$(printf '%s' "$INPUT" | grep -o '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+fi
+printf '%s\n' "${ROOT:-.}"

package/codex/hooks/test-adapters.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAIL=0
+
+# project-dir reads cwd, not workspace_roots
+ROOT="$(printf '{"cwd":"%s"}' "$TMP" | bash "$SCRIPT_DIR/project-dir.sh")"
+if [ "$ROOT" = "$TMP" ]; then echo "PASS: project-dir reads cwd"; else echo "FAIL: project-dir [$ROOT]"; FAIL=1; fi
+
+# sessionStart: injects last Round's content as plain stdout
+mkdir -p "$TMP/project/.devlog"
+cat > "$TMP/project/.devlog/devlog.md" <<'EOF'
+## Round 1 — now
+
+### Summary
+done
+
+### Handoff
+#### 現況
+done
+
+### Status
+DONE
+EOF
+OUT="$(printf '{"cwd":"%s","how":"startup"}' "$TMP/project" | bash "$SCRIPT_DIR/on-session-start.sh")"
+case "$OUT" in *"Round 1"*) echo "PASS: sessionStart injects context" ;; *) echo "FAIL: sessionStart [$OUT]"; FAIL=1 ;; esac
+
+# userPromptSubmit: opens a Round in .round-current.md
+SUBMIT="$TMP/submit"
+mkdir -p "$SUBMIT/.devlog"
+touch "$SUBMIT/.devlog/.enabled"
+bash "$SCRIPT_DIR/on-user-prompt-submit.sh" <<EOF2 >/dev/null
+{"cwd":"$SUBMIT","prompt":"hello","session_id":"codex-1"}
+EOF2
+if grep -q 'hello' "$SUBMIT/.devlog/.round-current.md" 2>/dev/null; then
+  echo "PASS: userPromptSubmit writes round"
+else
+  echo "FAIL: userPromptSubmit round"; FAIL=1
+fi
+
+# preTool: blocks (exit 2) once the silence window has expired, allows fresh writes
+NOW="$(date +%s)"
+OLD=$((NOW - 1000))
+SUM="$(cksum < "$SUBMIT/.devlog/.round-current.md" | tr -d '\n')"
+printf '{"last_change_epoch": %s, "last_seen_cksum": "%s", "max_silent_seconds": 900, "session_id": "codex-1"}\n' "$OLD" "$SUM" > "$SUBMIT/.devlog/.segment-state"
+set +e
+printf '{"cwd":"%s","tool_name":"Bash","tool_input":{},"session_id":"codex-1"}' "$SUBMIT" | bash "$SCRIPT_DIR/on-pre-tool.sh" >/dev/null 2>/dev/null
+RC=$?
+set -e
+if [ "$RC" -eq 2 ]; then echo "PASS: expired tool blocked (exit 2)"; else echo "FAIL: preTool exit [$RC]"; FAIL=1; fi
+
+set +e
+printf '{"cwd":"%s","tool_name":"Write","tool_input":{"file_path":"%s/.devlog/.round-current.md"},"session_id":"codex-1"}' "$SUBMIT" "$SUBMIT" | bash "$SCRIPT_DIR/on-pre-tool.sh" >/dev/null 2>/dev/null
+RC=$?
+set -e
+if [ "$RC" -eq 0 ]; then echo "PASS: devlog write allowed (exit 0)"; else echo "FAIL: allowed-tool exit [$RC]"; FAIL=1; fi
+
+# stop: blocks (exit 2) while the round is unfinished
+printf '{"round": 1, "opened_at": "now"}\n' > "$SUBMIT/.devlog/.round-open"
+cksum < "$SUBMIT/.devlog/.round-current.md" > "$SUBMIT/.devlog/.turn-start"
+set +e
+printf '{"cwd":"%s"}' "$SUBMIT" | bash "$SCRIPT_DIR/on-stop.sh" >/dev/null 2>/dev/null
+RC=$?
+set -e
+if [ "$RC" -eq 2 ]; then echo "PASS: stop blocks unfinished round (exit 2)"; else echo "FAIL: stop exit [$RC]"; FAIL=1; fi
+
+# sessionEnd: closes the open round using "why" (not "reason")
+printf '\n## Round 2 — now\n\n### Status\nIN_PROGRESS\n' > "$SUBMIT/.devlog/.round-current.md"
+printf '{"round": 2, "opened_at": "now"}\n' > "$SUBMIT/.devlog/.round-open"
+cksum < "$SUBMIT/.devlog/.round-current.md" > "$SUBMIT/.devlog/.turn-start"
+printf '{"cwd":"%s","why":"windowClosed"}' "$SUBMIT" | bash "$SCRIPT_DIR/on-session-end.sh" >/dev/null
+if grep -q 'SessionEnd:windowClosed' "$SUBMIT/.devlog/devlog.md" 2>/dev/null; then
+  echo "PASS: sessionEnd closes round via 'why'"
+else
+  echo "FAIL: sessionEnd 'why' fallback"; FAIL=1
+fi
+
+# fail-open: when ../../hooks/scripts is missing, preTool/stop wrappers must allow (exit 0)
+ORPHAN="$TMP/orphan"
+mkdir -p "$ORPHAN/codex/hooks"
+cp "$SCRIPT_DIR/on-pre-tool.sh" "$SCRIPT_DIR/on-stop.sh" "$SCRIPT_DIR/project-dir.sh" "$ORPHAN/codex/hooks/"
+for W in on-pre-tool on-stop; do
+  set +e
+  printf '{"cwd":"%s"}' "$ORPHAN" | bash "$ORPHAN/codex/hooks/$W.sh" >/dev/null 2>/dev/null
+  RC=$?
+  set -e
+  if [ "$RC" -eq 0 ]; then echo "PASS: $W fails open without hooks/scripts (exit 0)"; else echo "FAIL: $W orphan exit [$RC]"; FAIL=1; fi
+done
+
+# sessionStart: payload with neither "how" nor "source" falls back to startup and still injects
+OUT="$(printf '{"cwd":"%s"}' "$TMP/project" | bash "$SCRIPT_DIR/on-session-start.sh")"
+case "$OUT" in *"Round 1"*) echo "PASS: sessionStart falls back to startup without how/source" ;; *) echo "FAIL: sessionStart no-source [$OUT]"; FAIL=1 ;; esac
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1
+fi