rcpanel 0.2.0 - design notes

BOUNDARIES

The panel coordinates native OpenBSD tools. It has no resident daemon, remote
control socket, web server, private configuration database, or monitoring loop.
Native configuration files, service scripts, package records, and the kernel
remain authoritative. A broad map does not imply a form for every native flag.

system_map.py is data and lookup: 295 nodes, 251 endpoints, 12 top-level
categories, and 47 exact read-only command tuples. Codes are explicit stable
paths; additions must not renumber existing entries. A code only navigates.
map_ui.py owns category traversal, search, program review, and the sysctl tree.
Menu positions are keyed by screen and item identity, not a single global
cursor. Numeric navigation is confined to menus/viewers; field digits are text.

system_tools.py discovers executable paths, reads native manuals and sysctl
values, checks report membership, and constructs reviewed program argv. It scans
ten fixed directory groups without executing programs for discovery. Only
libexec trees recurse, to depth three. A scan is bounded to 50,000 directory
entries and 20,000 programs; omissions and access problems remain visible.
Dynamic program identity is the absolute path, not an invented map code.

The report allowlist and arbitrary native-program workflow have distinct
contracts. Reports accept exact fixed argv only. A program is rechecked against
the discovered inventory before launch; root invocation additionally checks
trusted executable ownership and path components. This does not sandbox trusted
program behavior or remove native destructive options. native_ui.py hands the
terminal to an explicitly reviewed executable, argv, and working directory.
The native program may have its own command language; the panel itself uses
no shell evaluation. Manuals and synopses come from the installed system.

services.py owns bounded command execution and rcctl behavior. Runner accepts
an absolute executable and argument vector, supplies a small fixed environment,
and uses / as the working directory. It preserves exit status and up to 1 MiB
of combined output. An incremental decoder preserves split UTF-8 sequences
while streaming. Display code escapes terminal controls. Observer failures do
not abort a child process. Ordinary reads and service operations have deadlines;
package writers explicitly use no deadline.

Service membership is checked against rcctl before action. Because rcctl uses
native shell service scripts, daemon flags receive an additional conservative
character check. Boot-enabled and running-now are separate. Whole-query failure
or unavailable inspection is unknown; successful runtime output follows rcctl's
own checks and cannot independently distinguish every script failure from a
stopped daemon. Commands are never silently forced, retried, or rolled back.

config.py owns one-file transactions in /etc, /var/unbound/etc, and /var/nsd/etc.
Directory descriptors and no-follow opens resist ordinary link substitution.
The file's identity, metadata, and bytes are compared before installation; the
private candidate is checked again after native validation. A durable private
backup precedes atomic replacement. Existing metadata is carried to the new
file. A directory-sync error after replacement is reported as already installed
with incomplete durability, not as an untouched target.

catalog.py registers 47 default paths, 14 native syntax checks, and file-effect
notes. operations.py combines service/configuration operations without curses,
including backup-before-rcctl for startup changes. Installation issues no
service action, but readers can use the new contents immediately or later.
cron's automatic /etc/crontab reload is an explicit example. A validator checks
only its supported main file; includes, derived databases, and external state
are not a multi-file transaction. Alternate daemon paths remain explicit.

templates.py owns two intentionally small configuration languages: a single
HTTP site and local mail. Inputs are validated before rendering. Parsing means
strict recognition of the entire generated format, including comments. A parser
returning None refuses ownership; it is not permission to approximate an
unfamiliar file. Explicit replacement is a separate reviewed operation.

tui.py owns reusable terminal widgets, staged editing, confirmations, and the
worker lifecycle. presentation.py formats results and renders terminal controls
visibly. package_ui.py owns package navigation and a bounded progress tail.
The demo substitutes temporary configuration and in-memory service, package,
kernel, and report data; inventory is illustrative. Native administrative tools
are never called in demo. The user-selected editor is still a real process
editing the temporary draft.

PACKAGE PLAN CONTRACT

packages.py owns fixed pkg_info/pkg_add/pkg_delete argv, installed membership,
repository-search membership, preview issuance, and application. Search accepts
a plain package-name fragment; URLs, paths, leading options, and package-spec
operators are not a second input language. Installation uses an exact result
from the last successful search. Removal/update use exact installed names.

A plan records native -n/-I preview output and status, final argv, a random
one-use token, and a fingerprint of the complete parsed installed inventory
plus manual-install tags. Both are checked around preview and before apply.
Failed, truncated, forged, altered, stale, foreign, or already-used plans cannot
apply. At most 16 outstanding plans are retained per manager. A consumed plan
must be previewed again, including after an unsuccessful apply attempt.

A per-manager mutex and a root-owned mode-0600 advisory file at
/var/run/rcpanel-packages.lock serialize panel package operations. The lock is
released between preview and confirmation; freshness is checked on apply.
Other package clients need not use that lock. The fingerprint is not a snapshot
of all package metadata or the repository, and native dependency checks and
native locking remain authoritative. Preview is advisory, not a frozen install.

Package writers run without an automatic kill timer. Progress streams to the
UI while final capture remains bounded; a failed observer does not kill the
writer. Ordinary package/script output and the native exit status remain
inspectable. Failure may follow partial changes. There is no automatic retry,
rollback, force flag, unsigned-package override, or panel dependency resolver.
The fixed environment excludes ambient PKG_PATH/PKG_DBDIR settings; native
repository configuration is /etc/installurl. The working directory is /.

KERNEL AND FAILURE SEMANTICS

The sysctl browser groups the actual current names, with bounded parsing and
visible unparsed-output warnings. Presence does not establish writability.
Assignments require an exact currently listed name, root, and confirmation.
A native failure remains a failure. Runtime writes do not update sysctl.conf;
editing that file does not apply its assignments to the running kernel.

Panel-managed jobs use a worker while the terminal redraws. The main thread
catches Ctrl+C without abandoning the job and defers SIGHUP/SIGTERM until the
worker exits. It joins the worker before transaction contexts close descriptors.
Package writes can take indefinitely long because database writers have no
panel deadline. A deferred close does not undo a completed change. Native
foreground programs and the editor use their own terminal interaction.

Configuration locks cannot constrain arbitrary root programs or atomically
snapshot includes. Observed conflicts stop installation; another root process
can still race final replacement. Native syntax checks do not prove routing,
credentials, port availability, content access, or future mail delivery.
Failure after a command timeout requires inspection of actual state.

EDITOR is an explicit trust boundary. The chosen editor receives the panel's
privileges and is not sandboxed. Its candidate is reviewed after it exits.
The editor must remain in the foreground, using a wait option when necessary.
Its parent catches SIGINT while the child retains normal interrupt behavior.
Launch/parsing failures and nonzero exits do not install a draft. Terminal
restoration failure is distinguished from ordinary unsupported cursor control.

INSTALLATION AND SCOPE

The installer publishes a complete version directory before replacing the
launcher. An upgrade to 0.2.0 retains 0.1.0's directory. Identical reinstallation
is allowed; changed code at an existing version is refused. The launcher binds
an exact interpreter and uses -I, adding only the selected application path.
Ambient Python import settings do not select privileged application modules.
The install is not a native OpenBSD package and does not register a dependency
on Python; administrators must retain its interpreter.

This release supplies broad access to native tools plus a small number of
structured workflows. It has no general parser for hand-maintained service
configuration, certificate issuance workflow, public-mail/IMAP deployment form,
multi-file transaction, package rollback engine, or automatic firewall policy.
Native OpenBSD acceptance remains a separate unfinished gate from the portable
test suite. See OPENBSD-CHECKLIST.txt and TEST-RESULTS.txt.
