claude-token-saver 3.28.0 → 3.28.1

package/README.en.md

@@ -397,12 +397,18 @@ Three situations, three different interception points:
 That second row is measured, not assumed: a `.pdf` Read fires the hook, and a `.pptx` Read in the same session leaves no hook log entry at all.
 
 ```bash
-claude-token-saver doc2md install-converter   # markitdown + editing libs + the .fig parser
-claude-token-saver doc2md on                  # register the Read hook
+claude-token-saver doc2md on                  # register the hooks (the converter installs itself)
 claude-token-saver doc2md                     # check converter + hook registration
 claude-token-saver doc2md report.pptx         # convert by hand and see the result
+claude-token-saver doc2md install-converter   # only to get the install out of the way early
 ```
 
+**The converter installs itself.** Any rollout step a person has to be told about is a step some of them skip, so the converter installs in the background the moment a document first shows up, and converts as soon as it is ready. Measured: about 30s for the first document (15s install plus markitdown's first import), then 3.7s for a new document and 0.1s on a cache hit. The `.fig` parser installs in half a second on the first Figma file.
+
+It installs on first use rather than at `install` time: the venv is 47MB, and someone who never opens a document should not pay for it. Set `CTS_DOC2MD_NO_AUTOINSTALL=1` to turn the automatic install off.
+
+**Python 3.10+ is required** — markitdown's own floor, and macOS still ships 3.9 as `/usr/bin/python3`. The venv is built on an interpreter chosen by version rather than by PATH order. Built on 3.9, pip resolves markitdown to a 2019 placeholder release (0.0.1a1): the install looks like it worked and every conversion then dies at import. This was found by walking into it. When nothing on the machine is new enough, the message points at `brew install python` instead of at an install command that cannot succeed.
+
 The converter goes into a venv this tool owns (`<state dir>/doc2md-venv`): no system interpreter is touched, and uninstalling the CLI takes it along. An existing markitdown on `uv tool` or `PATH` is preferred over building a new one.
 
 Conversion is [markitdown](https://github.com/microsoft/markitdown). Slide numbers, heading levels, tables, speaker notes and per-sheet headings all survive, and non-Latin text comes through intact.

package/README.md

@@ -389,12 +389,18 @@ doc2md 는 그 파일을 한 번 변환해 두고 원본 대신 변환본을 읽
 두 번째 줄의 제약은 실측으로 확인한 것입니다. `.pdf` 를 Read 하면 훅이 실행되고, 같은 세션에서 `.pptx` 를 Read 하면 훅 로그에 아무 기록도 남지 않습니다.
 
 ```bash
-claude-token-saver doc2md install-converter   # markitdown·편집 라이브러리·.fig 파서 설치
-claude-token-saver doc2md on                  # Read 훅 등록
+claude-token-saver doc2md on                  # 훅 등록 (변환기는 첫 문서에서 자동 설치)
 claude-token-saver doc2md                     # 변환기·훅 등록 상태 확인
 claude-token-saver doc2md 보고서.pptx          # 직접 변환해 결과 확인
+claude-token-saver doc2md install-converter   # 설치를 미리 끝내 두고 싶을 때만
 ```
 
+**변환기는 알아서 깔립니다.** 팀에 배포할 때 각자 설치 명령을 실행하게 만들면 그 단계에서 빠지는 사람이 생깁니다. 그래서 문서가 처음 등장하는 시점에 변환기가 백그라운드로 설치되고, 설치가 끝나는 대로 곧바로 변환합니다. 실측으로 첫 문서는 약 30초(설치 15초 + markitdown 최초 임포트), 이후로는 새 문서 3.7초, 캐시 적중 0.1초입니다. `.fig` 파서는 첫 Figma 파일에서 0.5초 만에 깔립니다.
+
+설치는 `install` 단계가 아니라 첫 사용 시점에 합니다. venv 가 47MB 라서, 문서를 다루지 않는 사람은 낼 이유가 없는 비용입니다. 자동 설치를 끄려면 `CTS_DOC2MD_NO_AUTOINSTALL=1` 을 설정하십시오.
+
+**파이썬 3.10 이상이 필요합니다.** markitdown 의 요구 사항이고, macOS 기본 `/usr/bin/python3` 는 3.9 입니다. 이 도구는 PATH 순서를 따르지 않고 3.10 이상인 인터프리터를 골라 venv 를 만듭니다. 3.9 로 만들면 pip 가 markitdown 을 2019 년 자리표시자 릴리스(0.0.1a1)로 해석해서, 설치는 성공한 것처럼 보이지만 모든 변환이 임포트 단계에서 죽습니다. 실제로 이 함정을 밟고 잡았습니다. 3.10 이상이 아예 없으면 설치 명령을 안내하는 대신 `brew install python` 을 안내합니다.
+
 변환기는 도구 전용 venv(`<상태 디렉터리>/doc2md-venv`)에 설치합니다. 시스템 파이썬을 건드리지 않고, CLI를 지우면 함께 사라집니다. 이미 `uv tool` 이나 다른 경로에 markitdown 이 있으면 그쪽을 먼저 씁니다.
 
 변환은 [markitdown](https://github.com/microsoft/markitdown)이 담당하며, 슬라이드 번호와 제목 계층, 표, 발표자 노트, 시트 구분이 모두 남습니다. 한글도 깨지지 않습니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.28.0",
+  "version": "3.28.1",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/doc2md.cjs

@@ -26,7 +26,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { spawnSync } = require('node:child_process');
+const { spawn, spawnSync } = require('node:child_process');
 const ledger = require('./doc2md-ledger.cjs');
 
 // Formats where the original is of no use to the model. Images are absent
@@ -226,6 +226,13 @@ function writeCache(filePath, markdown, extra) {
  * memoized for the life of this process, and the caller memoizes across
  * processes through the notice file.
  */
+// The readiness test for an interpreter. Importing the *class* matters: a pip
+// install creates the package directory long before it finishes writing into
+// it, so a bare `import markitdown` reports success mid-install and the
+// conversion then fails with "cannot import name 'MarkItDown'". Measured
+// during the first-use auto-install, where the window is about a second wide.
+const PROBE = 'from markitdown import MarkItDown';
+
 let interpreterCache;
 function findInterpreter() {
   if (interpreterCache !== undefined) return interpreterCache;
@@ -244,7 +251,7 @@ function findInterpreter() {
   );
   for (const bin of candidates) {
     try {
-      const probe = spawnSync(bin, ['-c', 'import markitdown'], { timeout: 20_000, stdio: 'ignore' });
+      const probe = spawnSync(bin, ['-c', PROBE], { timeout: 20_000, stdio: 'ignore' });
       if (probe.status === 0) {
         interpreterCache = bin;
         return bin;
@@ -281,19 +288,53 @@ const EDIT_LIBS = ['python-pptx', 'python-docx', 'openpyxl'];
  * for, it goes somewhere this tool owns, so uninstalling the CLI takes the
  * whole thing with it and no system interpreter is touched.
  */
+/**
+ * A Python new enough to run markitdown (3.10+), or null.
+ *
+ * Explicit version names are tried before the bare `python3` so a modern
+ * Homebrew interpreter wins over the system one regardless of PATH order.
+ */
+function findVenvBase() {
+  const candidates = [
+    'python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3.10',
+    'python3', 'python',
+  ];
+  for (const bin of candidates) {
+    const r = spawnSync(bin, ['-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], {
+      encoding: 'utf8',
+      timeout: 20_000,
+    });
+    if (r.status !== 0) continue;
+    const [major, minor] = String(r.stdout).trim().split('.').map(Number);
+    if (major > 3 || (major === 3 && minor >= 10)) return { bin, version: `python ${major}.${minor}` };
+  }
+  return null;
+}
+
 function installConverter({ onProgress = () => {} } = {}) {
   const venv = path.join(userDataDir(), 'doc2md-venv');
   const target = managedPython();
 
   if (!fs.existsSync(target)) {
-    onProgress(`creating ${venv}`);
-    let created = false;
-    for (const base of ['python3', 'python']) {
-      const r = spawnSync(base, ['-m', 'venv', venv], { encoding: 'utf8', timeout: 180_000 });
-      if (r.status === 0) { created = true; break; }
+    // The base interpreter is chosen by version, not by whichever `python3`
+    // comes first on PATH. markitdown needs 3.10+, and macOS still ships 3.9
+    // as /usr/bin/python3: building the venv on that one installs a
+    // seven-year-old placeholder release (0.0.1a1) that has no MarkItDown
+    // class in it, and every conversion then fails at import time. Measured
+    // on this machine, where /usr/bin/python3 precedes Homebrew's 3.14.
+    const base = findVenvBase();
+    if (!base) {
+      return {
+        ok: false,
+        reason: 'no-python',
+        detail: 'markitdown needs Python 3.10 or newer; none was found on PATH '
+          + '(macOS /usr/bin/python3 is 3.9 — install a newer one, e.g. `brew install python`)',
+      };
     }
-    if (!created) {
-      return { ok: false, reason: 'no-python', detail: 'no python3 with the venv module on PATH' };
+    onProgress(`creating ${venv} (${base.version})`);
+    const r = spawnSync(base.bin, ['-m', 'venv', venv], { encoding: 'utf8', timeout: 180_000 });
+    if (r.status !== 0) {
+      return { ok: false, reason: 'no-python', detail: (r.stderr || 'venv creation failed').slice(0, 300) };
     }
   }
 
@@ -308,7 +349,7 @@ function installConverter({ onProgress = () => {} } = {}) {
 
   // The probe is the actual acceptance test: pip can exit 0 and still leave an
   // interpreter that cannot import what was asked for.
-  const probe = spawnSync(target, ['-c', 'import markitdown'], { timeout: 60_000, stdio: 'ignore' });
+  const probe = spawnSync(target, ['-c', PROBE], { timeout: 60_000, stdio: 'ignore' });
   if (probe.status !== 0) {
     return { ok: false, reason: 'import-failed', detail: 'installed, but markitdown does not import' };
   }
@@ -320,8 +361,8 @@ function installConverter({ onProgress = () => {} } = {}) {
 /**
  * Convert one file. Returns `{ ok: true, cacheFile, meta }`, or
  * `{ ok: false, reason, detail }` where reason is one of:
- *   no-markitdown | too-large | sensitive | unsafe-archive | no-text |
- *   convert-failed | timeout
+ *   no-markitdown | python-too-old | no-figparser | too-large | sensitive |
+ *   unsafe-archive | no-text | convert-failed | timeout
  *
  * Every failure is a reason to leave the original Read alone, never to break
  * it. That is the whole contract with the hook.
@@ -370,7 +411,14 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   // Figma files take the Node converter; everything else goes to markitdown.
   if (path.extname(filePath).toLowerCase() === '.fig') {
     const fig2md = require('./fig2md.cjs');
-    const result = spawnFigConvert(fig2md, filePath);
+    let result = spawnFigConvert(fig2md, filePath);
+    // The .fig parser is an npm install of a few hundred KB, fast enough to
+    // wait for inline the first time a Figma file turns up.
+    if (!result.ok && result.reason === 'no-figparser'
+        && process.env.CTS_DOC2MD_NO_AUTOINSTALL !== '1') {
+      fig2md.installFigParser(userDataDir());
+      result = spawnFigConvert(fig2md, filePath);
+    }
     if (!result.ok) return result;
     const written = writeCache(filePath, result.markdown, {
       note: result.note, truncated: false, rows: 0, pages: 0, markupBytes: 0,
@@ -381,7 +429,21 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   // The override exists so tests can drive a stub converter with any Python at
   // all: the normal search insists the interpreter can import markitdown,
   // which would make the whole path untestable without the real package.
-  const python = pythonOverride || findInterpreter();
+  let python = pythonOverride || findInterpreter();
+  if (!python && !pythonOverride) {
+    // Telling someone to run the install command is wrong when the install
+    // cannot succeed on this machine. A too-old interpreter is a different
+    // problem with a different fix, so it gets its own reason rather than
+    // hiding behind "no converter".
+    if (!findVenvBase()) {
+      return {
+        ok: false,
+        reason: 'python-too-old',
+        detail: 'markitdown needs Python 3.10 or newer; none was found on PATH',
+      };
+    }
+    if (ensureConverterInstalled()) python = findInterpreter();
+  }
   if (!python) return { ok: false, reason: 'no-markitdown' };
 
   const run = spawnSync(python, [converter, filePath], {
@@ -421,6 +483,72 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
 }
 
+/**
+ * First-use install, so nobody has to be told to run a setup command.
+ *
+ * A team rollout dies on any step a person has to be told about, so the
+ * converter installs itself the first time a document actually shows up. It
+ * is still lazy rather than part of `install`: the venv is 47MB, and someone
+ * who never opens a document should never pay for it.
+ *
+ * The install runs detached and the caller waits only briefly. A cold install
+ * measured 6 seconds on a fast connection, but a corporate network can be far
+ * slower, and a hook that blocks a prompt for a minute is worse than a
+ * document that converts on the next turn. So: start it, wait up to
+ * `waitMs`, and if it is still going, say so and let this turn proceed
+ * without the conversion.
+ *
+ * Returns true when a converter is ready to use right now.
+ */
+function ensureConverterInstalled({ waitMs = 15_000 } = {}) {
+  if (process.env.CTS_DOC2MD_NO_AUTOINSTALL === '1') return false;
+  if (findInterpreter()) return true;
+
+  const lock = path.join(userDataDir(), 'doc2md-install.lock');
+  let running = false;
+  try {
+    const started = JSON.parse(fs.readFileSync(lock, 'utf8')).startedAt;
+    // A lock older than the pip timeout is a crashed run, not a live one.
+    running = Number.isFinite(started) && Date.now() - started < 900_000;
+  } catch { /* no lock, or an unreadable one: treat as not running */ }
+
+  if (!running) {
+    try {
+      fs.mkdirSync(userDataDir(), { recursive: true });
+      fs.writeFileSync(lock, JSON.stringify({ startedAt: Date.now() }));
+      const cli = path.join(__dirname, '..', 'bin', 'cli.js');
+      // Detached, so a session that ends mid-install does not take the
+      // install with it — the next session finds it finished.
+      const child = spawn(process.execPath, [cli, 'doc2md', 'install-converter'], {
+        detached: true,
+        stdio: 'ignore',
+      });
+      child.unref();
+    } catch {
+      try { fs.rmSync(lock, { force: true }); } catch { /* best effort */ }
+      return false;
+    }
+  }
+
+  // Poll cheaply: the interpreter file appearing is the first sign, and the
+  // import probe is the acceptance test. interpreterCache has to be cleared
+  // or the memoized null from the top of this function would stick.
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(managedPython())) {
+      interpreterCache = undefined;
+      if (findInterpreter()) {
+        try { fs.rmSync(lock, { force: true }); } catch { /* best effort */ }
+        return true;
+      }
+    }
+    // A synchronous sleep, because every caller here is synchronous. 400ms
+    // keeps the poll count low over a 15s wait.
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 400);
+  }
+  return false;
+}
+
 /** Where the "markitdown is not installed" notice records that it was shown. */
 function noticePath() {
   return path.join(userDataDir(), 'doc2md-notice.json');
@@ -490,9 +618,19 @@ function decideForRead(context, opts = {}) {
     markNoticeShown();
     return {
       deny: false,
-      reason: `[doc2md] ${name} 를 변환하려 했으나 markitdown 이 설치되어 있지 않습니다.\n`
-        + `  설치: ${INSTALL_HINT}\n`
-        + '  설치 전까지는 원본을 그대로 읽습니다. 이 안내는 한 번만 표시됩니다.',
+      reason: `[doc2md] ${name} 를 변환할 변환기를 지금 설치하고 있습니다(첫 실행에만 걸립니다).\n`
+        + '  설치가 끝나면 다음 요청부터 자동으로 변환합니다. 이번 turn 은 원본을 그대로 읽습니다.\n'
+        + `  진행 상황: ${INSTALL_HINT} 를 직접 실행하면 설치 로그를 볼 수 있습니다.`,
+    };
+  }
+  if (result.reason === 'python-too-old') {
+    if (noticeAlreadyShown()) return null;
+    markNoticeShown();
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 를 변환하지 못했습니다. 변환기(markitdown)는 Python 3.10 이상이 필요한데 PATH 에서 찾지 못했습니다.\n`
+        + '  macOS 기본 /usr/bin/python3 는 3.9 입니다. `brew install python` 으로 새 버전을 설치한 뒤 다시 시도하십시오.\n'
+        + '  그때까지는 원본을 그대로 읽습니다. 이 안내는 한 번만 표시됩니다.',
     };
   }
   if (result.reason === 'no-text') {
@@ -613,8 +751,12 @@ function contextForPrompt(payload, opts = {}) {
       }
     } else if (result.reason === 'no-markitdown') {
       lines.push(lang === 'ko'
-        ? `  ${name}: 변환기가 없어 변환하지 못했습니다. 설치: ${INSTALL_HINT}`
-        : `  ${name}: no converter installed. Install it with: ${INSTALL_HINT}`);
+        ? `  ${name}: 변환기를 설치하는 중입니다(첫 실행에만 걸립니다). 설치가 끝나면 다음 요청부터 자동 변환됩니다.`
+        : `  ${name}: the converter is installing now (first run only). It will convert automatically from the next request.`);
+    } else if (result.reason === 'python-too-old') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: 변환기가 Python 3.10 이상을 요구하는데 PATH 에 없습니다(macOS 기본은 3.9). \`brew install python\` 후 다시 시도하도록 사용자에게 안내하십시오.`
+        : `  ${name}: the converter needs Python 3.10+, and none is on PATH (macOS ships 3.9). Tell the user to install a newer Python, e.g. \`brew install python\`.`);
     } else if (result.reason === 'no-figparser') {
       lines.push(lang === 'ko'
         ? `  ${name}: .fig 파서가 없어 변환하지 못했습니다. 설치: claude-token-saver doc2md install-converter`
@@ -744,6 +886,8 @@ module.exports = {
   MARKITDOWN_SPEC,
   managedPython,
   installConverter,
+  ensureConverterInstalled,
+  findVenvBase,
   clearNotice,
   cacheDir,
   cachePathFor,