claude-token-saver 3.28.1 → 3.28.2

package/README.en.md

@@ -461,6 +461,23 @@ Conversion is one-way — editing the cached `.md` changes nothing in the source
 
 All four formats were exercised end to end on 2026-09-06: 10 docx run replacements plus three consecutive re-saves, a pptx bar-to-line chart swap with an added data point, xlsx value edits and a new row, and a fig text edit with re-encode and re-parse. In every case the original was byte-identical afterwards and the re-converted copy showed the change. One caveat: removing a chart shape from a pptx leaves the old chart XML part orphaned — PowerPoint ignores it, but delete the part and its rels for a clean file. Charts and images never appear in a conversion, so visual edits must be confirmed in the application itself.
 
+### Locked documents, and Windows
+
+**A password-protected document is a state, not an error.** Office encrypts by wrapping the package in an OLE compound file rather than a zip, so opening one as a zip used to report "not a zip file" — which reads as a broken download and sends the user after the wrong problem. It is now identified before conversion:
+
+```
+✗ encrypted: password-protected Office file (OLE-wrapped)
+✗ encrypted: password-protected PDF
+```
+
+The model is told to ask for an unlocked copy. This tool never asks for or stores a password, and never blocks the original `Read`, so work continues either way. A PDF that merely restricts printing still opens and still converts — checked against a false positive — and a legacy `.xls`, which is an OLE file by design, is not mistaken for an encrypted one.
+
+**Windows is supported.** For teams with Windows machines:
+
+- The Python search uses the `py -3` launcher. `python3` is rarely on PATH there, and a bare `python` may be the Store alias stub that opens a web page instead of running anything. Venv interpreters are looked for at `Scripts\python.exe`.
+- The `.fig` parser installs through `npm.cmd` via the shell, and the package spec dropped its caret (`openfig-core@0.4.x`): in cmd.exe `^` is the escape character and never reaches npm.
+- The background install and every child process set `windowsHide`, so no console window appears in the middle of someone's prompt.
+
 `claude-token-saver doc2md --clean` empties the conversion cache; `doc2md off` removes the hook. Removal filters for this tool's own entry, so anything else you registered under `PreToolUse` stays.
 
 ## 🌐 Behind a gateway (Bedrock / Vertex)

package/README.md

@@ -457,6 +457,23 @@ PDF 는 첨부하면 모델이 내용을 그대로 읽습니다. 대신 페이
 
 네 형식 모두 실제로 몇 바퀴 돌려 검증했습니다(2026-09-06): docx 텍스트 치환 10건과 3회 연속 재저장, pptx 막대→꺾은선 차트 교체와 데이터 행 추가, xlsx 값 정정·행 추가, fig 텍스트 수정·재인코드·재파싱. 전 케이스에서 원본은 바이트 그대로였고, 수정본 재변환에 변경 내용이 반영됐습니다. 한 가지 주의: pptx 에서 차트 도형을 제거하면 옛 차트 XML 파트가 고아로 남습니다. PowerPoint 는 무시하지만, 깔끔히 하려면 파트와 rels 도 지우십시오. 차트·이미지 같은 시각 요소는 변환본에 잡히지 않으므로, 시각 편집의 최종 확인은 해당 프로그램에서 해야 합니다.
 
+### 암호가 걸린 문서와 Windows
+
+**암호 문서는 오류가 아니라 상태로 다룹니다.** 사내에서 받는 문서 중 일부는 암호가 걸려 있습니다. 이전에는 암호 걸린 docx 를 "손상된 zip"이라고 알려서 사용자가 원인을 엉뚱한 곳에서 찾게 만들었습니다. 암호가 걸린 Office 문서는 zip 이 아니라 OLE 복합 문서로 저장되기 때문입니다. 지금은 변환 전에 판별해서 이렇게 알립니다.
+
+```
+✗ encrypted: password-protected Office file (OLE-wrapped)
+✗ encrypted: password-protected PDF
+```
+
+모델에게는 암호를 푼 사본을 사용자에게 요청하라고 안내합니다. 이 도구는 암호를 묻지도 저장하지도 않습니다. 어느 경우에도 원본 `Read` 를 막지 않으므로 작업이 중단되지 않습니다. 열람은 자유롭고 인쇄만 제한된 PDF 는 암호 문서가 아니므로 그대로 변환합니다(오탐 확인 완료). 구형 `.xls` 도 원래 OLE 형식이라 암호로 오인하지 않습니다.
+
+**Windows 를 지원합니다.** 사내에 Windows 사용자가 있어 다음을 맞췄습니다.
+
+- 파이썬 탐색이 `py -3` 런처를 씁니다. Windows 에서는 `python3` 가 PATH 에 없는 경우가 많고, 맨 `python` 은 실행 대신 마이크로소프트 스토어를 여는 별칭 스텁일 수 있습니다. venv 기반 인터프리터도 `Scripts\python.exe` 경로로 찾습니다.
+- `.fig` 파서 설치가 `npm.cmd` 를 셸로 호출합니다. 그리고 패키지 지정자에서 캐럿을 뺐습니다(`openfig-core@0.4.x`). cmd.exe 에서 `^` 는 이스케이프 문자라 npm 에 닿기 전에 먹힙니다.
+- 백그라운드 자동 설치와 모든 하위 프로세스에 `windowsHide` 를 걸어, 프롬프트 도중에 콘솔 창이 튀어나오지 않게 했습니다.
+
 `claude-token-saver doc2md --clean` 으로 변환 캐시를 비우고, `doc2md off` 로 훅을 제거합니다. 훅 해제는 자기 항목만 골라 지우므로 `PreToolUse` 에 등록해 둔 다른 훅은 그대로 남습니다.
 
 ## 🌐 Bedrock·Vertex 경유 환경

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.28.1",
+  "version": "3.28.2",
   "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/presets/doc2md/convert.py

@@ -43,6 +43,55 @@ def fail(reason, detail=""):
     sys.exit(0)
 
 
+# A password-protected OOXML file is not a zip at all: Office wraps the whole
+# package in an OLE compound file whose streams hold the ciphertext. Opening it
+# as a zip therefore reports "not a zip file", which reads as a broken download
+# and sends the user looking for the wrong problem.
+OLE_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+
+
+def encryption_problem(path, ext):
+    """('encrypted', detail) when the file is password-protected, else None."""
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(8)
+    except OSError:
+        return None
+
+    # Legacy .xls is an OLE file by design, so the magic alone proves nothing
+    # there. For the modern formats it can only mean encryption.
+    if ext in ZIP_EXTS and head == OLE_MAGIC:
+        return ("encrypted", "password-protected Office file (OLE-wrapped)")
+
+    # Some producers keep the zip container and put the ciphertext inside it.
+    if ext in ZIP_EXTS:
+        try:
+            import zipfile
+            with zipfile.ZipFile(path) as z:
+                names = z.namelist()
+            if any(n.startswith("EncryptedPackage") for n in names):
+                return ("encrypted", "password-protected Office file")
+        except Exception:
+            return None
+
+    if ext == ".pdf":
+        try:
+            from pdfminer.pdfparser import PDFParser
+            from pdfminer.pdfdocument import PDFDocument
+            with open(path, "rb") as fh:
+                doc = PDFDocument(PDFParser(fh))
+            # An empty owner password is the ordinary "printing restricted"
+            # case, which extracts fine. Only a document that refuses to open
+            # counts as encrypted here.
+            if doc.encryption is not None and not doc.is_extractable:
+                return ("encrypted", "password-protected PDF")
+        except Exception as e:
+            if "password" in str(type(e).__name__).lower() or "password" in str(e).lower():
+                return ("encrypted", "password-protected PDF")
+            return None
+    return None
+
+
 def check_zip(path):
     """Classify an archive before opening it as a document.
 
@@ -189,6 +238,13 @@ def main():
         fail("missing", path)
 
     ext = os.path.splitext(path)[1].lower()
+
+    # Checked before anything else opens the file: an encrypted document is a
+    # normal thing to receive, not a failure to report as corruption.
+    locked = encryption_problem(path, ext)
+    if locked:
+        fail(locked[0], locked[1])
+
     if ext in ZIP_EXTS:
         problem = check_zip(path)
         if problem:
@@ -224,6 +280,11 @@ def main():
         result = MarkItDown().convert(path)
         text = (result.text_content or "").strip()
     except Exception as e:
+        # markitdown surfaces the password failure from whichever backend hit
+        # it, so the type name is the reliable part.
+        blob = (type(e).__name__ + " " + str(e)).lower()
+        if "password" in blob or "encrypted" in blob:
+            fail("encrypted", "the file is password-protected")
         fail("convert-failed", e)
 
     if not text:

package/src/doc2md.cjs

@@ -233,28 +233,55 @@ function writeCache(filePath, markdown, extra) {
 // during the first-use auto-install, where the window is about a second wide.
 const PROBE = 'from markitdown import MarkItDown';
 
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Interpreters to try, as `{ bin, args }` so the Windows launcher can carry
+ * its version flag. `py -3` is how a Windows box usually reaches Python at
+ * all: `python3` is rarely on PATH there, and a bare `python` may be the App
+ * Execution Alias stub that opens the Microsoft Store instead of running
+ * anything.
+ */
+function interpreterCandidates() {
+  const out = [];
+  if (process.env.CTS_DOC2MD_PYTHON) out.push({ bin: process.env.CTS_DOC2MD_PYTHON, args: [] });
+  // The tool's own venv, created by `doc2md install-converter`. First because
+  // it is the only one this tool controls: telling people to `pip install`
+  // into the system interpreter is how a token-saving CLI ends up owning a
+  // break in someone else's project.
+  out.push({ bin: managedPython(), args: [] });
+  if (IS_WINDOWS) {
+    out.push(
+      { bin: path.join(os.homedir(), '.local', 'share', 'uv', 'tools', 'markitdown', 'Scripts', 'python.exe'), args: [] },
+      { bin: 'py', args: ['-3'] },
+      { bin: 'python', args: [] },
+    );
+  } else {
+    out.push(
+      { bin: path.join(os.homedir(), '.local', 'share', 'uv', 'tools', 'markitdown', 'bin', 'python'), args: [] },
+      { bin: path.join(os.homedir(), '.local', 'bin', 'markitdown-python'), args: [] },
+      { bin: 'python3', args: [] },
+      { bin: 'python', args: [] },
+    );
+  }
+  return out;
+}
+
 let interpreterCache;
 function findInterpreter() {
   if (interpreterCache !== undefined) return interpreterCache;
-  const candidates = [];
-  if (process.env.CTS_DOC2MD_PYTHON) candidates.push(process.env.CTS_DOC2MD_PYTHON);
-  candidates.push(
-    // The tool's own venv, created by `doc2md install-converter`. First
-    // because it is the only one this tool controls: telling people to
-    // `pip install` into the system interpreter is how a token-saving CLI
-    // ends up owning a break in someone else's project.
-    managedPython(),
-    path.join(os.homedir(), '.local', 'share', 'uv', 'tools', 'markitdown', 'bin', 'python'),
-    path.join(os.homedir(), '.local', 'bin', 'markitdown-python'),
-    'python3',
-    'python',
-  );
-  for (const bin of candidates) {
+  for (const { bin, args } of interpreterCandidates()) {
     try {
-      const probe = spawnSync(bin, ['-c', PROBE], { timeout: 20_000, stdio: 'ignore' });
+      const probe = spawnSync(bin, [...args, '-c', PROBE], {
+        timeout: 20_000,
+        stdio: 'ignore',
+        windowsHide: true,
+      });
       if (probe.status === 0) {
-        interpreterCache = bin;
-        return bin;
+        // Only a bare interpreter is cached as a string; the launcher form
+        // keeps its flag, since dropping it would run the wrong Python.
+        interpreterCache = args.length ? { bin, args } : bin;
+        return interpreterCache;
       }
     } catch { /* candidate unusable, try the next */ }
   }
@@ -262,6 +289,11 @@ function findInterpreter() {
   return null;
 }
 
+/** Split a `findInterpreter()` result into the pair spawnSync wants. */
+function interpreterParts(found) {
+  return typeof found === 'string' ? { bin: found, args: [] } : found;
+}
+
 const CONVERTER = path.join(__dirname, '..', 'presets', 'doc2md', 'convert.py');
 
 /** Path to the interpreter inside the venv this tool manages. */
@@ -295,18 +327,33 @@ const EDIT_LIBS = ['python-pptx', 'python-docx', 'openpyxl'];
  * 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])'], {
+  const candidates = IS_WINDOWS
+    ? [
+      // The launcher first, asked for each version in turn: it knows about
+      // installs that never touched PATH, which is the normal case on
+      // Windows.
+      { bin: 'py', args: ['-3.14'] }, { bin: 'py', args: ['-3.13'] },
+      { bin: 'py', args: ['-3.12'] }, { bin: 'py', args: ['-3.11'] },
+      { bin: 'py', args: ['-3.10'] }, { bin: 'py', args: ['-3'] },
+      { bin: 'python', args: [] },
+    ]
+    : [
+      { bin: 'python3.14', args: [] }, { bin: 'python3.13', args: [] },
+      { bin: 'python3.12', args: [] }, { bin: 'python3.11', args: [] },
+      { bin: 'python3.10', args: [] },
+      { bin: 'python3', args: [] }, { bin: 'python', args: [] },
+    ];
+  for (const { bin, args } of candidates) {
+    const r = spawnSync(bin, [...args, '-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], {
       encoding: 'utf8',
       timeout: 20_000,
+      windowsHide: true,
     });
     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}` };
+    if (major > 3 || (major === 3 && minor >= 10)) {
+      return { bin, args, version: `python ${major}.${minor}` };
+    }
   }
   return null;
 }
@@ -332,7 +379,11 @@ function installConverter({ onProgress = () => {} } = {}) {
       };
     }
     onProgress(`creating ${venv} (${base.version})`);
-    const r = spawnSync(base.bin, ['-m', 'venv', venv], { encoding: 'utf8', timeout: 180_000 });
+    const r = spawnSync(base.bin, [...(base.args || []), '-m', 'venv', venv], {
+      encoding: 'utf8',
+      timeout: 180_000,
+      windowsHide: true,
+    });
     if (r.status !== 0) {
       return { ok: false, reason: 'no-python', detail: (r.stderr || 'venv creation failed').slice(0, 300) };
     }
@@ -342,6 +393,7 @@ function installConverter({ onProgress = () => {} } = {}) {
   const install = spawnSync(target, ['-m', 'pip', 'install', '--quiet', MARKITDOWN_SPEC, ...EDIT_LIBS], {
     encoding: 'utf8',
     timeout: 900_000,
+    windowsHide: true,
   });
   if (install.status !== 0) {
     return { ok: false, reason: 'pip-failed', detail: (install.stderr || '').slice(0, 400) };
@@ -349,7 +401,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', PROBE], { timeout: 60_000, stdio: 'ignore' });
+  const probe = spawnSync(target, ['-c', PROBE], { timeout: 60_000, stdio: 'ignore', windowsHide: true });
   if (probe.status !== 0) {
     return { ok: false, reason: 'import-failed', detail: 'installed, but markitdown does not import' };
   }
@@ -361,8 +413,8 @@ function installConverter({ onProgress = () => {} } = {}) {
 /**
  * Convert one file. Returns `{ ok: true, cacheFile, meta }`, or
  * `{ ok: false, reason, detail }` where reason is one of:
- *   no-markitdown | python-too-old | no-figparser | too-large | sensitive |
- *   unsafe-archive | no-text | convert-failed | timeout
+ *   no-markitdown | python-too-old | no-figparser | encrypted | 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.
@@ -446,10 +498,12 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   }
   if (!python) return { ok: false, reason: 'no-markitdown' };
 
-  const run = spawnSync(python, [converter, filePath], {
+  const py = interpreterParts(python);
+  const run = spawnSync(py.bin, [...py.args, converter, filePath], {
     encoding: 'utf8',
     timeout: CONVERT_TIMEOUT_MS,
     maxBuffer: MAX_MARKDOWN_BYTES * 4,
+    windowsHide: true,
   });
   if (run.error && run.error.code === 'ETIMEDOUT') return { ok: false, reason: 'timeout' };
   if (run.status !== 0) {
@@ -522,6 +576,9 @@ function ensureConverterInstalled({ waitMs = 15_000 } = {}) {
       const child = spawn(process.execPath, [cli, 'doc2md', 'install-converter'], {
         detached: true,
         stdio: 'ignore',
+        // Without this Windows pops a console window for the install, in the
+        // middle of someone's prompt.
+        windowsHide: true,
       });
       child.unref();
     } catch {
@@ -623,6 +680,13 @@ function decideForRead(context, opts = {}) {
         + `  진행 상황: ${INSTALL_HINT} 를 직접 실행하면 설치 로그를 볼 수 있습니다.`,
     };
   }
+  if (result.reason === 'encrypted') {
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 는 암호가 걸린 문서라 변환하지 못했습니다. `
+        + '사용자에게 암호를 푼 사본을 요청하십시오. 이 도구는 암호를 묻거나 저장하지 않습니다.',
+    };
+  }
   if (result.reason === 'python-too-old') {
     if (noticeAlreadyShown()) return null;
     markNoticeShown();
@@ -753,6 +817,10 @@ function contextForPrompt(payload, opts = {}) {
       lines.push(lang === 'ko'
         ? `  ${name}: 변환기를 설치하는 중입니다(첫 실행에만 걸립니다). 설치가 끝나면 다음 요청부터 자동 변환됩니다.`
         : `  ${name}: the converter is installing now (first run only). It will convert automatically from the next request.`);
+    } else if (result.reason === 'encrypted') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: 암호가 걸린 문서입니다. 암호를 푼 사본을 달라고 사용자에게 요청하십시오.`
+        : `  ${name}: the document is password-protected. Ask the user for an unlocked copy.`);
     } else if (result.reason === 'python-too-old') {
       lines.push(lang === 'ko'
         ? `  ${name}: 변환기가 Python 3.10 이상을 요구하는데 PATH 에 없습니다(macOS 기본은 3.9). \`brew install python\` 후 다시 시도하도록 사용자에게 안내하십시오.`
@@ -888,6 +956,8 @@ module.exports = {
   installConverter,
   ensureConverterInstalled,
   findVenvBase,
+  interpreterCandidates,
+  interpreterParts,
   clearNotice,
   cacheDir,
   cachePathFor,

package/src/fig2md.cjs

@@ -28,7 +28,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
-const FIG_PARSER_SPEC = 'openfig-core@^0.4.1';
+// `0.4.x` rather than `^0.4.1` on purpose: the Windows install goes through
+// cmd.exe, where `^` is the escape character and would be eaten before npm
+// ever saw it. The range is the same one caret means for a 0.x package.
+const FIG_PARSER_SPEC = 'openfig-core@0.4.x';
 
 /** Where the on-demand parser install lives, under the tool's state dir. */
 function managedFigDir(userDataDir) {
@@ -56,10 +59,16 @@ function installFigParser(userDataDir, { onProgress = () => {} } = {}) {
     fs.writeFileSync(pkgJson, JSON.stringify({ name: 'doc2md-fig', private: true }) + '\n');
   }
   onProgress(`installing ${FIG_PARSER_SPEC}`);
-  const r = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', FIG_PARSER_SPEC], {
+  // npm on Windows is npm.cmd, which spawnSync cannot execute directly — it
+  // needs the shell. Elsewhere the shell is avoided, since the package spec
+  // would then go through shell quoting for no benefit.
+  const isWindows = process.platform === 'win32';
+  const r = spawnSync(isWindows ? 'npm.cmd' : 'npm', ['install', '--no-audit', '--no-fund', '--silent', FIG_PARSER_SPEC], {
     cwd: dir,
     encoding: 'utf8',
     timeout: 300_000,
+    windowsHide: true,
+    shell: isWindows,
   });
   if (r.status !== 0) {
     return { ok: false, reason: 'npm-failed', detail: (r.stderr || '').slice(0, 400) };