oh-langfuse 0.1.31 → 0.1.32

package/README.md

@@ -2,7 +2,7 @@
 
 `oh-langfuse` 是用于给 Claude Code、OpenCode 和 Codex 配置 Langfuse 追踪的命令行工具。它提供交互式安装向导，也支持 `setup` / `check` 直接命令，方便在用户机器上安装、修复和校验配置。
 
-当前 npm 版本：`0.1.25`
+当前 npm 版本：`0.1.32`
 
 ## 能做什么
 
@@ -34,6 +34,23 @@ npx oh-langfuse@latest check opencode
 npx oh-langfuse@latest check codex
 ```
 
+## 自动更新
+
+安装或更新 runtime 后，工具会在 `~/.config/oh-langfuse/runtime.json` 记录 Claude Code / OpenCode / Codex 当前写入本机 runtime 的 `oh-langfuse` 版本。
+
+OpenCode 生成的 `launch-opencode-langfuse.*` 会在启动 agent 前执行一次更新检测：如果 npm 上的 `oh-langfuse@latest` 高于本机 runtime 版本，会提示是否更新；用户确认后才会运行 `npx oh-langfuse@latest update opencode`。Claude Code 和 Codex 也会生成对应 launcher：
+
+- `~/.claude/launch-claude-langfuse.cmd` / `~/.claude/launch-claude-langfuse.sh`
+- `~/.codex/launch-codex-langfuse.cmd` / `~/.codex/launch-codex-langfuse.sh`
+
+如果直接运行系统原始的 `claude` / `codex` 命令，工具不会强行替换该命令；需要使用上述 launcher 才能做到启动前检测并提示更新。也可以手动运行：
+
+```bash
+npx oh-langfuse@latest auto-update opencode
+npx oh-langfuse@latest auto-update claude
+npx oh-langfuse@latest auto-update codex
+```
+
 本地开发运行：
 
 ```bash

package/bin/cli.js

@@ -796,7 +796,8 @@ function printHelp() {
     "oh-langfuse update all",
     "oh-langfuse update claude",
     "oh-langfuse update opencode",
-    "oh-langfuse update codex"
+    "oh-langfuse update codex",
+    "oh-langfuse auto-update opencode"
   ]);
   renderSection("Options", [
     `${paint("--dry-run", t.gold)}  Preview actions without writing files or installing packages.`,
@@ -856,6 +857,15 @@ async function main() {
       ];
       return runNodeScript("update-langfuse-runtime.mjs", updateArgs, options);
     }
+    if (cmd === "auto-update") {
+      return runNodeScript("auto-update-runtime.mjs", [
+        target || "all",
+        ...(hasValue(options.npmRegistry) ? [`--npmRegistry=${options.npmRegistry}`] : []),
+        ...(hasValue(options.pipIndexUrl) ? [`--pipIndexUrl=${options.pipIndexUrl}`] : []),
+        ...(options.skipCheck ? ["--skip-check"] : []),
+        ...(options.yes ? ["--yes"] : []),
+      ], options);
+    }
     if (cmd === "check" && target === "claude") return checkClaude(options);
     if (cmd === "check" && target === "opencode") return checkOpenCode(options);
     if (cmd === "check" && target === "codex") return checkCodex(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-langfuse",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "private": false,
   "type": "module",
   "description": "Use npm scripts to configure Claude Code / OpenCode / Codex with Langfuse tracing.",
@@ -12,7 +12,8 @@
     "code-tool-langfuse": "bin/cli.js"
   },
   "files": [
-    "bin",
+    "bin",
+    "scripts/auto-update-runtime.mjs",
     "scripts/codex-langfuse-check.mjs",
     "scripts/codex-langfuse-setup.mjs",
     "scripts/json-utils.mjs",
@@ -25,6 +26,7 @@
     "scripts/real-self-verify.mjs",
     "scripts/log-filter-utils.mjs",
     "scripts/metrics-utils.mjs",
+    "scripts/runtime-state-utils.mjs",
     "scripts/update-langfuse-runtime.mjs",
     "scripts/update-utils.mjs",
     "langfuse_hook.py",

package/scripts/auto-update-runtime.mjs

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { extractVersionFromNpmMetadata, isNewerVersion } from "./update-utils.mjs";
+import { getRuntimeInstallRecord } from "./runtime-state-utils.mjs";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
+const ALLOWED_TARGETS = new Set(["claude", "opencode", "codex"]);
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (const raw of argv) {
+    if (!raw.startsWith("--")) {
+      args._.push(raw);
+      continue;
+    }
+    const eq = raw.indexOf("=");
+    if (eq === -1) args[raw.slice(2)] = true;
+    else args[raw.slice(2, eq)] = raw.slice(eq + 1);
+  }
+  return args;
+}
+
+async function latestVersion(registry = "https://registry.npmjs.org") {
+  const base = registry.replace(/\/+$/, "");
+  const response = await fetch(`${base}/oh-langfuse`, { headers: { accept: "application/json" } });
+  if (!response.ok) throw new Error(`npm registry ${response.status} ${response.statusText}`);
+  return extractVersionFromNpmMetadata(await response.json());
+}
+
+function question(text) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(text, (answer) => {
+      rl.close();
+      resolve(String(answer || "").trim());
+    });
+  });
+}
+
+function npxCommand() {
+  return process.platform === "win32" ? "npx.cmd" : "npx";
+}
+
+function runUpdate(target, args) {
+  const updateArgs = ["-y", "oh-langfuse@latest", "update", target];
+  if (args["skip-check"]) updateArgs.push("--skip-check");
+  if (args.npmRegistry) updateArgs.push(`--npmRegistry=${args.npmRegistry}`);
+  if (args.pipIndexUrl) updateArgs.push(`--pipIndexUrl=${args.pipIndexUrl}`);
+  const command = npxCommand();
+  const result = spawnSync(command, updateArgs, {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    windowsHide: true,
+    timeout: 900000,
+  });
+  return result.status ?? (result.error ? 1 : 0);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (/^(0|false|no|off)$/i.test(String(process.env.OH_LANGFUSE_AUTO_UPDATE || ""))) return 0;
+
+  const target = String(args._[0] || "").trim().toLowerCase();
+  if (!ALLOWED_TARGETS.has(target)) {
+    throw new Error("Usage: oh-langfuse auto-update <claude|opencode|codex>");
+  }
+
+  let latest;
+  try {
+    latest = await latestVersion(args.npmRegistry);
+  } catch (error) {
+    if (args.verbose) console.log(`[INFO] oh-langfuse update check skipped: ${error.message}`);
+    return 0;
+  }
+
+  const record = getRuntimeInstallRecord(target);
+  const installedVersion = record?.packageVersion || record?.version || "";
+  const needsUpdate = installedVersion ? isNewerVersion(latest, installedVersion) : isNewerVersion(latest, packageJson.version);
+  if (!needsUpdate && installedVersion) return 0;
+  if (!needsUpdate && !installedVersion) return 0;
+
+  const message = installedVersion
+    ? `oh-langfuse ${target} runtime update available: ${installedVersion} -> ${latest}.`
+    : `oh-langfuse ${target} runtime may need update. Latest package: ${latest}.`;
+
+  if (args.yes || args.y) {
+    console.log(`[INFO] ${message}`);
+    const code = runUpdate(target, args);
+    return args.strict ? code : 0;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log(`[INFO] ${message} Run: npx oh-langfuse@latest update ${target}`);
+    return 0;
+  }
+
+  const answer = await question(`${message}\nUpdate now? (y/N) `);
+  if (!/^(y|yes)$/i.test(answer)) return 0;
+  const code = runUpdate(target, args);
+  return args.strict ? code : 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((error) => {
+    console.error(`[WARN] oh-langfuse auto-update skipped: ${error?.message || String(error)}`);
+    process.exit(0);
+  });

package/scripts/codex-langfuse-setup.mjs

@@ -1,9 +1,10 @@
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
+import os from "node:os";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
 
 const USER_ID_PATTERN = /^[a-z](?:\d{8}|wx\d{7})$/;
 const USER_ID_PATTERN_TEXT = "^[a-z](?:\\d{8}|wx\\d{7})$";
@@ -57,11 +58,46 @@ function tomlArray(items) {
   return `[${items.map(tomlString).join(", ")}]`;
 }
 
-function pythonExecutableInVenv(venvDir) {
-  return process.platform === "win32"
-    ? path.join(venvDir, "Scripts", "python.exe")
-    : path.join(venvDir, "bin", "python");
-}
+function pythonExecutableInVenv(venvDir) {
+  return process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python");
+}
+
+function shQuote(s) {
+  return `'${String(s).replace(/'/g, "'\"'\"'")}'`;
+}
+
+function createAgentLauncher({ baseDir, target, executable }) {
+  if (process.platform === "win32") {
+    const launcher = path.join(baseDir, `launch-${target}-langfuse.cmd`);
+    const content = [
+      "@echo off",
+      "where npx >nul 2>nul",
+      "if %ERRORLEVEL% EQU 0 (",
+      `  call npx -y oh-langfuse@latest auto-update ${target} --skip-check`,
+      ")",
+      `${executable} %*`,
+      ""
+    ].join(os.EOL);
+    fs.writeFileSync(launcher, content, "utf8");
+    return launcher;
+  }
+
+  const launcher = path.join(baseDir, `launch-${target}-langfuse.sh`);
+  const content = [
+    "#!/usr/bin/env sh",
+    "set -eu",
+    "if command -v npx >/dev/null 2>&1; then",
+    `  npx -y oh-langfuse@latest auto-update ${target} --skip-check || true`,
+    "fi",
+    `exec ${shQuote(executable)} "$@"`,
+    ""
+  ].join("\n");
+  fs.writeFileSync(launcher, content, "utf8");
+  fs.chmodSync(launcher, 0o755);
+  return launcher;
+}
 
 function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.tsinghua.edu.cn/simple" }) {
   const venvDir = path.join(baseDir, "langfuse-venv");
@@ -134,9 +170,10 @@ function updateCodexNotify(configPath, notifyCommand) {
   fs.writeFileSync(configPath, next.join(os.EOL), "utf8");
 }
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
 
   const publicKey =
     args.publicKey || process.env.LANGFUSE_PUBLIC_KEY || "pk-lf-da0c90a7-6e93-4eb7-bb86-c1047c8d187d";
@@ -188,14 +225,21 @@ async function main() {
   const notifyPython = args["skip-pip-install"]
     ? pythonCmd
     : createOrUpdateLangfuseVenv({ baseDir: codexHome, pipIndexUrl });
-  updateCodexNotify(configPath, [notifyPython, destHook]);
-
-  console.log(`Updated Codex notify hook: ${configPath}`);
-  console.log(`Installed hook script: ${destHook}`);
-  console.log(`Wrote Langfuse config: ${path.join(langfuseDir, "config.json")}`);
-
-  console.log("Done. Restart Codex so the updated notify command is loaded.");
-}
+  updateCodexNotify(configPath, [notifyPython, destHook]);
+  const agentLauncher = createAgentLauncher({ baseDir: codexHome, target: "codex", executable: "codex" });
+
+  console.log(`Updated Codex notify hook: ${configPath}`);
+  console.log(`Installed hook script: ${destHook}`);
+  console.log(`Wrote Langfuse config: ${path.join(langfuseDir, "config.json")}`);
+  console.log(`Agent launcher with update check: ${agentLauncher}`);
+  const runtimeState = writeRuntimeInstallRecord("codex", {
+    packageName: packageJson.name,
+    packageVersion: packageJson.version,
+  });
+  console.log(`Runtime version recorded: ${runtimeState}`);
+
+  console.log("Done. Restart Codex so the updated notify command is loaded.");
+}
 
 main().catch((err) => {
   console.error(err?.message || String(err));

package/scripts/langfuse-setup.mjs

@@ -4,8 +4,10 @@ import path from "node:path";
 import os from "node:os";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
 
 const USER_ID_PATTERN = /^[a-z](?:\d{8}|wx\d{7})$/;
 const USER_ID_PATTERN_TEXT = "^[a-z](?:\\d{8}|wx\\d{7})$";
@@ -147,6 +149,37 @@ function shQuote(s) {
   return `'${String(s).replace(/'/g, "'\\''")}'`;
 }
 
+function createAgentLauncher({ baseDir, target, executable }) {
+  if (process.platform === "win32") {
+    const launcher = path.join(baseDir, `launch-${target}-langfuse.cmd`);
+    const content = [
+      "@echo off",
+      "where npx >nul 2>nul",
+      "if %ERRORLEVEL% EQU 0 (",
+      `  call npx -y oh-langfuse@latest auto-update ${target} --skip-check`,
+      ")",
+      `${executable} %*`,
+      ""
+    ].join(os.EOL);
+    fs.writeFileSync(launcher, content, "utf8");
+    return launcher;
+  }
+
+  const launcher = path.join(baseDir, `launch-${target}-langfuse.sh`);
+  const content = [
+    "#!/usr/bin/env sh",
+    "set -eu",
+    "if command -v npx >/dev/null 2>&1; then",
+    `  npx -y oh-langfuse@latest auto-update ${target} --skip-check || true`,
+    "fi",
+    `exec ${shQuote(executable)} "$@"`,
+    ""
+  ].join("\n");
+  fs.writeFileSync(launcher, content, "utf8");
+  fs.chmodSync(launcher, 0o755);
+  return launcher;
+}
+
 function pythonExecutableInVenv(venvDir) {
   return process.platform === "win32"
     ? path.join(venvDir, "Scripts", "python.exe")
@@ -288,6 +321,7 @@ async function main() {
   }
   const hookPython = createOrUpdateLangfuseVenv({ baseDir: claudeDir, pipIndexUrl });
   const hookLauncher = await createHookLauncher({ hooksDir, hookPython, pyPath });
+  const agentLauncher = createAgentLauncher({ baseDir: claudeDir, target: "claude", executable: "claude" });
 
   // 4) 合并写入 settings.json
   const settingsPath = path.join(claudeDir, "settings.json");
@@ -322,10 +356,16 @@ async function main() {
 
   const merged = deepMerge(existing, desired);
   ensureDir(claudeDir);
-  writeJsonPretty(settingsPath, merged);
-  console.log(`已更新：${settingsPath}`);
-
-}
+  writeJsonPretty(settingsPath, merged);
+  const runtimeState = writeRuntimeInstallRecord("claude", {
+    packageName: packageJson.name,
+    packageVersion: packageJson.version,
+  });
+  console.log(`Runtime version recorded: ${runtimeState}`);
+  console.log(`已更新：${settingsPath}`);
+  console.log(`Agent launcher with update check: ${agentLauncher}`);
+
+}
 
 main().catch((err) => {
   console.error(err?.message || String(err));

package/scripts/opencode-langfuse-setup.mjs

@@ -1,12 +1,16 @@
-import fs from "node:fs";
+import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { parseJsonRelaxed, stripBom } from "./json-utils.mjs";
 import { shouldSuppressAgentLogLine } from "./log-filter-utils.mjs";
+import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
 
 const USER_ID_PATTERN = /^[a-z](?:\d{8}|wx\d{7})$/;
 const USER_ID_PATTERN_TEXT = "^[a-z](?:\\d{8}|wx\\d{7})$";
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
 
 function normalizeUserId(v) {
   return String(v || "").trim();
@@ -560,11 +564,15 @@ function writeWindowsLauncherCmd(opencodeDir, { publicKey, secretKey, baseUrl, u
   if (process.platform !== "win32") return null;
   const p = path.join(opencodeDir, "launch-opencode-langfuse.cmd");
   const cmd = ["@echo off", "REM Auto-generated by scripts/opencode-langfuse-setup.mjs"];
-  cmd.push(`set LANGFUSE_PUBLIC_KEY=${publicKey}`);
-  cmd.push(`set LANGFUSE_SECRET_KEY=${secretKey}`);
-  cmd.push(`set LANGFUSE_BASEURL=${baseUrl}`);
-  if (userId) cmd.push(`set LANGFUSE_USER_ID=${userId}`);
-  cmd.push('if exist "%USERPROFILE%\\.opencode\\bin\\opencode.exe" (');
+  cmd.push(`set LANGFUSE_PUBLIC_KEY=${publicKey}`);
+  cmd.push(`set LANGFUSE_SECRET_KEY=${secretKey}`);
+  cmd.push(`set LANGFUSE_BASEURL=${baseUrl}`);
+  if (userId) cmd.push(`set LANGFUSE_USER_ID=${userId}`);
+  cmd.push("where npx >nul 2>nul");
+  cmd.push("if %ERRORLEVEL% EQU 0 (");
+  cmd.push("  call npx -y oh-langfuse@latest auto-update opencode --skip-check");
+  cmd.push(")");
+  cmd.push('if exist "%USERPROFILE%\\.opencode\\bin\\opencode.exe" (');
   cmd.push('  "%USERPROFILE%\\.opencode\\bin\\opencode.exe" %*');
   cmd.push("  exit /b %ERRORLEVEL%");
   cmd.push(")");
@@ -588,6 +596,9 @@ function writeUnixLauncherSh(opencodeDir, { publicKey, secretKey, baseUrl, userI
     `export LANGFUSE_SECRET_KEY=${shQuote(secretKey)}`,
     `export LANGFUSE_BASEURL=${shQuote(baseUrl)}`,
     userId ? `export LANGFUSE_USER_ID=${shQuote(userId)}` : null,
+    'if command -v npx >/dev/null 2>&1; then',
+    '  npx -y oh-langfuse@latest auto-update opencode --skip-check || true',
+    "fi",
     'if [ -x "$HOME/.opencode/bin/opencode" ]; then',
     '  exec "$HOME/.opencode/bin/opencode" "$@"',
     "fi",
@@ -906,6 +917,11 @@ async function main() {
   }
 
   console.log(paint("完成。", colors.green, colors.bold));
+  const runtimeState = writeRuntimeInstallRecord("opencode", {
+    packageName: packageJson.name,
+    packageVersion: packageJson.version,
+  });
+  console.log(`Runtime version recorded: ${runtimeState}`);
   printCommandHint("可运行以下命令校验：", "npx oh-langfuse@latest check opencode");
   if (process.platform !== "win32") {
     console.log("");

package/scripts/runtime-state-utils.mjs

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const STATE_VERSION = 1;
+
+export function runtimeStateDir(home = os.homedir()) {
+  return path.join(home, ".config", "oh-langfuse");
+}
+
+export function runtimeStatePath(home = os.homedir()) {
+  return path.join(runtimeStateDir(home), "runtime.json");
+}
+
+function stripBom(s) {
+  return typeof s === "string" && s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+
+export function readRuntimeState(home = os.homedir()) {
+  const p = runtimeStatePath(home);
+  try {
+    if (!fs.existsSync(p)) return { version: STATE_VERSION, targets: {} };
+    const text = stripBom(fs.readFileSync(p, "utf8"));
+    if (!text.trim()) return { version: STATE_VERSION, targets: {} };
+    const parsed = JSON.parse(text);
+    return {
+      version: parsed.version || STATE_VERSION,
+      targets: parsed.targets && typeof parsed.targets === "object" ? parsed.targets : {},
+    };
+  } catch {
+    return { version: STATE_VERSION, targets: {} };
+  }
+}
+
+export function getRuntimeInstallRecord(target, home = os.homedir()) {
+  return readRuntimeState(home).targets?.[target] || null;
+}
+
+export function writeRuntimeInstallRecord(target, record = {}, home = os.homedir()) {
+  const state = readRuntimeState(home);
+  const dir = runtimeStateDir(home);
+  fs.mkdirSync(dir, { recursive: true });
+  state.version = STATE_VERSION;
+  state.targets = state.targets || {};
+  state.targets[target] = {
+    ...state.targets[target],
+    ...record,
+    target,
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(runtimeStatePath(home), JSON.stringify(state, null, 2) + os.EOL, "utf8");
+  return runtimeStatePath(home);
+}

package/scripts/update-langfuse-runtime.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { extractVersionFromNpmMetadata, selectUpdateTargets } from "./update-utils.mjs";
+import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
 
 const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
@@ -166,6 +167,10 @@ async function main() {
     console.log(`[INFO] Updating ${target} runtime...`);
     const config = mergedConfig(target, args);
     runNodeScript(setupScript(target), setupArgs(target, config, args));
+    writeRuntimeInstallRecord(target, {
+      packageName: packageJson.name,
+      packageVersion: packageJson.version,
+    });
     if (!args["skip-check"]) {
       runNodeScript(checkScript(target), []);
     }

package/scripts/update-utils.mjs

@@ -8,6 +8,33 @@ export function extractVersionFromNpmMetadata(metadata) {
   return latest.trim();
 }
 
+function versionParts(version) {
+  return String(version || "")
+    .trim()
+    .replace(/^v/i, "")
+    .split("-")[0]
+    .split(".")
+    .map((part) => Number.parseInt(part, 10) || 0);
+}
+
+export function compareSemver(a, b) {
+  const left = versionParts(a);
+  const right = versionParts(b);
+  const length = Math.max(left.length, right.length, 3);
+  for (let i = 0; i < length; i += 1) {
+    const l = left[i] || 0;
+    const r = right[i] || 0;
+    if (l > r) return 1;
+    if (l < r) return -1;
+  }
+  return 0;
+}
+
+export function isNewerVersion(candidate, current) {
+  if (!candidate || !current) return false;
+  return compareSemver(candidate, current) > 0;
+}
+
 export function selectUpdateTargets(target = "all", installed = {}) {
   const normalized = String(target || "all").trim().toLowerCase();
   if (normalized === "all") {