claude-dev-env 4.3.0 → 7.1.0

package/scripts/pr_verification/github_parsing.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from .config.constants import (
+    GITHUB_SHAPE_ERROR_TEMPLATE,
+    PULL_BASE_KEY,
+    PULL_DRAFT_KEY,
+    PULL_HEAD_KEY,
+    PULL_LIST_RESOURCE_NAME,
+    PULL_MERGE_SHA_KEY,
+    PULL_NUMBER_KEY,
+    PULL_REF_KEY,
+    PULL_RESOURCE_NAME,
+    PULL_SHA_KEY,
+)
+from .model import PullRequestCandidate
+
+
+class GitHubError(RuntimeError):
+    """Raised when GitHub metadata has an invalid shape."""
+
+
+def _require_pull_list(all_pull_entries: object) -> list[object]:
+    if isinstance(all_pull_entries, list):
+        return all_pull_entries
+    raise GitHubError(
+        GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=PULL_LIST_RESOURCE_NAME)
+    )
+
+
+def _parse_pull_candidates(
+    repository_slug: str,
+    all_pull_entries: list[object],
+    should_require_merge_commit: bool,
+) -> tuple[PullRequestCandidate, ...]:
+    all_candidates: list[PullRequestCandidate] = []
+    for each_pull in all_pull_entries:
+        maybe_candidate = parse_recognized_candidate(
+            repository_slug,
+            each_pull,
+            should_require_merge_commit=should_require_merge_commit,
+        )
+        if maybe_candidate is not None:
+            all_candidates.append(maybe_candidate)
+    return tuple(all_candidates)
+
+
+def _read_pull_branches(
+    all_pull_fields: Mapping[str, object],
+) -> tuple[Mapping[str, object], Mapping[str, object]]:
+    base = require_mapping(all_pull_fields.get(PULL_BASE_KEY), PULL_RESOURCE_NAME)
+    head = require_mapping(all_pull_fields.get(PULL_HEAD_KEY), PULL_RESOURCE_NAME)
+    return base, head
+
+
+def _read_pull_draft(all_pull_fields: Mapping[str, object]) -> bool:
+    is_draft = all_pull_fields.get(PULL_DRAFT_KEY)
+    if isinstance(is_draft, bool):
+        return is_draft
+    raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=PULL_RESOURCE_NAME))
+
+
+def parse_candidate(
+    repository_slug: str,
+    raw_pull: object,
+    *,
+    should_require_merge_commit: bool,
+) -> PullRequestCandidate:
+    """Parse pull request metadata.
+
+    Args:
+        repository_slug: Repository slug.
+        raw_pull: GitHub pull JSON.
+
+    Returns:
+        Parsed pull request.
+
+    Raises:
+        GitHubError: If metadata is invalid.
+    """
+    pull = require_mapping(raw_pull, PULL_RESOURCE_NAME)
+    base, head = _read_pull_branches(pull)
+    pull_number = require_positive_integer(pull, PULL_NUMBER_KEY, PULL_RESOURCE_NAME)
+    return PullRequestCandidate(
+        repository_slug=repository_slug,
+        pull_request_number=pull_number,
+        base_ref=require_text(base, PULL_REF_KEY, PULL_RESOURCE_NAME),
+        base_sha=require_text(base, PULL_SHA_KEY, PULL_RESOURCE_NAME),
+        head_sha=require_text(head, PULL_SHA_KEY, PULL_RESOURCE_NAME),
+        merge_sha=_read_merge_sha(pull, should_require_merge_commit),
+        is_draft=_read_pull_draft(pull),
+    )
+
+
+def _read_merge_sha(
+    all_pull_fields: Mapping[str, object],
+    should_require_merge_commit: bool,
+) -> str:
+    merge_sha = all_pull_fields.get(PULL_MERGE_SHA_KEY)
+    if merge_sha is None and not should_require_merge_commit:
+        return ""
+    if not isinstance(merge_sha, str) or not merge_sha:
+        raise GitHubError(
+            GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=PULL_RESOURCE_NAME)
+        )
+    return merge_sha
+
+
+def parse_recognized_candidate(
+    repository_slug: str,
+    raw_pull: object,
+    *,
+    should_require_merge_commit: bool = True,
+) -> PullRequestCandidate | None:
+    """Parse a pull request with a merge commit.
+
+    Args:
+        repository_slug: Repository slug.
+        raw_pull: GitHub pull JSON.
+
+    Returns:
+        Parsed pull request or None.
+    """
+    pull = require_mapping(raw_pull, PULL_RESOURCE_NAME)
+    if not should_require_merge_commit:
+        return parse_candidate(
+            repository_slug,
+            pull,
+            should_require_merge_commit=False,
+        )
+    if pull.get(PULL_MERGE_SHA_KEY) is None:
+        return None
+    return parse_candidate(repository_slug, pull, should_require_merge_commit=True)
+
+
+def require_mapping(raw_payload: object, resource: str) -> Mapping[str, object]:
+    if not isinstance(raw_payload, Mapping):
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    return raw_payload
+
+
+def require_text(
+    all_payload_fields: Mapping[str, object], field_name: str, resource: str
+) -> str:
+    """Read required text from a JSON object.
+
+    Args:
+        all_payload_fields: JSON object.
+
+    Returns:
+        Required text.
+
+    Raises:
+        GitHubError: If the field is absent.
+    """
+    field_text = all_payload_fields.get(field_name)
+    if not isinstance(field_text, str) or not field_text:
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    return field_text
+
+
+def require_positive_integer(
+    all_payload_fields: Mapping[str, object], field_name: str, resource: str
+) -> int:
+    """Read a required positive integer.
+
+    Args:
+        all_payload_fields: JSON object.
+
+    Returns:
+        Required integer.
+
+    Raises:
+        GitHubError: If the field is invalid.
+    """
+    field_integer = all_payload_fields.get(field_name)
+    if isinstance(field_integer, bool) or not isinstance(field_integer, int):
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    if field_integer < 1:
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    return field_integer

package/scripts/pr_verification/github_transport.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from http.client import HTTPResponse as OpenedHttpReply
+
+import jwt
+
+from .config.constants import (
+    UTF8_ENCODING,
+)
+from .config.timing import HTTP_TIMEOUT_SECONDS
+from .github_parsing import GitHubError
+
+
+@dataclass(frozen=True)
+class HttpReply:
+    status_code: int
+    headers: dict[str, str]
+    body: bytes
+
+
+HttpRequester = Callable[[str, str, dict[str, str], bytes | None], HttpReply]
+JwtEncoder = Callable[[dict[str, int | str], str, str], str]
+
+
+def _read_http_error(error: urllib.error.HTTPError) -> HttpReply:
+    return HttpReply(
+        status_code=error.code,
+        headers=dict(error.headers.items()),
+        body=error.read(),
+    )
+
+
+def request_http(
+    method: str,
+    url: str,
+    all_headers: dict[str, str],
+    body: bytes | None,
+) -> HttpReply:
+    """Send one GitHub HTTP request.
+
+    Args:
+        method: HTTP method.
+        url: Absolute request URL.
+        all_headers: Request headers.
+        body: Encoded request body, or None.
+
+    Returns:
+        The HTTP reply, including error replies with a status code.
+
+    Raises:
+        GitHubError: If the request fails before a status code exists.
+    """
+    request = urllib.request.Request(
+        url=url, data=body, headers=all_headers, method=method
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=HTTP_TIMEOUT_SECONDS) as reply:
+            return _read_http_reply(reply)
+    except urllib.error.HTTPError as error:
+        return _read_http_error(error)
+    except (urllib.error.URLError, OSError) as error:
+        raise GitHubError(str(error)) from error
+
+
+def _read_http_reply(reply: OpenedHttpReply) -> HttpReply:
+    return HttpReply(
+        status_code=reply.status,
+        headers=dict(reply.headers.items()),
+        body=reply.read(),
+    )
+
+
+def encode_app_jwt(
+    all_claims: dict[str, int | str], private_key: str, algorithm: str
+) -> str:
+    """Encode an app JWT.
+
+    Args:
+        all_claims: JWT claims.
+
+    Returns:
+        Encoded token.
+    """
+    encoded_token = jwt.encode(all_claims, private_key, algorithm=algorithm)
+    if isinstance(encoded_token, bytes):
+        return encoded_token.decode(UTF8_ENCODING)
+    return encoded_token

package/scripts/pr_verification/lock.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from types import TracebackType
+from typing import Self
+
+if sys.platform == "win32":
+    import msvcrt
+else:
+    import fcntl
+
+from .config.constants import (
+    SUPERVISOR_LOCK_ERROR,
+    SUPERVISOR_LOCK_FILE_MODE,
+    SUPERVISOR_LOCK_FILENAME,
+    SUPERVISOR_LOCK_IO_ERROR,
+)
+
+if sys.platform == "win32":
+
+    def _acquire_file_lock(file_descriptor: int) -> None:
+        """Acquire one nonblocking Windows lock."""
+        os.lseek(file_descriptor, 0, os.SEEK_SET)
+        msvcrt.locking(file_descriptor, msvcrt.LK_NBLCK, 1)
+
+    def _release_file_lock(file_descriptor: int) -> None:
+        """Release one Windows lock."""
+        os.lseek(file_descriptor, 0, os.SEEK_SET)
+        msvcrt.locking(file_descriptor, msvcrt.LK_UNLCK, 1)
+
+else:
+
+    def _acquire_file_lock(file_descriptor: int) -> None:
+        """Acquire one nonblocking POSIX lock."""
+        fcntl.flock(file_descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+    def _release_file_lock(file_descriptor: int) -> None:
+        """Release one POSIX lock."""
+        fcntl.flock(file_descriptor, fcntl.LOCK_UN)
+
+
+class SupervisorLockError(RuntimeError):
+    """Raised when the supervisor lock cannot be acquired or released."""
+
+
+class SupervisorLock:
+    def __init__(self, cache_root: Path) -> None:
+        self.cache_root = cache_root.resolve()
+        self.lock_path = self.cache_root / SUPERVISOR_LOCK_FILENAME
+        self.file_descriptor: int | None = None
+
+    def __enter__(self) -> Self:
+        self.acquire()
+        return self
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.release()
+
+    def acquire(self) -> None:
+        """Acquire the operating-system lock for this cache root.
+
+        Raises:
+            SupervisorLockError: If another owner holds the lock or I/O fails.
+        """
+        try:
+            self.cache_root.mkdir(parents=True, exist_ok=True)
+            file_descriptor = os.open(
+                self.lock_path,
+                os.O_CREAT | os.O_RDWR,
+                SUPERVISOR_LOCK_FILE_MODE,
+            )
+        except OSError as error:
+            raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+        try:
+            _acquire_file_lock(file_descriptor)
+        except (BlockingIOError, PermissionError) as error:
+            _close_file_descriptor_without_raising(file_descriptor)
+            raise SupervisorLockError(SUPERVISOR_LOCK_ERROR) from error
+        except OSError as error:
+            _close_file_descriptor_without_raising(file_descriptor)
+            raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+        self.file_descriptor = file_descriptor
+
+    def release(self) -> None:
+        """Release the operating-system lock and close its file descriptor.
+
+        Raises:
+            SupervisorLockError: If unlocking or closing the file fails.
+        """
+        file_descriptor = self.file_descriptor
+        if file_descriptor is None:
+            return
+        self.file_descriptor = None
+        try:
+            _release_file_lock(file_descriptor)
+        except OSError as error:
+            raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+        finally:
+            _close_file_descriptor(file_descriptor)
+
+
+def _close_file_descriptor(file_descriptor: int) -> None:
+    """Close one lock file descriptor."""
+    try:
+        os.close(file_descriptor)
+    except OSError as error:
+        raise SupervisorLockError(SUPERVISOR_LOCK_IO_ERROR) from error
+
+
+def _close_file_descriptor_without_raising(file_descriptor: int) -> None:
+    """Close one lock file descriptor while a lock failure is already being raised."""
+    try:
+        os.close(file_descriptor)
+    except OSError:
+        return

package/scripts/pr_verification/model.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from .config.constants import (
+    STATUS_ERROR,
+    STATUS_FAILURE,
+    STATUS_PENDING,
+    STATUS_SUCCESS,
+)
+
+
+class StatusState(str, Enum):
+    PENDING = STATUS_PENDING
+    ERROR = STATUS_ERROR
+    FAILURE = STATUS_FAILURE
+    SUCCESS = STATUS_SUCCESS
+
+
+@dataclass(frozen=True)
+class RepositorySettings:
+    slug: str
+    clone_url: str
+
+    @property
+    def name(self) -> str:
+        return self.slug.split("/", maxsplit=1)[1]
+
+
+@dataclass(frozen=True)
+class PullRequestCandidate:
+    repository_slug: str
+    pull_request_number: int
+    base_ref: str
+    base_sha: str
+    head_sha: str
+    merge_sha: str
+    is_draft: bool
+
+    @property
+    def key(self) -> tuple[str, int]:
+        return self.repository_slug, self.pull_request_number

package/scripts/pr_verification/requirements.txt

@@ -0,0 +1 @@
+PyJWT[crypto]>=2.10,<3

package/scripts/refresh_pstack_plugin_skills.mjs

@@ -0,0 +1,200 @@
+/**
+ * Keep a pstack skills-directory plugin manifest listing every skill folder.
+ *
+ * Claude Code loads a folder under `~/.claude/skills` as a plugin when the
+ * folder holds `.claude-plugin/plugin.json`, and it namespaces that plugin's
+ * skills as `pstack:how`. It does not scan a plugin root for skill folders, so
+ * the manifest names each sub-skill path:
+ *
+ *     plugin root holds: how/SKILL.md, why/SKILL.md, docs/, .claude-plugin/
+ *     manifest before:   "skills": ["./how"]
+ *     manifest after:    "skills": ["./how", "./why"]   <- why/ picked up
+ *     second run:        no write                        <- the list matches
+ *     docs/, .claude-plugin/                             <- skipped, no SKILL.md
+ *
+ * The installer calls `refreshPstackPluginManifest` for a pstack folder the
+ * user installed. Running this file directly refreshes the same manifest after
+ * a pstack update.
+ */
+
+import {
+    existsSync,
+    mkdirSync,
+    readdirSync,
+    readFileSync,
+    realpathSync,
+    writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PSTACK_PLUGIN_DIRECTORY_NAME = 'pstack';
+export const PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH = join('.claude-plugin', 'plugin.json');
+export const SKILL_MANIFEST_FILE_NAME = 'SKILL.md';
+export const SKILL_PATH_PREFIX = './';
+
+const CLAUDE_HOME_DIRECTORY_NAME = '.claude';
+const MANIFEST_SKILLS_KEY = 'skills';
+const MANIFEST_INDENT_SPACES = 2;
+const FILE_ENCODING = 'utf8';
+const HIDDEN_NAME_PREFIX = '.';
+
+/**
+ * Fields a first write seeds from the published pstack plugin. An existing
+ * manifest keeps its own values. This refresher changes only the skills list.
+ */
+const SEEDED_MANIFEST_FIELDS = Object.freeze({
+    $schema: 'https://anthropic.com/claude-code/plugin.schema.json',
+    name: PSTACK_PLUGIN_DIRECTORY_NAME,
+    version: '0.14.8',
+    description:
+        'if you want to go fast, go deep first. pstack helps you write less, but higher '
+        + 'quality code. rigorous agent workflows you can parallelize with confidence.',
+    author: Object.freeze({ name: 'Lauren Tan' }),
+    homepage: 'https://github.com/cursor/plugins/tree/main/pstack',
+    repository: 'https://github.com/cursor/plugins',
+    license: 'MIT',
+});
+
+/**
+ * Name every sub-folder of a plugin root that Claude Code loads as a skill.
+ *
+ * @param {string} pluginRoot Plugin folder holding one sub-folder per skill.
+ * @returns {string[]} The sorted names of each visible sub-folder holding a
+ *   skill manifest. A hidden folder and a folder without `SKILL.md` are left out.
+ */
+export function findPstackSkillDirectoryNames(pluginRoot) {
+    return readdirSync(pluginRoot, { withFileTypes: true })
+        .filter((eachEntry) => eachEntry.isDirectory())
+        .map((eachEntry) => eachEntry.name)
+        .filter((eachName) => !eachName.startsWith(HIDDEN_NAME_PREFIX))
+        .filter((eachName) => existsSync(join(pluginRoot, eachName, SKILL_MANIFEST_FILE_NAME)))
+        .sort();
+}
+
+function readManifestSkillPaths(manifestPath) {
+    if (!existsSync(manifestPath)) return { manifest: null, previousSkillPaths: [] };
+    const manifest = JSON.parse(readFileSync(manifestPath, FILE_ENCODING));
+    const listedSkillPaths = manifest[MANIFEST_SKILLS_KEY];
+    if (typeof listedSkillPaths === 'string') {
+        return { manifest, previousSkillPaths: [listedSkillPaths] };
+    }
+    if (Array.isArray(listedSkillPaths)) {
+        return { manifest, previousSkillPaths: listedSkillPaths };
+    }
+    return { manifest, previousSkillPaths: [] };
+}
+
+/**
+ * Rewrite a pstack plugin manifest's skills list to match its folder.
+ *
+ * Writes only when the list changes. A second call on an unchanged folder
+ * leaves the file byte for byte. An existing manifest keeps every field but
+ * the skills list.
+ *
+ * @param {string} pluginRoot Plugin folder holding the skill sub-folders.
+ * @returns {{didWrite: boolean, reason: string, previousSkillPaths: string[],
+ *   currentSkillPaths: string[]}} Whether this call wrote, and the paths
+ *   before and after. `reason` names a skip, and is empty on a write or an
+ *   unchanged list.
+ */
+export function refreshPstackPluginManifest(pluginRoot) {
+    const declined = { didWrite: false, previousSkillPaths: [], currentSkillPaths: [] };
+    if (!existsSync(pluginRoot)) {
+        return { ...declined, reason: 'plugin root is absent' };
+    }
+    if (existsSync(join(pluginRoot, SKILL_MANIFEST_FILE_NAME))) {
+        return { ...declined, reason: 'plugin root is itself a skill' };
+    }
+    const allSkillNames = findPstackSkillDirectoryNames(pluginRoot);
+    if (allSkillNames.length === 0) {
+        return { ...declined, reason: 'plugin root holds no skills' };
+    }
+    const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+    const { manifest, previousSkillPaths } = readManifestSkillPaths(manifestPath);
+    const currentSkillPaths = allSkillNames.map((eachName) => SKILL_PATH_PREFIX + eachName);
+    const outcome = { reason: '', previousSkillPaths, currentSkillPaths };
+    const isUnchanged = manifest !== null
+        && previousSkillPaths.length === currentSkillPaths.length
+        && previousSkillPaths.every((eachPath, eachIndex) => eachPath === currentSkillPaths[eachIndex]);
+    if (isUnchanged) {
+        return { ...outcome, didWrite: false };
+    }
+    const refreshedManifest = {
+        ...(manifest === null ? SEEDED_MANIFEST_FIELDS : manifest),
+        [MANIFEST_SKILLS_KEY]: currentSkillPaths,
+    };
+    mkdirSync(join(pluginRoot, '.claude-plugin'), { recursive: true });
+    writeFileSync(
+        manifestPath,
+        JSON.stringify(refreshedManifest, null, MANIFEST_INDENT_SPACES) + '\n',
+        FILE_ENCODING,
+    );
+    return { ...outcome, didWrite: true };
+}
+
+/**
+ * Return the pstack plugin folder under a Claude home.
+ *
+ * @param {string} claudeHome The Claude home directory holding `skills`.
+ * @returns {string} The pstack plugin folder path, present or not.
+ */
+export function pstackPluginRootFor(claudeHome) {
+    return join(claudeHome, 'skills', PSTACK_PLUGIN_DIRECTORY_NAME);
+}
+
+/**
+ * Return the Claude home used when no folder argument is given.
+ *
+ * A named profile sets `CLAUDE_CONFIG_DIR`. The installer writes into that
+ * root. The command-line form reads the same variable.
+ *
+ * @param {Record<string, string|undefined>} environment The process environment.
+ * @returns {string} The Claude home directory holding `skills`.
+ */
+export function claudeHomeFrom(environment) {
+    return environment.CLAUDE_CONFIG_DIR || join(homedir(), CLAUDE_HOME_DIRECTORY_NAME);
+}
+
+function main() {
+    const explicitRoot = process.argv[2];
+    const pluginRoot = explicitRoot || pstackPluginRootFor(claudeHomeFrom(process.env));
+    const outcome = refreshPstackPluginManifest(pluginRoot);
+    if (!outcome.didWrite && outcome.reason) {
+        console.log(`No manifest written: ${outcome.reason}.`);
+        return;
+    }
+    if (!outcome.didWrite) {
+        console.log(`No change. ${outcome.currentSkillPaths.length} skills listed.`);
+        return;
+    }
+    console.log(`Updated. ${outcome.currentSkillPaths.length} skills listed.`);
+    for (const eachPath of outcome.currentSkillPaths) {
+        if (!outcome.previousSkillPaths.includes(eachPath)) console.log(`  added   ${eachPath}`);
+    }
+    for (const eachPath of outcome.previousSkillPaths) {
+        if (!outcome.currentSkillPaths.includes(eachPath)) console.log(`  removed ${eachPath}`);
+    }
+}
+
+/**
+ * Return whether node ran this module as its entry point.
+ *
+ * A directory link to this script gives node an invoked path that differs from
+ * this module's own path. Both sides resolve to their real location before
+ * the comparison.
+ *
+ * @param {string|undefined} invokedPath The path node reports as `argv[1]`.
+ * @returns {boolean} True when node ran this module as its entry point.
+ */
+function isEntryPoint(invokedPath) {
+    if (!invokedPath) return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(invokedPath);
+    } catch {
+        return fileURLToPath(import.meta.url) === invokedPath;
+    }
+}
+
+if (isEntryPoint(process.argv[1])) main();