chore: project scaffolding (pyproject, requirements, license, claude.md, tests)

CLAUDE.md

@@ -0,0 +1,44 @@
+# Project Guidelines — z-image-studio
+
+Working notes for AI assistants implementing this project.
+
+## Sole-author rule (non-negotiable)
+
+Mayank Gupta is the sole author on every commit. NO `Co-Authored-By: Claude...`, NO "Generated with Claude Code" footer, NO `--author=...` flag. Treat any tooling suggesting a Claude trailer as a bug.
+
+## Architecture facts (locked — see spec)
+
+Spec: `docs/superpowers/specs/2026-05-13-z-image-studio-design.md`
+Plan: `docs/superpowers/plans/2026-05-13-z-image-studio.md`
+
+1. Backend is DiffSynth-Studio's `ZImagePipeline` — not ComfyUI.
+2. Three tabs (T2I dual-model, ControlNet turbo-only, Upscale turbo-only).
+3. One pipeline instance, shared across modes; transformer swap is the only model-pool change.
+4. `@spaces.GPU` applied module-level; identity off-Spaces.
+5. DiffSynth handles VRAM management — do not sprinkle `empty_cache()` calls.
+6. Models live in HF cache; on Spaces mirrored into `~/hf-cache-rw/` (build-vs-runtime user permissions).
+
+## Coding conventions
+
+- Python 3.11 (HF Spaces base image is 3.11)
+- Flat top-level layout — no `src/`, no nested packages.
+- No conda — `python3.11 -m venv .venv` + brew for system binaries.
+- No emojis in code or commits unless explicitly asked.
+- Type hints on public functions.
+- Imports at top of file unless breaking circular deps.
+- `ruff format` + `ruff check` must pass in CI.
+
+## Commits
+
+- Conventional Commits: `<type>(<scope>): <subject>` — types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `perf`.
+- Subject is imperative, lowercase, no trailing period.
+- Body explains WHY when non-obvious. Reference plan task if relevant.
+- Frequent small commits — one logical change per commit.
+- NO Claude trailer (see above).
+
+## Testing
+
+- TDD per the plan — failing test first, then implementation.
+- L1 + L2 run in CI without GPU. L3 + L4 require GPU/HF Space and are manual.
+- No mocks for DiffSynth internals — mock only the `pipe(...)` call boundary.
+- Use `pytest --gpu` to opt into L3 smoke tests.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mayank Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,3 @@
+# z-image-studio
+
+Placeholder — will be replaced by Task 16.

pyproject.toml

@@ -0,0 +1,18 @@
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+extend-exclude = [".venv", "build", "dist", ".superpowers"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "RUF"]
+ignore = ["E501"]  # handled by formatter
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+markers = [
+    "gpu: requires a GPU (CUDA or MPS); skipped by default",
+]

requirements.txt

@@ -0,0 +1,25 @@
+# Core
+gradio==5.50.0
+spaces==0.30.0
+diffsynth-studio>=0.5.0
+torch>=2.4
+safetensors>=0.4.5
+huggingface-hub>=0.27
+
+# ControlNet preprocessors
+controlnet-aux>=0.0.9
+opencv-python-headless>=4.9.0
+einops>=0.8.0
+
+# Upscaler
+realesrgan>=0.3.0
+basicsr>=1.4.2
+
+# Imaging
+pillow>=10.4.0
+numpy>=1.26
+
+# Dev
+ruff>=0.6.0
+pytest>=8.0
+pytest-mock>=3.14

setup.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+
+if [ ! -d .venv ]; then
+  python3.11 -m venv .venv
+fi
+# shellcheck source=/dev/null
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -r requirements.txt
+echo "Done. Activate with: source .venv/bin/activate"

tests/conftest.py

@@ -0,0 +1,5 @@
+import sys
+from pathlib import Path
+
+# Make top-level modules importable in tests
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

tests/test_scaffold.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+import re
+
+REPO = Path(__file__).resolve().parents[1]
+
+def test_required_files_exist():
+    for rel in [
+        "pyproject.toml", "requirements.txt", "setup.sh",
+        "LICENSE", "CLAUDE.md", "README.md", ".gitignore",
+        "tests/__init__.py", "tests/conftest.py",
+    ]:
+        assert (REPO / rel).exists(), f"missing {rel}"
+
+def test_pyproject_targets_py311():
+    text = (REPO / "pyproject.toml").read_text()
+    assert "python = " not in text  # not poetry
+    assert "py311" in text  # ruff target-version
+
+def test_requirements_has_core_deps():
+    text = (REPO / "requirements.txt").read_text().lower()
+    for dep in ["diffsynth-studio", "gradio", "spaces", "controlnet-aux", "torch", "safetensors", "ruff", "pytest"]:
+        assert dep in text, f"missing dep: {dep}"
+
+def test_license_is_mit():
+    text = (REPO / "LICENSE").read_text()
+    assert "MIT License" in text
+    assert "Mayank Gupta" in text