From d12d9fccbd3d0f473652fa0457cf5b089c2157c6 Mon Sep 17 00:00:00 2001 From: twilightsaurus <133054450+twilightsaurus@users.noreply.github.com> Date: Thu, 29 Oct 2026 23:11:17 +0200 Subject: [PATCH] fix: clarify installation completion and preservation messages --- deploy/README.md | 21 +++++++++++++----- deploy/install.sh | 13 ++++++++--- docs/roadmap.md | 56 +++++++++++++++++++++++++++++++---------------- docs/status.md | 41 +++++++++++++++++++++++++++------- 4 files changed, 95 insertions(+), 36 deletions(-) diff --git a/deploy/README.md b/deploy/README.md index 27b49bf..de96386 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -206,13 +206,21 @@ Configuration and state directories are kept private to the user. **Managed SSH** and **External SSH**. It creates no public edge. When services are being started, explicit SSH stops/disables the gateway but retains `gateway.env`; it disables only an unchanged Imp-owned Caddy listener. - Operator-owned web configuration is never disabled or modified. -- **direct** requires live services, a public DNS hostname, and interactive - stdin/stdout for a new one-time token handoff. `--hostname` and `--behind-nat` - are valid only with Direct; `--connection direct --no-start` is rejected. + Operator-owned web configuration is never disabled or modified. With + `--no-start`, completion reports installed/configured for SSH, not ready; + existing gateway and public-edge state is preserved. +- **direct** requires live services and a public DNS hostname. When no + `gateway.env` exists, it also requires interactive stdin/stdout for a new + verified one-time token handoff. With retained credentials, completion reports + preservation, not fresh public verification or a new token. + `--hostname` and `--behind-nat` are valid only with Direct; + `--connection direct --no-start` is rejected. - **none** installs normal components without configuring fresh Direct access. On an existing installation it preserves credentials, gateway state, and - public-edge identity; it does not mean delete or disable Direct. + public-edge identity; it does not mean delete or disable Direct. Fresh + install-only completion reports no remote connection configured and Direct + unconfigured; existing-install completion reports connection configuration + preserved. - **no option on an existing install** preserves connection state and operator-owned public edges. No implicit credential rotation occurs. Explicit Direct upgrades may migrate exact owned legacy edge policy even when @@ -321,7 +329,8 @@ port forward available for renewal. This syntax is supported by Caddy 2.6.2 and later; see [Caddy TLS issuer configuration](https://caddyserver.com/docs/caddyfile/directives/tls) and [TLS-ALPN reachability requirements](https://caddyserver.com/docs/automatic-https#tls-alpn-challenge). -After activation, trusted HTTPS GETs to `/unknown`, `/ingest`, and +When no `gateway.env` exists, the installer provisions Direct access. After +activation, trusted HTTPS GETs to `/unknown`, `/ingest`, and `/action-consumer` must each return `404`. NAT readiness dials `127.0.0.1:443` while keeping the public hostname for TLS SNI, certificate hostname validation, and HTTP Host; the locally presented certificate must validate against normal diff --git a/deploy/install.sh b/deploy/install.sh index 2ecf33f..2709a38 100755 --- a/deploy/install.sh +++ b/deploy/install.sh @@ -744,9 +744,12 @@ fi case "$CONNECTION" in ssh) if ((!START_SERVICES)); then - printf '\nServices were not started; existing gateway and public-edge state is preserved.\n' + printf '\nImp is installed and configured for SSH; services were not started.\n' + printf 'Existing gateway and public-edge state is preserved.\n' + else + printf '\nImp is ready for SSH connections.\n' fi - printf '\nImp is ready for SSH connections.\n\nIn Settings -> Connection choose:\n' + printf '\nIn Settings -> Connection choose:\n' printf ' Managed SSH - Imp manages the SSH tunnel\n External SSH - you manage the SSH tunnel\n' ;; direct) @@ -764,7 +767,11 @@ case "$CONNECTION" in fi ;; *) - printf '\nConnection configuration preserved; Direct remains unconfigured on a fresh install.\n' + if ((EXISTING_INSTALL)); then + printf '\nExisting connection configuration preserved.\n' + else + printf '\nNo remote connection configured; Direct remains unconfigured.\n' + fi printf 'To configure later, rerun with --connection ssh or --connection direct --hostname HOST.\n' ;; esac diff --git a/docs/roadmap.md b/docs/roadmap.md index a9efabe..c72f9d3 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -753,43 +753,55 @@ does not remove that requirement. #### Acceptance follow-ups -These are retained priorities, not failed acceptance checks or a new slice: - -- **Startup-file onboarding:** add the missing TinyFugue startup-file selection - UX for first-time operators. -- **Nested includes:** detect duplicate hook loading through nested startup - includes. -- **Upgrade messaging:** correct misleading Direct upgrade output when an - existing configuration is preserved rather than newly provisioned. -- **Retained-edge recovery:** handle deleted `gateway.env` with a retained, - inactive legacy edge, without unsafe ownership adoption or credential recovery. -- **Real-runtime CI:** run the real Caddy routing matrix and native TinyFugue - restart regression in CI rather than relying only on deterministic substitutes. +These priorities do not invalidate Slice 25 acceptance. Their dispositions are: + +- **Startup-file onboarding:** implemented in Slice 26 PR1 #48. +- **Nested includes:** PR1 inspects one level of literal absolute/`~/` includes + and offers manual setup when inspection is unsafe. Arbitrary nested-include + duplicate detection remains open; the bounded implementation does not close it. +- **Upgrade messaging:** implemented by Slice 26 item 5. Retained Direct already + truthfully reports preservation without public verification or a new token; + the remaining corrections cover SSH `--no-start` and fresh install-only versus + upgrade preservation. +- **Retained-edge recovery:** implemented in Slice 26 PR4 #51 for an exact-owned, + inactive legacy edge with missing `gateway.env`; live acceptance remains pending. +- **Real-runtime CI:** remains open. Run the real Caddy routing matrix and native + TinyFugue restart regression in CI rather than relying only on deterministic + substitutes. ## In progress ### Slice 26 - Installation reliability and onboarding -In progress. Bounded scope: +In progress: the five bounded implementation items are implemented; live +infrastructure acceptance remains pending. -1. TinyFugue onboarding/startup integration (PR1): explicit +1. TinyFugue onboarding/startup integration (landed in PR1 + [#48](https://github.com/i-mud/imp/pull/48)): explicit existing-file selection, early hook loading, one-level literal absolute/`~/` include duplicate detection, manual setup when inspection is unsafe, and honest operator confirmation of actual startup ordering. -2. Warning before discarding saved Direct credentials (implemented in PR2): +2. Warning before discarding saved Direct credentials (landed in PR2 + [#49](https://github.com/i-mud/imp/pull/49)): inline confirmation before saving another mode removes the saved Direct URL and token; cancel preserves pending edits without saving. Explicit token replacement while staying Direct is unchanged. -3. Correct NAT preflight error classification (implemented in PR3): a read-only +3. Correct NAT preflight error classification (landed in PR3 + [#50](https://github.com/i-mud/imp/pull/50)): a read-only Python classifier distinguishes directly-addressed DNS from successfully inspected NAT-eligible mismatches. Failed interface inspection and invalid DNS do not offer NAT; accepted offers rerun authoritative NAT validation. 4. Recovery of an exact-owned inactive legacy edge when `gateway.env` is missing - (implemented in PR4): explicit matching Direct setup validates and enables + (landed in PR4 [#51](https://github.com/i-mud/imp/pull/51)): explicit matching + Direct setup validates and enables retained policy under one legacy-baseline journal, then uses the existing new-token handoff and commit. Unsafe state is refused; rollback stops the listener before restoring legacy policy. -5. Installation documentation and completion-message corrections. +5. Installation documentation and completion-message corrections (implemented): + preserve the already-truthful retained Direct output (configuration preserved, + no public verification and no new token); avoid readiness claims for SSH + `--no-start`; distinguish fresh install-only from upgrades preserving existing + connection configuration. PR2 does not change Direct provisioning, native credential persistence, or the protocol. PR3 changes only read-only preflight classification and its installer @@ -797,7 +809,13 @@ decision; public-edge ownership, provisioning, credentials, and rollback remain unchanged. PR4 narrowly extends legacy enable/rollback and gives new Direct installer journals per-invocation ownership; ordinary migrations and credential provisioning are unchanged. -These PRs do not claim live infrastructure acceptance. Item 5 remains outstanding. +These implementations do not claim live infrastructure acceptance or inclusion +in a particular published artifact. Item 5 passed 12 actual-installer smoke +scenarios, five installer fixture tests and `npm run check`; its smoke used +fixture runtime/systemd/public-edge boundaries, not live infrastructure. The +earlier Slice 25 PASS evidence does not accept these later changes. One-level +include inspection does not solve arbitrary nested includes, and real-runtime CI +remains a separate open follow-up. ## Candidate work diff --git a/docs/status.md b/docs/status.md index 154d4a8..b430160 100644 --- a/docs/status.md +++ b/docs/status.md @@ -3,11 +3,12 @@ Canonical status for Imp. Platform-independent checks run in WSL2; the native shell is also runtime-verified on Windows 11 x64. -## Current release and acceptance +## Last recorded published-artifact live acceptance -[`v0.4.1`](https://github.com/i-mud/imp/releases/tag/v0.4.1) is the current -release, published with a Windows x64 installer and a self-contained Linux x86_64 -server bundle. The server needs no host Python. It ships SSH, Direct, and +The last recorded published-artifact live acceptance used the +[`v0.4.1`](https://github.com/i-mud/imp/releases/tag/v0.4.1) Linux server bundle +and the `v0.4.0` Windows x64 installer. The server needs no host Python. It ships +SSH, Direct, and install-only installation, automatic Direct WSS for supported directly-addressed hosts, explicit router/NAT support, and an Imp-restricted Caddy edge with schema-3 literal raw-target isolation. `v0.4.0` introduced that work; `v0.4.1` fixes the @@ -43,10 +44,34 @@ ephemeral checkpoint and still requires a fresh identity-bearing MUD login. Existing TinyFugue sessions using the old hook need one `/load ~/.config/imp/capture.tf`; do not reboot without operator approval. The [Slice 25 evidence](#slice-25---connection-oriented-server-installation) -preserves the initial failures and subsequent passing corrections. Priorities -from acceptance are recorded once in the -[roadmap follow-ups](roadmap.md#acceptance-follow-ups); they are not acceptance -blockers or a Slice 26 assignment. +preserves the initial failures and subsequent passing corrections. The +[roadmap follow-ups](roadmap.md#acceptance-follow-ups) distinguish work implemented +in Slice 26 from retained limitations; they do not invalidate Slice 25 acceptance. + +## Slice 26 implementation — live acceptance pending + +Slice 26 remains in progress for live infrastructure acceptance. PR1 +[#48](https://github.com/i-mud/imp/pull/48) landed startup-file onboarding; PR2 +[#49](https://github.com/i-mud/imp/pull/49) landed the saved Direct-credential +warning; PR3 [#50](https://github.com/i-mud/imp/pull/50) landed NAT preflight +classification; PR4 [#51](https://github.com/i-mud/imp/pull/51) landed exact-owned +retained-edge recovery. + +Item 5 implements completion-message and installation-doc corrections: retained +Direct already reports preservation, no public verification and no new token; +SSH `--no-start` makes no readiness claim; fresh install-only is distinguished +from an upgrade that preserves connection configuration. + +Item 5 verification passed: 12 actual-installer smoke scenarios covered SSH, +install-only, omitted-mode upgrades and fresh/retained Direct, including +credential and service-state preservation where promised. The five installer +fixture tests and `npm run check` also passed. The smoke used isolated homes and +fixture runtime/systemd/public-edge boundaries; it does not prove live connectivity. + +These are implementation dispositions, not new live acceptance or publication +claims. One-level literal include inspection does not cover arbitrary nested +startup includes, and real Caddy/native TinyFugue runtime CI remains open. See the +[Slice 26 scope and evidence limits](roadmap.md#slice-26---installation-reliability-and-onboarding). ## Working end to end