spacetime.json updates (#4504)

# Description of Changes

Adds a new reference documentation page for `spacetime.json` and fixes
several bugs where the CLI behavior diverged from the proposal.

**Docs:**
- New page at `/cli-reference/spacetime-json` covering config structure,
field reference, generate configuration, children/inheritance,
`spacetime dev` config, database selection, flag overrides,
`--no-config`, `--env`/environments, config file discovery, and editor
support

**Bug fixes:**
- `generate` was incorrectly inherited by child databases. A child with
a different `module-path` would silently inherit the parent's generate
entries, causing bindings to be written to the wrong output directory.
Generate is now never inherited, matching the proposal.
- The source conflict rule for `module-path`/`bin-path`/`js-path` was
not implemented during inheritance. A child specifying `module-path`
could still inherit `bin-path` from the parent. Now, if a child
specifies any module source, the others are not inherited.
- `--num-replicas` was not marked as a per-database override, so it
could be used with multiple databases selected without error.

# API and ABI breaking changes

None. These are bug fixes aligning the implementation with the intended
behavior from the proposal:
- `generate` inheritance was never documented or intended
- The source conflict rule was specified in the proposal but not
implemented
- `--num-replicas` as per-database is consistent with the other
module-source flags

# Expected complexity level and risk

2 - The changes are small and well-scoped. The generate inheritance fix
simplifies the code (removes a parameter). The source conflict rule adds
a straightforward check during field inheritance. Tests have been
updated to match.

# Testing

- [x] All 136 existing CLI tests pass
- [x] Updated tests for generate non-inheritance behavior
- [x] Docs site builds successfully, page renders in sidebar
- [ ] Manual test: verify a child with a different `module-path` no
longer inherits parent's `generate`
- [ ] Manual test: verify `--num-replicas` errors when multiple
databases are selected

---------

Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Phoebe Goldman <phoebe@clockworklabs.io>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>

Author: 4 people

crates/cli/src/spacetime_config.rs

@@ -164,46 +164,53 @@ pub struct LoadedConfig {
 
 impl SpacetimeConfig {
     /// Collect all database targets with parent→child inheritance.
-    /// Children inherit unset `additional_fields` and `generate` from their parent.
-    /// `dev` and `children` are NOT propagated to child targets.
+    /// Children inherit unset `additional_fields` from their parent.
+    /// `dev`, `generate`, and `children` are NOT propagated to child targets.
     /// Returns `Vec<FlatTarget>` with fully resolved fields.
     pub fn collect_all_targets_with_inheritance(&self) -> Vec<FlatTarget> {
-        self.collect_targets_inner(None, None)
+        self.collect_targets_inner(None)
     }
 
-    fn collect_targets_inner(
-        &self,
-        parent_fields: Option<&HashMap<String, Value>>,
-        parent_generate: Option<&Vec<HashMap<String, Value>>>,
-    ) -> Vec<FlatTarget> {
+    fn collect_targets_inner(&self, parent_fields: Option<&HashMap<String, Value>>) -> Vec<FlatTarget> {
+        // module-path, bin-path, and js-path are mutually exclusive module sources.
+        // If a child specifies any one, the other two are not inherited from the parent.
+        const MODULE_SOURCE_KEYS: &[&str] = &["module-path", "bin-path", "js-path"];
+        let child_specifies_source = MODULE_SOURCE_KEYS
+            .iter()
+            .any(|k| self.additional_fields.contains_key(*k));
+
         // Build this node's fields by inheriting from parent
         let mut fields = self.additional_fields.clone();
         if let Some(parent) = parent_fields {
             for (key, value) in parent {
-                if !fields.contains_key(key) {
-                    fields.insert(key.clone(), value.clone());
+                if fields.contains_key(key) {
+                    continue;
+                }
+                // If the child specifies any module source, skip inheriting the others
+                if child_specifies_source && MODULE_SOURCE_KEYS.contains(&key.as_str()) {
+                    continue;
                 }
+                fields.insert(key.clone(), value.clone());
             }
         }
 
-        // Generate: child's generate replaces parent's; if absent, inherit parent's
-        let effective_generate = if self.generate.is_some() {
-            self.generate.clone()
-        } else {
-            parent_generate.cloned()
-        };
+        // Generate is never inherited. It is tied to a specific module and output location:
+        // inheriting is redundant when the child shares the parent's module (deduplication
+        // handles it) and dangerous when the child uses a different module (two modules
+        // would write bindings to the same output directory).
+        let effective_generate = self.generate.clone();
 
         let target = FlatTarget {
             fields: fields.clone(),
             source_config: self.source_config.clone(),
-            generate: effective_generate.clone(),
+            generate: effective_generate,
         };
 
         let mut result = vec![target];
 
         if let Some(children) = &self.children {
             for child in children {
-                let child_targets = child.collect_targets_inner(Some(&fields), effective_generate.as_ref());
+                let child_targets = child.collect_targets_inner(Some(&fields));
                 result.extend(child_targets);
             }
         }
@@ -2595,8 +2602,8 @@ mod tests {
     }
 
     #[test]
-    fn test_generate_inheritance_from_parent() {
-        // Children inherit generate from parent if they don't define their own
+    fn test_generate_not_inherited_from_parent() {
+        // Generate is never inherited. Children must define their own.
         let json = r#"{
             "database": "parent-db",
             "server": "local",
@@ -2627,15 +2634,10 @@ mod tests {
             Some("typescript")
         );
 
-        // Child 1 inherits parent's generate
-        let child1_gen = targets[1].generate.as_ref().unwrap();
-        assert_eq!(child1_gen.len(), 1);
-        assert_eq!(
-            child1_gen[0].get("language").and_then(|v| v.as_str()),
-            Some("typescript")
-        );
+        // Child 1 does not inherit parent's generate
+        assert!(targets[1].generate.is_none());
 
-        // Child 2 overrides with its own generate
+        // Child 2 has its own generate
         let child2_gen = targets[2].generate.as_ref().unwrap();
         assert_eq!(child2_gen.len(), 1);
         assert_eq!(child2_gen[0].get("language").and_then(|v| v.as_str()), Some("csharp"));
@@ -3079,9 +3081,11 @@ mod tests {
     }
 
     #[test]
-    fn test_generate_dedup_with_inherited_generate() {
-        // Two sibling databases sharing parent's generate + same module path
-        // should deduplicate to a single generate entry
+    /// Even when children share the parent's module-path, generate is not inherited.
+    ///
+    /// Deduplication in generate.rs handles the common case; inheritance would be
+    /// dangerous when a child overrides module-path.
+    fn test_generate_not_inherited_for_children_sharing_module() {
         let json = r#"{
             "module-path": "./server",
             "generate": [
@@ -3096,20 +3100,22 @@ mod tests {
         let config: SpacetimeConfig = json5::from_str(json).unwrap();
         let targets = config.collect_all_targets_with_inheritance();
 
-        // All 3 targets (parent + 2 children) share the same module-path and generate
         assert_eq!(targets.len(), 3);
+
+        // Parent has generate
+        assert!(targets[0].generate.is_some());
+
+        // Children do not inherit generate
+        assert!(targets[1].generate.is_none());
+        assert!(targets[2].generate.is_none());
+
+        // All share the same module-path via field inheritance
         for target in &targets {
             assert_eq!(
                 target.fields.get("module-path").and_then(|v| v.as_str()),
                 Some("./server")
             );
-            let r#gen = target.generate.as_ref().unwrap();
-            assert_eq!(r#gen.len(), 1);
-            assert_eq!(r#gen[0].get("language").and_then(|v| v.as_str()), Some("typescript"));
         }
-
-        // All have the same (module-path, generate) so dedup should reduce to 1
-        // (this is verified in generate.rs tests, but we confirm the data here)
     }
 
     #[test]

crates/cli/src/subcommands/dev.rs

@@ -676,6 +676,7 @@ pub async fn exec(mut config: Config, args: &ArgMatches) -> Result<(), anyhow::E
     }
 
     // Safety prompt: warn if any selected database target is defined in spacetime.json.
+    // spacetime.local.json is gitignored and personal, so it's fine for dev use.
     if let Some(ref lc) = loaded_config {
         let database_sources = resolve_database_sources(&lc.config);
         let databases_from_main_config: Vec<String> = db_names_for_logging

crates/cli/src/subcommands/publish.rs

@@ -28,7 +28,7 @@ pub fn build_publish_schema(command: &clap::Command) -> Result<CommandSchema, an
         .key(Key::new("build_options").module_specific())
         .key(Key::new("wasm_file").module_specific())
         .key(Key::new("js_file").module_specific())
-        .key(Key::new("num_replicas"))
+        .key(Key::new("num_replicas").module_specific())
         .key(Key::new("break_clients"))
         .key(Key::new("anon_identity"))
         .key(Key::new("parent"))