claude-dev-env 1.89.0 → 1.92.0

package/scripts/dev_env_scripts_constants/claude_chain_constants.py

@@ -0,0 +1,124 @@
+"""Named constants for the claude fallback-chain runner.
+
+Per the project's configuration conventions, every scalar and structural
+constant the runner needs lives here rather than inline in the module.
+"""
+
+from __future__ import annotations
+
+UTF8_ENCODING: str = "utf-8"
+"""Encoding used to read the chain configuration file."""
+
+CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
+"""Per-user directory under the home directory that holds the chain config."""
+
+CONFIG_FILENAME: str = "claude-chain.json"
+"""Real chain-configuration filename read from the user's home directory."""
+
+EXAMPLE_CONFIG_FILENAME: str = "claude-chain.example.json"
+"""Committed template filename referenced in the config-error guidance."""
+
+CONFIG_CHAIN_KEY: str = "chain"
+"""Top-level key whose value is the ordered list of chain entries."""
+
+CONFIG_COMMAND_KEY: str = "command"
+"""Chain-entry key naming the binary to spawn."""
+
+CONFIG_EXTRA_ARGS_KEY: str = "extra_args"
+"""Chain-entry key holding per-account arguments appended to each invocation."""
+
+ALL_USAGE_LIMIT_SIGNATURES: tuple[str, ...] = (
+    "hit your session limit",
+    "usage limit reached",
+    "out of usage",
+    "usage quota exceeded",
+)
+"""Case-insensitive substrings that mark a non-zero exit as a usage-limit refusal."""
+
+ATTEMPT_STATUS_SERVED: str = "served"
+"""Status recorded when a binary exits zero and serves the call."""
+
+ATTEMPT_STATUS_USAGE_LIMITED: str = "usage_limited"
+"""Status recorded when a binary fails with a usage-limit signature."""
+
+ATTEMPT_STATUS_EXECUTABLE_NOT_FOUND: str = "executable_not_found"
+"""Status recorded when a binary is not installed."""
+
+ATTEMPT_STATUS_NONZERO_EXIT: str = "nonzero_exit"
+"""Status recorded when a binary fails without a usage-limit signature."""
+
+ATTEMPT_STATUS_TIMEOUT: str = "timeout"
+"""Status recorded when a binary exceeds the invocation timeout."""
+
+DEFAULT_TIMEOUT_SECONDS: int = 300
+"""Timeout applied to each binary invocation when the caller names none."""
+
+NO_COMPLETED_PROCESS_RETURN_CODE: int = 1
+"""Return code carried on the result when no binary produced a completed process."""
+
+CHAIN_EXHAUSTED_EXIT_CODE: int = 2
+"""CLI exit code when no binary in the chain served the call."""
+
+CHAIN_CONFIG_ERROR_EXIT_CODE: int = 3
+"""CLI exit code when the chain configuration is missing or invalid."""
+
+CLI_TIMEOUT_FLAG: str = "--timeout-seconds"
+"""CLI flag that overrides the per-invocation timeout in seconds."""
+
+CLI_ARGUMENTS_SEPARATOR: str = "--"
+"""CLI token separating runner flags from the passthrough claude arguments."""
+
+CONFIG_NOT_OBJECT_REASON: str = "the top-level value is not a JSON object"
+"""Reason detail when the config root is not an object."""
+
+CONFIG_CHAIN_NOT_LIST_REASON: str = "the 'chain' key is missing or not a list"
+"""Reason detail when the chain key is absent or the wrong type."""
+
+CONFIG_CHAIN_EMPTY_REASON: str = "the 'chain' list is empty"
+"""Reason detail when the chain contains no entries."""
+
+CONFIG_ENTRY_NOT_OBJECT_REASON: str = "a chain entry is not a JSON object"
+"""Reason detail when a chain entry is not an object."""
+
+CONFIG_ENTRY_COMMAND_MISSING_REASON: str = "a chain entry has no string 'command'"
+"""Reason detail when a chain entry lacks a usable command."""
+
+CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON: str = (
+    "a chain entry's 'extra_args' is not a list of strings"
+)
+"""Reason detail when a chain entry's extra_args value is the wrong shape."""
+
+CONFIG_MISSING_MESSAGE_TEMPLATE: str = (
+    "Claude chain config not found at {config_path}. Copy {example_filename} to "
+    "{config_path} and list your logged-in claude binaries in fallback order."
+)
+"""Guidance shown when the config file is absent."""
+
+CONFIG_UNREADABLE_MESSAGE_TEMPLATE: str = (
+    "Cannot read claude chain config at {config_path}: {error}. "
+    "See {example_filename} for the expected shape."
+)
+"""Guidance shown when the config file cannot be read."""
+
+CONFIG_MALFORMED_MESSAGE_TEMPLATE: str = (
+    "Malformed JSON in claude chain config at {config_path}: {error}. "
+    "See {example_filename} for the expected shape."
+)
+"""Guidance shown when the config file is not valid JSON."""
+
+CONFIG_INVALID_SHAPE_MESSAGE_TEMPLATE: str = (
+    "Invalid claude chain config at {config_path}: {reason}. "
+    "See {example_filename} for the expected shape."
+)
+"""Guidance shown when the config JSON does not match the expected shape."""
+
+CHAIN_EXHAUSTED_MESSAGE_TEMPLATE: str = (
+    "No claude binary in the chain served the call. Attempts: {attempt_summary}"
+)
+"""CLI stderr message when the walk ends without a serving binary."""
+
+ATTEMPT_SUMMARY_ENTRY_TEMPLATE: str = "{command}={status}"
+"""Per-attempt fragment used to build the exhausted-chain summary."""
+
+ATTEMPT_SUMMARY_JOIN_SEPARATOR: str = ", "
+"""Separator joining per-attempt fragments in the exhausted-chain summary."""

package/scripts/dev_env_scripts_constants/gh_artifact_upload_constants.py

@@ -0,0 +1,43 @@
+"""Constants for the gh_artifact_upload script.
+
+Per the project's configuration conventions, script-level scalar constants
+live in dev_env_scripts_constants alongside timing.py.
+"""
+
+ARTIFACTS_RELEASE_TAG: str = "artifacts"
+"""Release tag that holds durable post artifacts."""
+
+ARTIFACTS_RELEASE_TITLE: str = "Durable post artifacts"
+"""Human-readable title for the artifacts release."""
+
+ARTIFACTS_RELEASE_NOTES: str = (
+    "Permanent storage for binary artifacts linked from GitHub issue and pull "
+    "request posts. Job scratch directories are ephemeral and get cleaned soon "
+    "after a run; assets uploaded to this prerelease persist so a durable post "
+    "can link a stable URL."
+)
+"""Release body written when the artifacts release is first created."""
+
+GH_BINARY_NAME: str = "gh"
+"""The GitHub CLI executable name."""
+
+ASSET_NAME_TIMESTAMP_FORMAT: str = "%Y%m%d_%H%M%S"
+"""strftime format for the timestamp prefix on an uploaded asset name."""
+
+ASSET_NAME_TEMPLATE: str = "{timestamp}_{basename}"
+"""Template joining the timestamp prefix and the source file basename."""
+
+RELEASE_ASSETS_JSON_KEY: str = "assets"
+"""``gh release view --json`` field holding the release's asset list."""
+
+ASSET_URL_JSON_KEY: str = "url"
+"""Asset field carrying the browser download URL GitHub serves."""
+
+ASSET_CREATED_AT_JSON_KEY: str = "createdAt"
+"""Asset field carrying the ISO 8601 creation timestamp."""
+
+NOTES_FILE_SUFFIX: str = ".md"
+"""Suffix for the temporary release-notes file."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for subprocess output and temp files."""

package/scripts/gh_artifact_upload.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""Upload a file to a repo's durable 'artifacts' release and print its URL.
+
+A durable GitHub post (issue, PR, comment, review) must not link a file under a
+job scratch directory or worktree, because that scratch is cleaned soon after
+the run while the post lives forever. Binary artifacts belong in a permanent
+place instead. This tool ensures the repo has a prerelease tagged ``artifacts``,
+uploads the given file under a timestamped asset name, and prints the permanent
+download URL a post can safely link. The timestamped name keeps each upload a
+distinct asset. An upload never overwrites an earlier one. A same-name collision
+fails loudly instead of replacing the bytes an existing URL already serves.
+
+Usage::
+
+    python3 gh_artifact_upload.py <file-path> <owner/repo>
+    -> https://github.com/<owner>/<repo>/releases/download/artifacts/20260707_140233_contact_sheet.png
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from dev_env_scripts_constants.gh_artifact_upload_constants import (
+    ARTIFACTS_RELEASE_NOTES,
+    ARTIFACTS_RELEASE_TAG,
+    ARTIFACTS_RELEASE_TITLE,
+    ASSET_CREATED_AT_JSON_KEY,
+    ASSET_NAME_TEMPLATE,
+    ASSET_NAME_TIMESTAMP_FORMAT,
+    ASSET_URL_JSON_KEY,
+    GH_BINARY_NAME,
+    NOTES_FILE_SUFFIX,
+    RELEASE_ASSETS_JSON_KEY,
+    UTF8_ENCODING,
+)
+
+
+class ArtifactUploadError(Exception):
+    """Raised when creating the release or uploading the asset fails."""
+
+
+def _run_gh(all_arguments: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [GH_BINARY_NAME, *all_arguments],
+        capture_output=True,
+        text=True,
+        encoding=UTF8_ENCODING,
+        check=False,
+    )
+
+
+def artifacts_release_exists(repository: str) -> bool:
+    """Return whether the durable artifacts release already exists in the repo.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        True when ``gh release view`` finds the ``artifacts`` release.
+    """
+    completion = _run_gh(
+        [
+            "release",
+            "view",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--json",
+            "tagName",
+        ]
+    )
+    return completion.returncode == 0
+
+
+def ensure_artifacts_release(repository: str) -> None:
+    """Create the artifacts prerelease when the repo does not already have it.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Raises:
+        ArtifactUploadError: When the release cannot be created.
+    """
+    if artifacts_release_exists(repository):
+        return
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=NOTES_FILE_SUFFIX, delete=False, encoding=UTF8_ENCODING
+    ) as notes_file:
+        notes_file.write(ARTIFACTS_RELEASE_NOTES)
+        notes_path = notes_file.name
+    completion = _run_gh(
+        [
+            "release",
+            "create",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--prerelease",
+            "--title",
+            ARTIFACTS_RELEASE_TITLE,
+            "--notes-file",
+            notes_path,
+        ]
+    )
+    Path(notes_path).unlink(missing_ok=True)
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+
+
+def timestamped_asset_name(file_path: str) -> str:
+    """Return ``YYYYMMDD_HHMMSS_<basename>`` for the given file path.
+
+    Args:
+        file_path: The source file to be uploaded.
+
+    Returns:
+        The asset name that prefixes the basename with the current timestamp.
+    """
+    current_timestamp = datetime.datetime.now().strftime(ASSET_NAME_TIMESTAMP_FORMAT)
+    return ASSET_NAME_TEMPLATE.format(
+        timestamp=current_timestamp, basename=Path(file_path).name
+    )
+
+
+def _uploaded_asset_download_url(repository: str) -> str:
+    """Read the just-uploaded asset's real download URL back from GitHub.
+
+    ::
+
+        upload "My Report.png" -> GitHub stores "..._My.Report.png"
+        read-back -> the URL GitHub serves for that sanitized name
+
+    GitHub sanitizes an asset filename on upload: spaces and other characters
+    become periods. The stored name, and so the download URL, can differ from
+    the local name. Reading the release back returns the URL GitHub actually
+    serves for the most recently created asset, which is the one just uploaded.
+
+    Args:
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        The browser download URL of the newest artifacts-release asset.
+
+    Raises:
+        ArtifactUploadError: When the read-back fails, the response cannot be
+            parsed, or no asset carries a download URL.
+    """
+    completion = _run_gh(
+        [
+            "release",
+            "view",
+            ARTIFACTS_RELEASE_TAG,
+            "--repo",
+            repository,
+            "--json",
+            RELEASE_ASSETS_JSON_KEY,
+        ]
+    )
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+    try:
+        parsed_release = json.loads(completion.stdout)
+    except json.JSONDecodeError as decode_error:
+        raise ArtifactUploadError(f"could not read release assets: {decode_error}")
+    all_assets = (
+        parsed_release.get(RELEASE_ASSETS_JSON_KEY, [])
+        if isinstance(parsed_release, dict)
+        else []
+    )
+    all_dated_assets = [
+        each_asset
+        for each_asset in all_assets
+        if isinstance(each_asset, dict) and each_asset.get(ASSET_CREATED_AT_JSON_KEY)
+    ]
+    if not all_dated_assets:
+        raise ArtifactUploadError("uploaded asset not found on read-back")
+    newest_asset = max(
+        all_dated_assets,
+        key=lambda each_asset: each_asset[ASSET_CREATED_AT_JSON_KEY],
+    )
+    asset_url = newest_asset.get(ASSET_URL_JSON_KEY)
+    if not isinstance(asset_url, str) or not asset_url:
+        raise ArtifactUploadError("uploaded asset carries no download URL on read-back")
+    return asset_url
+
+
+def upload_artifact(file_path: str, repository: str) -> str:
+    """Upload a file to the artifacts release and return its permanent URL.
+
+    Args:
+        file_path: The source file to upload.
+        repository: The ``owner/repo`` slug.
+
+    Returns:
+        The permanent download URL for the uploaded asset.
+
+    Raises:
+        ArtifactUploadError: When the file is missing or the upload fails.
+    """
+    source_path = Path(file_path)
+    if not source_path.is_file():
+        raise ArtifactUploadError(f"file not found: {file_path}")
+    ensure_artifacts_release(repository)
+    asset_name = timestamped_asset_name(file_path)
+    with tempfile.TemporaryDirectory() as staging_directory:
+        staged_asset_path = Path(staging_directory) / asset_name
+        shutil.copyfile(source_path, staged_asset_path)
+        completion = _run_gh(
+            [
+                "release",
+                "upload",
+                ARTIFACTS_RELEASE_TAG,
+                str(staged_asset_path),
+                "--repo",
+                repository,
+            ]
+        )
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+    return _uploaded_asset_download_url(repository)
+
+
+def main() -> int:
+    """Parse arguments, upload the file, and print the permanent asset URL.
+
+    Returns:
+        ``0`` when the upload succeeds, ``1`` when it fails.
+    """
+    parser = argparse.ArgumentParser(
+        description="Upload a file to a repo's durable 'artifacts' release."
+    )
+    parser.add_argument("file_path", help="Path to the file to upload.")
+    parser.add_argument(
+        "repository", metavar="owner/repo", help="Target GitHub repository slug."
+    )
+    parsed_arguments = parser.parse_args()
+    try:
+        asset_url = upload_artifact(
+            parsed_arguments.file_path, parsed_arguments.repository
+        )
+    except ArtifactUploadError as upload_error:
+        print(f"gh-artifact-upload failed: {upload_error}", file=sys.stderr)
+        return 1
+    print(asset_url)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sync_to_cursor/rules.py

@@ -68,7 +68,7 @@ _merged_mapping_key_order = (
 )
 
 _code_standards_section_order = (
-    "COMMENT PRESERVATION (ABSOLUTE RULE)",
+    "COMMENT PRESERVATION",
     "CORE PRINCIPLES",
     "⚡ HOOK-ENFORCED RULES",
     "3. REUSE CONSTANTS / 4. CONFIG LOCATIONS",