@c0sc0s/codex-tags 0.5.0

package/runtime/src/controller.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+import { execFile, spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+import { CdpClient } from "./cdp-client.mjs";
+import { CodexProcess, findCodexApp } from "./codex-process.mjs";
+import { ControllerRouter } from "./controller-router.mjs";
+import { buildRuntimeMessageExpression, RUNTIME_BINDING, RUNTIME_VERSION } from "./inject-expression.mjs";
+import { isOwnedControllerCommand, parseControllerPid } from "./controller-state.mjs";
+import { createRuntimeMessage, RuntimeMessageType } from "./protocol.mjs";
+import { SessionSearchIndex } from "./search-index.mjs";
+import { SessionCatalog } from "./session-catalog.mjs";
+import { SettingsRepository } from "./settings-repository.mjs";
+import { RuntimeTargetRegistry } from "./runtime-target-registry.mjs";
+
+process.umask(0o077);
+
+const run = promisify(execFile);
+const configuredPort = Number(process.env.CODEX_TAGS_CDP_PORT ?? 9341);
+if (!Number.isSafeInteger(configuredPort) || configuredPort < 1024 || configuredPort > 65535) throw new Error("CODEX_TAGS_CDP_PORT must be an integer between 1024 and 65535");
+const PORT = configuredPort;
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const STATE_DIR = process.env.CODEX_TAGS_STATE_DIR ?? dirname(SCRIPT_PATH);
+const PID_PATH = join(STATE_DIR, "controller.pid");
+const LOG_PATH = join(STATE_DIR, "controller.log");
+const SEARCH_DATABASE_PATH = join(STATE_DIR, "search.sqlite");
+const SETTINGS_PATH = join(STATE_DIR, "settings.json");
+const INDEX_REFRESH_INTERVAL_MS = 30_000;
+const settingsRepository = new SettingsRepository(SETTINGS_PATH);
+const codexProcess = new CodexProcess({ port: PORT });
+const targetRegistry = new RuntimeTargetRegistry({
+  port: PORT,
+  ownsEndpoint: () => codexProcess.ownsCdpEndpoint(),
+  settingsRepository,
+});
+
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function apply() {
+  const { results } = await targetRegistry.ensureInjected(await settingsRepository.read());
+  return results;
+}
+
+async function readControllerPid() {
+  try {
+    return parseControllerPid(await readFile(PID_PATH, "utf8"));
+  } catch { return null; }
+}
+
+async function isOwnedController(pid) {
+  try {
+    const { stdout } = await run("/bin/ps", ["-p", String(pid), "-o", "command="]);
+    return isOwnedControllerCommand(stdout, SCRIPT_PATH);
+  } catch {
+    return false;
+  }
+}
+
+async function stopController() {
+  const pid = await readControllerPid();
+  if (pid !== null && await isOwnedController(pid)) {
+    try { process.kill(pid, "SIGTERM"); } catch {}
+    const deadline = Date.now() + 3000;
+    while (Date.now() < deadline && await isOwnedController(pid)) await wait(50);
+    if (await isOwnedController(pid)) throw new Error("The controller did not stop. No files were removed; retry after it exits.");
+  }
+  await rm(PID_PATH, { force: true });
+}
+
+async function spawnController() {
+  await stopController();
+  const output = openSync(LOG_PATH, "a");
+  const child = spawn(process.execPath, [SCRIPT_PATH, "watch"], {
+    detached: true,
+    stdio: ["ignore", output, output],
+  });
+  child.unref();
+  closeSync(output);
+}
+
+async function start() {
+  if (!findCodexApp()) throw new Error("Install the official Codex desktop app before activating Tags.");
+  await mkdir(STATE_DIR, { recursive: true });
+  await stopController();
+  if (!(await codexProcess.cdpIsReady(() => targetRegistry.discover()))) {
+    if (await codexProcess.ownsCdpEndpoint() || await codexProcess.hasCdpLaunchArguments()) {
+      await codexProcess.waitForCdp(() => targetRegistry.discover());
+    } else {
+      if (await codexProcess.portIsListening()) throw new Error(`端口 ${PORT} 已被其他进程占用；未退出或修改 Codex`);
+      await codexProcess.launchWithCdp(() => targetRegistry.discover());
+    }
+  }
+  const results = await apply();
+  await spawnController();
+  console.log(`Codex Sidebar Tags ${RUNTIME_VERSION} 已启用`, results);
+}
+
+async function hotApply() {
+  await mkdir(STATE_DIR, { recursive: true });
+  await stopController();
+  const results = await apply();
+  await spawnController();
+  return results;
+}
+
+async function watch() {
+  await mkdir(STATE_DIR, { recursive: true });
+  const nextPidPath = `${PID_PATH}.next-${process.pid}`;
+  await writeFile(nextPidPath, `${JSON.stringify({ pid: process.pid, scriptPath: SCRIPT_PATH, startedAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600 });
+  await rename(nextPidPath, PID_PATH);
+  console.log(`${new Date().toISOString()} watching ${RUNTIME_VERSION}`);
+  let misses = 0;
+  const searchIndex = new SessionSearchIndex(SEARCH_DATABASE_PATH);
+  const catalog = new SessionCatalog();
+  let catalogState = await catalog.read();
+  let catalogSignature = JSON.stringify(catalogState);
+  let nextCatalogRefreshAt = 0;
+  const runtimeClients = new Map();
+  let indexStatus = { phase: "indexing", completed: 0, total: 0, changed: 0 };
+  let indexRefresh = Promise.resolve();
+  let nextIndexRefreshAt = 0;
+  let settingsState = await settingsRepository.read();
+  if (settingsState.error) console.error(`${new Date().toISOString()} ${settingsState.error}`);
+  const syncTagSettings = async (target) => {
+    if (settingsState.exists || settingsState.error) return;
+    const definitions = await targetRegistry.evaluate(target, "window.__codexSidebarTags?.tagDefinitions?.() ?? null");
+    if (!Array.isArray(definitions)) return;
+    const result = await settingsRepository.write(definitions);
+    settingsState = { settings: result.settings, exists: true, error: null };
+  };
+  const scheduleIndexRefresh = () => {
+    indexRefresh = indexRefresh
+      .then(() => searchIndex.refresh((status) => { indexStatus = status; }))
+      .catch((error) => {
+        indexStatus = { phase: "error", message: error.message };
+        console.error(`${new Date().toISOString()} search indexing failed: ${error.message}`);
+      });
+    nextIndexRefreshAt = Date.now() + INDEX_REFRESH_INTERVAL_MS;
+  };
+  scheduleIndexRefresh();
+
+  const sendRuntimeMessage = (client, message, executionContextId) => client.evaluate(
+    buildRuntimeMessageExpression(message),
+    executionContextId,
+  );
+
+  const broadcastSettings = async (settings) => {
+    const message = createRuntimeMessage(RuntimeMessageType.settingsSnapshot, { settings });
+    await Promise.allSettled([...runtimeClients.values()].map((client) => sendRuntimeMessage(client, message)));
+  };
+
+  const router = new ControllerRouter({
+    searchIndex,
+    settingsRepository,
+    getSettings: () => settingsState.settings,
+    onSettingsChanged: async (settings) => {
+      settingsState = { settings, exists: true, error: null };
+      await broadcastSettings(settings);
+    },
+    waitForIndex: () => indexRefresh,
+    getIndexStatus: () => indexStatus,
+    send: sendRuntimeMessage,
+    openSession: async (threadId) => {
+      if (catalogState.items.some((item) => item.threadId === threadId)) await run("/usr/bin/open", [`codex://threads/${threadId}`]);
+    },
+  });
+
+  const ensureRuntimeClient = async (target) => {
+    const existing = runtimeClients.get(target.id);
+    if (existing?.connected) return existing;
+    existing?.close();
+    const client = await CdpClient.connect(target);
+    await client.addBinding(RUNTIME_BINDING, (params) => router.handle(client, params));
+    runtimeClients.set(target.id, client);
+    await router.sendSettingsSnapshot(client);
+    await sendRuntimeMessage(client, createRuntimeMessage(RuntimeMessageType.catalogSnapshot, catalogState));
+    return client;
+  };
+
+  let cleanupPromise = null;
+  const clean = () => {
+    cleanupPromise ??= (async () => {
+      for (const client of runtimeClients.values()) client.close();
+      runtimeClients.clear();
+      searchIndex.close();
+      if ((await readControllerPid()) === process.pid) await rm(PID_PATH, { force: true });
+    })();
+    return cleanupPromise;
+  };
+  process.once("SIGTERM", () => { clean().finally(() => process.exit(0)); });
+  process.once("SIGINT", () => { clean().finally(() => process.exit(0)); });
+
+  try {
+    while (true) {
+      try {
+        const { targets } = await targetRegistry.ensureInjected(settingsState);
+        const currentTargetIds = new Set(targets.map(({ id }) => id));
+        for (const [targetId, client] of runtimeClients) {
+          if (currentTargetIds.has(targetId)) continue;
+          client.close();
+          runtimeClients.delete(targetId);
+          router.forgetTarget(targetId);
+        }
+        for (const target of targets) {
+          await ensureRuntimeClient(target);
+          await syncTagSettings(target);
+        }
+        if (Date.now() >= nextIndexRefreshAt) scheduleIndexRefresh();
+        if (Date.now() >= nextCatalogRefreshAt) {
+          catalogState = await catalog.read();
+          const signature = JSON.stringify(catalogState);
+          if (signature !== catalogSignature) {
+            catalogSignature = signature;
+            await Promise.allSettled([...runtimeClients.values()].map((client) => sendRuntimeMessage(client, createRuntimeMessage(RuntimeMessageType.catalogSnapshot, catalogState))));
+          }
+          nextCatalogRefreshAt = Date.now() + 5000;
+        }
+        misses = 0;
+      } catch (error) {
+        misses += 1;
+        if (misses === 1 || misses % 10 === 0) console.error(`${new Date().toISOString()} sync failed (${misses}): ${error.message}`);
+        if (misses >= 10 && !(await codexProcess.isRunning())) return;
+      }
+      await wait(1000);
+    }
+  } finally {
+    await clean();
+  }
+}
+
+async function restore() {
+  await stopController();
+  if (await codexProcess.cdpIsReady(() => targetRegistry.discover())) await targetRegistry.removeInjection();
+  console.log("侧栏标题增强已移除；Codex 安装包没有被修改。");
+}
+
+async function purge() {
+  await stopController();
+  if (await codexProcess.cdpIsReady(() => targetRegistry.discover())) {
+    for (const target of await targetRegistry.discover()) {
+      await targetRegistry.evaluate(target, `
+        localStorage.removeItem("codex-sidebar-tags-config-v1");
+        localStorage.removeItem("codex-sidebar-tags-index-v1");
+      `);
+    }
+    await targetRegistry.removeInjection();
+  }
+  console.log("侧栏增强及其浏览器缓存已移除；Codex 会话没有被修改。");
+}
+
+async function status() {
+  const ready = await codexProcess.cdpIsReady(() => targetRegistry.discover());
+  const storedPid = await readControllerPid();
+  const controllerPid = storedPid !== null && await isOwnedController(storedPid) ? storedPid : null;
+  const codexRunning = await codexProcess.isRunning();
+  const activeVersions = [];
+  const activeWindows = [];
+  if (ready) {
+    for (const target of await targetRegistry.discover()) {
+      activeVersions.push(await targetRegistry.evaluate(target, "window.__codexSidebarTags?.version ?? null"));
+      activeWindows.push(await targetRegistry.evaluate(target, "window.__codexSidebarTags?.status?.() ?? null"));
+    }
+  }
+  let searchIndex = null;
+  try {
+    const index = new SessionSearchIndex(SEARCH_DATABASE_PATH, { readOnly: true });
+    searchIndex = index.status();
+    index.close();
+  } catch (error) {
+    searchIndex = { error: error.message };
+  }
+  const tagSettingsState = await settingsRepository.read();
+  const tagSettings = tagSettingsState.exists ? tagSettingsState.settings : null;
+  const catalogState = await new SessionCatalog().read();
+  const catalog = { complete: catalogState.complete, count: catalogState.items.length, error: catalogState.error };
+  console.log(JSON.stringify({ codexRunning, cdp: ready, controllerPid, sourceVersion: RUNTIME_VERSION, activeVersions, activeWindows, searchIndex, catalog, tagSettings, tagSettingsError: tagSettingsState.error }, null, 2));
+}
+
+const command = process.argv[2] ?? "start";
+if (command === "start") await start();
+else if (command === "apply") console.log(await hotApply());
+else if (command === "restore") await restore();
+else if (command === "purge") await purge();
+else if (command === "status") await status();
+else if (command === "watch") await watch();
+else throw new Error(`未知命令：${command}`);

package/runtime/src/inject-expression.mjs

@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { DEFAULT_TAG_DEFINITIONS, LEGACY_TONE_COLORS, TAG_COLOR_PRESETS } from "./tag-settings.mjs";
+import { createRuntimeMessage, RUNTIME_PROTOCOL_VERSION, RuntimeMessageType } from "./protocol.mjs";
+
+export const RUNTIME_VERSION = "6.0.12";
+export const RUNTIME_BINDING = "__codexTagsRequest";
+export const SEARCH_BINDING = RUNTIME_BINDING;
+
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+const bundleCandidates = [
+  join(moduleDirectory, "dist", "injected.js"),
+  join(moduleDirectory, "..", "dist", "injected.js"),
+];
+const bundlePath = bundleCandidates.find(existsSync);
+
+if (!bundlePath) {
+  throw new Error("Codex Tags runtime bundle is missing. Run `npm run build` before installing.");
+}
+
+const injectedBundle = readFileSync(bundlePath, "utf8");
+
+export function buildInjectionExpression(options = {}) {
+  const config = {
+    version: RUNTIME_VERSION,
+    protocolVersion: RUNTIME_PROTOCOL_VERSION,
+    tagDefinitions: options.tagDefinitions ?? DEFAULT_TAG_DEFINITIONS,
+    settingsSource: options.settingsSource ?? "defaults",
+    colorPresets: TAG_COLOR_PRESETS,
+    legacyToneColors: LEGACY_TONE_COLORS,
+    requestBinding: RUNTIME_BINDING,
+  };
+  return `(() => { ${injectedBundle}\nreturn CodexTagsInjected.installRuntime(${JSON.stringify(config)}); })()`;
+}
+
+export function buildRuntimeMessageExpression(message) {
+  return `window.__codexSidebarTags?.handleMessage?.(${JSON.stringify(message)}) ?? false`;
+}
+
+export function buildSearchResultExpression(result) {
+  const { type: _legacyType, requestId, ...payload } = result;
+  return buildRuntimeMessageExpression(createRuntimeMessage(RuntimeMessageType.searchResult, payload, requestId));
+}
+
+export function buildRemovalExpression() {
+  return "(() => { try { return window.__codexSidebarTags?.dispose?.() ?? false; } catch { return false; } })()";
+}

package/runtime/src/protocol.d.mts

@@ -0,0 +1,31 @@
+export const RUNTIME_PROTOCOL_VERSION: 1;
+
+export const RuntimeMessageType: Readonly<{
+  hello: "hello";
+  searchRequest: "search.request";
+  searchResult: "search.result";
+  settingsGet: "settings.get";
+  settingsSnapshot: "settings.snapshot";
+  settingsUpdate: "settings.update";
+  settingsError: "settings.error";
+  runtimeStatus: "runtime.status";
+  catalogSnapshot: "catalog.snapshot";
+  navigationOpen: "navigation.open";
+}>;
+
+export interface RuntimeMessage<TType extends string = string, TPayload extends Record<string, unknown> = Record<string, unknown>> {
+  protocolVersion: 1;
+  type: TType;
+  requestId?: number;
+  payload: TPayload;
+}
+
+export function createRuntimeMessage<TType extends string, TPayload extends Record<string, unknown>>(
+  type: TType,
+  payload?: TPayload,
+  requestId?: number,
+): RuntimeMessage<TType, TPayload>;
+
+export function parseRuntimeMessage(value: unknown):
+  | { ok: true; message: RuntimeMessage }
+  | { ok: false; reason: "invalid-json" | "invalid-envelope" | "unsupported-version" | "invalid-type" | "invalid-payload" | "invalid-request-id" };

package/runtime/src/protocol.mjs

@@ -0,0 +1,43 @@
+export const RUNTIME_PROTOCOL_VERSION = 1;
+
+export const RuntimeMessageType = Object.freeze({
+  hello: "hello",
+  searchRequest: "search.request",
+  searchResult: "search.result",
+  settingsGet: "settings.get",
+  settingsSnapshot: "settings.snapshot",
+  settingsUpdate: "settings.update",
+  settingsError: "settings.error",
+  runtimeStatus: "runtime.status",
+  catalogSnapshot: "catalog.snapshot",
+  navigationOpen: "navigation.open",
+});
+
+export function createRuntimeMessage(type, payload = {}, requestId) {
+  if (typeof type !== "string" || !type) throw new TypeError("Runtime message type must be a non-empty string");
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) throw new TypeError("Runtime message payload must be an object");
+  if (requestId !== undefined && !Number.isSafeInteger(requestId)) throw new TypeError("Runtime message requestId must be a safe integer");
+  return {
+    protocolVersion: RUNTIME_PROTOCOL_VERSION,
+    type,
+    ...(requestId === undefined ? {} : { requestId }),
+    payload,
+  };
+}
+
+export function parseRuntimeMessage(value) {
+  let candidate = value;
+  if (typeof candidate === "string") {
+    try {
+      candidate = JSON.parse(candidate);
+    } catch {
+      return { ok: false, reason: "invalid-json" };
+    }
+  }
+  if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) return { ok: false, reason: "invalid-envelope" };
+  if (candidate.protocolVersion !== RUNTIME_PROTOCOL_VERSION) return { ok: false, reason: "unsupported-version" };
+  if (typeof candidate.type !== "string" || !candidate.type) return { ok: false, reason: "invalid-type" };
+  if (candidate.payload === null || typeof candidate.payload !== "object" || Array.isArray(candidate.payload)) return { ok: false, reason: "invalid-payload" };
+  if (candidate.requestId !== undefined && !Number.isSafeInteger(candidate.requestId)) return { ok: false, reason: "invalid-request-id" };
+  return { ok: true, message: candidate };
+}

package/runtime/src/runtime-target-registry.mjs

@@ -0,0 +1,92 @@
+import { buildInjectionExpression, buildRemovalExpression, RUNTIME_VERSION } from "./inject-expression.mjs";
+
+export function isCodexRendererTarget(target) {
+  return target?.type === "page"
+    && typeof target.url === "string"
+    && target.url.startsWith("app://-")
+    && typeof target.webSocketDebuggerUrl === "string";
+}
+
+export class RuntimeTargetRegistry {
+  constructor(options) {
+    this.port = options.port;
+    this.ownsEndpoint = options.ownsEndpoint;
+    this.settingsRepository = options.settingsRepository;
+  }
+
+  async discover() {
+    const response = await fetch(`http://127.0.0.1:${this.port}/json/list`, {
+      redirect: "error",
+      signal: AbortSignal.timeout(800),
+    });
+    if (!response.ok) throw new Error(`CDP discovery failed: HTTP ${response.status}`);
+    const targets = await response.json();
+    return targets.filter(isCodexRendererTarget);
+  }
+
+  async evaluate(target, expression) {
+    const socket = new WebSocket(target.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        socket.close();
+        reject(new Error(`CDP websocket open timed out for target ${target.id}`));
+      }, 3000);
+      socket.addEventListener("open", () => { clearTimeout(timer); resolve(); }, { once: true });
+      socket.addEventListener("error", () => { clearTimeout(timer); reject(new Error(`CDP websocket open failed for target ${target.id}`)); }, { once: true });
+    });
+
+    try {
+      return await new Promise((resolve, reject) => {
+        const id = 1;
+        const timer = setTimeout(() => reject(new Error(`Runtime.evaluate timed out for target ${target.id}`)), 15_000);
+        socket.addEventListener("message", (event) => {
+          let message;
+          try {
+            message = JSON.parse(event.data);
+          } catch {
+            return;
+          }
+          if (message.id !== id) return;
+          clearTimeout(timer);
+          if (message.error) reject(new Error(message.error.message ?? "Runtime.evaluate failed"));
+          else if (message.result?.exceptionDetails) reject(new Error(message.result.exceptionDetails.text ?? "injected script failed"));
+          else resolve(message.result?.result?.value);
+        });
+        socket.send(JSON.stringify({
+          id,
+          method: "Runtime.evaluate",
+          params: { expression, awaitPromise: true, returnByValue: true },
+        }));
+      });
+    } finally {
+      socket.close();
+    }
+  }
+
+  async ensureInjected(settingsState) {
+    if (!(await this.ownsEndpoint())) throw new Error(`拒绝连接：127.0.0.1:${this.port} 不属于 Codex`);
+    const resolvedSettings = settingsState ?? await this.settingsRepository.read();
+    const targets = await this.discover();
+    if (targets.length === 0) throw new Error("未找到 Codex 主窗口 renderer");
+    const results = [];
+    const injectedTargetIds = new Set();
+    for (const target of targets) {
+      const activeVersion = await this.evaluate(target, "window.__codexSidebarTags?.version ?? null");
+      if (activeVersion === RUNTIME_VERSION) {
+        results.push(await this.evaluate(target, "window.__codexSidebarTags.status()"));
+        continue;
+      }
+      results.push(await this.evaluate(target, buildInjectionExpression({
+        tagDefinitions: resolvedSettings.settings.tags,
+        settingsSource: resolvedSettings.exists ? "repository" : "defaults",
+      })));
+      injectedTargetIds.add(target.id);
+    }
+    return { targets, results, injectedTargetIds };
+  }
+
+  async removeInjection() {
+    if (!(await this.ownsEndpoint())) throw new Error(`拒绝连接：127.0.0.1:${this.port} 不属于 Codex`);
+    for (const target of await this.discover()) await this.evaluate(target, buildRemovalExpression());
+  }
+}