feat: plugin improvements (stub generation, clean up) (#3136)

- Moved stub generation to language plugins (ie: the stubs in the shared
dir: `.ftl/go/modules/...`)
- Renamed some proto fields. `dir` when talking about the specific
directory to do work in, `xyz_root` when talking about a root of a
larger directory structure, like `project_root` and `stubs_root`
- Added some more comments to the proto

backend/protos/xyz/block/ftl/v1/language/language.proto

@@ -11,25 +11,30 @@ option java_multiple_files = true;
 
 // ModuleConfig contains the configuration for a module, found in the module's ftl.toml file.
 message ModuleConfig {
-  // name of the module
+  // Name of the module
   string name = 1;
-  // absolute path to the module's directory
-  string path = 2;
-
-  // absolute path
-  string deployDir = 3;
-  optional string build = 4;
-  optional string generated_schema_dir = 5;
-  repeated string watch = 6;
+  // Absolute path to the module's directory
+  string dir = 2;
+  // The language of the module
+  string language = 3;
+
+  // Absolute path to the directory containing all of this module's build artifacts for deployments
+  string deploy_dir = 4;
+  // Build is the command to build the module.
+  optional string build = 5;
+  // The directory to generate protobuf schema files into. These can be picked up by language specific build tools
+  optional string generated_schema_dir = 6;
+  // Patterns to watch for file changes
+  repeated string watch = 7;
 
   // LanguageConfig contains any metadata specific to a specific language.
   // These are stored in the ftl.toml file under the same key as the language (eg: "go", "java")
-  google.protobuf.Struct language_config = 7;
+  google.protobuf.Struct language_config = 8;
 }
 
 // ProjectConfig contains the configuration for a project, found in the ftl-project.toml file.
 message ProjectConfig {
-  string path = 1;
+  string dir = 1;
   string name = 2;
   bool no_git = 3;
   bool hermit = 4;
@@ -55,9 +60,9 @@ message GetCreateModuleFlagsResponse {
 // Request to create a new module.
 message CreateModuleRequest {
   string name = 1;
-  // The root path for the module, which does not yet exist.
+  // The root directory for the module, which does not yet exist.
   // The plugin should create the directory.
-  string path = 2;
+  string dir = 2;
 
   // The project configuration
   ProjectConfig project_config = 3;
@@ -70,7 +75,7 @@ message CreateModuleRequest {
 message CreateModuleResponse {}
 
 message ModuleConfigDefaultsRequest {
-  string path = 1;
+  string dir = 1;
 }
 
 // ModuleConfigDefaultsResponse provides defaults for ModuleConfig.
@@ -82,15 +87,15 @@ message ModuleConfigDefaultsRequest {
 // the module defaults will not be recalculated.
 message ModuleConfigDefaultsResponse {
   // Default relative path to the directory containing all build artifacts for deployments
-  string deployDir = 1;
+  string deploy_dir = 1;
 
   // Default build command
   optional string build = 2;
 
   // Default relative path to the directory containing generated schema files
   optional string generated_schema_dir = 3;
 
-  // Default patterns to watch for file changes
+  // Default patterns to watch for file changes, relative to the module directory
   repeated string watch = 4;
 
   // Default language specific configuration.
@@ -154,11 +159,15 @@ message ErrorList {
 // Request to build a module.
 message BuildRequest {
   // The root path for the FTL project
-  string project_path = 1;
+  string project_root = 1;
+
+  // The path to the directory containing all module stubs. Each module stub is in a subdirectory.
+  string stubs_root = 2;
+
   // Indicates whether to watch for file changes and automatically rebuild
-  bool rebuild_automatically = 2;
+  bool rebuild_automatically = 3;
 
-  BuildContext build_context = 3;
+  BuildContext build_context = 4;
 }
 
 // AutoRebuildStarted should be sent when the plugin decides to start rebuilding automatically.
@@ -233,6 +242,34 @@ message BuildEvent {
   }
 }
 
+message GenerateStubsRequest {
+  // The directory path to generate stubs into
+  string dir = 1;
+  // The schema of the module to generate stubs for
+  schema.Module module = 2;
+  // The module's configuration to generate stubs for
+  ModuleConfig module_config = 3;
+
+  // Native module configuration is the configuration for a module that uses the plugin's language, if
+  // the main moduleConfig provided is of a different language. It is provided as a mechanism to derive
+  // language specific information. For example, the language version.
+  optional ModuleConfig native_module_config = 4;
+}
+
+message GenerateStubsResponse {}
+
+message SyncStubReferencesRequest {
+  ModuleConfig module_config = 1;
+
+  // The path of the directory containing all module stubs. Each module is in a subdirectory
+  string stubs_root = 2;
+
+  // The names of all modules that have had stubs generated
+  repeated string modules = 3;
+}
+
+message SyncStubReferencesResponse {}
+
 // LanguageService allows a plugin to add support for a programming language.
 service LanguageService {
   // Ping service for readiness.
@@ -270,4 +307,22 @@ service LanguageService {
   // Each time this call is made, the Build call must send back a corresponding BuildSuccess or BuildFailure
   // event with the updated build context id with "is_automatic_rebuild" as false.
   rpc BuildContextUpdated(BuildContextUpdatedRequest) returns (BuildContextUpdatedResponse);
+
+  // Generate stubs for a module.
+  //
+  // Stubs allow modules to import other module's exported interface. If a language does not need this step,
+  // then it is not required to do anything in this call.
+  //
+  // This call is not tied to the module that this plugin is responsible for. A plugin of each language will
+  // be chosen to generate stubs for each module.
+  rpc GenerateStubs(GenerateStubsRequest) returns (GenerateStubsResponse);
+
+  // SyncStubReferences is called when module stubs have been updated. This allows the plugin to update
+  // references to external modules, regardless of whether they are dependencies.
+  //
+  // For example, go plugin adds references to all modules into the go.work file so that tools can automatically
+  // import the modules when users start reference them.
+  //
+  // It is optional to do anything with this call.
+  rpc SyncStubReferences(SyncStubReferencesRequest) returns (SyncStubReferencesResponse);
 }