consistent provider step naming (#228)

* docs: light improvements to code comments

* fix: use build, not step, in shell provider for consistency

* fix: stop using NewLocalLayer in static provider

this is the only provider using it

* fix: more consistent approach to including the local layer

* test: snapshot update

Author: iloveitaly

buildkit/build_llb/layers.go

@@ -179,6 +179,7 @@ func hasPathOverlap(paths1, paths2 []string) bool {
 // For container paths, the full relative path structure is preserved under /app.
 func resolvePaths(include string, isLocal bool) (srcPath, destPath string) {
 	if isLocal {
+		// convert a local path reference to fully qualified container path
 		return include, filepath.Join("/app", filepath.Base(include))
 	}
 

core/__snapshots__/TestGenerateBuildPlanForExamples_shell-script_1.snap.json

@@ -1,8 +1,16 @@
 {
  "deploy": {
   "base": {
-   "step": "setup"
+   "image": "ghcr.io/railwayapp/railpack-runtime:latest"
   },
+  "inputs": [
+   {
+    "include": [
+     "."
+    ],
+    "step": "build"
+   }
+  ],
   "startCommand": "sh start.sh"
  },
  "steps": [
@@ -21,7 +29,7 @@
      "image": "ghcr.io/railwayapp/railpack-runtime:latest"
     }
    ],
-   "name": "setup",
+   "name": "build",
    "secrets": [
     "*"
    ]

core/__snapshots__/TestGenerateBuildPlanForExamples_staticfile-config_1.snap.json

@@ -18,13 +18,7 @@
     "include": [
      "."
     ],
-    "step": "setup"
-   },
-   {
-    "include": [
-     "."
-    ],
-    "local": true
+    "step": "build"
    }
   ],
   "startCommand": "caddy run --config Caddyfile --adapter caddyfile 2\u003e\u00261"
@@ -68,6 +62,10 @@
     "Caddyfile": "{\n\tadmin off\n\tpersist_config off\n\tauto_https off\n\n\tlog {\n\t\tformat json\n\t}\n\n\tservers {\n\t\ttrusted_proxies static private_ranges\n\t}\n}\n\n:{$PORT:80} {\n\tlog {\n\t\tformat json\n\t}\n\n\trespond /health 200\n\n\t# Security headers\n\theader {\n\t\t# Enable cross-site filter (XSS) and tell browsers to block detected attacks\n\t\tX-XSS-Protection \"1; mode=block\"\n\t\t# Prevent some browsers from MIME-sniffing a response away from the declared Content-Type\n\t\tX-Content-Type-Options \"nosniff\"\n\t\t# Keep referrer data off of HTTP connections\n\t\tReferrer-Policy \"strict-origin-when-cross-origin\"\n\t\t# Enable strict Content Security Policy\n\t\tContent-Security-Policy \"default-src 'self'; img-src 'self' data: https: *; style-src 'self' 'unsafe-inline' https: *; script-src 'self' 'unsafe-inline' https: *; font-src 'self' data: https: *; connect-src 'self' https: *; media-src 'self' https: *; object-src 'none'; frame-src 'self' https: *;\"\n\t\t# Remove Server header\n\t\t-Server\n\t}\n\n\troot * hello\n\n\t# Handle static files\n\tfile_server {\n\t\thide .git\n\t\thide .env*\n\t}\n\n\t# Compression with more formats\n\tencode {\n\t\tgzip\n\t\tzstd\n\t}\n\n\t# Try files with HTML extension and handle SPA routing\n\ttry_files {path} {path}.html {path}/index.html /index.html\n\n\t# Handle 404 errors\n\thandle_errors {\n\t\trewrite * /{err.status_code}.html\n\t\tfile_server\n\t}\n}\n"
    },
    "commands": [
+    {
+     "dest": ".",
+     "src": "."
+    },
     {
      "name": "Caddyfile",
      "path": "Caddyfile"
@@ -81,7 +79,7 @@
      "step": "packages:mise"
     }
    ],
-   "name": "setup",
+   "name": "build",
    "secrets": [
     "*"
    ]

core/__snapshots__/TestGenerateBuildPlanForExamples_staticfile-index_1.snap.json

@@ -18,13 +18,7 @@
     "include": [
      "."
     ],
-    "step": "setup"
-   },
-   {
-    "include": [
-     "."
-    ],
-    "local": true
+    "step": "build"
    }
   ],
   "startCommand": "caddy run --config Caddyfile --adapter caddyfile 2\u003e\u00261"
@@ -68,6 +62,10 @@
     "Caddyfile": "{\n\tadmin off\n\tpersist_config off\n\tauto_https off\n\n\tlog {\n\t\tformat json\n\t}\n\n\tservers {\n\t\ttrusted_proxies static private_ranges\n\t}\n}\n\n:{$PORT:80} {\n\tlog {\n\t\tformat json\n\t}\n\n\trespond /health 200\n\n\t# Security headers\n\theader {\n\t\t# Enable cross-site filter (XSS) and tell browsers to block detected attacks\n\t\tX-XSS-Protection \"1; mode=block\"\n\t\t# Prevent some browsers from MIME-sniffing a response away from the declared Content-Type\n\t\tX-Content-Type-Options \"nosniff\"\n\t\t# Keep referrer data off of HTTP connections\n\t\tReferrer-Policy \"strict-origin-when-cross-origin\"\n\t\t# Enable strict Content Security Policy\n\t\tContent-Security-Policy \"default-src 'self'; img-src 'self' data: https: *; style-src 'self' 'unsafe-inline' https: *; script-src 'self' 'unsafe-inline' https: *; font-src 'self' data: https: *; connect-src 'self' https: *; media-src 'self' https: *; object-src 'none'; frame-src 'self' https: *;\"\n\t\t# Remove Server header\n\t\t-Server\n\t}\n\n\troot * .\n\n\t# Handle static files\n\tfile_server {\n\t\thide .git\n\t\thide .env*\n\t}\n\n\t# Compression with more formats\n\tencode {\n\t\tgzip\n\t\tzstd\n\t}\n\n\t# Try files with HTML extension and handle SPA routing\n\ttry_files {path} {path}.html {path}/index.html /index.html\n\n\t# Handle 404 errors\n\thandle_errors {\n\t\trewrite * /{err.status_code}.html\n\t\tfile_server\n\t}\n}\n"
    },
    "commands": [
+    {
+     "dest": ".",
+     "src": "."
+    },
     {
      "name": "Caddyfile",
      "path": "Caddyfile"
@@ -81,7 +79,7 @@
      "step": "packages:mise"
     }
    ],
-   "name": "setup",
+   "name": "build",
    "secrets": [
     "*"
    ]

core/core.go

@@ -159,7 +159,6 @@ func GenerateConfigFromFile(app *app.App, env *app.Environment, options *Generat
 	return config, nil
 }
 
-// GenerateConfigFromEnvironment generates a config from the environment
 func GenerateConfigFromEnvironment(env *app.Environment) *c.Config {
 	config := c.EmptyConfig()
 

core/plan/layer.go

@@ -85,8 +85,19 @@ func (i *Layer) DisplayName() string {
 	return fmt.Sprintf("input %s", include)
 }
 
+// Supports two types of inputs:
+//
+// Object Notation:
+//   - Step Layer: {"step": "build", "include": ["src/**/*.go"], "exclude": ["*_test.go"]}
+//     References the output of a named build step with optional file filtering
+//   - Image Layer: {"image": "golang:1.21", "include": ["."], "exclude": ["tmp"]}
+//     Uses a Docker image as input with optional file filtering
+//   - Local Layer: {"local": true, "include": ["src"], "exclude": ["node_modules"]}
+//     Uses local files from the build context with filtering
+//
+// String Shortcuts: ".", "...", "$stepname"
 func (i *Layer) UnmarshalJSON(data []byte) error {
-	// First try normal JSON unmarshal
+	// First try normal JSON unmarshal for object notation
 	type Alias Layer
 	aux := &struct {
 		*Alias
@@ -97,17 +108,22 @@ func (i *Layer) UnmarshalJSON(data []byte) error {
 		return nil
 	}
 
+	// If object unmarshaling fails, try string shortcuts
 	str := string(data)
 
+	// Remove quotes from JSON string
 	str = strings.Trim(str, "\"")
 	switch str {
 	case ".":
+		// "." represents a local layer with current directory
 		*i = NewLocalLayer(".")
 		return nil
 	case "...":
+		// Creates a spread layer that expands to include all previous layers' files
 		*i = Layer{Spread: true}
 		return nil
 	default:
+		// "$stepname" represents a reference to another step
 		if strings.HasPrefix(str, "$") {
 			stepName := strings.TrimPrefix(str, "$")
 			*i = NewStepLayer(stepName)

core/providers/shell/shell.go

@@ -32,17 +32,20 @@ func (p *ShellProvider) Plan(ctx *generate.GenerateContext) error {
 
 	ctx.Logger.LogInfo("Using shell script: %s", p.scriptName)
 
-	setup := ctx.NewCommandStep("setup")
-	setup.AddInput(plan.NewImageLayer(plan.RailpackRuntimeImage))
-	setup.AddCommands(
+	build := ctx.NewCommandStep("build")
+	build.AddInput(plan.NewImageLayer(plan.RailpackRuntimeImage))
+	build.AddCommands(
 		[]plan.Command{
 			plan.NewCopyCommand("."),
 			plan.NewExecCommand("chmod +x " + p.scriptName),
 		},
 	)
 
-	ctx.Deploy.Base = plan.NewStepLayer(setup.Name())
-	ctx.Deploy.AddInputs([]plan.Layer{ctx.GetMiseStepBuilder().GetLayer()})
+	ctx.Deploy.AddInputs([]plan.Layer{
+		plan.NewStepLayer(build.Name(), plan.Filter{
+			Include: []string{"."},
+		}),
+	})
 
 	return nil
 }

core/providers/staticfile/staticfile.go

@@ -1,3 +1,6 @@
+// this provider is distinct from the SPA functionality used by node providers
+// it is meant to simply serve static files over HTTP
+
 package staticfile
 
 import (
@@ -52,22 +55,25 @@ func (p *StaticfileProvider) Plan(ctx *generate.GenerateContext) error {
 	miseStep := ctx.GetMiseStepBuilder()
 	miseStep.Default("caddy", "latest")
 
-	setup := ctx.NewCommandStep("setup")
-	setup.AddInput(plan.NewStepLayer(miseStep.Name()))
-	err := p.Setup(ctx, setup)
+	build := ctx.NewCommandStep("build")
+	build.AddInput(plan.NewStepLayer(miseStep.Name()))
+	build.AddCommands([]plan.Command{
+		plan.NewCopyCommand("."),
+	})
+
+	err := p.addCaddyfileToStep(ctx, build)
 	if err != nil {
 		return err
 	}
 
 	ctx.Deploy.AddInputs([]plan.Layer{
 		miseStep.GetLayer(),
-		plan.NewStepLayer(setup.Name(), plan.Filter{
+		plan.NewStepLayer(build.Name(), plan.Filter{
 			Include: []string{"."},
 		}),
-		plan.NewLocalLayer("."),
 	})
 
-	ctx.Deploy.StartCmd = p.CaddyStartCommand(ctx)
+	ctx.Deploy.StartCmd = fmt.Sprintf("caddy run --config %s --adapter caddyfile 2>&1", CaddyfilePath)
 
 	return nil
 }
@@ -76,11 +82,7 @@ func (p *StaticfileProvider) StartCommandHelp() string {
 	return ""
 }
 
-func (p *StaticfileProvider) CaddyStartCommand(ctx *generate.GenerateContext) string {
-	return "caddy run --config " + CaddyfilePath + " --adapter caddyfile 2>&1"
-}
-
-func (p *StaticfileProvider) Setup(ctx *generate.GenerateContext, setup *generate.CommandStepBuilder) error {
+func (p *StaticfileProvider) addCaddyfileToStep(ctx *generate.GenerateContext, setup *generate.CommandStepBuilder) error {
 	ctx.Logger.LogInfo("Using root dir: %s", p.RootDir)
 
 	data := map[string]interface{}{