pyshellforge 0.0.0__tar.gz → 0.1.0__tar.gz

pyshellforge-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test & type-check caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# Rendered artefacts produced while experimenting
+/deploy.sh
+/backup.sh
+/build.sh
+/out/
+rendered/
+
+# README generation tooling (optional, Node only)
+node_modules/
+npm-debug.log*
+
+# Developer environment and sandbox
+.pixi/
+pixi-sandbox-pack/
+
+# Coverage, prose and link-check caches
+coverage.xml
+coverage_html/
+.lycheecache
+
+# Repository script output
+sandbox/
+
+# doit task state
+.doit.db
+.doit.db.*
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+*.swp

pyshellforge-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: pyshellforge
+Version: 0.1.0
+Summary: A Python-native DSL for building, composing and rendering structured Bash scripts.
+Project-URL: Homepage, https://github.com/Archont561/PyShellForge
+Project-URL: Documentation, https://github.com/Archont561/PyShellForge/tree/main/docs
+Project-URL: Repository, https://github.com/Archont561/PyShellForge
+Project-URL: Issues, https://github.com/Archont561/PyShellForge/issues
+Project-URL: Changelog, https://github.com/Archont561/PyShellForge/blob/main/CHANGELOG.md
+Author: PyShellForge contributors
+License: MIT
+Keywords: ast,automation,bash,code-generation,compiler,developer-tools,dsl,python,shell,shell-script,transpiler
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Unix Shell
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: System :: Shells
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pyfiglet<2,>=1.0.4; extra == 'dev'
+Requires-Dist: pytest-bdd<10,>=9; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: rude-clean-code<0.2,>=0.1; extra == 'dev'
+Requires-Dist: rude<0.2,>=0.1a4; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: tox>=4.20; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: alint>=0.20; extra == 'docs'
+Requires-Dist: gherlint>=0.5; extra == 'docs'
+Requires-Dist: pyfiglet<2,>=1.0.4; extra == 'docs'
+Requires-Dist: pyyaml>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<!--
+  Generated file - do not edit README.md by hand.
+
+  Source template : automation/readme/README.ejs
+  Generator       : readme-md-generator (pinned in package.json)
+  Regenerate with : pixi run automation readme   (python -m automation.readme)
+  Verify in CI    : pixi run automation readme-check
+-->
+
+<h1 align="center">PyShellForge</h1>
+
+<pre style="font-family: monospace">
+██████╗ ██╗   ██╗███████╗██╗  ██╗███████╗██╗     ██╗     ███████╗ ██████╗ ██████╗  ██████╗ ███████╗
+██╔══██╗╚██╗ ██╔╝██╔════╝██║  ██║██╔════╝██║     ██║     ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
+██████╔╝ ╚████╔╝ ███████╗███████║█████╗  ██║     ██║     █████╗  ██║   ██║██████╔╝██║  ███╗█████╗
+██╔═══╝   ╚██╔╝  ╚════██║██╔══██║██╔══╝  ██║     ██║     ██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝
+██║        ██║   ███████║██║  ██║███████╗███████╗███████╗██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
+╚═╝        ╚═╝   ╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝</pre>
+
+<p>
+  <img alt="Version: 0.1.0" src="https://img.shields.io/badge/version-0.1.0-blue.svg?cacheSeconds=2592000" />
+  <a href="https://github.com/Archont561/pyshellforge/blob/main/docs/README.md" target="_blank">
+    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
+  </a>
+  <img alt="python 3.11+" src="https://img.shields.io/badge/python-%3E%3D3.11-blue.svg" />
+  <a href="https://codecov.io/gh/Archont561/pyshellforge" target="_blank">
+    <img alt="Coverage" src="https://img.shields.io/codecov/c/github/Archont561/pyshellforge.svg" />
+  </a>
+  <a href="https://github.com/Archont561/pyshellforge/blob/main/LICENSE" target="_blank">
+    <img alt="License: MIT" src="https://img.shields.io/github/license/Archont561/pyshellforge" />
+  </a>
+</p>
+
+> Write shell scripts in Python. Render clean Bash.
+>
+> A Python-native DSL for building, composing and rendering structured Bash
+> scripts. The first Bash renderer supports comments, literal assignments,
+> commands and checked text interpolation.
+
+### 🏠 [Homepage](https://github.com/Archont561/PyShellForge#readme)
+
+## Documentation
+
+The [`docs/`](../../docs/README.md) directory is the source of truth for using and
+working on this repository:
+
+- [Documentation index](../../docs/README.md): everything, organized by purpose
+- [Install](../../docs/guides/install.md): prerequisites, installation, the locked developer sandbox
+- [AST design](../../docs/concepts/ast-design.md): nodes, renderers and interpolation
+- [API reference](../../docs/reference/api-reference.md): the script, nodes and Bash renderer
+- [Repository layout](../../docs/reference/repository-layout.md): what lives where and why
+- [Linting](../../docs/reference/linting.md): the Rude plugin, its rule codes, and the rules that wait for the validator
+- [Project status](../../docs/concepts/version-only-scaffold.md): what exists today and what the roadmap adds
+- [Contributing](../../docs/development/contributing.md): setup, the checks CI runs, the commit and merge policy
+- [Testing](../../docs/development/testing.md): test layout, what each layer proves, coverage
+- [Tooling](../../docs/development/tooling.md): the `automation` CLI, its task graph, hooks and linters
+- [Documentation](../../docs/development/documentation.md): policy, structure, validation and definition of done
+- [Releasing](../../docs/development/releasing.md): the tag-triggered release and trusted publishing
+
+Planned work is tracked in [`backlog/`](../../backlog/), and the release history is
+[`CHANGELOG.md`](../../CHANGELOG.md).
+
+## Install
+
+```sh
+pip install pyshellforge
+```
+
+## Usage
+
+```sh
+python -c 'from pyshellforge import ShellScript, Echo; print(ShellScript().add(Echo("Hello")).render())'
+```
+
+## Run tests
+
+```sh
+pixi run automation test-all
+```
+
+## Author
+
+👤 **PyShellForge contributors**
+
+- Website: [archont561.github.io/Archont561](https://archont561.github.io/Archont561/)
+- GitHub: [@Archont561](https://github.com/Archont561)
+
+## 🤝 Contributing
+
+Contributions, issues and feature requests are welcome!<br />Feel free to check
+the [issues page](https://github.com/Archont561/PyShellForge/issues). You can also take a look at the
+[contributing guide](../../CONTRIBUTING.md): it covers setup, the checks a change has
+to pass and the merge policy.
+
+## Show your support
+
+Give a ⭐️ if this project helped you!
+
+## 📝 License
+
+Copyright © 2026 [PyShellForge contributors](https://github.com/Archont561).<br />
+This project is [MIT](https://github.com/Archont561/pyshellforge/blob/main/LICENSE) licensed.
+
+***
+
+*This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator) from [`automation/readme/README.ejs`](../../automation/readme/README.ejs).*

pyshellforge-0.1.0/README.md

@@ -0,0 +1,106 @@
+<!--
+  Generated file - do not edit README.md by hand.
+
+  Source template : automation/readme/README.ejs
+  Generator       : readme-md-generator (pinned in package.json)
+  Regenerate with : pixi run automation readme   (python -m automation.readme)
+  Verify in CI    : pixi run automation readme-check
+-->
+
+<h1 align="center">PyShellForge</h1>
+
+<pre style="font-family: monospace">
+██████╗ ██╗   ██╗███████╗██╗  ██╗███████╗██╗     ██╗     ███████╗ ██████╗ ██████╗  ██████╗ ███████╗
+██╔══██╗╚██╗ ██╔╝██╔════╝██║  ██║██╔════╝██║     ██║     ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
+██████╔╝ ╚████╔╝ ███████╗███████║█████╗  ██║     ██║     █████╗  ██║   ██║██████╔╝██║  ███╗█████╗
+██╔═══╝   ╚██╔╝  ╚════██║██╔══██║██╔══╝  ██║     ██║     ██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝
+██║        ██║   ███████║██║  ██║███████╗███████╗███████╗██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
+╚═╝        ╚═╝   ╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝</pre>
+
+<p>
+  <img alt="Version: 0.1.0" src="https://img.shields.io/badge/version-0.1.0-blue.svg?cacheSeconds=2592000" />
+  <a href="https://github.com/Archont561/pyshellforge/blob/main/docs/README.md" target="_blank">
+    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
+  </a>
+  <img alt="python 3.11+" src="https://img.shields.io/badge/python-%3E%3D3.11-blue.svg" />
+  <a href="https://codecov.io/gh/Archont561/pyshellforge" target="_blank">
+    <img alt="Coverage" src="https://img.shields.io/codecov/c/github/Archont561/pyshellforge.svg" />
+  </a>
+  <a href="https://github.com/Archont561/pyshellforge/blob/main/LICENSE" target="_blank">
+    <img alt="License: MIT" src="https://img.shields.io/github/license/Archont561/pyshellforge" />
+  </a>
+</p>
+
+> Write shell scripts in Python. Render clean Bash.
+>
+> A Python-native DSL for building, composing and rendering structured Bash
+> scripts. The first Bash renderer supports comments, literal assignments,
+> commands and checked text interpolation.
+
+### 🏠 [Homepage](https://github.com/Archont561/PyShellForge#readme)
+
+## Documentation
+
+The [`docs/`](../../docs/README.md) directory is the source of truth for using and
+working on this repository:
+
+- [Documentation index](../../docs/README.md): everything, organized by purpose
+- [Install](../../docs/guides/install.md): prerequisites, installation, the locked developer sandbox
+- [AST design](../../docs/concepts/ast-design.md): nodes, renderers and interpolation
+- [API reference](../../docs/reference/api-reference.md): the script, nodes and Bash renderer
+- [Repository layout](../../docs/reference/repository-layout.md): what lives where and why
+- [Linting](../../docs/reference/linting.md): the Rude plugin, its rule codes, and the rules that wait for the validator
+- [Project status](../../docs/concepts/version-only-scaffold.md): what exists today and what the roadmap adds
+- [Contributing](../../docs/development/contributing.md): setup, the checks CI runs, the commit and merge policy
+- [Testing](../../docs/development/testing.md): test layout, what each layer proves, coverage
+- [Tooling](../../docs/development/tooling.md): the `automation` CLI, its task graph, hooks and linters
+- [Documentation](../../docs/development/documentation.md): policy, structure, validation and definition of done
+- [Releasing](../../docs/development/releasing.md): the tag-triggered release and trusted publishing
+
+Planned work is tracked in [`backlog/`](../../backlog/), and the release history is
+[`CHANGELOG.md`](../../CHANGELOG.md).
+
+## Install
+
+```sh
+pip install pyshellforge
+```
+
+## Usage
+
+```sh
+python -c 'from pyshellforge import ShellScript, Echo; print(ShellScript().add(Echo("Hello")).render())'
+```
+
+## Run tests
+
+```sh
+pixi run automation test-all
+```
+
+## Author
+
+👤 **PyShellForge contributors**
+
+- Website: [archont561.github.io/Archont561](https://archont561.github.io/Archont561/)
+- GitHub: [@Archont561](https://github.com/Archont561)
+
+## 🤝 Contributing
+
+Contributions, issues and feature requests are welcome!<br />Feel free to check
+the [issues page](https://github.com/Archont561/PyShellForge/issues). You can also take a look at the
+[contributing guide](../../CONTRIBUTING.md): it covers setup, the checks a change has
+to pass and the merge policy.
+
+## Show your support
+
+Give a ⭐️ if this project helped you!
+
+## 📝 License
+
+Copyright © 2026 [PyShellForge contributors](https://github.com/Archont561).<br />
+This project is [MIT](https://github.com/Archont561/pyshellforge/blob/main/LICENSE) licensed.
+
+***
+
+*This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator) from [`automation/readme/README.ejs`](../../automation/readme/README.ejs).*

pyshellforge-0.1.0/features/bash_rendering.feature

@@ -0,0 +1,10 @@
+@product
+Feature: Render a Bash script
+  A script is a sequence of shell-neutral nodes. The Bash renderer quotes literal
+  values and expands only variables declared earlier in the script.
+
+  Scenario: Render and run a greeting
+    Given a script that assigns a greeting name
+    When the script is rendered as Bash
+    Then the generated Bash matches the greeting golden file
+    And the generated Bash prints the greeting

pyshellforge-0.1.0/pyproject.toml

@@ -0,0 +1,147 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+# The distribution lives in this directory: the package under src/, its test
+# suite, its Gherkin features and this manifest. Everything repository-scoped
+# (docs/, automation/, CI, the Pixi environment) stays at the repository root and
+# builds, tests and checks this project from there.
+[project]
+name = "pyshellforge"
+version = "0.1.0"
+description = "A Python-native DSL for building, composing and rendering structured Bash scripts."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "PyShellForge contributors" }]
+keywords = [
+    "python",
+    "bash",
+    "shell",
+    "shell-script",
+    "code-generation",
+    "compiler",
+    "transpiler",
+    "dsl",
+    "ast",
+    "developer-tools",
+    "automation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Unix Shell",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: System :: Shells",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    # 9 emits every step definition as a fixture, which is how the automation
+    # suite registers its step modules; the Pixi environment pins the same major.
+    "pytest-bdd>=9,<10",
+    "pytest-cov>=5.0",
+    "hypothesis>=6.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "build>=1.2",
+    "tox>=4.20",
+    # Issue-form validation (automation.forms) reads YAML.
+    "pyyaml>=6.0",
+    "types-pyyaml>=6.0",
+    # The README banner is FIGlet art (automation.banner), rendered, not pasted.
+    "pyfiglet>=1.0.4,<2",
+    # Clean Code rules: rude is the linter, rude-clean-code the rule plugin.
+    "rude>=0.1a4,<0.2",
+    "rude-clean-code>=0.1,<0.2",
+]
+# Documentation tooling: repository policy and Gherkin style. markdownlint-cli2,
+# Vale and lychee are standalone binaries wired through Pixi (see pixi.toml).
+docs = [
+    "alint>=0.20",
+    "gherlint>=0.5",
+    # automation.forms validates the GitHub Issue Forms.
+    "pyyaml>=6.0",
+    # automation.readme renders the banner, and CI checks the README here.
+    "pyfiglet>=1.0.4,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Archont561/PyShellForge"
+Documentation = "https://github.com/Archont561/PyShellForge/tree/main/docs"
+Repository = "https://github.com/Archont561/PyShellForge"
+Issues = "https://github.com/Archont561/PyShellForge/issues"
+Changelog = "https://github.com/Archont561/PyShellForge/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyshellforge"]
+
+[tool.hatch.build.targets.sdist]
+# The sdist carries what the suite needs if it is ever unpacked and tested:
+include = ["src", "tests", "features", "README.md"]
+
+# Run from the repository root with an explicit configuration file:
+#   python -m pytest -c packages/pyshellforge/pyproject.toml               # the product suite
+#   python -m pytest -c packages/pyshellforge/pyproject.toml ../automation/tests
+# `pythonpath` is resolved against this file, so "src" is the package tree and
+# "../.." is the repository root the suites import `automation` from. The automation
+# suite brings its own conftest: its scenarios and step definitions live beside
+# the automation, outside this rootdir.
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["src", "../.."]
+addopts = "-ra --strict-markers"
+markers = [
+    "integration: end-to-end rendering and shell syntax checks",
+    "shellcheck: requires the shellcheck binary",
+    "tooling: automation scenarios (automation/features/)",
+    "product: product behaviour scenarios (packages/pyshellforge/features/)",
+]
+
+# ruff configuration: ../../ruff.toml
+# coverage configuration: ../../.coveragerc
+
+# Clean Code linting: `python -m automation.clean_code` runs
+#   python -m rude check --config packages/pyshellforge/pyproject.toml <paths>
+# over the same trees mypy checks. Only the CC family is selected, because ruff
+# owns everything else; the rules come from the rude-clean-code plugin, which
+# rude discovers through its `rude.plugins` entry point.
+[tool.rude]
+select = ["CC"]
+
+[tool.rude.rules.CC101]
+# The rule counts the whole definition: signature, docstring and blank lines.
+# Every function in this repository carries a docstring, so 60 keeps a function
+# to one operation while leaving room for the prose that explains it.
+max_lines = 60
+
+# Types are checked with `mypy --config-file packages/pyshellforge/pyproject.toml` from the
+# repository root; mypy resolves these paths against the working directory.
+[tool.mypy]
+python_version = "3.11"
+files = ["packages/pyshellforge/src", "packages/pyshellforge-rude/src", "automation", "dodo.py"]
+# `src/` layout: name the module base explicitly so `src/pyshellforge` is checked
+# as `pyshellforge`, not `pyshellforge.src.pyshellforge`. The second entry is the
+# BDD step directory, whose modules the suite imports by bare name.
+mypy_path = "packages/pyshellforge/src:packages/pyshellforge-rude/src:automation/tests/bdd"
+explicit_package_bases = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+strict_equality = true

pyshellforge-0.1.0/src/pyshellforge/__init__.py

@@ -0,0 +1,113 @@
+"""PyShellForge — the package surface.
+
+The package exposes the script container, initial nodes and Bash renderer.
+
+The version has a single source of truth, ``[project].version`` in
+``pyproject.toml``. Reading it at import time keeps the value honest — there is no
+second copy to forget — and it needs care in one respect: a wheel does not ship
+``pyproject.toml``. The order below therefore degrades instead of failing, so that
+``import pyshellforge`` works in a source checkout, from an installed
+distribution and from a vendored package:
+
+1. ``pyproject.toml`` found by walking up from this file (source checkout);
+2. installed distribution metadata (wheel, sdist, editable install);
+3. :data:`FALLBACK_VERSION`, which exists so that an import never raises.
+
+Usage::
+
+    >>> import pyshellforge
+    >>> pyshellforge.VERSION
+    '0.1.0'
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from .ast import Command, Comment, Echo, Node, VariableAssignment
+from .core import ShellScript
+from .renderers import InterpolationError, UnsupportedNodeError
+from .renderers.bash import BashRenderer
+
+__all__ = [
+    "VERSION",
+    "BashRenderer",
+    "Command",
+    "Comment",
+    "Echo",
+    "InterpolationError",
+    "Node",
+    "ShellScript",
+    "UnsupportedNodeError",
+    "VariableAssignment",
+]
+
+#: Distribution name used for metadata lookups.
+DIST_NAME = "pyshellforge"
+
+#: File searched for when no metadata is installed.
+PYPROJECT_NAME = "pyproject.toml"
+
+#: Last resort, so that a vendored package still imports.
+FALLBACK_VERSION = "0.1.0"
+
+#: Conservative check so a malformed file cannot leak garbage into a version string.
+VERSION_RE = re.compile(r"^\d+(\.\d+)*([.-]?[0-9A-Za-z.]+)?$")
+
+
+def find_pyproject(start: str | Path | None = None) -> Path | None:
+    """Return the ``pyproject.toml`` above ``start`` (default: this file), or ``None``."""
+    location = Path(start) if start is not None else Path(__file__)
+    try:
+        location = location.resolve()
+    except OSError:  # pragma: no cover - broken symlink
+        return None
+    directory = location if location.is_dir() else location.parent
+    for candidate_dir in (directory, *directory.parents):
+        candidate = candidate_dir / PYPROJECT_NAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def read_version(pyproject: str | Path) -> str | None:
+    """Return ``[project].version`` from ``pyproject.toml``, or ``None`` when unusable."""
+    path = Path(pyproject)
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError):
+        return None
+    project = data.get("project")
+    if not isinstance(project, dict):
+        return None
+    value = project.get("version")
+    if not isinstance(value, str) or not VERSION_RE.match(value.strip()):
+        return None
+    return value.strip()
+
+
+def installed_version(dist: str = DIST_NAME) -> str | None:
+    """Return the version recorded in installed distribution metadata, or ``None``."""
+    try:
+        return version(dist)
+    except PackageNotFoundError:
+        return None
+    except Exception:  # pragma: no cover - defensive: corrupt metadata
+        return None
+
+
+def resolve_version() -> str:
+    """Resolve the project version in the documented order."""
+    pyproject = find_pyproject()
+    if pyproject is not None:
+        resolved = read_version(pyproject)
+        if resolved:
+            return resolved
+    return installed_version() or FALLBACK_VERSION
+
+
+#: The project version, read from ``pyproject.toml`` (see :func:`resolve_version`).
+VERSION = resolve_version()

pyshellforge-0.1.0/src/pyshellforge/ast/__init__.py

@@ -0,0 +1,34 @@
+"""Shell-neutral building blocks for a script."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import Node
+from .nodes.echo import Echo
+
+
+@dataclass(frozen=True)
+class Comment(Node):
+    """A comment, with no leading comment marker."""
+
+    text: str
+
+
+@dataclass(frozen=True)
+class VariableAssignment(Node):
+    """Assign a literal value to a shell variable."""
+
+    name: str
+    value: str
+
+
+@dataclass(frozen=True)
+class Command(Node):
+    """A command and literal arguments, never a raw shell fragment."""
+
+    name: str
+    args: tuple[str, ...] = ()
+
+
+__all__ = ["Command", "Comment", "Echo", "Node", "VariableAssignment"]

pyshellforge-0.1.0/src/pyshellforge/ast/base.py

@@ -0,0 +1,5 @@
+"""Base type shared by shell-neutral nodes."""
+
+
+class Node:
+    """Base class for a shell construct."""

pyshellforge-0.1.0/src/pyshellforge/ast/nodes/__init__.py

@@ -0,0 +1 @@
+"""Additional shell-neutral nodes."""

pyshellforge-0.1.0/src/pyshellforge/ast/nodes/echo.py

@@ -0,0 +1,17 @@
+"""A safe, explicit template for printing text."""
+
+from __future__ import annotations
+
+from ..base import Node
+
+
+class Echo(Node):
+    """Print a template: ``{NAME}`` expands a declared variable, ``{{`` is literal.
+
+    ``{NAME!q}`` requests Bash's runtime shell quoting; other conversions and
+    format specifications are not supported. Templates are strings, not Python
+    f-strings, so Python cannot interpolate them before the renderer sees them.
+    """
+
+    def __init__(self, template: str) -> None:
+        self.template = template