chore: merge main

.gitignore

@@ -1,7 +1,6 @@
 dist/
 bin/
 .idea/
-.vscode/
 *.iml
 summary.md
 /.speakeasy/

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  "configurations": [
+      {
+          "name": "Debug CLI",
+          "type": "go",
+          "debugAdapter": "dlv-dap",
+          "request": "attach",
+          "mode": "remote",
+          "remotePath": "${workspaceFolder}",
+          "port": 2345,
+          "host": "127.0.0.1",
+          "preLaunchTask": "Run headless dlv" 
+      }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,42 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+      {
+          "label": "Run headless dlv",
+          "type": "process",
+          "command": [
+              "dlv",
+          ],
+          "args": [
+              "debug",
+              "--headless",
+              "--listen=:2345",
+              "--api-version=2",
+              "${workspaceFolder}/main.go",
+              "--",
+              "${input:command}"
+          ],
+          "isBackground": true,
+          "problemMatcher": {
+              "owner": "go",
+              "fileLocation": "relative",
+              "pattern": {
+                  "regexp": "^couldn't start listener:", // error if matched
+              },
+              "background": {
+                  "activeOnStart": true,
+                  "beginsPattern": "^API server listening at:",
+                  "endsPattern": "^Got a connection, launched process" // success if matched
+              }
+          }
+      }
+  ],
+  "inputs": [
+    {
+        "id": "command",
+        "type": "promptString",
+        "default": "quickstart",
+        "description": "CLI command to debug"
+    }
+  ]
+}

cmd/bump.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/hashicorp/go-version"
 	config "github.com/speakeasy-api/sdk-gen-config"
+	"github.com/speakeasy-api/speakeasy/internal/utils"
 	"github.com/spf13/cobra"
 )
 
@@ -19,19 +20,30 @@ const (
 	bumpGraduate bumpType = "graduate"
 )
 
-var bumpCommand = &cobra.Command{
-	Use:   "bump [patch|minor|major|graduate]",
-	Short: "Bumps the version of a Speakeasy Generation Target",
-	Long: `Bumps the version of a Speakeasy Generation Target, run within the target's directory. Allows the bumping of patch, minor, and major versions or setting to a specific version.
+const bumpLong = `# Bump
+
+Bumps the version of a Speakeasy Generation Target, run within the target's directory. Allows the bumping of patch, minor, and major versions or setting to a specific version.
 
 Examples:
 
 - speakeasy bump patch - Bumps the target's version by one patch version
 - speakeasy bump -v 1.2.3 - Sets the target's version to 1.2.3
 - speakeasy bump major -t typescript - Bumps the typescript target's version by one major version
 - speakeasy bump graduate - Current version 1.2.3-alpha.1 sets the target's version to 1.2.3
-`,
-	Args: cobra.RangeArgs(0, 1),
+`
+
+const bumpExamples = `
+
+const version = require("@speakeasy/sdk-typescript").version;
+console.log(version);
+`
+
+var bumpCommand = &cobra.Command{
+	Use:     "bump [patch|minor|major|graduate]",
+	Short:   "Bumps the version of a Speakeasy Generation Target",
+	Long:    utils.RenderMarkdown(bumpLong),
+	Example: utils.RenderMarkdown(bumpExamples),
+	Args:    cobra.RangeArgs(0, 1),
 }
 
 func bumpInit() {

cmd/configure.go

@@ -15,6 +15,7 @@ import (
 	"github.com/speakeasy-api/speakeasy-core/events"
 
 	"github.com/speakeasy-api/speakeasy/internal/model/flag"
+	"github.com/speakeasy-api/speakeasy/internal/utils"
 
 	"github.com/charmbracelet/lipgloss"
 	"github.com/pkg/errors"
@@ -38,10 +39,22 @@ const (
 	appInstallURL        = "https://github.com/apps/speakeasy-github"
 )
 
+const configureLong = `# Configure
+
+Configure your Speakeasy workflow file.
+
+[Workflows](https://www.speakeasy.com/docs/workflow-file-reference)
+
+[GitHub Setup](https://www.speakeasy.com/docs/publish-sdks/github-setup)
+
+[Publishing](https://www.speakeasy.com/docs/publish-sdks/publish-sdks)
+
+`
+
 var configureCmd = &model.CommandGroup{
 	Usage:          "configure",
 	Short:          "Configure your Speakeasy SDK Setup.",
-	Long:           `Configure your Speakeasy SDK Setup.`,
+	Long:           utils.RenderMarkdown(configureLong),
 	InteractiveMsg: "What do you want to configure?",
 	Commands:       []model.Command{configureSourcesCmd, configureTargetCmd, configureGithubCmd, configurePublishingCmd},
 }
@@ -371,7 +384,15 @@ func configurePublishing(ctx context.Context, _flags ConfigureGithubFlags) error
 		return err
 	}
 
+	var workflowFileDir string
 	workflowFile, _, _ := workflow.Load(workingDir)
+	if workflowFile == nil {
+		if err := promptForWorkflowFileDir(workingDir, &workflowFileDir); err != nil {
+			return err
+		}
+		workflowFile, _, _ = workflow.Load(filepath.Join(workingDir, workflowFileDir))
+	}
+
 	if workflowFile == nil {
 		return fmt.Errorf("you cannot run configure when a speakeasy workflow does not exist, make sure you are in your SDK directory")
 	}
@@ -419,7 +440,7 @@ func configurePublishing(ctx context.Context, _flags ConfigureGithubFlags) error
 		if len(workflowFile.Targets) == 1 {
 			filenameAddendum = nil
 		}
-		generationWorkflow, generationWorkflowFilePath, newPaths, err := writePublishingFile(workflowFile.Targets[name], workingDir, filenameAddendum)
+		generationWorkflow, generationWorkflowFilePath, newPaths, err := writePublishingFile(workflowFile.Targets[name], workingDir, workflowFileDir, filenameAddendum)
 		if err != nil {
 			return err
 		}
@@ -433,7 +454,7 @@ func configurePublishing(ctx context.Context, _flags ConfigureGithubFlags) error
 		generationWorkflowFilePaths = append(generationWorkflowFilePaths, generationWorkflowFilePath)
 	}
 
-	if err := workflow.Save(workingDir, workflowFile); err != nil {
+	if err := workflow.Save(filepath.Join(workingDir, workflowFileDir), workflowFile); err != nil {
 		return errors.Wrapf(err, "failed to save workflow file")
 	}
 
@@ -447,7 +468,7 @@ func configurePublishing(ctx context.Context, _flags ConfigureGithubFlags) error
 		secretPath = fmt.Sprintf("%s/settings/secrets/actions", remoteURL)
 	}
 
-	_, workflowFilePath, err := workflow.Load(workingDir)
+	_, workflowFilePath, err := workflow.Load(filepath.Join(workingDir, workflowFileDir))
 	if err != nil {
 		return errors.Wrapf(err, "failed to load workflow file")
 	}
@@ -508,7 +529,15 @@ func configureGithub(ctx context.Context, _flags ConfigureGithubFlags) error {
 	orgSlug := core.GetOrgSlugFromContext(ctx)
 	workspaceSlug := core.GetWorkspaceSlugFromContext(ctx)
 
+	var workflowFileDir string
 	workflowFile, _, _ := workflow.Load(workingDir)
+	if workflowFile == nil {
+		if err := promptForWorkflowFileDir(workingDir, &workflowFileDir); err != nil {
+			return err
+		}
+		workflowFile, _, _ = workflow.Load(filepath.Join(workingDir, workflowFileDir))
+	}
+
 	if workflowFile == nil {
 		return fmt.Errorf("you cannot run configure when a speakeasy workflow does not exist, make sure you are in your SDK directory")
 	}
@@ -552,7 +581,7 @@ func configureGithub(ctx context.Context, _flags ConfigureGithubFlags) error {
 	var generationWorkflowFilePaths []string
 
 	if len(workflowFile.Targets) <= 1 {
-		generationWorkflow, generationWorkflowFilePath, err := writeGenerationFile(workflowFile, workingDir, nil)
+		generationWorkflow, generationWorkflowFilePath, err := writeGenerationFile(workflowFile, workingDir, workflowFileDir, nil)
 		if err != nil {
 			return err
 		}
@@ -564,7 +593,7 @@ func configureGithub(ctx context.Context, _flags ConfigureGithubFlags) error {
 		generationWorkflowFilePaths = append(generationWorkflowFilePaths, generationWorkflowFilePath)
 	} else {
 		for name := range workflowFile.Targets {
-			generationWorkflow, generationWorkflowFilePath, err := writeGenerationFile(workflowFile, workingDir, &name)
+			generationWorkflow, generationWorkflowFilePath, err := writeGenerationFile(workflowFile, workingDir, workflowFileDir, &name)
 			if err != nil {
 				return err
 			}
@@ -584,7 +613,7 @@ func configureGithub(ctx context.Context, _flags ConfigureGithubFlags) error {
 		}
 	}
 
-	if err := workflow.Save(workingDir, workflowFile); err != nil {
+	if err := workflow.Save(filepath.Join(workingDir, workflowFileDir), workflowFile); err != nil {
 		return errors.Wrapf(err, "failed to save workflow file")
 	}
 
@@ -603,7 +632,7 @@ func configureGithub(ctx context.Context, _flags ConfigureGithubFlags) error {
 		secretPath = fmt.Sprintf("%s/settings/secrets/actions", remoteURL)
 	}
 
-	_, workflowFilePath, err := workflow.Load(workingDir)
+	_, workflowFilePath, err := workflow.Load(filepath.Join(workingDir, workflowFileDir))
 	if err != nil {
 		return errors.Wrapf(err, "failed to load workflow file")
 	}
@@ -662,7 +691,7 @@ func configureGithub(ctx context.Context, _flags ConfigureGithubFlags) error {
 	return nil
 }
 
-func writeGenerationFile(workflowFile *workflow.Workflow, workingDir string, target *string) (*config.GenerateWorkflow, string, error) {
+func writeGenerationFile(workflowFile *workflow.Workflow, workingDir, workflowFileDir string, target *string) (*config.GenerateWorkflow, string, error) {
 	generationWorkflowFilePath := filepath.Join(workingDir, ".github/workflows/sdk_generation.yaml")
 	if target != nil {
 		sanitizedName := strings.ReplaceAll(strings.ToLower(*target), "-", "_")
@@ -679,7 +708,7 @@ func writeGenerationFile(workflowFile *workflow.Workflow, workingDir string, tar
 	generationWorkflow := &config.GenerateWorkflow{}
 	prompts.ReadGenerationFile(generationWorkflow, generationWorkflowFilePath)
 
-	generationWorkflow, err := prompts.ConfigureGithub(generationWorkflow, workflowFile, target)
+	generationWorkflow, err := prompts.ConfigureGithub(generationWorkflow, workflowFile, workflowFileDir, target)
 	if err != nil {
 		return nil, "", err
 	}
@@ -691,7 +720,7 @@ func writeGenerationFile(workflowFile *workflow.Workflow, workingDir string, tar
 	return generationWorkflow, generationWorkflowFilePath, nil
 }
 
-func writePublishingFile(target workflow.Target, workingDir string, filenameAddendum *string) (*config.GenerateWorkflow, string, []string, error) {
+func writePublishingFile(target workflow.Target, workingDir, workflowFileDir string, filenameAddendum *string) (*config.GenerateWorkflow, string, []string, error) {
 	generationWorkflowFilePath := filepath.Join(workingDir, ".github/workflows/sdk_generation.yaml")
 	if filenameAddendum != nil {
 		sanitizedName := strings.ReplaceAll(strings.ToLower(*filenameAddendum), "-", "_")
@@ -710,7 +739,7 @@ func writePublishingFile(target workflow.Target, workingDir string, filenameAdde
 		return nil, "", nil, fmt.Errorf("you cannot run configure publishing when a github workflow file %s does not exist, try speakeasy configure github", generationWorkflowFilePath)
 	}
 
-	publishPaths, err := prompts.WritePublishing(generationWorkflow, workingDir, target, filenameAddendum, target.Output)
+	publishPaths, err := prompts.WritePublishing(generationWorkflow, workingDir, workflowFileDir, target, filenameAddendum, target.Output)
 	if err != nil {
 		return nil, "", nil, errors.Wrapf(err, "failed to write publishing configs")
 	}
@@ -786,3 +815,14 @@ func configureGithubRepo(ctx context.Context, org, repo string) bool {
 
 	return res.StatusCode == http.StatusOK
 }
+
+func promptForWorkflowFileDir(workingDir string, dirOutput *string) error {
+	_, err := charm.NewForm(huh.NewForm(huh.NewGroup(charm.NewInput().
+		Title("What directory is your speakeasy workflow file in?").
+		Suggestions(charm.DirsInCurrentDir(workingDir)).
+		SetSuggestionCallback(charm.SuggestionCallback(charm.SuggestionCallbackConfig{IsDirectories: true})).
+		Value(dirOutput))),
+		charm.WithTitle("Find your Speakeasy workflow file.")).
+		ExecuteForm()
+	return err
+}

cmd/lint.go

@@ -18,11 +18,13 @@ import (
 	"github.com/speakeasy-api/speakeasy/internal/validation"
 )
 
+const lintLong = "# Lint \n The `lint` command provides a set of commands for linting OpenAPI docs and more."
+
 var lintCmd = &model.CommandGroup{
 	Usage:          "lint",
 	Aliases:        []string{"validate"},
 	Short:          "Lint/Validate OpenAPI documents and Speakeasy configuration files",
-	Long:           `The "lint" command provides a set of commands for linting OpenAPI docs and more.`,
+	Long:           utils.RenderMarkdown(lintLong),
 	InteractiveMsg: "What do you want to lint?",
 	Commands:       []model.Command{lintOpenapiCmd, lintConfigCmd},
 }
@@ -36,10 +38,15 @@ type LintOpenapiFlags struct {
 	Ruleset               string `json:"ruleset"`
 }
 
+const lintOpenAPILong = `# Lint 
+## OpenAPI
+
+Validates an OpenAPI document is valid and conforms to the Speakeasy OpenAPI specification.`
+
 var lintOpenapiCmd = &model.ExecutableCommand[LintOpenapiFlags]{
 	Usage:          "openapi",
 	Short:          "Lint an OpenAPI document",
-	Long:           `Validates an OpenAPI document is valid and conforms to the Speakeasy OpenAPI specification.`,
+	Long:           utils.RenderMarkdown(lintOpenAPILong),
 	Run:            lintOpenapi,
 	RunInteractive: lintOpenapiInteractive,
 	Flags: []flag.Flag{

cmd/openapi.go

@@ -13,6 +13,7 @@ import (
 	"github.com/speakeasy-api/sdk-gen-config/workflow"
 	"github.com/speakeasy-api/speakeasy-core/events"
 	"github.com/speakeasy-api/speakeasy/internal/transform"
+	"github.com/speakeasy-api/speakeasy/internal/utils"
 	"github.com/speakeasy-api/speakeasy/registry"
 
 	"github.com/speakeasy-api/speakeasy/internal/changes"
@@ -21,10 +22,12 @@ import (
 	"github.com/speakeasy-api/speakeasy/internal/model/flag"
 )
 
+const openapiLong = "# OpenAPI \n The `openapi` command provides a set of commands for visualizing, linting and transforming OpenAPI documents."
+
 var openapiCmd = &model.CommandGroup{
 	Usage:          "openapi",
 	Short:          "Utilities for working with OpenAPI documents",
-	Long:           `The "openapi" command provides a set of commands for visualizing, linting and transforming OpenAPI documents.`,
+	Long:           utils.RenderMarkdown(openapiLong),
 	InteractiveMsg: "What do you want to do?",
 	Commands:       []model.Command{openapiLintCmd, openapiDiffCmd, transformCmd},
 }

cmd/overlay.go

@@ -19,9 +19,15 @@ var overlayFlag = flag.StringFlag{
 	Required:    true,
 }
 
+const overlayLong = `# Overlay
+
+Command group for working with OpenAPI Overlays.
+`
+
 var overlayCmd = &model.CommandGroup{
 	Usage:    "overlay",
 	Short:    "Work with OpenAPI Overlays",
+	Long:     utils.RenderMarkdown(overlayLong),
 	Commands: []model.Command{overlayCompareCmd, overlayValidateCmd, overlayApplyCmd},
 }