pyflyrail 0.1.0__tar.gz

pyflyrail-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.cache/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+.DS_Store
+*.log

pyflyrail-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable user-facing changes to Flyrail for Python. Package versions are independent from
+configuration bundle labels and shared format schema versions.
+
+## [0.1.0] - 2026-09-20
+
+
+### Features
+
+- Python prototype
+- Add reversible agent configuration bundles
+- Add Python release process
+
+
+### Bug Fixes
+
+- Unblock Python release
+- Initialize Windows lock files
+- Separate Windows lock range
+- Correct Windows filesystem semantics
+- Ignore inherited git context in the release helper
+
+[0.1.0]: https://github.com/nielsmadan/flyrail/tree/python-v0.1.0
+

pyflyrail-0.1.0/LICENSE

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

pyflyrail-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: pyflyrail
+Version: 0.1.0
+Summary: A typed library for reversible coding-agent configuration bundles.
+Project-URL: Documentation, https://github.com/nielsmadan/flyrail/tree/main/python/docs
+Project-URL: Issues, https://github.com/nielsmadan/flyrail/issues
+Project-URL: Repository, https://github.com/nielsmadan/flyrail
+Author: Niels Madan
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: tomlkit==0.15.1
+Description-Content-Type: text/markdown
+
+# Flyrail for Python
+
+A typed, synchronous library for coding-agent configuration bundles: skills,
+instructions, MCP registrations, hooks and supporting assets. Requires Python
+3.11+; TOML editing lazily imports pinned `tomlkit`. Windows mutations require
+Python 3.11.10+, 3.12.4+, or 3.13+ for private directory creation.
+
+## Install and use
+
+Install the `pyflyrail` distribution from PyPI. The import package remains `flyrail`:
+
+```sh
+python -m pip install pyflyrail
+```
+
+To install the current checkout instead, run `python -m pip install .` from `python/`.
+The following example uses the same public import in either installation:
+
+```python
+from flyrail import Bundle, Target, inspect, install, uninstall, update
+
+bundle = Bundle.from_directory("examples/filesystem/bundle")
+targets = [Target.directory(".cache/demo-skills")]
+
+installed = install(bundle, targets)
+current = all(result.observation.is_current for result in inspect(bundle, targets))
+updated = update(bundle, targets, lock_timeout=0.25)
+removed = uninstall(bundle.id, targets)
+```
+
+`Target.directory` names the skill container itself. This example installs
+`.cache/demo-skills/notes-summary/SKILL.md`. Use `Bundle.from_package("your_package")`
+for application resources with a `flyrail/` bundle directory. Both loaders snapshot
+complete trees before returning, so later removal of the source does not invalidate
+an already loaded bundle.
+
+Presets cover Claude Code, Codex, OpenCode, Pi, Cursor and Copilot. For example,
+`Target.user("codex")` selects a user installation and
+`Target.project("claude", "./project")` selects a project installation. Hosts choose
+explicit destinations; the library never selects agents, prints, prompts, exits,
+executes skill scripts or requests the network.
+
+Bundle version labels are independent of your application's version. Inspection
+compares the label, recorded content and actual content separately. Updates can
+change content under the same label or install an older-looking label. An intact
+matching revision returns `UNCHANGED`.
+
+Check every mutation result's status, errors and resource recovery paths. A
+committed resource can still need cleanup; `PARTIAL` reports completed resource
+commits followed by a failure. Own edits block replacement/removal unless
+`replace_modified=True`; untracked and foreign-owned skills remain protected.
+Uninstall uses the bundle ID and receipts, without requiring source files.
+
+For portable instructions, MCP, hooks and supporting assets, use `render(bundle, context)`
+with an explicit `RenderContext`. It returns a `RenderedBundle` for
+`preview`/`apply_preview` or `sync` with an `InstallationTarget`.
+[Translation](https://github.com/nielsmadan/flyrail/blob/main/python/docs/translation.md)
+explains capabilities, native alternatives and exact unsupported boundaries.
+`inspect_installation` and `remove` use the private index without source bytes.
+For applications that select destinations from observed files, call source-free
+`recover_installation` before re-reading those files and building a fresh immutable
+preview. Recovery preserves healthy ownership and retains pending membership for
+the subsequent update or removal.
+Use `inspect_installation(bundle.id, target).matches(bundle, rendered)` to compare
+the app's current bundle and rendering with intact installed content. The
+source-free `is_current` field checks the recorded generation only. Neither check
+establishes host trust, discovery or activation; inspect render notices separately.
+The [configuration API](https://github.com/nielsmadan/flyrail/blob/main/python/docs/api.md)
+shows an in-memory instruction example and explains explicit takeover/adoption.
+
+## Documentation and examples
+
+- [Public API](https://github.com/nielsmadan/flyrail/blob/main/python/docs/api.md)
+- [Command hooks](https://github.com/nielsmadan/flyrail/blob/main/python/docs/hooks.md)
+- [Destinations and inspection](https://github.com/nielsmadan/flyrail/blob/main/python/docs/inspection.md)
+- [Lifecycle and recovery](https://github.com/nielsmadan/flyrail/blob/main/python/docs/lifecycle.md)
+- [Examples](https://github.com/nielsmadan/flyrail/blob/main/python/docs/examples.md)
+- [Support and limits](https://github.com/nielsmadan/flyrail/blob/main/python/docs/support.md)
+- [Shared formats](https://github.com/nielsmadan/flyrail/tree/main/spec)
+
+The repository's `examples/` contains two independently packaged host CLIs: notes
+with an explicit filesystem bundle and checksum with packaged resources. They
+include a combined checksum `config` interface with generated guidance, skills,
+stdio/HTTP MCP environment references and a portable hook with packaged assets.
+Native hook execution requires an explicitly selected Node 24+ executable;
+OpenCode/Pi can use their existing host runtimes. Python package builds require
+no JavaScript runtime or compiler.
+
+Examples and development tooling live in the repository; the source distribution
+contains library code, tests, shared fixtures, runtime test tooling, package
+metadata and the license.
+
+For repository development, run `just check` from `python/` or the repository root.
+It checks formatting, lint/security, strict typing, tests with branch coverage,
+built package contents and installed consumers. The repository CI matrix covers
+Python 3.11 and 3.14 on macOS, Linux and Windows. See
+[development](https://github.com/nielsmadan/flyrail/blob/main/python/docs/development.md).

pyflyrail-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Flyrail for Python
+
+A typed, synchronous library for coding-agent configuration bundles: skills,
+instructions, MCP registrations, hooks and supporting assets. Requires Python
+3.11+; TOML editing lazily imports pinned `tomlkit`. Windows mutations require
+Python 3.11.10+, 3.12.4+, or 3.13+ for private directory creation.
+
+## Install and use
+
+Install the `pyflyrail` distribution from PyPI. The import package remains `flyrail`:
+
+```sh
+python -m pip install pyflyrail
+```
+
+To install the current checkout instead, run `python -m pip install .` from `python/`.
+The following example uses the same public import in either installation:
+
+```python
+from flyrail import Bundle, Target, inspect, install, uninstall, update
+
+bundle = Bundle.from_directory("examples/filesystem/bundle")
+targets = [Target.directory(".cache/demo-skills")]
+
+installed = install(bundle, targets)
+current = all(result.observation.is_current for result in inspect(bundle, targets))
+updated = update(bundle, targets, lock_timeout=0.25)
+removed = uninstall(bundle.id, targets)
+```
+
+`Target.directory` names the skill container itself. This example installs
+`.cache/demo-skills/notes-summary/SKILL.md`. Use `Bundle.from_package("your_package")`
+for application resources with a `flyrail/` bundle directory. Both loaders snapshot
+complete trees before returning, so later removal of the source does not invalidate
+an already loaded bundle.
+
+Presets cover Claude Code, Codex, OpenCode, Pi, Cursor and Copilot. For example,
+`Target.user("codex")` selects a user installation and
+`Target.project("claude", "./project")` selects a project installation. Hosts choose
+explicit destinations; the library never selects agents, prints, prompts, exits,
+executes skill scripts or requests the network.
+
+Bundle version labels are independent of your application's version. Inspection
+compares the label, recorded content and actual content separately. Updates can
+change content under the same label or install an older-looking label. An intact
+matching revision returns `UNCHANGED`.
+
+Check every mutation result's status, errors and resource recovery paths. A
+committed resource can still need cleanup; `PARTIAL` reports completed resource
+commits followed by a failure. Own edits block replacement/removal unless
+`replace_modified=True`; untracked and foreign-owned skills remain protected.
+Uninstall uses the bundle ID and receipts, without requiring source files.
+
+For portable instructions, MCP, hooks and supporting assets, use `render(bundle, context)`
+with an explicit `RenderContext`. It returns a `RenderedBundle` for
+`preview`/`apply_preview` or `sync` with an `InstallationTarget`.
+[Translation](https://github.com/nielsmadan/flyrail/blob/main/python/docs/translation.md)
+explains capabilities, native alternatives and exact unsupported boundaries.
+`inspect_installation` and `remove` use the private index without source bytes.
+For applications that select destinations from observed files, call source-free
+`recover_installation` before re-reading those files and building a fresh immutable
+preview. Recovery preserves healthy ownership and retains pending membership for
+the subsequent update or removal.
+Use `inspect_installation(bundle.id, target).matches(bundle, rendered)` to compare
+the app's current bundle and rendering with intact installed content. The
+source-free `is_current` field checks the recorded generation only. Neither check
+establishes host trust, discovery or activation; inspect render notices separately.
+The [configuration API](https://github.com/nielsmadan/flyrail/blob/main/python/docs/api.md)
+shows an in-memory instruction example and explains explicit takeover/adoption.
+
+## Documentation and examples
+
+- [Public API](https://github.com/nielsmadan/flyrail/blob/main/python/docs/api.md)
+- [Command hooks](https://github.com/nielsmadan/flyrail/blob/main/python/docs/hooks.md)
+- [Destinations and inspection](https://github.com/nielsmadan/flyrail/blob/main/python/docs/inspection.md)
+- [Lifecycle and recovery](https://github.com/nielsmadan/flyrail/blob/main/python/docs/lifecycle.md)
+- [Examples](https://github.com/nielsmadan/flyrail/blob/main/python/docs/examples.md)
+- [Support and limits](https://github.com/nielsmadan/flyrail/blob/main/python/docs/support.md)
+- [Shared formats](https://github.com/nielsmadan/flyrail/tree/main/spec)
+
+The repository's `examples/` contains two independently packaged host CLIs: notes
+with an explicit filesystem bundle and checksum with packaged resources. They
+include a combined checksum `config` interface with generated guidance, skills,
+stdio/HTTP MCP environment references and a portable hook with packaged assets.
+Native hook execution requires an explicitly selected Node 24+ executable;
+OpenCode/Pi can use their existing host runtimes. Python package builds require
+no JavaScript runtime or compiler.
+
+Examples and development tooling live in the repository; the source distribution
+contains library code, tests, shared fixtures, runtime test tooling, package
+metadata and the license.
+
+For repository development, run `just check` from `python/` or the repository root.
+It checks formatting, lint/security, strict typing, tests with branch coverage,
+built package contents and installed consumers. The repository CI matrix covers
+Python 3.11 and 3.14 on macOS, Linux and Windows. See
+[development](https://github.com/nielsmadan/flyrail/blob/main/python/docs/development.md).

pyflyrail-0.1.0/hatch_build.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+from hatchling.builders.sdist import SdistBuilderConfig
+
+
+class CustomBuildHook(BuildHookInterface[SdistBuilderConfig]):
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        root = Path(self.root)
+        fixtures = root / "spec/fixtures"
+        if not fixtures.is_dir():
+            fixtures = root.parent / "spec/fixtures"
+        for name in (
+            "bundles.json",
+            "configurations.json",
+            "edits.json",
+            "translations.json",
+            "hooks.json",
+        ):
+            build_data["force_include"][str(fixtures / name)] = f"spec/fixtures/{name}"

pyflyrail-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["hatchling==1.32.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyflyrail"
+version = "0.1.0"
+description = "A typed library for reversible coding-agent configuration bundles."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Niels Madan" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["tomlkit==0.15.1"]
+
+[project.urls]
+Documentation = "https://github.com/nielsmadan/flyrail/tree/main/python/docs"
+Issues = "https://github.com/nielsmadan/flyrail/issues"
+Repository = "https://github.com/nielsmadan/flyrail"
+
+[dependency-groups]
+audit = ["pip-audit==2.10.1"]
+dev = [
+  "hatchling==1.32.0",
+  "mypy==2.3.1",
+  "pytest==9.1.1",
+  "pytest-cov==7.1.0",
+  "ruff==0.16.7",
+]
+
+[tool.uv]
+required-version = ">=0.12.13"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flyrail"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/runtime-tooling", "/README.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.toml", "/uv.lock", "/hatch_build.py", "/.gitignore"]
+exclude = ["**/.git", "**/.cache", "**/.venv", "**/__pycache__", "**/*.py[cod]", "**/*.egg-info", "**/build", "**/dist", "**/.DS_Store", "**/*.log"]
+
+[tool.hatch.build.targets.sdist.hooks.custom]
+path = "hatch_build.py"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+cache-dir = ".cache/ruff"
+extend-exclude = [".cache", "dist"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "S", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]
+"scripts/package_probe.py" = ["S101"]
+"scripts/hook_package_probe.py" = ["S101"]
+"scripts/configuration_package_probe.py" = ["S101"]
+"scripts/typed_consumer.py" = ["S101"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests", "scripts", "examples", "hatch_build.py"]
+cache_dir = ".cache/mypy"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-config --strict-markers"
+markers = [
+  "integration: exercises real runtimes, subprocesses or full on-disk lifecycles",
+]
+cache_dir = ".cache/pytest"
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["flyrail"]
+data_file = ".cache/coverage/.coverage"
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false