Add full shell, replaceable Omics adapter and bilingual interaction

Implement approved specification #32 and tickets #33-#37. Keep host authentication server-verified and pin session interaction language. Compile scoped base selectors for browser compatibility and retain full gutters during CSS pruning.

tools/tht/internal/config/installation.go

@@ -40,6 +40,7 @@ type descriptor struct {
 	WorkspaceRepository workspaceRepositoryDescriptor `yaml:"workspaceRepository"`
 	Authentication      authenticationDescriptor      `yaml:"authentication"`
 	ModelCatalog        ModelCatalog                  `yaml:"modelCatalog"`
+	Shell               Shell                         `yaml:"shell"`
 	Overrides           []string                      `yaml:"overrides"`
 }
 
@@ -91,6 +92,7 @@ type Installation struct {
 	WorkspaceRepository WorkspaceRepository
 	Authentication      Authentication
 	ModelCatalog        ModelCatalog
+	Shell               Shell
 	Overrides           []string
 }
 
@@ -128,6 +130,9 @@ func Load(path string) (Installation, error) {
 	if err := raw.ModelCatalog.NormalizeDefaults(); err != nil {
 		return Installation{}, err
 	}
+	if err := raw.Shell.NormalizeDefaults(); err != nil {
+		return Installation{}, err
+	}
 
 	if raw.SchemaVersion != 2 {
 		return Installation{}, errors.New("migration_required: installation schemaVersion must be 2")
@@ -176,6 +181,7 @@ func Load(path string) (Installation, error) {
 		},
 		Authentication: authentication,
 		ModelCatalog:   raw.ModelCatalog,
+		Shell:          raw.Shell,
 		Overrides:      make([]string, 0, len(raw.Overrides)),
 	}
 	values, err := installation.environmentValues()
@@ -435,7 +441,7 @@ func (i Installation) ComposeFiles() []string {
 	return files
 }
 
-// GeneratedDirectory contains disposable runtime adapters derived from modelCatalog.
+// GeneratedDirectory contains disposable model and public frontend runtime projections.
 func (i Installation) GeneratedDirectory() string {
 	return filepath.Join(filepath.Dir(i.Path), "generated")
 }
@@ -452,6 +458,10 @@ func (i Installation) GeneratedPiSettingsPath() string {
 	return filepath.Join(i.GeneratedDirectory(), "pi", "settings.json")
 }
 
+func (i Installation) GeneratedFrontendConfigPath() string {
+	return filepath.Join(i.GeneratedDirectory(), "frontend", "config.js")
+}
+
 func (i Installation) ModelProjectionComposePath() string {
 	return filepath.Join(i.GeneratedDirectory(), "compose.models.yaml")
 }

tools/tht/internal/config/installation_shell_test.go

@@ -0,0 +1,113 @@
+package config
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestLoadDefaultsLegacyInstallationToEmbeddedShell(t *testing.T) {
+	for _, profile := range []string{"local", "server"} {
+		t.Run(profile, func(t *testing.T) {
+			path, _, _, _ := writeInstallation(t, profile)
+			installation, err := Load(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got, want := installation.Shell, (Shell{Mode: "embedded", DefaultLocale: "en", Adapter: "omics-portal"}); got != want {
+				t.Fatalf("Shell = %#v, want %#v", got, want)
+			}
+		})
+	}
+}
+
+func TestLoadResolvesExplicitShell(t *testing.T) {
+	for _, test := range []struct {
+		name, yaml string
+		want       Shell
+	}{
+		{"empty mapping", "shell: {}\n", Shell{Mode: "embedded", DefaultLocale: "en", Adapter: "omics-portal"}},
+		{"embedded Italian", "shell:\n  mode: embedded\n  defaultLocale: it\n", Shell{Mode: "embedded", DefaultLocale: "it", Adapter: "omics-portal"}},
+		{"full defaults", "shell:\n  mode: full\n", Shell{Mode: "full", DefaultLocale: "en"}},
+		{"full ignores known adapter", "shell:\n  mode: full\n  defaultLocale: it\n  adapter: omics-portal\n", Shell{Mode: "full", DefaultLocale: "it"}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			path, _, _, _ := writeInstallation(t, "local")
+			appendShellDescriptor(t, path, test.yaml)
+			installation, err := Load(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if installation.Shell != test.want {
+				t.Fatalf("Shell = %#v, want %#v", installation.Shell, test.want)
+			}
+		})
+	}
+}
+
+func TestLoadRejectsInvalidShell(t *testing.T) {
+	for _, test := range []struct{ name, yaml, errorPart string }{
+		{"unknown mode", "shell:\n  mode: fullscreen\n", "shell.mode"},
+		{"mode whitespace", "shell:\n  mode: ' full '\n", "shell.mode"},
+		{"malformed locale separator", "shell:\n  defaultLocale: en_US\n", "shell.defaultLocale"},
+		{"malformed locale", "shell:\n  defaultLocale: 'en;alert(1)'\n", "shell.defaultLocale"},
+		{"unknown adapter", "shell:\n  adapter: other-portal\n", "shell.adapter"},
+		{"unknown adapter in full", "shell:\n  mode: full\n  adapter: other-portal\n", "shell.adapter"},
+		{"wrong shape", "shell: []\n", "cannot unmarshal"},
+		{"wrong field type", "shell:\n  mode: [full]\n", "cannot unmarshal"},
+		{"unknown field", "shell:\n  theme: light\n", "field theme not found"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			path, _, _, _ := writeInstallation(t, "local")
+			appendShellDescriptor(t, path, test.yaml)
+			if _, err := Load(path); err == nil || !strings.Contains(err.Error(), test.errorPart) {
+				t.Fatalf("Load() error = %v, want %q", err, test.errorPart)
+			}
+		})
+	}
+}
+
+func TestLoadPreservesWellFormedShellLocalesWithoutCatalogLookup(t *testing.T) {
+	for _, locale := range []string{
+		"fr", "de-DE", "en-US", "sr-Latn-RS", "es-419", "zh-cmn-Hans-CN",
+		"sl-rozaj-biske", "de-CH-1901", "en-US-u-ca-gregory", "en-a-foo-b-bar-x-private",
+		"x-clinical", "en-x-a-a", "qaa-Qaaa-QM", "zzzz", "abcde", "EN-us",
+		"en-GB-oed", "i-klingon", "sgn-BE-FR", "zh-min-nan",
+	} {
+		t.Run(locale, func(t *testing.T) {
+			path, _, _, _ := writeInstallation(t, "local")
+			appendShellDescriptor(t, path, "shell:\n  mode: full\n  defaultLocale: "+locale+"\n")
+			installation, err := Load(path)
+			if err != nil || installation.Shell.DefaultLocale != locale {
+				t.Fatalf("Load() locale = %q, %v; want preserved %q", installation.Shell.DefaultLocale, err, locale)
+			}
+		})
+	}
+}
+
+func TestLoadRejectsMalformedShellLocales(t *testing.T) {
+	for _, locale := range []string{
+		"en_US", "en--US", "-en", "en-", "e", "123", "en-1234a5678", "en-12",
+		"en-US-Latn", "en-u", "en-x", "x", "a-foo", "i-unknown", "en-äbc", "en-Kaaa",
+		"en US", " en", "en;alert(1)", "sl-rozaj-ROZAJ", "en-a-foo-A-bar",
+	} {
+		t.Run(locale, func(t *testing.T) {
+			path, _, _, _ := writeInstallation(t, "local")
+			appendShellDescriptor(t, path, "shell:\n  defaultLocale: '"+locale+"'\n")
+			if _, err := Load(path); err == nil || !strings.Contains(err.Error(), "shell.defaultLocale") {
+				t.Fatalf("Load() error = %v; want invalid locale %q rejected", err, locale)
+			}
+		})
+	}
+}
+
+func appendShellDescriptor(t *testing.T, path, shell string) {
+	t.Helper()
+	contents, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, append(contents, []byte(shell)...), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}

tools/tht/internal/config/shell.go

@@ -0,0 +1,90 @@
+package config
+
+import (
+	"errors"
+	"regexp"
+	"strings"
+)
+
+// Shell is the public presentation configuration, independent of deployment topology and auth.
+type Shell struct {
+	Mode          string `yaml:"mode" json:"mode"`
+	DefaultLocale string `yaml:"defaultLocale" json:"defaultLocale"`
+	Adapter       string `yaml:"adapter,omitempty" json:"adapter,omitempty"`
+}
+
+// NormalizeDefaults resolves omitted installation settings before projecting them to the browser.
+func (s *Shell) NormalizeDefaults() error {
+	if s.Mode == "" {
+		s.Mode = "embedded"
+	}
+	if s.DefaultLocale == "" {
+		s.DefaultLocale = "en"
+	}
+	if s.Mode != "embedded" && s.Mode != "full" {
+		return errors.New("shell.mode must be full or embedded")
+	}
+	if !wellFormedLocale(s.DefaultLocale) {
+		return errors.New("shell.defaultLocale must be a well-formed BCP47 language tag")
+	}
+	if s.Adapter != "" && s.Adapter != "omics-portal" {
+		return errors.New("shell.adapter must be omics-portal")
+	}
+	if s.Mode == "full" {
+		s.Adapter = ""
+		return nil
+	}
+	if s.Adapter == "" {
+		s.Adapter = "omics-portal"
+	}
+	return nil
+}
+
+// RFC 5646 section 2.1 grammar. Capture variants and extensions to reject duplicates.
+// Validate syntax without consulting a language registry or the frontend's available catalogs.
+var localePattern = regexp.MustCompile(`^(?:` +
+	`(?:[a-z]{2,3}(?:-[a-z]{3}){0,3}|[a-z]{4}|[a-z]{5,8})` + // language / extlang
+	`(?:-[a-z]{4})?(?:-(?:[a-z]{2}|[0-9]{3}))?` + // script / region
+	`((?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*)` + // variants
+	`((?:-[0-9a-wy-z](?:-[a-z0-9]{2,8})+)*)` + // extensions
+	`(?:-x(?:-[a-z0-9]{1,8})+)?` + // private use after a language
+	`|x(?:-[a-z0-9]{1,8})+)$`) // private use alone
+
+func wellFormedLocale(locale string) bool {
+	// BCP47 is ASCII. Check before case folding, which could otherwise map Unicode to ASCII.
+	for _, character := range locale {
+		if character > 127 {
+			return false
+		}
+	}
+	tag := strings.ToLower(locale)
+	// These grandfathered irregular tags do not match the normal language-tag grammar.
+	switch tag {
+	case "en-gb-oed", "i-ami", "i-bnn", "i-default", "i-enochian", "i-hak", "i-klingon",
+		"i-lux", "i-mingo", "i-navajo", "i-pwn", "i-tao", "i-tay", "i-tsu",
+		"sgn-be-fr", "sgn-be-nl", "sgn-ch-de":
+		return true
+	}
+	parts := localePattern.FindStringSubmatch(tag)
+	if parts == nil {
+		return false
+	}
+	variants := make(map[string]bool)
+	for _, variant := range strings.Split(strings.TrimPrefix(parts[1], "-"), "-") {
+		if variants[variant] {
+			return false
+		}
+		variants[variant] = true
+	}
+	singletons := make(map[string]bool)
+	for _, subtag := range strings.Split(parts[2], "-") {
+		if len(subtag) != 1 {
+			continue
+		}
+		if singletons[subtag] {
+			return false
+		}
+		singletons[subtag] = true
+	}
+	return true
+}

tools/tht/internal/modelprojection/projection.go

@@ -1,4 +1,4 @@
-// Package modelprojection renders disposable runtime adapters from the installation model catalog.
+// Package modelprojection renders disposable model and public frontend installation projections.
 package modelprojection
 
 import (
@@ -16,10 +16,11 @@ import (
 )
 
 const (
-	CatalogFile    = "catalog.json"
-	PiModelsFile   = "pi/models.json"
-	PiSettingsFile = "pi/settings.json"
-	ComposeFile    = "compose.models.yaml"
+	CatalogFile        = "catalog.json"
+	PiModelsFile       = "pi/models.json"
+	PiSettingsFile     = "pi/settings.json"
+	ComposeFile        = "compose.models.yaml"
+	FrontendConfigFile = "frontend/config.js"
 )
 
 var renameProjectionDirectory = os.Rename
@@ -77,6 +78,9 @@ func Render(installation config.Installation) (map[string][]byte, error) {
 	if err := installation.ModelCatalog.NormalizeDefaults(); err != nil {
 		return nil, err
 	}
+	if err := installation.Shell.NormalizeDefaults(); err != nil {
+		return nil, err
+	}
 	models := installation.ModelCatalog.RuntimeModels()
 	hasMetadata := false
 	for _, model := range models {
@@ -146,10 +150,21 @@ func Render(installation config.Installation) (map[string][]byte, error) {
 		return nil, fmt.Errorf("render Pi settings projection: %w", err)
 	}
 	fingerprint := sha256.Sum256(bytes.Join([][]byte{catalogBytes, piModelsBytes, piSettingsBytes}, nil))
-	composeBytes := renderCompose(installation, fmt.Sprintf("sha256:%x", fingerprint))
+	publicJSON, err := marshalJSON(struct {
+		BackendBaseURL string       `json:"backendBaseUrl"`
+		Shell          config.Shell `json:"shell"`
+	}{BackendBaseURL: "/api", Shell: installation.Shell})
+	if err != nil {
+		return nil, fmt.Errorf("render public frontend configuration: %w", err)
+	}
+	publicJS := append([]byte("window.__THOTHII_CONFIG__ = "), bytes.TrimSpace(publicJSON)...)
+	publicJS = append(publicJS, ';', '\n')
+	publicFingerprint := sha256.Sum256(publicJS)
+	composeBytes := renderCompose(installation, fmt.Sprintf("sha256:%x", fingerprint), fmt.Sprintf("sha256:%x", publicFingerprint))
 	return map[string][]byte{
 		CatalogFile: catalogBytes, PiModelsFile: piModelsBytes,
 		PiSettingsFile: piSettingsBytes, ComposeFile: composeBytes,
+		FrontendConfigFile: publicJS,
 	}, nil
 }
 
@@ -210,10 +225,14 @@ func Generate(installation config.Installation) error {
 }
 
 func projectionMatches(directory string, artifacts map[string][]byte) bool {
+	if !projectionModeMatches(directory, 0o755) {
+		return false
+	}
 	for _, relative := range sortedArtifactPaths(artifacts) {
 		path := filepath.Join(directory, filepath.FromSlash(relative))
 		info, err := os.Lstat(path)
-		if err != nil || !info.Mode().IsRegular() {
+		if err != nil || !info.Mode().IsRegular() || !projectionModeMatches(path, 0o644) ||
+			!projectionModeMatches(filepath.Dir(path), 0o755) {
 			return false
 		}
 		actual, err := os.ReadFile(path)
@@ -224,6 +243,14 @@ func projectionMatches(directory string, artifacts map[string][]byte) bool {
 	return true
 }
 
+func projectionModeMatches(path string, mode os.FileMode) bool {
+	if runtime.GOOS == "windows" {
+		return true // POSIX mode bits do not represent Windows access controls.
+	}
+	info, err := os.Lstat(path)
+	return err == nil && info.Mode()&os.ModeSymlink == 0 && info.Mode().Perm() == mode
+}
+
 func writeProjectionCandidate(directory string, artifacts map[string][]byte) error {
 	if err := os.Chmod(directory, 0o755); err != nil {
 		return fmt.Errorf("protect model projection candidate: %w", err)
@@ -233,9 +260,16 @@ func writeProjectionCandidate(directory string, artifacts map[string][]byte) err
 		if err := os.MkdirAll(filepath.Dir(destination), 0o755); err != nil {
 			return fmt.Errorf("create model projection directory: %w", err)
 		}
+		if err := os.Chmod(filepath.Dir(destination), 0o755); err != nil {
+			return fmt.Errorf("set runtime projection directory permissions: %w", err)
+		}
 		if err := os.WriteFile(destination, artifacts[relative], 0o644); err != nil {
 			return fmt.Errorf("write model projection candidate: %w", err)
 		}
+		// Creation modes are filtered by the host umask; container readers have another UID.
+		if err := os.Chmod(destination, 0o644); err != nil {
+			return fmt.Errorf("set runtime projection file permissions: %w", err)
+		}
 	}
 	return nil
 }
@@ -251,7 +285,7 @@ func absentTemporaryPath(parent string) (string, error) {
 	return path, nil
 }
 
-// Check returns relative artifact names whose current bytes differ from the catalog projection.
+// Check returns relative artifact names whose bytes or POSIX modes differ from the projection.
 func Check(installation config.Installation) ([]string, error) {
 	artifacts, err := Render(installation)
 	if err != nil {
@@ -259,8 +293,11 @@ func Check(installation config.Installation) ([]string, error) {
 	}
 	drift := make([]string, 0)
 	for _, relative := range sortedArtifactPaths(artifacts) {
-		actual, readErr := os.ReadFile(filepath.Join(installation.GeneratedDirectory(), filepath.FromSlash(relative)))
-		if readErr != nil || !bytes.Equal(actual, artifacts[relative]) {
+		path := filepath.Join(installation.GeneratedDirectory(), filepath.FromSlash(relative))
+		actual, readErr := os.ReadFile(path)
+		if readErr != nil || !bytes.Equal(actual, artifacts[relative]) ||
+			!projectionModeMatches(installation.GeneratedDirectory(), 0o755) ||
+			!projectionModeMatches(filepath.Dir(path), 0o755) || !projectionModeMatches(path, 0o644) {
 			drift = append(drift, relative)
 		}
 	}
@@ -275,9 +312,19 @@ func marshalJSON(value any) ([]byte, error) {
 	return append(contents, '\n'), nil
 }
 
-func renderCompose(installation config.Installation, fingerprint string) []byte {
+func renderCompose(installation config.Installation, fingerprint, publicFingerprint string) []byte {
 	embedding := installation.ModelCatalog.Embedding
 	return []byte(fmt.Sprintf(`services:
+  frontend:
+    environment:
+      THT_FRONTEND_CONFIG_REVISION: %s
+    volumes:
+      - type: bind
+        source: %s
+        target: /usr/share/nginx/html/config.js
+        read_only: true
+        bind:
+          create_host_path: false
   core:
     environment:
       THT_HOST_PLATFORM: %s
@@ -308,7 +355,8 @@ func renderCompose(installation config.Installation, fingerprint string) []byte
   embedding-model-init:
     environment:
       OLLAMA_MODEL: %s
-`, strconv.Quote(runtime.GOOS), strconv.Quote(fingerprint), strconv.Quote(installation.ModelCatalog.Defaults.Interaction),
+`, strconv.Quote(publicFingerprint), strconv.Quote(installation.GeneratedFrontendConfigPath()),
+		strconv.Quote(runtime.GOOS), strconv.Quote(fingerprint), strconv.Quote(installation.ModelCatalog.Defaults.Interaction),
 		strconv.Quote(embedding.ID), strconv.Quote(embeddingModelName(embedding.ID)), strconv.Quote(strconv.Itoa(embedding.Dimensions)),
 		strconv.Quote(installation.GeneratedModelCatalogPath()), strconv.Quote(installation.GeneratedPiModelsPath()),
 		strconv.Quote(installation.GeneratedPiSettingsPath()), strconv.Quote(embedding.ID),

tools/tht/internal/modelprojection/projection_permissions_unix_test.go

@@ -0,0 +1,88 @@
+//go:build linux || darwin
+
+package modelprojection
+
+import (
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+
+	"github.com/aritmolab/thothii/tools/tht/internal/config"
+)
+
+func TestGenerateKeepsProjectionsContainerReadableWithRestrictiveUmask(t *testing.T) {
+	installation := projectionFixture(t)
+	parentBefore, err := os.Stat(filepath.Dir(installation.Path))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// This test must remain sequential: umask is process-wide.
+	previous := syscall.Umask(0o077)
+	defer syscall.Umask(previous)
+	if err := Generate(installation); err != nil {
+		t.Fatal(err)
+	}
+	assertContainerProjectionModes(t, installation)
+	parentAfter, err := os.Stat(filepath.Dir(installation.Path))
+	if err != nil || parentAfter.Mode().Perm() != parentBefore.Mode().Perm() {
+		t.Fatalf("generation changed private installation directory permissions: %v", err)
+	}
+}
+
+func TestGenerateRepairsUnreadableProjectionAsANewGeneration(t *testing.T) {
+	installation := projectionFixture(t)
+	if err := Generate(installation); err != nil {
+		t.Fatal(err)
+	}
+	before, err := os.Stat(installation.GeneratedDirectory())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for path, mode := range map[string]os.FileMode{
+		installation.GeneratedDirectory():                  0o700,
+		filepath.Dir(installation.GeneratedPiModelsPath()): 0o700,
+		installation.GeneratedFrontendConfigPath():         0o600,
+	} {
+		if err := os.Chmod(path, mode); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if drift, err := Check(installation); err != nil || len(drift) == 0 {
+		t.Fatalf("unreadable projection drift = %v, %v", drift, err)
+	}
+	if err := Generate(installation); err != nil {
+		t.Fatal(err)
+	}
+	assertContainerProjectionModes(t, installation)
+	after, err := os.Stat(installation.GeneratedDirectory())
+	if err != nil || os.SameFile(before, after) {
+		t.Fatalf("permissions were not repaired through candidate publication: %v", err)
+	}
+	if drift, err := Check(installation); err != nil || len(drift) != 0 {
+		t.Fatalf("repaired projection drift = %v, %v", drift, err)
+	}
+}
+
+func assertContainerProjectionModes(t *testing.T, installation config.Installation) {
+	t.Helper()
+	for path, mode := range map[string]os.FileMode{
+		installation.GeneratedDirectory():                        0o755,
+		filepath.Dir(installation.GeneratedFrontendConfigPath()): 0o755,
+		filepath.Dir(installation.GeneratedPiModelsPath()):       0o755,
+		installation.GeneratedFrontendConfigPath():               0o644,
+		installation.GeneratedModelCatalogPath():                 0o644,
+		installation.GeneratedPiModelsPath():                     0o644,
+		installation.GeneratedPiSettingsPath():                   0o644,
+		installation.ModelProjectionComposePath():                0o644,
+	} {
+		info, err := os.Stat(path)
+		if err != nil {
+			t.Error(err)
+			continue
+		}
+		if info.Mode().Perm() != mode {
+			t.Errorf("%s mode = %04o, want %04o for container readers", path, info.Mode().Perm(), mode)
+		}
+	}
+}

tools/tht/internal/modelprojection/projection_test.go

@@ -24,8 +24,8 @@ func TestRenderProducesDeterministicCatalogPiAndComposeProjections(t *testing.T)
 	if err != nil {
 		t.Fatalf("Render() second error = %v", err)
 	}
-	if len(first) != 4 {
-		t.Fatalf("artifact count = %d, want 4", len(first))
+	if len(first) != 5 {
+		t.Fatalf("artifact count = %d, want 5", len(first))
 	}
 	for path, contents := range first {
 		if !bytes.Equal(contents, second[path]) {
@@ -133,6 +133,7 @@ func TestGenerateDoesNotReplaceUnchangedProjection(t *testing.T) {
 		installation.GeneratedModelCatalogPath(),
 		installation.GeneratedPiModelsPath(),
 		installation.GeneratedPiSettingsPath(),
+		installation.GeneratedFrontendConfigPath(),
 		installation.ModelProjectionComposePath(),
 	}
 	before := make(map[string]os.FileInfo, len(paths))
@@ -174,7 +175,7 @@ func TestGenerateRestoresWholePreviousGenerationWhenPublishFails(t *testing.T) {
 		t.Fatalf("Generate() initial error = %v", err)
 	}
 	before := make(map[string][]byte)
-	for _, path := range []string{CatalogFile, PiModelsFile, PiSettingsFile, ComposeFile} {
+	for _, path := range []string{CatalogFile, PiModelsFile, PiSettingsFile, ComposeFile, FrontendConfigFile} {
 		contents, err := os.ReadFile(filepath.Join(installation.GeneratedDirectory(), filepath.FromSlash(path)))
 		if err != nil {
 			t.Fatal(err)

tools/tht/internal/modelprojection/shell_projection_test.go

@@ -0,0 +1,139 @@
+package modelprojection
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/aritmolab/thothii/tools/tht/internal/config"
+	"gopkg.in/yaml.v3"
+)
+
+func TestRenderPublicShellConfiguration(t *testing.T) {
+	for _, test := range []struct {
+		name  string
+		shell config.Shell
+		want  string
+	}{
+		{"legacy", config.Shell{}, `{"backendBaseUrl":"/api","shell":{"mode":"embedded","defaultLocale":"en","adapter":"omics-portal"}}`},
+		{"full", config.Shell{Mode: "full", Adapter: "omics-portal"}, `{"backendBaseUrl":"/api","shell":{"mode":"full","defaultLocale":"en"}}`},
+		{"Italian", config.Shell{Mode: "embedded", DefaultLocale: "it"}, `{"backendBaseUrl":"/api","shell":{"mode":"embedded","defaultLocale":"it","adapter":"omics-portal"}}`},
+		{"locale without catalog", config.Shell{Mode: "full", DefaultLocale: "fr-CA"}, `{"backendBaseUrl":"/api","shell":{"mode":"full","defaultLocale":"fr-CA"}}`},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			installation := projectionFixture(t)
+			installation.Shell = test.shell
+			files, err := Render(installation)
+			if err != nil {
+				t.Fatal(err)
+			}
+			// The entire public payload is an allowlist: no model endpoints, auth or host paths.
+			js := string(files["frontend/config.js"])
+			if !strings.HasPrefix(js, "window.__THOTHII_CONFIG__ = ") || !strings.HasSuffix(js, ";\n") {
+				t.Fatalf("invalid public config script: %q", js)
+			}
+			payload := strings.TrimSuffix(strings.TrimPrefix(js, "window.__THOTHII_CONFIG__ = "), ";\n")
+			var got, want any
+			if err := json.Unmarshal([]byte(payload), &got); err != nil {
+				t.Fatal(err)
+			}
+			if err := json.Unmarshal([]byte(test.want), &want); err != nil {
+				t.Fatal(err)
+			}
+			if !reflect.DeepEqual(got, want) {
+				t.Fatalf("public config = %s, want %s", payload, test.want)
+			}
+			var compose struct {
+				Services map[string]struct {
+					Volumes []struct {
+						Type     string `yaml:"type"`
+						Source   string `yaml:"source"`
+						Target   string `yaml:"target"`
+						ReadOnly bool   `yaml:"read_only"`
+					} `yaml:"volumes"`
+				} `yaml:"services"`
+			}
+			if err := yaml.Unmarshal(files[ComposeFile], &compose); err != nil {
+				t.Fatal(err)
+			}
+			mounts := compose.Services["frontend"].Volumes
+			if len(mounts) != 1 || mounts[0].Type != "bind" || !mounts[0].ReadOnly ||
+				mounts[0].Source != filepath.Join(installation.GeneratedDirectory(), "frontend", "config.js") ||
+				mounts[0].Target != "/usr/share/nginx/html/config.js" {
+				t.Fatalf("frontend mounts = %#v; want only public config.js, read-only", mounts)
+			}
+		})
+	}
+}
+
+func TestGenerateRefreshesPublicShellConfiguration(t *testing.T) {
+	installation := projectionFixture(t)
+	if err := Generate(installation); err != nil {
+		t.Fatal(err)
+	}
+	publicPath := filepath.Join(installation.GeneratedDirectory(), "frontend", "config.js")
+	before, err := os.ReadFile(publicPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	composeBefore, err := os.ReadFile(installation.ModelProjectionComposePath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	installation.Shell = config.Shell{Mode: "full", DefaultLocale: "it"}
+	drift, err := Check(installation)
+	if err != nil || !reflect.DeepEqual(drift, []string{"compose.models.yaml", "frontend/config.js"}) {
+		t.Fatalf("shell drift = %v, %v", drift, err)
+	}
+	if err := Generate(installation); err != nil {
+		t.Fatal(err)
+	}
+	after, err := os.ReadFile(publicPath)
+	if err != nil || bytes.Equal(before, after) || !bytes.Contains(after, []byte(`"mode": "full"`)) || bytes.Contains(after, []byte(`"adapter"`)) {
+		t.Fatalf("updated public config = %s, %v", after, err)
+	}
+	composeAfter, err := os.ReadFile(installation.ModelProjectionComposePath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	// A config revision changes Compose's service definition, ensuring active bind mounts refresh.
+	var oldCompose, newCompose map[string]map[string]map[string]any
+	if err := yaml.Unmarshal(composeBefore, &oldCompose); err != nil {
+		t.Fatal(err)
+	}
+	if err := yaml.Unmarshal(composeAfter, &newCompose); err != nil {
+		t.Fatal(err)
+	}
+	if reflect.DeepEqual(oldCompose["services"]["frontend"]["environment"], newCompose["services"]["frontend"]["environment"]) {
+		t.Fatal("shell change did not revise the frontend service")
+	}
+	if !reflect.DeepEqual(oldCompose["services"]["core"], newCompose["services"]["core"]) {
+		t.Fatal("shell-only change revised core configuration")
+	}
+	if drift, err := Check(installation); err != nil || len(drift) != 0 {
+		t.Fatalf("fresh generation drift = %v, %v", drift, err)
+	}
+}
+
+func TestGeneratedPublicShellPassesFrontendImageSmoke(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("frontend image smoke requires a POSIX host shell")
+	}
+	for _, shell := range []config.Shell{{}, {Mode: "full"}, {Mode: "full", DefaultLocale: "it"}, {Mode: "embedded", DefaultLocale: "it"}, {Mode: "full", DefaultLocale: "fr-CA"}, {Mode: "embedded", DefaultLocale: "zh-Hant-TW-u-nu-hanidec"}} {
+		installation := projectionFixture(t)
+		installation.Shell = shell
+		if err := Generate(installation); err != nil {
+			t.Fatal(err)
+		}
+		command := exec.Command("sh", "../../../../docker/smoke/frontend-smoke.sh", installation.GeneratedFrontendConfigPath())
+		if output, err := command.CombinedOutput(); err != nil {
+			t.Fatalf("frontend smoke for %#v: %v\n%s", shell, err, output)
+		}
+	}
+}

tools/tht/internal/setup/files.go

@@ -36,6 +36,7 @@ var atomicWriteNewFile = writeNewFileAtomically
 var effectiveUID = currentEffectiveUID
 
 type answers struct {
+	shell                            config.Shell
 	installationID, profile          string
 	workspaceRemote, workspaceBranch string
 	workspaceAccess                  string
@@ -65,6 +66,7 @@ type generatedDescriptor struct {
 		} `yaml:"runtimeProjection,omitempty"`
 	} `yaml:"authentication"`
 	ModelCatalog config.ModelCatalog `yaml:"modelCatalog"`
+	Shell        config.Shell        `yaml:"shell,omitempty"`
 	Overrides    []string            `yaml:"overrides"`
 }
 
@@ -226,6 +228,11 @@ func collectAnswers(request Request, input io.Reader, output io.Writer, root str
 func answersFromRequest(request Request) answers {
 	answer := request.Answers
 	return answers{
+		shell: config.Shell{
+			Mode:          firstNonEmpty(answer.ShellMode, os.Getenv("THT_SETUP_SHELL_MODE")),
+			DefaultLocale: firstNonEmpty(answer.ShellDefaultLocale, os.Getenv("THT_SETUP_SHELL_DEFAULT_LOCALE")),
+			Adapter:       firstNonEmpty(answer.ShellAdapter, os.Getenv("THT_SETUP_SHELL_ADAPTER")),
+		},
 		workspaceRemote:       firstNonEmpty(answer.WorkspaceRemote, os.Getenv("THT_SETUP_WORKSPACE_REMOTE")),
 		workspaceBranch:       firstNonEmpty(answer.WorkspaceBranch, os.Getenv("THT_SETUP_WORKSPACE_BRANCH")),
 		workspaceAccess:       firstNonEmpty(answer.WorkspaceAccess, os.Getenv("THT_SETUP_WORKSPACE_ACCESS")),
@@ -272,6 +279,9 @@ func prompt(scanner *bufio.Scanner, output io.Writer, question, defaultValue str
 }
 
 func validateAnswers(value answers) error {
+	if err := value.shell.NormalizeDefaults(); err != nil {
+		return err
+	}
 	if !installationIDPattern.MatchString(value.installationID) {
 		return errors.New("installation ID must contain only letters, numbers, dashes, and underscores")
 	}
@@ -322,6 +332,13 @@ func installationDirectory(root, id string) (string, error) {
 
 func render(root, descriptorPath string, value answers) ([]byte, []byte, error) {
 	descriptor := generatedDescriptor{SchemaVersion: 2, Profile: value.profile, ProjectDirectory: root, EnvFile: filepath.Join(filepath.Dir(descriptorPath), environmentName), ModelCatalog: defaultModelCatalog()}
+	// Preserve the legacy descriptor bytes when no shell setting was requested.
+	if value.shell != (config.Shell{}) {
+		if err := value.shell.NormalizeDefaults(); err != nil {
+			return nil, nil, err
+		}
+		descriptor.Shell = value.shell
+	}
 	descriptor.Workspace.Remote, descriptor.Workspace.Branch, descriptor.Workspace.Access = value.workspaceRemote, value.workspaceBranch, value.workspaceAccess
 	descriptor.Authentication.ConfigDirectory = filepath.Join(filepath.Dir(descriptorPath), "auth")
 	if value.profile == "server" {

tools/tht/internal/setup/files_shell_test.go

@@ -0,0 +1,78 @@
+package setup
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/aritmolab/thothii/tools/tht/internal/config"
+)
+
+func TestEnsureFilesProjectsShellAnswersThroughInstallationLoad(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		answers Answers
+		want    config.Shell
+	}{
+		{"defaults", Answers{}, config.Shell{Mode: "embedded", DefaultLocale: "en", Adapter: "omics-portal"}},
+		{"full", Answers{ShellMode: "full"}, config.Shell{Mode: "full", DefaultLocale: "en"}},
+		{"locale without UI catalog", Answers{ShellMode: "full", ShellDefaultLocale: "fr-CA"}, config.Shell{Mode: "full", DefaultLocale: "fr-CA"}},
+		{"embedded Italian", Answers{ShellMode: "embedded", ShellDefaultLocale: "it", ShellAdapter: "omics-portal"}, config.Shell{Mode: "embedded", DefaultLocale: "it", Adapter: "omics-portal"}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			root := newProject(t, "shell setup")
+			setNonInteractiveAnswers(t, newExternalSecrets(t, root))
+			for _, key := range []string{"THT_SETUP_SHELL_MODE", "THT_SETUP_SHELL_DEFAULT_LOCALE", "THT_SETUP_SHELL_ADAPTER"} {
+				t.Setenv(key, "")
+			}
+			request := Request{ProjectRoot: root, InstallationID: "shell", Profile: "local", NonInteractive: true, Answers: test.answers}
+			result, err := EnsureFiles(request, strings.NewReader(""), ioDiscard{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			installation, err := config.Load(result.DescriptorPath)
+			if err != nil || installation.Shell != test.want {
+				t.Fatalf("Load() shell = %#v, %v, want %#v", installation.Shell, err, test.want)
+			}
+			if repeated, err := EnsureFiles(request, strings.NewReader(""), ioDiscard{}); err != nil || len(repeated.Created) != 0 {
+				t.Fatalf("repeated setup = %#v, %v", repeated, err)
+			}
+		})
+	}
+}
+
+func TestEnsureFilesAcceptsShellEnvironmentAndExplicitPrecedence(t *testing.T) {
+	root := newProject(t, "shell environment")
+	setNonInteractiveAnswers(t, newExternalSecrets(t, root))
+	t.Setenv("THT_SETUP_SHELL_MODE", "embedded")
+	t.Setenv("THT_SETUP_SHELL_DEFAULT_LOCALE", "it")
+	t.Setenv("THT_SETUP_SHELL_ADAPTER", "omics-portal")
+	result, err := EnsureFiles(Request{
+		ProjectRoot: root, InstallationID: "shell", Profile: "local", NonInteractive: true,
+		Answers: Answers{ShellMode: "full"},
+	}, strings.NewReader(""), ioDiscard{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	installation, err := config.Load(result.DescriptorPath)
+	if err != nil || installation.Shell != (config.Shell{Mode: "full", DefaultLocale: "it"}) {
+		t.Fatalf("Load() shell = %#v, %v", installation.Shell, err)
+	}
+}
+
+func TestEnsureFilesRejectsInvalidShellBeforeWritingInstallation(t *testing.T) {
+	for _, answers := range []Answers{{ShellMode: "fullscreen"}, {ShellDefaultLocale: "de_DE"}, {ShellAdapter: "unknown"}} {
+		root := newProject(t, "invalid shell")
+		setNonInteractiveAnswers(t, newExternalSecrets(t, root))
+		_, err := EnsureFiles(Request{
+			ProjectRoot: root, InstallationID: "shell", Profile: "local", NonInteractive: true, Answers: answers,
+		}, strings.NewReader(""), ioDiscard{})
+		if err == nil || !strings.Contains(err.Error(), "shell.") {
+			t.Fatalf("EnsureFiles() error = %v", err)
+		}
+		if _, err := os.Stat(filepath.Join(root, "deploy", "shell")); !os.IsNotExist(err) {
+			t.Fatalf("invalid shell created installation directory: %v", err)
+		}
+	}
+}

tools/tht/internal/setup/request.go

@@ -15,6 +15,9 @@ type Request struct {
 // Answers are optional explicit answers supplied by command flags. Empty values may be supplied
 // through THT_SETUP_* environment variables or collected interactively.
 type Answers struct {
+	ShellMode             string
+	ShellDefaultLocale    string
+	ShellAdapter          string
 	WorkspaceRemote       string
 	WorkspaceBranch       string
 	WorkspaceAccess       string