winauto-cli 0.1.0__tar.gz

winauto_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wenqu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

winauto_cli-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: winauto-cli
+Version: 0.1.0
+Summary: A pragmatic Windows UI automation CLI built on top of pywinauto.
+Author: wenqu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yourname/winauto-cli
+Project-URL: Repository, https://github.com/yourname/winauto-cli
+Project-URL: Issues, https://github.com/yourname/winauto-cli/issues
+Keywords: windows,automation,uia,pywinauto,testing,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pywinauto>=0.6.8
+Dynamic: license-file
+
+# winauto-cli
+
+`winauto-cli` is a Python CLI wrapper around `pywinauto` for Windows desktop automation, with an Agent-oriented command surface for inspection, interaction, validation, and screenshot capture.
+
+## Install
+
+```powershell
+pip install winauto-cli
+```
+
+For local development:
+
+```powershell
+pip install -e .
+```
+
+## Agent commands
+
+These commands default to JSON output and are intended to be composed by an AI Agent.
+
+### `list-windows`
+
+List top-level windows:
+
+```powershell
+winauto-cli list-windows
+```
+
+### `find`
+
+Return candidate matches instead of forcing a single element:
+
+```powershell
+winauto-cli find --window-title "MyApp" --control-type Button --max-results 10
+winauto-cli find --window-title "MyApp" --path "//Button[@name='Submit']"
+winauto-cli find --window-title "MyApp" --path "Pane/Edit[0]"
+```
+
+### `inspect`
+
+Inspect one resolved element and return its children, parent chain, supported patterns, recommended selectors, and recommended paths:
+
+```powershell
+winauto-cli inspect --window-title "MyApp" --name "Submit"
+winauto-cli inspect --window-title "MyApp" --path "//Button[@name='Submit']"
+```
+
+`inspect` now returns path-oriented hints such as:
+
+- `recommended_paths`
+- `relative_path`
+
+These are intended for Agent follow-up calls using `--path`.
+
+### `act`
+
+Run a single action against a resolved element:
+
+```powershell
+winauto-cli act --window-title "MyApp" --name "Submit" --action click
+winauto-cli act --window-title "MyApp" --control-type Edit --action type --text "hello"
+winauto-cli act --window-title "MyApp" --path "//Button[@name='Submit']" --action click
+```
+
+### `assert`
+
+Validate existence, count, text, visibility, or enabled state:
+
+```powershell
+winauto-cli assert --window-title "MyApp" --name "Submit" --assertion exists
+winauto-cli assert --window-title "MyApp" --name "Submit" --assertion enabled --expected-bool true
+winauto-cli assert --window-title "MyApp" --control-type Button --assertion count --expected 3
+winauto-cli assert --window-title "MyApp" --path "//Button[@name='Submit']" --assertion exists
+```
+
+### `screenshot`
+
+Capture a screenshot for a resolved window or element:
+
+```powershell
+winauto-cli screenshot --window-title "MyApp" --out app-window.png
+winauto-cli screenshot --window-title "MyApp" --path "//Button[@name='Submit']" --out submit-button.png
+winauto-cli screenshot --window-title "MyApp" --path "//Button[@name='Submit']" --highlight --out submit-button-marked.png
+```
+
+Useful highlight options:
+
+- `--highlight`
+- `--highlight-duration-ms 800`
+- `--highlight-colour red`
+- `--highlight-thickness 3`
+
+## Path DSL
+
+The `--path` query is XPath-like, but intentionally smaller and desktop-focused.
+
+Supported forms:
+
+- `//Button`
+- `//Button[@name='Submit']`
+- `//Edit[@auto_id='txtUsername']`
+- `Pane/Edit[0]`
+- `//Pane[@class_name='Toolbar']/Button[1]`
+
+Rules:
+
+- `/` means direct child step.
+- `//` means descendant step.
+- `Type` matches `control_type`.
+- `[@name='x']`, `[@auto_id='x']`, `[@class_name='x']`, `[@control_type='x']`, `[@window_text='x']` are supported.
+- `[0]`, `[1]`, ... select by zero-based index after a step is filtered.
+
+## Compatibility commands
+
+These are retained as convenience wrappers over the newer primitives.
+
+- `dump`
+- `click`
+- `type`
+
+Examples:
+
+```powershell
+winauto-cli dump --window-title "MyApp"
+winauto-cli click --window-title "MyApp" --name "Submit"
+winauto-cli type --window-title "MyApp" --control-type Edit --text "hello from cli"
+```
+
+## Selector model
+
+Parent window options:
+
+- `--window-title`
+- `--window-title-re`
+- `--window-class-name`
+- `--window-auto-id`
+
+Target element options:
+
+- `--name`
+- `--auto-id`
+- `--control-type`
+- `--class-name`
+- `--index`
+- `--path`
+
+Runtime options:
+
+- `--backend {uia,win32}`
+- `--timeout <seconds>`
+- `--top-level-only`
+- `--verbose`
+- `--json`
+
+## Design intent
+
+The project is optimized for AI-assisted test authoring and debugging:
+
+- `find` returns candidate sets instead of hiding ambiguity.
+- `inspect` exposes enough metadata to refine selectors.
+- `act` separates action execution from selector debugging.
+- `assert` closes the loop for script verification.
+- `screenshot` provides visual verification and failure evidence.
+- `--path` provides a bridge between raw tree exploration and stable scripted lookup.
+- Compatibility commands remain available for quick manual use.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE`.
+
+Third-party dependencies keep their own licenses. See `THIRD_PARTY_NOTICES.md`.
+
+## Publishing
+
+Build distributions:
+
+```powershell
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+Test on TestPyPI first:
+
+```powershell
+python -m twine upload --repository testpypi dist/*
+```
+
+Then publish to PyPI:
+
+```powershell
+python -m twine upload dist/*
+```

winauto_cli-0.1.0/README.md

@@ -0,0 +1,193 @@
+# winauto-cli
+
+`winauto-cli` is a Python CLI wrapper around `pywinauto` for Windows desktop automation, with an Agent-oriented command surface for inspection, interaction, validation, and screenshot capture.
+
+## Install
+
+```powershell
+pip install winauto-cli
+```
+
+For local development:
+
+```powershell
+pip install -e .
+```
+
+## Agent commands
+
+These commands default to JSON output and are intended to be composed by an AI Agent.
+
+### `list-windows`
+
+List top-level windows:
+
+```powershell
+winauto-cli list-windows
+```
+
+### `find`
+
+Return candidate matches instead of forcing a single element:
+
+```powershell
+winauto-cli find --window-title "MyApp" --control-type Button --max-results 10
+winauto-cli find --window-title "MyApp" --path "//Button[@name='Submit']"
+winauto-cli find --window-title "MyApp" --path "Pane/Edit[0]"
+```
+
+### `inspect`
+
+Inspect one resolved element and return its children, parent chain, supported patterns, recommended selectors, and recommended paths:
+
+```powershell
+winauto-cli inspect --window-title "MyApp" --name "Submit"
+winauto-cli inspect --window-title "MyApp" --path "//Button[@name='Submit']"
+```
+
+`inspect` now returns path-oriented hints such as:
+
+- `recommended_paths`
+- `relative_path`
+
+These are intended for Agent follow-up calls using `--path`.
+
+### `act`
+
+Run a single action against a resolved element:
+
+```powershell
+winauto-cli act --window-title "MyApp" --name "Submit" --action click
+winauto-cli act --window-title "MyApp" --control-type Edit --action type --text "hello"
+winauto-cli act --window-title "MyApp" --path "//Button[@name='Submit']" --action click
+```
+
+### `assert`
+
+Validate existence, count, text, visibility, or enabled state:
+
+```powershell
+winauto-cli assert --window-title "MyApp" --name "Submit" --assertion exists
+winauto-cli assert --window-title "MyApp" --name "Submit" --assertion enabled --expected-bool true
+winauto-cli assert --window-title "MyApp" --control-type Button --assertion count --expected 3
+winauto-cli assert --window-title "MyApp" --path "//Button[@name='Submit']" --assertion exists
+```
+
+### `screenshot`
+
+Capture a screenshot for a resolved window or element:
+
+```powershell
+winauto-cli screenshot --window-title "MyApp" --out app-window.png
+winauto-cli screenshot --window-title "MyApp" --path "//Button[@name='Submit']" --out submit-button.png
+winauto-cli screenshot --window-title "MyApp" --path "//Button[@name='Submit']" --highlight --out submit-button-marked.png
+```
+
+Useful highlight options:
+
+- `--highlight`
+- `--highlight-duration-ms 800`
+- `--highlight-colour red`
+- `--highlight-thickness 3`
+
+## Path DSL
+
+The `--path` query is XPath-like, but intentionally smaller and desktop-focused.
+
+Supported forms:
+
+- `//Button`
+- `//Button[@name='Submit']`
+- `//Edit[@auto_id='txtUsername']`
+- `Pane/Edit[0]`
+- `//Pane[@class_name='Toolbar']/Button[1]`
+
+Rules:
+
+- `/` means direct child step.
+- `//` means descendant step.
+- `Type` matches `control_type`.
+- `[@name='x']`, `[@auto_id='x']`, `[@class_name='x']`, `[@control_type='x']`, `[@window_text='x']` are supported.
+- `[0]`, `[1]`, ... select by zero-based index after a step is filtered.
+
+## Compatibility commands
+
+These are retained as convenience wrappers over the newer primitives.
+
+- `dump`
+- `click`
+- `type`
+
+Examples:
+
+```powershell
+winauto-cli dump --window-title "MyApp"
+winauto-cli click --window-title "MyApp" --name "Submit"
+winauto-cli type --window-title "MyApp" --control-type Edit --text "hello from cli"
+```
+
+## Selector model
+
+Parent window options:
+
+- `--window-title`
+- `--window-title-re`
+- `--window-class-name`
+- `--window-auto-id`
+
+Target element options:
+
+- `--name`
+- `--auto-id`
+- `--control-type`
+- `--class-name`
+- `--index`
+- `--path`
+
+Runtime options:
+
+- `--backend {uia,win32}`
+- `--timeout <seconds>`
+- `--top-level-only`
+- `--verbose`
+- `--json`
+
+## Design intent
+
+The project is optimized for AI-assisted test authoring and debugging:
+
+- `find` returns candidate sets instead of hiding ambiguity.
+- `inspect` exposes enough metadata to refine selectors.
+- `act` separates action execution from selector debugging.
+- `assert` closes the loop for script verification.
+- `screenshot` provides visual verification and failure evidence.
+- `--path` provides a bridge between raw tree exploration and stable scripted lookup.
+- Compatibility commands remain available for quick manual use.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE`.
+
+Third-party dependencies keep their own licenses. See `THIRD_PARTY_NOTICES.md`.
+
+## Publishing
+
+Build distributions:
+
+```powershell
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+Test on TestPyPI first:
+
+```powershell
+python -m twine upload --repository testpypi dist/*
+```
+
+Then publish to PyPI:
+
+```powershell
+python -m twine upload dist/*
+```

winauto_cli-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "winauto-cli"
+version = "0.1.0"
+description = "A pragmatic Windows UI automation CLI built on top of pywinauto."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "wenqu" },
+]
+keywords = ["windows", "automation", "uia", "pywinauto", "testing", "cli"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: Microsoft :: Windows",
+  "Environment :: Console",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = [
+  "pywinauto>=0.6.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourname/winauto-cli"
+Repository = "https://github.com/yourname/winauto-cli"
+Issues = "https://github.com/yourname/winauto-cli/issues"
+
+[project.scripts]
+winauto-cli = "winauto_cli.cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["winauto_cli*"]

winauto_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

winauto_cli-0.1.0/winauto_cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

winauto_cli-0.1.0/winauto_cli/__main__.py

@@ -0,0 +1,5 @@
+from winauto_cli.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())