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.
- docuhand-0.1.0/.github/workflows/ci.yml +30 -0
- docuhand-0.1.0/.gitignore +218 -0
- docuhand-0.1.0/CHANGELOG.md +50 -0
- docuhand-0.1.0/LICENSE +21 -0
- docuhand-0.1.0/PKG-INFO +223 -0
- docuhand-0.1.0/README.md +211 -0
- docuhand-0.1.0/THREAT-MODEL.md +158 -0
- docuhand-0.1.0/_verify/.github/workflows/ci.yml +30 -0
- docuhand-0.1.0/_verify/.gitignore +218 -0
- docuhand-0.1.0/_verify/CHANGELOG.md +50 -0
- docuhand-0.1.0/_verify/LICENSE +21 -0
- docuhand-0.1.0/_verify/README.md +211 -0
- docuhand-0.1.0/_verify/THREAT-MODEL.md +158 -0
- docuhand-0.1.0/_verify/docs/pitfalls.md +275 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_01.doc +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_01.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_02.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_03.doc +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_03.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_04.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_05.doc +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_05.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_06.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_07.doc +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_07.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_08.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_09.doc +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_09.docx +0 -0
- docuhand-0.1.0/_verify/examples/convert-demo/mixed_demo_10.docx +0 -0
- docuhand-0.1.0/_verify/examples/demo-files/DocuHand_Demo.doc +0 -0
- docuhand-0.1.0/_verify/examples/demo-files/DocuHand_Demo.docx +0 -0
- docuhand-0.1.0/_verify/examples/hermes-config.json +8 -0
- docuhand-0.1.0/_verify/pyproject.toml +41 -0
- docuhand-0.1.0/_verify/scripts/check_word.ps1 +8 -0
- docuhand-0.1.0/_verify/scripts/make_demo_docs.py +67 -0
- docuhand-0.1.0/_verify/scripts/make_mixed_dir.py +55 -0
- docuhand-0.1.0/_verify/src/docuhand/__init__.py +3 -0
- docuhand-0.1.0/_verify/src/docuhand/__main__.py +4 -0
- docuhand-0.1.0/_verify/src/docuhand/_compat.py +28 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/__init__.py +38 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/com_thread.py +88 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/com_utils.py +56 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/container_guard.py +166 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/convert_plan.py +43 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/edit_plan.py +71 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/extraction.py +175 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/live_edit.py +265 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/merge_plan.py +58 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/office_app.py +828 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/pdf_plan.py +49 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/template_plan.py +107 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/templating.py +316 -0
- docuhand-0.1.0/_verify/src/docuhand/engine/wd_constants.py +23 -0
- docuhand-0.1.0/_verify/src/docuhand/errors.py +202 -0
- docuhand-0.1.0/_verify/src/docuhand/safety/__init__.py +11 -0
- docuhand-0.1.0/_verify/src/docuhand/safety/allowlist.py +41 -0
- docuhand-0.1.0/_verify/src/docuhand/safety/audit.py +52 -0
- docuhand-0.1.0/_verify/src/docuhand/safety/policy.py +29 -0
- docuhand-0.1.0/_verify/src/docuhand/server.py +221 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/__init__.py +7 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/convert.py +228 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/edit_open.py +92 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/export_pdf.py +92 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/extract.py +63 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/fill_template.py +115 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/inspect.py +57 -0
- docuhand-0.1.0/_verify/src/docuhand/tools/merge.py +143 -0
- docuhand-0.1.0/_verify/tests/__init__.py +0 -0
- docuhand-0.1.0/_verify/tests/conftest.py +33 -0
- docuhand-0.1.0/_verify/tests/integration/__init__.py +0 -0
- docuhand-0.1.0/_verify/tests/integration/test_convert_e2e.py +229 -0
- docuhand-0.1.0/_verify/tests/integration/test_e2e_mcp.py +94 -0
- docuhand-0.1.0/_verify/tests/integration/test_tools_e2e.py +271 -0
- docuhand-0.1.0/_verify/tests/unit/__init__.py +0 -0
- docuhand-0.1.0/_verify/tests/unit/helpers_cfb.py +123 -0
- docuhand-0.1.0/_verify/tests/unit/test_container_guard.py +124 -0
- docuhand-0.1.0/_verify/tests/unit/test_convert_plan.py +84 -0
- docuhand-0.1.0/_verify/tests/unit/test_detect_encryption.py +97 -0
- docuhand-0.1.0/_verify/tests/unit/test_live_edit_attach.py +116 -0
- docuhand-0.1.0/_verify/tests/unit/test_new_tools.py +148 -0
- docuhand-0.1.0/_verify/tests/unit/test_pure.py +95 -0
- docuhand-0.1.0/_verify/uv.lock +726 -0
- docuhand-0.1.0/docs/pitfalls.md +276 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_01.doc +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_01.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_02.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_03.doc +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_03.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_04.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_05.doc +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_05.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_06.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_07.doc +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_07.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_08.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_09.doc +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_09.docx +0 -0
- docuhand-0.1.0/examples/convert-demo/mixed_demo_10.docx +0 -0
- docuhand-0.1.0/examples/demo-files/DocuHand_Demo.doc +0 -0
- docuhand-0.1.0/examples/demo-files/DocuHand_Demo.docx +0 -0
- docuhand-0.1.0/examples/hermes-config.json +8 -0
- docuhand-0.1.0/pyproject.toml +41 -0
- docuhand-0.1.0/scripts/check_word.ps1 +8 -0
- docuhand-0.1.0/scripts/make_demo_docs.py +67 -0
- docuhand-0.1.0/scripts/make_mixed_dir.py +55 -0
- docuhand-0.1.0/src/docuhand/__init__.py +3 -0
- docuhand-0.1.0/src/docuhand/__main__.py +4 -0
- docuhand-0.1.0/src/docuhand/_compat.py +28 -0
- docuhand-0.1.0/src/docuhand/engine/__init__.py +38 -0
- docuhand-0.1.0/src/docuhand/engine/com_thread.py +88 -0
- docuhand-0.1.0/src/docuhand/engine/com_utils.py +56 -0
- docuhand-0.1.0/src/docuhand/engine/container_guard.py +166 -0
- docuhand-0.1.0/src/docuhand/engine/convert_plan.py +43 -0
- docuhand-0.1.0/src/docuhand/engine/edit_plan.py +71 -0
- docuhand-0.1.0/src/docuhand/engine/extraction.py +175 -0
- docuhand-0.1.0/src/docuhand/engine/live_edit.py +265 -0
- docuhand-0.1.0/src/docuhand/engine/merge_plan.py +58 -0
- docuhand-0.1.0/src/docuhand/engine/office_app.py +828 -0
- docuhand-0.1.0/src/docuhand/engine/pdf_plan.py +49 -0
- docuhand-0.1.0/src/docuhand/engine/template_plan.py +107 -0
- docuhand-0.1.0/src/docuhand/engine/templating.py +316 -0
- docuhand-0.1.0/src/docuhand/engine/wd_constants.py +23 -0
- docuhand-0.1.0/src/docuhand/errors.py +202 -0
- docuhand-0.1.0/src/docuhand/safety/__init__.py +11 -0
- docuhand-0.1.0/src/docuhand/safety/allowlist.py +41 -0
- docuhand-0.1.0/src/docuhand/safety/audit.py +52 -0
- docuhand-0.1.0/src/docuhand/safety/policy.py +29 -0
- docuhand-0.1.0/src/docuhand/server.py +221 -0
- docuhand-0.1.0/src/docuhand/tools/__init__.py +7 -0
- docuhand-0.1.0/src/docuhand/tools/convert.py +228 -0
- docuhand-0.1.0/src/docuhand/tools/edit_open.py +92 -0
- docuhand-0.1.0/src/docuhand/tools/export_pdf.py +92 -0
- docuhand-0.1.0/src/docuhand/tools/extract.py +63 -0
- docuhand-0.1.0/src/docuhand/tools/fill_template.py +115 -0
- docuhand-0.1.0/src/docuhand/tools/inspect.py +57 -0
- docuhand-0.1.0/src/docuhand/tools/merge.py +143 -0
- docuhand-0.1.0/tests/__init__.py +0 -0
- docuhand-0.1.0/tests/conftest.py +33 -0
- docuhand-0.1.0/tests/integration/__init__.py +0 -0
- docuhand-0.1.0/tests/integration/test_convert_e2e.py +229 -0
- docuhand-0.1.0/tests/integration/test_e2e_mcp.py +94 -0
- docuhand-0.1.0/tests/integration/test_tools_e2e.py +271 -0
- docuhand-0.1.0/tests/unit/__init__.py +0 -0
- docuhand-0.1.0/tests/unit/helpers_cfb.py +123 -0
- docuhand-0.1.0/tests/unit/test_container_guard.py +124 -0
- docuhand-0.1.0/tests/unit/test_convert_plan.py +84 -0
- docuhand-0.1.0/tests/unit/test_detect_encryption.py +97 -0
- docuhand-0.1.0/tests/unit/test_live_edit_attach.py +116 -0
- docuhand-0.1.0/tests/unit/test_new_tools.py +148 -0
- docuhand-0.1.0/tests/unit/test_pure.py +95 -0
- 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.
|
docuhand-0.1.0/PKG-INFO
ADDED
|
@@ -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.
|