shell-next 0.1.0__tar.gz

shell_next-0.1.0/.gitattributes

@@ -0,0 +1,7 @@
+* text=auto
+*.py text eol=lf
+*.sh text eol=lf
+*.yml text eol=lf
+*.md text eol=lf
+*.png binary
+*.ps1 text eol=lf

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

@@ -0,0 +1,86 @@
+name: quality
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  contracts:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m ruff check .
+      - run: python -m ruff format --check .
+      - run: python -m mypy
+      - run: python scripts/quality/check_source.py
+      - name: Run platform contracts and collect partial coverage
+        run: python -m pytest --cov --cov-branch --cov-report=xml --cov-fail-under=0
+      - name: Verify installed wheel outside the source checkout
+        run: python -m scripts.release.check_wheel
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-${{ matrix.os }}
+          path: .coverage
+          include-hidden-files: true
+  release-gates:
+    needs: [contracts, rhel8-reference]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - run: python -m pip install -e ".[dev]"
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-*
+          path: reports/coverage
+      - run: python -m coverage combine reports/coverage/coverage-ubuntu-latest/.coverage reports/coverage/coverage-windows-latest/.coverage reports/coverage/coverage-rhel8/.coverage
+      - name: Enforce full combined branch coverage
+        run: python -m coverage report --fail-under=100
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/*
+  rhel8-reference:
+    runs-on: ubuntu-latest
+    container: registry.access.redhat.com/ubi8/ubi:8.10
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with:
+          path: /opt/python
+          key: rhel8-python-3.14.2-v1
+      - run: bash scripts/quality/rhel8.sh
+      - run: /opt/python/bin/python3.14 -m pip install -e ".[dev]"
+      - name: Configure disposable sudo contract account
+        run: |
+          useradd --create-home shellnext
+          echo 'shellnext:shell-next-disposable-ci-password' | chpasswd
+          printf 'Defaults:shellnext timestamp_type=global\nDefaults:shellnext passwd_tries=2\nshellnext ALL=(ALL) ALL\n' > /etc/sudoers.d/shell-next-contract
+          chmod 0440 /etc/sudoers.d/shell-next-contract
+          chown -R shellnext:shellnext "$GITHUB_WORKSPACE"
+      - name: Reference contracts and interactive sudo
+        env:
+          SHELL_NEXT_SUDO_PASSWORD: shell-next-disposable-ci-password
+        run: su -m -s /bin/bash shellnext -c '/opt/python/bin/python3.14 -m pytest --cov --cov-branch --cov-report=xml --cov-fail-under=0'
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-rhel8
+          path: .coverage
+          include-hidden-files: true

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

@@ -0,0 +1,42 @@
+name: publish
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Exact package version to publish after all release gates pass
+        required: true
+permissions:
+  contents: read
+  actions: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - run: python -m pip install -e ".[dev]"
+      - name: Require completed release evidence for this commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ inputs.version }}
+        run: python -m scripts.release.verify
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: verified-distributions
+          path: dist/*
+  pypi:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: verified-distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

shell_next-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+/.coverage
+/.mypy_cache/
+/.pytest_cache/
+/pytest-cache-files-*/
+/.ruff_cache/
+/build/
+/dist/
+/reports/
+/*.egg-info/
+**/__pycache__/
+*.py[cod]
+/.codex_tmp/
+
+/venv/
+/.venv/
+/.coverage.*
+/coverage.xml
+

shell_next-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+- Persistent Bash, PowerShell 7, and cmd sessions for Python 3.14+.
+- Structural process arguments and native scripts with persistent shell state.
+- Managed commands, scoped handles, FIFO queuing, independent observation deadlines,
+  and bounded interruption and cleanup.
+- Manual and planned stdin, literal prompt matching, bounded byte capture,
+  optional durable files, and independent output subscribers.
+- Interactive/noninteractive Bash sudo with separate authentication channels.
+- Strict deterministic mock scenarios through `SessionConfig._session_cls`.
+- RHEL 8, Linux, and Windows contracts, installed-wheel checks, static analysis,
+  and 100% combined branch coverage as publication gates.
+
+Active Windows elevation, terminal emulation, and strict cleanup of privileged
+descendants are unsupported. Forced interruption invalidates the persistent
+session; callers create a new session explicitly.

shell_next-0.1.0/LICENSE

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

shell_next-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: shell-next
+Version: 0.1.0
+Summary: Persistent asynchronous shell sessions with deterministic test doubles
+Project-URL: Repository, https://github.com/gokurakujoudo/shell-next
+Project-URL: Issues, https://github.com/gokurakujoudo/shell-next/issues
+Author: shell-next contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: build>=1.4; extra == 'dev'
+Requires-Dist: mypy>=1.19; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1; extra == 'dev'
+Requires-Dist: pytest-cov>=7; extra == 'dev'
+Requires-Dist: pytest>=9; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# shell-next
+
+Persistent asynchronous Bash, PowerShell, and cmd sessions for Python 3.14+.
+
+```python
+from shell_next import Backend, ProcessCommand, SessionConfig, use_shell_session
+
+
+async def inspect_repository(config: SessionConfig):
+    async with use_shell_session(config) as shell:
+        await shell.chdir("/srv/project")
+        result = await shell.run(ProcessCommand("git", ("status", "--short")), check=True)
+        return result.stdout.tail
+```
+
+Use `ProcessCommand` for executable arguments that must remain structural. Use
+`SessionScript` for backend-native scripts and persistent shell variables,
+functions, and aliases. Shell syntax is never translated between languages.
+
+Install with `python -m pip install shell-next`. Supply
+`SessionConfig(backend=Backend.BASH)` on Linux, or select `Backend.POWERSHELL`
+(PowerShell 7 installed) or `Backend.CMD` on Windows. Python 3.14+ is required.
+
+## Interactive commands
+
+```python
+from shell_next import CommandOptions, StdinMode
+
+
+async def answer_prompt(shell, program):
+    options = CommandOptions(stdin=StdinMode.MANUAL)
+    async with shell.command(program, options=options, timeout=30) as command:
+        await command.expect(b"Name: ")
+        await command.sendline(b"Ada")
+        await command.close_stdin()
+        return await command.wait()
+```
+
+`submit()` immediately registers a command and returns its handle. One session
+executes one command at a time; the default policy rejects concurrent submissions.
+`ConcurrencyPolicy.QUEUE` enables FIFO queuing. Different sessions run independently.
+
+Cancelling `wait()` cancels observation only. Cancelling `run()` or escaping a
+command context requests termination. A force-stopped shell becomes unusable;
+create another session explicitly when required.
+
+## Deterministic application tests
+
+```python
+from shell_next import Emit, MockExpectation, MockScenario, MockShellSession
+
+scenario = MockScenario(
+    [
+        MockExpectation(ProcessCommand("git", ("status", "--short")), (Emit(b" M README.md\n"),)),
+    ]
+)
+config = SessionConfig()
+config._session_cls = MockShellSession.configured(scenario)
+```
+
+Pass this same configuration to application code using `use_shell_session`.
+The mock shares production lifecycle code while keeping execution, state, input,
+and output in memory. Unmatched commands and unconsumed strict expectations fail.
+`Advance(60)` advances mock time without sleeping. Plain
+`config._session_cls = MockShellSession` creates an empty strict scenario.
+
+## Capture and capabilities
+
+Output is bytes. Each stream retains a bounded tail (64 KiB by default), and
+literal prompt matching uses a separate bounded window. Slow event subscribers
+receive an overflow error without blocking primary capture. Opt into full capture
+with `CaptureConfig(directory=existing_directory)`. Results distinguish received
+bytes, durable file bytes, truncation, sealing, and possible unread output.
+
+Inspect `shell.capabilities` before requesting backend-specific behavior.
+Windows active elevation and terminal/PowerShell Host prompt automation are
+unsupported. The library is a process-management API, **not a security sandbox**
+for untrusted scripts.
+
+See the [development specification](docs/development/specification.md),
+[usage guide](docs/usage.md),
+[architecture](docs/development/architecture.md), and
+[release checklist](docs/development/release.md).
+
+## Development
+
+```console
+python -m pip install -e ".[dev]"
+python -m ruff check .
+python -m mypy
+python -m pytest --cov --cov-branch
+python -m build
+python -m twine check dist/*
+```
+
+The package uses only the Python standard library at runtime. Tests that start
+real shells are marked `integration`. Test files mirror production responsibilities;
+reusable test infrastructure lives in `tests/support`.

shell_next-0.1.0/README.md

@@ -0,0 +1,98 @@
+# shell-next
+
+Persistent asynchronous Bash, PowerShell, and cmd sessions for Python 3.14+.
+
+```python
+from shell_next import Backend, ProcessCommand, SessionConfig, use_shell_session
+
+
+async def inspect_repository(config: SessionConfig):
+    async with use_shell_session(config) as shell:
+        await shell.chdir("/srv/project")
+        result = await shell.run(ProcessCommand("git", ("status", "--short")), check=True)
+        return result.stdout.tail
+```
+
+Use `ProcessCommand` for executable arguments that must remain structural. Use
+`SessionScript` for backend-native scripts and persistent shell variables,
+functions, and aliases. Shell syntax is never translated between languages.
+
+Install with `python -m pip install shell-next`. Supply
+`SessionConfig(backend=Backend.BASH)` on Linux, or select `Backend.POWERSHELL`
+(PowerShell 7 installed) or `Backend.CMD` on Windows. Python 3.14+ is required.
+
+## Interactive commands
+
+```python
+from shell_next import CommandOptions, StdinMode
+
+
+async def answer_prompt(shell, program):
+    options = CommandOptions(stdin=StdinMode.MANUAL)
+    async with shell.command(program, options=options, timeout=30) as command:
+        await command.expect(b"Name: ")
+        await command.sendline(b"Ada")
+        await command.close_stdin()
+        return await command.wait()
+```
+
+`submit()` immediately registers a command and returns its handle. One session
+executes one command at a time; the default policy rejects concurrent submissions.
+`ConcurrencyPolicy.QUEUE` enables FIFO queuing. Different sessions run independently.
+
+Cancelling `wait()` cancels observation only. Cancelling `run()` or escaping a
+command context requests termination. A force-stopped shell becomes unusable;
+create another session explicitly when required.
+
+## Deterministic application tests
+
+```python
+from shell_next import Emit, MockExpectation, MockScenario, MockShellSession
+
+scenario = MockScenario(
+    [
+        MockExpectation(ProcessCommand("git", ("status", "--short")), (Emit(b" M README.md\n"),)),
+    ]
+)
+config = SessionConfig()
+config._session_cls = MockShellSession.configured(scenario)
+```
+
+Pass this same configuration to application code using `use_shell_session`.
+The mock shares production lifecycle code while keeping execution, state, input,
+and output in memory. Unmatched commands and unconsumed strict expectations fail.
+`Advance(60)` advances mock time without sleeping. Plain
+`config._session_cls = MockShellSession` creates an empty strict scenario.
+
+## Capture and capabilities
+
+Output is bytes. Each stream retains a bounded tail (64 KiB by default), and
+literal prompt matching uses a separate bounded window. Slow event subscribers
+receive an overflow error without blocking primary capture. Opt into full capture
+with `CaptureConfig(directory=existing_directory)`. Results distinguish received
+bytes, durable file bytes, truncation, sealing, and possible unread output.
+
+Inspect `shell.capabilities` before requesting backend-specific behavior.
+Windows active elevation and terminal/PowerShell Host prompt automation are
+unsupported. The library is a process-management API, **not a security sandbox**
+for untrusted scripts.
+
+See the [development specification](docs/development/specification.md),
+[usage guide](docs/usage.md),
+[architecture](docs/development/architecture.md), and
+[release checklist](docs/development/release.md).
+
+## Development
+
+```console
+python -m pip install -e ".[dev]"
+python -m ruff check .
+python -m mypy
+python -m pytest --cov --cov-branch
+python -m build
+python -m twine check dist/*
+```
+
+The package uses only the Python standard library at runtime. Tests that start
+real shells are marked `integration`. Test files mirror production responsibilities;
+reusable test infrastructure lives in `tests/support`.

shell_next-0.1.0/docs/development/architecture.md

@@ -0,0 +1,60 @@
+# Architecture
+
+The public entry point is `use_shell_session(SessionConfig(...))`. The factory
+selects the implementation before entering the session, including the official
+`config._session_cls` injection point. Application code should depend on this
+interface instead of constructing native adapters.
+
+## Dependency boundaries
+
+| Responsibility | Modules | Tests |
+| --- | --- | --- |
+| Value validation and immutable contracts | `models/{commands,config,capabilities,state,results,input,privilege}`; `errors` | `tests/models` |
+| Session ownership and command lifecycle | `frontend/{session,execution,lease,handle,observation,operations}` | `tests/frontend`, `tests/contracts` |
+| Bounded output and subscriptions | `frontend/{capture,output,finalization}` | `tests/frontend` |
+| Native process and byte transports | `backends/native/{process,channels,containment,termination}` | `tests/backends/native` |
+| Native command protocol | `backends/native/{driver,preparation,syntax,bridge}` | `tests/backends/native` |
+| Bash syntax and sudo | `backends/bash/{syntax,containment,authentication,password_channel}` | `tests/backends/bash` |
+| PowerShell and cmd syntax | `backends/powershell/{syntax,driver.ps1}`; `backends/cmd/syntax` | native and common contract tests |
+| Windows process containment | `backends/windows/{containment,limits}` | `tests/backends/native/test_platform_containment.py` |
+| Deterministic application double | `backends/mock/{session,driver,scenario}` | `tests/backends/mock`, `tests/contracts` |
+
+Quality tools live in `scripts/quality`; packaging and release operations live in
+`scripts/release`. Shared test fixtures belong in `tests/support`. Keep shell
+language details in their backend instead of branching throughout the frontend.
+
+Value models do not start processes or perform I/O. The common frontend owns
+submission, queuing, cancellation, and final results. Drivers own transport
+resources. Both drivers implement the same protocol and feed the same bounded
+capture and input interfaces. Mock code cannot call native driver methods.
+
+Each session owns one idle interpreter, one execution lease, and all its submitted
+commands. Command-specific pipes isolate business input and output from shell
+control messages. A bridge invokes structural processes with argv while inheriting
+the shell's current directory and exported environment. Native scripts run in the
+existing interpreter scope. Wrapper state uses the reserved `sn_`/`$sn_` namespace;
+Bash reserves file descriptor 9 for status messages. Scripts that corrupt the
+protocol invalidate the session rather than causing transparent restart.
+
+Windows uses IOCP named pipes and a Job Object assigned before user commands.
+POSIX uses private FIFOs and a new process group. Native shells are trusted:
+programs that deliberately escape a process group are outside that containment
+guarantee. Active Windows elevation is rejected.
+
+Capture retains bounded tails and rolling match windows. Each file destination
+has a dedicated single-worker executor; transport backpressure limits outstanding
+writes. Subscriber queues are bounded and cannot backpressure primary capture.
+File bytes are called durable only after flush and fsync complete.
+
+Tests must mock external connectivity. Filesystem tests own a TemporaryDirectory.
+Contract tests assert behavior through the public factory; unit tests exercise
+failure boundaries with narrowly scoped fakes. Integration tests assert native
+semantics and process cleanup instead of merely checking an echo command.
+
+Production modules are limited to 200 code-bearing physical lines. Production
+classes and functions use descriptive names without underscore prefixes, except
+Python protocol dunders. Every function and value class uses English rST
+documentation with parameter, return, and intentional-exception documentation.
+Ruff, strict mypy, structural policy checks, and 100% combined branch coverage are
+release gates. Platform-specific tests contribute coverage across the OS matrix;
+coverage must not be lowered or platform implementations excluded to pass release.

shell_next-0.1.0/docs/development/release.md

@@ -0,0 +1,32 @@
+# First release gates
+
+No stable tag or PyPI publication is permitted until these gates are verified.
+Candidate source metadata may carry the intended version while publication
+remains blocked until all evidence passes for that exact commit.
+
+- Common behavioral contracts pass for Mock, Bash, PowerShell 7, and cmd.
+- Bash reference testing includes RHEL 8, persistent state, large simultaneous
+  streams, descendant cleanup, cancellation races, and ignored soft termination.
+- Interactive sudo, cached credentials, wrong passwords, authentication deadlines,
+  separate business stdin, and strict privileged-cleanup rejection pass.
+- PowerShell and cmd pass native script, structural process, persistent state,
+  timeout, cancellation, containment, and unsupported-elevation tests.
+- Mock tests prohibit real subprocesses, filesystem writes, network access,
+  environment/directory mutation, and real sleeps.
+- Ruff, strict mypy, production policy checks, and **100% branch coverage** pass.
+- Repeated lifecycle stress tests detect no process, handle, task, or thread leaks.
+- Wheel and sdist build, metadata checks, and installed-wheel smoke tests pass.
+- GitHub release artifacts are built from the tested commit.
+- PyPI publication uses a configured trusted publisher or the maintainer's existing
+  local PyPI credential configuration.
+
+The optional GitHub publishing workflow uses an environment named `pypi` and
+the PyPA trusted publisher action. Local publication uses Twine after the same
+exact-commit verification. Credentials are never committed to the repository or
+printed by release tooling. A draft release does not establish that gates passed.
+
+For an authorized local release, start with a clean checkout of the tested commit
+and run `python -m scripts.release.publish`. This verifies the complete successful
+quality run, builds both distributions, checks metadata, stages GitHub assets,
+publishes through the existing Twine configuration, and publishes the GitHub
+release. An existing version or asset with different bytes is never overwritten.