feat(cli): discover ThothII projects and installations

tools/tht/cmd/tht/main.go

@@ -22,7 +22,10 @@ import (
 	"github.com/aritmolab/thothii/tools/tht/internal/workspaceops"
 )
 
-const usage = `Usage: tht --installation <absolute-path>/thothii-installation.yaml <command>
+const usage = `Usage: tht [--installation <absolute-path>/thothii-installation.yaml] <command>
+
+When --installation is omitted, tht uses THOTHII_INSTALLATION or discovers one valid
+descriptor in the current project tree.
 
 Commands:
   status              Show the Compose service state.
@@ -78,6 +81,23 @@ func run(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stderr, "tht: %s\n\n%s", err, usage)
 		return 2
 	}
+	if command == "help" && len(commandArgs) == 0 {
+		fmt.Fprint(stdout, usage)
+		return 0
+	}
+	if (command == "version" || command == "setup") && len(commandArgs) == 0 {
+		return commandUsageError(stderr, fmt.Sprintf("unknown command %q", command))
+	}
+	workingDirectory, err := os.Getwd()
+	if err != nil {
+		fmt.Fprintf(stderr, "tht: current directory is unavailable: %s\n", output.Sanitize(err.Error(), nil))
+		return 2
+	}
+	installationPath, err = config.Resolve(installationPath, os.Getenv, workingDirectory)
+	if err != nil {
+		fmt.Fprintf(stderr, "tht: %s\n", output.Sanitize(err.Error(), nil))
+		return 2
+	}
 	installation, err := config.Load(installationPath)
 	if err != nil {
 		fmt.Fprintf(stderr, "tht: %s\n", output.Sanitize(err.Error(), nil))
@@ -588,13 +608,29 @@ func piFailure(stderr io.Writer, err error, secretValues []string) int {
 }
 
 func parseArgs(args []string) (string, string, []string, error) {
-	if len(args) < 3 || args[0] != "--installation" {
-		return "", "", nil, errors.New("--installation <absolute-path> is required before the command")
+	var installation string
+	commandArgs := make([]string, 0, len(args))
+	for index := 0; index < len(args); index++ {
+		if args[index] != "--installation" {
+			commandArgs = append(commandArgs, args[index])
+			continue
+		}
+		if index+1 >= len(args) {
+			return "", "", nil, errors.New("--installation requires an absolute path")
+		}
+		if installation != "" {
+			return "", "", nil, errors.New("--installation may be supplied once")
+		}
+		installation = args[index+1]
+		if !filepath.IsAbs(installation) {
+			return "", "", nil, errors.New("--installation must be an absolute path")
+		}
+		index++
 	}
-	if !filepath.IsAbs(args[1]) {
-		return "", "", nil, errors.New("--installation must be an absolute path")
+	if len(commandArgs) == 0 {
+		return "", "", nil, errors.New("a command is required")
 	}
-	return args[1], args[2], args[3:], nil
+	return installation, commandArgs[0], commandArgs[1:], nil
 }
 
 func logsArgs(args []string) ([]string, error) {

tools/tht/cmd/tht/main_test.go

@@ -74,6 +74,31 @@ func TestRootCommandIdentity(t *testing.T) {
 	}
 }
 
+func TestBootstrapCommandsDoNotRequireAnInstallationDescriptor(t *testing.T) {
+	projectRoot := newProjectWithoutInstallation(t)
+	previousDirectory, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(filepath.Join(projectRoot, "frontend")); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if restoreErr := os.Chdir(previousDirectory); restoreErr != nil {
+			t.Errorf("restore working directory: %v", restoreErr)
+		}
+	})
+	t.Setenv("THOTHII_INSTALLATION", "")
+
+	for _, args := range [][]string{nil, {"help"}, {"version"}, {"setup"}} {
+		var stdout, stderr bytes.Buffer
+		_ = run(context.Background(), args, &stdout, &stderr)
+		if output := stdout.String() + stderr.String(); strings.Contains(output, "installation descriptor") {
+			t.Fatalf("run(%v) required a descriptor: %q", args, output)
+		}
+	}
+}
+
 // Catches interactive configuration prompts that use retired model-only data instead of the
 // provider, model, and reasoning choices supplied by the dedicated Pi Management API.
 func TestResolvePiConfigureUsesNumberedClosedChoicesOnlyForTTY(t *testing.T) {
@@ -126,6 +151,35 @@ func TestLogsRejectsFollowAndOtherArguments(t *testing.T) {
 	}
 }
 
+func TestParseArgsMakesInstallationOptionalAndAcceptsOverrideAfterCommand(t *testing.T) {
+	if installation, command, commandArgs, err := parseArgs([]string{"pi", "status"}); err != nil || installation != "" || command != "pi" || strings.Join(commandArgs, " ") != "status" {
+		t.Fatalf("implicit parse = %q, %q, %v, %v", installation, command, commandArgs, err)
+	}
+
+	want := "/tmp/thothii-installation.yaml"
+	installation, command, commandArgs, err := parseArgs([]string{"pi", "update", "--installation", want})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if installation != want || command != "pi" || strings.Join(commandArgs, " ") != "update" {
+		t.Fatalf("trailing override parse = %q, %q, %v", installation, command, commandArgs)
+	}
+}
+
+func TestRunPiStatusUsesInstallationEnvironmentWithoutFlag(t *testing.T) {
+	fixture := newCLIFixture(t, "THT_LLM_URL=https://llm.example.invalid\n")
+	fixture.setEnvironment(t)
+	t.Setenv("THOTHII_INSTALLATION", fixture.installationPath)
+
+	var stdout, stderr bytes.Buffer
+	if code := run(context.Background(), []string{"pi", "status"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("run() exit code = %d, stderr = %s", code, stderr.String())
+	}
+	if stdout.String() != "Pi version: 0.80.3\n" {
+		t.Fatalf("stdout = %q, want image-bundled Pi version", stdout.String())
+	}
+}
+
 func TestUsageDocumentsClosedConfigureUpdateSourcesRestartAndMaintenanceRecovery(t *testing.T) {
 	if strings.Contains(usage, "--follow") {
 		t.Fatal("usage still advertises unbounded log following")
@@ -1078,6 +1132,20 @@ type cliFixture struct {
 	envTemplate      string
 }
 
+func newProjectWithoutInstallation(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	for _, directory := range []string{"backend", "frontend", "harness", "tools", "deploy", ".git"} {
+		if err := os.MkdirAll(filepath.Join(root, directory), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(root, "compose.yaml"), []byte("services: {}\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
 func newCLIFixture(t *testing.T, envTemplate string) cliFixture {
 	t.Helper()
 	temporaryRoot, err := filepath.EvalSymlinks(os.TempDir())