pull-cli 0.1.0__py3-none-any.whl

pull_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: pull-cli
+Version: 0.1.0
+Summary: AI-optimized Confluence evidence package extractor
+Project-URL: Homepage, https://github.com/ThomasRohde/pull-cli
+Project-URL: Repository, https://github.com/ThomasRohde/pull-cli
+Project-URL: Issues, https://github.com/ThomasRohde/pull-cli/issues
+Author-email: Thomas Rohde <rohde.thomas@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,atlassian,cli,confluence,markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: atlassian-python-api>=4.0.7
+Requires-Dist: beautifulsoup4>=4.12.3
+Requires-Dist: lxml>=5.2.0
+Requires-Dist: markdownify>=0.13.1
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: dev
+Requires-Dist: hatch>=1.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.9; extra == 'dev'
+Provides-Extra: extract
+Requires-Dist: defusedxml>=0.7.1; extra == 'extract'
+Requires-Dist: openpyxl>=3.1.5; extra == 'extract'
+Requires-Dist: pypdf>=5.0.0; extra == 'extract'
+Requires-Dist: python-docx>=1.1.2; extra == 'extract'
+Requires-Dist: python-pptx>=1.0.2; extra == 'extract'
+Description-Content-Type: text/markdown
+
+# pull-cli
+
+`pull-cli` installs the `pull` command, a read-only Confluence extractor for AI-consumable evidence packages. It is rendered-page-first: page Markdown, and the optional Markdown bundle in full mode, are based on the current published page as visible to the authenticated user, while storage XML is kept for macro recovery, provenance, and fallback.
+
+The default output mode is `simple`: a quiet agent-facing package with the root AI Markdown file, per-page Markdown files, assets/sidecars, and validation control files. Use `--output-mode full` when you also want `bundle.md`, page HTML snapshots, and storage-source sidecars.
+
+Confluence access is implemented through `atlassian-python-api` behind a small `pull_cli.clients` protocol. The extraction, redaction, manifest, asset, link, and validation contracts remain owned by `pull-cli`.
+
+## Install
+
+```bash
+uvx pull-cli --help
+uv tool install pull-cli
+pip install pull-cli
+```
+
+The package name is `pull-cli`. The import package is `pull_cli`. Console scripts are `pull` and `pull-cli`.
+
+## Quickstart
+
+Cloud:
+
+```bash
+set PULL_URL=https://example.atlassian.net/wiki
+set PULL_USER=you@example.com
+set PULL_TOKEN=your-api-token
+pull 123456 -o pulled-confluence
+```
+
+Data Center or Server:
+
+```bash
+set PULL_URL=https://confluence.example.com/confluence
+set PULL_TOKEN=your-personal-access-token
+pull --page-id 123456 -o pulled-confluence
+```
+
+`CONFPUB_URL`, `CONFPUB_USER`, `CONFPUB_TOKEN`, and `CONFPUB_SSL_VERIFY` are accepted as compatibility fallbacks after `PULL_*` variables.
+
+## CLI Examples
+
+```bash
+pull 123456 -o pulled
+pull "https://example.atlassian.net/wiki/spaces/EA/pages/123456/Architecture" -o pulled
+pull --space EA --title "Architecture Overview" -o pulled
+pull --page-id 123456 --tree --depth 3 --max-pages 100 -o tree
+pull --page-id 123456 --tree --assets all --extract-attachments -o offline
+pull --page-id 123456 --tree --comments -o with-comments
+pull --page-id 123456 --output-mode full -o full-evidence
+pull --page-id 123456 --output-mode simple --bundle -o simple-with-bundle
+pull --page-id 123456 --json -o pulled
+pull validate pulled
+pull guide --json
+```
+
+Selector resolution order is: explicit `--page-id`, explicit `--url`, positional URL, positional numeric page ID, then `--space` plus `--title`.
+
+## Output Package
+
+Default `simple` mode:
+
+```text
+pulled-confluence/
+├── page-title.md
+├── page-title.yaml
+├── manifest.yaml
+├── pages/
+│   └── 0001-page-slug/
+│       ├── index.md
+│       ├── page.json
+│       ├── comments.md        # with --comments, only when comments exist
+│       └── assets/
+└── diagnostics/
+    ├── warnings.jsonl
+    └── unresolved-links.md
+```
+
+`page-title.md` is named from the sanitized root page title and is the recommended first file to give another AI agent. In simple mode it links only the reading/navigation surface: page Markdown paths, assets, sidecars, and explicitly requested agent-facing extras such as `bundle.md` or `chunks.jsonl`. Warning counts are shown, but control files are not linked from the root AI Markdown.
+
+`page-title.yaml` is the machine-readable version of that AI navigation manifest, also named from the sanitized root page title. It intentionally omits noisy provenance and raw API details; use `manifest.yaml` when you need full validation/provenance data. The exact generated filenames are recorded in `manifest.yaml` under `paths.ai_entry` and `paths.ai_manifest`. AI navigation paths are package-root-relative: resolve them against the directory containing the root AI Markdown/YAML file, not the caller's shell working directory.
+
+`manifest.yaml`, `page.json`, and diagnostics files are still written in simple mode so `pull validate <output-dir>` and provenance checks work. `--force` never deletes stale files from earlier runs; use `--clean` when switching modes if you need the physical tree to contain only files from the new mode.
+
+`--output-mode full` adds the full evidence artifacts:
+
+```text
+pulled-confluence/
+├── bundle.md
+└── pages/
+    └── 0001-page-slug/
+        ├── index.html
+        └── source.storage.xml
+```
+
+`bundle.md` concatenates pages in page/tree order with stable delimiters for AI use; local links embedded in the bundle are rebased to the package root. `index.html` and `source.storage.xml` are raw/reference artifacts, not the primary navigation surface.
+
+For tree pulls, nested page paths are the default. The manifest always carries stable numeric ordering.
+
+## Auth and Config
+
+Resolution order:
+
+1. CLI flags such as `--base-url`, `--user`, `--token`, `--ssl-verify`.
+2. `PULL_*` environment variables.
+3. Optional YAML config from `--config`.
+4. `CONFPUB_*` compatibility environment variables.
+
+`--ssl-verify` accepts `true`, `false`, or a CA bundle path.
+
+## Macro, Asset, and Link Behavior
+
+The extractor uses a macro adapter registry. Current adapters cover panels/admonitions, code/noformat, status, expand, tabs, layout flattening, TOC placeholders, children/page tree links when in scope, include/excerpt placeholders or inline source when available, attachments, displayed files, Jira placeholders, diagram snapshots, dynamic snapshots, HTML macro sanitization, and unknown macro placeholders.
+
+Asset policy defaults to `visible`: rendered images, visible attachment links, file macros, and rendered diagram images where discoverable. `--assets page` downloads all page attachments. `--assets all` includes visible/referenced assets plus all page attachments and macro-listed files where discoverable. `--no-assets` skips downloads and preserves source links with warnings.
+
+Local links to pages in the pulled tree are rewritten to relative `index.md` paths. Downloaded asset links are rewritten to local files. External, mailto, Jira, and out-of-scope Confluence links are preserved. Same-page anchors are normalized where possible; unresolved anchors become diagnostics.
+
+## Comments
+
+Comments are skipped by default. Use `--comments` to fetch page-level and inline comments for each pulled page. When comments exist, `pull` writes a page-local `comments.md` sidecar with agent-readable metadata and Markdown-converted comment bodies.
+
+Comment sidecars are agent-facing reading surfaces: the root AI Markdown page hierarchy links them in simple mode, the page `index.md` header links the local sidecar, and the AI YAML includes the optional comments path and count. If one page's comments cannot be fetched, the pull continues with `W_COMMENTS_FETCH_FAILED` and validation can still pass for the partial package.
+
+## JSON Mode
+
+With `--json` or `LLM=true`, stdout is exactly one JSON object with:
+
+```json
+{
+  "schema_version": "1.0",
+  "request_id": "req_...",
+  "ok": true,
+  "command": "pull",
+  "target": {},
+  "result": {},
+  "warnings": [],
+  "errors": [],
+  "metrics": {}
+}
+```
+
+Progress, retries, warnings, and debug output belong on stderr.
+
+## Security
+
+`pull` is read-only. It does not mutate Confluence, fetch drafts by default, bypass permissions, or call LLM services. Tokens, Authorization headers, cookies, signed download query parameters, and token-like strings are redacted before JSON envelopes, manifests, page metadata, and diagnostics are written.
+
+Rendered HTML snapshots are sanitized by removing executable tags and event attributes. HTML macro content is made inert before conversion.
+
+## Validation
+
+```bash
+pull validate pulled-confluence
+pull validate pulled-confluence/manifest.yaml --json
+```
+
+Validation checks manifest shape, AI navigation manifest paths, relative paths, page files, optional comment sidecars, asset checksums, diagnostics JSONL, Markdown local links, and token-like markers in text outputs.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run pytest
+uv build
+uv run pull --help
+uv run pull guide --json
+uv run python tests/generate_fixture_output.py .tmp/generated-fixture
+uv run pull validate .tmp/generated-fixture
+```
+
+Live smoke testing requires a readable Confluence page and credentials through `PULL_*` or `CONFPUB_*`.
+
+## Releasing
+
+Versions are managed from `src/pull_cli/__init__.py` through Hatch. Use `uv run hatch version patch`, `uv run hatch version minor`, or `uv run hatch version major`; `pull --version`, built package metadata, and GitHub release tags are expected to match. See [RELEASING.md](RELEASING.md) for the PyPI trusted publisher setup and release flow.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pull_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+pull_cli/__init__.py,sha256=NwPRGSlXfZCb8Z4R1qZXHlFuXjmIGWj3CDBUsow4Rpk,105
+pull_cli/__main__.py,sha256=UP0yjf5bUzmplYRElA6c5FuXZNu3sTDMJfOpZsy3Bqg,115
+pull_cli/assets.py,sha256=jh1Jgl-la-zA2jA4fhy58Bt9geEuffKrKRuy5yIZnA8,8356
+pull_cli/attachment_extractors.py,sha256=9gZr7K5hFN7sp_Xp9jSqXdQy2Gt-EH7bwU_8TKAbB6c,2769
+pull_cli/cli.py,sha256=RWDrY0WWo-tmqAuOtOvoG7cYhEJL7eKsomaJWFLpjDo,14896
+pull_cli/config.py,sha256=Itkuda5Ir3yY6RRYYCNGIOm6yfW1ntSXgP6tnrqJmS4,2294
+pull_cli/crawler.py,sha256=dLA5OBQPSznqXkDEPfiQTEnnv5JSo-9fWM5SEFGSrwA,1582
+pull_cli/envelope.py,sha256=cwfFkR_ZERf-U4FkB-69qTd3ohIs6uZpvwxMY4iPWZk,1647
+pull_cli/errors.py,sha256=20lRBifyj_KTuCaJWEQWAExDPNlWGp2-_Wig3SS9Igo,1155
+pull_cli/extractor.py,sha256=klALkkc5_UgeOzTuYhlcJ_2PvzoXRmxBay_eTR9HU0o,12911
+pull_cli/guide.py,sha256=PEXHT_B01JVjJSgmt8s_HVSccja16TfLDufxXppFtMM,6047
+pull_cli/html_normalizer.py,sha256=JAf8fRnDUnUaIGnK1fHNJCz3FSdzPANea1eLSvBHCTE,4225
+pull_cli/links.py,sha256=Zbb8s8f-TT9x6hFLocz-u4WHqU_F7SJt8OGf6cUMinU,6136
+pull_cli/macros.py,sha256=WO2rWdH24X0x7dpn_hDlj6kVfOSsw3jS-UlRNgSiFlo,18938
+pull_cli/markdown_writer.py,sha256=Zl4MR4MMssnBrbbln-1lixaBCsfSM3tD9vVAzu7F7Xk,673
+pull_cli/models.py,sha256=SDj4u_0Mj1tUbdxFBrsjGx7w1OUQoYxAgO9xnxXP3S8,6276
+pull_cli/paths.py,sha256=DTt26KNqFTk08uUL1g24UcHFdbJ1wB3WGwEvLIzc74g,1220
+pull_cli/resolver.py,sha256=Jyoznr9ff-_lwgcMtKal1Yo-4E58XD7JIOfddHmGxHI,2872
+pull_cli/security.py,sha256=p5ozNBKvvT2g0LFgB8Qjf6HYxN_-laSEFuO7Q_EiWN8,3760
+pull_cli/validator.py,sha256=nBiFbAgbil0dCpkr_VbL1BTefhT_SeuuKeSWQx5HGSk,18935
+pull_cli/writer.py,sha256=7qN-7TzDG0cZCndddR8A6jxJs-AmB_FeUIyTbhj4Shs,31656
+pull_cli/clients/__init__.py,sha256=54sYdetJJ03RnCtRP4xbINO0JqlRpoUB2PN-rlBx13k,267
+pull_cli/clients/base.py,sha256=KxgYGCYFeu1NRiFo8-HayvRYVEjCrtmjGBBoHYfzx4Q,858
+pull_cli/clients/cloud_v2.py,sha256=YhLk6mv1kKZq2NmuDC52uJFdfvE1Y9J-Er6wR9k0NJE,5571
+pull_cli/clients/data_center.py,sha256=1zN35inHrCni-X2xxny_NanP3k5Lf4RPa5veJLdTn7M,15647
+pull_cli/clients/hybrid.py,sha256=gBOSMrxvUbV9pHYP5YpWa53lL1CIE-WfyUc-A1sJtkA,424
+pull_cli-0.1.0.dist-info/METADATA,sha256=6nxkPhYw8M26ogIi5YtjyQxnF0qt9TZo2a9HVirUcso,10056
+pull_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pull_cli-0.1.0.dist-info/entry_points.txt,sha256=WbpaUb8ralPybdTXQvn4ntQzXX3PpcixXZJ9NZXz3LU,72
+pull_cli-0.1.0.dist-info/licenses/LICENSE,sha256=XeaSn5y2iyNPWLW7TlPEWT8OkLhuZw-koqZ5bhUw5tg,1069
+pull_cli-0.1.0.dist-info/RECORD,,

pull_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pull_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pull = pull_cli.cli:main
+pull-cli = pull_cli.cli:main

pull_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Rohde
+
+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.