@opengsd/gsd-path 1.0.0

package/scripts/check_task_briefs.py

@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Lint build task briefs against the layer base before dispatch."""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path, PurePosixPath
+from typing import Dict, List, Optional, Sequence, Set, Tuple
+
+try:
+    import _common
+except ImportError:  # pragma: no cover - package import used by tests
+    from scripts import _common
+
+
+DEFAULT_TASKS_DIR = ".project/tasks"
+REQUIRED_FIELDS = (
+    "id",
+    "title",
+    "wave",
+    "deps",
+    "status",
+    "agent",
+    "base",
+    "worktree",
+    "task_branch",
+    "files",
+)
+FORBIDDEN_FIELDS = ("commit",)
+REQUIRED_SECTIONS = (
+    "Context",
+    "Approach",
+    "Interface contract",
+    "Intent coverage",
+    "Acceptance criteria",
+    "Verify",
+    "Log",
+)
+PROSE_SECTIONS = ("Context", "Approach", "Interface contract")
+FIELD_PATTERN = _common.FIELD_PATTERN
+INLINE_LIST_PATTERN = _common.INLINE_LIST_PATTERN
+LIST_ITEM_PATTERN = _common.LIST_ITEM_PATTERN
+HEADING_PATTERN = re.compile(r"(?m)^## (?P<name>.+?)\s*$")
+COMMENT_PATTERN = re.compile(r"<!--.*?-->", re.DOTALL)
+BACKTICK_PATTERN = re.compile(r"`([^`\n]+)`")
+PATH_TOKEN_PATTERN = re.compile(r"[A-Za-z0-9._~/-]+")
+VERIFY_BLOCK_PATTERN = re.compile(r"```bash[ \t]*\n(?P<block>.*?)```", re.DOTALL)
+
+
+class BriefError(RuntimeError):
+    """Raised when task briefs fail the layer-prep lint or inputs are unusable."""
+
+
+_run_git = _common.run_git
+
+
+def _resolve_base(repo: Path, base: str) -> str:
+    result = _run_git(repo, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}")
+    if result.returncode != 0:
+        raise BriefError(f"--base does not resolve to a commit: {base}")
+    return result.stdout.strip()
+
+
+def _base_exists(repo: Path, base: str, path: str) -> bool:
+    return _run_git(repo, "cat-file", "-e", f"{base}:{path}").returncode == 0
+
+
+def _supplied_contract(repo: Path, task: Path, token: str) -> bool:
+    """Plan approval checkpoints these supplied inputs after the brief gate."""
+    track = task.parent.parent.relative_to(repo).as_posix()
+    if track not in {".project", ".project/next"}:
+        return False
+    if token not in {
+        f"{track}/intent/INTENT.md",
+        f"{track}/research/SYNTHESIS.md",
+    }:
+        return False
+    path = repo / token
+    return path.is_file() and path.resolve() == repo.resolve() / token
+
+
+_strip_yaml_comment = _common.strip_yaml_comment
+_unquote = _common.unquote
+
+
+def _frontmatter(text: str) -> Tuple[Optional[Dict[str, object]], Optional[str]]:
+    lines = text.splitlines()
+    if not lines or lines[0] != "---":
+        return None, "missing YAML frontmatter"
+    fields: Dict[str, object] = {}
+    index = 1
+    while index < len(lines):
+        line = lines[index]
+        if line == "---":
+            return fields, None
+        match = FIELD_PATTERN.match(line)
+        if match:
+            key = match.group("key")
+            if key in fields:
+                return None, f"frontmatter repeats field: {key}"
+            value = _strip_yaml_comment(match.group("value"))
+            inline = INLINE_LIST_PATTERN.fullmatch(value)
+            if inline is not None:
+                body = inline.group("body").strip()
+                fields[key] = [
+                    _unquote(item)
+                    for item in body.split(",")
+                    if item.strip()
+                ]
+                index += 1
+                continue
+            if value:
+                fields[key] = _unquote(value)
+                index += 1
+                continue
+            items: List[str] = []
+            cursor = index + 1
+            while cursor < len(lines):
+                item = LIST_ITEM_PATTERN.match(lines[cursor])
+                if not item:
+                    break
+                items.append(_unquote(item.group("value")))
+                cursor += 1
+            fields[key] = items
+            index = cursor
+            continue
+        if line.strip() and not line.lstrip().startswith("#"):
+            return None, f"malformed frontmatter line: {line}"
+        index += 1
+    return None, "frontmatter is not closed"
+
+
+def _sections(text: str) -> Dict[str, str]:
+    headings = list(HEADING_PATTERN.finditer(text))
+    sections: Dict[str, str] = {}
+    for position, heading in enumerate(headings):
+        end = headings[position + 1].start() if position + 1 < len(headings) else len(text)
+        sections[heading.group("name")] = text[heading.end() : end]
+    return sections
+
+
+def _clean(body: str) -> str:
+    return COMMENT_PATTERN.sub("", body).strip()
+
+
+def _looks_like_path(token: str) -> bool:
+    return (
+        "/" in token
+        and PATH_TOKEN_PATTERN.fullmatch(token) is not None
+        and "://" not in token
+        and not token.startswith(("-", "/"))  # /api/users is a route, not a repo path
+        and "<" not in token
+        and ">" not in token
+    )
+
+
+def _normalize(path: str) -> str:
+    return str(PurePosixPath(path))
+
+
+def _prose_tokens(body: str) -> List[str]:
+    cleaned = COMMENT_PATTERN.sub("", body)
+    return [
+        _normalize(match.group(1).strip())
+        for match in BACKTICK_PATTERN.finditer(cleaned)
+        if _looks_like_path(match.group(1).strip())
+    ]
+
+
+def _verify_tokens(block: str) -> List[str]:
+    tokens = []
+    for line in block.splitlines():
+        parts = line.split()
+        for token in parts[1:]:
+            token = token.strip("\"'")
+            if _looks_like_path(token):
+                tokens.append(_normalize(token))
+    return tokens
+
+
+def _lint_task(
+    repo: Path, base: str, path: Path,
+    dependency_files: Optional[Dict[str, Set[str]]] = None,
+    landed_bases: Optional[Dict[str, str]] = None,
+) -> Tuple[str, List[str], Optional[str], int]:
+    text = path.read_text(encoding="utf-8")
+    fields, error = _frontmatter(text)
+    task_id = path.stem
+    if fields and isinstance(fields.get("id"), str):
+        task_id = fields["id"]  # type: ignore[assignment]
+    base = (landed_bases or {}).get(task_id, base)
+    problems: List[str] = []
+    checked = 0
+    if fields is None:
+        return task_id, [error or "invalid frontmatter"], None, checked
+
+    for field in REQUIRED_FIELDS:
+        if field not in fields:
+            problems.append(f"missing frontmatter field: {field}")
+    for field in FORBIDDEN_FIELDS:
+        if field in fields:
+            problems.append(f"forbidden frontmatter field: {field}")
+
+    sections = _sections(text)
+    for name in REQUIRED_SECTIONS:
+        body = sections.get(name)
+        if body is None:
+            problems.append(f"missing ## {name} section")
+        elif not _clean(body):
+            problems.append(f"## {name} section is empty")
+
+    supplied = (dependency_files or {}).get(task_id, set())
+    declared: Set[str] = set()
+    files = fields.get("files")
+    if isinstance(files, str):
+        problems.append("frontmatter files must be a list")
+    elif isinstance(files, list):
+        for entry in files:
+            candidate = PurePosixPath(entry)
+            if candidate.is_absolute():
+                problems.append(f"files entry is not repo-relative: {entry}")
+                continue
+            if ".." in candidate.parts:
+                problems.append(f"files entry must not contain '..': {entry}")
+                continue
+            normalized = str(candidate)
+            declared.add(normalized)
+            checked += 1
+            if ".git" in candidate.parts:
+                problems.append(f"files entry must not enter .git: {normalized}")
+                continue
+            for parent in candidate.parents:
+                if str(parent) == ".":
+                    break
+                kind = _run_git(repo, "cat-file", "-t", f"{base}:{parent}")
+                if kind.returncode == 0 and kind.stdout.strip() != "tree":
+                    problems.append(
+                        f"files entry {normalized} has non-directory ancestor "
+                        f"{parent} at the layer base"
+                    )
+                    break
+
+    for name in PROSE_SECTIONS:
+        body = sections.get(name)
+        if body is None or not _clean(body):
+            continue
+        for token in _prose_tokens(body):
+            checked += 1
+            if (
+                token not in declared
+                and token not in supplied
+                and not _supplied_contract(repo, path, token)
+                and not _base_exists(repo, base, token)
+            ):
+                problems.append(f"## {name} names a path missing at the layer base: {token}")
+
+    verify_body = sections.get("Verify")
+    if verify_body is not None and _clean(verify_body):
+        block = VERIFY_BLOCK_PATTERN.search(verify_body)
+        if block is None or not block.group("block").strip():
+            problems.append("## Verify must contain a non-empty fenced bash block")
+        else:
+            for token in _verify_tokens(block.group("block")):
+                checked += 1
+                if token not in declared and token not in supplied and not _base_exists(repo, base, token):
+                    problems.append(f"## Verify names a path missing at the layer base: {token}")
+
+    contract = None
+    contract_body = sections.get("Interface contract")
+    if contract_body is not None:
+        normalized = " ".join(_clean(contract_body).split())
+        if normalized and normalized not in {"None", "- None"}:
+            contract = _clean(contract_body)
+
+    return task_id, problems, contract, checked
+
+
+def validate_task_briefs(
+    root: Path, base: str, tasks_dir: str = DEFAULT_TASKS_DIR,
+    *, dependency_files: Optional[Dict[str, Set[str]]] = None,
+    landed_bases: Optional[Dict[str, str]] = None,
+) -> Dict[str, object]:
+    """Lint task briefs using the caller's validation bases.
+
+    Dispatch uses the layer base without overrides. Plan approval supplies
+    transitive dependency files for pending tasks and resolved historical bases
+    for landed tasks, whose immutable briefs must survive later file changes.
+    The caller validates the task graph and landed metadata before supplying
+    these mappings; landed tasks receive no dependency-file allowance.
+    """
+
+    resolved_base = _resolve_base(root, base)
+    tasks_path = root / tasks_dir
+    if not tasks_path.is_dir():
+        raise BriefError(f"tasks directory not found: {tasks_dir}")
+
+    problems: List[str] = []
+    contracts: Dict[str, Set[str]] = {}
+    checked = 0
+    task_files = sorted(tasks_path.glob("*.md"))
+    if not task_files:
+        raise BriefError(f"no task briefs found in {tasks_dir}")
+    for path in task_files:
+        task_id, task_problems, contract, task_checked = _lint_task(
+            root, resolved_base, path, dependency_files, landed_bases
+        )
+        problems.extend(f"{task_id}: {problem}" for problem in task_problems)
+        if contract is not None:
+            for entry in re.split(r"(?m)^-[ \t]+", contract):
+                shape = " ".join(entry.split())
+                if shape:
+                    contracts.setdefault(shape, set()).add(task_id)
+        checked += task_checked
+
+    for shape, task_ids in contracts.items():
+        if len(task_ids) == 1:
+            task_id = next(iter(task_ids))
+            problems.append(
+                f"{task_id}: interface contract is not shared by any other task: {shape}"
+            )
+
+    if problems:
+        raise BriefError("\n".join(problems))
+    return {"base": resolved_base, "checked": checked, "tasks": len(task_files)}
+
+
+def _tasks_dir(value: str) -> str:
+    """Argparse type for --tasks-dir: a relative POSIX-style path."""
+
+    path = PurePosixPath(value)
+    if path.is_absolute():
+        raise argparse.ArgumentTypeError(
+            f"--tasks-dir must be a relative path, found absolute: {value}"
+        )
+    if ".." in path.parts:
+        raise argparse.ArgumentTypeError(
+            f"--tasks-dir must not contain '..', found: {value}"
+        )
+    return str(path)
+
+
+def parser() -> argparse.ArgumentParser:
+    argument_parser = argparse.ArgumentParser(description=__doc__)
+    argument_parser.add_argument("--repo", type=Path, required=True)
+    argument_parser.add_argument(
+        "--base",
+        required=True,
+        help="full SHA of the clean layer base commit the briefs are checked against",
+    )
+    argument_parser.add_argument(
+        "--tasks-dir",
+        type=_tasks_dir,
+        default=DEFAULT_TASKS_DIR,
+        help="relative POSIX-style directory under --repo holding the task files "
+        "(default: .project/tasks)",
+    )
+    return argument_parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    arguments = parser().parse_args(argv)
+    try:
+        result = validate_task_briefs(
+            arguments.repo.resolve(), arguments.base, arguments.tasks_dir
+        )
+    except BriefError as error:
+        print(f"task brief validation failed: {error}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_update.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Print a one-line notice when a newer GSD Path is published to npm.
+
+Installed beside the router skill; the installer stamps ../VERSION. Silent on
+any failure (offline, unpublished package, missing stamp) and rate-limited by
+a 24h cache, so the router can run it unconditionally.
+"""
+
+import json
+import time
+import urllib.request
+from pathlib import Path
+
+REGISTRY_URL = "https://registry.npmjs.org/@opengsd%2Fgsd-path/latest"
+CACHE_PATH = Path.home() / ".cache" / "gsd-path" / "update-check.json"
+CACHE_TTL_SECONDS = 24 * 3600
+NETWORK_TIMEOUT_SECONDS = 3
+
+
+def parse_version(value):
+    try:
+        return tuple(int(part) for part in value.strip().split("."))
+    except (ValueError, AttributeError):
+        return None
+
+
+def is_newer(latest, installed):
+    latest_parts = parse_version(latest)
+    installed_parts = parse_version(installed)
+    return (
+        latest_parts is not None
+        and installed_parts is not None
+        and latest_parts > installed_parts
+    )
+
+
+def _write_cache(now, latest):
+    try:
+        CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        CACHE_PATH.write_text(
+            json.dumps({"checked_at": now, "latest": latest}), encoding="utf-8"
+        )
+    except OSError:
+        pass
+
+
+def latest_version():
+    now = time.time()
+    try:
+        cached = json.loads(CACHE_PATH.read_text(encoding="utf-8"))
+        if now - cached["checked_at"] < CACHE_TTL_SECONDS:
+            return cached["latest"]
+    except Exception:
+        pass
+    try:
+        with urllib.request.urlopen(
+            REGISTRY_URL, timeout=NETWORK_TIMEOUT_SECONDS
+        ) as response:
+            latest = json.load(response)["version"]
+    except Exception:
+        # Cache the failure too, so offline or pre-publish routers do not
+        # retry the network on every conversation within the TTL.
+        _write_cache(now, None)
+        return None
+    _write_cache(now, latest)
+    return latest
+
+
+def notice():
+    version_file = Path(__file__).resolve().parent.parent / "VERSION"
+    try:
+        installed = version_file.read_text(encoding="utf-8").strip()
+        latest = latest_version()
+    except Exception:
+        return None
+    if is_newer(latest, installed):
+        return (
+            f"GSD Path {latest} is available (installed {installed}). "
+            "Update: npx @opengsd/gsd-path@latest --update "
+            "(add --local for a project install)."
+        )
+    return None
+
+
+def main():
+    line = notice()
+    if line:
+        print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/core_hook_gate.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""Run an existing Core hook except in explicitly migrated project roots."""
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", required=True, action="append", type=Path)
+    parser.add_argument("--command", required=True)
+    args = parser.parse_args()
+    payload = sys.stdin.buffer.read()
+    try:
+        event = json.loads(payload)
+        cwd = event.get("cwd") if isinstance(event, dict) else None
+        if isinstance(cwd, str) and Path(cwd).is_absolute():
+            directory = Path(cwd).resolve(strict=True)
+            for project in args.repo:
+                root = project.resolve(strict=True)
+                if directory.is_dir() and (directory == root or root in directory.parents):
+                    return 0
+    except (OSError, ValueError, RuntimeError):
+        # An uncertain event keeps the original hook's protection and errors.
+        pass
+    result = subprocess.run(args.command, shell=True, input=payload)
+    return result.returncode if result.returncode >= 0 else 128 - result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/core_hook_settings.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Prepare, apply or restore one explicitly selected standalone Core hook."""
+
+import argparse
+import base64
+import json
+import os
+from pathlib import Path
+import shlex
+import stat
+import subprocess
+import sys
+import tempfile
+
+
+def read_regular(path):
+    metadata = path.lstat()
+    if not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1:
+        raise ValueError(f"expected an unlinked regular file: {path}")
+    return path.read_bytes()
+
+
+def plan(args):
+    if args.settings is None or args.repo is None or args.location is None:
+        raise ValueError("plan requires --settings, --repo and --location")
+    before = read_regular(args.settings)
+    data = json.loads(before)
+    location = json.loads(args.location)
+    if not isinstance(location, list) or len(location) < 2 or location[0] not in ("hooks", "statusLine") or location[-1] != "command":
+        raise ValueError("location must select a hooks or statusLine command")
+    entry = data
+    for key in location[:-1]:
+        if isinstance(entry, dict) and isinstance(key, str):
+            entry = entry[key]
+        elif isinstance(entry, list) and type(key) is int and key >= 0:
+            entry = entry[key]
+        else:
+            raise ValueError("invalid command location")
+    if not isinstance(entry, dict) or entry.get("type", "command") != "command":
+        raise ValueError("selected hook is not a command hook")
+    original = entry.get("command")
+    if not isinstance(original, str) or not original.strip():
+        raise ValueError("selected command must be a nonempty string")
+    repo = args.repo.resolve(strict=True)
+    if not repo.is_dir():
+        raise ValueError("--repo must be a directory")
+    gate = Path(__file__).resolve().with_name("core_hook_gate.py")
+    if not gate.is_file():
+        raise ValueError(f"missing installed hook gate: {gate}")
+    argv = [sys.executable, "-B", str(gate), "--repo", str(repo), "--command", original]
+    replacement = subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+    entry["command"] = replacement
+    after = (json.dumps(data, indent=2) + "\n").encode()
+    receipt = {
+        "schema": "gsd-path/core-hook-change/v1",
+        "settings": str(args.settings.absolute()),
+        "repo": str(repo), "location": location,
+        "original_command": original, "replacement_command": replacement,
+        "before": base64.b64encode(before).decode(),
+        "after": base64.b64encode(after).decode(),
+    }
+    # Settings may contain secrets; the review/rollback copy is owner-only.
+    with open(args.receipt, "x", encoding="utf-8", opener=lambda path, flags: os.open(path, flags, 0o600)) as handle:
+        json.dump(receipt, handle, indent=2)
+        handle.write("\n")
+    return {"status": "planned", "receipt": str(args.receipt.absolute())}
+
+
+def change(args):
+    if args.settings is not None or args.repo is not None or args.location is not None:
+        raise ValueError("apply and restore accept only --receipt")
+    receipt = json.loads(read_regular(args.receipt))
+    if not isinstance(receipt, dict) or receipt.get("schema") != "gsd-path/core-hook-change/v1":
+        raise ValueError("unsupported hook change receipt")
+    path = Path(receipt["settings"])
+    if not path.is_absolute():
+        raise ValueError("receipt settings path must be absolute")
+    before = base64.b64decode(receipt["before"], validate=True)
+    after = base64.b64decode(receipt["after"], validate=True)
+    expected, desired = (before, after) if args.action == "apply" else (after, before)
+    current = read_regular(path)
+    if current == desired:
+        return {"status": args.action, "settings": str(path), "changed": False}
+    if current != expected:
+        raise ValueError("settings changed since planning; refusing to overwrite later edits")
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as handle:
+            temporary = Path(handle.name)
+            handle.write(desired)
+        os.chmod(temporary, stat.S_IMODE(path.stat().st_mode))
+        if read_regular(path) != expected:
+            raise ValueError("settings changed during update")
+        os.replace(temporary, path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return {"status": args.action, "settings": str(path), "changed": True}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", choices=("plan", "apply", "restore"))
+    parser.add_argument("--receipt", type=Path, required=True)
+    parser.add_argument("--settings", type=Path)
+    parser.add_argument("--repo", type=Path)
+    parser.add_argument("--location", help="JSON array locating the selected command")
+    args = parser.parse_args()
+    try:
+        result = plan(args) if args.action == "plan" else change(args)
+        print(json.dumps(result))
+    except (OSError, ValueError, KeyError, IndexError, TypeError) as error:
+        print(f"hook settings error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())