unaltraweb 0.3.0 → 0.5.0

data/scripts/manual/filters/figure-captions.lua

@@ -4,22 +4,53 @@ local function append_all(destination, values)
   end
 end
 
-function Figure(figure)
-  if not FORMAT:match("latex") or #figure.caption.long == 0 then
-    return nil
-  end
-
-  local caption = {pandoc.RawInline("latex", "\\caption{")}
-  for index, block in ipairs(figure.caption.long) do
+local function caption_inlines(caption)
+  local result = pandoc.Inlines({})
+  for index, block in ipairs(caption.long) do
     if index > 1 then
-      table.insert(caption, pandoc.Space())
+      table.insert(result, pandoc.Space())
     end
     if block.content then
-      append_all(caption, block.content)
+      append_all(result, block.content)
     else
-      table.insert(caption, pandoc.Str(pandoc.utils.stringify(block)))
+      table.insert(result, pandoc.Str(pandoc.utils.stringify(block)))
+    end
+  end
+  return result
+end
+
+local function description_only(inlines)
+  local has_source = false
+  local description = inlines:walk({
+    Span = function(span)
+      if span.classes:includes("uw-caption-source") then
+        has_source = true
+        return {}
+      end
     end
+  })
+  while #description > 0 and (description[#description].t == "Space" or description[#description].t == "SoftBreak") do
+    table.remove(description)
+  end
+  return description, has_source
+end
+
+local function figure_caption(figure)
+  if not FORMAT:match("latex") or #figure.caption.long == 0 then
+    return nil
+  end
+
+  local full = caption_inlines(figure.caption)
+  local short, has_source = description_only(full)
+  local caption = {}
+  if has_source then
+    table.insert(caption, pandoc.RawInline("latex", "\\caption[{"))
+    append_all(caption, short)
+    table.insert(caption, pandoc.RawInline("latex", "}]{"))
+  else
+    table.insert(caption, pandoc.RawInline("latex", "\\caption{"))
   end
+  append_all(caption, full)
   table.insert(caption, pandoc.RawInline("latex", "}"))
   if figure.identifier and figure.identifier ~= "" then
     table.insert(caption, pandoc.RawInline("latex", "\\label{" .. figure.identifier .. "}"))
@@ -33,3 +64,27 @@ function Figure(figure)
   table.insert(blocks, pandoc.RawBlock("latex", "\\end{figure}"))
   return blocks
 end
+
+local function table_caption(element)
+  if not FORMAT:match("latex") then
+    return nil
+  end
+  local short, has_source = description_only(caption_inlines(element.caption))
+  if has_source then
+    element.caption.short = short
+    return element
+  end
+end
+
+local function source_style(span)
+  if FORMAT:match("latex") and span.classes:includes("uw-caption-source") then
+    local inlines = {pandoc.RawInline("latex", "{\\itshape ")}
+    append_all(inlines, span.content)
+    table.insert(inlines, pandoc.RawInline("latex", "}"))
+    return inlines
+  end
+end
+
+-- Preserve semantic credit spans until short captions have been computed.
+-- Citeproc runs before this filter, including citations inside the spans.
+return {{Figure = figure_caption, Table = table_caption}, {Span = source_style}}

data/scripts/manual/templates/manual.tex

@@ -44,6 +44,10 @@
 \displaywidowpenalty=10000
 \setcounter{secnumdepth}{3}
 \setcounter{tocdepth}{2}
+\makeatletter
+\renewcommand*{\l@section}{\@dottedtocline{1}{1.5em}{3em}}
+\renewcommand*{\l@subsection}{\@dottedtocline{2}{4.5em}{4em}}
+\makeatother
 \pretocmd{\section}{\Needspace{6\baselineskip}}{}{}
 \pretocmd{\subsection}{\Needspace{5\baselineskip}}{}{}
 \pretocmd{\subsubsection}{\Needspace{5\baselineskip}}{}{}
@@ -81,7 +85,8 @@
   singlelinecheck=false
 }
 \captionsetup[figure]{position=top,margin=1em,aboveskip=0pt,belowskip=7pt}
-\captionsetup[table]{position=top,margin=1em,aboveskip=0pt,belowskip=7pt}
+% longtable uses the caption skip below a top caption; belowskip alone is ignored.
+\captionsetup[table]{position=top,margin=1em,skip=7pt}
 \captionsetup[lstlisting]{position=top,margin=0pt,aboveskip=0pt,belowskip=7pt}
 \captionsetup[subfigure]{
   font={manualsubcaption,color=ManualMuted},

data/scripts/test_gem_build.py

@@ -23,7 +23,7 @@ CONTRACT = json.loads((ROOT / "src/unaltraweb_mcp/component-contract.json").read
 RUNTIME_IMAGE = str(CONTRACT["components"]["runtime"]["reference"])
 
 
-def run(command: list[str], *, cwd: Path = ROOT) -> subprocess.CompletedProcess[str]:
+def run(command: list[str], *, cwd: Path = ROOT, expected: int = 0) -> subprocess.CompletedProcess[str]:
     completed = subprocess.run(
         command,
         cwd=cwd,
@@ -32,7 +32,7 @@ def run(command: list[str], *, cwd: Path = ROOT) -> subprocess.CompletedProcess[
         stderr=subprocess.PIPE,
         check=False,
     )
-    if completed.returncode != 0:
+    if completed.returncode != expected:
         raise RuntimeError(f"Command failed: {' '.join(command)}\n{completed.stdout}\n{completed.stderr}")
     return completed
 
@@ -61,12 +61,16 @@ 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",
+                                          "src/unaltraweb_mcp/image_probe.py", "src/unaltraweb_mcp/processes.py"]
     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())
+            editorial_bytes = {name: payload.extractfile(name).read() for name in inspection_files}
     required = {
         "LICENSE",
         "README.md",
@@ -97,6 +101,7 @@ def inspect_gem(path: Path) -> None:
         "src/unaltraweb_mcp/component-contract.json",
         "src/unaltraweb_mcp/component-contract.schema.json",
         "src/unaltraweb_mcp/docker_mount.py",
+        *inspection_files,
     }
     missing = sorted(required - names)
     if missing:
@@ -104,6 +109,31 @@ def inspect_gem(path: Path) -> None:
     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}")
+    # Exercise only the actual gem payload with isolated Python: no factory,
+    # wheel, inherited PYTHONPATH, source checkout or MCP dependency may help.
+    with tempfile.TemporaryDirectory(prefix="unaltraweb-gem-editorial-") as temporary:
+        core = Path(temporary) / "core"
+        for name, content in editorial_bytes.items():
+            target = core / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(content)
+        site = Path(temporary) / "site"
+        (site / "_pages/en").mkdir(parents=True)
+        (site / "_config.yml").write_text("unaltraweb:\n  site_profile: unaltreselfie\n", encoding="utf-8")
+        page = site / "_pages/en/about.md"
+        page.write_text("I study spatial data.\n", encoding="utf-8")
+        command = [sys.executable, "-I", str(core / editorial_files[0]), "--project", str(site)]
+        if not json.loads(run(command, cwd=site).stdout)["ok"]:
+            raise RuntimeError("Gem-native editorial check rejected publication copy.")
+        page.write_text("As requested, I have added the biography.\n", encoding="utf-8")
+        if json.loads(run(command, cwd=site, expected=1).stdout)["ok"]:
+            raise RuntimeError("Gem-native editorial gate accepted chat-dependent copy.")
+        (site / "assets").mkdir()
+        (site / "assets/test.svg").write_text('<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><circle cx="5" cy="5" r="2" fill="blue"/></svg>', encoding="utf-8")
+        image_command = [sys.executable, "-I", str(core / "scripts/image_background_check.py"), "--project", str(site), "--source", "assets/test.svg"]
+        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}")
 
 
 def main() -> int:

data/scripts/test_reproducible_jekyll_build.py

@@ -13,7 +13,7 @@ from pathlib import Path
 
 
 ROOT = Path(__file__).resolve().parents[1]
-IMAGE = os.environ.get("DOCKER_IMAGE", "ghcr.io/dosquartsdedocs/unaltraweb:0.3.0")
+IMAGE = os.environ.get("DOCKER_IMAGE", "ghcr.io/dosquartsdedocs/unaltraweb:0.5.0")
 SELECTOR = "v2026.09"
 EPOCH = "946684800"
 

data/scripts/test_wheel_install.py

@@ -73,7 +73,12 @@ def main() -> int:
             "unaltraweb_mcp/calibre_import.py",
             "unaltraweb_mcp/component-contract.json",
             "unaltraweb_mcp/component-contract.schema.json",
+            "unaltraweb_mcp/manual_pdf_preview.py",
             "unaltraweb_mcp/manual_release.py",
+            "unaltraweb_mcp/editorial.py",
+            "unaltraweb_mcp/editorial_sources.py",
+            "unaltraweb_mcp/image_backgrounds.py",
+            "unaltraweb_mcp/image_probe.py",
             "unaltraweb_mcp/scaffolds/common/AGENTS.md.tmpl",
             "unaltraweb_mcp/scaffolds/common/Makefile.tmpl",
             "unaltraweb_mcp/scaffolds/common/README.md.tmpl",
@@ -123,6 +128,7 @@ def main() -> int:
             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")
+            agents = (profile_site / "AGENTS.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")
@@ -132,7 +138,7 @@ def main() -> int:
                 f"**`{profile}`** profile: {description}",
                 f"## Editable Content For `{profile}`",
                 profile_path,
-                "only one active editor per file",
+                "only one active editing session per repository",
                 "Never edit or commit directly to `main`",
                 "Draft pull request",
                 "Starts the deploy workflow manually",
@@ -146,6 +152,18 @@ def main() -> int:
                 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")
+            agent_markers = [
+                "read-only checkout preflight",
+                "primary mutable checkout",
+                "process-held cooperative lease",
+                "`exec` wrapper",
+                "one active editing session per repository",
+                "one top-level MCP",
+                "declared dependency closure",
+                "`MCP_CONSUMER_WORKSPACE`",
+            ]
+            if any(value not in agents for value in agent_markers):
+                raise RuntimeError(f"generated {profile} agent contract lacks single-checkout guidance")
             collaboration_markers = [
                 "content/<issue>-<slug>",
                 "reference/<issue>-<slug>",
@@ -158,20 +176,37 @@ def main() -> int:
                 "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 active editing session per repository",
+                "primary mutable checkout",
+                "read-only checkout preflight",
+                "process-held cooperative lease",
+                "`exec` wrapper",
+                "Never create, switch to, move, prune, repair, or remove Git worktrees implicitly",
+                "one top-level MCP",
+                "declared dependency closure",
+                "`MCP_CONSUMER_WORKSPACE`",
+                "factory `build`, `check`, and `smoke` operations",
                 "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",
+                "retain the primary checkout",
             ]
             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
+            combined_guidance = readme + collaboration + pr_template + agents
+            obsolete_guidance = [
+                "dedicated Git worktree",
+                "Never share a mutable checkout",
+                "remove the worktree",
+                "one active editor per file",
+                "no other active editor",
+            ]
+            if any(value in combined_guidance for value in obsolete_guidance):
+                raise RuntimeError(f"generated {profile} guidance retains obsolete worktree coordination")
             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")
@@ -198,6 +233,7 @@ def main() -> int:
                 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")
+            makefile = (profile_site / "Makefile").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")
@@ -207,6 +243,16 @@ def main() -> int:
                 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")
+            makefile_markers = [
+                f"MANUAL_PDF_IMAGE ?= {integration['manual_pdf_image']}",
+                "manual-pdf-preview-prepare: runtime-image",
+                "manual-pdf-preview-clean: runtime-image",
+                "build: manual-pdf-preview-prepare",
+                "serve: manual-pdf-preview-prepare",
+                "test: manual-pdf-preview-prepare",
+            ]
+            if any(value not in makefile for value in makefile_markers):
+                raise RuntimeError(f"generated {profile} Makefile lacks managed manual PDF preview staging")
             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"))
@@ -224,6 +270,9 @@ def main() -> int:
             if set(manifest["files"]) != expected_managed:
                 raise RuntimeError(f"generated {profile} scaffold baseline is incomplete: {manifest['files']}")
             sites[profile] = profile_site
+            checked = json.loads(run([str(cli), "--project", str(profile_site), "mcp", "prose-check"], cwd=temp).stdout)
+            if not checked["ok"] or checked["profile"] != profile:
+                raise RuntimeError(f"Package-only editorial check failed for {profile}: {checked}")
 
         site = sites["unaltredocs"]
         if not (site / ".unaltraweb/scaffold.json").is_file():
@@ -253,6 +302,9 @@ def main() -> int:
         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}")
+        backgrounds = json.loads(run([str(cli), "--project", str(site), "mcp", "image-background-check"], cwd=temp).stdout)
+        if not backgrounds["ok"] or not backgrounds["read_only"]:
+            raise RuntimeError(f"Factory-free background inspection failed: {backgrounds}")
         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}")
@@ -270,6 +322,24 @@ def main() -> int:
         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}")
+        context = json.loads(run([str(cli), "--project", str(site), "mcp", "site-context"], cwd=temp).stdout)
+        if context["update_status"]["state"] != "current" or context["update_status"]["can_apply"]:
+            raise RuntimeError(f"wheel consumer update advisory failed: {context['update_status']}")
+        prepared = json.loads(run([str(cli), "--project", str(site), "mcp", "editorial-review-prepare"], cwd=temp).stdout)
+        report = {"id": "wheel-review", "source_digest": prepared["source_digest"], "reviewer": "Wheel smoke", "findings": []}
+        recorded = json.loads(run([
+            str(cli), "--project", str(site), "mcp", "editorial-review-record",
+            "--report-json", json.dumps(report), "--expected-revision", "0",
+        ], cwd=temp).stdout)
+        editorial = json.loads(run([str(cli), "--project", str(site), "mcp", "editorial-status"], cwd=temp).stdout)
+        if recorded["revision"] != 1 or editorial["reviews"]["wheel-review"]["stale"]:
+            raise RuntimeError("Factory-free wheel did not preserve a fresh editorial review.")
+        confirmed = json.loads(run([
+            str(cli), "--project", str(site), "mcp", "scaffold-sync", "--apply", "--confirm-sync",
+            "--expected-plan-sha256", scaffold["plan_sha256"],
+        ], cwd=temp).stdout)
+        if not confirmed["ok"] or not confirmed["applied"]:
+            raise RuntimeError(f"wheel reviewed scaffold synchronization failed: {confirmed}")
 
         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:

data/scripts/unaltraweb-mcp-bootstrap.sh

@@ -10,7 +10,7 @@ If --project is omitted, MCP_CONSUMER_WORKSPACE is used, then the current direct
 USAGE
 }
 
-image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0}"
+image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0}"
 project="${MCP_CONSUMER_WORKSPACE:-${UNALTRAWEB_PROJECT:-}}"
 
 while [ "$#" -gt 0 ]; do
@@ -62,6 +62,24 @@ project_id="$(/bin/sh "$script_dir/unaltraweb-mcp-project-id.sh" "$project")"
 workspace_mount="$(/bin/sh "$script_dir/unaltraweb-docker-mount.sh" "$project" /workspace)"
 mirror_mount="$(/bin/sh "$script_dir/unaltraweb-docker-mount.sh" "$project" "$project")"
 
+if [ -S "$docker_socket" ]; then
+  unresolved_socket="$docker_socket"
+  if ! docker_socket="$(realpath -e -- "$unresolved_socket")"; then
+    printf '%s\n' "Cannot resolve Docker socket: $unresolved_socket" >&2
+    exit 1
+  fi
+  if [ "$(stat -c '%h' "$docker_socket")" != 1 ]; then
+    printf '%s\n' 'UNALTRAWEB_DOCKER_SOCKET must not have hard-link aliases that could enter the consumer project.' >&2
+    exit 1
+  fi
+  case "$docker_socket" in
+    "$project"|"$project"/*)
+      printf '%s\n' 'UNALTRAWEB_DOCKER_SOCKET must be outside the consumer project so the persistent preview cannot inherit it.' >&2
+      exit 1
+      ;;
+  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")"

data/scripts/validate_distribution.py

@@ -71,6 +71,23 @@ def make_value(path: Path, variable: str) -> str:
     return match.group(1).strip('"\'') if match else ""
 
 
+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"}
+    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"
+                and selected["release_status"] == "released"):
+            # Digest/repository/version-tag semantics remain independently checked
+            # by component_contract_semantic_errors; this is not a mutable fallback.
+            continue
+        if str(selected["version"]) != version:
+            errors.append(f"{component_id} version does not match release {version}")
+    return errors
+
+
 def validate(root: Path = ROOT) -> list[str]:
     errors: list[str] = []
     contract = distribution_contract()
@@ -87,9 +104,7 @@ def validate(root: Path = ROOT) -> list[str]:
         errors.append("release-candidates.json must be excluded from Docker build contexts")
     if __version__ != version:
         errors.append(f"wheel version {__version__} != contract version {version}")
-    for component_id in ["gem", "wheel", "runtime", "mcp", "compute_python", "compute_r", "web_capture", "manual_pdf"]:
-        if str(contract["components"][component_id]["version"]) != version:
-            errors.append(f"{component_id} version does not match release {version}")
+    errors.extend(component_version_errors(contract))
     included = {name for name, item in contract["components"].items() if item["included_in_wheel"]}
     if included != {"wheel"}:
         errors.append(f"wheel must not bundle external components: {sorted(included)}")
@@ -241,7 +256,7 @@ def validate(root: Path = ROOT) -> list[str]:
     scaffold_templates = {
         "Gemfile.tmpl": ["__GEM_VERSION__", "__CORE_REPOSITORY__", "__CORE_SHA__"],
         "Gemfile.lock.tmpl": ["__GEM_VERSION__", "__CORE_REPOSITORY__", "__CORE_SHA__"],
-        "Makefile.tmpl": ["__MCP_IMAGE__"],
+        "Makefile.tmpl": ["__MCP_IMAGE__", "__MANUAL_PDF_IMAGE__"],
         ".github/workflows/deploy.yml.tmpl": [
             "__SITE_DEPLOY_WORKFLOW__",
             "__CORE_SHA__",