@opengsd/gsd-path 1.4.0 → 1.6.0

package/skills/gsd-path-inspect/scripts/detect_project.py

@@ -55,10 +55,22 @@ try:
         fcntl.flock(fd, fcntl.LOCK_EX)
 
 except ImportError:  # Windows does not provide POSIX file locks.
+    import errno
     import msvcrt
+    import time
 
     def lock_exclusive(fd: int) -> None:
-        msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
+        delay = 0.01
+        while True:
+            try:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                return
+            except OSError as error:
+                if error.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+                    raise
+                time.sleep(delay)
+                delay = min(delay * 2, 0.25)
 
 
 IGNORE_DIRS = {
@@ -217,16 +229,20 @@ HTML_BLOCK_START = re.compile(
     re.IGNORECASE,
 )
 REPARSE_NAME_SURROGATE = 0x20000000
-ANCHORED_EVIDENCE_SUPPORTED = (
+_POSIX_ANCHORED_EVIDENCE_SUPPORTED = (
     hasattr(os, "O_DIRECTORY")
     and hasattr(os, "O_NOFOLLOW")
     and os.open in os.supports_dir_fd
     and os.stat in os.supports_dir_fd
     and os.stat in os.supports_follow_symlinks
 )
+WINDOWS_ANCHORED_EVIDENCE_SUPPORTED = os.name == "nt"
+ANCHORED_EVIDENCE_SUPPORTED = (
+    _POSIX_ANCHORED_EVIDENCE_SUPPORTED or WINDOWS_ANCHORED_EVIDENCE_SUPPORTED
+)
 LISTDIR_DIR_FD_SUPPORTED = os.listdir in getattr(os, "supports_fd", ())
 ANCHORED_STATE_CREATE_SUPPORTED = (
-    ANCHORED_EVIDENCE_SUPPORTED
+    _POSIX_ANCHORED_EVIDENCE_SUPPORTED
     and LISTDIR_DIR_FD_SUPPORTED
     and os.mkdir in getattr(os, "supports_dir_fd", ())
     and os.unlink in getattr(os, "supports_dir_fd", ())
@@ -269,11 +285,12 @@ def is_link_like_status(status: os.stat_result) -> bool:
 def is_link_like(path: Path, status: os.stat_result) -> bool:
     if is_link_like_status(status):
         return True
-    isjunction = getattr(os.path, "isjunction", None)
-    if os.name != "nt" or isjunction is None:
+    if os.name != "nt":
         return False
     try:
-        return bool(isjunction(path))
+        return is_link_like_status(os.lstat(path))
+    except FileNotFoundError:
+        return False
     except OSError as error:
         raise DetectError(f"cannot inspect link-like evidence: {path}: {error}") from error
 
@@ -332,7 +349,7 @@ def is_managed_pipeline_directory(relative: str, root: Path) -> bool:
     return is_verified_skill_bundle(relative, root)
 
 
-def is_verified_skill_bundle_at(relative: str, directory_fd: int) -> bool:
+def is_verified_skill_bundle_at(relative: str, directory_fd: int, root: Path) -> bool:
     parts = PurePosixPath(relative).parts
     if not parts:
         return False
@@ -342,19 +359,45 @@ def is_verified_skill_bundle_at(relative: str, directory_fd: int) -> bool:
         return False
     if is_verified_installer_bundle(parts):
         return True
+    if _POSIX_ANCHORED_EVIDENCE_SUPPORTED:
+        try:
+            status = os.stat(
+                "SKILL.md",
+                dir_fd=directory_fd,
+                follow_symlinks=False,
+            )
+        except FileNotFoundError:
+            return False
+        except OSError as error:
+            raise DetectError(
+                f"cannot inspect managed skill bundle: {relative}: {error}"
+            ) from error
+        return not is_link_like_status(status) and stat.S_ISREG(status.st_mode)
+    skill_fd = None
     try:
-        status = os.stat(
+        win = get_windows_handles()
+        skill_fd = win.open_relative(
+            directory_fd,
             "SKILL.md",
-            dir_fd=directory_fd,
-            follow_symlinks=False,
+            _FILE_READ_ATTRIBUTES,
+            _PIN_SHARE,
+            _FILE_OPEN,
+            0,
         )
+        status = os.fstat(skill_fd)
     except FileNotFoundError:
         return False
     except OSError as error:
+        if getattr(error, "winerror", None) == 2:
+            return False
         raise DetectError(
             f"cannot inspect managed skill bundle: {relative}: {error}"
         ) from error
-    return not is_link_like_status(status) and stat.S_ISREG(status.st_mode)
+    finally:
+        if skill_fd is not None:
+            os.close(skill_fd)
+    skill = root.joinpath(*parts) / "SKILL.md"
+    return not is_link_like(skill, status) and stat.S_ISREG(status.st_mode)
 
 
 def is_fixed_managed_pipeline_artifact(relative: str) -> bool:
@@ -423,13 +466,20 @@ def read_regular_evidence(
         ) from error
     if not relative.parts:
         raise DetectError(f"{evidence_name} evidence path is empty: {path}")
-    if ANCHORED_EVIDENCE_SUPPORTED:
+    if _POSIX_ANCHORED_EVIDENCE_SUPPORTED:
         return read_anchored_evidence(
             relative,
             root,
             missing_ok=missing_ok,
             evidence_name=evidence_name,
         )
+    if WINDOWS_ANCHORED_EVIDENCE_SUPPORTED:
+        return read_windows_anchored_evidence(
+            relative,
+            root,
+            missing_ok=missing_ok,
+            evidence_name=evidence_name,
+        )
     return read_lstat_open_evidence(
         relative,
         root,
@@ -447,6 +497,17 @@ def directory_flags() -> int:
     )
 
 
+def listdir_anchored(dir_fd: int) -> list[str]:
+    """List names through a fresh directory descriptor under dir_fd."""
+    fresh = os.open(".", directory_flags(), dir_fd=dir_fd)
+    try:
+        if not os.path.samestat(os.fstat(fresh), os.fstat(dir_fd)):
+            raise DetectError("anchored directory listing lost its identity")
+        return os.listdir(fresh)
+    finally:
+        os.close(fresh)
+
+
 def file_flags() -> int:
     return (
         os.O_RDONLY
@@ -766,9 +827,12 @@ def raise_walk_error(error: OSError) -> None:
 
 
 def iter_worktree_files(root: Path) -> Iterable[str]:
-    if ANCHORED_EVIDENCE_SUPPORTED and LISTDIR_DIR_FD_SUPPORTED:
+    if _POSIX_ANCHORED_EVIDENCE_SUPPORTED and LISTDIR_DIR_FD_SUPPORTED:
         yield from iter_worktree_files_anchored(root)
         return
+    if WINDOWS_ANCHORED_EVIDENCE_SUPPORTED:
+        yield from iter_worktree_files_windows_anchored(root)
+        return
     for dirpath, dirnames, filenames in os.walk(
         root,
         followlinks=False,
@@ -826,7 +890,7 @@ def iter_from_dir_fd(
     dir_fd: int, relative_dir: str, root: Path
 ) -> Iterable[str]:
     try:
-        names = os.listdir(dir_fd)
+        names = listdir_anchored(dir_fd)
     except OSError as error:
         raise DetectError(f"cannot traverse filesystem evidence: {error}") from error
     for name in names:
@@ -862,7 +926,7 @@ def iter_from_dir_fd(
                     raise DetectError(
                         f"filesystem evidence changed while traversing: {relative}"
                     )
-                if is_verified_skill_bundle_at(relative, child):
+                if is_verified_skill_bundle_at(relative, child, root):
                     continue
                 yield from iter_from_dir_fd(child, relative, root)
             finally:
@@ -1227,10 +1291,17 @@ def project_slug(root: Path) -> str:
     return slug or "project"
 
 
-def filled_state_template(template: str, slug: str, phase: str) -> str:
+def filled_state_template(
+    template: str, slug: str, phase: str, default_branch: str = "main"
+) -> str:
     if "<slug>" not in template:
         raise DetectError("state template missing slug placeholder")
     text = template.replace("<slug>", slug)
+    text, count = re.subn(
+        r"(?m)^default_branch: main\b", lambda _: f"default_branch: {default_branch}", text, count=1
+    )
+    if count != 1:
+        raise DetectError("state template missing default_branch: main line")
     text, count = re.subn(r"(?m)^phase: define\b", f"phase: {phase}", text, count=1)
     if count != 1:
         raise DetectError("state template missing phase: define line")
@@ -1302,7 +1373,7 @@ def close_file_descriptors(
 
 def project_entries(project_fd: int, project: Path) -> set:
     """Names in .project without ignored OS junk (Finder may add .DS_Store at any time)."""
-    entries = set(os.listdir(project_fd))
+    entries = set(listdir_anchored(project_fd))
     for name in entries & _common.OS_JUNK_NAMES:
         try:
             status = os.stat(name, dir_fd=project_fd, follow_symlinks=False)
@@ -1413,12 +1484,12 @@ def write_state_anchored(
                 follow_symlinks=False,
             )
         except FileNotFoundError as error:
-            if "STATE.md" in os.listdir(project_fd):
+            if "STATE.md" in listdir_anchored(project_fd):
                 raise DetectError("STATE.md already exists") from error
             raise DetectError("temporary STATE.md disappeared") from error
         if not os.path.samestat(created_status, named_temporary):
             raise DetectError("temporary STATE.md changed before writing")
-        if "STATE.md" in os.listdir(project_fd):
+        if "STATE.md" in listdir_anchored(project_fd):
             raise DetectError("STATE.md already exists")
         os.ftruncate(state_fd, 0)
         write_all(state_fd, payload)
@@ -1653,6 +1724,167 @@ class _WindowsHandles:
             raise ctypes.WinError(ctypes.get_last_error())
 
 
+_WINDOWS_HANDLES: Optional[_WindowsHandles] = None
+
+
+def get_windows_handles() -> _WindowsHandles:
+    global _WINDOWS_HANDLES
+    if _WINDOWS_HANDLES is None:
+        _WINDOWS_HANDLES = _WindowsHandles()
+    return _WINDOWS_HANDLES
+
+
+def _windows_missing_ok(error: OSError) -> bool:
+    return getattr(error, "winerror", None) in {2, 3}
+
+
+def read_windows_anchored_evidence(
+    relative: Path,
+    root: Path,
+    *,
+    missing_ok: bool,
+    evidence_name: str,
+) -> Optional[str]:
+    win = get_windows_handles()
+    descriptors: list[int] = []
+    try:
+        descriptors.append(win.open_root(root))
+        opened_root = os.fstat(descriptors[-1])
+        if not stat.S_ISDIR(opened_root.st_mode):
+            raise DetectError(f"repo evidence is not a directory: {root}")
+        for index, part in enumerate(relative.parts):
+            current = root.joinpath(*relative.parts[: index + 1])
+            final = index == len(relative.parts) - 1
+            access = _GENERIC_READ if final else _DIRECTORY_ACCESS
+            options = _FILE_NON_DIRECTORY_FILE if final else _FILE_DIRECTORY_FILE
+            try:
+                descriptor = win.open_relative(
+                    descriptors[-1],
+                    part,
+                    access,
+                    _PIN_SHARE,
+                    _FILE_OPEN,
+                    options,
+                )
+            except OSError as error:
+                if missing_ok and _windows_missing_ok(error):
+                    return None
+                raise DetectError(
+                    f"filesystem evidence disappeared: {root / relative}"
+                ) from error
+            descriptors.append(descriptor)
+            actual = os.fstat(descriptor)
+            if is_link_like(current, actual):
+                raise DetectError(
+                    f"link-like {evidence_name} evidence is not allowed: {current}"
+                )
+            if final and not stat.S_ISREG(actual.st_mode):
+                raise DetectError(
+                    f"{evidence_name} evidence is not a regular file: {current}"
+                )
+            if not final and not stat.S_ISDIR(actual.st_mode):
+                raise DetectError(
+                    f"{evidence_name} evidence parent is not a directory: {current}"
+                )
+        with os.fdopen(descriptors.pop(), "rb") as stream:
+            data = stream.read()
+    except DetectError:
+        raise
+    except OSError as error:
+        raise DetectError(
+            f"cannot read {evidence_name} evidence: {root / relative}"
+        ) from error
+    finally:
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise DetectError(
+            f"cannot read {evidence_name} evidence: {root / relative}"
+        ) from error
+
+
+def iter_worktree_files_windows_anchored(root: Path) -> Iterable[str]:
+    win = get_windows_handles()
+    try:
+        root_fd = win.open_root(root)
+    except OSError as error:
+        raise DetectError(f"cannot traverse filesystem evidence: {error}") from error
+    try:
+        root_status = os.fstat(root_fd)
+        if not stat.S_ISDIR(root_status.st_mode):
+            raise DetectError(f"repo evidence is not a directory: {root}")
+        yield from iter_from_windows_dir_fd(root_fd, "", root, win)
+    finally:
+        os.close(root_fd)
+
+
+def iter_from_windows_dir_fd(
+    dir_fd: int, relative_dir: str, root: Path, win: _WindowsHandles
+) -> Iterable[str]:
+    scan_dir = root if not relative_dir else root.joinpath(*PurePosixPath(relative_dir).parts)
+    try:
+        # Windows CPython cannot listdir(dir_fd); paths come from the pinned walk.
+        names = os.listdir(scan_dir)
+    except OSError as error:
+        raise DetectError(f"cannot traverse filesystem evidence: {error}") from error
+    for name in names:
+        relative = f"{relative_dir}/{name}" if relative_dir else name
+        if is_ignored(relative) or name == ".project":
+            continue
+        path = root.joinpath(*PurePosixPath(relative).parts)
+        try:
+            child_fd = win.open_relative(
+                dir_fd,
+                name,
+                _DIRECTORY_ACCESS,
+                _PIN_SHARE,
+                _FILE_OPEN,
+                _FILE_DIRECTORY_FILE,
+            )
+        except OSError:
+            child_fd = None
+        else:
+            status = os.fstat(child_fd)
+            if is_link_like(path, status):
+                os.close(child_fd)
+                continue
+            if stat.S_ISDIR(status.st_mode):
+                try:
+                    if is_verified_skill_bundle_at(relative, child_fd, root):
+                        continue
+                    yield from iter_from_windows_dir_fd(
+                        child_fd, relative, root, win
+                    )
+                finally:
+                    os.close(child_fd)
+                continue
+            os.close(child_fd)
+        try:
+            file_fd = win.open_relative(
+                dir_fd,
+                name,
+                _FILE_READ_ATTRIBUTES,
+                _PIN_SHARE,
+                _FILE_OPEN,
+                _FILE_NON_DIRECTORY_FILE,
+            )
+        except OSError as error:
+            raise DetectError(
+                f"cannot inspect filesystem evidence: {relative}: {error}"
+            ) from error
+        try:
+            status = os.fstat(file_fd)
+            if is_link_like(path, status) or not stat.S_ISREG(status.st_mode):
+                continue
+            if is_fixed_managed_pipeline_artifact(relative):
+                continue
+            yield relative
+        finally:
+            os.close(file_fd)
+
+
 def windows_project_entries(project: Path) -> set:
     """project_entries for a .project held open without delete sharing."""
     entries = set(os.listdir(project))
@@ -1805,6 +2037,14 @@ def initialize(
         )
         if git.returncode != 0 or git.stdout.strip() != "true":
             return {**payload, "route": "setup-repository", "wrote_state": False}
+    default_branch = _common.origin_default_branch(root)
+    if not _common.valid_default_branch(default_branch):
+        return {**payload, "wrote_state": False, "error": (
+            f"origin default branch {default_branch!r} cannot be recorded in STATE.md: "
+            "it is a GSD Path reserved name or it has a character that STATE frontmatter "
+            "cannot hold. Rename the default branch, then run "
+            "`git remote set-head origin --auto`."
+        )}
     expected = "inspect" if payload["verdict"] == "brownfield" else "define"
     if phase is None:
         phase = expected
@@ -1818,7 +2058,7 @@ def initialize(
         return payload
     write_state_anchored(
         root,
-        filled_state_template(raw, project_slug(root), phase),
+        filled_state_template(raw, project_slug(root), phase, default_branch),
         root_status,
         project_status,
     )

package/skills/gsd-path-inspect/scripts/discussion_records.py

@@ -7,6 +7,7 @@ import json
 import os
 import shutil
 import sys
+import traceback
 
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
@@ -33,7 +34,7 @@ def _load_pipeline_modules():
     try:
         from scripts import archive_milestone, pipeline_state, _common
         return _common, archive_milestone, pipeline_state
-    except ModuleNotFoundError as error:
+    except ImportError as error:  # a foreign `scripts` package
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
@@ -41,6 +42,13 @@ def _load_pipeline_modules():
             "scripts._common",
         }:
             raise
+        # A plain ImportError raised while a `scripts` module loaded is not a
+        # foreign package. A missing module falls back, as before.
+        if not isinstance(error, ModuleNotFoundError) and any(
+            frame.f_globals.get("__name__", "").startswith("scripts.")
+            for frame, _ in traceback.walk_tb(error.__traceback__)
+        ):
+            raise
         shared_scripts = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared_scripts))
         import archive_milestone