Metadata-Version: 2.4
Name: pyplines-system-manager
Version: 2026.8.1a29
Summary: Install, upgrade, verify, and operate Pyplines installations
Author: Pyplines
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: argon2-cffi<26,>=25
Requires-Dist: bcrypt<6,>=4.2
Requires-Dist: docker<8,>=7.1
Requires-Dist: httpx<1,>=0.28
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: kubernetes<35,>=33
Requires-Dist: paramiko<4,>=3.5
Requires-Dist: psycopg[binary]<4,>=3.2
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<15,>=14
Requires-Dist: textual<7,>=6
Requires-Dist: typer<1,>=0.16

# Pyplines System Manager

`pyplines-system-manager` installs, upgrades, verifies, and diagnoses a
Pyplines appliance in local or dedicated appliance mode through the
Kubernetes, PostgreSQL, and OCI APIs managed behind that boundary.

```console
pipx install pyplines-system-manager
pyplines-system-manager
```

Running without a subcommand in an interactive terminal opens the Textual
management interface. Explicit commands support Rich terminal output and
authoritative JSON for automation. The manager is a capability-based thin
client: it resolves the selected immutable published Platform Release OCI
artifact and uses that release's inventory, Kubernetes resources, migrations,
and image digests. Local Docker and production SSH appliances consume this same
release; Docker and SSH remain internal reconciliation mechanisms, and a source checkout and locally built platform images are not
installation inputs. The manager never shells out to `kubectl`. A newer
platform release does not require reinstalling
the manager when it uses contracts and capabilities the installed client
already supports.

For a local installation, Docker is the only host prerequisite. System Manager
creates real k3s, PostgreSQL, and OCI registry services and never requires the
operator to supply a kubeconfig or run k3d or kubectl. The local registry stores
prepared Function images only; platform workloads are pulled by immutable
digest from the published release repository.

The interactive interface opens on a stable, state-aware main menu:

```text
New Installation
Upgrade Installation
Inspect Installation
Repair Installation
Exit
```

The interface uses the official Pyplines dark semantic palette: navy surfaces,
steel-blue structure, signal-gold focus and primary actions, restrained
functional status colors, and crisp bordered panels. The global header is
simply `Pyplines System Manager`; workflow context belongs to the active screen.

The menu does not change shape as installation state changes. Instead, it
recommends the appropriate workflow, disables actions that are not currently
safe, and keeps the five operator-facing labels stable. It reconstructs state
from the installation, release lock, credentials, Kubernetes resources, and
any unfinished release transaction.

The installation journey is:

```text
Installation configuration → Appliance infrastructure → Installation prerequisites
→ Published Platform Release → PostgreSQL migrations → Platform components
→ Platform readiness → Installation verification → Root authority → Complete
```

Selecting a menu action starts one monotonic controller in one persistent
installer screen. The complete journey remains visible on the left, the current
stage and any required input occupy the main panel, and the full-width Activity
console remains visible below them. Explicit operation results advance stages
automatically.
Inspection does not navigate an active installation and completed stages never
move backwards.

Infrastructure precedes credential checkpointing because a new local appliance
must provide the Kubernetes authority in which installation credentials are
stored. Existing production infrastructure is detected and skipped. Credential
presence is not treated as proof of access: System Manager verifies PostgreSQL,
the complete Platform Release image set, Function Runtimes, and the prepared
Function registry before platform work begins. Anonymous registry access is
accepted only when every required release artifact is readable.

Upgrade and repair both recheck installation prerequisites before assessment or
diagnosis, then use the same release, migration, component, readiness, and
verification stages. System-controlled stages advance automatically. Errors
remain at the failed stage with retry and copyable diagnostic context.

Inspect Installation is read-only. Upgrade and repair use the same Journey
screen and structured progress events as installation.

Plans show the release transition, pending migrations, affected components,
and changed resources. Unchanged Kubernetes resources remain hidden until
explicitly requested. Apply validates stable preconditions—configuration,
release lock, desired release, and transaction identity—rather than comparing
volatile inspection output. A harmless refresh therefore cannot invalidate the
resolved distribution. A meaningful state change causes System Manager to
resolve the distribution again before continuing.

Installation and upgrade work stays in one progress screen with durable
lifecycle stages. An indeterminate activity indicator and the latest structured
status remain visible while work runs. The indicator occupies the available
space to the right of the Activity heading, associating it with the event stream
without taking space from the stage body or input forms. Raw activity remains
visible, independently scrollable, selectable, and copyable. The flow pauses
only for required installation, credential, or Root input; secret values
are never rendered in progress or activity output. Credential requirements open
the inline form and resume automatically after verification; they are not
presented as installation failures. Static stage explanations are omitted from
the main panel.

Drag to select text and press `Ctrl+C` to copy it, press `c` to copy the current
journey, or use the visible copy buttons. The installer cannot be exited while
a stage is actively mutating the installation. Automation commands and their
JSON contracts remain stable.

```console
pyplines-system-manager --config pyplines-installation.yaml configure
pyplines-system-manager --config pyplines-installation.yaml doctor
pyplines-system-manager --output json --config pyplines-installation.yaml plan
pyplines-system-manager --config pyplines-installation.yaml apply --auto-approve
pyplines-system-manager --config pyplines-installation.yaml verify
pyplines-system-manager --config pyplines-installation.yaml stop
pyplines-system-manager --config pyplines-installation.yaml start
```

Interactive workflows may also be opened directly. These commands require a
terminal; the existing `plan`, `apply`, and `verify` commands remain the
automation interface.

```console
pyplines-system-manager --config pyplines-installation.yaml install
pyplines-system-manager --config pyplines-installation.yaml upgrade
pyplines-system-manager --config pyplines-installation.yaml inspect
pyplines-system-manager --config pyplines-installation.yaml repair
```
