Merge branch 'serve-mode' into main

Generated by construct

Author: mtsfoni

CHANGELOG.md

@@ -3,7 +3,11 @@
 ## [Unreleased]
 
 ### Added
+- **Serve mode** — `construct run` now starts `opencode serve` headlessly inside the container (`docker run -d`) and connects a local client from the host. The local client is `opencode attach <url>` when `opencode` is on `$PATH`, or the system default browser as a fallback. This eliminates TUI-in-container rendering issues and lets users interact through their own local opencode setup.
+- **Headless mode** — when passthrough args are provided (`construct [path] -- "message"`), `opencode run --attach <url> <args...>` is run locally instead of launching an interactive TUI.
+- **`--serve-port` flag** — sets the port for the opencode HTTP server inside the container (default `4096`). Distinct from `--port` (application ports). Saved to `last-used.json` and replayed by `construct qs`.
 - **Pass-through args (`--`)** — both `construct [flags] [path] -- <tool-args>` and `construct qs [path] -- <tool-args>` now forward everything after the bare `--` separator verbatim to the tool inside the container (e.g. `construct qs -- continue-session <session-id>`). Pass-through args are not persisted to last-used settings. Debug mode (`--debug`) ignores them.
+- **`--client` flag** — explicitly choose the local client that connects to the opencode server: `tui` (always `opencode attach`; errors if opencode not on PATH), `web` (always opens browser directly), or omit for auto-detect (default: `opencode attach` if on PATH, browser otherwise). `--client web` is incompatible with passthrough args (headless mode requires opencode). Saved to `last-used.json` and replayed by `construct qs`.
 
 ### Fixed
 - **Container startup "Permission denied" errors** — the entrypoint script's heredoc that writes `~/.config/opencode/AGENTS.md` used an unquoted delimiter, causing the shell to treat backtick-wrapped paths (`` `/workspace` ``, `` `/home/agent` ``) as command substitutions. The delimiter is now quoted (`<< 'AGENTSEOF'`), preventing the errors `/workspace: Permission denied` and `/home/agent: Permission denied` on startup.

README.md

@@ -51,7 +51,7 @@ go build -o construct ./cmd/construct
 ## Usage
 
 ```
-construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [path] [-- <tool-args>]
+construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [--serve-port <port>] [--client <tui|web>] [path] [-- <tool-args>]
 construct config <set|unset|list> [--local] [KEY [VALUE]]
 construct qs [path] [-- <tool-args>]
 ```
@@ -63,6 +63,8 @@ construct --stack dotnet /path/to/repo
 construct --stack go ~/projects/myapp
 construct --stack ui --mcp --port 3000 .
 construct --stack go --docker dind .
+construct --client web .
+construct --client tui .
 ```
 
 ### Flags
@@ -76,6 +78,8 @@ construct --stack go --docker dind .
 | `--debug` | `false` | Start an interactive shell instead of the agent (for troubleshooting) |
 | `--mcp` | `false` | Activate MCP servers (e.g. `@playwright/mcp`); requires `--stack ui`, `--stack dotnet-ui`, `--stack dotnet-big-ui`, or `--stack ruby-ui` for browser automation |
 | `--port` | *(none)* | Publish a container port to the host (repeatable). Accepts any format `docker run -p` supports: `3000`, `9000:3000`, `127.0.0.1:3000:3000`. |
+| `--serve-port` | `4096` | Port for the opencode HTTP server inside the container. |
+| `--client` | *(auto)* | Local client to connect to the opencode server: `tui` (always use `opencode attach`; error if not on PATH), `web` (always open browser), or omit for auto-detect. |
 | `--version` | — | Print the construct version and exit. |
 
 ## Quickstart (`qs`)
@@ -86,7 +90,7 @@ After running `construct` at least once in a repo, replay the exact same invocat
 construct qs [path]
 ```
 
-`qs` restores the last `--stack`, `--docker`, `--mcp`, and all `--port` values used for that repo. Settings are stored in `~/.construct/last-used.json`.
+`qs` restores the last `--stack`, `--docker`, `--mcp`, `--port`, `--serve-port`, and `--client` values used for that repo. Settings are stored in `~/.construct/last-used.json`.
 
 You can pass extra arguments to the tool after `--`. They are forwarded verbatim and are not saved to last-used:
 

cmd/construct/main.go

@@ -74,11 +74,13 @@ func runAgent(args []string) {
 	reset := fs.Bool("reset", false, "Wipe and re-seed the agent home volume before starting")
 	mcp := fs.Bool("mcp", false, "Activate MCP servers (e.g. @playwright/mcp); requires --stack ui for browser automation")
 	dockerMode := fs.String("docker", "none", "Docker access mode: none (default, no Docker), dood (Docker-outside-of-Docker via host socket), dind (Docker-in-Docker sidecar)")
+	servePort := fs.Int("serve-port", 0, "Port for the opencode HTTP server inside the container (default 4096)")
+	client := fs.String("client", "", "Local client to connect to the opencode server: tui (opencode attach), web (browser), or empty for auto-detect")
 	var ports portFlag
 	fs.Var(&ports, "port", "Publish a container port to the host (repeatable): --port 3000 --port 8080:8080")
 
 	fs.Usage = func() {
-		fmt.Fprintf(os.Stderr, "Usage: construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [path] [-- <tool-args>]\n\n")
+		fmt.Fprintf(os.Stderr, "Usage: construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [--serve-port <port>] [--client <tui|web>] [path] [-- <tool-args>]\n\n")
 		fmt.Fprintf(os.Stderr, "Subcommands:\n")
 		fmt.Fprintf(os.Stderr, "  config    Manage credential environment variables\n")
 		fmt.Fprintf(os.Stderr, "  qs        Re-run the last stack used in the current repo\n\n")
@@ -95,12 +97,17 @@ func runAgent(args []string) {
 		fmt.Fprintf(os.Stderr, "  none   No Docker access inside the agent container (default)\n")
 		fmt.Fprintf(os.Stderr, "  dood   Docker-outside-of-Docker: bind-mounts the host socket (/var/run/docker.sock)\n")
 		fmt.Fprintf(os.Stderr, "  dind   Docker-in-Docker: starts a privileged dind sidecar container\n")
+		fmt.Fprintf(os.Stderr, "\nClient modes (--client):\n")
+		fmt.Fprintf(os.Stderr, "  <empty>  Auto-detect: opencode attach if opencode on PATH, else browser (default)\n")
+		fmt.Fprintf(os.Stderr, "  tui      Always use opencode attach; error if opencode not on PATH\n")
+		fmt.Fprintf(os.Stderr, "  web      Always open browser directly\n")
 		fmt.Fprintf(os.Stderr, "\nExamples:\n")
 		fmt.Fprintf(os.Stderr, "  construct --stack dotnet /path/to/repo\n")
 		fmt.Fprintf(os.Stderr, "  construct --stack go ~/projects/myapp\n")
 		fmt.Fprintf(os.Stderr, "  construct --stack ui --mcp --port 3000 --port 8080 .\n")
 		fmt.Fprintf(os.Stderr, "  construct --docker dood .\n")
-		fmt.Fprintf(os.Stderr, "  construct --docker dind .\n\n")
+		fmt.Fprintf(os.Stderr, "  construct --docker dind .\n")
+		fmt.Fprintf(os.Stderr, "  construct --client web .\n\n")
 		fmt.Fprintf(os.Stderr, "Flags:\n")
 		fs.PrintDefaults()
 	}
@@ -122,6 +129,13 @@ func runAgent(args []string) {
 		log.Fatalf("unknown docker mode %q; supported modes: none, dood, dind", *dockerMode)
 	}
 
+	switch *client {
+	case "", "tui", "web":
+		// valid
+	default:
+		log.Fatalf("unknown client %q; supported values: tui, web", *client)
+	}
+
 	repoPath := "."
 	if fs.NArg() > 0 {
 		repoPath = fs.Arg(0)
@@ -136,7 +150,7 @@ func runAgent(args []string) {
 
 	// Persist so `construct qs` can replay this invocation.
 	// Pass-through args (after --) are not persisted.
-	if err := config.SaveLastUsed(absRepoPath, *stackName, *mcp, []string(ports), *dockerMode); err != nil {
+	if err := config.SaveLastUsed(absRepoPath, *stackName, *mcp, []string(ports), *dockerMode, *servePort, *client); err != nil {
 		log.Printf("warning: could not save last-used settings: %v", err)
 	}
 
@@ -151,6 +165,8 @@ func runAgent(args []string) {
 		Ports:      []string(ports),
 		DockerMode: *dockerMode,
 		ExtraArgs:  passthroughArgs,
+		ServePort:  *servePort,
+		Client:     *client,
 	}); err != nil {
 		log.Fatal(err)
 	}
@@ -297,6 +313,12 @@ func runQuickstart(args []string) {
 	for _, p := range last.Ports {
 		statusLine += " --port " + p
 	}
+	if last.ServePort != 0 {
+		statusLine += fmt.Sprintf(" --serve-port %d", last.ServePort)
+	}
+	if last.Client != "" {
+		statusLine += " --client " + last.Client
+	}
 	fmt.Fprintln(os.Stderr, statusLine)
 
 	agentArgs := []string{"--stack", last.Stack, "--docker", dockerMode}
@@ -306,6 +328,12 @@ func runQuickstart(args []string) {
 	for _, p := range last.Ports {
 		agentArgs = append(agentArgs, "--port", p)
 	}
+	if last.ServePort != 0 {
+		agentArgs = append(agentArgs, "--serve-port", fmt.Sprintf("%d", last.ServePort))
+	}
+	if last.Client != "" {
+		agentArgs = append(agentArgs, "--client", last.Client)
+	}
 	agentArgs = append(agentArgs, absRepoPath)
 	// Pass-through args are appended after -- so runAgent's splitPassthrough
 	// correctly routes them to runner.Config.ExtraArgs (and they are not saved

docs/spec/client-flag.md

@@ -0,0 +1,63 @@
+# Spec: `--client` flag
+
+## Problem
+
+`construct` currently uses a hardcoded heuristic to decide how to connect the user to the running `opencode serve` server:
+
+1. If `opencode` is on `$PATH` → run `opencode attach <url>` (TUI).
+2. Otherwise → open the URL in a browser.
+
+This is a reasonable default but gives users no control. A user who has `opencode` installed but prefers the web UI must work around the auto-detection. Conversely, a user who knows `opencode` is not on their `$PATH` gets a silent browser fallback with no error. Web and TUI should be equal citizens that the user can explicitly select.
+
+## Solution
+
+Add a `--client` flag to `construct` (and replayed by `construct qs`) with three valid values:
+
+| Value | Meaning |
+|---|---|
+| `""` (empty, default) | Auto-detect: try `opencode attach`; fall back to browser if not found. |
+| `"tui"` | Always use `opencode attach <url>`. Error if `opencode` not on `$PATH`. |
+| `"web"` | Always open the browser directly; skip `opencode` check entirely. |
+
+The flag is saved to `last-used.json` and replayed by `construct qs`. An empty string is omitted from JSON (`omitempty`), meaning old entries behave as auto (the previous default behaviour).
+
+## Behaviour table
+
+| `--client` | `opencode` on `$PATH`? | Passthrough args? | Result |
+|---|---|---|---|
+| `""` (auto) | yes | any | `opencode attach <url>` |
+| `""` (auto) | no | any | browser (`xdg-open`/`open`) |
+| `"tui"` | yes | any | `opencode attach <url>` |
+| `"tui"` | no | any | **error**: "opencode not found on PATH; install opencode or use --client web" |
+| `"web"` | either | none | browser directly |
+| `"web"` | either | present | **fatal error**: "--client web is incompatible with passthrough args (headless requires opencode)" |
+
+Any value other than `""`, `"tui"`, or `"web"` is a fatal validation error at startup.
+
+## Persistence
+
+`Client string \`json:"client,omitempty"\`` is added to `config.LastUsed`. An empty string is absent from JSON, so existing entries continue to behave as auto.
+
+`SaveLastUsed` gains a `client string` parameter. All call sites are updated.
+
+`construct qs` replays `--client <value>` in the `agentArgs` slice only when `last.Client != ""`.
+
+## Error messages
+
+| Condition | Message |
+|---|---|
+| `--client tui` and `opencode` not on PATH | `opencode not found on PATH; install opencode or use --client web` |
+| `--client web` with passthrough args | `--client web is incompatible with passthrough args (headless requires opencode)` |
+| Unknown `--client` value | `unknown client %q; supported values: tui, web` |
+
+## Files changed
+
+| File | Change |
+|---|---|
+| `docs/spec/client-flag.md` | This file — spec |
+| `internal/config/lastused.go` | Add `Client string` to `LastUsed`; add `client string` param to `SaveLastUsed` |
+| `internal/config/lastused_test.go` | Update `SaveLastUsed` call sites; add `TestSaveAndLoadLastUsed_Client` and `TestSaveAndLoadLastUsed_ClientOmittedWhenEmpty` |
+| `internal/runner/runner.go` | Add `Client string` to `Config`; refactor `runLocalAttach` to accept `client string`; add validation in `Run` |
+| `internal/runner/runner_test.go` | Tests for `runLocalAttach` client modes and `Run` validation |
+| `cmd/construct/main.go` | Add `--client` flag; validate; wire into `SaveLastUsed` and `runner.Config`; update `runQuickstart` |
+| `CHANGELOG.md` | Entry under `[Unreleased]` |

docs/spec/passthrough-args.md

@@ -19,6 +19,10 @@ construct qs [path] -- [tool-args...]
 - The `[path]` positional and all `construct` flags are parsed from the portion **before** `--`.
 - If `--` is absent the behaviour is identical to today (no change in the default case).
 - `--debug` mode (`/bin/bash`) still ignores pass-through args — there is nothing useful to forward to a shell.
+- `--client web` is incompatible with pass-through args: headless mode requires `opencode run --attach`, so a browser-only client cannot be used. Passing both results in a fatal error:
+  ```
+  --client web is incompatible with passthrough args (headless requires opencode)
+  ```
 
 ### Examples
 

docs/spec/quickstart-qs.md

@@ -6,7 +6,7 @@ Running `construct` requires remembering the `--stack` flag used last time for a
 
 ## Solution
 
-Introduce a `qs` subcommand that replays the last `--stack`, `--docker`, `--mcp`, and `--port` flags used in a repository without requiring the user to re-type them.
+Introduce a `qs` subcommand that replays the last `--stack`, `--docker`, `--mcp`, `--port`, `--serve-port`, and `--client` flags used in a repository without requiring the user to re-type them.
 
 ## Behaviour
 
@@ -16,10 +16,11 @@ construct qs [path] [-- <tool-args>]
 
 - `path` defaults to the current working directory.
 - Prints all replayed flags to stderr before launching, e.g.:
-  `construct qs: reusing --stack go --docker dind --mcp --port 3000`
+  `construct qs: reusing --stack go --docker dind --mcp --port 3000 --client web`
 - Errors with a clear message if no previous run has been recorded for the given path.
-- Replays `--docker`, `--mcp`, and all `--port` values that were used in the last recorded invocation.
+- Replays `--docker`, `--mcp`, all `--port` values, `--serve-port`, and `--client` that were used in the last recorded invocation.
 - For entries recorded before `--docker` was introduced (no `"docker"` key), defaults to `--docker none`.
+- `--client` is only replayed when it was explicitly set (non-empty); absent/empty means auto-detect and is not added to the args.
 - Anything after a bare `--` separator is forwarded verbatim to the tool inside the container and is **not** saved to last-used (see `docs/spec/passthrough-args.md`).
 
 ## Persistence
@@ -30,11 +31,12 @@ Last-used settings are stored in `~/.construct/last-used.json` as a JSON object
 {
   "/home/alice/projects/myapp": { "stack": "base" },
   "/home/alice/projects/api":   { "stack": "go", "docker": "dind" },
-  "/home/alice/projects/web":   { "stack": "ui", "mcp": true, "ports": ["3000", "8080:8080"], "docker": "dood" }
+  "/home/alice/projects/web":   { "stack": "ui", "mcp": true, "ports": ["3000", "8080:8080"], "docker": "dood" },
+  "/home/alice/projects/srv":   { "stack": "go", "serve_port": 4096, "client": "web" }
 }
 ```
 
-The `mcp` key is omitted when `false`; the `ports` key is omitted when empty; the `docker` key is omitted when empty (legacy entries without a docker mode default to `none` at replay time).
+The `mcp` key is omitted when `false`; the `ports` key is omitted when empty; the `docker` key is omitted when empty (legacy entries without a docker mode default to `none` at replay time); `serve_port` is omitted when zero (defaults to `4096`); `client` is omitted when empty (defaults to auto-detect).
 
 The file is written atomically (write to `.tmp`, then rename) with mode `0600`. The directory is created with mode `0700` if it does not exist.