summaryrefslogtreecommitdiff
path: root/scripts/fetch_github_tree.py
blob: eab99e8a21dad8236e564137c266dd2c3078724d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""Fetch a directory tree from GitHub via the gh CLI.

Recursively downloads files from a GitHub repo path and writes
them to a local directory. Prints a JSON manifest to stdout.

Note: Branch names with slashes (e.g., feature/foo) are not
supported in URL parsing. Use the full tree URL and the script
will capture only the first path segment as the branch name.
"""

import argparse
import base64
import binascii
import json
import re
import subprocess
import sys
import tempfile
import time
from pathlib import Path

MAX_FILES = 200
MAX_DEPTH = 10
SUBPROCESS_TIMEOUT = 30
# Polite delay between API calls to avoid rate-limit pressure
API_DELAY_SECONDS = 0.3


def run_gh(*args: str) -> str:
    """Run a gh CLI command and return stdout."""
    result = subprocess.run(
        ["gh", *args],
        capture_output=True,
        text=True,
        check=True,
        timeout=SUBPROCESS_TIMEOUT,
    )
    return result.stdout


def check_gh_auth() -> None:
    """Verify gh CLI is authenticated."""
    try:
        subprocess.run(
            ["gh", "auth", "status"],
            capture_output=True,
            check=True,
            timeout=SUBPROCESS_TIMEOUT,
        )
    except FileNotFoundError:
        print(
            "Error: gh CLI not found. Install from https://cli.github.com/",
            file=sys.stderr,
        )
        sys.exit(1)
    except subprocess.CalledProcessError:
        print(
            "Error: gh CLI not authenticated. Run 'gh auth login' first.",
            file=sys.stderr,
        )
        sys.exit(1)
    except subprocess.TimeoutExpired:
        print(
            "Error: gh auth check timed out.",
            file=sys.stderr,
        )
        sys.exit(1)


def _validate_component(value: str, name: str) -> None:
    """Reject path traversal and shell metacharacters."""
    if re.search(r"[;$`|&<>\\\x00-\x1f]", value):
        print(
            f"Error: Invalid characters in {name}: {value[:200]}",
            file=sys.stderr,
        )
        sys.exit(1)
    if ".." in value.split("/"):
        print(
            f"Error: Path traversal in {name}: {value[:200]}",
            file=sys.stderr,
        )
        sys.exit(1)


def parse_github_url(url: str) -> tuple[str, str, str | None]:
    """Parse a GitHub URL into (repo, path, branch).

    Supports:
      https://github.com/{owner}/{repo}/tree/{branch}/{path}
      https://github.com/{owner}/{repo}/blob/{branch}/{path}
      github.com/{owner}/{repo}/tree/{branch}/{path}
      {owner}/{repo}  (shorthand: root path, default branch)

    For blob URLs, uses the parent directory.
    Branch names with slashes are not supported; the regex
    captures only the first segment after tree/blob.

    Returns:
        (repo, path, branch) where branch may be None
        for default branch.
    """
    url = url.strip().rstrip("/")

    # Strip protocol and github.com prefix
    cleaned = re.sub(r"^https?://", "", url)
    cleaned = re.sub(r"^github\.com/", "", cleaned)

    # Match tree/blob URL: owner/repo/(tree|blob)/branch/path
    m = re.match(
        r"^([^/]+/[^/]+)/(tree|blob)/([^/]+)(?:/(.*))?$",
        cleaned,
    )
    if m:
        repo = m.group(1)
        url_type = m.group(2)
        branch = m.group(3)
        path = m.group(4) or ""
        if url_type == "blob" and "/" in path:
            path = path.rsplit("/", 1)[0]
        elif url_type == "blob":
            path = ""
        _validate_component(repo, "repo")
        _validate_component(branch, "branch")
        if path:
            _validate_component(path, "path")
        return repo, path, branch

    # Shorthand: owner/repo
    m = re.match(r"^([^/]+/[^/]+)$", cleaned)
    if m:
        repo = m.group(1)
        _validate_component(repo, "repo")
        return repo, "", None

    print(
        f"Error: Could not parse GitHub URL: {url[:200]}\n"
        "Expected formats:\n"
        "  https://github.com/owner/repo/tree/branch/path\n"
        "  https://github.com/owner/repo/blob/branch/path\n"
        "  owner/repo",
        file=sys.stderr,
    )
    sys.exit(1)


def get_repo_metadata(repo: str) -> tuple[str, str | None]:
    """Get the default branch and license in one API call."""
    raw = run_gh(
        "api",
        f"repos/{repo}",
        "--jq",
        "{branch: .default_branch, license: .license.spdx_id}",
    )
    data = json.loads(raw)
    branch = data["branch"]
    license_id = data.get("license")
    if license_id in (None, "null", "NOASSERTION"):
        license_id = None
    return branch, license_id


def fetch_file_content(repo: str, path: str) -> bytes | None:
    """Fetch a single file's content, base64-decoded."""
    try:
        raw = run_gh(
            "api",
            f"repos/{repo}/contents/{path}",
            "--jq",
            ".content",
        )
        content = raw.strip()
        if not content or content == "null":
            return None
        return base64.b64decode(content)
    except subprocess.CalledProcessError as exc:
        stderr = (exc.stderr or "").strip()
        if "rate limit" in stderr.lower():
            print(
                "Error: GitHub API rate limit exceeded. "
                "Wait a few minutes or check 'gh api rate_limit'.",
                file=sys.stderr,
            )
            sys.exit(1)
        print(
            f"Warning: Failed to fetch {path}: {stderr}",
            file=sys.stderr,
        )
        return None
    except binascii.Error:
        print(
            f"Warning: Invalid base64 for {path}, skipping.",
            file=sys.stderr,
        )
        return None


def fetch_tree(
    repo: str,
    path: str,
    *,
    _depth: int = 0,
    _file_count: int = 0,
) -> dict[str, bytes | None]:
    """Recursively fetch all files under a path.

    Args:
        repo: GitHub repo in 'owner/repo' format.
        path: Directory path within the repo.
        _depth: Current recursion depth (internal).
        _file_count: Running file count (internal).

    Returns:
        Dict mapping relative paths to file content bytes.
    """
    if _depth > MAX_DEPTH:
        print(
            f"Error: Maximum directory depth ({MAX_DEPTH}) exceeded at {path}.",
            file=sys.stderr,
        )
        sys.exit(1)

    files: dict[str, bytes | None] = {}
    try:
        raw = run_gh(
            "api",
            f"repos/{repo}/contents/{path}",
        )
        entries = json.loads(raw)
    except subprocess.CalledProcessError:
        print(
            f"Error: Path '{path[:200]}' not found in {repo}.",
            file=sys.stderr,
        )
        sys.exit(1)
    except json.JSONDecodeError:
        print(
            f"Error: Unexpected API response for {repo}/{path[:200]}.",
            file=sys.stderr,
        )
        sys.exit(1)

    # Single file (API returns object, not array)
    if isinstance(entries, dict):
        entries = [entries]

    for entry in entries:
        rel = entry["path"].removeprefix(path).lstrip("/")
        if not rel:
            rel = entry["name"]

        # Reject paths with traversal components
        if ".." in rel.split("/"):
            print(
                f"Warning: Skipping suspicious path: {rel}",
                file=sys.stderr,
            )
            continue

        if entry["type"] == "file":
            _file_count += 1
            if _file_count > MAX_FILES:
                print(
                    f"Error: Too many files (>{MAX_FILES}). Use a more specific path.",
                    file=sys.stderr,
                )
                sys.exit(1)
            content = fetch_file_content(repo, entry["path"])
            files[rel] = content
            time.sleep(API_DELAY_SECONDS)
        elif entry["type"] == "dir":
            sub = fetch_tree(
                repo,
                entry["path"],
                _depth=_depth + 1,
                _file_count=_file_count,
            )
            _file_count += len(sub)
            for sub_path, sub_content in sub.items():
                files[f"{rel}/{sub_path}"] = sub_content

    return files


def write_tree(
    files: dict[str, bytes | None],
    output_dir: Path,
) -> None:
    """Write fetched files to disk with path traversal protection."""
    resolved_base = output_dir.resolve()
    for rel_path, content in files.items():
        if content is None:
            continue
        out_file = (output_dir / rel_path).resolve()
        if not str(out_file).startswith(str(resolved_base) + "/"):
            print(
                f"Error: Path traversal detected: {rel_path}",
                file=sys.stderr,
            )
            sys.exit(1)
        out_file.parent.mkdir(parents=True, exist_ok=True)
        out_file.write_bytes(content)


def main() -> None:
    """Entry point."""
    parser = argparse.ArgumentParser(
        description="Fetch a directory tree from GitHub",
    )
    parser.add_argument(
        "url",
        help="GitHub URL or owner/repo shorthand",
    )
    args = parser.parse_args()

    check_gh_auth()

    repo, path, branch = parse_github_url(args.url)

    default_branch, license_id = get_repo_metadata(repo)
    if branch is None:
        branch = default_branch

    output_dir = Path(tempfile.mkdtemp(prefix="skill-import-"))

    files = fetch_tree(repo, path)
    write_tree(files, output_dir)

    manifest = {
        "repo": repo,
        "path": path,
        "branch": branch,
        "license": license_id,
        "output_dir": str(output_dir),
        "files": sorted(k for k, v in files.items() if v is not None),
    }
    print(json.dumps(manifest, indent=2))


if __name__ == "__main__":
    main()