unaltraweb 0.3.0

data/scripts/test_gem_build.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Build the gem without network access and inspect its packaged contract files."""
+
+from __future__ import annotations
+
+import io
+import json
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from unaltraweb_mcp.docker_mount import docker_bind_mount
+
+
+CONTRACT = json.loads((ROOT / "src/unaltraweb_mcp/component-contract.json").read_text(encoding="utf-8"))
+RUNTIME_IMAGE = str(CONTRACT["components"]["runtime"]["reference"])
+
+
+def run(command: list[str], *, cwd: Path = ROOT) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(
+        command,
+        cwd=cwd,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+    if completed.returncode != 0:
+        raise RuntimeError(f"Command failed: {' '.join(command)}\n{completed.stdout}\n{completed.stderr}")
+    return completed
+
+
+def build(output: Path, *, source: Path = ROOT) -> str:
+    if shutil.which("ruby") and shutil.which("gem"):
+        run(["gem", "build", "unaltraweb.gemspec", "--output", str(output)], cwd=source)
+        return "local-ruby"
+    if not shutil.which("docker"):
+        raise RuntimeError("Gem smoke requires local RubyGems or Docker with the selected runtime image.")
+    inspected = subprocess.run(
+        ["docker", "image", "inspect", RUNTIME_IMAGE],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    if inspected.returncode != 0:
+        raise RuntimeError(f"Gem smoke requires the already-local runtime image {RUNTIME_IMAGE}; it never pulls implicitly.")
+    run([
+        "docker", "run", "--rm", "--network", "none",
+        "--mount", docker_bind_mount(source, "/repo", readonly=True),
+        "--mount", docker_bind_mount(output.parent, "/out"), "-w", "/repo",
+        RUNTIME_IMAGE, "gem", "build", "unaltraweb.gemspec", "--output", f"/out/{output.name}",
+    ])
+    return "docker-runtime"
+
+
+def inspect_gem(path: Path) -> None:
+    with tarfile.open(path, mode="r") as package:
+        data_member = package.extractfile("data.tar.gz")
+        if data_member is None:
+            raise RuntimeError("Built gem has no data.tar.gz payload.")
+        with tarfile.open(fileobj=io.BytesIO(data_member.read()), mode="r:gz") as payload:
+            names = set(payload.getnames())
+    required = {
+        "LICENSE",
+        "README.md",
+        "_data/i18n/ca.yml",
+        "_data/i18n/en.yml",
+        "_data/i18n/es.yml",
+        "_plugins/bibliography_profiles.rb",
+        "_plugins/code_blocks.rb",
+        "_plugins/content_search_index.rb",
+        "_plugins/figure_captions.rb",
+        "_plugins/manual_release_metadata.rb",
+        "_plugins/reproducible_build_time.rb",
+        "assets/js/content-search-match.js",
+        "assets/js/content-search.js",
+        "_config.yml",
+        "Makefile",
+        "requirements.txt",
+        "lib/unaltraweb/version.rb",
+        "scripts/manual/build_pdf.py",
+        "scripts/manual/filters/bibliography.lua",
+        "scripts/manual/filters/code-blocks.lua",
+        "scripts/manual/filters/figure-captions.lua",
+        "scripts/manual/publish_release.sh",
+        "scripts/manual/verify_release_assets.py",
+        "scripts/unaltraweb-docker-mount.sh",
+        "scripts/unaltraweb-mcp-cleanup.sh",
+        "scripts/unaltraweb-mcp-project-id.sh",
+        "src/unaltraweb_mcp/component-contract.json",
+        "src/unaltraweb_mcp/component-contract.schema.json",
+        "src/unaltraweb_mcp/docker_mount.py",
+    }
+    missing = sorted(required - names)
+    if missing:
+        raise RuntimeError(f"Built gem is missing required files: {missing}")
+    unexpected_data = sorted(name for name in names if name.startswith("_data/") and not name.startswith("_data/i18n/"))
+    if unexpected_data:
+        raise RuntimeError(f"Built gem contains non-runtime data files: {unexpected_data}")
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(prefix="unaltraweb-gem-") as raw_temp:
+        output = Path(raw_temp) / "unaltraweb.gem"
+        runner = build(output)
+        inspect_gem(output)
+        archive_source = Path(raw_temp) / "source-archive"
+        shutil.copytree(
+            ROOT,
+            archive_source,
+            ignore=shutil.ignore_patterns(".git", "_site", "tmp", ".jekyll-cache", "__pycache__", "*.pyc"),
+        )
+        archive_output = Path(raw_temp) / "unaltraweb-source-archive.gem"
+        build(archive_output, source=archive_source)
+        inspect_gem(archive_output)
+        print(json.dumps({"ok": True, "runner": runner, "gem": output.name}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/test_reproducible_jekyll_build.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Prove deterministic Jekyll output with the packaged core and fixed epoch."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+IMAGE = os.environ.get("DOCKER_IMAGE", "ghcr.io/dosquartsdedocs/unaltraweb:0.3.0")
+SELECTOR = "v2026.09"
+EPOCH = "946684800"
+
+
+def run(command: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(
+        command,
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+    if check and completed.returncode != 0:
+        detail = completed.stderr.strip() or completed.stdout.strip()
+        raise RuntimeError(f"Command failed ({completed.returncode}): {' '.join(command)}\n{detail}")
+    return completed
+
+
+def docker_build(site: Path, destination: str, epoch: str) -> subprocess.CompletedProcess[str]:
+    return run(
+        [
+            "docker",
+            "run",
+            "--rm",
+            "--network",
+            "none",
+            "--user",
+            f"{os.getuid()}:{os.getgid()}",
+            "-e",
+            "HOME=/tmp",
+            "-e",
+            "BUNDLE_GEMFILE=/site/Gemfile.local",
+            "-e",
+            "JEKYLL_ENV=production",
+            "-e",
+            "LANG=C.UTF-8",
+            "-e",
+            "LC_ALL=C.UTF-8",
+            "-e",
+            f"SOURCE_DATE_EPOCH={epoch}",
+            "-e",
+            "TZ=UTC",
+            "-e",
+            f"UNALTRAWEB_MANUAL_RELEASE_SELECTOR={SELECTOR}",
+            "--mount",
+            f"type=bind,src={ROOT},dst=/core,readonly",
+            "--mount",
+            f"type=bind,src={site},dst=/site",
+            "--workdir",
+            "/site",
+            "--entrypoint",
+            "/bin/sh",
+            IMAGE,
+            "-c",
+            "umask 022; bundle lock --local && bundle check && "
+            "bundle exec jekyll build --config /core/_config.yml,/site/_config.yml "
+            f"--destination /site/{destination} --disable-disk-cache",
+        ],
+        check=False,
+    )
+
+
+def tree_inventory(root: Path) -> dict[str, dict[str, int | str]]:
+    result: dict[str, dict[str, int | str]] = {}
+    for path in sorted(root.rglob("*")):
+        relative = path.relative_to(root).as_posix()
+        metadata = path.lstat()
+        if stat.S_ISLNK(metadata.st_mode) or not (stat.S_ISDIR(metadata.st_mode) or stat.S_ISREG(metadata.st_mode)):
+            raise RuntimeError(f"Unexpected output type in reproducibility fixture: {relative}")
+        if path.is_dir():
+            result[relative + "/"] = {"mode": stat.S_IMODE(metadata.st_mode), "type": "directory"}
+        else:
+            content = path.read_bytes()
+            result[relative] = {
+                "mode": stat.S_IMODE(metadata.st_mode),
+                "sha256": hashlib.sha256(content).hexdigest(),
+                "size": len(content),
+                "type": "file",
+            }
+    return result
+
+
+def set_source_mtime(site: Path, timestamp: int) -> None:
+    for path in site.rglob("*"):
+        if not path.is_dir() and not any(part.startswith("_site-") for part in path.parts):
+            os.utime(path, (timestamp, timestamp))
+
+
+def write_fixture(site: Path) -> None:
+    (site / "_posts").mkdir(parents=True)
+    (site / "Gemfile.local").write_text(
+        'source "https://rubygems.org"\ngem "unaltraweb", path: "/core"\n',
+        encoding="utf-8",
+    )
+    (site / "_config.yml").write_text(
+        "title: Reproducible manual\n"
+        "url: https://example.invalid\n"
+        "baseurl: ''\n"
+        "lang: en\n"
+        "default_lang: en\n"
+        "languages: [en]\n"
+        "theme: unaltraweb\n"
+        "plugins: [unaltraweb]\n"
+        "last_updated: true\n"
+        "exclude: [_site-a, _site-b, _site-invalid]\n"
+        "unaltraweb:\n"
+        "  site_profile: unaltremanual\n"
+        "  manual:\n"
+        "    pdf:\n"
+        "      enabled: false\n",
+        encoding="utf-8",
+    )
+    (site / "index.md").write_text(
+        "---\ntitle: Manual\n---\n{% include footer.liquid %}\n",
+        encoding="utf-8",
+    )
+    (site / "_posts/1999-12-31-reviewed.md").write_text(
+        "---\ntitle: Reviewed\ndate: 1999-12-31 12:00:00 +0000\n---\nReviewed post.\n",
+        encoding="utf-8",
+    )
+    (site / "manual.pdf").write_bytes(b"reviewed static file\n")
+
+
+def main() -> int:
+    inspected = run(["docker", "image", "inspect", IMAGE], check=False)
+    if inspected.returncode != 0:
+        raise RuntimeError(f"Reproducibility check requires the already-local runtime image {IMAGE}; it never pulls implicitly.")
+
+    with tempfile.TemporaryDirectory(prefix="unaltraweb-reproducible-site-") as raw:
+        site = Path(raw).resolve()
+        write_fixture(site)
+        set_source_mtime(site, 978307200)
+        first = docker_build(site, "_site-a", EPOCH)
+        if first.returncode != 0:
+            raise RuntimeError(first.stderr.strip() or first.stdout.strip())
+
+        set_source_mtime(site, 1893456000)
+        second = docker_build(site, "_site-b", EPOCH)
+        if second.returncode != 0:
+            raise RuntimeError(second.stderr.strip() or second.stdout.strip())
+
+        first_inventory = tree_inventory(site / "_site-a")
+        second_inventory = tree_inventory(site / "_site-b")
+        if first_inventory != second_inventory:
+            differing = sorted(set(first_inventory) | set(second_inventory))
+            differing = [path for path in differing if first_inventory.get(path) != second_inventory.get(path)]
+            raise RuntimeError("Fixed-epoch Jekyll builds differ: " + ", ".join(differing[:12]))
+
+        expected_marker = json.dumps(
+            {"channel": "stable", "schema_version": 1, "selector": SELECTOR},
+            ensure_ascii=False,
+            indent=2,
+            sort_keys=True,
+        ) + "\n"
+        marker = (site / "_site-a/manual-release.json").read_text(encoding="utf-8")
+        if marker != expected_marker:
+            raise RuntimeError("manual-release.json was not preserved as canonical JSON.")
+        index = (site / "_site-a/index.html").read_text(encoding="utf-8")
+        if "2000" not in index or "January 1, 2000" not in index:
+            raise RuntimeError("Footer does not use the fixed build time.")
+        feed = (site / "_site-a/feed.xml").read_text(encoding="utf-8")
+        if "2000-01-01T00:00:00+00:00" not in feed:
+            raise RuntimeError("Feed does not use the fixed build time.")
+
+        invalid = docker_build(site, "_site-invalid", "not-an-epoch")
+        if invalid.returncode == 0 or "SOURCE_DATE_EPOCH" not in (invalid.stderr + invalid.stdout):
+            raise RuntimeError("Malformed SOURCE_DATE_EPOCH did not fail the Jekyll build.")
+
+    print(json.dumps({"image": IMAGE, "ok": True, "selector": SELECTOR}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/test_wheel_install.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""Build and exercise a clean, factory-free unaltraweb-mcp wheel install."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import venv
+import zipfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run(command: list[str], *, cwd: Path, env: dict[str, str] | None = None, expected: int = 0) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(command, cwd=cwd, env=env, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+    if completed.returncode != expected:
+        raise RuntimeError(
+            f"Command returned {completed.returncode}, expected {expected}: {' '.join(command)}\n{completed.stdout}\n{completed.stderr}"
+        )
+    return completed
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(prefix="unaltraweb-wheel-") as raw_temp:
+        temp = Path(raw_temp)
+        source = temp / "source"
+        shutil.copytree(
+            ROOT,
+            source,
+            ignore=shutil.ignore_patterns(
+                ".git",
+                "build",
+                "dist",
+                "*.egg-info",
+                "_site",
+                "tmp",
+                "__pycache__",
+                "*.pyc",
+            ),
+        )
+        wheel_dir = temp / "dist"
+        wheel_dir.mkdir()
+        env = os.environ.copy()
+        env["PIP_NO_INDEX"] = "1"
+        run(
+            [sys.executable, "-m", "pip", "wheel", ".", "--no-deps", "--no-build-isolation", "--wheel-dir", str(wheel_dir)],
+            cwd=source,
+            env=env,
+        )
+        wheels = list(wheel_dir.glob("unaltraweb_mcp-*.whl"))
+        if len(wheels) != 1:
+            raise RuntimeError(f"Expected one wheel, found: {wheels}")
+        with zipfile.ZipFile(wheels[0]) as archive:
+            names = archive.namelist()
+        forbidden_roots = {"docs", "scripts", "_layouts", "_includes", "_sass"}
+        leaked = []
+        for name in names:
+            parts = Path(name).parts
+            if not parts or parts[0] != "unaltraweb_mcp":
+                continue
+            package_parts = parts[1:]
+            if package_parts and (package_parts[0] in forbidden_roots or package_parts[0] in {"mcp-factory.yml", "Dockerfile", "Makefile"}):
+                leaked.append(name)
+        if leaked:
+            raise RuntimeError(f"Factory assets leaked into wheel: {leaked}")
+        required = [
+            "unaltraweb_mcp/calibre_import.py",
+            "unaltraweb_mcp/component-contract.json",
+            "unaltraweb_mcp/component-contract.schema.json",
+            "unaltraweb_mcp/manual_release.py",
+            "unaltraweb_mcp/scaffolds/common/AGENTS.md.tmpl",
+            "unaltraweb_mcp/scaffolds/common/Makefile.tmpl",
+            "unaltraweb_mcp/scaffolds/common/README.md.tmpl",
+            "unaltraweb_mcp/scaffolds/common/.gitignore.tmpl",
+            "unaltraweb_mcp/scaffolds/common/.unaltraweb/docker-mount.sh",
+            "unaltraweb_mcp/scaffolds/common/root.html.tmpl",
+            "unaltraweb_mcp/scaffolds/profiles/unaltremanual/computations.yml.tmpl",
+            "unaltraweb_mcp/scaffolds/profiles/unaltremanual/_bibliography/manual.bib",
+            "unaltraweb_mcp/scaffolds/profiles/unaltreprojecte/_bibliography/papers.bib",
+            "unaltraweb_mcp/scaffolds/profiles/unaltreselfie/_bibliography/papers.bib",
+            "unaltraweb_mcp/scaffolds/common/.github/CONTRIBUTING.md",
+            "unaltraweb_mcp/scaffolds/common/.github/dependabot.yml.tmpl",
+            "unaltraweb_mcp/scaffolds/common/.github/pull_request_template.md",
+            "unaltraweb_mcp/scaffolds/common/.github/workflows/deploy.yml.tmpl",
+        ]
+        missing = [name for name in required if name not in names]
+        if missing:
+            raise RuntimeError(f"Wheel is missing modular package assets: {missing}")
+        if "unaltraweb_mcp/scaffolds/common/.gitignore" in names:
+            raise RuntimeError("Wheel contains the retired static common .gitignore")
+
+        environment = temp / "venv"
+        venv.EnvBuilder(with_pip=True).create(environment)
+        python = environment / "bin/python"
+        cli = environment / "bin/unaltraweb-mcp"
+        run([str(python), "-m", "pip", "install", "--no-deps", str(wheels[0])], cwd=temp, env=env)
+        version = run([str(cli), "version"], cwd=temp).stdout.strip()
+        doctor = json.loads(run([str(cli), "doctor"], cwd=temp).stdout)
+        if not doctor["ok"] or doctor["mode"] != "wheel" or not doctor["limited"]:
+            raise RuntimeError(f"Unexpected clean wheel doctor result: {doctor}")
+
+        contract = json.loads((ROOT / "src/unaltraweb_mcp/component-contract.json").read_text(encoding="utf-8"))
+        integration = contract["consumer_integration"]
+        profiles = {
+            "unaltreselfie": ("Personal academic or professional site.", "`_posts/` and `_news/`"),
+            "unaltreprojecte": ("Research project, group, infrastructure, or output site.", "`_data/team.yml`"),
+            "unaltremanual": ("Book-like manual, course, or teaching site.", "`_chapters/<lang>/`"),
+            "unaltredocs": ("Technical or operational documentation portal.", "`_documentation/<lang>/`"),
+        }
+        sites: dict[str, Path] = {}
+        for profile, (description, profile_path) in profiles.items():
+            profile_site = temp / f"site-{profile}"
+            created = json.loads(run([
+                str(cli), "--project", str(profile_site), "new-web", "--site-profile", profile,
+                "--title", f"Wheel {profile}",
+            ], cwd=temp).stdout)
+            if not created["ok"]:
+                raise RuntimeError(f"new-web failed for {profile} from clean wheel: {created}")
+            readme = (profile_site / "README.md").read_text(encoding="utf-8")
+            collaboration = (profile_site / ".github/CONTRIBUTING.md").read_text(encoding="utf-8")
+            dependabot = (profile_site / ".github/dependabot.yml").read_text(encoding="utf-8")
+            pr_template = (profile_site / ".github/pull_request_template.md").read_text(encoding="utf-8")
+            if not readme.startswith("# GitHub Web Editing Workflow\n"):
+                raise RuntimeError(f"generated {profile} README is not editor-first")
+            required_guidance = [
+                f"**`{profile}`** profile: {description}",
+                f"## Editable Content For `{profile}`",
+                profile_path,
+                "only one active editor per file",
+                "Never edit or commit directly to `main`",
+                "Draft pull request",
+                "Starts the deploy workflow manually",
+            ]
+            missing_guidance = [value for value in required_guidance if value not in readme]
+            if missing_guidance:
+                raise RuntimeError(f"generated {profile} README is missing guidance: {missing_guidance}")
+            if f"Wheel {profile}" in readme:
+                raise RuntimeError(f"generated {profile} README interpolated the user-controlled title")
+            if any(f"`{known_profile}`" not in readme for known_profile in profiles):
+                raise RuntimeError(f"generated {profile} README does not explain all profiles")
+            if "correctly named short-lived branch" not in pr_template or "Required local checks and renders pass" not in pr_template:
+                raise RuntimeError(f"generated {profile} pull request template lacks coordination checks")
+            collaboration_markers = [
+                "content/<issue>-<slug>",
+                "reference/<issue>-<slug>",
+                "figure/<provider>/<issue>-<slug>",
+                "fix/<issue>-<slug>",
+                "feat/<issue>-<slug>",
+                "docs/<issue>-<slug>",
+                "chore/<issue>-<slug>",
+                "format/<issue>-<slug>",
+                "integration/<provider>/<issue>-<slug>",
+                "A maintainer must accept an exact reservation",
+                "not broad directories or globs",
+                "dedicated Git worktree",
+                "Never share a mutable checkout",
+                "one atomic bundle",
+                "source, every local data/input file, output, caption-bearing content reference",
+                "immutable release, full commit SHA, or image digest",
+                "Draft pull request after the first coherent change",
+                "delete the local and remote task branch",
+                "remove the worktree",
+            ]
+            if any(value not in collaboration for value in collaboration_markers):
+                raise RuntimeError(f"generated {profile} collaboration contract is incomplete")
+            if "dependency-name: unaltraweb" not in dependabot or f"dependency-name: {integration['site_deploy_workflow']}" not in dependabot:
+                raise RuntimeError(f"generated {profile} Dependabot policy permits partial integration updates")
+            combined_guidance = readme + collaboration + pr_template
+            forbidden = ["${{", "secrets.", "GITHUB_TOKEN", "id-token:", "contents: write", "on:\n  push:"]
+            if any(value in combined_guidance for value in forbidden):
+                raise RuntimeError(f"generated {profile} editor guidance exposes workflow or secret internals")
+            auto_publish = ["publishes automatically", "deploys automatically", "automatic deployment"]
+            if any(value in combined_guidance.lower() for value in auto_publish):
+                raise RuntimeError(f"generated {profile} editor guidance implies automatic publication")
+            if profile == "unaltremanual":
+                manual_markers = [
+                    "`latest` is a manual-only deployment",
+                    "Pushing or merging to `main` does not publish the manual",
+                    "are generated for deployment and are not versioned",
+                    "`vYYYY.MM(.N)`",
+                    "Release checks reject `legacy/` or `sandbox/`",
+                ]
+                if any(value not in readme for value in manual_markers):
+                    raise RuntimeError("generated unaltremanual README lacks release-channel guidance")
+            elif "## unaltremanual Publishing Channels" in readme:
+                raise RuntimeError(f"generated {profile} README contains unaltremanual-only release guidance")
+            ignore_lines = (profile_site / ".gitignore").read_text(encoding="utf-8").splitlines()
+            expects_manual_outputs = profile == "unaltremanual"
+            if ("/assets/pdf/manual-en.pdf" in ignore_lines) != expects_manual_outputs or ("/assets/img/manual-cover-en.png" in ignore_lines) != expects_manual_outputs:
+                raise RuntimeError(f"generated {profile} .gitignore has incorrect manual output scope")
+            if "*.pdf" in ignore_lines or "*.png" in ignore_lines:
+                raise RuntimeError(f"generated {profile} .gitignore ignores arbitrary publication assets")
+            gemfile = (profile_site / "Gemfile").read_text(encoding="utf-8")
+            lockfile = (profile_site / "Gemfile.lock").read_text(encoding="utf-8")
+            deploy = (profile_site / ".github/workflows/deploy.yml").read_text(encoding="utf-8")
+            if f'git: "{integration["core_repository"]}"' not in gemfile or f'ref: "{integration["core_sha"]}"' not in gemfile:
+                raise RuntimeError(f"generated {profile} Gemfile does not use the reviewed core revision")
+            if f'revision: {integration["core_sha"]}' not in lockfile:
+                raise RuntimeError(f"generated {profile} lockfile does not use the reviewed core revision")
+            if f'uses: {integration["site_deploy_workflow"]}@{integration["core_sha"]}' not in deploy:
+                raise RuntimeError(f"generated {profile} deploy caller does not use the reviewed core revision")
+            if f'manual-pdf-image: "{integration["manual_pdf_image"]}"' not in deploy:
+                raise RuntimeError(f"generated {profile} deploy caller does not use the reviewed PDF image")
+            if f'vegavisuals-sha: "{integration["vegavisuals_sha"]}"' not in deploy:
+                raise RuntimeError(f"generated {profile} deploy caller does not use the reviewed Vega renderer")
+            manifest = json.loads((profile_site / ".unaltraweb/scaffold.json").read_text(encoding="utf-8"))
+            expected_managed = {
+                ".gitignore",
+                ".unaltraweb/docker-mount.sh",
+                ".github/CONTRIBUTING.md",
+                ".github/dependabot.yml",
+                "Makefile",
+                "Gemfile",
+                "Gemfile.lock",
+                ".github/pull_request_template.md",
+                ".github/workflows/deploy.yml",
+            }
+            if set(manifest["files"]) != expected_managed:
+                raise RuntimeError(f"generated {profile} scaffold baseline is incomplete: {manifest['files']}")
+            sites[profile] = profile_site
+
+        site = sites["unaltredocs"]
+        if not (site / ".unaltraweb/scaffold.json").is_file():
+            raise RuntimeError("new-web did not install the package scaffold baseline")
+
+        manual_site = temp / "manual-site"
+        manual_created = json.loads(run([str(cli), "--project", str(manual_site), "new-web", "--site-profile", "unaltremanual"], cwd=temp).stdout)
+        if not manual_created["ok"]:
+            raise RuntimeError(f"manual new-web failed from clean wheel: {manual_created}")
+        for required_path in [
+            "AGENTS.md",
+            "README.md",
+            "_pages/index.html",
+            "_chapters/en/.gitkeep",
+            "assets/quarto/.gitkeep",
+            "assets/img/generated/.gitkeep",
+        ]:
+            if not (manual_site / required_path).is_file():
+                raise RuntimeError(f"manual new-web did not create {required_path}")
+        computation_config = (manual_site / ".unaltraweb/computations.yml").read_text(encoding="utf-8")
+        for component_id in ["compute_python", "compute_r"]:
+            if contract["components"][component_id]["reference"] not in computation_config:
+                raise RuntimeError(f"new-web did not select the {component_id} worker from the component contract")
+        manual_doctor = json.loads(run([str(cli), "doctor", "--project", str(manual_site)], cwd=temp).stdout)
+        if not {"compute_python", "compute_r"}.issubset(manual_doctor["selected_components"]):
+            raise RuntimeError(f"manual project doctor did not select both computation workers: {manual_doctor}")
+        detected = json.loads(run([str(cli), "--project", str(site), "mcp", "detect-site"], cwd=temp).stdout)
+        if not detected["is_unaltraweb_site"]:
+            raise RuntimeError(f"package-only inspection failed from clean wheel: {detected}")
+        project_doctor = json.loads(run([str(cli), "doctor", "--project", str(site)], cwd=temp).stdout)
+        if not project_doctor["ok"] or project_doctor["project"]["profile"] != "unaltredocs":
+            raise RuntimeError(f"project doctor failed from clean wheel: {project_doctor}")
+        site_doctor = json.loads(run([str(cli), "--project", str(site), "mcp", "site-doctor"], cwd=temp).stdout)
+        if not site_doctor["ok"] or not site_doctor["offline"]:
+            raise RuntimeError(f"site doctor failed from clean wheel: {site_doctor}")
+        source = json.loads(run([str(cli), "--project", str(site), "mcp", "site-source-read", "--path", "_pages/en/index.md"], cwd=temp).stdout)
+        source_dry_run = json.loads(run([
+            str(cli), "--project", str(site), "mcp", "site-source-write",
+            "--path", "_pages/en/index.md", "--content", source["content"] + "\nWheel source test.\n",
+            "--expected-sha256", source["sha256"],
+        ], cwd=temp).stdout)
+        if not source_dry_run["dry_run"] or (site / "_pages/en/index.md").read_text(encoding="utf-8") != source["content"]:
+            raise RuntimeError(f"wheel source dry-run mutated content: {source_dry_run}")
+        scaffold = json.loads(run([str(cli), "--project", str(site), "mcp", "scaffold-sync"], cwd=temp).stdout)
+        if not scaffold["ok"] or not scaffold["dry_run"]:
+            raise RuntimeError(f"wheel scaffold sync dry-run failed: {scaffold}")
+
+        factory_error = run([str(cli), "--project", str(site), "mcp", "prompts"], cwd=temp, expected=1)
+        if "requires the unaltraweb factory checkout" not in factory_error.stderr:
+            raise RuntimeError(f"Factory-required command did not fail clearly: {factory_error.stderr}")
+        print(json.dumps({"ok": True, "version": version, "wheel": wheels[0].name, "mode": doctor["mode"]}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/unaltraweb-docker-mount.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+set -eu
+
+if [ "$#" -lt 2 ] || [ "$#" -gt 3 ]; then
+  printf '%s\n' 'Usage: unaltraweb-docker-mount SOURCE TARGET [readonly]' >&2
+  exit 2
+fi
+case "$1" in
+  /*) ;;
+  *) printf '%s\n' 'Docker bind source must be an absolute path.' >&2; exit 2 ;;
+esac
+case "$2" in
+  /*) ;;
+  *) printf '%s\n' 'Docker bind target must be an absolute path.' >&2; exit 2 ;;
+esac
+if [ "$#" -eq 3 ] && [ "$3" != "readonly" ]; then
+  printf '%s\n' 'The optional Docker bind mode must be readonly.' >&2
+  exit 2
+fi
+newline='
+'
+carriage_return=$(printf '\r')
+case "$1$2" in
+  *"$newline"*|*"$carriage_return"*)
+    printf '%s\n' 'Docker bind source and target must not contain carriage returns or newlines.' >&2
+    exit 2
+    ;;
+esac
+
+source_field=$(printf 'source=%s' "$1" | sed 's/"/""/g')
+target_field=$(printf 'target=%s' "$2" | sed 's/"/""/g')
+printf 'type=bind,"%s","%s"' "$source_field" "$target_field"
+if [ "$#" -eq 3 ]; then
+  printf ',readonly'
+fi
+printf '\n'