unaltraweb 0.5.0 → 0.6.0

data/scripts/test_gem_build.py

@@ -62,8 +62,11 @@ def build(output: Path, *, source: Path = ROOT) -> str:
 
 def inspect_gem(path: Path) -> None:
     editorial_files = ["scripts/editorial_check.py", "src/unaltraweb_mcp/editorial.py", "src/unaltraweb_mcp/editorial_sources.py"]
-    inspection_files = editorial_files + ["scripts/image_background_check.py", "src/unaltraweb_mcp/image_backgrounds.py",
+    inspection_files = editorial_files + ["src/unaltraweb_mcp/bundler_runtime.py", "scripts/image_background_check.py", "src/unaltraweb_mcp/image_backgrounds.py",
                                           "src/unaltraweb_mcp/image_probe.py", "src/unaltraweb_mcp/processes.py"]
+    inspection_files += [f"src/unaltraweb_mcp/{name}" for name in (
+        "__init__.py", "distribution.py", "component-contract.json", "component-contract.schema.json",
+        "artifact_imports.py", "artifact_handoff_v1.py", "artifact-handoff-v1.schema.json", "letter_bundle.py", "pdf_probe.py")]
     with tarfile.open(path, mode="r") as package:
         data_member = package.extractfile("data.tar.gz")
         if data_member is None:
@@ -83,6 +86,7 @@ def inspect_gem(path: Path) -> None:
         "_plugins/figure_captions.rb",
         "_plugins/manual_release_metadata.rb",
         "_plugins/reproducible_build_time.rb",
+        "_plugins/retained_documents.rb",
         "assets/js/content-search-match.js",
         "assets/js/content-search.js",
         "_config.yml",
@@ -134,6 +138,29 @@ def inspect_gem(path: Path) -> None:
         inspection = json.loads(run(image_command, cwd=site).stdout)
         if not inspection["ok"] or inspection["images"][0]["state"] != "transparent" or not inspection["warnings"]:
             raise RuntimeError(f"Gem-native SVG background inspection failed: {inspection}")
+        # This is the synthetic domain fixture, not published-Carta acceptance.
+        # Only its data crosses into the isolated extracted-gem subprocess.
+        sys.path.insert(0, str(ROOT / "test"))
+        from test_artifact_imports import fixture
+
+        bundle_sha, template_sha = fixture(site / "incoming/letter")
+        (site / ".gitignore").write_text("tmp/\n", encoding="utf-8")
+        run(["git", "init", "--quiet"], cwd=site)
+        isolated = """
+import json, sys
+from pathlib import Path
+sys.path.insert(0, sys.argv[1])
+from unaltraweb_mcp import artifact_imports, letter_bundle, artifact_handoff_v1, distribution, processes
+for module in (artifact_imports, letter_bundle, artifact_handoff_v1, distribution, processes):
+    assert Path(module.__file__).is_relative_to(Path(sys.argv[1])), module.__file__
+letter_bundle.TEMPLATES['default-letter.latex'] = sys.argv[4]
+project = Path(sys.argv[2])
+result = artifact_imports.import_bundle(project, 'incoming/letter/bundle.json', sys.argv[3],
+    'letter', '_pages/en/letter.md', dry_run=False, confirm_import=True)
+print(json.dumps(result))
+raise SystemExit(0 if result['ok'] else 1)
+"""
+        run([sys.executable, "-I", "-c", isolated, str(core / "src"), str(site), bundle_sha, template_sha], cwd=site)
 
 
 def main() -> int:

data/scripts/test_wheel_install.py

@@ -35,6 +35,9 @@ def main() -> int:
             source,
             ignore=shutil.ignore_patterns(
                 ".git",
+                ".venv",
+                ".cache",
+                ".jekyll-cache",
                 "build",
                 "dist",
                 "*.egg-info",
@@ -58,6 +61,21 @@ def main() -> int:
             raise RuntimeError(f"Expected one wheel, found: {wheels}")
         with zipfile.ZipFile(wheels[0]) as archive:
             names = archive.namelist()
+            launcher_prefix = f"{wheels[0].name.split('-')[0]}-{wheels[0].name.split('-')[1]}.data/data/share/unaltraweb-launcher/"
+            launcher_files = {
+                "Makefile": "packaging/launcher/Makefile",
+                "mcp-factory.yml": "mcp-factory.yml",
+                **{f"scripts/{name}.sh": f"scripts/{name}.sh" for name in (
+                    "unaltraweb-mcp-bootstrap", "unaltraweb-mcp-project-id",
+                    "unaltraweb-mcp-cleanup", "unaltraweb-docker-mount",
+                )},
+            }
+            actual_launcher = {name.removeprefix(launcher_prefix) for name in names if name.startswith(launcher_prefix)}
+            if actual_launcher != set(launcher_files):
+                raise RuntimeError(f"Wheel launcher closure mismatch: {actual_launcher}")
+            for installed_path, source_path in launcher_files.items():
+                if archive.read(launcher_prefix + installed_path) != (ROOT / source_path).read_bytes():
+                    raise RuntimeError(f"Wheel launcher asset differs from source: {installed_path}")
         forbidden_roots = {"docs", "scripts", "_layouts", "_includes", "_sass"}
         leaked = []
         for name in names:
@@ -71,6 +89,12 @@ def main() -> int:
             raise RuntimeError(f"Factory assets leaked into wheel: {leaked}")
         required = [
             "unaltraweb_mcp/calibre_import.py",
+            "unaltraweb_mcp/bundler_runtime.py",
+            "unaltraweb_mcp/artifact_imports.py",
+            "unaltraweb_mcp/artifact_handoff_v1.py",
+            "unaltraweb_mcp/artifact-handoff-v1.schema.json",
+            "unaltraweb_mcp/letter_bundle.py",
+            "unaltraweb_mcp/pdf_probe.py",
             "unaltraweb_mcp/component-contract.json",
             "unaltraweb_mcp/component-contract.schema.json",
             "unaltraweb_mcp/manual_pdf_preview.py",
@@ -105,6 +129,33 @@ def main() -> int:
         python = environment / "bin/python"
         cli = environment / "bin/unaltraweb-mcp"
         run([str(python), "-m", "pip", "install", "--no-deps", str(wheels[0])], cwd=temp, env=env)
+        docker_cli = environment / "bin/unaltraweb-mcp-docker"
+        launcher = Path(run([str(docker_cli), "path"], cwd=temp).stdout.strip())
+        if launcher != environment / "share/unaltraweb-launcher":
+            raise RuntimeError(f"Launcher did not resolve its installed wheel data: {launcher}")
+        if run([str(docker_cli), "manifest"], cwd=temp).stdout != (ROOT / "mcp-factory.yml").read_text(encoding="utf-8"):
+            raise RuntimeError("Installed native manifest drifted from discovery contract")
+        no_consumer_env = {key: value for key, value in env.items() if key not in {"MCP_CONSUMER_WORKSPACE", "UNALTRAWEB_PROJECT"}}
+        refused = run([str(docker_cli), "serve"], cwd=temp, env=no_consumer_env, expected=2)
+        if "requires --project" not in refused.stderr:
+            raise RuntimeError("Installed launcher accepted an implicit consumer")
+        fake_bin = temp / "fake-bin"
+        fake_bin.mkdir()
+        fake_docker = fake_bin / "docker"
+        fake_docker.write_text("#!/bin/sh\n[ \"$1 $2\" = 'image inspect' ] || exit 99\n[ \"$5\" = \"$EXPECTED_IMAGE\" ] || exit 98\nprintf 'sha256:fixture\\n'\n", encoding="utf-8")
+        fake_docker.chmod(0o755)
+        expected_image = json.loads((ROOT / "src/unaltraweb_mcp/component-contract.json").read_text())["components"]["mcp"]["reference"]
+        launcher_env = {**no_consumer_env, "PATH": f"{fake_bin}:{env['PATH']}", "EXPECTED_IMAGE": expected_image}
+        launcher_env.pop("UNALTRAWEB_MCP_IMAGE", None)
+        launcher_env.pop("MCP_RELEASE_IMAGE", None)
+        prepared_image = run([str(docker_cli), "prepare"], cwd=temp, env=launcher_env).stdout.strip()
+        if prepared_image != "sha256:fixture":
+            raise RuntimeError("Installed preparation did not use the packaged bootstrap")
+        run(["make", "--silent", "--no-print-directory", "-C", str(launcher), "mcp-build"], cwd=temp, env=launcher_env)
+        run([str(docker_cli), "prepare", "--image", "explicit:override"], cwd=temp,
+            env={**launcher_env, "EXPECTED_IMAGE": "explicit:override", "UNALTRAWEB_MCP_IMAGE": "environment:override"})
+        run([str(docker_cli), "prepare"], cwd=temp,
+            env={**launcher_env, "EXPECTED_IMAGE": "environment:override", "UNALTRAWEB_MCP_IMAGE": "environment:override"})
         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"]:

data/scripts/unaltraweb-mcp-bootstrap.sh

@@ -3,15 +3,18 @@ set -eu
 
 usage() {
   cat <<'USAGE'
-Usage: unaltraweb-mcp-bootstrap [--project PATH] [--image IMAGE]
+Usage: unaltraweb-mcp-bootstrap [--project PATH] [--image IMAGE] [--prepare|--check|--smoke]
 
 Start one Dockerized unaltraweb MCP stdio server for the selected workspace.
 If --project is omitted, MCP_CONSUMER_WORKSPACE is used, then the current directory.
+--prepare inspects or pulls the selected image without mounting a consumer.
+--check and --smoke require that image locally; neither builds nor pulls.
 USAGE
 }
 
-image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0}"
+image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:908b4ce54c7bdf355e14ed55b31ed4b9baae319e211af90004a680d1d1cb8692}"
 project="${MCP_CONSUMER_WORKSPACE:-${UNALTRAWEB_PROJECT:-}}"
+operation=serve
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -25,6 +28,11 @@ while [ "$#" -gt 0 ]; do
       image="$2"
       shift 2
       ;;
+    --prepare|--check|--smoke)
+      [ "$operation" = serve ] || { printf '%s\n' 'Select only one operation.' >&2; exit 2; }
+      operation="${1#--}"
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -37,6 +45,28 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
+resolve_image() {
+  if ! resolved_image="$(docker image inspect --format '{{.Id}}' "$image" 2>/dev/null)"; then
+    case "$operation" in
+      check|smoke)
+        printf 'Image is not prepared: %s. Run --prepare first.\n' "$image" >&2
+        exit 1
+        ;;
+    esac
+    docker pull "$image" >&2
+    resolved_image="$(docker image inspect --format '{{.Id}}' "$image")"
+  fi
+}
+
+if [ "$operation" != serve ]; then
+  resolve_image
+  case "$operation" in
+    prepare) printf '%s\n' "$resolved_image"; exit 0 ;;
+    check) exec docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint unaltraweb-mcp "$resolved_image" version ;;
+    smoke) exec docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint python3 "$resolved_image" /opt/unaltraweb/test/mcp_smoke.py ;;
+  esac
+fi
+
 if [ -z "$project" ]; then
   project="$PWD"
 fi
@@ -80,10 +110,7 @@ if [ -S "$docker_socket" ]; then
   esac
 fi
 
-if ! resolved_image="$(docker image inspect --format '{{.Id}}' "$image" 2>/dev/null)"; then
-  docker pull "$image" >/dev/null
-  resolved_image="$(docker image inspect --format '{{.Id}}' "$image")"
-fi
+resolve_image
 image_reference="$image"
 case "$image_reference" in
   ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:*) ;;

data/scripts/validate_distribution.py

@@ -75,7 +75,7 @@ def component_version_errors(contract: dict[str, Any]) -> list[str]:
     """Retain the real version of already-published, digest-pinned workers."""
     version = str(contract["release"]["version"])
     errors = []
-    reusable_workers = {"compute_python", "compute_r", "web_capture"}
+    reusable_workers = {"compute_python", "compute_r", "web_capture", "manual_pdf"}
     for component_id in ["gem", "wheel", "runtime", "mcp", "compute_python", "compute_r", "web_capture", "manual_pdf"]:
         selected = contract["components"][component_id]
         if (component_id in reusable_workers and selected["kind"] == "container"
@@ -168,6 +168,20 @@ def validate(root: Path = ROOT) -> list[str]:
         errors.append("component contract schema does not select version 1")
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    launcher_files = {
+        "share/unaltraweb-launcher": ["packaging/launcher/Makefile", "mcp-factory.yml"],
+        "share/unaltraweb-launcher/scripts": [
+            "scripts/unaltraweb-mcp-bootstrap.sh", "scripts/unaltraweb-mcp-project-id.sh",
+            "scripts/unaltraweb-mcp-cleanup.sh", "scripts/unaltraweb-docker-mount.sh",
+        ],
+    }
+    if pyproject.get("tool", {}).get("setuptools", {}).get("data-files") != launcher_files:
+        errors.append("wheel must distribute exactly the native Docker launcher and its helper closure")
+    launcher_image = make_value(root / "Makefile", "MCP_RELEASE_IMAGE")
+    if not re.fullmatch(r"ghcr\.io/dosquartsdedocs/unaltraweb-mcp@sha256:[0-9a-f]{64}", launcher_image):
+        errors.append("MCP_RELEASE_IMAGE must select a full GHCR MCP digest")
+    if make_value(root / "packaging/launcher/Makefile", "MCP_RELEASE_IMAGE") != component_reference("mcp"):
+        errors.append("installed launcher must select its own package release image")
     project = pyproject.get("project", {})
     if "version" in project or project.get("dynamic") != ["version"]:
         errors.append("pyproject version must be derived from the package component contract")
@@ -242,7 +256,7 @@ def validate(root: Path = ROOT) -> list[str]:
     pinned_text = {
         "scripts/computations/render.py": [component_reference("compute_python"), component_reference("compute_r")],
         "scripts/web_captures/render.py": [component_reference("web_capture")],
-        "scripts/unaltraweb-mcp-bootstrap.sh": [component_reference("mcp")],
+        "scripts/unaltraweb-mcp-bootstrap.sh": [launcher_image],
         "Dockerfile.mcp": [component_reference("runtime")],
     }
     for relative, references in pinned_text.items():
@@ -485,6 +499,11 @@ def publish_ref_errors(
         if not isinstance(component, dict):
             errors.append(f"unknown publish component: {component_id}")
             continue
+        if (component_id == "manual_pdf" and component.get("release_status") == "released"
+                and re.fullmatch(r"ghcr\.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:[0-9a-f]{64}", str(component.get("reference", "")))):
+            # Already-published, unchanged worker. It is not a new candidate for
+            # this coordinated core release and receives no new semver identity.
+            continue
         if str(component.get("version") or "") != version:
             errors.append(f"{component_id} publish version does not match distribution release {version}")
         if str(component.get("release") or "") != release_tag:

data/src/unaltraweb_mcp/__init__.py

@@ -0,0 +1,4 @@
+from .distribution import distribution_version
+
+
+__version__ = distribution_version()

data/src/unaltraweb_mcp/artifact-handoff-v1.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "MCP artifact handoff v1 (review candidate)",
+  "oneOf": [
+    {"$ref": "#/$defs/bundle"},
+    {"$ref": "#/$defs/integration"}
+  ],
+  "$defs": {
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,79}$"},
+    "hash": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+    "revision": {"type": "string", "pattern": "^(git:([0-9a-f]{40}|[0-9a-f]{64})|sha256:[0-9a-f]{64})$"},
+    "path": {"type": "string", "minLength": 1, "maxLength": 1024},
+    "runtime": {
+      "type": "object", "additionalProperties": false,
+      "required": ["name", "revision"],
+      "properties": {
+        "name": {"$ref": "#/$defs/id"},
+        "revision": {"$ref": "#/$defs/revision"}
+      }
+    },
+    "actor": {
+      "type": "object", "additionalProperties": false,
+      "required": ["name", "version", "revision", "runtimes"],
+      "properties": {
+        "name": {"$ref": "#/$defs/id"},
+        "version": {"type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]*$"},
+        "revision": {"$ref": "#/$defs/revision"},
+        "runtimes": {"type": "array", "maxItems": 32, "items": {"$ref": "#/$defs/runtime"}}
+      }
+    },
+    "dependency": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "sha256"],
+      "properties": {
+        "id": {"$ref": "#/$defs/id"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "upstream": {
+      "type": "object", "additionalProperties": false,
+      "required": ["dependency", "file"],
+      "properties": {
+        "dependency": {"$ref": "#/$defs/id"},
+        "file": {"$ref": "#/$defs/id"}
+      }
+    },
+    "file": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "path", "kind", "role", "ownership", "sha256", "bytes"],
+      "properties": {
+        "id": {"$ref": "#/$defs/id"},
+        "path": {"$ref": "#/$defs/path"},
+        "kind": {"enum": ["input", "output", "evidence"]},
+        "role": {"$ref": "#/$defs/id"},
+        "ownership": {"enum": ["author", "producer"]},
+        "sha256": {"$ref": "#/$defs/hash"},
+        "bytes": {"type": "integer", "minimum": 0, "maximum": 536870912},
+        "variant_of": {"$ref": "#/$defs/id"},
+        "from": {"$ref": "#/$defs/upstream"}
+      }
+    },
+    "bundle": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schema_version", "kind", "producer", "request", "files", "dependencies"],
+      "properties": {
+        "schema_version": {"type": "integer", "const": 1},
+        "kind": {"const": "mcp-artifact-bundle"},
+        "producer": {"$ref": "#/$defs/actor"},
+        "request": {"$ref": "#/$defs/id"},
+        "files": {"type": "array", "minItems": 2, "maxItems": 10000, "items": {"$ref": "#/$defs/file"}},
+        "dependencies": {"type": "array", "maxItems": 63, "items": {"$ref": "#/$defs/dependency"}}
+      }
+    },
+    "retained_bundle": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {"$ref": "#/$defs/path"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "mapping": {
+      "type": "object", "additionalProperties": false,
+      "required": ["source", "destination"],
+      "properties": {
+        "source": {"$ref": "#/$defs/path"},
+        "destination": {"$ref": "#/$defs/path"}
+      }
+    },
+    "integration": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schema_version", "kind", "integrator", "bundle", "mappings"],
+      "properties": {
+        "schema_version": {"type": "integer", "const": 1},
+        "kind": {"const": "mcp-artifact-integration"},
+        "integrator": {"$ref": "#/$defs/actor"},
+        "bundle": {"$ref": "#/$defs/retained_bundle"},
+        "mappings": {"type": "array", "minItems": 1, "maxItems": 10000, "items": {"$ref": "#/$defs/mapping"}}
+      }
+    }
+  }
+}