Docker Build Fails: Missing zod dependency and spec-parser in Dockerfile

[JasonBroderick]

Bug Report: Docker Build Fails Due to Missing Dependencies

Summary

The Docker production build (docker-compose up -d / docker compose build) fails with two separate dependency resolution errors. These issues only manifest in Docker builds because npm workspace hoisting masks them during local development.

Environment

• OS: Ubuntu 24.04 LTS (WSL2)
• Docker: Docker Desktop with WSL2 backend
• Node.js: v22.22.0
• Automaker Version: 0.13.0
• Commit: HEAD of main branch as of 2026-01-24

Issues Found

Issue 1: Missing zod dependency in apps/ui/package.json

Error Message:

[vite]: Rollup failed to resolve import "zod" from "/app/apps/ui/src/routes/terminal.tsx".
This is most likely unintended because it can break your application at runtime.

Root Cause:

• apps/ui/src/routes/terminal.tsx imports zod directly (line 3: import { z } from 'zod';)
• zod is NOT listed in apps/ui/package.json dependencies
• Locally, this works because zod is a transitive dependency of @tanstack/router-plugin (devDependency) and npm hoists it to the root node_modules/
• In Docker, the ui-builder stage runs npm ci --ignore-scripts which only installs packages explicitly listed in apps/ui/package.json, so zod is not available

Verification:

# Shows zod is not in UI package.json
grep -i "zod" apps/ui/package.json
# Returns nothing

# Shows zod IS imported in the codebase
grep -r "from ['\"]zod['\"]" apps/ui/src/
# Returns: apps/ui/src/routes/terminal.tsx:import { z } from 'zod';

# Shows zod comes from router-plugin (devDependency)
npm ls zod
# @tanstack/router-plugin -> zod@3.25.76

---

Issue 2: Missing libs/spec-parser in Dockerfile base stage

Error Message:

src/xml-to-spec.ts(7,27): error TS2307: Cannot find module 'fast-xml-parser' or its corresponding type declarations.

Root Cause:

• The Dockerfile base stage copies package.json files for all workspace packages to enable proper dependency installation
• libs/spec-parser/package.json is NOT included in the copy list (lines 23-30 of Dockerfile)
• libs/spec-parser depends on fast-xml-parser (declared in its package.json)
• When npm ci runs, it doesn't know about spec-parser's dependencies, so fast-xml-parser is never installed
• The build:packages script then fails when compiling @automaker/spec-parser

Verification:

# Dockerfile base stage copies these libs (line 23-30):
# libs/types, libs/utils, libs/prompts, libs/platform,
# libs/model-resolver, libs/dependency-resolver, libs/git-utils
#
# MISSING: libs/spec-parser

# spec-parser DOES have fast-xml-parser as a dependency:
cat libs/spec-parser/package.json | grep fast-xml-parser
# "fast-xml-parser": "^5.3.3"

---

Steps to Reproduce

1. Clone the repository:

   git clone https://github.com/AutoMaker-Org/automaker.git
   cd automaker

2. Attempt to build Docker images:

   docker compose build

3. First failure (Issue 2 - spec-parser):

   error TS2307: Cannot find module 'fast-xml-parser'
   

4. If you manually fix the Dockerfile to add spec-parser, rebuild:

   docker compose build

5. Second failure (Issue 1 - zod):

   [vite]: Rollup failed to resolve import "zod" from "/app/apps/ui/src/routes/terminal.tsx"
   

---

Suggested Fixes

Fix 1: Add zod to UI dependencies

File: apps/ui/package.json

Change: Add zod to the dependencies object:

   "dependencies": {
     "@automaker/dependency-resolver": "1.0.0",
     "@automaker/spec-parser": "1.0.0",
     "@automaker/types": "1.0.0",
     ...
     "usehooks-ts": "3.1.1",
+    "zod": "3.25.76",
     "zustand": "5.0.9"
   },

Note: The version 3.25.76 matches what @tanstack/router-plugin currently brings in. Alternatively, use ^3.25.0 for flexibility.

After making this change, run npm install to update package-lock.json.

---

Fix 2: Add libs/spec-parser to Dockerfile base stage

File: Dockerfile

Change: Add the missing COPY line for spec-parser (around line 30):

 # Copy all libs package.json files (centralized - add new libs here)
 COPY libs/types/package*.json ./libs/types/
 COPY libs/utils/package*.json ./libs/utils/
 COPY libs/prompts/package*.json ./libs/prompts/
 COPY libs/platform/package*.json ./libs/platform/
 COPY libs/model-resolver/package*.json ./libs/model-resolver/
 COPY libs/dependency-resolver/package*.json ./libs/dependency-resolver/
 COPY libs/git-utils/package*.json ./libs/git-utils/
+COPY libs/spec-parser/package*.json ./libs/spec-parser/

---

Why This Wasn't Caught Earlier

Both issues are masked during local development:

1. npm workspace hoisting: When you run npm install at the repo root, npm hoists all transitive dependencies to node_modules/. This means zod and fast-xml-parser are available even though they're not direct dependencies of the packages that use them.

2. Docker isolation: The Dockerfile uses multi-stage builds where each stage runs npm ci with only the package.json files explicitly copied. This creates a "clean room" environment that exposes missing dependency declarations.

3. Local builds succeed: Running npm run build locally works fine because all dependencies are hoisted and available.

---

Verification After Fixes

After applying both fixes:

# Update lockfile
npm install

# Build Docker images
docker compose build

# Start containers
docker compose up -d

# Verify health
curl http://localhost:3008/api/health
# {"status":"ok","timestamp":"...","version":"0.13.0"}

---

Additional Recommendation

Consider adding a CI check that builds the Docker images on each PR to catch these types of issues before they reach main. Example GitHub Actions step:

- name: Build Docker images
  run: docker compose build

This would have caught both issues immediately.

---

Related Files

• apps/ui/package.json - Missing zod dependency
• apps/ui/src/routes/terminal.tsx - Imports zod
• libs/spec-parser/package.json - Has fast-xml-parser dependency
• Dockerfile - Missing spec-parser in base stage COPY commands

---

Credits

Discovered and debugged by @JasonBroderick with assistance from Claude Code.

[ruant]

#664 should already fix this i think