skyrun 0.1.0__tar.gz

skyrun-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,28 @@
+name: Bug report
+description: Report a reproducible problem with Skyrun.
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem and expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include the command and a sanitized configuration. Remove credentials and private paths/content.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Versions and environment
+      description: Skyrun, Python, Modal SDK, local OS, requested compute, and relevant run status.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output
+      description: Share only sanitized logs. Console output can contain workload secrets.

skyrun-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,16 @@
+name: Feature request
+description: Propose a focused improvement or provider integration.
+body:
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use case
+      description: What concrete task is difficult today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior and alternatives
+    validations:
+      required: true

skyrun-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

skyrun-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Problem and resulting behavior
+
+Describe the concrete trigger, the previous behavior, and what now happens.
+
+## Validation
+
+List meaningful checks and their results. Distinguish offline checks from any
+explicitly enabled Modal runs; include run IDs and hardware for live validation.
+
+## Compatibility
+
+Describe any user-facing changes, documentation updates, or remaining limits.

skyrun-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install -e '.[modal,dev]'
+      - run: python -m ruff check .
+      - run: python -m ruff format --check .
+      - run: python -m pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install -e '.[dev]'
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - run: python tools/check_dist.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+

skyrun-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      index:
+        description: Package index
+        type: choice
+        required: true
+        default: testpypi
+        options: [testpypi, pypi]
+
+permissions:
+  contents: read
+
+jobs:
+  verify-ref:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Require a matching version tag for production
+        env:
+          PUBLISH_INDEX: ${{ github.event_name == 'release' && 'pypi' || inputs.index }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+          version = tomllib.loads(Path('pyproject.toml').read_text())['project']['version']
+          ref = os.environ['GITHUB_REF']
+          if os.environ['PUBLISH_INDEX'] == 'pypi' or ref.startswith('refs/tags/'):
+              expected = 'refs/tags/v' + version
+              if ref != expected:
+                  raise SystemExit(f'Release requires {expected}; got {ref}')
+          PY
+
+  checks:
+    needs: verify-ref
+    uses: ./.github/workflows/ci.yml
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch' && inputs.index == 'testpypi'
+    needs: checks
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: github.event_name == 'release' || inputs.index == 'pypi'
+    needs: checks
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

skyrun-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+.pytest_cache/
+.env*
+runs/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+dist/
+build/
+*.egg-info/
+outputs/
+checkpoints/
+.venv*/

skyrun-0.1.0/AUTHORS.md

@@ -0,0 +1,7 @@
+# Authors and contributors
+
+- Aliaksei Kaliutau — original author and maintainer.
+
+Contributors are also recorded in the [Git history](https://github.com/akaliutau/skyrun/graphs/contributors).
+You may add your name here with your first merged contribution. A public email
+address is optional. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow.

skyrun-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable user-facing changes are recorded here. Skyrun uses semantic versions;
+the provider extension contract may evolve between minor releases before 1.0.
+
+## 0.1.0 — Unreleased
+
+### Added
+
+- Installable `skyrun` package, console entry point, `python -m skyrun`, and Python API.
+- Provider-neutral execution/download interface and third-party entry points.
+- Dedicated TOML and `[tool.skyrun]` configuration with local validation.
+- Project `.modalignore`, packaged baseline rules, bounded immutable snapshots,
+  executable mode preservation, and content-addressed source caching on Modal.
+- Optional run-boundary bidirectional sync with hash verification, local conflict
+  detection, explicit resolution policies, and retained remote versions.
+- Wheel-distributed hello, training, and inference projects exposed by `skyrun init`.
+- Offline regression suite, opt-in live CPU smoke, CI, distribution checks,
+  contributor files, and TestPyPI/PyPI publishing workflows and documentation.
+
+### Execution
+
+- PTY output, unbuffered raw streaming, complete console logs, process-group cleanup,
+  graceful checkpoint allowance, and escalating stop requests.
+- Workload exit codes, timeout/cancel status, isolated per-run outputs, model caching,
+  streamed artifact downloads, and GPU-free recovery of committed files.
+
+### Fixed
+
+- Hardcoded remote source location that could diverge from the selected project.
+- Predictable download temporary filenames and insufficient ancestor symlink checks.
+- Source snapshots now retain executable bits and report files modified during copying.
+- Trusted Modal mountpoints are resolved before applying symlink checks to their contents.
+
+### Repository cleanup
+
+- Repository links, package metadata, badges, clone commands, and Trusted Publishing
+  settings target `akaliutau/skyrun`.
+- The package CLI/API is the sole execution interface; examples have one canonical
+  location under `src/skyrun/examples/`.
+- Removed standalone compatibility scripts, obsolete configuration aliases,
+  duplicate examples/dependency files, and the separate starter archive builder.
+- Releases contain the standard Python wheel and source distribution.

skyrun-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,21 @@
+# Code of conduct
+
+Skyrun welcomes contributors with different backgrounds and levels of experience.
+Treat participants with respect, give constructive feedback, and focus discussion
+on the work. Assume good intent while taking concerns about harmful behavior
+seriously.
+
+Harassment, discriminatory remarks, threats, personal attacks, and sharing private
+information without consent are unacceptable. This applies to issues, pull
+requests, reviews, and other project spaces, including conduct while representing
+the project elsewhere.
+
+Maintainers may edit or remove inappropriate content, close a discussion, or
+restrict participation when needed to protect the community. They should explain
+the reason when appropriate and consider the impact and context of the behavior.
+
+Report concerns privately to the repository owner through the contact methods
+listed on [their GitHub profile](https://github.com/akaliutau). Avoid posting
+personal details publicly. Maintainers will handle reports discreetly and seek a
+fair resolution. Participants who need to challenge a decision can contact the
+repository owner with the relevant context.

skyrun-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to Skyrun
+
+Thank you for helping make remote execution dependable and easy to use. Small,
+well-tested fixes, clear documentation, and additional provider adapters are
+welcome. Open an issue before a substantial API or behavior change so maintainers
+can discuss compatibility and scope.
+
+## Development environment
+
+```bash
+git clone https://github.com/akaliutau/skyrun.git
+cd skyrun
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[modal,dev]'
+```
+
+Python 3.11+ is required. Tests run without Modal credentials or cloud compute by
+default. Remote process tests use real POSIX subprocesses; CI runs on Linux across
+Python 3.11–3.14. Runnable examples live in `src/skyrun/examples/` and ship with
+every wheel. Update their scripts and configuration together.
+
+## Before opening a pull request
+
+```bash
+python -m ruff check .
+python -m ruff format --check .
+python -m pytest
+python -m build
+python -m twine check --strict dist/*
+python tools/check_dist.py
+```
+
+Use `python -m ruff format .` to apply formatting. Add a regression test for a bug
+fix or behavior change. Prefer tests of externally visible behavior: process
+cleanup, saved artifacts, path boundaries, transfer interruption, and file
+conflicts. Avoid tests that simply repeat implementation details. Update the
+relevant guide and `CHANGELOG.md` when user behavior changes.
+
+Tests marked `integration` are skipped unless explicitly enabled. To exercise the
+live CPU sample against your own authenticated Modal account:
+
+```bash
+SKYRUN_TEST_MODAL=1 python -m pytest -m integration -v
+```
+
+This allocates Modal CPU compute, creates persistent Volumes, and can incur
+charges. Run it deliberately. A separate bounded GPU smoke checks T4 allocation,
+selected-file sync, and GPU-free recovery, without model downloads:
+
+```bash
+SKYRUN_TEST_GPU=1 python -m pytest tests/test_integration.py::test_live_modal_gpu_sync_and_recovery -v
+```
+
+For model/training validation, follow the training and
+inference recipes in [the example catalog](docs/examples.md) and record the GPU,
+SDK version, run ID, exit code, and relevant saved artifacts in your PR. Never
+commit credentials, model weights, run data, or private environment output.
+
+## Compatibility requirements
+
+Preserve the documented `skyrun` CLI, Python API, `skyrun.toml`, and
+`[tool.skyrun]` configuration. Keep ordinary workload scripts free of runner
+imports. Configuration and dry runs must work without a provider SDK or
+authentication. Maintain live raw output,
+first/second/third stop semantics, nonzero exit codes, process-group cleanup,
+artifact recovery, and source isolation.
+
+Two-way sync must remain opt-in, detect local changes, verify downloaded hashes,
+and retain remote versions on conflict. Do not add automatic deletion or
+overwriting to default sync behavior. Source and artifact paths must reject
+traversal and symlinks. A backend must not retry an arbitrary workload without
+explicit user configuration.
+
+Read [architecture and extension points](docs/architecture.md) before adding a
+provider. Keep SDK imports inside the provider boundary, use entry points for
+extensions, and add transport contract tests. New dependencies should have a
+clear purpose and support the declared Python versions.
+
+## Pull requests and releases
+
+Explain the concrete problem, resulting behavior, and meaningful validation.
+Include a reproduction for bug fixes and identify any remaining live-cloud checks.
+Keep unrelated formatting and redesigns out of a focused change. Maintainers
+review contributions under the [code of conduct](CODE_OF_CONDUCT.md).
+
+Contributions are licensed under the repository's MIT license. Add yourself to
+[AUTHORS.md](AUTHORS.md) when your first contribution is merged, if you wish.
+Maintainers publish following [the release guide](docs/publishing.md); do not push
+release tags or upload distributions as part of an ordinary contribution.

skyrun-0.1.0/LICENSE

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

skyrun-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE README.md CONTRIBUTING.md CODE_OF_CONDUCT.md AUTHORS.md SECURITY.md CHANGELOG.md
+include .gitignore
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include .github *.yml *.yaml *.md
+recursive-include tools *.py
+global-exclude __pycache__ *.py[cod]
+prune runs
+exclude plan.txt