SHARD-657: shard setup sets up a local host or saves a remote connection

.golangci.yml

@@ -49,11 +49,13 @@ linters:
             - $gostd
             - github.com/presmihaylov/shard/models
             - github.com/presmihaylov/shard/pkg/pty
+            - github.com/presmihaylov/shard/pkg/term
             - github.com/presmihaylov/shard/pkg/vzshim
             - github.com/presmihaylov/shard/services/client
             - github.com/presmihaylov/shard/services/sandbox
             - github.com/presmihaylov/shard/services/daemon
             - github.com/presmihaylov/shard/services/serve
+            - github.com/presmihaylov/shard/services/setup
         # models/ is a leaf so that it never participates in an import cycle.
         models-is-a-leaf:
           files:

AGENTS.md

@@ -74,6 +74,7 @@ pkg/reflink/               one clone by reference, and whether a directory's fil
 pkg/xfs/                   mkfs.xfs, the loop mount and the fstab line of one image
 pkg/vz/                    the Virtualization.framework driver: the shim protocol, its client and its server
 pkg/vzshim/                the shim binary embedded in the daemon, installed and ad-hoc signed on first use
+pkg/term/                  the terminal prompts and the live checklist shard setup draws
 
 services/sandbox/          the orchestrator: the lifecycle verbs the daemon serves
 services/image/            pull, unpack, cache policy
@@ -87,6 +88,7 @@ services/daemon/           shard daemon: the wiring of every layer, and the back
 services/api/              the REST handlers the daemon serves over its unix socket
 services/client/           the typed client of that API, which the thin CLI verbs call
 services/serve/            the TCP front: a bearer token, and the bytes onto that socket
+services/setup/            shard setup: inspect this host, install a provider and the daemon, or save a remote
 services/provider/gvisor/       implements models.Provider on gVisor
 services/provider/sysbox/       implements models.Provider on Sysbox
 services/provider/runc/         implements models.Provider on bare runc
@@ -111,9 +113,10 @@ website/                   useshards.com: Astro + Starlight, landing at /, docs
   a driver and it belongs in `services/`. `depguard` enforces this in CI.
 - **Dependencies point one way: `cli` to `services` to `pkg`.** `models` sits
   under all of them.
-- **`cli/` imports `services/client`, `pkg/pty`, `pkg/vzshim`, `models`, the request
-  types in `services/sandbox`, and `services/daemon` and `services/serve` for the
-  two verbs that are a process rather than a client. Nothing else.** A verb holds no
+- **`cli/` imports `services/client`, `pkg/pty`, `pkg/term`, `pkg/vzshim`, `models`, the
+  request types in `services/sandbox`, and `services/daemon`, `services/serve` and
+  `services/setup` for the three verbs that are a process rather than a client.
+  Nothing else.** A verb holds no
   store and no provider: it asks the socket.
   `depguard` enforces the allow list in CI.
 - **`models/` is one package with several files, and it is a leaf.** It imports

README.md

@@ -154,6 +154,7 @@ are in those directories, and [the release guide](docs/release.md) says how an S
 
 ## Documentation
 
+- [Set up a host or a remote connection](docs/setup.md)
 - [CLI commands and options](docs/cli.md)
 - [Daemon, REST API, and remote access](docs/daemon.md)
 - [Provider capabilities and limits](docs/provider.md)

cli/cli.go

@@ -2,6 +2,7 @@
 package cli
 
 import (
+	"cmp"
 	"context"
 	"errors"
 	"flag"
@@ -54,6 +55,9 @@ type App struct {
 
 	// plainWarned is shared by every copy of the App one run makes, so a verb that builds two clients warns once.
 	plainWarned *sync.Once
+
+	// remoteFlag says --remote was passed, so even an empty one names the target and the saved connection names none.
+	remoteFlag bool
 }
 
 // stdin is what exec hands the guest and what secret set reads the value from.
@@ -254,6 +258,7 @@ func commands() []command {
 		{name: "daemon", run: App.daemon, subs: []command{{name: "status", run: App.daemonStatus}}},
 		{name: "info", run: App.info},
 		{name: "serve", run: App.serve},
+		{name: "setup", run: App.setup},
 		{name: "tokens", subs: []command{
 			{name: "mint", run: App.tokensMint},
 			{name: "list", aliases: []string{"ls"}, run: App.tokensList},
@@ -388,6 +393,7 @@ func (a *App) parseGlobals(args []string) ([]string, error) {
 	if err := parseVerb(flags, args); err != nil {
 		return nil, err
 	}
+	flags.Visit(func(f *flag.Flag) { a.remoteFlag = a.remoteFlag || f.Name == "remote" })
 
 	// --version answers before the root is checked, so it never fails.
 	if showVersion {
@@ -435,11 +441,15 @@ func (h *hostList) Set(value string) error {
 	return nil
 }
 
-// client speaks to the daemon on the socket, or through --remote; a verb asks only after its flags parsed, so --help reads no token.
+// client speaks to the daemon on the socket, or through --remote, SHARD_REMOTE or the saved connection; a verb asks only after its flags parsed, so --help reads no token.
 func (a App) client() (*client.Client, error) {
-	// The key and the certificate are read here, so a bad one fails before the verb dials.
-	if a.Remote != "" {
-		c, err := client.NewRemoteFromEnv(a.Remote)
+	saved, err := a.saved()
+	if err != nil {
+		return nil, err
+	}
+	// a.Remote is already --remote or SHARD_REMOTE (fromEnv), so the saved remote comes last; a bad key or certificate fails before the dial.
+	if remote := cmp.Or(a.Remote, saved.Remote); remote != "" {
+		c, err := client.NewRemoteFromEnv(remote, saved)
 		if err != nil {
 			return nil, err
 		}
@@ -469,13 +479,42 @@ func (a App) localClient(verb string) (*client.Client, error) {
 
 // hostOnly refuses a remote for a verb that acts on this host, so it never reports the local result as the server's.
 func (a App) hostOnly(verb string) error {
+	if err := a.noRemote(verb); err != nil {
+		return err
+	}
+	saved, err := a.saved()
+	if err != nil {
+		return err
+	}
+	if saved.Remote == "" {
+		return nil
+	}
+
+	return fmt.Errorf("shard %s runs on the daemon host only and cannot reach the %v; remove it with shard setup to run it here", verb, saved)
+}
+
+// noRemote is hostOnly for daemon and serve: the saved connection names where commands go, never where a daemon runs.
+func (a App) noRemote(verb string) error {
 	if a.Remote == "" {
 		return nil
 	}
 
 	return fmt.Errorf("shard %s runs on the daemon host only and cannot reach %s; unset --remote and %s to run it there", verb, a.Remote, client.RemoteEnv)
 }
 
+// saved is the connection shard setup saved; an explicit --remote "" asks for the socket, so it reads none.
+func (a App) saved() (client.Config, error) {
+	if a.remoteFlag && a.Remote == "" {
+		return client.Config{}, nil
+	}
+	path, err := client.ConfigPath(os.Getenv)
+	if err != nil {
+		return client.Config{}, err
+	}
+
+	return client.LoadConfig(path)
+}
+
 // gotArgs echoes what a verb refused, quoted, so the error shows what was typed rather than a count.
 func gotArgs(args []string) string {
 	if len(args) == 0 {