Add state machine to apps-mcp (#4160)

## Changes

Add state machine to apps-mcp to enforce workflow transitions:
scaffolded → validated → deployed.

## Why

Prevents deploying code that hasn't been validated, or deploying stale
code that changed since validation.

## Tests

Manual testing

Author: arsenyinfo

experimental/apps-mcp/cmd/deploy.go

@@ -10,6 +10,7 @@ import (
 	"github.com/databricks/cli/bundle/run"
 	"github.com/databricks/cli/cmd/bundle/utils"
 	"github.com/databricks/cli/cmd/root"
+	"github.com/databricks/cli/experimental/apps-mcp/lib/state"
 	"github.com/databricks/cli/experimental/apps-mcp/lib/validation"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/databricks/cli/libs/log"
@@ -40,10 +41,37 @@ The command will stop immediately if any step fails.`,
 
 func deployRun(cmd *cobra.Command, args []string) error {
 	ctx := cmd.Context()
+	workDir := "."
+
+	// Load and verify state
+	currentState, err := state.LoadState(workDir)
+	if err != nil {
+		return fmt.Errorf("failed to load state: %w", err)
+	}
+	if currentState == nil {
+		return errors.New("cannot deploy: project not validated (run validate first)")
+	}
+
+	// Verify checksum before deploy
+	if currentState.GetChecksum() != "" {
+		match, err := state.VerifyChecksum(workDir, currentState.GetChecksum())
+		if err != nil {
+			return fmt.Errorf("failed to verify checksum: %w", err)
+		}
+		if !match {
+			return errors.New("cannot deploy: code changed since validation (run validate again)")
+		}
+	}
+
+	// Check state transition is valid
+	newState, err := currentState.Deploy()
+	if err != nil {
+		return err
+	}
 
 	log.Infof(ctx, "Running Node.js validation...")
 	validator := &validation.ValidationNodeJs{}
-	result, err := validator.Validate(ctx, ".")
+	result, err := validator.Validate(ctx, workDir)
 	if err != nil {
 		return fmt.Errorf("validation error: %w", err)
 	}
@@ -78,6 +106,11 @@ func deployRun(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("failed to run app: %w", err)
 	}
 
+	// Save deployed state
+	if err := state.SaveState(workDir, newState); err != nil {
+		return fmt.Errorf("failed to save state: %w", err)
+	}
+
 	return nil
 }
 

experimental/apps-mcp/cmd/init_template.go

@@ -13,6 +13,7 @@ import (
 	"github.com/databricks/cli/cmd/root"
 	"github.com/databricks/cli/experimental/apps-mcp/lib/common"
 	"github.com/databricks/cli/experimental/apps-mcp/lib/prompts"
+	"github.com/databricks/cli/experimental/apps-mcp/lib/state"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/databricks/cli/libs/template"
 	"github.com/spf13/cobra"
@@ -343,6 +344,11 @@ After initialization:
 		// Inject L3 (template-specific guidance from CLAUDE.md)
 		readClaudeMd(ctx, configFile)
 
+		// Save initial scaffolded state
+		if err := state.SaveState(absOutputDir, state.NewScaffolded()); err != nil {
+			return fmt.Errorf("failed to save project state: %w", err)
+		}
+
 		return nil
 	}
 	return cmd

experimental/apps-mcp/cmd/validate.go

@@ -6,6 +6,7 @@ import (
 	"os"
 	"path/filepath"
 
+	"github.com/databricks/cli/experimental/apps-mcp/lib/state"
 	"github.com/databricks/cli/experimental/apps-mcp/lib/validation"
 	"github.com/databricks/cli/libs/cmdio"
 	"github.com/spf13/cobra"
@@ -79,6 +80,28 @@ Exit codes:
 			if !result.Success {
 				return errors.New("validation failed")
 			}
+
+			// Compute checksum and transition to validated state
+			checksum, err := state.ComputeChecksum(absPath)
+			if err != nil {
+				return fmt.Errorf("failed to compute checksum: %w", err)
+			}
+
+			// Load current state or create new scaffolded state
+			currentState, err := state.LoadState(absPath)
+			if err != nil {
+				return fmt.Errorf("failed to load state: %w", err)
+			}
+			if currentState == nil {
+				currentState = state.NewScaffolded()
+			}
+
+			// Transition to validated
+			newState := currentState.Validate(checksum)
+			if err := state.SaveState(absPath, newState); err != nil {
+				return fmt.Errorf("failed to save state: %w", err)
+			}
+
 			return nil
 		},
 	}

experimental/apps-mcp/lib/state/checksum.go

@@ -0,0 +1,125 @@
+package state
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+)
+
+var (
+	// directories to scan for source files
+	sourceDirs = []string{"client", "server"}
+
+	// directories to exclude
+	excludeDirs = map[string]bool{
+		"node_modules": true,
+		"dist":         true,
+		".git":         true,
+		"build":        true,
+		"coverage":     true,
+	}
+
+	// file extensions to include
+	sourceExtensions = map[string]bool{
+		".ts":   true,
+		".tsx":  true,
+		".js":   true,
+		".jsx":  true,
+		".json": true,
+		".css":  true,
+		".html": true,
+		".yaml": true,
+		".yml":  true,
+	}
+)
+
+// ComputeChecksum computes SHA256 checksum of all source files
+func ComputeChecksum(workDir string) (string, error) {
+	var files []string
+
+	// collect files from source directories
+	for _, dir := range sourceDirs {
+		dirPath := filepath.Join(workDir, dir)
+		if _, err := os.Stat(dirPath); err == nil {
+			if err := collectSourceFiles(dirPath, &files); err != nil {
+				return "", err
+			}
+		}
+	}
+
+	// include root package.json
+	packageJSON := filepath.Join(workDir, "package.json")
+	if _, err := os.Stat(packageJSON); err == nil {
+		files = append(files, packageJSON)
+	}
+
+	// sort for deterministic order
+	slices.Sort(files)
+
+	if len(files) == 0 {
+		return "", errors.New("no source files found - project structure appears invalid")
+	}
+
+	// compute combined hash
+	hasher := sha256.New()
+	for _, file := range files {
+		if err := hashFile(hasher, file); err != nil {
+			return "", fmt.Errorf("failed to hash %s: %w", file, err)
+		}
+	}
+
+	return hex.EncodeToString(hasher.Sum(nil)), nil
+}
+
+// VerifyChecksum verifies that current checksum matches expected
+func VerifyChecksum(workDir, expected string) (bool, error) {
+	current, err := ComputeChecksum(workDir)
+	if err != nil {
+		return false, err
+	}
+	return current == expected, nil
+}
+
+func collectSourceFiles(dir string, files *[]string) error {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return fmt.Errorf("failed to read directory %s: %w", dir, err)
+	}
+
+	for _, entry := range entries {
+		path := filepath.Join(dir, entry.Name())
+
+		if entry.IsDir() {
+			if excludeDirs[entry.Name()] {
+				continue
+			}
+			if err := collectSourceFiles(path, files); err != nil {
+				return err
+			}
+		} else {
+			ext := strings.ToLower(filepath.Ext(entry.Name()))
+			if sourceExtensions[ext] {
+				*files = append(*files, path)
+			}
+		}
+	}
+
+	return nil
+}
+
+func hashFile(hasher io.Writer, path string) error {
+	f, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	_, err = io.Copy(hasher, f)
+	return err
+}

experimental/apps-mcp/lib/state/checksum_test.go

@@ -0,0 +1,83 @@
+package state
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestComputeChecksum(t *testing.T) {
+	dir := t.TempDir()
+
+	// create client/ and server/ dirs
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "client"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "server"), 0o755))
+
+	// create source files
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "client", "app.ts"), []byte("console.log('hello')"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "server", "main.ts"), []byte("export default {}"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "package.json"), []byte(`{"name": "test"}`), 0o644))
+
+	// compute checksum
+	checksum1, err := ComputeChecksum(dir)
+	require.NoError(t, err)
+	assert.Len(t, checksum1, 64) // sha256 hex
+
+	// same content = same checksum
+	checksum2, err := ComputeChecksum(dir)
+	require.NoError(t, err)
+	assert.Equal(t, checksum1, checksum2)
+
+	// modify file = different checksum
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "client", "app.ts"), []byte("console.log('changed')"), 0o644))
+	checksum3, err := ComputeChecksum(dir)
+	require.NoError(t, err)
+	assert.NotEqual(t, checksum1, checksum3)
+}
+
+func TestComputeChecksumExcludesNodeModules(t *testing.T) {
+	dir := t.TempDir()
+
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "client"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "client", "node_modules"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "client", "app.ts"), []byte("code"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "client", "node_modules", "dep.js"), []byte("dependency"), 0o644))
+
+	checksum1, err := ComputeChecksum(dir)
+	require.NoError(t, err)
+
+	// changing node_modules should not affect checksum
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "client", "node_modules", "dep.js"), []byte("changed"), 0o644))
+	checksum2, err := ComputeChecksum(dir)
+	require.NoError(t, err)
+
+	assert.Equal(t, checksum1, checksum2)
+}
+
+func TestComputeChecksumEmptyProject(t *testing.T) {
+	dir := t.TempDir()
+
+	_, err := ComputeChecksum(dir)
+	assert.ErrorContains(t, err, "no source files found")
+}
+
+func TestVerifyChecksum(t *testing.T) {
+	dir := t.TempDir()
+
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "client"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "client", "app.ts"), []byte("code"), 0o644))
+
+	checksum, err := ComputeChecksum(dir)
+	require.NoError(t, err)
+
+	match, err := VerifyChecksum(dir, checksum)
+	require.NoError(t, err)
+	assert.True(t, match)
+
+	match, err = VerifyChecksum(dir, "wrong")
+	require.NoError(t, err)
+	assert.False(t, match)
+}

experimental/apps-mcp/lib/state/persistence.go

@@ -0,0 +1,53 @@
+package state
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+const StateFileName = ".app_state"
+
+// LoadState loads project state from work directory
+func LoadState(workDir string) (*ProjectState, error) {
+	statePath := filepath.Join(workDir, StateFileName)
+
+	data, err := os.ReadFile(statePath)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("failed to read state file: %w", err)
+	}
+
+	var state ProjectState
+	if err := json.Unmarshal(data, &state); err != nil {
+		return nil, fmt.Errorf("failed to parse state file: %w", err)
+	}
+
+	return &state, nil
+}
+
+// SaveState saves project state to work directory atomically
+func SaveState(workDir string, state *ProjectState) error {
+	statePath := filepath.Join(workDir, StateFileName)
+	tempPath := statePath + ".tmp"
+
+	data, err := json.MarshalIndent(state, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to serialize state: %w", err)
+	}
+
+	if err := os.WriteFile(tempPath, data, 0o644); err != nil {
+		return fmt.Errorf("failed to write temp state file: %w", err)
+	}
+
+	if err := os.Rename(tempPath, statePath); err != nil {
+		os.Remove(tempPath)
+		return fmt.Errorf("failed to rename temp state file: %w", err)
+	}
+
+	return nil
+}