Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

skills/skill-creator/scripts/package_skill.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+from quick_validate import validate_skill
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"[ERROR] Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"[ERROR] Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"[ERROR] SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"[ERROR] Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"[OK] {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    EXCLUDED_DIRS = {".git", ".svn", ".hg", "__pycache__", "node_modules"}
+
+    # Create the .skill file (zip format)
+    try:
+        with zipfile.ZipFile(skill_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
+            # Walk in a deterministic order. Sort by the archive-relative POSIX
+            # entry name (not Path object order, which is filesystem/OS-flavour
+            # dependent) so written .skill entries are byte-stable everywhere.
+            for file_path in sorted(
+                skill_path.rglob("*"),
+                key=lambda path: path.relative_to(skill_path).as_posix(),
+            ):
+                # Security: never follow or package symlinks.
+                if file_path.is_symlink():
+                    print(f"[WARN] Skipping symlink: {file_path}")
+                    continue
+
+                rel_parts = file_path.relative_to(skill_path).parts
+                if any(part in EXCLUDED_DIRS for part in rel_parts):
+                    continue
+
+                if file_path.is_file():
+                    resolved_file = file_path.resolve()
+                    if not _is_within(resolved_file, skill_path):
+                        print(f"[ERROR] File escapes skill root: {file_path}")
+                        return None
+                    # If output lives under skill_path, avoid writing archive into itself.
+                    if resolved_file == skill_filename.resolve():
+                        print(f"[WARN] Skipping output archive: {file_path}")
+                        continue
+
+                    # Calculate the relative path within the zip.
+                    arcname = Path(skill_name) / file_path.relative_to(skill_path)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\n[OK] Successfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        print(f"[ERROR] Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python utils/package_skill.py skills/public/my-skill")
+        print("  python utils/package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

skills/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    import yaml
+except ModuleNotFoundError:
+    yaml = None
+
+MAX_SKILL_NAME_LENGTH = 64
+
+
+def _extract_frontmatter(content: str) -> Optional[str]:
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            return "\n".join(lines[1:i])
+    return None
+
+
+def _parse_simple_frontmatter(frontmatter_text: str) -> Optional[dict[str, str]]:
+    """
+    Minimal fallback parser used when PyYAML is unavailable.
+    Supports simple `key: value` mappings used by SKILL.md frontmatter.
+    """
+    parsed: dict[str, str] = {}
+    current_key: Optional[str] = None
+    for raw_line in frontmatter_text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        is_indented = raw_line[:1].isspace()
+        if is_indented:
+            if current_key is None:
+                return None
+            current_value = parsed[current_key]
+            parsed[current_key] = (
+                f"{current_value}\n{stripped}" if current_value else stripped
+            )
+            continue
+
+        if ":" not in stripped:
+            return None
+        key, value = stripped.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            return None
+        if (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        ):
+            value = value[1:-1]
+        parsed[key] = value
+        current_key = key
+    return parsed
+
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    try:
+        content = skill_md.read_text(encoding="utf-8-sig")
+    except OSError as e:
+        return False, f"Could not read SKILL.md: {e}"
+
+    frontmatter_text = _extract_frontmatter(content)
+    if frontmatter_text is None:
+        return False, "Invalid frontmatter format"
+    if yaml is not None:
+        try:
+            frontmatter = yaml.safe_load(frontmatter_text)
+            if not isinstance(frontmatter, dict):
+                return False, "Frontmatter must be a YAML dictionary"
+        except yaml.YAMLError as e:
+            return False, f"Invalid YAML in frontmatter: {e}"
+    else:
+        frontmatter = _parse_simple_frontmatter(frontmatter_text)
+        if frontmatter is None:
+            return (
+                False,
+                "Invalid YAML in frontmatter: unsupported syntax without PyYAML installed",
+            )
+
+    allowed_properties = {
+        "name",
+        "description",
+        "homepage",
+        "license",
+        "allowed-tools",
+        "user-invocable",
+        "metadata",
+    }
+
+    unexpected_keys = set(frontmatter.keys()) - allowed_properties
+    if unexpected_keys:
+        allowed = ", ".join(sorted(allowed_properties))
+        unexpected = ", ".join(sorted(unexpected_keys))
+        return (
+            False,
+            f"Unexpected key(s) in SKILL.md frontmatter: {unexpected}. Allowed properties are: {allowed}",
+        )
+
+    if "name" not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if "description" not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    name = frontmatter.get("name", "")
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if not name:
+        return False, "Name must not be empty"
+    if not re.match(r"^[a-z0-9-]+$", name):
+        return (
+            False,
+            f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)",
+        )
+    if name.startswith("-") or name.endswith("-") or "--" in name:
+        return (
+            False,
+            f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens",
+        )
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        return (
+            False,
+            f"Name is too long ({len(name)} characters). "
+            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters.",
+        )
+
+    description = frontmatter.get("description", "")
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if not description:
+        return False, "Description must not be empty"
+    if "<" in description or ">" in description:
+        return False, "Description cannot contain angle brackets (< or >)"
+    if len(description) > 1024:
+        return (
+            False,
+            f"Description is too long ({len(description)} characters). Maximum is 1024 characters.",
+        )
+
+    return True, "Skill is valid!"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)

skills/skill-creator/scripts/test_package_skill.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+Regression tests for skill packaging security behavior.
+"""
+
+import sys
+import tempfile
+import types
+import zipfile
+from pathlib import Path
+from unittest import TestCase, main
+from unittest.mock import patch
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+
+fake_quick_validate = types.ModuleType("quick_validate")
+fake_quick_validate.validate_skill = lambda _path: (True, "Skill is valid!")
+original_quick_validate = sys.modules.get("quick_validate")
+sys.modules["quick_validate"] = fake_quick_validate
+
+import package_skill as package_skill_module
+
+package_skill = package_skill_module.package_skill
+
+if original_quick_validate is not None:
+    sys.modules["quick_validate"] = original_quick_validate
+else:
+    sys.modules.pop("quick_validate", None)
+
+
+class TestPackageSkillSecurity(TestCase):
+    def setUp(self):
+        self.temp_dir = Path(tempfile.mkdtemp(prefix="test_skill_"))
+
+    def tearDown(self):
+        import shutil
+
+        if self.temp_dir.exists():
+            shutil.rmtree(self.temp_dir)
+
+    def create_skill(self, name="test-skill"):
+        skill_dir = self.temp_dir / name
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        (skill_dir / "SKILL.md").write_text("---\nname: test-skill\ndescription: test\n---\n")
+        (skill_dir / "script.py").write_text("print('ok')\n")
+        return skill_dir
+
+    def test_packages_normal_files(self):
+        skill_dir = self.create_skill("normal-skill")
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        result = package_skill(str(skill_dir), str(out_dir))
+
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "normal-skill.skill"
+        self.assertTrue(skill_file.exists())
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("normal-skill/SKILL.md", names)
+        self.assertIn("normal-skill/script.py", names)
+
+    def test_skips_symlink_to_external_file(self):
+        skill_dir = self.create_skill("symlink-file-skill")
+        outside = self.temp_dir / "outside-secret.txt"
+        outside.write_text("super-secret\n")
+        link = skill_dir / "loot.txt"
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        try:
+            link.symlink_to(outside)
+        except (OSError, NotImplementedError):
+            self.skipTest("symlink unsupported on this platform")
+
+        result = package_skill(str(skill_dir), str(out_dir))
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "symlink-file-skill.skill"
+        self.assertTrue(skill_file.exists())
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("symlink-file-skill/SKILL.md", names)
+        self.assertIn("symlink-file-skill/script.py", names)
+        self.assertNotIn("symlink-file-skill/loot.txt", names)
+
+    def test_skips_symlink_directory(self):
+        skill_dir = self.create_skill("symlink-dir-skill")
+        outside_dir = self.temp_dir / "outside"
+        outside_dir.mkdir()
+        (outside_dir / "secret.txt").write_text("secret\n")
+        link = skill_dir / "docs"
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        try:
+            link.symlink_to(outside_dir, target_is_directory=True)
+        except (OSError, NotImplementedError):
+            self.skipTest("symlink unsupported on this platform")
+
+        result = package_skill(str(skill_dir), str(out_dir))
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "symlink-dir-skill.skill"
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("symlink-dir-skill/SKILL.md", names)
+        self.assertIn("symlink-dir-skill/script.py", names)
+        self.assertNotIn("symlink-dir-skill/docs/secret.txt", names)
+
+    def test_rejects_resolved_path_outside_skill_root(self):
+        skill_dir = self.create_skill("escape-skill")
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        original_within = package_skill_module._is_within
+
+        def fake_is_within(path_obj: Path, root: Path):
+            if path_obj.name == "script.py":
+                return False
+            return original_within(path_obj, root)
+
+        with patch.object(package_skill_module, "_is_within", fake_is_within):
+            result = package_skill(str(skill_dir), str(out_dir))
+
+        self.assertIsNone(result)
+
+    def test_allows_nested_regular_files(self):
+        skill_dir = self.create_skill("nested-skill")
+        nested = skill_dir / "lib" / "helpers"
+        nested.mkdir(parents=True, exist_ok=True)
+        (nested / "util.py").write_text("def run():\n    return 1\n")
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        result = package_skill(str(skill_dir), str(out_dir))
+
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "nested-skill.skill"
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("nested-skill/lib/helpers/util.py", names)
+
+    def test_skips_output_archive_when_output_dir_is_skill_dir(self):
+        skill_dir = self.create_skill("self-output-skill")
+
+        result = package_skill(str(skill_dir), str(skill_dir))
+
+        self.assertIsNotNone(result)
+        skill_file = skill_dir / "self-output-skill.skill"
+        self.assertTrue(skill_file.exists())
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("self-output-skill/SKILL.md", names)
+        self.assertIn("self-output-skill/script.py", names)
+        self.assertNotIn("self-output-skill/self-output-skill.skill", names)
+
+    def test_archive_entry_order_is_deterministic(self):
+        skill_dir = self.create_skill("order-skill")
+        # Files across multiple levels, created in non-sorted order, so the
+        # filesystem/rglob enumeration order differs from a lexicographic sort.
+        (skill_dir / "zeta.md").write_text("z\n")
+        (skill_dir / "yankee.txt").write_text("y\n")
+        alpha = skill_dir / "alpha"
+        alpha.mkdir()
+        (alpha / "delta.txt").write_text("d\n")
+        (alpha / "bravo.txt").write_text("b\n")
+        nested = skill_dir / "zlib"
+        nested.mkdir()
+        (nested / "november.txt").write_text("n\n")
+        # "alpha-x.txt" discriminates entry-name ordering from Path-object
+        # ordering: "-" (0x2d) sorts before "/" (0x2f) in the archive entry
+        # name, but Path part-tuple ordering places it after the "alpha/" dir.
+        (skill_dir / "alpha-x.txt").write_text("x\n")
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        result = package_skill(str(skill_dir), str(out_dir))
+
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "order-skill.skill"
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = [name for name in archive.namelist() if not name.endswith("/")]
+        # Entries must be ordered by their archive entry name, regardless of
+        # filesystem enumeration or OS path-flavour, so archives are reproducible.
+        self.assertEqual(names, sorted(names))
+        # Lock the entry-name contract: "alpha-x.txt" precedes "alpha/bravo.txt"
+        # (Path-object sorting would invert these).
+        self.assertLess(
+            names.index("order-skill/alpha-x.txt"),
+            names.index("order-skill/alpha/bravo.txt"),
+        )
+        # Ensure the fixture actually spans multiple directories/files.
+        self.assertIn("order-skill/zlib/november.txt", names)
+
+
+if __name__ == "__main__":
+    main()

skills/skill-creator/scripts/test_quick_validate.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+Regression tests for quick skill validation.
+"""
+
+import tempfile
+from pathlib import Path
+from unittest import TestCase, main
+
+import quick_validate
+
+
+class TestQuickValidate(TestCase):
+    def setUp(self):
+        self.temp_dir = Path(tempfile.mkdtemp(prefix="test_quick_validate_"))
+
+    def tearDown(self):
+        import shutil
+
+        if self.temp_dir.exists():
+            shutil.rmtree(self.temp_dir)
+
+    def test_accepts_crlf_frontmatter(self):
+        skill_dir = self.temp_dir / "crlf-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = "---\r\nname: crlf-skill\r\ndescription: ok\r\n---\r\n# Skill\r\n"
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertTrue(valid, message)
+
+    def test_rejects_missing_frontmatter_closing_fence(self):
+        skill_dir = self.temp_dir / "bad-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = "---\nname: bad-skill\ndescription: missing end\n# no closing fence\n"
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertFalse(valid)
+        self.assertEqual(message, "Invalid frontmatter format")
+
+    def test_fallback_parser_handles_multiline_frontmatter_without_pyyaml(self):
+        skill_dir = self.temp_dir / "multiline-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = """---
+name: multiline-skill
+description: Works without pyyaml
+allowed-tools:
+  - gh
+metadata: |
+  {
+    "owners": ["team-openclaw"]
+  }
+---
+# Skill
+"""
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        previous_yaml = quick_validate.yaml
+        quick_validate.yaml = None
+        try:
+            valid, message = quick_validate.validate_skill(skill_dir)
+        finally:
+            quick_validate.yaml = previous_yaml
+
+        self.assertTrue(valid, message)
+
+    def test_rejects_empty_name(self):
+        skill_dir = self.temp_dir / "empty-name-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = '---\nname: ""\ndescription: a valid description\n---\n# Skill\n'
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertFalse(valid)
+        self.assertEqual(message, "Name must not be empty")
+
+    def test_rejects_whitespace_only_name(self):
+        skill_dir = self.temp_dir / "ws-name-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = "---\nname: '   '\ndescription: a valid description\n---\n# Skill\n"
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertFalse(valid)
+        self.assertEqual(message, "Name must not be empty")
+
+    def test_rejects_empty_description(self):
+        skill_dir = self.temp_dir / "empty-desc-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = '---\nname: valid-skill\ndescription: ""\n---\n# Skill\n'
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertFalse(valid)
+        self.assertEqual(message, "Description must not be empty")
+
+    def test_rejects_whitespace_only_description(self):
+        skill_dir = self.temp_dir / "ws-desc-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = "---\nname: valid-skill\ndescription: '   '\n---\n# Skill\n"
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertFalse(valid)
+        self.assertEqual(message, "Description must not be empty")
+
+
+if __name__ == "__main__":
+    main()