@alanwalk/codex-until 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @alanwalk/codex-until
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Windows Codex 额度监控命令行工具。零 npm 依赖，Node.js 18 或以上。
+
+需要已安装并通过 ChatGPT 账号登录的官方 Codex CLI / 桌面应用。工具复用本地登录状态，不打印 token。默认使用桌面应用 CLI，找不到时使用 PATH 中的 `codex.exe`；可通过 `CODEX_QUOTA_CLI` 指定完整可执行文件路径。
+
+发布到 npm 后，无需预先执行 `npm install`，直接运行：
+
+```powershell
+npx @alanwalk/codex-until
+npx --yes @alanwalk/codex-until status
+npx --yes @alanwalk/codex-until stop
+npx --yes @alanwalk/codex-until quota
+npx --yes @alanwalk/codex-until logs
+```
+
+不带参数会立即开启监控：在交互终端中显示最新日志，输入 `b` 并回车转入后台，输入 `q` 并回车停止监控并退出，`Ctrl+C` 同样停止监控。转入后台只是退出控制台，监控进程及本次比较基线保持不变。输入流关闭时也会退出控制台并保留后台监控。
+
+`start` 与无参数执行相同，在交互终端默认显示日志和 b/q 选项；使用 `-b / --background` 直接进入后台：
+
+```powershell
+npx @alanwalk/codex-until                      # 显示日志及 b/q 选项
+npx @alanwalk/codex-until start                # 同上
+npx @alanwalk/codex-until -b                   # 直接后台运行
+npx @alanwalk/codex-until start --background   # 同上，可简写 -b
+```
+
+通过自动化工具等非交互环境无参数执行时，默认后台启动，不等待输入。重复启动不会产生多个监控，前台模式可连接已有监控。`stop` 只停止监控，不停止 Codex。`status` 输出 JSON；表示后台监控进程可响应，不代表最近的额度请求一定成功，请结合 `logs` 查看查询结果。`--help` 显示帮助；添加 `--yes`（例如 `npx --yes @alanwalk/codex-until`）可跳过 npx 首次下载确认。
+
+## 重置判断
+
+首次成功查询只建立内存基线。后续对比上次成功查询，在账号、窗口名称和窗口时长相同的前提下，任一窗口满足以下条件即触发：
+
+- 已用百分比下降，即剩余额度上升，哪怕只上升 1%。
+- 重置时间推迟，且已用百分比没有增加。
+
+查询失败记录日志并重试，不清空上一次成功结果。停止再启动重新建立基线，不比较监控停机期间的变化。服务端额度修正也可能满足上述规则。轮询存在约一分钟延迟，另加网络请求耗时。
+
+**触发后执行 `taskkill /F /T /IM codex.exe`，强制结束本机所有 Codex 进程及其子进程，包括其他账号的本地会话，正在执行的任务会被中断。远程主机不受影响。** 成功后监控退出；停止失败会记录错误，后续继续尝试。没有自动消费额度重置次数的功能。
+
+日志保存在 `%LOCALAPPDATA%\codex-quota-guard\monitor.log`，不写入 npx 缓存中的包目录。日志不包含凭据。后台监控没有开机自启功能。
+
+## 本地验证
+
+```powershell
+npm run prepublishOnly
+npm pack
+```
+
+当前包名是 `@alanwalk/codex-until`，未确认 npm 名称可用性。包内使用 files 白名单，不包含本机日志、测试或登录凭据。无需构建、无需 npm install。npx 首次运行仍需联网下载并缓存包。
+
+## GitHub Actions 自动发布 npm
+
+沿用 [alanwalk/svn-merge-tool](https://github.com/alanwalk/svn-merge-tool/blob/main/.github/workflows/npm-publish.yml) 的发布方式：发布 GitHub Release 后，检查通过才发布 npm。配置文件为 `.github/workflows/npm-publish.yml`，Node.js 24，使用 npm Trusted Publishing（OIDC），无需配置 `NPM_TOKEN`。
+
+### 首次配置
+
+1. 将项目上传到你自己的 GitHub 仓库，包含 `.github/workflows/npm-publish.yml`。
+2. 确认 npm 账号有 `@alanwalk` scope 的发布权限。若该包尚不存在，先在本机完成首次发布：
+
+   ```powershell
+   npm login
+   npm publish --access public
+   ```
+
+3. 打开 npm 网站中 `@alanwalk/codex-until` 的 Settings → Trusted Publisher，选择 GitHub Actions，填写实际 GitHub 用户/组织、仓库名，以及工作流文件名 `npm-publish.yml`。当前 workflow 未使用 GitHub Environment，此项留空；如果页面提供 Allowed actions，允许直接执行 `npm publish`。
+4. 按 [npm 官方 Trusted Publishing 文档](https://docs.npmjs.com/trusted-publishers/) 保存配置。上传源码本身不会触发发布；只有发布 GitHub Release 才触发。
+
+### 后续发版
+
+1. 修改代码，运行 `npm run prepublishOnly`。
+2. 修改版本，例如运行 `npm version patch --no-git-tag-version`，然后提交并推送代码。
+3. 在 GitHub 创建并发布 Release，tag 必须为 `v` 加 `package.json` 中的版本，例如 `v0.1.1`。tag 应指向准备发布的提交。
+4. Actions 先在 Windows 上检查 tag、语法、帮助入口、判断测试及包内容，再在 Ubuntu 上使用 OIDC 执行 `npm publish`。全程无需安装 npm 依赖。
+
+版本号必须是 npm 尚未发布的版本；相同版本不能重复发布。`package.json` 已设置 public access。Release 的 prerelease 标志不会自动切换 npm dist-tag，当前流程统一使用 `latest`，请只发布准备正式使用的版本。

package/bin/cli.cjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const readline = require('node:readline');
+const { spawn } = require('node:child_process');
+const watch = require('../watch-codex-quota.cjs');
+const userKey = crypto.createHash('sha256').update(os.homedir()).digest('hex').slice(0, 16);
+const pipe = `\\\\.\\pipe\\codex-quota-guard-${userKey}`;
+
+function request(action) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(pipe);
+    let response = '';
+    socket.setTimeout(2000, () => socket.destroy(new Error('Monitor response timed out')));
+    socket.on('connect', () => socket.write(action + '\n'));
+    socket.on('data', chunk => { response += chunk; });
+    socket.on('end', () => {
+      try { resolve(JSON.parse(response)); } catch { reject(new Error('Invalid monitor response')); }
+    });
+    socket.on('error', reject);
+  });
+}
+
+async function status() {
+  try { return await request('status'); }
+  catch (error) {
+    if (['ENOENT', 'ECONNREFUSED'].includes(error.code)) return { running: false, logPath: watch.logPath };
+    throw error;
+  }
+}
+
+async function daemon() {
+  const server = net.createServer(socket => {
+    socket.setTimeout(2000, () => socket.destroy());
+    socket.on('error', () => {});
+    socket.once('data', data => {
+      const action = data.toString().trim();
+      const result = { running: action !== 'stop', pid: process.pid, logPath: watch.logPath };
+      socket.end(JSON.stringify(result) + '\n', () => {
+        if (action === 'stop') process.exit(0);
+      });
+    });
+  });
+  server.on('error', error => {
+    if (error.code !== 'EADDRINUSE') console.error(error.message);
+    process.exit(error.code === 'EADDRINUSE' ? 0 : 1);
+  });
+  server.listen(pipe, () => {
+    watch.main().then(() => process.exit(process.exitCode || 0)).catch(error => {
+      console.error(error.message);
+      process.exit(1);
+    });
+  });
+}
+
+function parseOptions(args, interactive) {
+  const hasCommand = args.length > 0 && !args[0].startsWith('-');
+  const action = hasCommand ? args[0] : 'start';
+  if (['--help', '-h'].includes(args[0])) return { action: 'help', foreground: false };
+  const flags = hasCommand ? args.slice(1) : args;
+  if (flags.some(flag => !['--background', '-b'].includes(flag))) {
+    throw new Error('Unknown option. Use --help.');
+  }
+  const background = flags.some(flag => ['--background', '-b'].includes(flag));
+  if (flags.length && action !== 'start') throw new Error('Mode options are only supported by start.');
+  return { action, foreground: action === 'start' && interactive && !background };
+}
+
+async function consoleMode() {
+  console.log('监控中：输入 b 回车转入后台；输入 q 回车停止监控并退出。Ctrl+C 同样停止监控。');
+  const input = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let lastLog = '';
+  let busy = false;
+  let closing = false;
+  return new Promise(resolve => {
+    const finish = async stop => {
+      if (closing) return;
+      closing = true;
+      clearInterval(timer);
+      try {
+        if (stop) {
+          const current = await status();
+          if (current.running) await request('stop');
+          console.log('监控已停止。Codex 会话保持运行。');
+        } else console.log('已退出控制台，监控继续在后台运行。');
+      } catch (error) { console.error(error.message); process.exitCode = 1; }
+      input.close();
+      process.removeListener('SIGINT', interrupt);
+      resolve();
+    };
+    const interrupt = () => { void finish(true); };
+    const refresh = async () => {
+      if (busy || closing) return;
+      busy = true;
+      try {
+        if (fs.existsSync(watch.logPath)) {
+          const latest = fs.readFileSync(watch.logPath, 'utf8').trimEnd().split('\n').slice(-1)[0];
+          if (latest !== lastLog) { console.log(latest); lastLog = latest; }
+        }
+        if (!(await status()).running) {
+          console.log('后台监控已退出。');
+          closing = true;
+          clearInterval(timer);
+          input.close();
+          process.removeListener('SIGINT', interrupt);
+          resolve();
+        }
+      } catch (error) { console.error(error.message); }
+      finally { busy = false; }
+    };
+    const timer = setInterval(refresh, 1000);
+    input.on('line', line => {
+      const choice = line.trim().toLowerCase();
+      if (choice === 'b') void finish(false);
+      else if (choice === 'q') void finish(true);
+      else console.log('输入 b 转入后台，或 q 停止并退出。');
+    });
+    input.on('SIGINT', interrupt);
+    process.on('SIGINT', interrupt);
+    input.on('close', () => { if (!closing) void finish(false); });
+    void refresh();
+  });
+}
+
+async function main() {
+  const { action, foreground } = parseOptions(process.argv.slice(2), Boolean(process.stdin.isTTY && process.stdout.isTTY));
+  if (['help', '--help', '-h'].includes(action)) {
+    console.log(`Codex Until (Windows, Node >=18)
+Usage: codex-until [start|stop|status|quota|logs]
+No command defaults to start. Without -b, show b/q controls in a terminal.
+Non-interactive invocations run in the background.
+  start   Start polling every 60 seconds; repeated calls are safe.
+          --background / -b: start directly in the background.
+  stop    Stop monitoring only. Codex sessions remain running.
+  status  Print monitor status as JSON.
+  quota   Query quota once without enabling monitoring.
+  logs    Print the last 50 log lines.
+Reset detection stops ALL local codex.exe processes and their children.
+Restarting the monitor establishes a fresh baseline. No baseline is persisted.`);
+    return;
+  }
+  if (process.platform !== 'win32') throw new Error('This version supports Windows only.');
+  if (action === '--daemon') return daemon();
+  if (action === 'quota') return watch.main(true);
+  if (action === 'logs') {
+    if (!fs.existsSync(watch.logPath)) return console.log('No logs yet.');
+    return console.log(fs.readFileSync(watch.logPath, 'utf8').trimEnd().split('\n').slice(-50).join('\n'));
+  }
+  if (!['start', 'stop', 'status'].includes(action)) throw new Error(`Unknown command: ${action}. Use --help.`);
+  const before = await status();
+  if (action === 'status') return console.log(JSON.stringify(before));
+  if (action === 'stop') {
+    const result = before.running ? await request('stop') : before;
+    console.log(JSON.stringify({ ...result, changed: before.running }));
+    return;
+  }
+  if (before.running) {
+    console.log(JSON.stringify({ ...before, changed: false }));
+    if (foreground) await consoleMode();
+    return;
+  }
+  fs.mkdirSync(path.dirname(watch.logPath), { recursive: true });
+  const output = fs.openSync(watch.logPath, 'a');
+  const child = spawn(process.execPath, [__filename, '--daemon'], {
+    detached: true, windowsHide: true, stdio: ['ignore', 'ignore', output],
+  });
+  fs.closeSync(output);
+  child.on('error', error => { console.error(error.message); process.exitCode = 1; });
+  child.unref();
+  for (let attempt = 0; attempt < 50; attempt++) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    const result = await status();
+    if (result.running) {
+      console.log(JSON.stringify({ ...result, changed: true }));
+      if (foreground) await consoleMode();
+      return;
+    }
+  }
+  throw new Error(`Monitor failed to start. See ${watch.logPath}`);
+}
+
+module.exports = { parseOptions };
+if (require.main === module) main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@alanwalk/codex-until",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Stop local Codex sessions when quota resets during monitoring.",
+  "homepage": "https://github.com/alanwalk/codex-until#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alanwalk/codex-until.git"
+  },
+  "bugs": { "url": "https://github.com/alanwalk/codex-until/issues" },
+  "license": "UNLICENSED",
+  "publishConfig": { "access": "public" },
+  "bin": { "codex-until": "bin/cli.cjs" },
+  "main": "watch-codex-quota.cjs",
+  "files": ["bin/", "watch-codex-quota.cjs", "README.md"],
+  "engines": { "node": ">=18" },
+  "os": ["win32"],
+  "scripts": {
+    "check": "node --check bin/cli.cjs && node --check watch-codex-quota.cjs && node bin/cli.cjs --help",
+    "test": "node watch-codex-quota.test.cjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "keywords": ["codex", "quota", "cli", "monitor"]
+}

package/watch-codex-quota.cjs

@@ -0,0 +1,131 @@
+const { spawn, spawnSync } = require('node:child_process');
+const readline = require('node:readline');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const logPath = path.join(process.env.LOCALAPPDATA || os.homedir(), 'codex-quota-guard', 'monitor.log');
+function log(message) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const line = `${new Date().toISOString()} ${message}`;
+  fs.appendFileSync(logPath, line + '\n');
+  console.log(line);
+}
+
+function readQuota() {
+  return new Promise((resolve, reject) => {
+    const desktopCli = path.join(process.env.LOCALAPPDATA || '', 'Programs/OpenAI/Codex/bin/codex.exe');
+    const cli = process.env.CODEX_QUOTA_CLI || (fs.existsSync(desktopCli) ? desktopCli : 'codex.exe');
+    const child = spawn(cli, ['app-server', '--stdio'], {
+      windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const send = message => child.stdin.write(JSON.stringify(message) + '\n');
+    const cleanup = () => child.kill();
+    process.once('exit', cleanup);
+    let settled = false;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      process.removeListener('exit', cleanup);
+      clearTimeout(timeout);
+      child.kill();
+      if (error) reject(error);
+      else resolve(result);
+    };
+    const timeout = setTimeout(() => finish(new Error('Quota query timed out')), 30000);
+    child.stderr.resume();
+    child.on('error', error => finish(error));
+    child.stdin.on('error', error => finish(error));
+    child.on('exit', () => finish(new Error('Quota query process exited')));
+    readline.createInterface({ input: child.stdout }).on('line', line => {
+      let message;
+      try { message = JSON.parse(line); } catch { return; }
+      if (message.id !== 1 && message.id !== 2) return;
+      if (message.error) return finish(new Error(message.error.message));
+      if (message.id === 1) {
+        send({ method: 'initialized', params: {} });
+        send({ id: 2, method: 'account/rateLimits/read', params: {} });
+      } else {
+        finish(null, message.result);
+      }
+    });
+    send({ id: 1, method: 'initialize', params: {
+      clientInfo: { name: 'quota_watch', version: '1.0.0' },
+    } });
+  });
+}
+
+function getSnapshot(result) {
+  const limits = result.rateLimitsByLimitId?.codex ?? result.rateLimits;
+  if (!result.accountId || !limits || limits.limitId !== 'codex') {
+    throw new Error('Missing Codex account or quota');
+  }
+  const windows = {};
+  for (const name of ['primary', 'secondary']) {
+    const window = limits[name];
+    if (!window) continue;
+    if (!Number.isFinite(window.usedPercent) || window.usedPercent < 0 ||
+        window.usedPercent > 100 || !Number.isFinite(window.resetsAt) ||
+        !Number.isFinite(window.windowDurationMins)) {
+      throw new Error('Invalid quota window');
+    }
+    windows[name] = window;
+  }
+  if (!Object.keys(windows).length) throw new Error('No quota windows returned');
+  return { accountId: result.accountId, windows };
+}
+
+function resetReason(previous, current) {
+  if (!previous || previous.accountId !== current.accountId) return null;
+  for (const [name, window] of Object.entries(current.windows)) {
+    const before = previous.windows[name];
+    if (!before || before.windowDurationMins !== window.windowDurationMins) continue;
+    if (window.usedPercent < before.usedPercent) {
+      return `${name}: used ${before.usedPercent}% -> ${window.usedPercent}%`;
+    }
+    if (window.resetsAt > before.resetsAt && window.usedPercent <= before.usedPercent) {
+      return `${name}: reset time advanced`;
+    }
+  }
+  return null;
+}
+
+function stopCodex() {
+  // /T also stops tasks spawned by each Codex process.
+  const result = spawnSync('taskkill.exe', ['/F', '/T', '/IM', 'codex.exe'], {
+    windowsHide: true, encoding: 'utf8',
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(`Failed to stop Codex: ${result.error?.message ?? result.stderr.trim()}`);
+  }
+  log('All local codex.exe processes and their child processes stopped.');
+}
+
+async function main(queryOnly = process.argv.includes('--once')) {
+  let previous = null;
+  log('Started. Polling every 60 seconds. Ctrl+C stops this monitor.');
+  for (;;) {
+    const started = Date.now();
+    try {
+      const current = getSnapshot(await readQuota());
+      log(Object.entries(current.windows).map(([name, window]) =>
+        `${name}: remaining ${100 - window.usedPercent}%, reset ${new Date(window.resetsAt * 1000).toISOString()}`
+      ).join('; '));
+      if (queryOnly) return;
+      const reason = resetReason(previous, current);
+      if (reason) {
+        log(`RESET DETECTED: ${reason}. Stopping all local Codex sessions.`);
+        stopCodex();
+        return;
+      }
+      previous = current;
+    } catch (error) {
+      log(`ERROR: ${error.message}`);
+      if (queryOnly) { process.exitCode = 1; return; }
+    }
+    await new Promise(resolve => setTimeout(resolve, Math.max(0, 60000 - (Date.now() - started))));
+  }
+}
+
+module.exports = { getSnapshot, resetReason, main, logPath };
+if (require.main === module) main().catch(error => { console.error(error); process.exitCode = 1; });