From a5b0d0f31943bc95b20db0a9da17a7bca6094921 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 19 Jun 2026 14:13:53 +0000
Subject: [PATCH 1/4] Preserve script order in generated README (#1991)

`devbox generate readme` listed scripts in alphabetical order instead of
the order they are defined in devbox.json. This happened because scripts
are stored in a map and the README template ranged over it directly;
Go's text/template (like map iteration generally) visits keys in sorted
order, so user-defined ordering was lost.

Add order-preserving APIs driven by the existing hujson AST:

- configAST.objectKeysInOrder walks to an object and returns its member
  names in source order.
- ConfigFile.ScriptOrder / Config.ScriptOrder expose the script names in
  the order they appear (included plugins first, then the root config,
  matching Scripts' merge precedence).
- Scripts.InOrder turns the script map into an ordered []ScriptWithName,
  appending any scripts not covered by the order slice alphabetically so
  output stays deterministic.

docgen now renders scripts via this ordered slice, and the README
template ranges over it. Adds unit tests covering source-order
preservation, the alphabetical fallback, and de-duplication of unknown
scripts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kMnjYNx5Y5YzyqLPzeroQ
---
 internal/devbox/docgen/docgen.go              | 18 ++--
 internal/devbox/docgen/readme.tmpl            | 10 +--
 internal/devconfig/config.go                  | 13 +++
 internal/devconfig/configfile/ast.go          | 28 ++++++
 internal/devconfig/configfile/scripts.go      | 60 +++++++++++++
 internal/devconfig/configfile/scripts_test.go | 90 +++++++++++++++++++
 6 files changed, 207 insertions(+), 12 deletions(-)
 create mode 100644 internal/devconfig/configfile/scripts_test.go

diff --git a/internal/devbox/docgen/docgen.go b/internal/devbox/docgen/docgen.go
index 957a22f7821..9408a37e8b1 100644
--- a/internal/devbox/docgen/docgen.go
+++ b/internal/devbox/docgen/docgen.go
@@ -50,14 +50,18 @@ func GenerateReadme(
 		return err
 	}
 
+	cfg := devbox.Config()
+	scripts := cfg.Scripts().
+		WithRelativePaths(devbox.ProjectDir()).
+		InOrder(cfg.ScriptOrder())
+
 	return tmpl.Execute(f, map[string]any{
-		"Name":        devbox.Config().Root.Name,
-		"Description": devbox.Config().Root.Description,
-		"Scripts": devbox.Config().Scripts().
-			WithRelativePaths(devbox.ProjectDir()),
-		"EnvVars":  devbox.Config().Env(),
-		"InitHook": devbox.Config().InitHook(),
-		"Packages": devbox.TopLevelPackages(),
+		"Name":        cfg.Root.Name,
+		"Description": cfg.Root.Description,
+		"Scripts":     scripts,
+		"EnvVars":     cfg.Env(),
+		"InitHook":    cfg.InitHook(),
+		"Packages":    devbox.TopLevelPackages(),
 		// TODO add includes
 	})
 }
diff --git a/internal/devbox/docgen/readme.tmpl b/internal/devbox/docgen/readme.tmpl
index ad3306f58cd..61f1a86457c 100644
--- a/internal/devbox/docgen/readme.tmpl
+++ b/internal/devbox/docgen/readme.tmpl
@@ -28,8 +28,8 @@ devbox run <script>
 {{- if .Scripts }}
 ## Scripts
 Scripts are custom commands that can be run using this project's environment. This project has the following scripts:
-{{ range $name, $_ := .Scripts }}
-* [{{ $name }}](#devbox-run-{{ $name }})
+{{ range .Scripts }}
+* [{{ .Name }}](#devbox-run-{{ .Name }})
 {{- end }}
 {{ end }}
 
@@ -61,13 +61,13 @@ on `devbox shell` and on `devbox run`.
 
 {{- if .Scripts }}
 ## Script Details
-{{ range $name, $commands := .Scripts }}
-### devbox run {{ $name }}
+{{ range .Scripts }}
+### devbox run {{ .Name }}
 {{- if .Comments }}
 {{ .Comments }}
 {{-  end }}
 ```sh
-{{ $commands }}
+{{ .Commands }}
 ```
 &ensp;
 {{ end }}
diff --git a/internal/devconfig/config.go b/internal/devconfig/config.go
index c7e38d02965..bbae859f159 100644
--- a/internal/devconfig/config.go
+++ b/internal/devconfig/config.go
@@ -390,6 +390,19 @@ func (c *Config) Scripts() configfile.Scripts {
 	return scripts
 }
 
+// ScriptOrder returns script names in the order they are defined, with scripts
+// from included plugins first (matching Scripts' merge precedence) followed by
+// the root config's scripts. Duplicate names are de-duplicated by the consumer
+// (Scripts.InOrder).
+func (c *Config) ScriptOrder() []string {
+	var order []string
+	for _, i := range c.included {
+		order = append(order, i.ScriptOrder()...)
+	}
+	order = append(order, c.Root.ScriptOrder()...)
+	return order
+}
+
 func (c *Config) Hash() (string, error) {
 	data := []byte{}
 	for _, i := range c.included {
diff --git a/internal/devconfig/configfile/ast.go b/internal/devconfig/configfile/ast.go
index bd92c6fac47..3ebf4bd165e 100644
--- a/internal/devconfig/configfile/ast.go
+++ b/internal/devconfig/configfile/ast.go
@@ -395,6 +395,34 @@ func (c *configAST) appendStringSliceField(name, fieldName string, fieldValues [
 	c.root.Format()
 }
 
+// objectKeysInOrder walks the AST to the object at the given path and returns
+// its member names in the order they appear in the file. It returns nil if the
+// path doesn't resolve to an object (for example, when the field is missing).
+func (c *configAST) objectKeysInOrder(path ...string) []string {
+	elem := c.root
+	for _, key := range path {
+		obj, ok := elem.Value.(*hujson.Object)
+		if !ok {
+			return nil
+		}
+		i := c.memberIndex(obj, key)
+		if i == -1 {
+			return nil
+		}
+		elem = obj.Members[i].Value
+	}
+
+	obj, ok := elem.Value.(*hujson.Object)
+	if !ok {
+		return nil
+	}
+	names := make([]string, 0, len(obj.Members))
+	for i := range obj.Members {
+		names = append(names, obj.Members[i].Name.Value.(hujson.Literal).String())
+	}
+	return names
+}
+
 func (c *configAST) beforeComment(path ...any) []byte {
 	elem := c.root
 	for _, pathItem := range path {
diff --git a/internal/devconfig/configfile/scripts.go b/internal/devconfig/configfile/scripts.go
index 96c0e4b932b..c3a752364f3 100644
--- a/internal/devconfig/configfile/scripts.go
+++ b/internal/devconfig/configfile/scripts.go
@@ -1,6 +1,7 @@
 package configfile
 
 import (
+	"slices"
 	"strings"
 
 	"go.jetify.com/devbox/internal/devbox/shellcmd"
@@ -13,6 +14,65 @@ type script struct {
 
 type Scripts map[string]*script
 
+// ScriptWithName pairs a script with its name so callers can iterate over
+// scripts in a deterministic order. Scripts are stored in a map, and ranging
+// over a map (including in text/template) visits keys in alphabetical order,
+// which doesn't match the order scripts are defined in devbox.json. This type
+// is used when generating documentation so the output preserves the user's
+// ordering.
+type ScriptWithName struct {
+	Name     string
+	Commands *shellcmd.Commands
+	Comments string
+}
+
+// ScriptOrder returns the names of the scripts in the order they appear in the
+// devbox.json file. Names that can't be determined from the source file (for
+// example, when the config wasn't parsed from a file) are omitted; callers
+// should treat a missing name as "order unknown".
+func (c *ConfigFile) ScriptOrder() []string {
+	if c == nil || c.ast == nil {
+		return nil
+	}
+	return c.ast.objectKeysInOrder("shell", "scripts")
+}
+
+// InOrder returns the scripts as a slice ordered by the given names. Any
+// scripts not present in order (or when order is nil) are appended in
+// alphabetical order so the result stays deterministic.
+func (s Scripts) InOrder(order []string) []ScriptWithName {
+	result := make([]ScriptWithName, 0, len(s))
+	seen := make(map[string]bool, len(s))
+	add := func(name string) {
+		sc := s[name]
+		result = append(result, ScriptWithName{
+			Name:     name,
+			Commands: &sc.Commands,
+			Comments: sc.Comments,
+		})
+		seen[name] = true
+	}
+
+	for _, name := range order {
+		if _, ok := s[name]; ok && !seen[name] {
+			add(name)
+		}
+	}
+
+	rest := make([]string, 0, len(s))
+	for name := range s {
+		if !seen[name] {
+			rest = append(rest, name)
+		}
+	}
+	slices.Sort(rest)
+	for _, name := range rest {
+		add(name)
+	}
+
+	return result
+}
+
 func (c *ConfigFile) Scripts() Scripts {
 	if c == nil || c.Shell == nil {
 		return nil
diff --git a/internal/devconfig/configfile/scripts_test.go b/internal/devconfig/configfile/scripts_test.go
new file mode 100644
index 00000000000..c5e88084dc1
--- /dev/null
+++ b/internal/devconfig/configfile/scripts_test.go
@@ -0,0 +1,90 @@
+package configfile
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// scriptNames returns just the names of the ordered scripts, for convenient
+// assertions.
+func scriptNames(scripts []ScriptWithName) []string {
+	names := make([]string, 0, len(scripts))
+	for _, s := range scripts {
+		names = append(names, s.Name)
+	}
+	return names
+}
+
+func TestScriptsInOrderPreservesSourceOrder(t *testing.T) {
+	config := []byte(`{
+		"shell": {
+			"scripts": {
+				"step-one": "echo one",
+				"step-two": "echo two",
+				"step-three": "echo three",
+				"step-four": "echo four"
+			}
+		}
+	}`)
+
+	cfg, err := LoadBytes(config)
+	require.NoError(t, err)
+
+	ordered := cfg.Scripts().InOrder(cfg.ScriptOrder())
+	assert.Equal(t,
+		[]string{"step-one", "step-two", "step-three", "step-four"},
+		scriptNames(ordered),
+	)
+}
+
+func TestScriptsInOrderFallsBackToAlphabetical(t *testing.T) {
+	// When no order is provided (e.g. the config wasn't parsed from a file),
+	// the result should be deterministic (alphabetical) rather than random
+	// map order.
+	scripts := Scripts{
+		"build": &script{},
+		"test":  &script{},
+		"clean": &script{},
+	}
+
+	ordered := scripts.InOrder(nil)
+	assert.Equal(t, []string{"build", "clean", "test"}, scriptNames(ordered))
+}
+
+func TestScriptsInOrderAppendsUnknownScripts(t *testing.T) {
+	// Scripts present in the map but missing from the order slice should be
+	// appended in alphabetical order, with no duplicates.
+	scripts := Scripts{
+		"first":  &script{},
+		"second": &script{},
+		"zeta":   &script{},
+		"alpha":  &script{},
+	}
+
+	ordered := scripts.InOrder([]string{"first", "second"})
+	assert.Equal(t,
+		[]string{"first", "second", "alpha", "zeta"},
+		scriptNames(ordered),
+	)
+}
+
+func TestScriptsInOrderCarriesCommands(t *testing.T) {
+	config := []byte(`{
+		"shell": {
+			"scripts": {
+				"greet": ["echo hello", "echo world"]
+			}
+		}
+	}`)
+
+	cfg, err := LoadBytes(config)
+	require.NoError(t, err)
+
+	ordered := cfg.Scripts().InOrder(cfg.ScriptOrder())
+	require.Len(t, ordered, 1)
+	assert.Equal(t, "greet", ordered[0].Name)
+	require.NotNil(t, ordered[0].Commands)
+	assert.Equal(t, "echo hello\necho world", ordered[0].Commands.String())
+}

From c0a718f4ba3bf5a92c6657b80dfed0f12de1bde9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 19 Jun 2026 14:19:39 +0000
Subject: [PATCH 2/4] Address review: clarify map-order comment, dedupe order
 by last occurrence

- Reword the ScriptWithName comment: only text/template sorts map keys;
  plain Go map iteration is randomized, not alphabetical.
- Scripts.InOrder now keeps the last occurrence of a duplicated name in
  order, so a script overridden by a later (root) definition appears at
  that definition's position, matching merge precedence.
- Add a unit test covering the duplicate-name / keep-last-occurrence case.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kMnjYNx5Y5YzyqLPzeroQ
---
 internal/devconfig/configfile/scripts.go      | 23 +++++++++++++++----
 internal/devconfig/configfile/scripts_test.go | 23 +++++++++++++++++++
 2 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/internal/devconfig/configfile/scripts.go b/internal/devconfig/configfile/scripts.go
index c3a752364f3..b32efff9ecc 100644
--- a/internal/devconfig/configfile/scripts.go
+++ b/internal/devconfig/configfile/scripts.go
@@ -15,10 +15,10 @@ type script struct {
 type Scripts map[string]*script
 
 // ScriptWithName pairs a script with its name so callers can iterate over
-// scripts in a deterministic order. Scripts are stored in a map, and ranging
-// over a map (including in text/template) visits keys in alphabetical order,
-// which doesn't match the order scripts are defined in devbox.json. This type
-// is used when generating documentation so the output preserves the user's
+// scripts in a deterministic order. Scripts are stored in a map, and Go's
+// text/template ranges over map keys in sorted (alphabetical) order, which
+// doesn't match the order scripts are defined in devbox.json. This type is
+// used when generating documentation so the output preserves the user's
 // ordering.
 type ScriptWithName struct {
 	Name     string
@@ -40,6 +40,12 @@ func (c *ConfigFile) ScriptOrder() []string {
 // InOrder returns the scripts as a slice ordered by the given names. Any
 // scripts not present in order (or when order is nil) are appended in
 // alphabetical order so the result stays deterministic.
+//
+// order may contain a name more than once when it's built by concatenating
+// multiple sources (e.g. included configs followed by the root config). In
+// that case only the last occurrence is used, so a script overridden by a
+// later definition appears at that definition's position. This matches the
+// merge precedence that produced its value in s (later definitions win).
 func (s Scripts) InOrder(order []string) []ScriptWithName {
 	result := make([]ScriptWithName, 0, len(s))
 	seen := make(map[string]bool, len(s))
@@ -53,7 +59,14 @@ func (s Scripts) InOrder(order []string) []ScriptWithName {
 		seen[name] = true
 	}
 
-	for _, name := range order {
+	lastIndex := make(map[string]int, len(order))
+	for i, name := range order {
+		lastIndex[name] = i
+	}
+	for i, name := range order {
+		if lastIndex[name] != i {
+			continue
+		}
 		if _, ok := s[name]; ok && !seen[name] {
 			add(name)
 		}
diff --git a/internal/devconfig/configfile/scripts_test.go b/internal/devconfig/configfile/scripts_test.go
index c5e88084dc1..cc50266efce 100644
--- a/internal/devconfig/configfile/scripts_test.go
+++ b/internal/devconfig/configfile/scripts_test.go
@@ -70,6 +70,29 @@ func TestScriptsInOrderAppendsUnknownScripts(t *testing.T) {
 	)
 }
 
+func TestScriptsInOrderDedupesKeepingLastOccurrence(t *testing.T) {
+	// When a script name appears more than once in order (e.g. defined in
+	// both an included config and the root config), it should appear once, at
+	// the position of its last occurrence — matching the merge precedence
+	// where the later (root) definition wins.
+	scripts := Scripts{
+		"shared":      &script{},
+		"plugin-only": &script{},
+		"root-only":   &script{},
+	}
+
+	// Simulates: included config order ["shared", "plugin-only"] followed by
+	// root config order ["root-only", "shared"]. "shared" is overridden by
+	// root, so it should follow root-only rather than lead.
+	order := []string{"shared", "plugin-only", "root-only", "shared"}
+
+	ordered := scripts.InOrder(order)
+	assert.Equal(t,
+		[]string{"plugin-only", "root-only", "shared"},
+		scriptNames(ordered),
+	)
+}
+
 func TestScriptsInOrderCarriesCommands(t *testing.T) {
 	config := []byte(`{
 		"shell": {

From 15b1dcbddd911961d28b6feb653a59377a701822 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 19 Jun 2026 14:32:20 +0000
Subject: [PATCH 3/4] ci: re-trigger checks (flaky add_platforms_flakeref
 network test)

The add_platforms_flakeref testscript fetches and nix-builds
github:F1bonacc1/process-compose from GitHub; it timed out on the
previous run. The failure is unrelated to this PR's changes (README
script ordering). Empty commit to re-run CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kMnjYNx5Y5YzyqLPzeroQ

From a70478f9154ab1329cf61a0c9eedf604ec0a8646 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 19 Jun 2026 14:45:21 +0000
Subject: [PATCH 4/4] ci: re-trigger checks (flaky integration testscripts)

Run on c0a718f flaked on add_platforms_flakeref.test (plugin.test passed);
run on 15b1dcb flaked on plugin.test (add_platforms_flakeref passed). A
different heavy/network integration testscript fails each run. This PR only
changes README generation and additive config script-ordering APIs, which
these testscripts do not exercise; build, vet, lint and unit tests all pass.
Empty commit to re-run CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kMnjYNx5Y5YzyqLPzeroQ