feat(circleci): opt-in docker_build with BASE_HASH + DAG; add layer_caching option; fix --config .cigen output path; docs workflow waits for CI; tests + README updates

Author: ndbroadbent

README.md

@@ -15,6 +15,7 @@ The tool can generate both static CircleCI configs and setup/dynamic configs. Th
 - Architecture variants per job (e.g., `build_amd64`, `build_arm64`)
 - Advanced git checkout: shallow clone by default with configurable clone/fetch options, host key scanning, and path overrides
 - Descriptive error messages and schema/data validation ([miette], JSON Schema)
+- Opt-in Docker builds with a single BASE_HASH and image DAG
 
 ## Not Yet Implemented / In Progress
 
@@ -249,3 +250,54 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 ## Support
 
 For issues and feature requests, please use the [GitHub issue tracker](https://github.com/DocSpring/cigen/issues).
+
+### Docker Builds (opt-in)
+
+CIGen can build and tag your CI Docker images as first-class jobs. Enable it with split config under `.cigen/config/docker_build.yml` or inline in your config:
+
+```yaml
+docker_build:
+  enabled: true
+  # Optional on CircleCI cloud
+  layer_caching: true
+
+  registry:
+    repo: yourorg/ci
+    # Default push behavior (true recommended on cloud)
+    push: true
+
+  images:
+    - name: ci_base
+      dockerfile: docker/ci/base.Dockerfile
+      context: .
+      arch: [amd64]
+      build_args:
+        BASE_IMAGE: cimg/base:current
+      # Sources for the canonical BASE_HASH (one hash across images)
+      hash_sources:
+        - scripts/package_versions_env.sh
+        - .tool-versions
+        - .ruby-version
+        - docker/**/*.erb
+        - scripts/docker/**
+      depends_on: []
+      # Optional per-image push override
+      # push: false
+```
+
+What happens:
+
+- CIGen computes one `BASE_HASH` by hashing all declared `hash_sources` (path + content) across images.
+- For each image+arch, a `build_<image>` job builds `registry/<name>:<BASE_HASH>-<arch>` and (optionally) pushes it.
+- Downstream jobs that specify `image: <name>` are resolved to `registry/<name>:<BASE_HASH>-<arch>` and automatically `require` `build_<image>`.
+- Build jobs include job-status skip logic (native CircleCI cache or Redis) so unchanged images skip quickly.
+- On CircleCI cloud, `layer_caching: true` emits `setup_remote_docker: { docker_layer_caching: true }` for faster rebuilds.
+
+Notes:
+
+- If a job `image` contains `/` or `:`, it is treated as a full reference and not rewritten.
+- Per-image `push` overrides the registry default.
+
+```]
+
+```

integration_tests/circleci_docker_build_layer_cache/.cigen/config.yml

@@ -0,0 +1,25 @@
+provider: circleci
+output_path: .circleci
+workflows:
+  test:
+    jobs:
+      build_and_use:
+        image: ci_base
+        steps:
+          - run: echo "hello"
+
+docker_build:
+  enabled: true
+  layer_caching: true
+  registry:
+    repo: example/repo
+    push: false
+  images:
+    - name: ci_base
+      dockerfile: Dockerfile
+      context: .
+      arch: [amd64]
+      build_args: {}
+      hash_sources:
+        - Dockerfile
+      depends_on: []

integration_tests/circleci_docker_build_layer_cache/Dockerfile

@@ -0,0 +1,2 @@
+FROM alpine:3.19
+RUN echo hello

integration_tests/circleci_docker_build_minimal/.cigen/config.yml

@@ -0,0 +1,25 @@
+provider: circleci
+output_path: .circleci
+setup: false
+workflows:
+  test:
+    jobs:
+      build_and_use:
+        image: ci_base
+        steps:
+          - run: echo "hello"
+
+docker_build:
+  enabled: true
+  registry:
+    repo: example/repo
+    push: false
+  images:
+    - name: ci_base
+      dockerfile: Dockerfile
+      context: .
+      arch: [amd64]
+      build_args: {}
+      hash_sources:
+        - Dockerfile
+      depends_on: []

integration_tests/circleci_docker_build_minimal/Dockerfile

@@ -0,0 +1,2 @@
+FROM alpine:3.19
+RUN echo hello

src/main.rs

@@ -136,8 +136,18 @@ fn main() -> Result<()> {
             };
 
             if config_dir.exists() {
+                // If config_dir is a .cigen directory, treat its parent as the project root (original_dir)
+                let project_root = if config_dir.file_name() == Some(std::ffi::OsStr::new(".cigen"))
+                {
+                    config_dir
+                        .parent()
+                        .map(|p| p.to_path_buf())
+                        .unwrap_or(original_dir.clone())
+                } else {
+                    original_dir.clone()
+                };
                 // Initialize context before changing directory
-                cigen::loader::context::init_context(original_dir, config_dir.clone());
+                cigen::loader::context::init_context(project_root, config_dir.clone());
 
                 std::env::set_current_dir(&config_dir)?;
                 tracing::debug!("Changed working directory to: {}", config_dir.display());

src/models/config.rs

@@ -119,6 +119,9 @@ pub struct DockerBuild {
     pub registry: DockerRegistry,
 
     pub images: Vec<DockerBuildImage>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub layer_caching: Option<bool>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]

src/providers/circleci/generator.rs

@@ -92,13 +92,21 @@ impl CircleCIGenerator {
 
         // Process all workflows
         for (workflow_name, jobs) in workflows {
-            let workflow_config = self.build_workflow(workflow_name, jobs)?;
+            // Augment jobs with docker_build if enabled
+            let mut jobs_augmented = jobs.clone();
+            if let Some(db) = &config.docker_build
+                && db.enabled
+            {
+                self.augment_with_docker_build(config, &mut jobs_augmented)?;
+            }
+
+            let workflow_config = self.build_workflow(workflow_name, &jobs_augmented)?;
             circleci_config
                 .workflows
                 .insert(workflow_name.clone(), workflow_config);
 
             // Process all jobs in the workflow with architecture variants
-            for (job_name, job_def) in jobs {
+            for (job_name, job_def) in &jobs_augmented {
                 // Skip approval jobs (they are workflow-level only)
                 if job_def.job_type.as_deref() == Some("approval") {
                     continue;
@@ -511,8 +519,8 @@ impl CircleCIGenerator {
                         ),
                     ])).unwrap());
 
-                    // setup_remote_docker
-                    raw_steps.push(serde_yaml::Value::String("setup_remote_docker".to_string()));
+                    // setup_remote_docker (optionally with layer caching)
+                    raw_steps.push(self.setup_remote_docker_step(config));
 
                     // docker login if pushing with auth
                     let push_enabled = images_by_name
@@ -601,8 +609,8 @@ impl CircleCIGenerator {
                         ),
                     ])).unwrap());
 
-                    // setup_remote_docker
-                    raw_steps.push(serde_yaml::Value::String("setup_remote_docker".to_string()));
+                    // setup_remote_docker (optionally with layer caching)
+                    raw_steps.push(self.setup_remote_docker_step(config));
                 }
             }
 
@@ -1655,6 +1663,25 @@ cat /tmp/continuation.json
         println!("  # or visit: https://circleci.com/docs/local-cli/");
     }
 
+    fn setup_remote_docker_step(&self, config: &Config) -> serde_yaml::Value {
+        if let Some(db) = &config.docker_build
+            && db.layer_caching.unwrap_or(false)
+        {
+            let mut map = serde_yaml::Mapping::new();
+            let mut inner = serde_yaml::Mapping::new();
+            inner.insert(
+                serde_yaml::Value::String("docker_layer_caching".to_string()),
+                serde_yaml::Value::Bool(true),
+            );
+            map.insert(
+                serde_yaml::Value::String("setup_remote_docker".to_string()),
+                serde_yaml::Value::Mapping(inner),
+            );
+            return serde_yaml::Value::Mapping(map);
+        }
+        serde_yaml::Value::String("setup_remote_docker".to_string())
+    }
+
     fn scan_for_template_commands(&self, config: &CircleCIConfig) -> HashSet<String> {
         let mut used_commands = HashSet::new();
 

tests/snapshot_docker_build.rs

@@ -0,0 +1,58 @@
+use assert_cmd::prelude::*;
+use std::fs;
+use std::path::PathBuf;
+use std::process::Command;
+
+fn repo_root() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+}
+
+#[test]
+fn snapshot_docker_build_minimal() {
+    let root = repo_root();
+    let fixture_dir = root.join("integration_tests/circleci_docker_build_minimal");
+    let output_dir = fixture_dir.join(".circleci");
+    let _ = fs::remove_dir_all(&output_dir);
+    fs::create_dir_all(&output_dir).unwrap();
+
+    let mut cmd = Command::cargo_bin("cigen").unwrap();
+    cmd.current_dir(&fixture_dir)
+        .env("CIGEN_SKIP_CIRCLECI_CLI", "1")
+        .arg("generate");
+    cmd.assert().success();
+
+    let yaml = fs::read_to_string(output_dir.join("config.yml")).unwrap();
+
+    // Should contain build job and resolved image tag
+    assert!(yaml.contains("build_ci_base"), "missing build job");
+    assert!(
+        yaml.contains("example/repo/ci_base:"),
+        "missing resolved image tag"
+    );
+    assert!(yaml.contains("requires:"), "missing requires between jobs");
+}
+
+#[test]
+fn snapshot_docker_build_with_layer_cache() {
+    let root = repo_root();
+    let fixture_dir = root.join("integration_tests/circleci_docker_build_layer_cache");
+    let output_dir = fixture_dir.join(".circleci");
+    let _ = fs::remove_dir_all(&output_dir);
+    fs::create_dir_all(&output_dir).unwrap();
+
+    let mut cmd = Command::cargo_bin("cigen").unwrap();
+    cmd.current_dir(&fixture_dir)
+        .env("CIGEN_SKIP_CIRCLECI_CLI", "1")
+        .arg("generate");
+    cmd.assert().success();
+
+    let yaml = fs::read_to_string(output_dir.join("config.yml")).unwrap();
+    assert!(
+        yaml.contains("setup_remote_docker:"),
+        "missing setup_remote_docker step"
+    );
+    assert!(
+        yaml.contains("docker_layer_caching: true"),
+        "missing docker_layer_caching flag"
+    );
+}