@mriekki/lean 0.4.5 → 0.4.6

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "defaultProfile": "greenfield-poc",
   "profiles": {
     "greenfield-poc": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "68f3f45e663cab535c5a9544cf4efe2f048f8f34",
+      "commit": "52905468c06fe39caa491a15a77e33cd400a60d9",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "68f3f45e663cab535c5a9544cf4efe2f048f8f34",
+      "commit": "52905468c06fe39caa491a15a77e33cd400a60d9",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -192,7 +192,7 @@
         {
           "source": "core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
           "destination": "docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
-          "sha256": "e6697c8d9bc346e8c8229625fc422b869a6428a083e4fee717b97d17afde7b03"
+          "sha256": "8dc0773a245ed23089caa02a1a2f0dd5670710646d446d190406ae47a85da4c6"
         },
         {
           "source": "core/process/LEAN_ENGINEERING_GUIDE.md",
@@ -282,7 +282,7 @@
         {
           "source": "tools/docs_site/docs_site.py",
           "destination": "tools/lean-docs/docs-site.py",
-          "sha256": "d8516175150b48b85b2a0b8013d5790b78bdd6eb6de73ab8dce9ed8e32e2dc68"
+          "sha256": "50ea30f5d42f71176a74a642123089c6e246f2da616e0c0bba2f16168d2c15c9"
         },
         {
           "source": "tools/package/check_baseline.py",

package/assets/generated/core/core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md

@@ -190,6 +190,8 @@ Build-only mode:
 python .\tools\lean-docs\docs-site.py build --root . --out .\.lean\docs-site
 ```
 
+The builder protects existing data: it refuses the repository root, paths overlapping either lab cache, linked paths, and non-empty output directories without its `.lean-docs-site` ownership marker. Existing unmarked output from an older viewer must be inspected and moved or a new output path selected before rebuilding.
+
 The viewer should:
 
 - bind to loopback only;

package/assets/generated/core/tools/docs_site/docs_site.py

@@ -13,13 +13,15 @@ import webbrowser
 from datetime import datetime, timezone
 from functools import partial
 from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
-from pathlib import Path
+from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Any
 
 IGNORE_DIRS = {".git", ".lean", "node_modules", "bin", "obj", "dist", "build", "target", ".venv", "venv", "__pycache__"}
 DEFAULT_CACHE = Path(".lean/docs-cache")
 DEFAULT_SITE = Path(".lean/docs-site")
 MANIFEST = Path("docs/lean-docs.json")
+SITE_MARKER = ".lean-docs-site"
+SITE_MARKER_CONTENT = "lean-docs-site\n"
 
 
 class DocsSiteError(RuntimeError):
@@ -86,17 +88,30 @@ def _manifest_documents(root: Path, manifest: dict[str, Any] | None) -> tuple[li
             if not isinstance(item, dict) or not isinstance(item.get("path"), str):
                 warnings.append(f"docs/lean-docs.json documents[{index}] is invalid")
                 continue
-            rel = Path(item["path"]).as_posix().lstrip("/")
-            if rel.startswith("../") or "/../" in rel:
+            raw_path = item["path"]
+            windows_path = PureWindowsPath(raw_path)
+            relative_path = PurePosixPath(raw_path.replace("\\", "/"))
+            if (
+                relative_path.is_absolute()
+                or windows_path.root
+                or windows_path.drive
+                or ".." in relative_path.parts
+            ):
                 warnings.append(f"Skipped unsafe documentation path: {item['path']}")
                 continue
+            rel = relative_path.as_posix()
             path = root / rel
+            try:
+                resolved_path = root / _safe_rel(root, path)
+            except DocsSiteError:
+                warnings.append(f"Skipped unsafe documentation path: {item['path']}")
+                continue
             seen.add(rel)
-            if not path.is_file():
+            if not resolved_path.is_file():
                 if item.get("optional") is not True:
                     warnings.append(f"Listed documentation is not present: {rel}")
                 continue
-            content = path.read_text(encoding="utf-8", errors="replace")
+            content = resolved_path.read_text(encoding="utf-8", errors="replace")
             docs.append(
                 {
                     "path": rel,
@@ -116,14 +131,30 @@ def _manifest_documents(root: Path, manifest: dict[str, Any] | None) -> tuple[li
             candidates.append(path)
     docs_root = root / "docs"
     if docs_root.is_dir():
-        for base, dirs, names in os.walk(docs_root):
-            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS]
-            for name in names:
-                if name.lower().endswith(".md"):
-                    candidates.append(Path(base) / name)
+        if _path_contains_link(docs_root):
+            warnings.append(f"Skipped unsafe documentation directory: {docs_root}")
+        else:
+            for base, dirs, names in os.walk(docs_root):
+                safe_dirs = []
+                for directory in dirs:
+                    candidate = Path(base) / directory
+                    if directory in IGNORE_DIRS:
+                        continue
+                    if _is_link(candidate):
+                        warnings.append(f"Skipped unsafe documentation directory: {candidate}")
+                        continue
+                    safe_dirs.append(directory)
+                dirs[:] = safe_dirs
+                for name in names:
+                    if name.lower().endswith(".md"):
+                        candidates.append(Path(base) / name)
 
     for path in sorted(candidates):
-        rel = _safe_rel(root, path)
+        try:
+            rel = _safe_rel(root, path)
+        except DocsSiteError:
+            warnings.append(f"Skipped unsafe documentation path: {path}")
+            continue
         if rel in seen:
             continue
         content = path.read_text(encoding="utf-8", errors="replace")
@@ -220,14 +251,113 @@ def _prepare_system_lab(root: Path) -> str | None:
     return None
 
 
-def _copy_lab_cache(root: Path, out: Path, kind: str) -> None:
+def _validate_lab_cache(root: Path, kind: str) -> Path:
     source = root / DEFAULT_CACHE / kind
-    if not source.is_dir():
-        return
+    if _path_contains_link(source):
+        raise DocsSiteError(f"Lab cache contains a symlink or junction: {source}")
+    if source.exists():
+        try:
+            source.resolve().relative_to(root)
+        except ValueError as exc:
+            raise DocsSiteError(f"Lab cache escapes repository root: {source}") from exc
+    if source.is_dir() and _directory_contains_link(source):
+        raise DocsSiteError(f"Lab cache contains a symlink or junction: {source}")
+    return source
+
+
+def _copy_lab_cache(root: Path, out: Path, kind: str) -> None:
+    source = _validate_lab_cache(root, kind)
     target = out / "labs" / kind
+    try:
+        target.resolve().relative_to(out)
+    except ValueError as exc:
+        raise DocsSiteError(f"Lab output escapes generated site directory: {target}") from exc
+    if _path_contains_link(target):
+        raise DocsSiteError(f"Lab output contains a symlink or junction: {target}")
     if target.exists():
+        if target.is_symlink() or not target.is_dir():
+            raise DocsSiteError(f"Unexpected lab output path: {target}")
         shutil.rmtree(target)
-    shutil.copytree(source, target)
+    if source.is_dir():
+        shutil.copytree(source, target)
+
+
+def _is_link(path: Path) -> bool:
+    if path.is_symlink():
+        return True
+    is_junction = getattr(path, "is_junction", None)
+    return bool(is_junction and is_junction())
+
+
+def _path_contains_link(path: Path) -> bool:
+    absolute = Path(os.path.abspath(path))
+    current = Path(absolute.anchor)
+    for part in absolute.parts[1:]:
+        current /= part
+        if _is_link(current):
+            return True
+    return False
+
+
+def _paths_overlap(left: Path, right: Path) -> bool:
+    left = Path(os.path.abspath(left))
+    right = Path(os.path.abspath(right))
+    return left == right or left in right.parents or right in left.parents
+
+
+def _directory_contains_link(root: Path) -> bool:
+    directories = [root]
+    while directories:
+        current = directories.pop()
+        with os.scandir(current) as entries:
+            for entry in entries:
+                path = Path(entry.path)
+                if _is_link(path):
+                    return True
+                if entry.is_dir(follow_symlinks=False):
+                    directories.append(path)
+    return False
+
+
+def _prepare_output(root: Path, out: Path) -> None:
+    if _path_contains_link(out):
+        raise DocsSiteError(f"Refusing to use an output path containing a symlink or junction: {out}")
+    if out == root or out in root.parents:
+        raise DocsSiteError(f"Refusing to use the repository root or one of its parents as output: {out}")
+    for kind in ("system", "database"):
+        cache = root / DEFAULT_CACHE / kind
+        if _paths_overlap(out, cache):
+            raise DocsSiteError(f"Output path overlaps a lab cache: {cache}")
+
+    if out.exists():
+        if not out.is_dir():
+            raise DocsSiteError(f"Output path is not a directory: {out}")
+        marker = out / SITE_MARKER
+        if any(out.iterdir()):
+            if marker.is_symlink() or not marker.is_file():
+                raise DocsSiteError(f"Refusing to overwrite an unowned output directory: {out}")
+            try:
+                marker_content = marker.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise DocsSiteError(f"Unable to verify output ownership: {marker}") from exc
+            if marker_content != SITE_MARKER_CONTENT:
+                raise DocsSiteError(f"Refusing to overwrite an unowned output directory: {out}")
+
+        if _directory_contains_link(out):
+            raise DocsSiteError(f"Refusing to write through a symlink in output directory: {out}")
+
+        for name in (SITE_MARKER, "index.html", "site.json"):
+            path = out / name
+            if path.is_file():
+                try:
+                    link_count = path.stat().st_nlink
+                except OSError as exc:
+                    raise DocsSiteError(f"Unable to verify output file links: {path}") from exc
+                if link_count > 1:
+                    raise DocsSiteError(f"Refusing to overwrite hard-linked output file: {path}")
+
+    out.mkdir(parents=True, exist_ok=True)
+    (out / SITE_MARKER).write_text(SITE_MARKER_CONTENT, encoding="utf-8")
 
 
 def _site_payload(root: Path) -> dict[str, Any]:
@@ -299,16 +429,16 @@ document.querySelector('#siteTitle').textContent=SITE.title;document.querySelect
 
 def build(root: Path, out: Path, *, prepare_system_lab: bool = False) -> tuple[Path, dict[str, Any]]:
     root = root.resolve()
-    out = out.resolve()
+    out = Path(os.path.abspath(out))
     if not root.is_dir():
         raise DocsSiteError(f"Repository root does not exist: {root}")
+    for kind in ("system", "database"):
+        _validate_lab_cache(root, kind)
+    _prepare_output(root, out)
     prep_warning = _prepare_system_lab(root) if prepare_system_lab else None
     payload = _site_payload(root)
     if prep_warning:
         payload["warnings"].append(prep_warning)
-    if out.exists():
-        shutil.rmtree(out)
-    out.mkdir(parents=True, exist_ok=True)
     _copy_lab_cache(root, out, "system")
     _copy_lab_cache(root, out, "database")
     index = out / "index.html"
@@ -359,7 +489,7 @@ def parse_args() -> argparse.Namespace:
 def main() -> int:
     args = parse_args()
     root = args.root.resolve()
-    out = args.out.resolve() if args.out else (root / DEFAULT_SITE).resolve()
+    out = args.out if args.out else root / DEFAULT_SITE
     try:
         if args.command == "build":
             index, payload = build(root, out, prepare_system_lab=args.prepare_system_lab)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/lean",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Public consumer distribution and updater for Lean engineering assets.",
   "type": "module",
   "bin": {