ocloud 0.1.0__tar.gz

ocloud-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+bandit-report.json
+
+# Build artifacts
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+.env
+
+# IDE and operating system
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Cloud credentials and local configuration
+.aws/
+.azure/
+.config/gcloud/
+*.pem
+*.key

ocloud-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes are recorded here. OCloud follows [Semantic Versioning](https://semver.org/) and the [Keep a Changelog](https://keepachangelog.com/) format.
+
+## [Unreleased]
+
+### Changed
+- Documented Azure Functions invocation as unsupported in the CLI MVP. Azure CLI does not provide a generic function-invocation command; OCloud now raises `UnsupportedOperationError` instead of issuing a metadata request.
+- Migrated GCP storage service commands from `gsutil` to `gcloud storage`.
+
+### Added
+- Unit coverage for provider routing, command construction, CLI availability, timeout handling, temporary Lambda response files, and unified APIs.
+- Project security policy, architecture and provider documentation, pre-commit configuration, CI, security scanning, and a manually dispatched Trusted Publishing release workflow.
+
+## [0.1.0] - 2026-08-22
+
+### Added
+- Synchronous command model, safe CLI executor, structured results, validation, and redacted logging.
+- Provider clients for selected AWS S3/EC2/Lambda, Azure Blob Storage/VM/Functions, and GCP Cloud Storage/Compute Engine/Cloud Functions operations.
+- Advanced provider-only raw CLI APIs using argument lists.
+- A narrow unified `Cloud` facade for common storage, compute, and serverless lifecycle routing.
+
+### Security
+- No cloud credential storage or automatic cloud CLI installation.
+- Shell-free subprocess execution, timeout handling, CLI discovery, and secret-redaction utilities.
+
+### Verification status
+- Unit tested with mocked CLIs; real-cloud integration testing has not been performed or claimed.

ocloud-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in the OCloud community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people.
+- Respecting differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility and apologizing to those affected by mistakes.
+- Focusing on what is best for the overall community.
+
+Examples of unacceptable behavior include:
+
+- Sexualized language, imagery, or attention; sexual advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Conduct that is reasonably considered inappropriate in a professional setting.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior. They may take appropriate and fair corrective action in response to behavior they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders may remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that do not align with this Code of Conduct. Reasons for moderation decisions will be communicated when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and also applies when an individual is officially representing the OCloud community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers through the repository's private security reporting channel. All complaints will be reviewed and investigated promptly and fairly.
+
+Maintainers will respect the privacy and security of the reporter. A report may result in a private warning, a public warning, temporary restrictions, or permanent removal from community spaces, depending on the severity and pattern of behavior.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

ocloud-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to OCloud
+
+Thank you for helping improve OCloud. By participating, you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+```bash
+git clone https://github.com/THE-S0HAM/ocloud.git
+cd ocloud
+python -m venv .venv
+# Windows PowerShell: .venv\Scripts\Activate.ps1
+# POSIX: source .venv/bin/activate
+python -m pip install -e ".[dev]"
+pre-commit install
+```
+
+Cloud CLIs and cloud credentials are optional for unit testing. Do not add credentials, tokens, profiles, or cloud account IDs to commits, test fixtures, or examples.
+
+## Required validation
+
+```bash
+ruff format --check .
+ruff check .
+mypy src/ocloud
+pytest --cov=ocloud --cov-report=term-missing
+bandit -r src/ocloud -q
+python -m build
+python -m twine check dist/*
+```
+
+Tests must validate commands, arguments, routing, results, errors, and security behavior. Unit tests must mock subprocess/CLI behavior and require no cloud account. Put real-cloud tests behind an explicit `integration` marker and document their setup.
+
+## Design rules
+
+- Use the shared command/result/executor layer; never add direct `subprocess` calls in services.
+- Never use `shell=True` or construct a shell command string.
+- Validate public input and return `CommandResult` for executed operations.
+- Use OCloud exceptions for expected failures.
+- Keep provider-specific concepts explicit rather than forcing false cross-cloud equivalence.
+- Update user-facing documentation, examples, and `CHANGELOG.md` with public API changes.
+
+## Pull requests
+
+Use a focused branch and submit a PR that explains user impact, security implications, and validation performed. Do not commit generated `dist/`, coverage, or environment files. Maintainers review for correctness, security, API stability, documentation, and test quality before merge.
+
+## Reporting issues
+
+Use GitHub issues for reproducible bugs and feature proposals. Use the [private security reporting channel](SECURITY.md) for suspected vulnerabilities; do not disclose them publicly.
+
+Contributions are licensed under the [MIT License](LICENSE).

ocloud-0.1.0/LICENSE

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

ocloud-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: ocloud
+Version: 0.1.0
+Summary: A production-grade Python library for unified cloud management across AWS, Azure, and GCP
+Project-URL: Homepage, https://github.com/THE-S0HAM/ocloud
+Project-URL: Repository, https://github.com/THE-S0HAM/ocloud
+Project-URL: Documentation, https://github.com/THE-S0HAM/ocloud/tree/main/docs
+Project-URL: Issues, https://github.com/THE-S0HAM/ocloud/issues
+Project-URL: Changelog, https://github.com/THE-S0HAM/ocloud/blob/main/CHANGELOG.md
+Author: OCloud Contributors
+License: MIT
+License-File: LICENSE
+Keywords: aws,azure,blob,cli,cloud,cloud-management,ec2,functions,gcp,lambda,s3,vm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+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: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: bandit==1.8.3; extra == 'dev'
+Requires-Dist: build==1.2.2.post1; extra == 'dev'
+Requires-Dist: mypy==1.15.0; extra == 'dev'
+Requires-Dist: pre-commit==4.1.0; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==8.4.2; extra == 'dev'
+Requires-Dist: ruff==0.9.10; extra == 'dev'
+Requires-Dist: twine==7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OCloud
+
+[![CI](https://github.com/THE-S0HAM/ocloud/actions/workflows/ci.yml/badge.svg)](https://github.com/THE-S0HAM/ocloud/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/ocloud.svg)](https://pypi.org/project/ocloud/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**OCloud** is a lightweight, synchronous Python library for managing selected AWS, Azure, and Google Cloud resources through their official CLI tools. It provides a typed provider API, a deliberately narrow unified API, structured command results, and an advanced provider-only raw CLI escape hatch.
+
+## What OCloud does
+
+- Runs only the official `aws`, `az`, and `gcloud` executables—no cloud SDK dependency or credential store.
+- Safely invokes subprocesses with argument lists; it never uses `shell=True`.
+- Captures redacted stdout, stderr, exit code, parsed JSON where applicable, and redacted command metadata.
+- Provides storage, compute, and serverless lifecycle helpers for the documented MVP surface.
+
+## Install and authenticate
+
+```bash
+python -m pip install ocloud
+aws configure       # AWS users
+az login            # Azure users
+gcloud auth login   # Google Cloud users
+```
+
+Install the provider CLI separately; OCloud does not install it. Python 3.10–3.13 is supported.
+
+## Quick start
+
+```python
+from ocloud import AWS
+
+aws = AWS()
+aws.auth.check_status()
+result = aws.s3.put_object_acl(
+    bucket="my-bucket",
+    key="path/to/file.pdf",
+    acl="public-read",
+)
+
+if result.success:
+    print(result.data)
+else:
+    print(result.stderr)
+```
+
+## Unified API
+
+Use `Cloud` for operations with genuinely shared semantics. Provider-specific context remains explicit.
+
+```python
+from ocloud import Cloud
+
+cloud = Cloud("aws")
+result = cloud.storage.upload(
+    file="document.pdf",
+    bucket="my-bucket",
+    key="documents/document.pdf",
+    timeout=60,
+)
+```
+
+## Provider APIs
+
+| Provider | Storage | Compute | Serverless |
+| --- | --- | --- | --- |
+| AWS | S3 upload/download/delete/list/exists/ACL | EC2 start/stop/restart/status | Lambda deploy/invoke/status/delete |
+| Azure | Blob upload/download/delete/list/exists | VM start/stop/restart/status | Function App ZIP deploy; Function status/delete |
+| GCP | Cloud Storage upload/download/delete/list/exists | Compute Engine start/stop/restart/status | Cloud Functions deploy/invoke/status/delete |
+
+Azure Functions has no generic Azure CLI invocation command. OCloud explicitly raises `UnsupportedOperationError` for that operation rather than misrepresenting a metadata request as an invocation.
+
+### Advanced raw CLI API
+
+Use this only for provider operations not exposed by the MVP. It accepts arguments, not a shell string.
+
+```python
+from ocloud import AWS
+
+result = AWS().raw(
+    "s3api", "put-object-acl", "--bucket", "my-bucket",
+    "--key", "path/to/file.pdf", "--acl", "public-read",
+)
+```
+
+## Results and errors
+
+Every executed operation returns `CommandResult` with `success`, `returncode`, redacted `stdout`, redacted `stderr`, `data`, `command`, `provider`, and `operation`. The package raises OCloud-specific exceptions for unavailable CLIs, authentication checks, invalid parameters, unsupported operations, and timeouts.
+
+```python
+from ocloud import AWS, CLINotFoundError, OCloudTimeoutError
+
+try:
+    result = AWS().s3.list("my-bucket", timeout=30)
+except CLINotFoundError:
+    print("Install AWS CLI and ensure it is on PATH.")
+except OCloudTimeoutError:
+    print("The provider command exceeded its timeout.")
+```
+
+## Security
+
+Authentication stays in the official cloud CLI. OCloud has no credential database and redacts common secret patterns from command metadata and diagnostics. Use least-privilege cloud identities; avoid secrets in raw arguments. See [SECURITY.md](SECURITY.md) and [docs/security.md](docs/security.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pre-commit install
+ruff format --check .
+ruff check .
+mypy src/ocloud
+pytest --cov=ocloud --cov-report=term-missing
+python -m build
+```
+
+Unit tests use mocks and need no cloud account. The opt-in integration suite verifies only selected provider CLI authentication and performs no resource mutation; see [Testing](docs/testing.md).
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Installation](docs/installation.md)
+- [Authentication](docs/authentication.md)
+- [Architecture](docs/architecture.md)
+- [Testing](docs/testing.md)
+- [Provider guides](docs/providers/)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Project status and roadmap
+
+`0.1.0` is an alpha API. The repository has mocked unit coverage and successful package validation. AWS, Azure, and GCP CLI authentication were manually verified through OCloud on a Windows host; GCP validation used its SDK `bin` directory on `PATH` for the validation process. No cloud-resource integration validation has been performed. Planned work includes opt-in integration environments, stronger provider error classification, more services, native SDK adapters, and async execution.
+
+OCloud is released under the [MIT License](LICENSE). See [CHANGELOG.md](CHANGELOG.md) for release history.

ocloud-0.1.0/README.md

@@ -0,0 +1,133 @@
+# OCloud
+
+[![CI](https://github.com/THE-S0HAM/ocloud/actions/workflows/ci.yml/badge.svg)](https://github.com/THE-S0HAM/ocloud/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/ocloud.svg)](https://pypi.org/project/ocloud/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**OCloud** is a lightweight, synchronous Python library for managing selected AWS, Azure, and Google Cloud resources through their official CLI tools. It provides a typed provider API, a deliberately narrow unified API, structured command results, and an advanced provider-only raw CLI escape hatch.
+
+## What OCloud does
+
+- Runs only the official `aws`, `az`, and `gcloud` executables—no cloud SDK dependency or credential store.
+- Safely invokes subprocesses with argument lists; it never uses `shell=True`.
+- Captures redacted stdout, stderr, exit code, parsed JSON where applicable, and redacted command metadata.
+- Provides storage, compute, and serverless lifecycle helpers for the documented MVP surface.
+
+## Install and authenticate
+
+```bash
+python -m pip install ocloud
+aws configure       # AWS users
+az login            # Azure users
+gcloud auth login   # Google Cloud users
+```
+
+Install the provider CLI separately; OCloud does not install it. Python 3.10–3.13 is supported.
+
+## Quick start
+
+```python
+from ocloud import AWS
+
+aws = AWS()
+aws.auth.check_status()
+result = aws.s3.put_object_acl(
+    bucket="my-bucket",
+    key="path/to/file.pdf",
+    acl="public-read",
+)
+
+if result.success:
+    print(result.data)
+else:
+    print(result.stderr)
+```
+
+## Unified API
+
+Use `Cloud` for operations with genuinely shared semantics. Provider-specific context remains explicit.
+
+```python
+from ocloud import Cloud
+
+cloud = Cloud("aws")
+result = cloud.storage.upload(
+    file="document.pdf",
+    bucket="my-bucket",
+    key="documents/document.pdf",
+    timeout=60,
+)
+```
+
+## Provider APIs
+
+| Provider | Storage | Compute | Serverless |
+| --- | --- | --- | --- |
+| AWS | S3 upload/download/delete/list/exists/ACL | EC2 start/stop/restart/status | Lambda deploy/invoke/status/delete |
+| Azure | Blob upload/download/delete/list/exists | VM start/stop/restart/status | Function App ZIP deploy; Function status/delete |
+| GCP | Cloud Storage upload/download/delete/list/exists | Compute Engine start/stop/restart/status | Cloud Functions deploy/invoke/status/delete |
+
+Azure Functions has no generic Azure CLI invocation command. OCloud explicitly raises `UnsupportedOperationError` for that operation rather than misrepresenting a metadata request as an invocation.
+
+### Advanced raw CLI API
+
+Use this only for provider operations not exposed by the MVP. It accepts arguments, not a shell string.
+
+```python
+from ocloud import AWS
+
+result = AWS().raw(
+    "s3api", "put-object-acl", "--bucket", "my-bucket",
+    "--key", "path/to/file.pdf", "--acl", "public-read",
+)
+```
+
+## Results and errors
+
+Every executed operation returns `CommandResult` with `success`, `returncode`, redacted `stdout`, redacted `stderr`, `data`, `command`, `provider`, and `operation`. The package raises OCloud-specific exceptions for unavailable CLIs, authentication checks, invalid parameters, unsupported operations, and timeouts.
+
+```python
+from ocloud import AWS, CLINotFoundError, OCloudTimeoutError
+
+try:
+    result = AWS().s3.list("my-bucket", timeout=30)
+except CLINotFoundError:
+    print("Install AWS CLI and ensure it is on PATH.")
+except OCloudTimeoutError:
+    print("The provider command exceeded its timeout.")
+```
+
+## Security
+
+Authentication stays in the official cloud CLI. OCloud has no credential database and redacts common secret patterns from command metadata and diagnostics. Use least-privilege cloud identities; avoid secrets in raw arguments. See [SECURITY.md](SECURITY.md) and [docs/security.md](docs/security.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pre-commit install
+ruff format --check .
+ruff check .
+mypy src/ocloud
+pytest --cov=ocloud --cov-report=term-missing
+python -m build
+```
+
+Unit tests use mocks and need no cloud account. The opt-in integration suite verifies only selected provider CLI authentication and performs no resource mutation; see [Testing](docs/testing.md).
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Installation](docs/installation.md)
+- [Authentication](docs/authentication.md)
+- [Architecture](docs/architecture.md)
+- [Testing](docs/testing.md)
+- [Provider guides](docs/providers/)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Project status and roadmap
+
+`0.1.0` is an alpha API. The repository has mocked unit coverage and successful package validation. AWS, Azure, and GCP CLI authentication were manually verified through OCloud on a Windows host; GCP validation used its SDK `bin` directory on `PATH` for the validation process. No cloud-resource integration validation has been performed. Planned work includes opt-in integration environments, stronger provider error classification, more services, native SDK adapters, and async execution.
+
+OCloud is released under the [MIT License](LICENSE). See [CHANGELOG.md](CHANGELOG.md) for release history.

ocloud-0.1.0/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are applied to the latest released `0.x` version. OCloud is in active API development; upgrade promptly when a security release is published.
+
+## Reporting a vulnerability
+
+Do **not** open a public issue for a suspected vulnerability. Report it privately through the repository's [security advisory page](https://github.com/THE-S0HAM/ocloud/security/advisories/new). Include affected version, reproduction steps, impact, and any relevant logs with credentials removed.
+
+Maintainers will acknowledge reports within 7 days, assess impact, and coordinate a fix and disclosure timeline with the reporter.
+
+## Security model
+
+OCloud delegates authentication to the official AWS, Azure, and Google Cloud CLIs. It does not store cloud credentials, tokens, or profiles; install and authenticate the provider CLI yourself.
+
+Commands run with `subprocess.run()` using argument lists and never use `shell=True`. CLI executable discovery is performed with `shutil.which`. OCloud captures stdout, stderr, and exit status, applies caller-provided timeouts, and redacts common secret patterns before command metadata and diagnostic output are retained or logged.
+
+Use least-privilege cloud identities, do not enable debug logs in untrusted log sinks, and avoid placing secrets in raw CLI arguments. Treat raw provider APIs as advanced functionality: they execute only the selected provider CLI, but the underlying cloud operation can still change or expose resources.
+
+## Scope
+
+Report vulnerabilities in OCloud source, release artifacts, GitHub Actions, and documentation that could cause insecure use. Cloud CLI and provider account issues should be reported to the relevant vendor.

ocloud-0.1.0/docs/architecture.md

@@ -0,0 +1,32 @@
+# Architecture
+
+OCloud is a synchronous Python library that delegates cloud operations to officially supported provider CLIs. It keeps command construction separate from process execution so each layer remains testable and future adapters can replace the CLI boundary without changing public APIs.
+
+## Layers
+
+```text
+Public provider or Cloud API
+  -> input validation
+  -> provider service command construction
+  -> Command model
+  -> CLIExecutor
+  -> aws | az | gcloud
+```
+
+`Command` contains the executable, argument list, provider, operation name, timeout, and optional environment overlay. `CLIExecutor` discovers executables safely, invokes `subprocess.run` without a shell, captures output, applies timeouts, and produces `CommandResult`.
+
+## Result and errors
+
+Every executed command returns `CommandResult` with raw stdout/stderr, return code, success flag, redacted command metadata, provider/operation metadata, and parsed JSON where output is JSON. Missing CLIs and timeouts raise OCloud exceptions because no useful result can exist.
+
+Authentication is delegated to the CLI. `aws.auth.check_status()`, `azure.auth.check_status()`, and `gcp.auth.check_status()` run lightweight provider commands and raise `CLIAuthenticationError` on failure.
+
+## Provider and unified APIs
+
+Provider clients retain provider names and required context. The `Cloud` facade routes only common storage, compute, and lifecycle operations; provider-specific values such as Azure resource groups, storage accounts, GCP zones, and AWS IAM role ARNs remain explicit parameters.
+
+Azure Functions deployment is Function App ZIP deployment. Generic Azure Function invocation is intentionally unsupported: Azure CLI has no generic function-invocation command, so OCloud raises `UnsupportedOperationError` rather than issuing a metadata query and calling it an invocation.
+
+## Extension and async strategy
+
+Service methods depend on `CLIExecutor`, not `subprocess` directly. A future SDK adapter can implement the same command/result boundary or a compatible provider service without rewriting the public API. The synchronous executor is isolated, so a future async executor can be introduced alongside it without changing validation or service semantics.

ocloud-0.1.0/docs/authentication.md

@@ -0,0 +1,23 @@
+# Authentication
+
+OCloud delegates authentication to provider CLIs and never stores credentials or tokens.
+
+```bash
+aws configure
+az login
+gcloud auth login
+```
+
+Verify a configured identity without printing credentials:
+
+```python
+from ocloud import AWS, Azure, GCP
+
+AWS().auth.check_status()
+Azure().auth.check_status()
+GCP().auth.check_status()
+```
+
+Each method returns `True` when the underlying CLI verifies an identity and raises `CLIAuthenticationError` when authentication is unavailable or fails. `CLINotFoundError` indicates the provider CLI is not installed or not on `PATH`.
+
+Use provider-supported mechanisms for profiles, subscriptions, projects, workload identity, and credential renewal. OCloud passes through the process environment only when a caller explicitly configures a command environment internally; it does not create a credential database.

ocloud-0.1.0/docs/examples.md

@@ -0,0 +1,8 @@
+# Examples
+
+Examples require the corresponding official CLI to be installed and authenticated. They target real resources and may incur cloud-provider charges.
+
+- [AWS S3 object ACL](../examples/aws/s3_acl.py)
+- [AWS unified storage upload](../examples/unified/storage_upload.py)
+
+Before running an example, replace placeholder resource names and review its cloud-side permission and access implications. In particular, `public-read` exposes an object publicly when the bucket and provider policy allow it.

ocloud-0.1.0/docs/getting-started.md

@@ -0,0 +1,39 @@
+# Getting Started
+
+OCloud wraps a deliberately small set of official cloud CLI operations. It is not a replacement for the full provider CLIs; use `raw()` for advanced provider commands.
+
+## 1. Install prerequisites
+
+Install OCloud and at least one official provider CLI. See [installation.md](installation.md).
+
+## 2. Authenticate once
+
+```bash
+aws configure
+# or: az login
+# or: gcloud auth login
+```
+
+## 3. Verify the CLI and identity
+
+```python
+from ocloud import AWS
+
+aws = AWS()
+print(aws.is_available())
+aws.auth.check_status()
+```
+
+## 4. Run an operation
+
+```python
+result = aws.ec2.start_instance("i-0123456789abcdef0", timeout=60)
+if not result.success:
+    raise RuntimeError(result.stderr)
+```
+
+Use provider clients when a provider needs native context. For example, Azure VM operations require a resource group and GCP Compute Engine operations require a zone.
+
+## 5. Inspect the result
+
+`CommandResult` preserves raw output and parsed JSON where CLI output is JSON. Command metadata is redacted before it is stored in the result.

ocloud-0.1.0/docs/installation.md

@@ -0,0 +1,30 @@
+# Installation
+
+OCloud supports Python 3.10 through 3.13 and has no runtime Python dependencies.
+
+```bash
+python -m pip install ocloud
+```
+
+Install the official CLI for each provider you use; OCloud never installs these tools for you:
+
+- AWS: [AWS CLI](https://aws.amazon.com/cli/)
+- Azure: [Azure CLI](https://learn.microsoft.com/cli/azure/)
+- Google Cloud: [Google Cloud CLI](https://cloud.google.com/sdk/docs/install)
+
+Verify availability from Python before executing operations:
+
+```python
+from ocloud import AWS
+
+aws = AWS()
+if not aws.is_available():
+    raise RuntimeError("Install AWS CLI before continuing")
+```
+
+For development:
+
+```bash
+python -m pip install -e ".[dev]"
+pre-commit install
+```