apdf-cloud-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{apdf_cloud_cli-0.1.0 → apdf_cloud_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apdf-cloud-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: CLI and MCP server tools for Aspose PDF Cloud
 Keywords: aspose,pdf,cli,mcp
 Author: Andriy Andruhovski
@@ -32,8 +32,29 @@ Description-Content-Type: text/markdown
 
 # APDF Cloud CLI + MCP Tools
 
-Stage 1 exposes APDF storage and PDF operations through both a CLI
-and an MCP server.
+APDF Cloud CLI exposes Aspose PDF Cloud storage and PDF operations through
+both a command-line interface and an MCP server.
+
+## Installation
+
+Install from PyPI:
+
+```powershell
+python -m pip install apdf-cloud-cli
+```
+
+Check that the CLI is available:
+
+```powershell
+apdf-cloud-cli --help
+apdf --help
+```
+
+For local development from a checkout:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
 
 ## Configuration
 
@@ -46,14 +67,18 @@ $env:ASPOSE_CLIENT_SECRET = "your-client-secret"
 
 Optional environment variables:
 
-- `ASPOSE_BASE_URL`
-- `ASPOSE_SELF_HOST`
-- `ASPOSE_STORAGE_NAME`
+- `ASPOSE_STORAGE_NAME`: default Aspose storage name.
+- `ASPOSE_BASE_URL`: alternate Aspose PDF Cloud base URL.
+- `ASPOSE_SELF_HOST`: set to `1`, `true`, `yes`, or `on` for self-hosted use.
+
+You can also create a local `.env` file. See
+[`.env.example`](.env.example) for a template. Environment variables take
+precedence over `.env` values.
 
-## CLI
+## CLI Usage
 
-The canonical executable is `apdf-cloud-cli`. A shorter `apdf`
-alias is also installed for convenience.
+The canonical executable is `apdf-cloud-cli`. A shorter `apdf` alias is
+also installed for convenience.
 
 ```powershell
 apdf-cloud-cli storage list /
@@ -64,20 +89,61 @@ apdf-cloud-cli pdf extract-text sample.pdf --output sample.txt
 apdf-cloud-cli mcp serve
 ```
 
-## Development
+## MCP Usage
 
-Install the package with development dependencies:
+After installing the package, configure your MCP client to launch:
 
 ```powershell
-python -m pip install -e ".[dev]"
+apdf-cloud-cli mcp serve
+```
+
+Codex MCP configuration examples are available in
+[docs/mcp-config.md](docs/mcp-config.md), with a copy-pasteable helper at
+[examples/codex-mcp-config.toml](examples/codex-mcp-config.toml).
+
+## Codex Prompts
+
+Sample prompts for using this MCP server with Codex are in
+[docs/codex-prompts.md](docs/codex-prompts.md).
+
+## Install as an Agent Skill
+
+The package includes an `apdf-cloud-mcp` skill for Codex and Claude Code.
+Install the package first, then install the bundled skill:
+
+```powershell
+python -m pip install apdf-cloud-cli
+apdf-cloud-cli skill install codex
+apdf-cloud-cli skill install claude-code
+```
+
+For Claude Code project-local installation:
+
+```powershell
+apdf-cloud-cli skill install claude-code --project
 ```
 
-Run the default test suite:
+Use `--force` to replace an existing installed copy. More details are in
+[docs/agent-skill.md](docs/agent-skill.md).
+
+## Development
+
+Run the default unit test suite:
 
 ```powershell
 python -m pytest -q
 ```
 
+Run live Aspose Cloud smoke tests only when you intentionally want to call
+the real API:
+
+```powershell
+$env:ASPOSE_RUN_LIVE_TESTS = "1"
+python -m pytest -q -m live
+```
+
+More live-test setup notes are in [docs/live-tests.md](docs/live-tests.md).
+
 Build and validate the package distributions:
 
 ```powershell
@@ -85,6 +151,12 @@ python -m build
 python -m twine check dist/*
 ```
 
+## Security
+
+Never commit real credentials. Keep `.env` local, prefer short-lived
+environment variables in CI, and avoid pasting secrets into issue reports,
+test output, logs, or prompts. See [docs/security.md](docs/security.md).
+
 ## Publishing
 
 Publishing is handled by GitHub Actions with PyPI trusted publishing.
@@ -97,8 +169,8 @@ Publishing is handled by GitHub Actions with PyPI trusted publishing.
 3. Push a matching version tag, for example:
 
 ```powershell
-git tag v0.1.0
-git push origin v0.1.0
+git tag v0.2.0
+git push origin v0.2.0
 ```
 
 ## Stage 2 Roadmap

apdf_cloud_cli-0.2.0/README.md

@@ -0,0 +1,148 @@
+# APDF Cloud CLI + MCP Tools
+
+APDF Cloud CLI exposes Aspose PDF Cloud storage and PDF operations through
+both a command-line interface and an MCP server.
+
+## Installation
+
+Install from PyPI:
+
+```powershell
+python -m pip install apdf-cloud-cli
+```
+
+Check that the CLI is available:
+
+```powershell
+apdf-cloud-cli --help
+apdf --help
+```
+
+For local development from a checkout:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+## Configuration
+
+Set credentials before running CLI commands or the MCP server:
+
+```powershell
+$env:ASPOSE_CLIENT_ID = "your-client-id"
+$env:ASPOSE_CLIENT_SECRET = "your-client-secret"
+```
+
+Optional environment variables:
+
+- `ASPOSE_STORAGE_NAME`: default Aspose storage name.
+- `ASPOSE_BASE_URL`: alternate Aspose PDF Cloud base URL.
+- `ASPOSE_SELF_HOST`: set to `1`, `true`, `yes`, or `on` for self-hosted use.
+
+You can also create a local `.env` file. See
+[`.env.example`](.env.example) for a template. Environment variables take
+precedence over `.env` values.
+
+## CLI Usage
+
+The canonical executable is `apdf-cloud-cli`. A shorter `apdf` alias is
+also installed for convenience.
+
+```powershell
+apdf-cloud-cli storage list /
+apdf-cloud-cli storage upload .\sample.pdf /sample.pdf
+apdf-cloud-cli storage download /sample.pdf .\sample.pdf
+apdf-cloud-cli pdf merge /a.pdf /b.pdf merged.pdf
+apdf-cloud-cli pdf extract-text sample.pdf --output sample.txt
+apdf-cloud-cli mcp serve
+```
+
+## MCP Usage
+
+After installing the package, configure your MCP client to launch:
+
+```powershell
+apdf-cloud-cli mcp serve
+```
+
+Codex MCP configuration examples are available in
+[docs/mcp-config.md](docs/mcp-config.md), with a copy-pasteable helper at
+[examples/codex-mcp-config.toml](examples/codex-mcp-config.toml).
+
+## Codex Prompts
+
+Sample prompts for using this MCP server with Codex are in
+[docs/codex-prompts.md](docs/codex-prompts.md).
+
+## Install as an Agent Skill
+
+The package includes an `apdf-cloud-mcp` skill for Codex and Claude Code.
+Install the package first, then install the bundled skill:
+
+```powershell
+python -m pip install apdf-cloud-cli
+apdf-cloud-cli skill install codex
+apdf-cloud-cli skill install claude-code
+```
+
+For Claude Code project-local installation:
+
+```powershell
+apdf-cloud-cli skill install claude-code --project
+```
+
+Use `--force` to replace an existing installed copy. More details are in
+[docs/agent-skill.md](docs/agent-skill.md).
+
+## Development
+
+Run the default unit test suite:
+
+```powershell
+python -m pytest -q
+```
+
+Run live Aspose Cloud smoke tests only when you intentionally want to call
+the real API:
+
+```powershell
+$env:ASPOSE_RUN_LIVE_TESTS = "1"
+python -m pytest -q -m live
+```
+
+More live-test setup notes are in [docs/live-tests.md](docs/live-tests.md).
+
+Build and validate the package distributions:
+
+```powershell
+python -m build
+python -m twine check dist/*
+```
+
+## Security
+
+Never commit real credentials. Keep `.env` local, prefer short-lived
+environment variables in CI, and avoid pasting secrets into issue reports,
+test output, logs, or prompts. See [docs/security.md](docs/security.md).
+
+## Publishing
+
+Publishing is handled by GitHub Actions with PyPI trusted publishing.
+
+1. In PyPI, add a trusted publisher for repository
+   `andruhovski/apdf-tools`, workflow `publish.yml`, environment `pypi`,
+   and project name `apdf-cloud-cli`.
+2. Update the version in `pyproject.toml` and
+   `src/apdf_cloud_cli/__init__.py`.
+3. Push a matching version tag, for example:
+
+```powershell
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+## Stage 2 Roadmap
+
+- Split PDF files
+- Extract images from PDF files
+- Extract tables from PDF files

{apdf_cloud_cli-0.1.0 → apdf_cloud_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "apdf-cloud-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "CLI and MCP server tools for Aspose PDF Cloud"
 authors = [
     {name = "Andriy Andruhovski",email = "andruhovski@gmail.com"}
@@ -39,6 +39,11 @@ dev = [
 apdf-cloud-cli = "apdf_cloud_cli.cli:main"
 apdf = "apdf_cloud_cli.cli:main"
 
+[tool.poetry]
+include = [
+    { path = "src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/**/*", format = ["sdist", "wheel"] },
+]
+
 [project.urls]
 Homepage = "https://github.com/andruhovski/apdf-tools"
 Repository = "https://github.com/andruhovski/apdf-tools"

{apdf_cloud_cli-0.1.0 → apdf_cloud_cli-0.2.0}/src/apdf_cloud_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{apdf_cloud_cli-0.1.0 → apdf_cloud_cli-0.2.0}/src/apdf_cloud_cli/cli.py

@@ -12,14 +12,17 @@ from rich.table import Table
 
 from . import operations
 from .config import ConfigError
+from .skill_installer import SkillInstallError, install_skill
 
 app = typer.Typer(help="APDF CLI tools.")
 storage_app = typer.Typer(help="Cloud storage operations.")
 pdf_app = typer.Typer(help="PDF operations.")
 mcp_app = typer.Typer(help="MCP server commands.")
+skill_app = typer.Typer(help="Install bundled agent skills.")
 app.add_typer(storage_app, name="storage")
 app.add_typer(pdf_app, name="pdf")
 app.add_typer(mcp_app, name="mcp")
+app.add_typer(skill_app, name="skill")
 
 console = Console()
 
@@ -154,6 +157,36 @@ def serve_mcp() -> None:
     main()
 
 
+@skill_app.command("install")
+def install_agent_skill(
+    client: Annotated[
+        str,
+        typer.Argument(help="Target client: codex or claude-code."),
+    ],
+    target_dir: Annotated[
+        Path | None,
+        typer.Option("--target-dir", help="Custom skills directory to install into."),
+    ] = None,
+    project: Annotated[
+        bool,
+        typer.Option("--project", help="For Claude Code, install into ./.claude/skills."),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Replace an existing apdf-cloud-mcp skill."),
+    ] = False,
+) -> None:
+    """Install the bundled APDF Cloud MCP skill for Codex or Claude Code."""
+
+    try:
+        result = install_skill(client, target_dir=target_dir, project=project, force=force)
+    except SkillInstallError as exc:
+        _handle_error(exc)
+
+    action = "Reinstalled" if result.overwritten else "Installed"
+    console.print(f"{action} [bold]apdf-cloud-mcp[/bold] skill to [bold]{result.destination}[/bold].")
+
+
 def main() -> None:
     app()
 

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: apdf-cloud-mcp
+description: Use APDF Cloud CLI and its Aspose PDF Cloud MCP server for PDF/storage automation. Trigger when the user wants to configure or use the APDF MCP server, connect Codex or Claude Code to Aspose PDF Cloud, list/upload/download Aspose storage files, merge PDFs, extract PDF text, write sample agent prompts for APDF, run live APDF smoke tests, or troubleshoot APDF Cloud CLI/MCP setup and credential handling.
+---
+
+# APDF Cloud MCP
+
+## Core Workflow
+
+Use this skill for APDF Cloud CLI / MCP work involving Aspose PDF Cloud.
+
+1. Determine whether the user wants setup, MCP usage, CLI usage, testing, docs, or troubleshooting.
+2. Prefer active MCP tools for storage/PDF operations when the APDF MCP server is available.
+3. Use the `apdf-cloud-cli` / `apdf` CLI as a fallback when MCP tools are unavailable or the user asks for local commands.
+4. **Priority rule**: If the user explicitly requests CLI commands, provide CLI commands even when MCP tools are active. Otherwise, default to MCP tools when the server is available.
+5. Keep credentials out of output, logs, examples, commits, and prompts. Use placeholders in docs and configs.
+
+## MCP Operations
+
+When APDF MCP tools are active, use them for:
+
+- `list_files(path, storage_name=None)`
+- `upload_file(local_path, remote_path, storage_name=None)`
+- `download_file(remote_path, local_path, storage_name=None, version_id=None)`
+- `merge_pdfs(input_1, input_2, output_name, folder=None, storage=None)`
+- `extract_text(name, folder=None, storage=None)`
+
+### Error Handling
+
+If an MCP tool returns an error, report the error message to the user verbatim, identify the likely cause (e.g., invalid credentials, missing file, wrong storage name), and suggest a corrective action before retrying.
+
+### Confirmation & Validation
+
+Before executing upload, merge-output, or download-overwrite operations, confirm the target path unless the user has provided a fully-qualified remote path (e.g., `folder/filename.pdf`) and has not used words like 'somewhere', 'any folder', or left the path field empty.
+
+For `download_file`, use `version_id` only when the user explicitly requests a specific file version. If version information is needed but not provided, ask the user for the version ID before calling the tool.
+
+## Setup
+
+For install/configuration tasks, read `references/setup.md`. If a referenced file (e.g., `references/setup.md`, `references/mcp-config.md`, `references/prompts.md`, or `references/security.md`) cannot be read, proceed using only the information provided in this prompt and clearly note to the user that the full reference document was unavailable.
+
+Default install command:
+
+```powershell
+python -m pip install apdf-cloud-cli
+```
+
+Default MCP command:
+
+```powershell
+apdf-cloud-cli mcp serve
+```
+
+Required credentials:
+
+- `ASPOSE_CLIENT_ID`
+- `ASPOSE_CLIENT_SECRET`
+
+Optional settings:
+
+- `ASPOSE_STORAGE_NAME`
+- `ASPOSE_BASE_URL`
+- `ASPOSE_SELF_HOST`
+
+## Agent MCP Config
+
+For Codex and Claude Code config examples, read `references/mcp-config.md`.
+
+Prefer inherited environment variables in agent config:
+
+```toml
+[mcp_servers.aspose_pdf_cloud]
+command = "apdf-cloud-cli"
+args = ["mcp", "serve"]
+env_vars = [
+  "ASPOSE_CLIENT_ID",
+  "ASPOSE_CLIENT_SECRET",
+  "ASPOSE_STORAGE_NAME",
+  "ASPOSE_BASE_URL",
+  "ASPOSE_SELF_HOST"
+]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+## Prompt Writing
+
+For sample agent prompts, read `references/prompts.md`.
+
+Good APDF prompts specify:
+
+- Storage path or local path.
+- Operation: list, upload, download, merge, or extract text.
+- Whether writes are allowed.
+- Whether to summarize extracted text or save it.
+
+## Security
+
+For security details, read `references/security.md`.
+
+Never print or commit real values for:
+
+- `ASPOSE_CLIENT_ID`
+- `ASPOSE_CLIENT_SECRET`
+
+Use `<redacted>` or `your-client-id` / `your-client-secret` in examples.

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "APDF Cloud MCP"
+  short_description: "Use Aspose PDF Cloud through APDF MCP"
+  default_prompt: "Use $apdf-cloud-mcp to configure APDF Cloud MCP and work with PDFs in Aspose storage."

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/references/live-tests.md

@@ -0,0 +1,30 @@
+# Live Test Reference
+
+Default tests do not call Aspose Cloud:
+
+```powershell
+python -m pytest -q
+```
+
+Live tests require:
+
+- `ASPOSE_CLIENT_ID`
+- `ASPOSE_CLIENT_SECRET`
+- `ASPOSE_RUN_LIVE_TESTS=1`
+- `ASPOSE_STORAGE_NAME`, if the account requires named storage
+
+Run live tests:
+
+```powershell
+$env:ASPOSE_CLIENT_ID = "your-client-id"
+$env:ASPOSE_CLIENT_SECRET = "your-client-secret"
+$env:ASPOSE_STORAGE_NAME = "your-storage-name"
+$env:ASPOSE_RUN_LIVE_TESTS = "1"
+python -m pytest -q -m live
+```
+
+The live upload/download smoke test writes under the
+`aspose-pdf-cloud-cli-live/` prefix and attempts cleanup. If interrupted,
+check that prefix manually in Aspose storage.
+
+Do not enable live tests in public CI unless safe credentials are explicitly configured.

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/references/mcp-config.md

@@ -0,0 +1,65 @@
+# MCP Configuration Reference
+
+## Codex
+
+Prefer inherited environment variables so secrets remain outside config files:
+
+```toml
+[mcp_servers.aspose_pdf_cloud]
+command = "apdf-cloud-cli"
+args = ["mcp", "serve"]
+env_vars = [
+  "ASPOSE_CLIENT_ID",
+  "ASPOSE_CLIENT_SECRET",
+  "ASPOSE_STORAGE_NAME",
+  "ASPOSE_BASE_URL",
+  "ASPOSE_SELF_HOST"
+]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+## Claude Code
+
+Claude Code skills can be installed globally under `~/.claude/skills/` or
+per project under `.claude/skills/`. Configure the MCP server in the place
+where your Claude Code setup manages MCP servers, using this command:
+
+```powershell
+apdf-cloud-cli mcp serve
+```
+
+If your Claude Code MCP config uses JSON, adapt this shape:
+
+```json
+{
+  "mcpServers": {
+    "aspose_pdf_cloud": {
+      "command": "apdf-cloud-cli",
+      "args": ["mcp", "serve"],
+      "env": {
+        "ASPOSE_CLIENT_ID": "your-client-id",
+        "ASPOSE_CLIENT_SECRET": "your-client-secret",
+        "ASPOSE_STORAGE_NAME": "your-storage-name"
+      }
+    }
+  }
+}
+```
+
+## Explicit Environment Map
+
+Only use explicit values in local-only files. Use placeholders in committed examples:
+
+```toml
+[mcp_servers.aspose_pdf_cloud]
+command = "apdf-cloud-cli"
+args = ["mcp", "serve"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+
+[mcp_servers.aspose_pdf_cloud.env]
+ASPOSE_CLIENT_ID = "your-client-id"
+ASPOSE_CLIENT_SECRET = "your-client-secret"
+ASPOSE_STORAGE_NAME = "your-storage-name"
+```

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/references/prompts.md

@@ -0,0 +1,43 @@
+# Prompt Reference
+
+## Storage
+
+```text
+List the files in my default Aspose storage root and summarize the PDFs you find.
+```
+
+```text
+Upload ./sample.pdf to /codex-demo/sample.pdf in Aspose storage.
+```
+
+```text
+Download /codex-demo/sample.pdf from Aspose storage to ./downloads/sample.pdf.
+```
+
+## PDF Operations
+
+```text
+Merge /contracts/part-a.pdf and /contracts/part-b.pdf into merged-contract.pdf in Aspose storage.
+```
+
+```text
+Extract text from /reports/q1.pdf and save it locally as ./reports/q1.txt.
+```
+
+```text
+Extract text from /reports/q1.pdf, summarize the important dates, and tell me what looks missing.
+```
+
+## Safe Workflows
+
+```text
+Before modifying storage, list the target folder and ask me to confirm the upload path.
+```
+
+```text
+Use the APDF MCP tools, but do not print credentials or raw environment variables.
+```
+
+```text
+Run a small smoke check by listing storage only. Do not upload, download, or delete files.
+```

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/references/security.md

@@ -0,0 +1,38 @@
+# Security Reference
+
+## Credentials
+
+Never commit or print real values for:
+
+- `ASPOSE_CLIENT_ID`
+- `ASPOSE_CLIENT_SECRET`
+
+Treat these as sensitive too:
+
+- `ASPOSE_STORAGE_NAME`
+- `ASPOSE_BASE_URL`
+- `ASPOSE_SELF_HOST`
+
+## Config Files
+
+Prefer MCP configs that inherit environment variables. If explicit secret
+values are necessary for a local-only config, keep that file outside version
+control.
+
+Use placeholders in examples:
+
+```text
+ASPOSE_CLIENT_ID=your-client-id
+ASPOSE_CLIENT_SECRET=your-client-secret
+```
+
+## Logs and Prompts
+
+Before sharing logs, issue reports, or agent transcripts, redact secrets:
+
+```text
+ASPOSE_CLIENT_SECRET=<redacted>
+```
+
+Do not echo raw environment variables unless the user explicitly asks and the
+values are already placeholders.

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/resources/skills/apdf-cloud-mcp/references/setup.md

@@ -0,0 +1,54 @@
+# Setup Reference
+
+## Install
+
+Install the published package:
+
+```powershell
+python -m pip install apdf-cloud-cli
+```
+
+Verify commands:
+
+```powershell
+apdf-cloud-cli --help
+apdf --help
+```
+
+Install from a local checkout for development:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+## Environment
+
+Set required credentials:
+
+```powershell
+$env:ASPOSE_CLIENT_ID = "your-client-id"
+$env:ASPOSE_CLIENT_SECRET = "your-client-secret"
+```
+
+Set optional values when needed:
+
+```powershell
+$env:ASPOSE_STORAGE_NAME = "your-storage-name"
+$env:ASPOSE_BASE_URL = "https://api.aspose.cloud/v3.0"
+$env:ASPOSE_SELF_HOST = "false"
+```
+
+Local `.env` files are supported by the APDF CLI, but they must remain untracked.
+
+## CLI Commands
+
+```powershell
+apdf-cloud-cli storage list /
+apdf-cloud-cli storage upload .\sample.pdf /sample.pdf
+apdf-cloud-cli storage download /sample.pdf .\sample.pdf
+apdf-cloud-cli pdf merge /a.pdf /b.pdf merged.pdf
+apdf-cloud-cli pdf extract-text sample.pdf --output sample.txt
+apdf-cloud-cli mcp serve
+```
+
+Use `apdf` as the short alias when convenient.

apdf_cloud_cli-0.2.0/src/apdf_cloud_cli/skill_installer.py

@@ -0,0 +1,80 @@
+"""Install the bundled APDF Cloud MCP agent skill."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+
+SKILL_NAME = "apdf-cloud-mcp"
+
+
+class SkillInstallError(RuntimeError):
+    """Raised when bundled skill installation fails."""
+
+
+@dataclass(frozen=True)
+class SkillInstallResult:
+    client: str
+    destination: Path
+    overwritten: bool
+
+
+def _bundled_skill_path() -> Path:
+    traversable = resources.files("apdf_cloud_cli") / "resources" / "skills" / SKILL_NAME
+    try:
+        path = Path(str(traversable))
+    except TypeError as exc:
+        raise SkillInstallError("Unable to resolve bundled skill path.") from exc
+
+    if not path.is_dir():
+        raise SkillInstallError(f"Bundled skill not found: {path}")
+    return path
+
+
+def default_skill_root(client: str, project: bool = False) -> Path:
+    """Return the default skill root for Codex or Claude Code."""
+
+    normalized = client.strip().lower()
+    if normalized == "codex":
+        return Path.home() / ".codex" / "skills"
+    if normalized in {"claude", "claude-code", "claudecode"}:
+        if project:
+            return Path.cwd() / ".claude" / "skills"
+        return Path.home() / ".claude" / "skills"
+    raise SkillInstallError("Client must be 'codex' or 'claude-code'.")
+
+
+def install_skill(
+    client: str,
+    *,
+    target_dir: str | Path | None = None,
+    project: bool = False,
+    force: bool = False,
+) -> SkillInstallResult:
+    """Install the bundled skill into a client skill directory."""
+
+    root = Path(target_dir) if target_dir is not None else default_skill_root(client, project)
+    destination = root / SKILL_NAME
+    source = _bundled_skill_path()
+
+    overwritten = destination.exists()
+    if overwritten:
+        if not force:
+            raise SkillInstallError(
+                f"Skill already exists at {destination}. Re-run with --force to replace it."
+            )
+        if not destination.is_dir():
+            raise SkillInstallError(f"Destination exists and is not a directory: {destination}")
+        shutil.rmtree(destination)
+
+    root.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source, destination)
+
+    return SkillInstallResult(
+        client=client,
+        destination=destination,
+        overwritten=overwritten,
+    )

apdf_cloud_cli-0.1.0/README.md

@@ -1,76 +0,0 @@
-# APDF Cloud CLI + MCP Tools
-
-Stage 1 exposes APDF storage and PDF operations through both a CLI
-and an MCP server.
-
-## Configuration
-
-Set credentials before running CLI commands or the MCP server:
-
-```powershell
-$env:ASPOSE_CLIENT_ID = "your-client-id"
-$env:ASPOSE_CLIENT_SECRET = "your-client-secret"
-```
-
-Optional environment variables:
-
-- `ASPOSE_BASE_URL`
-- `ASPOSE_SELF_HOST`
-- `ASPOSE_STORAGE_NAME`
-
-## CLI
-
-The canonical executable is `apdf-cloud-cli`. A shorter `apdf`
-alias is also installed for convenience.
-
-```powershell
-apdf-cloud-cli storage list /
-apdf-cloud-cli storage upload .\sample.pdf /sample.pdf
-apdf-cloud-cli storage download /sample.pdf .\sample.pdf
-apdf-cloud-cli pdf merge /a.pdf /b.pdf merged.pdf
-apdf-cloud-cli pdf extract-text sample.pdf --output sample.txt
-apdf-cloud-cli mcp serve
-```
-
-## Development
-
-Install the package with development dependencies:
-
-```powershell
-python -m pip install -e ".[dev]"
-```
-
-Run the default test suite:
-
-```powershell
-python -m pytest -q
-```
-
-Build and validate the package distributions:
-
-```powershell
-python -m build
-python -m twine check dist/*
-```
-
-## Publishing
-
-Publishing is handled by GitHub Actions with PyPI trusted publishing.
-
-1. In PyPI, add a trusted publisher for repository
-   `andruhovski/apdf-tools`, workflow `publish.yml`, environment `pypi`,
-   and project name `apdf-cloud-cli`.
-2. Update the version in `pyproject.toml` and
-   `src/apdf_cloud_cli/__init__.py`.
-3. Push a matching version tag, for example:
-
-```powershell
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-## Stage 2 Roadmap
-
-- Split PDF files
-- Extract images from PDF files
-- Extract tables from PDF files