feat(surfer): create surfer generate command framework (#2834)

Create the initial surfer CLI and add the framework for `surfer
generate`. The generation logic will be added in a follow-up change.

Remove gcloud.Generate from sidekick, since we no longer intend to run
it from the sidekick CLI.

Move `testdata/gcloud.yaml` to `testdata/parallelstore/gcloud.yaml` to
make it clear that it belongs to the parallelstore service.

For #2375

Author: julieqiu

cmd/surfer/main.go

@@ -0,0 +1,31 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Command surfer generates gcloud command YAML files.
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+
+	"github.com/googleapis/librarian/internal/surfer/surfer"
+)
+
+func main() {
+	ctx := context.Background()
+	if err := surfer.Run(ctx, os.Args[1:]); err != nil {
+		log.Fatal(err)
+	}
+}

internal/sidekick/sidekick/refresh.go

@@ -25,7 +25,6 @@ import (
 	"github.com/googleapis/librarian/internal/sidekick/parser"
 	"github.com/googleapis/librarian/internal/sidekick/rust"
 	"github.com/googleapis/librarian/internal/sidekick/rust_prost"
-	"github.com/googleapis/librarian/internal/surfer/gcloud"
 )
 
 func init() {
@@ -99,8 +98,6 @@ func refreshDir(rootConfig *config.Config, cmdLine *CommandLine, output string)
 		return dart.Generate(model, output, config)
 	case "sample":
 		return codec_sample.Generate(model, output, config)
-	case "gcloud":
-		return gcloud.Generate(model, output, config)
 	default:
 		return fmt.Errorf("unknown language: %s", config.General.Language)
 	}

internal/surfer/gcloud/config_test.go

@@ -25,25 +25,24 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
-func TestGcloudConfig(t *testing.T) {
-	data, err := os.ReadFile("testdata/gcloud.yaml")
+func TestReadGcloudConfig(t *testing.T) {
+	cfg, err := readGcloudConfig("testdata/parallelstore/gcloud.yaml")
 	if err != nil {
-		t.Fatalf("failed to read temporary YAML file: %v", err)
-	}
-
-	var config Config
-	if err := yaml.Unmarshal(data, &config); err != nil {
-		t.Fatalf("failed to unmarshal YAML: %v", err)
+		t.Fatal(err)
 	}
 
 	var got bytes.Buffer
 	enc := yaml.NewEncoder(&got)
 	enc.SetIndent(2)
-	if err := enc.Encode(config); err != nil {
+	if err := enc.Encode(cfg); err != nil {
 		t.Fatalf("failed to marshal struct to YAML: %v", err)
 	}
 
 	var index int
+	data, err := os.ReadFile("testdata/parallelstore/gcloud.yaml")
+	if err != nil {
+		t.Fatalf("failed to read temporary YAML file: %v", err)
+	}
 	lines := strings.Split(string(data), "\n")
 	for i, line := range lines {
 		if strings.HasPrefix(line, "#") {
@@ -52,7 +51,7 @@ func TestGcloudConfig(t *testing.T) {
 			continue
 		}
 	}
-	want := fmt.Sprintf("service_name: %s\n%s", config.ServiceName, strings.Join(lines[index:], "\n"))
+	want := fmt.Sprintf("service_name: %s\n%s", cfg.ServiceName, strings.Join(lines[index:], "\n"))
 	if diff := cmp.Diff(want, got.String()); diff != "" {
 		t.Errorf("mismatch(-want, +got)\n%s", diff)
 	}

internal/surfer/gcloud/generate.go

@@ -15,11 +15,52 @@
 package gcloud
 
 import (
-	"github.com/googleapis/librarian/internal/sidekick/api"
+	"context"
+	"fmt"
+	"os"
+
 	"github.com/googleapis/librarian/internal/sidekick/config"
+	"github.com/googleapis/librarian/internal/sidekick/parser"
+	"gopkg.in/yaml.v3"
 )
 
-// Generate generates gcloud commands from the model.
-func Generate(model *api.API, outdir string, cfg *config.Config) error {
+// Generate generates gcloud commands for a service.
+func Generate(ctx context.Context, googleapis, gcloudconfig, output string) error {
+	cfg, err := readGcloudConfig(gcloudconfig)
+	if err != nil {
+		return err
+	}
+
+	model, err := parser.ParseProtobuf(&config.Config{
+		General: config.GeneralConfig{
+			// TODO(https://github.com/googleapis/librarian/issues/2817):
+			// determine the specification source
+			SpecificationSource: "",
+		},
+		Source: map[string]string{
+			"googleapis-root": googleapis,
+		},
+	})
+	if err != nil {
+		return fmt.Errorf("failed to create API model: %w", err)
+	}
+
+	// TODO(https://github.com/googleapis/librarian/issues/2817): implement
+	// gcloud command generation logic
+	_, _ = model, cfg
 	return nil
 }
+
+// readGcloudConfig loads the gcloud configuration from a gcloud.yaml file.
+func readGcloudConfig(path string) (*Config, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read gcloud config file: %w", err)
+	}
+
+	var cfg Config
+	if err := yaml.Unmarshal(data, &cfg); err != nil {
+		return nil, fmt.Errorf("failed to parse gcloud config YAML: %w", err)
+	}
+	return &cfg, nil
+}

…ernal/surfer/gcloud/testdata/gcloud.yaml …cloud/testdata/parallelstore/gcloud.yamlinternal/surfer/gcloud/testdata/gcloud.yaml renamed to internal/surfer/gcloud/testdata/parallelstore/gcloud.yaml internal/surfer/gcloud/testdata/gcloud.yaml renamed to internal/surfer/gcloud/testdata/parallelstore/gcloud.yaml

@@ -0,0 +1,66 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package surfer provides the core implementation for the surfer CLI tool.
+package surfer
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/googleapis/librarian/internal/cli"
+	"github.com/googleapis/librarian/internal/surfer/gcloud"
+)
+
+// Run executes the surfer CLI with the given command line arguments.
+func Run(ctx context.Context, args []string) error {
+	cmd := &cli.Command{
+		Short:     "surfer generates gcloud command YAML files",
+		UsageLine: "surfer generate [arguments]",
+		Long:      "surfer generates gcloud command YAML files",
+		Commands: []*cli.Command{
+			newCmdGenerate(),
+		},
+	}
+	cmd.Init()
+	return cmd.Run(ctx, args)
+}
+
+func newCmdGenerate() *cli.Command {
+	var (
+		googleapis string
+		out        string
+	)
+
+	cmdGenerate := &cli.Command{
+		Short:     "generate generates gcloud commands",
+		UsageLine: "surfer generate <path to gcloud.yaml> --googleapis <path> [--out <path>]",
+		Long: `generate generates gcloud commands
+
+generate generates gcloud command files from protobuf API specifications,
+service config yaml, and gcloud.yaml.`,
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			args := cmd.Flags.Args()
+			if len(args) == 0 {
+				return fmt.Errorf("path to gcloud.yaml is required")
+			}
+			config := args[0]
+			return gcloud.Generate(ctx, googleapis, config, out)
+		},
+	}
+	cmdGenerate.Init()
+	cmdGenerate.Flags.StringVar(&googleapis, "googleapis", "https://github.com/googleapis/googleapis", "URL or directory path to googleapis")
+	cmdGenerate.Flags.StringVar(&out, "out", ".", "output directory")
+	return cmdGenerate
+}

internal/surfer/surfer/surfer.go

@@ -0,0 +1,63 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package surfer
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestRun(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		args    []string
+		wantErr bool
+	}{
+		{
+			name: "valid command",
+			args: []string{
+				"generate",
+				"../gcloud/testdata/parallelstore/gcloud.yaml",
+				"--out", "../gcloud/testdata/parallelstore/surface",
+			},
+		},
+		{
+			name: "invalid gcloud.yaml filepath",
+			args: []string{
+				"generate",
+				"invalidpath/gcloud.yaml",
+			},
+			wantErr: true,
+		},
+		{
+			name:    "missing config arg",
+			args:    []string{"generate"},
+			wantErr: true,
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			if err := Run(t.Context(), test.args); err != nil {
+				// TODO(https://github.com/googleapis/librarian/issues/2817):
+				// remove once the generate functionality has been implemented
+				if strings.Contains(err.Error(), "failed to create API model") {
+					return
+				}
+				if !test.wantErr {
+					t.Fatal(err)
+				}
+			}
+		})
+	}
+}