docuhand 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. docuhand-0.1.0/.github/workflows/ci.yml +30 -0
  2. docuhand-0.1.0/.gitignore +218 -0
  3. docuhand-0.1.0/CHANGELOG.md +50 -0
  4. docuhand-0.1.0/LICENSE +21 -0
  5. docuhand-0.1.0/PKG-INFO +223 -0
  6. docuhand-0.1.0/README.md +211 -0
  7. docuhand-0.1.0/THREAT-MODEL.md +158 -0
  8. docuhand-0.1.0/_verify/.github/workflows/ci.yml +30 -0
  9. docuhand-0.1.0/_verify/.gitignore +218 -0
  10. docuhand-0.1.0/_verify/CHANGELOG.md +50 -0
  11. docuhand-0.1.0/_verify/LICENSE +21 -0
  12. docuhand-0.1.0/_verify/README.md +211 -0
  13. docuhand-0.1.0/_verify/THREAT-MODEL.md +158 -0
  14. docuhand-0.1.0/_verify/docs/pitfalls.md +275 -0
  15. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_01.doc +0 -0
  16. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_01.docx +0 -0
  17. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_02.docx +0 -0
  18. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_03.doc +0 -0
  19. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_03.docx +0 -0
  20. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_04.docx +0 -0
  21. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_05.doc +0 -0
  22. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_05.docx +0 -0
  23. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_06.docx +0 -0
  24. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_07.doc +0 -0
  25. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_07.docx +0 -0
  26. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_08.docx +0 -0
  27. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_09.doc +0 -0
  28. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_09.docx +0 -0
  29. docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_10.docx +0 -0
  30. docuhand-0.1.0/_verify/examples/demo-files/DocuHand_Demo.doc +0 -0
  31. docuhand-0.1.0/_verify/examples/demo-files/DocuHand_Demo.docx +0 -0
  32. docuhand-0.1.0/_verify/examples/hermes-config.json +8 -0
  33. docuhand-0.1.0/_verify/pyproject.toml +41 -0
  34. docuhand-0.1.0/_verify/scripts/check_word.ps1 +8 -0
  35. docuhand-0.1.0/_verify/scripts/make_demo_docs.py +67 -0
  36. docuhand-0.1.0/_verify/scripts/make_mixed_dir.py +55 -0
  37. docuhand-0.1.0/_verify/src/docuhand/__init__.py +3 -0
  38. docuhand-0.1.0/_verify/src/docuhand/__main__.py +4 -0
  39. docuhand-0.1.0/_verify/src/docuhand/_compat.py +28 -0
  40. docuhand-0.1.0/_verify/src/docuhand/engine/__init__.py +38 -0
  41. docuhand-0.1.0/_verify/src/docuhand/engine/com_thread.py +88 -0
  42. docuhand-0.1.0/_verify/src/docuhand/engine/com_utils.py +56 -0
  43. docuhand-0.1.0/_verify/src/docuhand/engine/container_guard.py +166 -0
  44. docuhand-0.1.0/_verify/src/docuhand/engine/convert_plan.py +43 -0
  45. docuhand-0.1.0/_verify/src/docuhand/engine/edit_plan.py +71 -0
  46. docuhand-0.1.0/_verify/src/docuhand/engine/extraction.py +175 -0
  47. docuhand-0.1.0/_verify/src/docuhand/engine/live_edit.py +265 -0
  48. docuhand-0.1.0/_verify/src/docuhand/engine/merge_plan.py +58 -0
  49. docuhand-0.1.0/_verify/src/docuhand/engine/office_app.py +828 -0
  50. docuhand-0.1.0/_verify/src/docuhand/engine/pdf_plan.py +49 -0
  51. docuhand-0.1.0/_verify/src/docuhand/engine/template_plan.py +107 -0
  52. docuhand-0.1.0/_verify/src/docuhand/engine/templating.py +316 -0
  53. docuhand-0.1.0/_verify/src/docuhand/engine/wd_constants.py +23 -0
  54. docuhand-0.1.0/_verify/src/docuhand/errors.py +202 -0
  55. docuhand-0.1.0/_verify/src/docuhand/safety/__init__.py +11 -0
  56. docuhand-0.1.0/_verify/src/docuhand/safety/allowlist.py +41 -0
  57. docuhand-0.1.0/_verify/src/docuhand/safety/audit.py +52 -0
  58. docuhand-0.1.0/_verify/src/docuhand/safety/policy.py +29 -0
  59. docuhand-0.1.0/_verify/src/docuhand/server.py +221 -0
  60. docuhand-0.1.0/_verify/src/docuhand/tools/__init__.py +7 -0
  61. docuhand-0.1.0/_verify/src/docuhand/tools/convert.py +228 -0
  62. docuhand-0.1.0/_verify/src/docuhand/tools/edit_open.py +92 -0
  63. docuhand-0.1.0/_verify/src/docuhand/tools/export_pdf.py +92 -0
  64. docuhand-0.1.0/_verify/src/docuhand/tools/extract.py +63 -0
  65. docuhand-0.1.0/_verify/src/docuhand/tools/fill_template.py +115 -0
  66. docuhand-0.1.0/_verify/src/docuhand/tools/inspect.py +57 -0
  67. docuhand-0.1.0/_verify/src/docuhand/tools/merge.py +143 -0
  68. docuhand-0.1.0/_verify/tests/__init__.py +0 -0
  69. docuhand-0.1.0/_verify/tests/conftest.py +33 -0
  70. docuhand-0.1.0/_verify/tests/integration/__init__.py +0 -0
  71. docuhand-0.1.0/_verify/tests/integration/test_convert_e2e.py +229 -0
  72. docuhand-0.1.0/_verify/tests/integration/test_e2e_mcp.py +94 -0
  73. docuhand-0.1.0/_verify/tests/integration/test_tools_e2e.py +271 -0
  74. docuhand-0.1.0/_verify/tests/unit/__init__.py +0 -0
  75. docuhand-0.1.0/_verify/tests/unit/helpers_cfb.py +123 -0
  76. docuhand-0.1.0/_verify/tests/unit/test_container_guard.py +124 -0
  77. docuhand-0.1.0/_verify/tests/unit/test_convert_plan.py +84 -0
  78. docuhand-0.1.0/_verify/tests/unit/test_detect_encryption.py +97 -0
  79. docuhand-0.1.0/_verify/tests/unit/test_live_edit_attach.py +116 -0
  80. docuhand-0.1.0/_verify/tests/unit/test_new_tools.py +148 -0
  81. docuhand-0.1.0/_verify/tests/unit/test_pure.py +95 -0
  82. docuhand-0.1.0/_verify/uv.lock +726 -0
  83. docuhand-0.1.0/docs/pitfalls.md +276 -0
  84. docuhand-0.1.0/examples/convert-demo/mixed_demo_01.doc +0 -0
  85. docuhand-0.1.0/examples/convert-demo/mixed_demo_01.docx +0 -0
  86. docuhand-0.1.0/examples/convert-demo/mixed_demo_02.docx +0 -0
  87. docuhand-0.1.0/examples/convert-demo/mixed_demo_03.doc +0 -0
  88. docuhand-0.1.0/examples/convert-demo/mixed_demo_03.docx +0 -0
  89. docuhand-0.1.0/examples/convert-demo/mixed_demo_04.docx +0 -0
  90. docuhand-0.1.0/examples/convert-demo/mixed_demo_05.doc +0 -0
  91. docuhand-0.1.0/examples/convert-demo/mixed_demo_05.docx +0 -0
  92. docuhand-0.1.0/examples/convert-demo/mixed_demo_06.docx +0 -0
  93. docuhand-0.1.0/examples/convert-demo/mixed_demo_07.doc +0 -0
  94. docuhand-0.1.0/examples/convert-demo/mixed_demo_07.docx +0 -0
  95. docuhand-0.1.0/examples/convert-demo/mixed_demo_08.docx +0 -0
  96. docuhand-0.1.0/examples/convert-demo/mixed_demo_09.doc +0 -0
  97. docuhand-0.1.0/examples/convert-demo/mixed_demo_09.docx +0 -0
  98. docuhand-0.1.0/examples/convert-demo/mixed_demo_10.docx +0 -0
  99. docuhand-0.1.0/examples/demo-files/DocuHand_Demo.doc +0 -0
  100. docuhand-0.1.0/examples/demo-files/DocuHand_Demo.docx +0 -0
  101. docuhand-0.1.0/examples/hermes-config.json +8 -0
  102. docuhand-0.1.0/pyproject.toml +41 -0
  103. docuhand-0.1.0/scripts/check_word.ps1 +8 -0
  104. docuhand-0.1.0/scripts/make_demo_docs.py +67 -0
  105. docuhand-0.1.0/scripts/make_mixed_dir.py +55 -0
  106. docuhand-0.1.0/src/docuhand/__init__.py +3 -0
  107. docuhand-0.1.0/src/docuhand/__main__.py +4 -0
  108. docuhand-0.1.0/src/docuhand/_compat.py +28 -0
  109. docuhand-0.1.0/src/docuhand/engine/__init__.py +38 -0
  110. docuhand-0.1.0/src/docuhand/engine/com_thread.py +88 -0
  111. docuhand-0.1.0/src/docuhand/engine/com_utils.py +56 -0
  112. docuhand-0.1.0/src/docuhand/engine/container_guard.py +166 -0
  113. docuhand-0.1.0/src/docuhand/engine/convert_plan.py +43 -0
  114. docuhand-0.1.0/src/docuhand/engine/edit_plan.py +71 -0
  115. docuhand-0.1.0/src/docuhand/engine/extraction.py +175 -0
  116. docuhand-0.1.0/src/docuhand/engine/live_edit.py +265 -0
  117. docuhand-0.1.0/src/docuhand/engine/merge_plan.py +58 -0
  118. docuhand-0.1.0/src/docuhand/engine/office_app.py +828 -0
  119. docuhand-0.1.0/src/docuhand/engine/pdf_plan.py +49 -0
  120. docuhand-0.1.0/src/docuhand/engine/template_plan.py +107 -0
  121. docuhand-0.1.0/src/docuhand/engine/templating.py +316 -0
  122. docuhand-0.1.0/src/docuhand/engine/wd_constants.py +23 -0
  123. docuhand-0.1.0/src/docuhand/errors.py +202 -0
  124. docuhand-0.1.0/src/docuhand/safety/__init__.py +11 -0
  125. docuhand-0.1.0/src/docuhand/safety/allowlist.py +41 -0
  126. docuhand-0.1.0/src/docuhand/safety/audit.py +52 -0
  127. docuhand-0.1.0/src/docuhand/safety/policy.py +29 -0
  128. docuhand-0.1.0/src/docuhand/server.py +221 -0
  129. docuhand-0.1.0/src/docuhand/tools/__init__.py +7 -0
  130. docuhand-0.1.0/src/docuhand/tools/convert.py +228 -0
  131. docuhand-0.1.0/src/docuhand/tools/edit_open.py +92 -0
  132. docuhand-0.1.0/src/docuhand/tools/export_pdf.py +92 -0
  133. docuhand-0.1.0/src/docuhand/tools/extract.py +63 -0
  134. docuhand-0.1.0/src/docuhand/tools/fill_template.py +115 -0
  135. docuhand-0.1.0/src/docuhand/tools/inspect.py +57 -0
  136. docuhand-0.1.0/src/docuhand/tools/merge.py +143 -0
  137. docuhand-0.1.0/tests/__init__.py +0 -0
  138. docuhand-0.1.0/tests/conftest.py +33 -0
  139. docuhand-0.1.0/tests/integration/__init__.py +0 -0
  140. docuhand-0.1.0/tests/integration/test_convert_e2e.py +229 -0
  141. docuhand-0.1.0/tests/integration/test_e2e_mcp.py +94 -0
  142. docuhand-0.1.0/tests/integration/test_tools_e2e.py +271 -0
  143. docuhand-0.1.0/tests/unit/__init__.py +0 -0
  144. docuhand-0.1.0/tests/unit/helpers_cfb.py +123 -0
  145. docuhand-0.1.0/tests/unit/test_container_guard.py +124 -0
  146. docuhand-0.1.0/tests/unit/test_convert_plan.py +84 -0
  147. docuhand-0.1.0/tests/unit/test_detect_encryption.py +97 -0
  148. docuhand-0.1.0/tests/unit/test_live_edit_attach.py +116 -0
  149. docuhand-0.1.0/tests/unit/test_new_tools.py +148 -0
  150. docuhand-0.1.0/tests/unit/test_pure.py +95 -0
  151. docuhand-0.1.0/uv.lock +726 -0
@@ -0,0 +1,30 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ # Windows is the product's only platform: the dependency set includes
11
+ # pywin32 (Windows-only wheels — an ubuntu runner cannot even `uv sync`)
12
+ # and the tools under
13
+ # test drive Word/WPS via COM. Unit tests exercise pure logic; COM
14
+ # integration tests (`-m com`) drive real engines and stay on the
15
+ # maintainer's machine (docs/pitfalls.md).
16
+ runs-on: windows-latest
17
+ strategy:
18
+ matrix:
19
+ python-version: ["3.12", "3.13"]
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - uses: astral-sh/setup-uv@v5
23
+ with:
24
+ python-version: ${{ matrix.python-version }}
25
+ - name: Run unit tests
26
+ run: uv run pytest tests/unit -q
27
+ - name: Build distributions
28
+ run: uv build
29
+ - name: Check distributions
30
+ run: uv run --with twine python -m twine check dist/*
@@ -0,0 +1,218 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ # Pipfile.lock
96
+
97
+ # UV
98
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ # uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ # poetry.lock
109
+ # poetry.toml
110
+
111
+ # pdm
112
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
114
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
115
+ # pdm.lock
116
+ # pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # pixi
121
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
122
+ # pixi.lock
123
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
124
+ # in the .venv directory. It is recommended not to include this directory in version control.
125
+ .pixi
126
+
127
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
128
+ __pypackages__/
129
+
130
+ # Celery stuff
131
+ celerybeat-schedule
132
+ celerybeat.pid
133
+
134
+ # Redis
135
+ *.rdb
136
+ *.aof
137
+ *.pid
138
+
139
+ # RabbitMQ
140
+ mnesia/
141
+ rabbitmq/
142
+ rabbitmq-data/
143
+
144
+ # ActiveMQ
145
+ activemq-data/
146
+
147
+ # SageMath parsed files
148
+ *.sage.py
149
+
150
+ # Environments
151
+ .env
152
+ .envrc
153
+ .venv
154
+ env/
155
+ venv/
156
+ ENV/
157
+ env.bak/
158
+ venv.bak/
159
+
160
+ # Spyder project settings
161
+ .spyderproject
162
+ .spyproject
163
+
164
+ # Rope project settings
165
+ .ropeproject
166
+
167
+ # mkdocs documentation
168
+ /site
169
+
170
+ # mypy
171
+ .mypy_cache/
172
+ .dmypy.json
173
+ dmypy.json
174
+
175
+ # Pyre type checker
176
+ .pyre/
177
+
178
+ # pytype static type analyzer
179
+ .pytype/
180
+
181
+ # Cython debug symbols
182
+ cython_debug/
183
+
184
+ # PyCharm
185
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
186
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
187
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
188
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
189
+ # .idea/
190
+
191
+ # Abstra
192
+ # Abstra is an AI-powered process automation framework.
193
+ # Ignore directories containing user credentials, local state, and settings.
194
+ # Learn more at https://abstra.io/docs
195
+ .abstra/
196
+
197
+ # Visual Studio Code
198
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
199
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
200
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
201
+ # you could uncomment the following to ignore the entire vscode folder
202
+ # .vscode/
203
+ # Temporary file for partial code execution
204
+ tempCodeRunnerFile.py
205
+
206
+ # Ruff stuff:
207
+ .ruff_cache/
208
+
209
+ # PyPI configuration file
210
+ .pypirc
211
+
212
+ # Marimo
213
+ marimo/_static/
214
+ marimo/_lsp/
215
+ __marimo__/
216
+
217
+ # Streamlit
218
+ .streamlit/secrets.toml
@@ -0,0 +1,50 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ The format follows [Keep a Changelog](https://keepachangelog.com/) (loosely);
5
+ versions follow [Semantic Versioning](https://semver.org/) (pre-1.0: the
6
+ minor slot is the API surface).
7
+
8
+ ## [0.1.0] - 2026-11-17
9
+
10
+ First public release. The complete v0.1 tool set:
11
+
12
+ ### Added
13
+ - `inspect_document` — pre-flight health check: true format vs extension,
14
+ lock state, page/word/paragraph counts, corruption & password detection,
15
+ protection mode, bookmarks, field codes.
16
+ - `convert_documents` — batch `.doc ↔ .docx` per directory; Word→WPS
17
+ automatic failover; per-file fault isolation; sources never deleted;
18
+ overwrite policy (`skip`/`overwrite`); optional output directory;
19
+ pre-COM container & encryption gates (no modal-dialog hangs).
20
+ - `fill_template` — bookmarks / `{{placeholders}}` / content controls in
21
+ `auto` mode; CJK font protection (`NameFarEast` re-assertion before and
22
+ after `SaveAs2`); leftover-placeholder scan; per-key fill report.
23
+ - `export_pdf` — PDF via `ExportAsFixedFormat` with a
24
+ `SaveAs(pdf)` fallback for older engines; page-range grammar
25
+ (`all` | `7` | `3-9`); `%PDF-` header verification.
26
+ - `extract_content` — `text` / `tables` (row-major JSON grids from legacy
27
+ `.doc`, merged cells keep the grid rectangular) / `outline` via
28
+ locale-independent outline levels.
29
+ - `edit_open_document` — attaches to the user's live Word/WPS instance,
30
+ resolves documents by path or window title, validates the whole operation
31
+ batch before any COM call, `save="ask"` default never writes disk.
32
+ - `merge_documents` — one template × N data rows with per-row fault
33
+ isolation; sanitized `{i}`/`{field}` output naming; collision-free targets.
34
+ - Safety layer: `DOCUHAND_ALLOWLIST` path allowlist, `DOCUHAND_READONLY`
35
+ global read-only mode, JSONL audit log (`DOCUHAND_AUDIT`,
36
+ `DOCUHAND_AUDIT_PATH`).
37
+ - Architecture: dedicated COM STA worker thread with serial queue and
38
+ timeout-abandon semantics; Word→WPS engine probe/failover; structured
39
+ errors (`error_code` / `human_message` / `llm_hint`); Chinese-Windows
40
+ UTF-8 stdio fix; pure-logic planning modules unit-tested in CI.
41
+ - Documentation: `docs/pitfalls.md` — 17 battle-tested pitfalls from
42
+ hands-on debugging on real Chinese-Windows machines.
43
+
44
+ ### Fixed
45
+ - `edit_open_document` no longer attaches to the wrong engine instance.
46
+ A stale zero-document registration left in the Running Object Table
47
+ (e.g. after a crashed engine) used to shadow the user's live instance,
48
+ producing a misleading `Document not found among the 0 open document(s)`.
49
+ The attach path now enumerates the ROT and prefers an instance that
50
+ actually holds open documents. See `docs/pitfalls.md` #17.
docuhand-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Frank Wang
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,223 @@
1
+ Metadata-Version: 2.5
2
+ Name: docuhand
3
+ Version: 0.1.0
4
+ Summary: Give your AI agent hands to operate real Word & WPS documents on Windows — an MCP server driving real Office apps via COM.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.12
8
+ Requires-Dist: mcp<2,>=1.2
9
+ Requires-Dist: olefile>=0.47
10
+ Requires-Dist: pywin32<312,>=306
11
+ Description-Content-Type: text/markdown
12
+
13
+ # DocuHand 🖐️
14
+
15
+ **Give your AI agent hands to operate real Word & WPS documents on Windows.**
16
+
17
+ DocuHand is a Model Context Protocol (MCP) server that lets AI agents
18
+ (Claude Desktop, Cursor, and any other MCP client) actually *drive* Microsoft
19
+ Word and WPS Office via COM — not just read docx XML, but automate the real
20
+ applications: legacy `.doc` binaries, documents currently open on screen,
21
+ and PDF export through the word processor's own layout engine.
22
+
23
+ Works on **both** Microsoft Word and WPS Office. When Word is absent or
24
+ crashes mid-batch, the WPS engine takes over transparently. (WPS support is
25
+ believed to be unique among Office MCP servers.)
26
+
27
+ ```bash
28
+ uvx docuhand serve
29
+ ```
30
+
31
+ Security posture: **zero network code** (audited; see
32
+ [THREAT-MODEL.md](THREAT-MODEL.md)): no telemetry, no update checks, a
33
+ local JSONL audit log, and an explicit non-goals section.
34
+
35
+ ## Why DocuHand exists
36
+
37
+ Most Office MCP servers are built on `python-docx`: they manipulate XML in
38
+ idealized files. Real-world documents are not idealized:
39
+
40
+ - 20-year-old `.doc` binaries that XML libraries cannot touch
41
+ - Files currently **open and locked** in Word/WPS right now
42
+ - WPS Office — Kingsoft reported **676 million** WPS Office monthly active
43
+ devices in June 2026, so the "default suite" problem is not a niche
44
+ - CJK fonts that silently reset when text is replaced (the `NameFarEast` trap)
45
+ - Password-protected and corrupt files that pop **modal dialogs** and hang
46
+ headless servers
47
+
48
+ DocuHand drives the real applications, hardened by hands-on debugging on
49
+ real Chinese-Windows machines. Every pitfall in
50
+ [docs/pitfalls.md](docs/pitfalls.md) cost real debugging time, and you get
51
+ them pre-solved.
52
+
53
+ ## Tools
54
+
55
+ | Tool | What it does |
56
+ |------|--------------|
57
+ | `inspect_document` | Pre-flight health check: real format vs extension, lock state, page/word counts, corruption & password detection, bookmarks, field codes |
58
+ | `convert_documents` | Batch `.doc ↔ .docx` for a whole directory in one call, Word→WPS failover, per-file fault isolation, sources never deleted |
59
+ | `fill_template` | Bookmarks / `{{placeholders}}` / content controls, CJK fonts protected through save |
60
+ | `export_pdf` | PDF via the real layout engine, optional page range |
61
+ | `extract_content` | Text / tables (as JSON grids) / heading outline from legacy `.doc` |
62
+ | `edit_open_document` | Edit a document the user **has open right now** — changes appear in their window |
63
+ | `merge_documents` | Mail-merge style batch generation: one template × N data rows |
64
+
65
+ Every tool returns structured JSON. Every error carries
66
+ `{error_code, human_message, llm_hint}`: errors are data the agent reads to
67
+ self-correct, not tracebacks it drowns in.
68
+
69
+ ## Quick start
70
+
71
+ Install from PyPI:
72
+
73
+ ```bash
74
+ # with pip
75
+ pip install docuhand
76
+
77
+ # or with uv (also gives you the `uvx docuhand serve` one-liner)
78
+ uv tool install docuhand
79
+ ```
80
+
81
+ Requirements: **Windows** with either Microsoft Word or WPS Office installed
82
+ (either one is enough; the engine probes `Word.Application` first, then
83
+ `KWPS.Application`, overridable with `DOCUHAND_ENGINE=wps|word`), and
84
+ **Python 3.12 or newer** (the package requires `>=3.12`; on older
85
+ interpreters pip reports `from versions: none`).
86
+
87
+ It runs with **your own user privileges**: no admin rights, no service
88
+ install, no daemon. It does not run on Linux or macOS: it drives the real
89
+ Office engine through COM.
90
+
91
+ **Test coverage:** the development machine has **WPS Office only, no
92
+ Microsoft Word**. Every end-to-end verification in this repository ran on
93
+ that machine; the Word-side code paths are the one thing not yet verified
94
+ against real Word. If you run on Word and hit a difference, please open an
95
+ issue, because that is exactly the gap worth closing.
96
+
97
+ Add to your MCP client (Claude Desktop example):
98
+
99
+ ```json
100
+ {
101
+ "mcpServers": {
102
+ "docuhand": {
103
+ "command": "docuhand",
104
+ "args": ["serve"]
105
+ }
106
+ }
107
+ }
108
+ ```
109
+
110
+ Then ask your agent: *"Convert every .doc in D:\\Reports to PDF"* — see
111
+ [Examples](#examples).
112
+
113
+ ## Examples
114
+
115
+ **Examples of what to ask your agent**
116
+
117
+ Batch conversion — one call converts the whole folder:
118
+
119
+ > "Convert every .doc file in D:\Reports to .docx"
120
+
121
+ Template fill with CJK font safety — layout and East-Asian fonts survive:
122
+
123
+ > "Fill D:\Templates\notice.docx with name=Zhang San, amount=426, save it to my desktop"
124
+
125
+ Edit a document that's open on screen — the agent works in the user's
126
+ live Word/WPS window:
127
+
128
+ > "In the contract I have open right now, replace every 2023 with 2024 — don't save yet"
129
+
130
+ Mail-merge batch:
131
+
132
+ > "Generate one offer letter per row in data.json from the offer.docx template"
133
+
134
+ A synthetic demo document lives in
135
+ [examples/demo-files/](examples/demo-files/) (generated by
136
+ `scripts/make_demo_docs.py`, no real/personal data), and
137
+ [examples/](examples/) has MCP client config snippets.
138
+
139
+ ## Security model (read before granting file access)
140
+
141
+ - **100% local execution** — your documents never leave your machine
142
+ - **No telemetry**, ever
143
+ - **Explicit path allowlist** — set `DOCUHAND_ALLOWLIST` to a
144
+ `os.pathsep`-separated list of directories; when unset, the fact that you
145
+ launched the server yourself is the consent
146
+ - **Read-only mode** — set `DOCUHAND_READONLY=1` to block every mutating
147
+ tool; only `inspect_document` / `extract_content` / `export_pdf` remain
148
+ - **JSONL audit log** — every operation is appended to
149
+ `%LOCALAPPDATA%\docuhand\audit.jsonl` (disable: `DOCUHAND_AUDIT=off`,
150
+ relocate: `DOCUHAND_AUDIT_PATH`)
151
+ - **Pre-COM container gates** — broken/encrypted files are rejected in pure
152
+ Python *before* the engine opens them, so a corrupt file can never pop a
153
+ modal dialog on your desktop or hang the server (the #1 killer of headless
154
+ Office automation)
155
+
156
+ Environment variables (`DOCUHAND_ENGINE`, `DOCUHAND_ALLOWLIST`,
157
+ `DOCUHAND_READONLY`, `DOCUHAND_AUDIT*`, `DOCUHAND_COM_TIMEOUT`) must be
158
+ declared in your MCP client's server config — hosts pass stdio servers a
159
+ filtered environment.
160
+
161
+ ## Why not just use Copilot in Word / WPS AI?
162
+
163
+ Those are copilots: they serve the *person sitting in front of the
164
+ document*, through a closed, human-driven interface with no public API.
165
+ DocuHand is ground crew: it serves *agents working unattended*, from batch
166
+ jobs at 3 AM to pipelines, on any MCP client. Different buyer, different mode of
167
+ operation.
168
+
169
+ **"Why operate legacy .doc files at all?"**
170
+ Nobody *chooses* legacy formats. Archives of millions of `.doc` files are locked
171
+ by compliance (retain-original requirements), ecosystem inertia (counterparties
172
+ still sending `.doc`), and sheer scale. Converting them *is* one of our tools.
173
+ Copilot can't touch them; python-docx can't either. Manual clerical work or
174
+ DocuHand: those are the options.
175
+
176
+ ## DocuHand vs. XML-level Office tools
177
+
178
+ | | python-docx based | DocuHand |
179
+ |---|---|---|
180
+ | Legacy `.doc` binaries | ❌ | ✅ (real app required) |
181
+ | Open/locked files | ❌ | ✅ `edit_open_document` |
182
+ | WPS Office | ❌ | ✅ dedicated engine |
183
+ | CJK font safety | ⚠️ n/a or silent corruption | ✅ hardened (`NameFarEast` re-assertion) |
184
+ | PDF fidelity | ⚠️ re-layout | ✅ print-engine export |
185
+ | Corrupt/password files | ⚠️ crash or hang | ✅ pre-COM gates, structured errors |
186
+
187
+ ## Architecture notes
188
+
189
+ The short version of the four decisions that make this survive real machines
190
+ (full rationale in [docs/pitfalls.md](docs/pitfalls.md)):
191
+
192
+ - **One dedicated STA thread** owns all COM: the asyncio event loop must
193
+ never touch COM directly (`RPC_E_WRONG_THREAD`), and one serial queue
194
+ means no WINWORD.EXE instance explosion. A stuck call times out and the
195
+ thread is abandoned wholesale.
196
+ - **Word → WPS failover**: an engine that dies mid-call is discarded and
197
+ the next one takes over; probe order is configurable.
198
+ - **Errors are structured data** for the calling agent, not stack traces.
199
+ - **Safety is registration-time middleware**, not "remember to check".
200
+
201
+ ## Roadmap
202
+
203
+ - v0.2: `track_changes`, `compare_documents`, protect/unprotect, Excel family
204
+ - Pro (separate, later): batch queue/concurrency, service mode, priority support
205
+
206
+ The free core stays free (MIT).
207
+
208
+ ## Development
209
+
210
+ ```bash
211
+ git clone <this repo> && cd docuhand
212
+ uv sync
213
+
214
+ # CI-safe unit tests (no Office needed)
215
+ uv run pytest tests/unit
216
+
217
+ # COM integration tests (local machine with Word/WPS only, never CI)
218
+ uv run pytest tests -m com
219
+ ```
220
+
221
+ ## License
222
+
223
+ MIT. Free core, forever. Pro is a separate commercial license, later.