laraship 1.3.0__tar.gz

laraship-1.3.0/.gitignore

@@ -0,0 +1,188 @@
+# AI-KIT v0.1: place this file at the project repository root.
+# Keep project source, migrations, ordinary docs, CI, and lockfiles under version control.
+
+# ---- AI-KIT and agent instructions (private, local to each checkout) ----
+AGENTS.md
+AGENTS.override.md
+CLAUDE.md
+KIMI.md
+MANUS.md
+GEMINI.md
+SKILL.md
+AI_CONTEXT.md
+PROJECT_CONTEXT.md
+BOOTSTRAP_PROMPT.md
+/WIKI.md
+/ai-kit/
+/.agents/
+/.ai/
+/.codex/
+/.cursor/
+/.windsurf/
+/.windsurfrules
+/.cursorrules
+/.github/copilot-instructions.md
+/.github/instructions/
+/.github/prompts/
+/.github/agents/
+/docs/DECISIONS.md
+/docs/adr/0000-template.md
+/AI-KIT*/
+
+# ---- Local secrets and credentials ----
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.dist
+!.env.*.dist
+.envrc
+auth.json
+/.secrets/
+/secrets/
+*.pem
+*.p12
+*.pfx
+*.private.key
+id_rsa*
+id_ed25519*
+
+# ---- OS, editor, and temporary files ----
+.DS_Store
+Thumbs.db
+Desktop.ini
+*.swp
+*.swo
+*~
+*.tmp
+*.bak
+.idea/
+.vscode/
+.fleet/
+.history/
+
+# ---- Dependency installs and frontend build output ----
+vendor/
+node_modules/
+.npm/
+.pnpm-store/
+.yarn/cache/
+.yarn/unplugged/
+.yarn/install-state.gz
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+/build/
+/dist/
+/out/
+/tmp/
+/temp/
+
+# ---- PHP / Laravel ----
+.phpunit.cache/
+.phpunit.result.cache
+.phpactor.json
+/coverage/
+/clover.xml
+/phpunit-coverage.xml
+/bootstrap/cache/*.php
+/public/hot
+/public/storage
+/public/build/
+/public_html/hot
+/public_html/storage
+/public_html/build/
+/storage/*.key
+/storage/pail/
+/storage/logs/*
+!/storage/logs/.gitignore
+/storage/framework/cache/*
+!/storage/framework/cache/.gitignore
+/storage/framework/sessions/*
+!/storage/framework/sessions/.gitignore
+/storage/framework/views/*
+!/storage/framework/views/.gitignore
+/storage/app/public/*
+!/storage/app/public/.gitignore
+/storage/app/private/*
+!/storage/app/private/.gitignore
+/database/database.sqlite
+/database/database.sqlite-*
+
+# ---- Moodle installation (do not ignore plugin source) ----
+/config.php
+/behat.yml
+/moodledata/
+/behat_dataroot/
+/phpunit_dataroot/
+/moodle-plugin-ci.phar
+
+# ---- Go build, profiling, and coverage output ----
+go-cache
+.go-cache
+gocache
+.gocache
+go-build
+.go-build
+/.cache/go-build/
+/pkg/mod/
+/go/pkg/mod/
+*.exe
+*.exe~
+*.test
+*.out
+*.prof
+*.coverprofile
+/cpu.prof
+/mem.prof
+/bin/
+
+# ---- Python environments, caches, and generated packages ----
+.venv/
+venv/
+__pypackages__/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+.hypothesis/
+.tox/
+.nox/
+.ipynb_checkpoints/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.egg-info/
+.eggs/
+*.egg
+*.whl
+pip-wheel-metadata/
+pip-log.txt
+pip-delete-this-directory.txt
+/.cache/pip/
+/.cache/uv/
+/.cache/pypoetry/
+.pypirc
+
+# ---- Local containers, logs, dumps, and backups ----
+/docker-compose.override.yml
+/docker-compose.override.yaml
+*.log
+*.dump
+*.sql.gz
+/dumps/
+/backups/
+
+# Deliberately track README.md, CHANGELOG.md, ordinary project docs,
+# composer.lock, go.mod, go.sum, pyproject.toml, Python lockfiles,
+# requirements files, package lockfiles, source code,
+# database migrations, and .github/workflows/.
+# For a reusable PHP library that intentionally does not track its lockfile,
+# uncomment the next line in that library only:
+# /composer.lock

laraship-1.3.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: laraship
+Version: 1.3.0
+Summary: Install and run LaraShip through its native Bash toolkit or Docker CLI image.
+Project-URL: Homepage, https://shellharbor.github.io/laraship-docs/
+Project-URL: Documentation, https://github.com/shellharbor/laraship/blob/main/docs/PYTHON.md
+Project-URL: Source, https://github.com/shellharbor/laraship
+Project-URL: Issues, https://github.com/shellharbor/laraship/issues
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# LaraShip Python CLI
+
+Install and run LaraShip through its native Bash toolkit or published Docker CLI image. The Python package uses Python 3.10+ and has no runtime Python dependencies. It preserves the existing deployment, locking, backup and recovery behavior by calling the existing tools.
+
+The package does not install Docker, deploy an application or modify a server during `pip install`. Those operations require explicit CLI commands. Native deployments target Ubuntu 20.04+; Docker server operations target the same Linux server and its local Docker Engine. Package help and installation previews are available without root. This package does not make server deployment work directly on Windows or macOS; connect to the server over SSH.
+
+## Install with pip or pipx
+
+Version 1.3.0 introduces the Python package. The commands below install that release once it is published on PyPI; a reviewed source checkout can also be installed with `pipx install .` or `python -m pip install .` inside a virtual environment. Older tags, including v1.2.2, predate Python packaging and must not be moved to publish it.
+
+For an isolated command available on PATH, use pipx:
+
+```bash
+pipx install laraship==1.3.0
+laraship --version
+laraship --help
+```
+
+Alternatively, use pip in a virtual environment:
+
+```bash
+python3 -m venv "$HOME/.venvs/laraship"
+"$HOME/.venvs/laraship/bin/python" -m pip install laraship==1.3.0
+"$HOME/.venvs/laraship/bin/laraship" --help
+```
+
+Install the distribution-provided Python/venv or pipx packages first if these tools are missing. Keep the operating system's Python environment managed by the OS; do not use `sudo pip` or `--break-system-packages`. See the [PyPA CLI installation guide](https://packaging.python.org/en/latest/guides/installing-stand-alone-command-line-tools/).
+
+## Native backend
+
+Install downloads the exact GitHub release archive and SHA-256 file over HTTPS, validates the checksum and archive members, checks the embedded VERSION, then copies the complete toolkit into a new directory. Existing files, directories and symlink paths are refused. Downloads use private temporary files with size/time limits. Archive traversal, links, devices, duplicate entries and excessive expansion are rejected.
+
+```bash
+laraship install --backend native --version 1.3.0 --dry-run
+
+# Use the absolute executable path because sudo may not include pipx in PATH.
+LARASHIP_CLI="$(command -v laraship)"
+sudo "$LARASHIP_CLI" install --backend native --version 1.3.0
+laraship toolkit-version
+
+sudo "$LARASHIP_CLI" deploy --backend native -- \
+  --slug shop --domain shop.example.com --db-type postgres \
+  --ssl-email admin@example.com
+```
+
+The default native directory is `/opt/laraship`. Use `--directory /absolute/new/path` on install and subsequent commands for another location. Its parent must exist. A partial copy caused by a disk/permission failure is retained for inspection; a rerun refuses that path. The installer does not overwrite or automatically resume it. Checksums establish consistency with GitHub's published release assets; they are not independent signatures.
+
+The native toolkit retains its existing prerequisites and ability to install Docker when deploying. Installing the toolkit alone does not install server dependencies. See the [server requirements and deployment guide](https://github.com/shellharbor/laraship#requirements).
+
+## Docker backend
+
+Install Docker Engine and Compose v2 on the server and start the daemon first. This backend does not install a host daemon or run Docker-in-Docker.
+
+```bash
+laraship install --backend docker --version 1.3.0
+laraship toolkit-version --backend docker --image shellharbor/laraship:1.3.0
+
+# Informational flags go first after --; no server mounts are needed.
+laraship deploy --backend docker --image shellharbor/laraship:1.3.0 -- \
+  --dry-run --domain shop.example.com --db-type postgres --no-ssl
+
+LARASHIP_CLI="$(command -v laraship)"
+sudo "$LARASHIP_CLI" deploy --backend docker --image shellharbor/laraship:1.3.0 -- \
+  --slug shop --domain shop.example.com --db-type postgres \
+  --ssl-email admin@example.com
+```
+
+The default image is `shellharbor/laraship:<package release>`. Installing another release does not change this default; select that image with `--image` on subsequent commands. Exact version tags and SHA-256 digests are accepted; mutable aliases such as `latest` are refused. Registry version tags can still be overwritten by their owner; use a digest when immutability is required.
+
+Server operations require root, the local `/var/run/docker.sock`, host networking and identical writable host binds for `/var/www`, `/run/lock/laraship`, the Docker socket and `/var/backups/laraship`. The three directories are created if absent after mount validation. `--archive-dir /absolute/path` changes the archive directory and its bind. Remote Docker hosts and explicit Docker contexts are refused; server commands explicitly select the local Unix socket, including when Docker has a saved default context.
+
+Expose configuration files, SSH keys or other host inputs explicitly with repeatable `--mount-readonly /absolute/path`. The path is mounted at the same absolute location. Mounts that hide the packaged CLI or required server paths are refused:
+
+```bash
+sudo "$LARASHIP_CLI" deploy --backend docker --image shellharbor/laraship:1.3.0 \
+  --mount-readonly /root/laraship-input -- \
+  --config /root/laraship-input/shop.conf
+```
+
+For inspection without server-state mounts, put `--help`, `--version`, `--list-modules`, `--list-presets` or `--dry-run` first after `--` on `deploy`. The image then runs without networking, with a read-only root filesystem and writable `/tmp`; explicit `--mount-readonly` inputs remain available for configuration/hook validation. The command `toolkit-version` uses the same isolation. Ordinary server commands retain the [administrative Docker adapter's existing permissions and limitations](https://github.com/shellharbor/laraship/blob/main/docs/CONTAINERS.md); this is not an application Pod or a Kubernetes installation backend. Native host database provisioning remains unsupported by the Docker adapter.
+
+## Commands and argument forwarding
+
+```text
+laraship --version
+laraship install [--backend native|docker] [--version RELEASE] [--dry-run]
+laraship toolkit-version [--backend native|docker]
+laraship deploy|update|backup|activate|deactivate|remove|list [adapter options] -- [backend arguments]
+```
+
+Native is the default backend. Adapter options precede `--`; all following values are forwarded unchanged as individual arguments, without shell interpolation. Backend output, terminal input, signals and exit status go directly to/from the backend process. The Python adapter does not print the forwarded argument list. Existing backend messages and credential handling remain governed by that backend.
+
+```bash
+sudo "$LARASHIP_CLI" backup -- --slug shop now
+sudo "$LARASHIP_CLI" update -- --slug shop
+sudo "$LARASHIP_CLI" list --backend docker
+```
+
+CLI parsing errors exit with 2; installer/preflight errors exit with 1; cancellation during installation exits with 130. Executed backends retain their own status. The installer has no interactive prompts or implicit sudo escalation.
+
+## Updates and removal
+
+Use `pipx upgrade laraship` or upgrade the package with pip inside its environment. This updates the Python adapter only. It does not modify deployed projects, database volumes or an existing native toolkit directory. The Docker default follows the newly installed package version; keep `--image` explicit to retain a selected runtime.
+
+For native toolkit upgrades, install into a new directory and select it with `--directory`. Follow the release's manual template migration and recovery guidance. Remove the Python CLI with `pipx uninstall laraship` or pip in the environment; toolkit files and deployed projects remain in place. Project deletion stays an explicit `laraship remove -- ...` operation.
+
+## Build and verify locally
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -r requirements-python-build.txt
+python -m unittest discover -s tests -p 'test_python_cli.py' -v
+python -m build
+python -m twine check --strict dist/*
+python .github/scripts/check-python-dist.py dist "$(cat VERSION)"
+```
+
+CI additionally rebuilds the wheel from the source distribution, installs with pip and pipx in fresh environments and executes the installed CLI. Backend behavior tests substitute external services; real smoke checks should distinguish package installation/command forwarding from a full Laravel deployment.
+
+## Publish to PyPI
+
+The existing **Release** workflow builds the Python distributions after its GitHub release and exact-commit CI gate succeed, then publishes from a separate `pypi` job with GitHub OIDC. The publish job only downloads the previously checked distributions and invokes the official PyPA action; it does not check out or execute repository build code. All new third-party action references are pinned to verified commit SHAs.
+
+Before the first publication:
+
+1. Create a PyPI account and configure its required account security. The name `laraship` returned HTTP 404 during the 2026-10-22 check; this does not reserve the name or guarantee PyPI will allow it.
+2. In [PyPI pending publishers](https://pypi.org/manage/account/publishing/), add project **laraship**, GitHub owner **shellharbor**, repository **laraship**, workflow **release.yml**, and environment **pypi**. For an existing project, add the same Trusted Publisher under its publishing settings.
+3. Create GitHub environment **pypi**. Restrict it to release tags and the default branch used for manual release retries; configure required reviewers if desired.
+4. Set GitHub Actions repository **Variable** `PYPI_PUBLISH=true`. No PyPI token Secret is used. If this variable is absent, existing GitHub and Docker Hub publication behave as before and the Python publishing jobs skip.
+5. Commit the feature, prepare a **new release version** in VERSION/CHANGELOG, push it and wait for all required checks on that exact commit. Tests includes the Python package matrix. Tag the verified commit using the existing release process.
+
+For a failed publication, rerun the failed jobs. You can also dispatch **Release** for the existing new tag after fixing configuration. PyPI refuses replacement of published distribution filenames; successful files may be skipped by the publish action on retries. Do not change source code or move an existing tag to repair a published package. A code fix requires a new version.
+
+VERSION is the single version source for Bash, archives and the Python package. Python distribution filenames normalize prerelease versions according to PEP 440; metadata versions are compared by their PEP 440 identity. The wheel also records the exact original release spelling for GitHub asset names and Docker defaults. Existing tags without pyproject.toml cannot publish a Python package. Enabling this workflow and preparing files do not publish anything until the repository and PyPI settings are configured and a suitable release is run.
+
+References: [PyPA packaging guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/), [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/), [publisher action](https://github.com/pypa/gh-action-pypi-publish).

laraship-1.3.0/VERSION

@@ -0,0 +1 @@
+1.3.0

laraship-1.3.0/docs/PYTHON.md

@@ -0,0 +1,137 @@
+# LaraShip Python CLI
+
+Install and run LaraShip through its native Bash toolkit or published Docker CLI image. The Python package uses Python 3.10+ and has no runtime Python dependencies. It preserves the existing deployment, locking, backup and recovery behavior by calling the existing tools.
+
+The package does not install Docker, deploy an application or modify a server during `pip install`. Those operations require explicit CLI commands. Native deployments target Ubuntu 20.04+; Docker server operations target the same Linux server and its local Docker Engine. Package help and installation previews are available without root. This package does not make server deployment work directly on Windows or macOS; connect to the server over SSH.
+
+## Install with pip or pipx
+
+Version 1.3.0 introduces the Python package. The commands below install that release once it is published on PyPI; a reviewed source checkout can also be installed with `pipx install .` or `python -m pip install .` inside a virtual environment. Older tags, including v1.2.2, predate Python packaging and must not be moved to publish it.
+
+For an isolated command available on PATH, use pipx:
+
+```bash
+pipx install laraship==1.3.0
+laraship --version
+laraship --help
+```
+
+Alternatively, use pip in a virtual environment:
+
+```bash
+python3 -m venv "$HOME/.venvs/laraship"
+"$HOME/.venvs/laraship/bin/python" -m pip install laraship==1.3.0
+"$HOME/.venvs/laraship/bin/laraship" --help
+```
+
+Install the distribution-provided Python/venv or pipx packages first if these tools are missing. Keep the operating system's Python environment managed by the OS; do not use `sudo pip` or `--break-system-packages`. See the [PyPA CLI installation guide](https://packaging.python.org/en/latest/guides/installing-stand-alone-command-line-tools/).
+
+## Native backend
+
+Install downloads the exact GitHub release archive and SHA-256 file over HTTPS, validates the checksum and archive members, checks the embedded VERSION, then copies the complete toolkit into a new directory. Existing files, directories and symlink paths are refused. Downloads use private temporary files with size/time limits. Archive traversal, links, devices, duplicate entries and excessive expansion are rejected.
+
+```bash
+laraship install --backend native --version 1.3.0 --dry-run
+
+# Use the absolute executable path because sudo may not include pipx in PATH.
+LARASHIP_CLI="$(command -v laraship)"
+sudo "$LARASHIP_CLI" install --backend native --version 1.3.0
+laraship toolkit-version
+
+sudo "$LARASHIP_CLI" deploy --backend native -- \
+  --slug shop --domain shop.example.com --db-type postgres \
+  --ssl-email admin@example.com
+```
+
+The default native directory is `/opt/laraship`. Use `--directory /absolute/new/path` on install and subsequent commands for another location. Its parent must exist. A partial copy caused by a disk/permission failure is retained for inspection; a rerun refuses that path. The installer does not overwrite or automatically resume it. Checksums establish consistency with GitHub's published release assets; they are not independent signatures.
+
+The native toolkit retains its existing prerequisites and ability to install Docker when deploying. Installing the toolkit alone does not install server dependencies. See the [server requirements and deployment guide](https://github.com/shellharbor/laraship#requirements).
+
+## Docker backend
+
+Install Docker Engine and Compose v2 on the server and start the daemon first. This backend does not install a host daemon or run Docker-in-Docker.
+
+```bash
+laraship install --backend docker --version 1.3.0
+laraship toolkit-version --backend docker --image shellharbor/laraship:1.3.0
+
+# Informational flags go first after --; no server mounts are needed.
+laraship deploy --backend docker --image shellharbor/laraship:1.3.0 -- \
+  --dry-run --domain shop.example.com --db-type postgres --no-ssl
+
+LARASHIP_CLI="$(command -v laraship)"
+sudo "$LARASHIP_CLI" deploy --backend docker --image shellharbor/laraship:1.3.0 -- \
+  --slug shop --domain shop.example.com --db-type postgres \
+  --ssl-email admin@example.com
+```
+
+The default image is `shellharbor/laraship:<package release>`. Installing another release does not change this default; select that image with `--image` on subsequent commands. Exact version tags and SHA-256 digests are accepted; mutable aliases such as `latest` are refused. Registry version tags can still be overwritten by their owner; use a digest when immutability is required.
+
+Server operations require root, the local `/var/run/docker.sock`, host networking and identical writable host binds for `/var/www`, `/run/lock/laraship`, the Docker socket and `/var/backups/laraship`. The three directories are created if absent after mount validation. `--archive-dir /absolute/path` changes the archive directory and its bind. Remote Docker hosts and explicit Docker contexts are refused; server commands explicitly select the local Unix socket, including when Docker has a saved default context.
+
+Expose configuration files, SSH keys or other host inputs explicitly with repeatable `--mount-readonly /absolute/path`. The path is mounted at the same absolute location. Mounts that hide the packaged CLI or required server paths are refused:
+
+```bash
+sudo "$LARASHIP_CLI" deploy --backend docker --image shellharbor/laraship:1.3.0 \
+  --mount-readonly /root/laraship-input -- \
+  --config /root/laraship-input/shop.conf
+```
+
+For inspection without server-state mounts, put `--help`, `--version`, `--list-modules`, `--list-presets` or `--dry-run` first after `--` on `deploy`. The image then runs without networking, with a read-only root filesystem and writable `/tmp`; explicit `--mount-readonly` inputs remain available for configuration/hook validation. The command `toolkit-version` uses the same isolation. Ordinary server commands retain the [administrative Docker adapter's existing permissions and limitations](https://github.com/shellharbor/laraship/blob/main/docs/CONTAINERS.md); this is not an application Pod or a Kubernetes installation backend. Native host database provisioning remains unsupported by the Docker adapter.
+
+## Commands and argument forwarding
+
+```text
+laraship --version
+laraship install [--backend native|docker] [--version RELEASE] [--dry-run]
+laraship toolkit-version [--backend native|docker]
+laraship deploy|update|backup|activate|deactivate|remove|list [adapter options] -- [backend arguments]
+```
+
+Native is the default backend. Adapter options precede `--`; all following values are forwarded unchanged as individual arguments, without shell interpolation. Backend output, terminal input, signals and exit status go directly to/from the backend process. The Python adapter does not print the forwarded argument list. Existing backend messages and credential handling remain governed by that backend.
+
+```bash
+sudo "$LARASHIP_CLI" backup -- --slug shop now
+sudo "$LARASHIP_CLI" update -- --slug shop
+sudo "$LARASHIP_CLI" list --backend docker
+```
+
+CLI parsing errors exit with 2; installer/preflight errors exit with 1; cancellation during installation exits with 130. Executed backends retain their own status. The installer has no interactive prompts or implicit sudo escalation.
+
+## Updates and removal
+
+Use `pipx upgrade laraship` or upgrade the package with pip inside its environment. This updates the Python adapter only. It does not modify deployed projects, database volumes or an existing native toolkit directory. The Docker default follows the newly installed package version; keep `--image` explicit to retain a selected runtime.
+
+For native toolkit upgrades, install into a new directory and select it with `--directory`. Follow the release's manual template migration and recovery guidance. Remove the Python CLI with `pipx uninstall laraship` or pip in the environment; toolkit files and deployed projects remain in place. Project deletion stays an explicit `laraship remove -- ...` operation.
+
+## Build and verify locally
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -r requirements-python-build.txt
+python -m unittest discover -s tests -p 'test_python_cli.py' -v
+python -m build
+python -m twine check --strict dist/*
+python .github/scripts/check-python-dist.py dist "$(cat VERSION)"
+```
+
+CI additionally rebuilds the wheel from the source distribution, installs with pip and pipx in fresh environments and executes the installed CLI. Backend behavior tests substitute external services; real smoke checks should distinguish package installation/command forwarding from a full Laravel deployment.
+
+## Publish to PyPI
+
+The existing **Release** workflow builds the Python distributions after its GitHub release and exact-commit CI gate succeed, then publishes from a separate `pypi` job with GitHub OIDC. The publish job only downloads the previously checked distributions and invokes the official PyPA action; it does not check out or execute repository build code. All new third-party action references are pinned to verified commit SHAs.
+
+Before the first publication:
+
+1. Create a PyPI account and configure its required account security. The name `laraship` returned HTTP 404 during the 2026-10-22 check; this does not reserve the name or guarantee PyPI will allow it.
+2. In [PyPI pending publishers](https://pypi.org/manage/account/publishing/), add project **laraship**, GitHub owner **shellharbor**, repository **laraship**, workflow **release.yml**, and environment **pypi**. For an existing project, add the same Trusted Publisher under its publishing settings.
+3. Create GitHub environment **pypi**. Restrict it to release tags and the default branch used for manual release retries; configure required reviewers if desired.
+4. Set GitHub Actions repository **Variable** `PYPI_PUBLISH=true`. No PyPI token Secret is used. If this variable is absent, existing GitHub and Docker Hub publication behave as before and the Python publishing jobs skip.
+5. Commit the feature, prepare a **new release version** in VERSION/CHANGELOG, push it and wait for all required checks on that exact commit. Tests includes the Python package matrix. Tag the verified commit using the existing release process.
+
+For a failed publication, rerun the failed jobs. You can also dispatch **Release** for the existing new tag after fixing configuration. PyPI refuses replacement of published distribution filenames; successful files may be skipped by the publish action on retries. Do not change source code or move an existing tag to repair a published package. A code fix requires a new version.
+
+VERSION is the single version source for Bash, archives and the Python package. Python distribution filenames normalize prerelease versions according to PEP 440; metadata versions are compared by their PEP 440 identity. The wheel also records the exact original release spelling for GitHub asset names and Docker defaults. Existing tags without pyproject.toml cannot publish a Python package. Enabling this workflow and preparing files do not publish anything until the repository and PyPI settings are configured and a suitable release is run.
+
+References: [PyPA packaging guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/), [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/), [publisher action](https://github.com/pypa/gh-action-pypi-publish).

laraship-1.3.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "laraship"
+dynamic = ["version"]
+description = "Install and run LaraShip through its native Bash toolkit or Docker CLI image."
+readme = "docs/PYTHON.md"
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Environment :: Console",
+  "Operating System :: POSIX :: Linux",
+  "Topic :: System :: Installation/Setup",
+]
+
+[project.scripts]
+laraship = "laraship.cli:main"
+
+[project.urls]
+Homepage = "https://shellharbor.github.io/laraship-docs/"
+Documentation = "https://github.com/shellharbor/laraship/blob/main/docs/PYTHON.md"
+Source = "https://github.com/shellharbor/laraship"
+Issues = "https://github.com/shellharbor/laraship/issues"
+
+[tool.hatch.version]
+path = "VERSION"
+pattern = "(?P<version>[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.]+)?)"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/laraship", "/VERSION", "/pyproject.toml", "/docs/PYTHON.md", "/.gitignore"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/laraship"]
+
+[tool.hatch.build.targets.wheel.force-include]
+VERSION = "laraship/_release.txt"

laraship-1.3.0/src/laraship/__init__.py

@@ -0,0 +1,14 @@
+"""LaraShip's dependency-free installation and execution adapter."""
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+_release_file = Path(__file__).with_name("_release.txt")
+if not _release_file.is_file():
+    _release_file = Path(__file__).resolve().parents[2] / "VERSION"
+DEFAULT_RELEASE = _release_file.read_text(encoding="ascii").strip()
+
+try:
+    __version__ = version("laraship")
+except PackageNotFoundError:
+    __version__ = DEFAULT_RELEASE

laraship-1.3.0/src/laraship/__main__.py

@@ -0,0 +1,5 @@
+"""Allow python -m laraship."""
+
+from .cli import main
+
+raise SystemExit(main())

laraship-1.3.0/src/laraship/cli.py

@@ -0,0 +1,201 @@
+"""Install LaraShip and forward commands to its existing execution backends."""
+
+import argparse
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+from urllib.error import URLError
+
+from . import DEFAULT_RELEASE, __version__
+from .install import absolute_path, install_native, installation_path, release_version
+
+COMMANDS = {"deploy": "deploy-laravel.sh", "update": "update.sh", "backup": "backup.sh",
+            "activate": "activate.sh", "deactivate": "deactivate.sh", "remove": "remove.sh",
+            "list": "list-projects.sh", "toolkit-version": "deploy-laravel.sh"}
+SERVER_PATHS = ("/var/www", "/run/lock/laraship", "/var/run/docker.sock")
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(description=__doc__)
+    result.add_argument("--version", action="version", version=f"laraship {__version__}")
+    commands = result.add_subparsers(dest="command", required=True)
+    install = commands.add_parser("install", help="Install a release or pull its CLI image")
+    install.add_argument("--backend", choices=("native", "docker"), default="native")
+    install.add_argument("--version", dest="release", help="Exact toolkit release (defaults to the package version)")
+    install.add_argument("--directory", default="/opt/laraship", help="New native toolkit directory")
+    install.add_argument("--dry-run", action="store_true", help="Show the plan without network requests or writes")
+    for name in COMMANDS:
+        command = commands.add_parser(name, help=f"Run the existing {name} command")
+        command.add_argument("--backend", choices=("native", "docker"), default="native")
+        command.add_argument("--directory", default="/opt/laraship", help="Installed native toolkit directory")
+        command.add_argument("--image", help="Docker image with an exact release tag or SHA-256 digest")
+        command.add_argument("--archive-dir", default="/var/backups/laraship")
+        command.add_argument("--mount-readonly", action="append", default=[], metavar="ABSOLUTE_PATH",
+                             help="Expose an extra host file/directory at the same path in Docker")
+        command.add_argument("arguments", nargs=argparse.REMAINDER,
+                             help="Separate all backend arguments with --")
+    return result
+
+
+def image_reference(value: str) -> str:
+    repository = r"(?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*"
+    if re.fullmatch(repository + r"@sha256:[0-9a-f]{64}", value):
+        return value
+    if ":" not in value:
+        raise ValueError("Docker images require an exact release tag or SHA-256 digest")
+    name, tag = value.rsplit(":", 1)
+    if not re.fullmatch(repository, name):
+        raise ValueError("Invalid Docker image repository")
+    release_version(tag)
+    return value
+
+
+def require_linux() -> None:
+    if sys.platform != "linux":
+        raise ValueError("Run installation and server operations on the target Linux server over SSH")
+
+
+def require_docker(local: bool = False) -> None:
+    if not shutil.which("docker"):
+        raise ValueError("Docker is not installed; install Docker Engine and Compose v2 on the server first")
+    try:
+        command = ["docker", "--host", "unix:///var/run/docker.sock"] if local else ["docker"]
+        probe = subprocess.run([*command, "info", "--format", "{{.OSType}}"],
+                               capture_output=True, text=True, timeout=15, check=False)
+    except subprocess.TimeoutExpired as exc:
+        raise ValueError("Docker daemon check timed out") from exc
+    if probe.returncode or probe.stdout.strip() != "linux":
+        raise ValueError("A running Linux Docker daemon accessible to this user is required")
+
+
+def informational(command: str, arguments: list[str]) -> bool:
+    if command == "toolkit-version" or arguments == ["--help"]:
+        return True
+    return command == "deploy" and bool(arguments) and arguments[0] in (
+        "--dry-run", "--help", "-h", "--version", "-V", "--list-modules", "--list-presets")
+
+
+def docker_command(args: argparse.Namespace, arguments: list[str]) -> list[str]:
+    image = image_reference(args.image or f"shellharbor/laraship:{release_version(DEFAULT_RELEASE)}")
+    command = ["docker", "run", "--rm", "--init"]
+    if informational(args.command, arguments):
+        command += ["--network", "none", "--read-only", "--tmpfs", "/tmp"]
+    else:
+        require_linux()
+        if os.geteuid() != 0:
+            raise ValueError("Docker server operations require root; use sudo with the absolute CLI path")
+        if os.environ.get("DOCKER_HOST", "unix:///var/run/docker.sock") != "unix:///var/run/docker.sock":
+            raise ValueError("Server operations require the local /var/run/docker.sock daemon")
+        if os.environ.get("DOCKER_CONTEXT"):
+            raise ValueError("Unset DOCKER_CONTEXT; server operations require the local Docker daemon")
+        archive = absolute_path(args.archive_dir)
+        paths = (*SERVER_PATHS, str(archive))
+        protected_archives = (*SERVER_PATHS, "/opt/laraship", "/usr", "/bin", "/etc")
+        if any(archive == Path(p) or archive in Path(p).parents or Path(p) in archive.parents
+               for p in protected_archives):
+            raise ValueError("Archive directory must be separate from server mounts and runtime paths")
+        for value in paths:
+            path = absolute_path(value)
+            if any(part.is_symlink() and not (part == Path("/var/run") and part.resolve() == Path("/run"))
+                   for part in (path, *path.parents)):
+                raise ValueError("Docker server mount paths must not contain symbolic links")
+        if not Path("/var/run/docker.sock").exists():
+            raise ValueError("The local /var/run/docker.sock is missing")
+        # Ignore the user's saved default Docker context for host-mutating operations.
+        command[1:1] = ["--host", "unix:///var/run/docker.sock"]
+        command += ["--interactive"]
+        if sys.stdin.isatty() and sys.stdout.isatty():
+            command += ["--tty"]
+        command += ["--network", "host", "--env", f"LARASHIP_ARCHIVE_DIR={archive}"]
+        for value in paths:
+            command += ["--mount", f"type=bind,src={value},dst={value}"]
+    if args.mount_readonly:
+        require_linux()
+        protected = (*SERVER_PATHS, str(absolute_path(args.archive_dir)), "/opt/laraship", "/usr", "/bin", "/etc")
+        for value in args.mount_readonly:
+            path = absolute_path(value)
+            if not path.exists() or any(path == Path(p) or path in Path(p).parents for p in protected):
+                raise ValueError("Additional read-only mount is missing or shadows a protected path")
+            command += ["--mount", f"type=bind,src={path},dst={path},readonly"]
+    backend = "--version" if args.command == "toolkit-version" else args.command
+    return [*command, image, backend, *arguments]
+
+
+def native_command(args: argparse.Namespace, arguments: list[str]) -> list[str]:
+    require_linux()
+    root = absolute_path(args.directory)
+    if (root / ".laraship-installing").exists():
+        raise ValueError("Native toolkit installation is incomplete; inspect it before use")
+    if not (root / "VERSION").is_file() or not (root / COMMANDS[args.command]).is_file():
+        raise ValueError("Native toolkit is missing; run 'laraship install' or select --directory")
+    if not shutil.which("bash"):
+        raise ValueError("Bash is required for the native backend")
+    backend_args = ["--version"] if args.command == "toolkit-version" else arguments
+    return ["bash", str(root / COMMANDS[args.command]), *backend_args]
+
+
+def execute(command: list[str]) -> int:
+    """Replace the adapter so the backend receives signals, terminal I/O and exit status."""
+    os.execvp(command[0], command)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "install":
+            version = release_version(args.release or DEFAULT_RELEASE)
+            if args.backend == "native":
+                destination = installation_path(args.directory)
+                if args.dry_run:
+                    print(f"Would download and verify LaraShip {version}, then install into {destination}")
+                    return 0
+                require_linux()
+                install_native(version, str(destination))
+                print(f"Installed LaraShip {version} into {destination}")
+            else:
+                image = f"shellharbor/laraship:{version}"
+                if args.dry_run:
+                    print(f"Would pull {image}; no deployment or host setup would run")
+                    return 0
+                require_linux()
+                require_docker()
+                result = subprocess.run(["docker", "pull", image], check=False)
+                if result.returncode:
+                    return result.returncode
+                print(f"Pulled {image}; select --backend docker when running commands")
+            return 0
+        arguments = args.arguments[1:] if args.arguments[:1] == ["--"] else args.arguments
+        if args.command == "toolkit-version" and arguments:
+            raise ValueError("toolkit-version does not accept backend arguments")
+        if args.backend == "docker":
+            # Reject invalid references before contacting Docker or changing host paths.
+            if args.image:
+                image_reference(args.image)
+            command = docker_command(args, arguments)
+            inspect_only = informational(args.command, arguments)
+            require_docker(local=not inspect_only)
+            if not inspect_only:
+                # All arguments, mounts and the local daemon were checked before writes.
+                for value in ("/var/www", "/run/lock/laraship", args.archive_dir):
+                    absolute_path(value).mkdir(parents=True, exist_ok=True)
+        else:
+            if args.image or args.mount_readonly:
+                raise ValueError("--image and --mount-readonly require --backend docker")
+            command = native_command(args, arguments)
+        return execute(command)
+    except KeyboardInterrupt:
+        print("LaraShip operation cancelled", file=sys.stderr)
+        return 130
+    except (ValueError, OSError, URLError, tarfile.TarError, shutil.Error) as exc:
+        # Backend commands inherit stdout/stderr; never stringify their argument lists.
+        print(f"LaraShip: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

laraship-1.3.0/src/laraship/install.py

@@ -0,0 +1,163 @@
+"""Download, verify and install an explicit official LaraShip release."""
+
+import hashlib
+import gzip
+import os
+from pathlib import Path, PurePosixPath
+import re
+import shutil
+import tarfile
+import tempfile
+import time
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, build_opener
+
+MAX_DOWNLOAD = 64 * 1024 * 1024
+MAX_EXPANDED = 128 * 1024 * 1024
+MAX_MEMBERS = 20000
+RELEASE_PATTERN = r"[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?"
+REQUIRED_FILES = ("VERSION", "versions.env", "deploy-laravel.sh", "update.sh",
+                  "backup.sh", "activate.sh", "deactivate.sh", "remove.sh",
+                  "list-projects.sh", "lib/runtime.sh", "laravel/docker-compose.yml",
+                  "nginxproxy/nginx.conf")
+
+
+def release_version(value: str) -> str:
+    """Accept release filenames, without path components or mutable aliases."""
+    if not re.fullmatch(RELEASE_PATTERN, value):
+        raise ValueError("Use an exact release version, for example 1.2.2 or 1.3.0-rc.1")
+    return value
+
+
+def absolute_path(value: str) -> Path:
+    path = Path(value).expanduser()
+    if not path.is_absolute() or ".." in path.parts or any(c in str(path) for c in "\x00\r\n,"):
+        raise ValueError("Use an absolute path without '..', commas or control characters")
+    return path
+
+
+def installation_path(value: str) -> Path:
+    destination = absolute_path(value)
+    for path in (destination, *destination.parents):
+        if path.is_symlink():
+            raise ValueError("Installation paths must not contain symbolic links")
+    if destination.exists():
+        raise ValueError("Installation path already exists; choose a new directory with --directory")
+    if not destination.parent.is_dir():
+        raise ValueError("Installation parent directory must already exist")
+    return destination
+
+
+class HTTPSRedirects(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if urlsplit(newurl).scheme != "https":
+            raise ValueError("Refusing a download redirect without HTTPS")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def download(url: str, destination: Path, limit: int = MAX_DOWNLOAD) -> None:
+    """Bound network operations and stream into an exclusively created private file."""
+    if urlsplit(url).scheme != "https":
+        raise ValueError("Release downloads require HTTPS")
+    started = time.monotonic()
+    opener = build_opener(HTTPSRedirects())
+    with opener.open(url, timeout=30) as response:
+        with destination.open("xb") as output:
+            os.chmod(destination, 0o600)
+            total = 0
+            while chunk := response.read(65536):
+                total += len(chunk)
+                if total > limit or time.monotonic() - started > 180:
+                    raise ValueError("Release download exceeded its size or time limit")
+                output.write(chunk)
+
+
+def verify_checksum(archive: Path, checksum: Path, filename: str) -> None:
+    text = checksum.read_text(encoding="ascii").strip()
+    match = re.fullmatch(r"([0-9a-fA-F]{64}) [ *]" + re.escape(filename), text)
+    if not match:
+        raise ValueError("Checksum file must contain exactly the requested archive name and SHA-256")
+    digest = hashlib.sha256()
+    with archive.open("rb") as source:
+        for chunk in iter(lambda: source.read(65536), b""):
+            digest.update(chunk)
+    if digest.hexdigest() != match[1].lower():
+        raise ValueError("Release archive SHA-256 does not match; nothing was installed")
+
+
+def unpack_release(archive: Path, staging: Path, version: str) -> Path:
+    """Extract regular files only; never follow archive links or traversal paths."""
+    prefix = f"laraship-{release_version(version)}"
+    staging.mkdir(mode=0o700, parents=True)
+    unpacked_tar = staging / "release.tar"
+    expanded = 0
+    # Bound the complete tar stream, including PAX/GNU headers, before parsing it.
+    with gzip.open(archive, "rb") as compressed, unpacked_tar.open("xb") as output:
+        while chunk := compressed.read(65536):
+            expanded += len(chunk)
+            if expanded > MAX_EXPANDED:
+                raise ValueError("Expanded release archive exceeds the size limit")
+            output.write(chunk)
+    seen: set[str] = set()
+    total = 0
+    with tarfile.open(unpacked_tar, "r:") as source:
+        for count, member in enumerate(source, 1):
+            path = PurePosixPath(member.name)
+            parts = path.parts
+            if (count > MAX_MEMBERS or path.is_absolute() or not parts or parts[0] != prefix
+                    or ".." in parts or "\\" in member.name
+                    or any(ord(c) < 32 for c in member.name)
+                    or not (member.isdir() or member.isfile()) or member.name in seen):
+                raise ValueError("Release archive contains an unsafe or duplicate entry")
+            seen.add(member.name)
+            total += member.size
+            if member.size < 0 or total > MAX_EXPANDED:
+                raise ValueError("Expanded release archive exceeds the size limit")
+            target = staging.joinpath(*parts)
+            if member.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            reader = source.extractfile(member)
+            if reader is None:
+                raise ValueError("Release archive contains an unreadable file")
+            with reader, target.open("xb") as output:
+                shutil.copyfileobj(reader, output)
+            target.chmod(0o755 if member.mode & 0o111 else 0o644)
+    root = staging / prefix
+    if any(not (root / name).is_file() for name in REQUIRED_FILES):
+        raise ValueError("Release archive is missing required LaraShip files")
+    if (root / "VERSION").read_text(encoding="ascii").strip() != version:
+        raise ValueError("Release archive VERSION does not match the requested release")
+    if (root / ".laraship-installing").exists():
+        raise ValueError("Release archive contains a reserved installation marker")
+    # A permissive caller umask must not make the installed root-run toolkit writable.
+    root.chmod(0o755)
+    for path in root.rglob("*"):
+        if path.is_dir():
+            path.chmod(0o755)
+    return root
+
+
+def install_native(version: str, directory: str) -> Path:
+    version = release_version(version)
+    destination = installation_path(directory)
+    filename = f"laraship-{version}.tar.gz"
+    base = f"https://github.com/shellharbor/laraship/releases/download/v{version}"
+    with tempfile.TemporaryDirectory(prefix="laraship-install-") as temporary:
+        private = Path(temporary)
+        archive = private / filename
+        checksum = private / f"{filename}.sha256"
+        download(f"{base}/{filename}.sha256", checksum, limit=4096)
+        download(f"{base}/{filename}", archive)
+        verify_checksum(archive, checksum, filename)
+        staged = unpack_release(archive, private / "unpacked", version)
+        # Reserve exclusively, including in a concurrent install. Failed copies stay
+        # visible and marked for inspection; they are never removed or overwritten.
+        destination.mkdir(mode=0o755)
+        marker = destination / ".laraship-installing"
+        marker.write_text("Installation incomplete; inspect this directory before use.\n", encoding="ascii")
+        marker.chmod(0o600)
+        shutil.copytree(staged, destination, dirs_exist_ok=True)
+        marker.unlink()
+    return destination