fix(feature): match devcontainer CLI lockfile dependsOn format

pkg/devcontainer/config/feature.go

@@ -1,12 +1,56 @@
 package config
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
+	"sort"
 
 	"github.com/devsy-org/devsy/pkg/types"
 )
 
+// objectKeyOrder returns the keys of the named top-level object field in the
+// order they appear in the JSON document. It returns nil when the field is
+// absent or is not a JSON object.
+func objectKeyOrder(data []byte, field string) ([]string, error) {
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return nil, err
+	}
+	value, ok := raw[field]
+	if !ok {
+		return nil, nil
+	}
+
+	var obj map[string]json.RawMessage
+	if err := json.Unmarshal(value, &obj); err != nil {
+		return nil, nil //nolint:nilerr // non-object values carry no key order
+	}
+	return decodeObjectKeys(value)
+}
+
+// decodeObjectKeys reads the keys of a JSON object in document order.
+func decodeObjectKeys(value json.RawMessage) ([]string, error) {
+	dec := json.NewDecoder(bytes.NewReader(value))
+	if _, err := dec.Token(); err != nil { // consume opening '{'
+		return nil, err
+	}
+
+	var keys []string
+	for dec.More() {
+		keyTok, err := dec.Token()
+		if err != nil {
+			return nil, err
+		}
+		keys = append(keys, keyTok.(string))
+		var skip json.RawMessage
+		if err := dec.Decode(&skip); err != nil {
+			return nil, err
+		}
+	}
+	return keys, nil
+}
+
 type FeatureSet struct {
 	ConfigID string
 	Version  string
@@ -78,6 +122,43 @@ type FeatureConfig struct {
 
 	// Origin is the path where the feature was loaded from
 	Origin string `json:"-"`
+
+	// dependsOnOrder preserves the declaration order of DependsOn keys as they
+	// appear in devcontainer-feature.json. The reference devcontainer CLI emits
+	// lockfile dependsOn arrays in this order (Object.keys), so we retain it to
+	// produce byte-identical lockfiles.
+	dependsOnOrder []string `json:"-"`
+}
+
+// UnmarshalJSON decodes a FeatureConfig while capturing the declaration order
+// of the dependsOn object's keys, which a plain map cannot preserve.
+func (c *FeatureConfig) UnmarshalJSON(data []byte) error {
+	type alias FeatureConfig
+	if err := json.Unmarshal(data, (*alias)(c)); err != nil {
+		return err
+	}
+	order, err := objectKeyOrder(data, "dependsOn")
+	if err != nil {
+		return err
+	}
+	c.dependsOnOrder = order
+	return nil
+}
+
+// DependsOnKeys returns the dependency feature identifiers in their original
+// declaration order, matching the reference devcontainer CLI's lockfile output.
+// It falls back to sorted keys when order was not captured (e.g. a
+// programmatically constructed config).
+func (c *FeatureConfig) DependsOnKeys() []string {
+	if len(c.dependsOnOrder) == len(c.DependsOn) {
+		return c.dependsOnOrder
+	}
+	keys := make([]string, 0, len(c.DependsOn))
+	for k := range c.DependsOn {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
 }
 
 type DependsOnField map[string]any

pkg/devcontainer/config/feature_test.go

@@ -0,0 +1,57 @@
+package config
+
+import (
+	"encoding/json"
+	"reflect"
+	"testing"
+)
+
+const (
+	depZeta  = "ghcr.io/x/zeta:1"
+	depAlpha = "ghcr.io/x/alpha:1"
+	depMid   = "ghcr.io/x/mid:1"
+)
+
+func TestFeatureConfig_DependsOnKeysPreservesDeclarationOrder(t *testing.T) {
+	// Keys are intentionally not alphabetical to prove declaration order is
+	// preserved rather than sorted, matching the reference devcontainer CLI.
+	data := []byte(`{
+		"id": "example",
+		"dependsOn": {
+			"ghcr.io/x/zeta:1": {},
+			"ghcr.io/x/alpha:1": {},
+			"ghcr.io/x/mid:1": {}
+		}
+	}`)
+
+	var cfg FeatureConfig
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+
+	want := []string{depZeta, depAlpha, depMid}
+	if got := cfg.DependsOnKeys(); !reflect.DeepEqual(got, want) {
+		t.Errorf("DependsOnKeys() = %v, want %v", got, want)
+	}
+}
+
+func TestFeatureConfig_DependsOnKeysFallsBackToSorted(t *testing.T) {
+	// A programmatically constructed config has no captured order; keys must be
+	// returned deterministically (sorted).
+	cfg := FeatureConfig{DependsOn: DependsOnField{
+		depZeta:  map[string]any{},
+		depAlpha: map[string]any{},
+	}}
+
+	want := []string{depAlpha, depZeta}
+	if got := cfg.DependsOnKeys(); !reflect.DeepEqual(got, want) {
+		t.Errorf("DependsOnKeys() = %v, want %v", got, want)
+	}
+}
+
+func TestFeatureConfig_DependsOnKeysEmpty(t *testing.T) {
+	var cfg FeatureConfig
+	if got := cfg.DependsOnKeys(); len(got) != 0 {
+		t.Errorf("DependsOnKeys() = %v, want empty", got)
+	}
+}

pkg/devcontainer/feature/extend.go

@@ -529,7 +529,7 @@ func (p *featureProcessor) recordLockEntry(
 		Integrity: res.integrity,
 	}
 	if len(cfg.DependsOn) > 0 {
-		entry.DependsOn = map[string]any(cfg.DependsOn)
+		entry.DependsOn = cfg.DependsOnKeys()
 	}
 	p.lock.record(featureID, entry)
 }

pkg/devcontainer/feature/lockfile.go

@@ -16,10 +16,10 @@ import (
 // LockedFeature is a single pinned entry in a devcontainer-lock.json file. It
 // mirrors the structure produced by the reference devcontainer CLI.
 type LockedFeature struct {
-	Version   string         `json:"version,omitempty"`
-	Resolved  string         `json:"resolved,omitempty"`
-	Integrity string         `json:"integrity,omitempty"`
-	DependsOn map[string]any `json:"dependsOn,omitempty"`
+	Version   string   `json:"version,omitempty"`
+	Resolved  string   `json:"resolved,omitempty"`
+	Integrity string   `json:"integrity,omitempty"`
+	DependsOn []string `json:"dependsOn,omitempty"`
 }
 
 // Lockfile mirrors the devcontainer-lock.json structure: a map of feature

pkg/devcontainer/feature/lockfile_test.go

@@ -125,6 +125,33 @@ func TestWriteLockfile_CreatesSortedStable(t *testing.T) {
 	}
 }
 
+func TestWriteLockfile_DependsOnIsArray(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "devcontainer-lock.json")
+	lf := &Lockfile{Features: map[string]LockedFeature{
+		lockTestFeatureA: {
+			Version:   lockTestVersion,
+			Resolved:  lockTestResolvedA,
+			Integrity: lockTestShaA,
+			DependsOn: []string{"ghcr.io/b/feature:1"},
+		},
+	}}
+
+	if err := WriteLockfile(path, lf, false); err != nil {
+		t.Fatalf("WriteLockfile: %v", err)
+	}
+
+	data, err := os.ReadFile(filepath.Clean(path))
+	if err != nil {
+		t.Fatal(err)
+	}
+	content := string(data)
+	// The reference devcontainer CLI serializes dependsOn as an array of
+	// feature identifiers, not an object.
+	if !strings.Contains(content, "\"dependsOn\": [") {
+		t.Errorf("expected dependsOn as JSON array, got:\n%s", content)
+	}
+}
+
 func TestWriteLockfile_SkipsUnchanged(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "devcontainer-lock.json")
 	lf := &Lockfile{Features: map[string]LockedFeature{