shell-next 0.1.2__tar.gz → 0.1.3__tar.gz

{shell_next-0.1.2 → shell_next-0.1.3}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.1.3
+
+Released 2026-09-13.
+
+- Fix intermittent cmd session loss by reporting completion after the private
+  batch wrapper returns, before removing its files.
+
+- Accept an upfront text or bytes sudo password in `SessionConfig`, reusing it
+  for explicitly elevated Bash commands through the private authentication
+  channel. Preserve per-command provider precedence and secret-free diagnostics.
+
+- Add an ordered tutorial with complete runnable examples for commands, navigation,
+  environment, native scripts, capture, input, lifecycle, concurrency, sudo,
+  deterministic mocks, and a composed workflow across Bash, PowerShell, and cmd.
+- Verify tutorial discovery, example-file parity, and exact published source
+  execution with native platform and deterministic mock checks.
+- Update the project logo and show it only in the home page content on the
+  documentation site, removing the sidebar logo.
+
 ## 0.1.2
 
 Released 2026-09-11.

{shell_next-0.1.2 → shell_next-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shell-next
-Version: 0.1.2
+Version: 0.1.3
 Summary: Persistent asynchronous shell sessions with deterministic test doubles
 Project-URL: Documentation, https://gokurakujoudo.github.io/shell-next/
 Project-URL: Repository, https://github.com/gokurakujoudo/shell-next
@@ -41,6 +41,13 @@ Description-Content-Type: text/markdown
 
 Persistent asynchronous Bash, PowerShell, and cmd sessions for Python 3.14+.
 
+Bash sudo supports an upfront `SessionConfig(sudo_password=...)` reused by
+explicitly elevated commands, or an asynchronous per-command password provider.
+
+Follow the [step-by-step tutorial](docs/tutorials/index.md) for examples from basic
+commands through a complete workflow on all three backends. Full standalone code
+is in [examples/](examples/README.md).
+
 [Documentation](https://gokurakujoudo.github.io/shell-next/) ·
 [PyPI](https://pypi.org/project/shell-next/) · [Wiki drafts](wiki/README.md)
 

{shell_next-0.1.2 → shell_next-0.1.3}/README.md

@@ -12,6 +12,13 @@
 
 Persistent asynchronous Bash, PowerShell, and cmd sessions for Python 3.14+.
 
+Bash sudo supports an upfront `SessionConfig(sudo_password=...)` reused by
+explicitly elevated commands, or an asynchronous per-command password provider.
+
+Follow the [step-by-step tutorial](docs/tutorials/index.md) for examples from basic
+commands through a complete workflow on all three backends. Full standalone code
+is in [examples/](examples/README.md).
+
 [Documentation](https://gokurakujoudo.github.io/shell-next/) ·
 [PyPI](https://pypi.org/project/shell-next/) · [Wiki drafts](wiki/README.md)
 

{shell_next-0.1.2 → shell_next-0.1.3}/docs/assets/stylesheets/brand.css

@@ -1,105 +1,96 @@
-:root {
-  --shell-ink: #20303a;
-  --shell-blue: #007caa;
-  --shell-accent: #16b8ef;
-}
-
-.wy-side-nav-search,
-.wy-nav-top {
-  background: var(--shell-ink);
-}
-
-.wy-side-nav-search > a img.logo {
-  width: 200px;
-  height: 130px;
-  max-width: 100%;
-  object-fit: cover;
-  border-radius: 12px;
-  margin: 4px auto 12px;
-  padding: 0;
-}
-
-.wy-side-nav-search input[type="text"] {
-  border-color: var(--shell-accent);
-}
-
-.wy-nav-content {
-  max-width: 1040px;
-}
-
-.wy-menu-vertical header,
-.wy-menu-vertical p.caption {
-  color: var(--shell-accent);
-}
-
-.rst-content a {
-  color: var(--shell-blue);
-}
-
-.rst-content h1,
-.rst-content h2,
-.rst-content h3 {
-  color: var(--shell-ink);
-}
-
-.hero {
-  display: grid;
-  grid-template-columns: 220px 1fr;
-  align-items: center;
-  gap: 32px;
-  margin: 0 0 32px;
-}
-
-.hero img {
-  width: 220px;
-  border-radius: 18px;
-}
-
-.hero p {
-  font-size: 1.15rem;
-  line-height: 1.6;
-}
-
-.hero .version {
-  color: #52616b;
-  font-size: 0.85rem;
-  letter-spacing: 0.06em;
-  text-transform: uppercase;
-}
-
-.rst-content .button {
-  display: inline-block;
-  padding: 10px 16px;
-  margin: 4px 8px 4px 0;
-  border-radius: 6px;
-  color: white;
-  background: var(--shell-blue);
-  font-weight: 600;
-}
-
-.rst-content .button.secondary {
-  background: var(--shell-ink);
-}
-
-a:focus-visible,
-button:focus-visible,
-input:focus-visible {
-  outline: 3px solid var(--shell-accent);
-  outline-offset: 3px;
-}
-
-@media (max-width: 600px) {
-  .hero {
-    grid-template-columns: 1fr;
-    gap: 12px;
-  }
-
-  .hero img {
-    width: 170px;
-  }
-
-  .rst-content table.docutils {
-    display: block;
-    overflow-x: auto;
-  }
-}
+:root {
+  --shell-ink: #20303a;
+  --shell-blue: #007caa;
+  --shell-accent: #16b8ef;
+}
+
+.wy-side-nav-search,
+.wy-nav-top {
+  background: var(--shell-ink);
+}
+
+.wy-side-nav-search input[type="text"] {
+  border-color: var(--shell-accent);
+}
+
+.wy-nav-content {
+  max-width: 1040px;
+}
+
+.wy-menu-vertical header,
+.wy-menu-vertical p.caption {
+  color: var(--shell-accent);
+}
+
+.rst-content a {
+  color: var(--shell-blue);
+}
+
+.rst-content h1,
+.rst-content h2,
+.rst-content h3 {
+  color: var(--shell-ink);
+}
+
+.hero {
+  display: grid;
+  grid-template-columns: 220px 1fr;
+  align-items: center;
+  gap: 32px;
+  margin: 0 0 32px;
+}
+
+.hero img {
+  width: 220px;
+  height: auto;
+  border-radius: 18px;
+}
+
+.hero p {
+  font-size: 1.15rem;
+  line-height: 1.6;
+}
+
+.hero .version {
+  color: #52616b;
+  font-size: 0.85rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.rst-content .button {
+  display: inline-block;
+  padding: 10px 16px;
+  margin: 4px 8px 4px 0;
+  border-radius: 6px;
+  color: white;
+  background: var(--shell-blue);
+  font-weight: 600;
+}
+
+.rst-content .button.secondary {
+  background: var(--shell-ink);
+}
+
+a:focus-visible,
+button:focus-visible,
+input:focus-visible {
+  outline: 3px solid var(--shell-accent);
+  outline-offset: 3px;
+}
+
+@media (max-width: 600px) {
+  .hero {
+    grid-template-columns: 1fr;
+    gap: 12px;
+  }
+
+  .hero img {
+    width: 170px;
+  }
+
+  .rst-content table.docutils {
+    display: block;
+    overflow-x: auto;
+  }
+}

{shell_next-0.1.2 → shell_next-0.1.3}/docs/backends.md

@@ -25,6 +25,8 @@ shell scope. Bash descriptor 9 and the `sn_` namespace are reserved for the
 control protocol.
 
 Interactive sudo authentication uses private channels and a unique prompt.
+`SessionConfig.sudo_password` supplies an upfront text/bytes secret for elevated
+commands without an explicit provider; ordinary commands retain their identity.
 Passwords are separate from business stdin and capture. Cached credentials do
 not cause unnecessary provider calls. Elevated scripts run in a separate
 elevated Bash process, so their state does not persist in the ordinary session.

{shell_next-0.1.2 → shell_next-0.1.3}/docs/development/architecture.md

@@ -41,6 +41,11 @@ 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.
 
+The shared submission frontend resolves `SessionConfig.sudo_password` into a
+captured asynchronous provider only for an elevated request without its own
+provider. Both native and mock drivers use their existing authentication paths.
+The configured secret stays out of child environment and configuration serialization.
+
 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.

{shell_next-0.1.2 → shell_next-0.1.3}/docs/development/documentation.md

@@ -4,6 +4,8 @@ The site is built from `docs/` with MkDocs. `mkdocs.yml` owns navigation and
 theme configuration; `docs/assets/stylesheets/brand.css` owns the presentation.
 The supplied `shell-next-logo.png` remains the canonical logo. Its byte-identical
 copy in `docs/assets/` makes site builds independent of remote image hosts.
+The site displays the logo only at the top of the home page content; the sidebar
+uses the site name without a logo.
 
 ## Build and preview
 
@@ -19,6 +21,24 @@ The local preview is served at `http://127.0.0.1:8000`. Generated output lives i
 navigation warnings; the validator also checks generated HTML links, fragments,
 assets, and logo integrity.
 
+## Tutorial examples
+
+`docs/tutorials/index.md` owns the ordered chapter list. Each chapter publishes
+the complete matching `examples/NN-topic.py` source. Update both together;
+documentation tests reject differences and missing or unlisted chapters/files.
+
+Tutorial blocks use `<!-- python-doc-exec native: NN-topic.py -->`, `mock`, or
+`sudo` markers. Documentation tests execute mock blocks and inject deterministic
+sudo scenarios into the exact published code. Integration tests in
+`tests/contracts/test_tutorial_examples.py` execute native blocks on each supported
+host/backend and report genuine platform skips. This does not make legacy,
+unmarked examples executable. To check tutorial native execution separately, run
+`python -m pytest tests/contracts/test_tutorial_examples.py`.
+
+Run Ruff and `python -m mypy examples` after editing standalone examples in
+addition to the normal project checks. Tutorial examples are application code,
+not part of the production source branch-coverage target.
+
 ## GitHub Pages
 
 The `documentation` workflow builds pull requests for review. Pushes to

{shell_next-0.1.2 → shell_next-0.1.3}/docs/development/specification.md

@@ -84,6 +84,10 @@ A Bash `SessionScript` executes in the current Bash state space, a PowerShell `S
 
 A `SessionScript` may modify persistent session state. Such modifications are not rolled back when the script later fails.
 
+On cmd, command completion is reported only after the private batch wrapper
+returns to its caller. Cleanup must not remove a batch file that cmd may still
+read. Consecutive successful commands must preserve session usability.
+
 The package does not convert Bash syntax to PowerShell syntax, PowerShell syntax to cmd syntax, or any other Shell language automatically.
 
 Portable application logic should therefore prefer `ProcessCommand`, `shell.chdir()`, `shell.set_env()`, and `shell.unset_env()` whenever Shell-specific syntax is unnecessary.
@@ -290,6 +294,30 @@ The package must expose privilege capability through `shell.capabilities` before
 
 ### Bash supports interactive and noninteractive sudo in the first release.
 
+`SessionConfig(sudo_password=...)` accepts an upfront password as UTF-8 text or
+raw bytes for use by the session. `None` means no configured password; empty
+text/bytes represent an empty password. Other types, unencodable text, and
+passwords containing CR, LF, or NUL raise `ConfigurationError` without including
+the secret. Text is normalized to UTF-8 bytes during configuration.
+
+An explicitly elevated command with no password provider uses the configured
+password through the existing private interactive authentication transport.
+This enables password authentication even when the request's `interactive`
+field has its default false value. An explicit provider takes precedence.
+Without a session password, existing noninteractive/provider behavior is unchanged.
+Setting the password never elevates an inherited-identity command or authenticates
+at session startup. Windows active elevation and strict privileged cleanup remain
+unsupported. Commands can inherit an elevated request from `SessionConfig.defaults`.
+
+The password is reused for later authentication requests, subject to each
+request's attempt limit; sudo cache hits send no password. No host prompt or
+fallback provider is added. Passwords are excluded from configuration repr,
+equality, `to_dict()`, child environment, command results, and call history.
+The caller-owned configuration retains its password in memory; closing a session
+does not erase it or promise secure memory zeroization. Each submission captures
+its password value; a later change to `shell.config.sudo_password` affects future
+submissions only. The mock copies the caller's configuration when it is created.
+
 The Bash backend on RHEL 8 must support noninteractive sudo and interactive password-based sudo as first-release features.
 
 Interactive sudo must not send a password through a normal business stdin plan.

{shell_next-0.1.2 → shell_next-0.1.3}/docs/getting-started.md

@@ -62,5 +62,6 @@ result = await shell.run(SessionScript('printf "%s" "$answer"'), check=True)
 assert result.stdout.tail == b"42"
 ```
 
-Continue with the [usage guide](usage.md) for interactive input and capture, or
+Continue with the [step-by-step tutorial](tutorials/index.md) for complete examples
+across all three backends, the [usage guide](usage.md) for input and capture, or
 [application testing](testing.md) to replace native execution with a mock.

{shell_next-0.1.2 → shell_next-0.1.3}/docs/index.md

@@ -3,7 +3,7 @@
 <div class="hero">
   <img src="assets/shell-next-logo.png" alt="shell-next logo" width="220" height="220">
   <div>
-    <p class="version">shell-next 0.1.2 · Python 3.14+</p>
+    <p class="version">shell-next 0.1.3 · Python 3.14+</p>
     <p>Persistent asynchronous Bash, PowerShell, and cmd sessions. Own commands through completion, interact with prompts, and test the same application code with a deterministic mock.</p>
     <a class="button" href="getting-started/">Get started</a>
     <a class="button secondary" href="https://github.com/gokurakujoudo/shell-next">View on GitHub</a>
@@ -40,10 +40,13 @@ environment variables, and native shell state persist between normal commands.
   configuration. Declare expected commands, input, output, failures, and virtual time.
 - **Backend honesty.** Discover supported features before execution. Forced
   interruption invalidates the session; there is no hidden restart.
+- **Session sudo password.** Supply `SessionConfig(sudo_password=...)` once for
+  elevated Bash commands, or use a per-command provider for on-demand secrets.
 
 ## Find your next step
 
 - [Getting started](getting-started.md): choose a backend and run your first command.
+- [Step-by-step tutorial](tutorials/index.md): learn each feature with complete runnable examples.
 - [Usage guide](usage.md): input, deadlines, results, capture, and sudo.
 - [Backend support](backends.md): Linux and Windows guarantees and limitations.
 - [Testing applications](testing.md): test production call paths without starting a shell.

shell_next-0.1.3/docs/tutorials/01-commands.md

@@ -0,0 +1,69 @@
+# Ordinary and multiple commands
+
+Start with a normal executable, then add literal arguments, then an ordered
+sequence. This chapter works on Bash, PowerShell, and cmd.
+
+1. Run the selected Python interpreter with `--version`. `await shell.run()`
+   waits through capture and cleanup before returning the result.
+2. Pass each argument separately in `ProcessCommand.args`. The spaces, ampersand,
+   and pipe in the second example are data, so the shell does not execute them.
+3. Await commands in a loop. `check=True` stops the sequence by raising on the
+   first unsuccessful command; the three successful results remain in order.
+
+`ProcessCommand` is for external executables. Shell built-ins such as `cd`,
+PowerShell cmdlets, redirection, and pipes require the portable state helpers or
+`SessionScript`, covered in later chapters. Replace `sys.executable` with an
+installed executable such as `git` when adapting this example.
+
+## Full example
+
+File: [`examples/01-commands.py`](https://github.com/gokurakujoudo/shell-next/blob/main/examples/01-commands.py).
+
+```console
+python examples/01-commands.py bash
+```
+
+On Windows replace `bash` with `powershell` or `cmd`.
+
+<!-- python-doc-exec native: 01-commands.py -->
+```python
+"""Run one command, preserve arguments, then run an ordered sequence."""
+
+import asyncio
+import os
+import sys
+
+from shell_next import Backend, ProcessCommand, SessionConfig, use_shell_session
+
+
+async def main(backend: Backend) -> None:
+    config = SessionConfig(backend=backend, startup_timeout=30)
+    async with use_shell_session(config) as shell:
+        # 1. Run an ordinary external command through the selected shell.
+        result = await shell.run(ProcessCommand(sys.executable, ("--version",)), check=True)
+        assert "Python 3." in result.stdout_str()
+        print(result.stdout_str(), end="")
+
+        # 2. Arguments remain literal, including spaces and shell operators.
+        value = "two words & literal | text"
+        command = ProcessCommand(sys.executable, ("-c", "import sys; print(sys.argv[1])", value))
+        result = await shell.run(command, check=True)
+        assert result.stdout_str().strip() == value
+        assert result.command is command
+
+        # 3. Await each command to preserve order and stop on the first failure.
+        outputs = []
+        for number in (1, 2, 3):
+            command = ProcessCommand(sys.executable, ("-c", f"print({number})"))
+            result = await shell.run(command, check=True, timeout=10)
+            outputs.append(result.stdout_str().strip())
+        assert outputs == ["1", "2", "3"]
+        print(outputs)
+
+
+if __name__ == "__main__":
+    selected = sys.argv[1] if len(sys.argv) > 1 else ("cmd" if os.name == "nt" else "bash")
+    asyncio.run(main(Backend(selected)))
+```
+
+[Tutorial contents](index.md)

shell_next-0.1.3/docs/tutorials/02-navigation.md

@@ -0,0 +1,69 @@
+# Directory navigation
+
+A shell session owns its working directory independently of the Python process.
+These two examples work unchanged on all three backends.
+
+1. Create an isolated workspace and select it with `SessionConfig.cwd`. Query
+   `get_cwd()` to observe the interpreter, then inspect the cached `snapshot()`.
+2. Use `chdir()` with a relative path containing spaces. The next external
+   process inherits that directory. Navigate back using `..` and verify that
+   Python never moved. Absolute paths also work; the final workflow uses one.
+
+The shell closes before `TemporaryDirectory` removes its workspace, which matters
+on Windows where an active process can hold a directory open. After a native
+script changes directories, call `get_cwd()` before relying on the cached snapshot.
+
+## Full example
+
+File: [`examples/02-navigation.py`](https://github.com/gokurakujoudo/shell-next/blob/main/examples/02-navigation.py).
+
+```console
+python examples/02-navigation.py bash
+```
+
+On Windows replace `bash` with `powershell` or `cmd`.
+
+<!-- python-doc-exec native: 02-navigation.py -->
+```python
+"""Inspect and change the shell directory without changing Python's directory."""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from shell_next import Backend, ProcessCommand, SessionConfig, use_shell_session
+
+
+async def main(backend: Backend) -> None:
+    parent_cwd = Path.cwd()
+    with TemporaryDirectory(prefix="shell-next-navigation-") as directory:
+        root = await asyncio.to_thread(Path(directory).resolve)
+        child = root / "project with spaces"
+        child.mkdir()
+        config = SessionConfig(backend=backend, cwd=str(root), startup_timeout=30)
+        async with use_shell_session(config) as shell:
+            # 1. Inspect the initial directory and the cached snapshot.
+            assert Path(await shell.get_cwd()) == root
+            assert shell.snapshot().cwd == str(root)
+
+            # 2. Navigate relatively, then let a child process inherit the cwd.
+            await shell.chdir("project with spaces")
+            assert Path(await shell.get_cwd()) == child
+            command = ProcessCommand(sys.executable, ("-c", "import os; print(os.getcwd())"))
+            result = await shell.run(command, check=True)
+            assert Path(result.stdout_str().strip()) == child
+            await shell.chdir("..")
+            assert Path(await shell.get_cwd()) == root
+            assert Path.cwd() == parent_cwd
+            print("Only the shell moved; Python stayed in", parent_cwd)
+        # Close the shell before removing directories it may still have open.
+
+
+if __name__ == "__main__":
+    selected = sys.argv[1] if len(sys.argv) > 1 else ("cmd" if os.name == "nt" else "bash")
+    asyncio.run(main(Backend(selected)))
+```
+
+[Tutorial contents](index.md)

shell_next-0.1.3/docs/tutorials/03-environment.md

@@ -0,0 +1,74 @@
+# Environment variables
+
+Exported environment variables are inherited by later external commands on
+Bash, PowerShell, and cmd. The Python parent remains unchanged.
+
+1. Supply an initial override through `SessionConfig.env` and query it by name.
+2. Update it with `set_env()` and read it from an external Python process.
+   `get_env()` without a name returns the observed environment dictionary and
+   refreshes the cached snapshot. Avoid printing the whole environment because
+   it may contain credentials.
+3. Remove the variable with `unset_env()`; a subsequent lookup returns `None`.
+
+Portable names are shell identifiers, for example `BUILD_MODE`. Native shell
+variables are different: Bash locals and PowerShell variables are not exported;
+cmd `set` variables are environment variables. Use the next chapter for native
+syntax. Environment queries need enough output retention for their JSON reply;
+a very small `tail_bytes` can cause `SessionProtocolError`.
+
+## Full example
+
+File: [`examples/03-environment.py`](https://github.com/gokurakujoudo/shell-next/blob/main/examples/03-environment.py).
+
+```console
+python examples/03-environment.py bash
+```
+
+On Windows replace `bash` with `powershell` or `cmd`.
+
+<!-- python-doc-exec native: 03-environment.py -->
+```python
+"""Configure, update, inspect, and remove an exported session variable."""
+
+import asyncio
+import os
+import sys
+
+from shell_next import Backend, ProcessCommand, SessionConfig, use_shell_session
+
+
+async def main(backend: Backend) -> None:
+    parent_value = os.environ.get("SHELL_NEXT_DEMO_MODE")
+    config = SessionConfig(
+        backend=backend, env={"SHELL_NEXT_DEMO_MODE": "preview"}, startup_timeout=30
+    )
+    async with use_shell_session(config) as shell:
+        # 1. Initial overrides belong to this session, not the Python parent.
+        assert await shell.get_env("SHELL_NEXT_DEMO_MODE") == "preview"
+        assert os.environ.get("SHELL_NEXT_DEMO_MODE") == parent_value
+
+        # 2. A later process inherits updates made through the portable helper.
+        await shell.set_env("SHELL_NEXT_DEMO_MODE", "release candidate")
+        command = ProcessCommand(
+            sys.executable, ("-c", "import os; print(os.environ['SHELL_NEXT_DEMO_MODE'])")
+        )
+        result = await shell.run(command, check=True)
+        assert result.stdout_str().strip() == "release candidate"
+        environment = await shell.get_env()
+        assert isinstance(environment, dict)
+        assert environment["SHELL_NEXT_DEMO_MODE"] == "release candidate"
+        assert dict(shell.snapshot().environment)["SHELL_NEXT_DEMO_MODE"] == "release candidate"
+
+        # 3. Remove the variable explicitly; None means it is absent.
+        await shell.unset_env("SHELL_NEXT_DEMO_MODE")
+        assert await shell.get_env("SHELL_NEXT_DEMO_MODE") is None
+        assert os.environ.get("SHELL_NEXT_DEMO_MODE") == parent_value
+        print("Session environment updated and removed")
+
+
+if __name__ == "__main__":
+    selected = sys.argv[1] if len(sys.argv) > 1 else ("cmd" if os.name == "nt" else "bash")
+    asyncio.run(main(Backend(selected)))
+```
+
+[Tutorial contents](index.md)