go-astty 0.1.0a0__tar.gz

go_astty-0.1.0a0/.gitignore

@@ -0,0 +1,19 @@
+# Environments
+.venv/
+env/
+venv/
+
+# Python Cache
+**/__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Build and Distribution
+build/
+dist/
+*.egg-info/
+
+# Linux System Files
+.DS_Store
+.directory

go_astty-0.1.0a0/LICENSE

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

go_astty-0.1.0a0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: go-astty
+Version: 0.1.0a0
+Summary: go-astty is modular process orchestration gate for seamless synchronous and asynchronous command-line executions in Python.
+Project-URL: Codeberg, https://codeberg.org/Fyllus/go-astty
+Project-URL: Github, https://github.com/Fyllus/go-astty
+Author-email: Fyllus <Fyllus@git.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pygit2>=1.14.0
+Description-Content-Type: text/markdown
+
+# go-astty
+
+`go-astty` or `Gate of Asyncronous and Syncronous TTY`, is a modular process orchestration gate for seamless synchronous and asynchronous command-line executions in Python.
+
+`go-astty` decouples process lifecycle management from standard I/O streams by introducing structured, data-driven pipelines. By abstracting execution payload contexts into self-contained Object vectors, it shifts execution responsibility from external engine hooks directly into individual Task runtimes.
+
+## Architecture
+
+The framework splits execution into two unified, object-oriented components:
+
+* **Tasks (`_BaseTask`)**: Extended list containers acting as payload data vectors. They isolate the executable binary context, handle target system constraints via explicit pre-runtime structural gates (`validation`), and natively invoke their own execution cycles via `.run()`.
+* **Pipers (`_BasePiper`)**: Isolated state engines tied directly to specific task envelopes to capture and track operational boundaries (`stdin`, `stdout`, `stderr`, paths, and exit return codes).
+
+---
+
+## Features
+
+* **Self-Contained Runtimes**: Tasks are no longer passive configuration blocks passed to functional routines; execution logic is encapsulated directly within the task objects (`task.run()`).
+* **Pre-Runtime Validation Gates**: Safe assertion tracks (`shutil.which`) evaluate process structure and binary integrity before booting processes to enforce immediate fail-fast mechanics.
+* **Dual Object Engine Layout**: Mirrored execution architectures separating blocking synchronous behaviors (`syncrun.SyncTask`) and non-blocking asynchronous event routines (`asyncrun.AsyncTask`) cleanly under a predictable interface.
+
+---
+
+## Installation
+
+To install directly from the source repository:
+
+**Clone from Codeberg:**
+
+```bash
+git clone https://codeberg.org/Fyllus/go-astty.git
+
+```
+
+**Clone from GitHub:**
+
+```bash
+git clone https://github.com/fyllus/go-astty.git
+
+```
+
+**Install:**
+
+```bash
+cd goastty
+pip install .
+
+```
+
+---
+
+## Usage Guide
+
+### 1. Asynchronous Execution Pipeline
+
+Perfect for long-running CLI integrations, microservices, or concurrent network-bound stream tracking.
+
+```python
+import asyncio
+from pathlib import Path
+from goastty import asyncrun
+
+async def main():
+    # Instantiate asynchronous task with payload arguments
+    task = asyncrun.AsyncTask("ping", "-c", "5", "google.com")
+    task.piper.path = Path.home()
+    
+    # Fire the self-contained non-blocking runtime
+    await task.run()
+    
+    # Evaluate context matrices safely
+    if task.piper.returncode == 0:
+        print(task.piper.stdout.decode("utf-8"))
+    else:
+        print(f"Error: {task.piper.stderr.decode('utf-8')}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+### 2. Synchronous Execution Pipeline
+
+Ideal for local scripts, standard automation sequences, or linear operational pipelines.
+
+```python
+from pathlib import Path
+from goastty import syncrun
+
+def run_backup():
+    # Build standard array configuration payload
+    task = syncrun.SyncTask("tar", "-czf", "backup.tar.gz", "src/")
+    task.piper.path = Path.cwd()
+    
+    # Invoke execution directly from the task payload instance
+    task.run()
+    
+    print(f"Process finalized with code: {task.piper.returncode}")
+
+if __name__ == "__main__":
+    run_backup()
+
+```
+
+---
+
+## API Specification
+
+### Core Classes
+
+#### `_BasePiper`
+
+The logical data matrix tracking standard streams and execution boundaries.
+
+* `stdout` / `stderr`: Automatic validation and mutation of incremental stream chunks (`bytearray`).
+* `returncode`: Tracking vector for process termination status.
+* `path`: Explicit execution context location directory (`pathlib.Path`).
+* `shell`: Evaluates whether execution requires a target environment shell gateway.
+
+#### `_BaseTask(list)`
+
+An extended list structure executing process payload vectors.
+
+* `prog`: Tracks the execution binary anchor context (`self[0]`).
+* `args`: Slices away argument payloads safely (`self[1:]`).
+* `validation()`: Evaluates process layout constraints and structural target command existence before booting.
+* `run(stdin=None, kwargs)`: Abstract gateway implemented by runtime engines to drive process setups natively.

go_astty-0.1.0a0/README.md

@@ -0,0 +1,127 @@
+# go-astty
+
+`go-astty` or `Gate of Asyncronous and Syncronous TTY`, is a modular process orchestration gate for seamless synchronous and asynchronous command-line executions in Python.
+
+`go-astty` decouples process lifecycle management from standard I/O streams by introducing structured, data-driven pipelines. By abstracting execution payload contexts into self-contained Object vectors, it shifts execution responsibility from external engine hooks directly into individual Task runtimes.
+
+## Architecture
+
+The framework splits execution into two unified, object-oriented components:
+
+* **Tasks (`_BaseTask`)**: Extended list containers acting as payload data vectors. They isolate the executable binary context, handle target system constraints via explicit pre-runtime structural gates (`validation`), and natively invoke their own execution cycles via `.run()`.
+* **Pipers (`_BasePiper`)**: Isolated state engines tied directly to specific task envelopes to capture and track operational boundaries (`stdin`, `stdout`, `stderr`, paths, and exit return codes).
+
+---
+
+## Features
+
+* **Self-Contained Runtimes**: Tasks are no longer passive configuration blocks passed to functional routines; execution logic is encapsulated directly within the task objects (`task.run()`).
+* **Pre-Runtime Validation Gates**: Safe assertion tracks (`shutil.which`) evaluate process structure and binary integrity before booting processes to enforce immediate fail-fast mechanics.
+* **Dual Object Engine Layout**: Mirrored execution architectures separating blocking synchronous behaviors (`syncrun.SyncTask`) and non-blocking asynchronous event routines (`asyncrun.AsyncTask`) cleanly under a predictable interface.
+
+---
+
+## Installation
+
+To install directly from the source repository:
+
+**Clone from Codeberg:**
+
+```bash
+git clone https://codeberg.org/Fyllus/go-astty.git
+
+```
+
+**Clone from GitHub:**
+
+```bash
+git clone https://github.com/fyllus/go-astty.git
+
+```
+
+**Install:**
+
+```bash
+cd goastty
+pip install .
+
+```
+
+---
+
+## Usage Guide
+
+### 1. Asynchronous Execution Pipeline
+
+Perfect for long-running CLI integrations, microservices, or concurrent network-bound stream tracking.
+
+```python
+import asyncio
+from pathlib import Path
+from goastty import asyncrun
+
+async def main():
+    # Instantiate asynchronous task with payload arguments
+    task = asyncrun.AsyncTask("ping", "-c", "5", "google.com")
+    task.piper.path = Path.home()
+    
+    # Fire the self-contained non-blocking runtime
+    await task.run()
+    
+    # Evaluate context matrices safely
+    if task.piper.returncode == 0:
+        print(task.piper.stdout.decode("utf-8"))
+    else:
+        print(f"Error: {task.piper.stderr.decode('utf-8')}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+### 2. Synchronous Execution Pipeline
+
+Ideal for local scripts, standard automation sequences, or linear operational pipelines.
+
+```python
+from pathlib import Path
+from goastty import syncrun
+
+def run_backup():
+    # Build standard array configuration payload
+    task = syncrun.SyncTask("tar", "-czf", "backup.tar.gz", "src/")
+    task.piper.path = Path.cwd()
+    
+    # Invoke execution directly from the task payload instance
+    task.run()
+    
+    print(f"Process finalized with code: {task.piper.returncode}")
+
+if __name__ == "__main__":
+    run_backup()
+
+```
+
+---
+
+## API Specification
+
+### Core Classes
+
+#### `_BasePiper`
+
+The logical data matrix tracking standard streams and execution boundaries.
+
+* `stdout` / `stderr`: Automatic validation and mutation of incremental stream chunks (`bytearray`).
+* `returncode`: Tracking vector for process termination status.
+* `path`: Explicit execution context location directory (`pathlib.Path`).
+* `shell`: Evaluates whether execution requires a target environment shell gateway.
+
+#### `_BaseTask(list)`
+
+An extended list structure executing process payload vectors.
+
+* `prog`: Tracks the execution binary anchor context (`self[0]`).
+* `args`: Slices away argument payloads safely (`self[1:]`).
+* `validation()`: Evaluates process layout constraints and structural target command existence before booting.
+* `run(stdin=None, kwargs)`: Abstract gateway implemented by runtime engines to drive process setups natively.

go_astty-0.1.0a0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "go-astty"
+version = "0.1.0-a"
+description = "go-astty is modular process orchestration gate for seamless synchronous and asynchronous command-line executions in Python."
+readme = "README.md"
+authors = [
+    { name = "Fyllus", email = "Fyllus@git.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pygit2>=1.14.0",
+]
+license = { text = "MIT" }
+
+[project.urls]
+Codeberg = "https://codeberg.org/Fyllus/go-astty"
+Github = "https://github.com/Fyllus/go-astty"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/goastty"]

go_astty-0.1.0a0/src/goastty/__init__.py

@@ -0,0 +1,5 @@
+from . import asyncrun, base, gitfy, syncrun
+
+__version__ = '0.1.0-a'
+
+__all__ = ['asyncrun', 'base', 'syncrun', 'gitfy']

go_astty-0.1.0a0/src/goastty/asyncrun.py

@@ -0,0 +1,72 @@
+import asyncio
+from asyncio import create_subprocess_exec as async_exec
+from asyncio import create_subprocess_shell as async_shell
+from typing import Any
+
+from . import base
+
+
+class AsyncPiper(base._BasePiper):
+    """Asynchronous stream reader and state manager for running sub-processes."""
+    def __init__(self) -> None:
+        super().__init__()
+
+    async def stream_stdout(self, stream: asyncio.StreamReader | None) -> None:
+        """Consume and append chunks from the asynchronous stdout stream buffer."""
+        if not isinstance(stream, asyncio.StreamReader):
+            raise TypeError('<stream> must be StreamReader ')
+        while True:
+            data = await stream.read(4096)
+            if not data:
+                break
+            self.stdout = data
+
+    async def stream_stderr(self, stream: asyncio.StreamReader | None) -> None:
+        """Consume and append chunks from the asynchronous stderr stream buffer."""
+        if not isinstance(stream, asyncio.StreamReader):
+            raise TypeError('<stream> must be StreamReader ')
+        while True:
+            data = await stream.read(4096)
+            if not data:
+                break
+            self.stderr = data
+
+
+class AsyncTask(base._BaseTask):
+    """Asynchronous executable command vector managing an AsyncPiper context."""
+    def __init__(self, *args: str) -> None:
+        super().__init__(*args)
+
+    @property
+    def piper(self) -> AsyncPiper:
+        """Get or initialize the asynchronous stream pipeline manager instance."""
+        if not hasattr(self, '_piper'):
+            setattr(self, '_piper', AsyncPiper())
+        return getattr(self, '_piper')
+
+    async def run(self, stdin: Any = None, **kwargs: Any) -> None:
+        """Execute an AsyncTask asynchronously using either shell or executive sub-processes."""
+        self.validation()
+
+        if stdin is not None:
+            self.piper.stdin_pipe = stdin
+
+        kwargs.setdefault('stdin', self.piper.stdin_pipe)
+        kwargs.setdefault('stdout', self.piper.stdout_pipe)
+        kwargs.setdefault('stderr', self.piper.stderr_pipe)
+        kwargs.setdefault('cwd', self.piper.path)
+
+        if self.piper.shell:
+            cmd_str = " ".join(self)
+            process = await async_shell(cmd_str, **kwargs)
+        else:
+            process = await async_exec(self.prog, *self.args, **kwargs)
+
+        await asyncio.gather(
+            self.piper.stream_stdout(process.stdout),
+            self.piper.stream_stderr(process.stderr)
+        )
+
+        await process.wait()
+        if process.returncode is not None:
+            self.piper.returncode = process.returncode

go_astty-0.1.0a0/src/goastty/base.py

@@ -0,0 +1,211 @@
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Callable, List, TypeVar
+
+PIPE = subprocess.PIPE
+STDOUT = subprocess.STDOUT
+DEVNULL = subprocess.DEVNULL
+
+
+class AssignmentError(Exception):
+    """Exception raised for invalid property or attribute assignments."""
+    def __init__(self, case: str, obj: object, *expected: type) -> None:
+        expected_types = ", ".join(f"<{t.__name__}>" for t in expected)
+        self._cases = {
+            'none': f'Property/Attribute cannot be None: expected {expected_types}, got <{type(obj).__name__}>',
+            'unable': f'Unable to assign type <{type(obj).__name__}>: expected {expected_types}',
+            'invalid': f'Invalid Assignment: expected {expected_types}, cannot use <{type(obj).__name__}>'
+        }
+        super().__init__(self._cases.get(case, f"Unknown error case with type <{type(obj).__name__}>"))
+
+
+class TaskError(Exception):
+    """Exception raised for validation failures before task runtime execution."""
+    def __init__(self, flag: str, task: "_BaseTask") -> None:
+        self._cases = {
+            'empty': f'Unable to run empty task: {task}',
+            'invalid_command': f'Not found or unknown command {task.prog}'
+        }
+        super().__init__(self._cases.get(flag, f'Unknown error case with task {task}'))
+
+
+BaseTask = TypeVar('BaseTask', bound='_BaseTask')
+BasePiper = TypeVar('BasePiper', bound='_BasePiper')
+
+
+class _BasePiper:
+    """Manage stream pipes, exit status, and execution context for a process."""
+    def __init__(self) -> None:
+        pass
+
+    def __getitem__(self, name: str) -> Any:
+        return getattr(self, name)
+
+    def __setitem__(self, name: str, value: Any) -> None:
+        if not hasattr(self, name):
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+        setattr(self, name, value)
+
+    # ---------- class property -------------------
+    @property
+    def stdout(self) -> bytearray:
+        """Get the accumulated standard output bytes."""
+        if not hasattr(self, '_stdout'):
+            setattr(self, '_stdout', bytearray())
+        return getattr(self, '_stdout')
+
+    @stdout.setter
+    def stdout(self, value: bytes | bytearray) -> None:
+        if not isinstance(value, (bytes, bytearray)):
+            raise AssignmentError('invalid', value, bytes, bytearray)
+        self.stdout.extend(value)
+
+    @property
+    def stderr(self) -> bytearray:
+        """Get the accumulated standard error bytes."""
+        if not hasattr(self, '_stderr'):
+            setattr(self, '_stderr', bytearray())
+        return getattr(self, '_stderr')
+
+    @stderr.setter
+    def stderr(self, value: bytes | bytearray) -> None:
+        if not isinstance(value, (bytes, bytearray)):
+            raise AssignmentError('invalid', value, bytes, bytearray)
+        self.stderr.extend(value)
+
+    @property
+    def returncode(self) -> int | None:
+        """Get the process exit code integer after termination."""
+        if not hasattr(self, '_returncode'):
+            setattr(self, '_returncode', None)
+        return getattr(self, '_returncode')
+
+    @returncode.setter
+    def returncode(self, value: int) -> None:
+        if not isinstance(value, int):
+            raise AssignmentError('unable', value, int)
+        self._returncode = value
+
+    @property
+    def stdout_pipe(self) -> int:
+        """Get the internal target destination descriptor for stdout."""
+        if not hasattr(self, '_stdout_pipe'):
+            setattr(self, '_stdout_pipe', PIPE)
+        return getattr(self, '_stdout_pipe')
+
+    @property
+    def stderr_pipe(self) -> int:
+        """Get the internal target destination descriptor for stderr."""
+        if not hasattr(self, '_stderr_pipe'):
+            setattr(self, '_stderr_pipe', PIPE)
+        return getattr(self, '_stderr_pipe')
+
+    @property
+    def stdin_pipe(self) -> Any:
+        """Get the source input stream pipeline anchor for stdin."""
+        if not hasattr(self, '_stdin'):
+            setattr(self, '_stdin', None)
+        return getattr(self, '_stdin')
+
+    @stdin_pipe.setter
+    def stdin_pipe(self, value: Any) -> None:
+        setattr(self, '_stdin', value)
+
+    @property
+    def path(self) -> Path:
+        """Get the filesystem directory context where execution occurs."""
+        if not hasattr(self, '_path'):
+            setattr(self, '_path', Path.cwd())
+        return getattr(self, '_path')
+
+    @path.setter
+    def path(self, value: Path) -> None:
+        if value is None:
+            raise AssignmentError('none', value, Path)
+        if not isinstance(value, Path):
+            raise AssignmentError('unable', value, Path)
+        setattr(self, '_path', value)
+
+    @property
+    def shell(self) -> bool:
+        """Check whether direct system shell execution is enabled."""
+        if not hasattr(self, '_shell'):
+            setattr(self, '_shell', False)
+        return getattr(self, '_shell')
+
+    @shell.setter
+    def shell(self, value: bool) -> None:
+        if not isinstance(value, bool):
+            raise AssignmentError('unable', value, bool)
+        setattr(self, '_shell', value)
+
+
+class _BaseTask(list):
+    """Represent an executable command payload structure as an array of arguments."""
+    def __init__(self, *args: str) -> None:
+        super().__init__()
+        if args:
+            self.extend(args)
+
+    def __bool__(self) -> bool:
+        return len(self) > 0
+
+    # ---------- class property -------------------
+    @property
+    def prog(self) -> str:
+        """Get the root binary filename executable anchor of the command."""
+        if not self:
+            return ''
+        return self[0]
+
+    @property
+    def args(self) -> list:
+        """Get the trailing arguments list passed to the executable payload."""
+        if not len(self) > 1:
+            return []
+        return self[1:]
+
+    @property
+    def piper(self) -> Any:
+        """Get the stream pipeline manager tied to this specific task execution context."""
+        if not hasattr(self, '_piper'):
+            setattr(self, '_piper', _BasePiper())
+        return getattr(self, '_piper')
+
+    @piper.setter
+    def piper(self, value: Any) -> None:
+        if not isinstance(value, _BasePiper):
+            raise AssignmentError('unable', value, _BasePiper)
+        setattr(self, '_piper', value)
+
+    @property
+    def callback(self) -> Any:
+        """Get the execution hook function triggered upon process completion."""
+        return getattr(self, '_callback', None)
+
+    @callback.setter
+    def callback(self, value: Any) -> None:
+        if not callable(value):
+            raise AssignmentError('invalid', value, Callable)
+        setattr(self, '_callback', value)
+
+    # --------------- main methods -------------------------------
+    def append(self, value: str) -> None:
+        """Append a safe string argument entry to the command vector."""
+        if not isinstance(value, str):
+            raise ValueError('Value must be <str>')
+        super().append(value)
+
+    def extend(self, value: List[str]) -> None:
+        """Extend the command argument payload using an array of string slices."""
+        if not all(isinstance(arg_item, str) for arg_item in value):
+            raise ValueError('Value must be <List[str]>')
+        super().extend(value)
+
+    def validation(self) -> None:
+        """Pre-Runtime validation gate to check structural faults before process boot."""
+        if not self:
+            raise TaskError('empty', self)
+        if not self.piper.shell and not shutil.which(self.prog):
+            raise TaskError('invalid_command', self)

go_astty-0.1.0a0/src/goastty/gitfy.py

@@ -0,0 +1,189 @@
+from pathlib import Path
+from typing import (
+    List,
+    Optional,
+    Self,
+)
+
+from pygit2 import (
+    Commit,
+    GitError,
+    Index,
+    Repository,
+    Signature,
+    clone_repository,
+    init_repository,
+)
+
+
+class GitRepoError(Exception):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
+def open_repo(repo: Repository | Path) -> Repository:
+    """Open an existing git repository from a Path or Repository object."""
+    if isinstance(repo, Repository):
+        return repo
+    if not isinstance(repo, Path):
+        raise GitRepoError(f'Invalid repository type <{type(repo).__name__}>, expected <RepositoryOrPath>')
+    try:
+        return Repository(str(repo))
+    except (KeyError, GitError):
+        raise GitRepoError('Not a valid repository inited.')
+
+def is_git(path: Path) -> bool:
+    """Check if the given path is a valid git repository."""
+    try:
+        open_repo(repo=path)
+        return True
+    except GitRepoError:
+        return False
+
+class GitRepo:
+    """
+    TODO: log, status, tag
+    """
+    def __init__(self, repo: Repository | Path) -> None:
+        self.repo = repo
+
+    # ---------------------- class property ---------------------------
+    @property
+    def index(self) -> Index:
+        """Get the repository index (staging area)."""
+        return self.repo.index
+
+    @property
+    def repo(self) -> Repository:
+        """Get the underlying native repository instance."""
+        if not hasattr(self, '_repo'):
+            setattr(self, '_repo', None)
+        return getattr(self, '_repo')
+
+    @property
+    def workdir(self) -> Path:
+        """Get the absolute path to the working directory."""
+        return Path(self.repo.workdir).resolve()
+
+    @repo.setter
+    def repo(self, repo: Repository | Path) -> None:
+        new_repo = open_repo(repo=repo)
+        setattr(self, '_repo', new_repo)
+
+    #  ---------------- repo methods ------------------
+    @classmethod
+    def init(cls, path: Path, bare: bool = False, **kwargs) -> "GitRepo":
+        """Initialize a new git repository or open it if already initialized."""
+        if is_git(path):
+            return cls(open_repo(repo=path))
+        if not path.exists():
+            raise GitRepoError(f"Path does not exist: invalid try to init a repo at '{path}'.")
+        native_repo = init_repository(str(path), bare=bare, **kwargs)
+        return cls(native_repo)
+
+    @classmethod
+    def clone(cls, url: str, path: Path, **kwargs) -> "GitRepo":
+        """Clone a remote git repository into a local directory."""
+        if is_git(path):
+            raise GitRepoError(f"Cannot clone: a valid git repository already exists at '{path}'.")
+        native_repo = clone_repository(url, str(path), **kwargs)
+        return cls(native_repo)
+
+    # ------------- main methods -----------------------------
+    def add(self, *files: Path) -> Self:
+        """Stage files or all modifications to the repository index."""
+        if len(files) == 0:
+            self.index.add_all()
+        else:
+            for file_path in files:
+                abs_path = file_path.resolve()
+                try:
+                    rel_path = abs_path.relative_to(self.workdir)
+                    self.index.add(str(rel_path))
+                except ValueError:
+                    raise ValueError(
+                        f"File {abs_path} out of repository {self.workdir}"
+                    )
+        self.index.write()
+        return self
+
+    def remove(self, *files: Path, staged_only: bool = False) -> Self:
+        """Remove files from the repository index and optionally from the working directory."""
+        for file_path in files:
+            rel_path = file_path.resolve().relative_to(self.workdir)
+            str_path = str(rel_path)
+
+            if str_path in self.index:
+                self.index.remove(str_path)
+
+            if not staged_only:
+                abs_path = self.workdir / rel_path
+                if abs_path.exists():
+                    abs_path.unlink()
+
+        self.index.write()
+        return self
+
+    def move(self, source: Path, destination: Path) -> Self:
+        """Move or rename a file within the working directory and update the index."""
+        abs_src = source.resolve()
+        abs_dst = destination.resolve()
+
+        rel_src = abs_src.relative_to(self.workdir)
+        rel_dst = abs_dst.relative_to(self.workdir)
+
+        if abs_src.exists():
+            abs_dst.parent.mkdir(parents=True, exist_ok=True)
+            abs_src.rename(abs_dst)
+
+        str_src = str(rel_src)
+        if str_src in self.index:
+            self.index.remove(str_src)
+
+        self.index.add(str(rel_dst))
+        self.index.write()
+        return self
+
+    def restore(self, *files: Path, ref: str = 'HEAD') -> Self:
+        """Discard local modifications by restoring files from a specific commit reference."""
+        try:
+            commit = self.repo.revparse_single(ref)
+            commit_tree = commit.tree
+        except KeyError:
+            return self
+
+        if len(files) == 0:
+            self.repo.checkout_tree(commit_tree, strategy=1, directory=str(self.workdir))
+            self.index.read()
+        else:
+            for file_path in files:
+                rel_path = file_path.resolve().relative_to(self.workdir)
+                str_path = str(rel_path)
+
+                self.repo.checkout_tree(
+                    commit_tree,
+                    strategy=1,
+                    paths=[str_path],
+                    directory=str(self.workdir)
+                )
+
+            self.index.read()
+        return self
+
+    def commit(self,
+               author: Signature, committer: Signature,
+               message: str, parents: Optional[List[Commit]] = None,
+               ref: str = 'HEAD'
+               ) -> Self:
+        """Commit staged changes to the repository history."""
+        tree_oid = self.index.write_tree()
+        if parents is None:
+            parents = []
+        if len(parents) == 0:
+            try:
+                current_tip = self.repo.revparse_single(ref)
+                if isinstance(current_tip, Commit):
+                    parents = [current_tip]
+            except KeyError:
+                pass
+        self.repo.create_commit(ref, author, committer, message, tree_oid, parents)
+        return self

go_astty-0.1.0a0/src/goastty/syncrun.py

@@ -0,0 +1,50 @@
+from subprocess import run as shell
+from typing import Any
+
+from . import base
+
+
+class SyncPiper(base._BasePiper):
+    """Synchronous stream reader and state manager for running sub-processes."""
+    def __init__(self) -> None:
+        super().__init__()
+
+
+class SyncTask(base._BaseTask):
+    """Synchronous executable command vector managing a SyncPiper context."""
+    def __init__(self, *args: str) -> None:
+        super().__init__(*args)
+
+    @property
+    def piper(self) -> SyncPiper:
+        """Get or initialize the synchronous stream pipeline manager instance."""
+        if not hasattr(self, '_piper'):
+            setattr(self, '_piper', SyncPiper())
+        return getattr(self, '_piper')
+
+    def run(self, stdin: Any = None, **kwargs: Any) -> None:
+        """Execute a SyncTask synchronously using either shell or executive sub-processes."""
+        self.validation()
+
+        if stdin is not None:
+            self.piper.stdin_pipe = stdin
+
+        kwargs.setdefault('stdin', self.piper.stdin_pipe)
+        kwargs.setdefault('stdout', self.piper.stdout_pipe)
+        kwargs.setdefault('stderr', self.piper.stderr_pipe)
+        kwargs.setdefault('cwd', self.piper.path)
+        kwargs.setdefault('shell', self.piper.shell)
+
+        if not self.piper.shell:
+            cmd = list(self)
+            process = shell(cmd, **kwargs)
+        else:
+            cmd_str = ' '.join(self)
+            process = shell(cmd_str, **kwargs)
+
+        if process.stdout is not None:
+            self.piper.stdout = process.stdout
+        if process.stderr is not None:
+            self.piper.stderr = process.stderr
+
+        self.piper.returncode = process.returncode

go_astty-0.1.0a0/tests/async/test.py

@@ -0,0 +1,29 @@
+import asyncio
+from pathlib import Path
+
+from goastty import asyncrun
+
+
+async def main(c: int = 5) -> None:
+    # Safe argument array context for native ping execution
+    task = asyncrun.AsyncTask("ping", "-Dv", "-c", str(c), "google.com")
+    task.piper.path = Path.home()
+
+    print({"status": "starting", "command": list(task)})
+
+    # Dispatch the execution coroutine to the background event loop
+    run_task = asyncio.create_task(task.run())
+
+    # Monitor engine execution while returncode remains unassigned
+    while task.piper.returncode is None:
+        print("[Async Engine] Awaiting ping response... process actively running.")
+        await asyncio.sleep(0.5)
+
+    await run_task
+
+    print(f"\n[Async Engine] Process finalized with code: {task.piper.returncode}")
+    print(f"Accumulated STDOUT buffer:\n{task.piper.stdout.decode('utf-8', errors='ignore')}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main(5))

go_astty-0.1.0a0/tests/sync/test.py

@@ -0,0 +1,31 @@
+import threading
+import time
+from pathlib import Path
+
+from goastty import syncrun
+
+
+def main(c: int=5) -> None:
+    # Initialize sequential task vector context
+    task = syncrun.SyncTask("ping", "-Dv", "-c", str(c), "google.com")
+    task.piper.path = Path.home()
+
+    print({"status": "starting", "command": list(task)})
+
+    # Dispatch the blocking execution thread to decouple I/O boundary tracking
+    worker_thread = threading.Thread(target=task.run)
+    worker_thread.start()
+
+    # Core main loop monitors the state engine without stopping the thread runtime
+    while task.piper.returncode is None:
+        print("[Sync Engine] Processing execution pipeline... task locked in worker thread.")
+        time.sleep(0.5)
+
+    worker_thread.join()
+
+    print(f"\n[Sync Engine] Process finalized with code: {task.piper.returncode}")
+    print(f"Accumulated STDOUT buffer:\n{task.piper.stdout.decode('utf-8', errors='ignore')}")
+
+
+if __name__ == "__main__":
+    main(5)