[Bug]: Makefile missing .PHONY declarations and other issues

# Complete Makefile Defect List

## 🚨 Critical Issues

### 1. **Missing .PHONY Declarations**
Several targets are not declared as .PHONY:
- `print-runtime` (line 549)
- `print-image` (line 555)
- `container-validate-env` (line 827)
- `container-check-ports` (line 833)

**Fix**: Add to line 623:
```makefile
.PHONY: container-build container-run container-run-ssl container-run-ssl-host \
        container-push container-info container-stop container-logs container-shell \
        container-health image-list image-clean image-retag container-check-image \
        container-build-multi use-docker use-podman show-runtime print-runtime \
        print-image container-validate-env container-check-ports container-wait-healthy
```

### 2. **Undefined Target Referenced**
Line 849 references `container-wait-healthy` which doesn't exist:
```makefile
container-run-safe: container-validate container-run
	@$(MAKE) container-wait-healthy  # ← This target is undefined!
```

**Fix**: Add the missing target:
```makefile
container-wait-healthy:
	@echo "⏳ Waiting for container to be healthy..."
	@for i in $$(seq 1 30); do \
		if $(CONTAINER_RUNTIME) inspect $(PROJECT_NAME) --format='{{.State.Health.Status}}' 2>/dev/null | grep -q healthy; then \
			echo "✅ Container is healthy"; \
			exit 0; \
		fi; \
		echo "⏳ Waiting for container health... ($$i/30)"; \
		sleep 2; \
	done; \
	echo "⚠️  Container not healthy after 60 seconds"; \
	exit 1
```

### 11. **Wrong Dependency Name in `container-validate`**
Line 823 uses non-existent `check-ports` target:
```makefile
container-validate: container-validate-env check-ports
```

**Fix**:
```makefile
container-validate: container-validate-env container-check-ports
```

## ⚠️ Important Issues

### 3. **Platform-Specific Commands Without Checks**
- Line 2448: `systemctl` used without checking existence (not on macOS)
- Line 838: `lsof` used without checking existence

**Fix for trivy target**:
```makefile
trivy:
	@command -v trivy >/dev/null 2>&1 || { ... }
	@if command -v systemctl >/dev/null 2>&1; then \
		systemctl --user enable --now podman.socket 2>/dev/null || true; \
	fi
	@echo "🔎  trivy vulnerability scan..."
```

**Fix for container-check-ports**:
```makefile
container-check-ports:
	@echo "🔍 Checking port availability..."
	@if ! command -v lsof >/dev/null 2>&1; then \
		echo "⚠️  lsof not installed - skipping port check"; \
		echo "💡  Install with: brew install lsof (macOS) or apt-get install lsof (Linux)"; \
		exit 0; \
	fi
	@failed=0; \
	...
```

### 4. **IBM Cloud Target Missing File Check**
Line 1267: `ibmcloud-check-env` doesn't check if `.env.ce` exists first.

**Fix**:
```makefile
ibmcloud-check-env:
	@test -f .env.ce || { echo "❌ Missing .env.ce file"; exit 1; }
	@bash -eu -o pipefail -c '...'
```

### 5. **Clean Target Missing Files**
Line 106: Add these to `FILES_TO_CLEAN`:
```makefile
FILES_TO_CLEAN := .coverage coverage.xml mcp.prof mcp.pstats \
                  $(PROJECT_NAME).sbom.json $(PROJECT_NAME).sbom.xml \
                  snakefood.dot packages.dot classes.dot \
                  $(DOCS_DIR)/pstats.png \
                  $(DOCS_DIR)/docs/test/sbom.md \
                  $(DOCS_DIR)/docs/test/{unittest,full,index,test}.md \
                  $(DOCS_DIR)/docs/images/coverage.svg $(LICENSES_MD) $(METRICS_MD) \
                  *.db *.sqlite *.sqlite3 mcp.db-journal \
                  grype-results.sarif $(LOCAL_PYPI_AUTH) *.tar
```

### 6. **Inconsistent xargs Usage**
Several places use bare `-r` instead of `$(XARGS_FLAGS)`:
- Line 2577: `xargs -r kill`
- Line 2584: `xargs -r kill -9`
- Line 2590: `xargs -r kill -9`

**Fix**: Replace all instances with `xargs $(XARGS_FLAGS)`

### 12. **Local PyPI Port / URL Mismatch**
- `LOCAL_PYPI_URL` is hardcoded to port 8085 (line 2390)
- `local-pypi-start` launches on port 8084
- Other targets fail because they use the wrong port

**Fix**:
```makefile
LOCAL_PYPI_PORT ?= 8084
LOCAL_PYPI_PORT_AUTH ?= 8085
LOCAL_PYPI_URL := http://localhost:$(LOCAL_PYPI_PORT)
LOCAL_PYPI_URL_AUTH := http://localhost:$(LOCAL_PYPI_PORT_AUTH)
```

### 13. **Orphaned `.PHONY` Marker**
After fixing issue 11, remove `check-ports` from the .PHONY declaration on line 823.

### 14. **`shfmt` May Not Be on PATH After Install**
Line 2965: The PATH export is in a subshell and won't persist.

**Fix**:
```makefile
shell-linters-install:
	...
	if ! command -v shfmt >/dev/null 2>&1 ; then \
		echo "🛠  Installing shfmt..." ; \
		if command -v go >/dev/null 2>&1; then \
			GO111MODULE=on go install mvdan.cc/sh/v3/cmd/shfmt@latest; \
			mkdir -p $(VENV_DIR)/bin; \
			ln -sf $(HOME)/go/bin/shfmt $(VENV_DIR)/bin/shfmt 2>/dev/null || true; \
		else \
			echo "⚠️  Go not found - install shfmt via package manager"; \
		fi; \
	fi
```

### 15. **Hard-coded `--platform=linux/amd64`**
Line 630 forces AMD64 builds, which fails on ARM systems.

**Fix**:
```makefile
# Auto-detect platform
PLATFORM ?= linux/$(shell uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

container-build:
	@echo "🔨 Building with $(CONTAINER_RUNTIME) for platform $(PLATFORM)..."
	$(CONTAINER_RUNTIME) build \
		--platform=$(PLATFORM) \
		...
```

### 16. **`docker buildx` Builder Never Re-used or Pruned**
Line 799 always creates a new builder.

**Fix**:
```makefile
container-build-multi:
	@echo "🔨 Building multi-architecture image..."
	@if [ "$(CONTAINER_RUNTIME)" = "docker" ]; then \
		if ! docker buildx inspect $(PROJECT_NAME)-builder >/dev/null 2>&1; then \
			echo "📦 Creating buildx builder..."; \
			docker buildx create --name $(PROJECT_NAME)-builder; \
		fi; \
		docker buildx use $(PROJECT_NAME)-builder; \
		docker buildx build \
			--platform=linux/amd64,linux/arm64 \
			...
```

### 17. **Conflicting Flags in `compose-restart`**
Line 1812: `--pull=missing` and `--build` can conflict.

**Fix**:
```makefile
compose-restart:
	@echo "🔄  Restarting stack..."
	$(COMPOSE) pull
	$(COMPOSE) build
	IMAGE_LOCAL=$(IMAGE_LOCAL) $(COMPOSE) up -d
```

## 📝 Minor Issues

### 7. **Static Container File**
Line 614 should dynamically detect:
```makefile
CONTAINER_FILE ?= $(shell [ -f "Containerfile" ] && echo "Containerfile" || echo "Dockerfile")
```

### 8. **Test File Assumption**
Line 316: `pytest-examples` assumes `test_readme.py` exists.

**Fix**:
```makefile
pytest-examples:
	@echo "🧪 Testing README examples..."
	@test -d "$(VENV_DIR)" || $(MAKE) venv
	@test -f test_readme.py || { echo "⚠️  test_readme.py not found - skipping"; exit 0; }
	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
		python3 -m pip install -q pytest pytest-examples && \
		pytest -v test_readme.py"
```

### 9. **Shell Script Finding**
Line 2936: Exclude more directories:
```makefile
SHELL_SCRIPTS := $(shell find . -type f -name '*.sh' \
    -not -path './node_modules/*' \
    -not -path './.venv/*' \
    -not -path './venv/*' \
    -not -path './$(VENV_DIR)/*' \
    -not -path './.git/*' \
    -not -path './dist/*' \
    -not -path './build/*' \
    -not -path './.tox/*')
```

### 10. **Unused Variable**
Lines 361-365: `SED_INPLACE` is defined but never used. Either remove it or add a comment explaining why it's kept for future use.

### 18. **Non-Persistent Error Handling in Long Pipelines**
Several loops don't run under `set -e`. Example fix for clean target:
```makefile
clean:
	@echo "🧹  Cleaning workspace..."
	@bash -eu -o pipefail -c '\
		for dir in $(DIRS_TO_CLEAN); do \
			find . -type d -name "$$dir" -exec rm -rf {} + 2>/dev/null || true; \
		done'
```

### 19. **Duplicate `.PHONY` Declarations**
Targets `yamllint`, `jsonlint`, `tomllint` appear in both:
- Line 476 in LINTERS list
- Line 739 as `.PHONY: yamllint jsonlint tomllint`

Remove the duplicate .PHONY declaration on line 739.

### 20. **Documentation Inconsistencies**
Several help comments reference different project names:
- Line 1403: References "mcp-context-forge" but project is "mcpgateway"
- Help text should be consistent with PROJECT_NAME variable

## Summary

**Critical (Must Fix):**
- Issues 1, 2, 11: Missing .PHONY declarations and undefined targets will cause make to fail

**Important (Should Fix):**
- Issues 3, 4, 5, 6, 12-17: Will cause failures on different platforms or configurations
- Port mismatches, missing file checks, platform assumptions

**Minor (Nice to Have):**
- Issues 7-10, 18-20: Code quality and maintainability improvements

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Bug]: Makefile missing .PHONY declarations and other issues #507

Complete Makefile Defect List

🚨 Critical Issues

1. Missing .PHONY Declarations

2. Undefined Target Referenced

11. Wrong Dependency Name in `container-validate`

⚠️ Important Issues

3. Platform-Specific Commands Without Checks

4. IBM Cloud Target Missing File Check

5. Clean Target Missing Files

6. Inconsistent xargs Usage

12. Local PyPI Port / URL Mismatch

13. Orphaned `.PHONY` Marker

14. `shfmt` May Not Be on PATH After Install

15. Hard-coded `--platform=linux/amd64`

16. `docker buildx` Builder Never Re-used or Pruned

17. Conflicting Flags in `compose-restart`

📝 Minor Issues

7. Static Container File

8. Test File Assumption

9. Shell Script Finding

10. Unused Variable

18. Non-Persistent Error Handling in Long Pipelines

19. Duplicate `.PHONY` Declarations

20. Documentation Inconsistencies

Summary

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Bug]: Makefile missing .PHONY declarations and other issues #507

Description

Complete Makefile Defect List

🚨 Critical Issues

1. Missing .PHONY Declarations

2. Undefined Target Referenced

11. Wrong Dependency Name in container-validate

⚠️ Important Issues

3. Platform-Specific Commands Without Checks

4. IBM Cloud Target Missing File Check

5. Clean Target Missing Files

6. Inconsistent xargs Usage

12. Local PyPI Port / URL Mismatch

13. Orphaned .PHONY Marker

14. shfmt May Not Be on PATH After Install

15. Hard-coded --platform=linux/amd64

16. docker buildx Builder Never Re-used or Pruned

17. Conflicting Flags in compose-restart

📝 Minor Issues

7. Static Container File

8. Test File Assumption

9. Shell Script Finding

10. Unused Variable

18. Non-Persistent Error Handling in Long Pipelines

19. Duplicate .PHONY Declarations

20. Documentation Inconsistencies

Summary

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

11. Wrong Dependency Name in `container-validate`

13. Orphaned `.PHONY` Marker

14. `shfmt` May Not Be on PATH After Install

15. Hard-coded `--platform=linux/amd64`

16. `docker buildx` Builder Never Re-used or Pruned

17. Conflicting Flags in `compose-restart`

19. Duplicate `.PHONY` Declarations