codeplain 0.3.10.dev5__tar.gz → 0.3.11__tar.gz

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/.flake8

@@ -20,6 +20,8 @@ exclude =
 per-file-ignores =
     __init__.py: F401
     tests/*: U100
+# require_git() runs between imports in plain_modules.py, so the imports below it trip E402
+    plain_modules.py: E402
 max-complexity = 15
 enable-extensions = U100
 # Plugin-specific configuration

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeplain
-Version: 0.3.10.dev5
+Version: 0.3.11
 Summary: Transform plain language specifications into working code
 License-File: LICENSE
 Classifier: Environment :: Console
@@ -8,7 +8,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: ==3.11.*
-Requires-Dist: gitpython==3.1.55
+Requires-Dist: gitpython==3.1.59
 Requires-Dist: mistletoe==1.6.0
 Requires-Dist: networkx==3.6.1
 Requires-Dist: python-frontmatter==1.3.0
@@ -16,9 +16,9 @@ Requires-Dist: python-liquid2==0.4.0
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: requests==2.34.2
 Requires-Dist: rich==15.0.0
-Requires-Dist: sentry-sdk==2.66.1
+Requires-Dist: sentry-sdk==2.68.1
 Requires-Dist: textual>=7.5.0
-Requires-Dist: tiktoken==0.13.0
+Requires-Dist: tiktoken==0.14.0
 Requires-Dist: transitions==0.9.3
 Provides-Extra: dev
 Requires-Dist: black==26.5.1; extra == 'dev'

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/cli_output/status.py

@@ -6,6 +6,8 @@ from typing import Optional
 import codeplain_REST_api as codeplain_api
 from plain2code_console import console
 
+PLANS_URL = "https://platform.codeplain.ai/plans"
+
 
 def _create_progress_bar(remaining: int, total: int, width: int = 30) -> str:
     """Create a Unicode progress bar."""
@@ -42,12 +44,12 @@ def _display_credit_line(plan_credits: dict) -> None:
     bar = _create_progress_bar(remaining, total, width=30)
 
     # Format plan type label
-    plan_label = "Free trial" if plan_type == "free" else plan_type.upper() + " plan"
+    plan_label = "Free credits" if plan_type == "free" else plan_type.upper() + " plan"
 
     if is_expired:
-        console.print(f"    {plan_label:10} {bar}   expired {formatted_date}")
+        console.print(f"    {plan_label:12} {bar}   expired {formatted_date}")
     else:
-        console.print(f"    {plan_label:10} {bar}   {remaining:2} of {total} remaining    expires {formatted_date}")
+        console.print(f"    {plan_label:12} {bar}   {remaining:2} of {total} remaining    expires {formatted_date}")
 
 
 def _display_bucket_credit_line(bucket: dict, label: str) -> None:
@@ -71,9 +73,9 @@ def _display_bucket_credit_line(bucket: dict, label: str) -> None:
     bar = _create_progress_bar(remaining, total, width=30)
 
     if is_expired:
-        console.print(f"    {label:10} {bar}   expired {formatted_date}")
+        console.print(f"    {label:12} {bar}   expired {formatted_date}")
     else:
-        console.print(f"    {label:10} {bar}   {remaining:2} of {total} remaining    expires {formatted_date}")
+        console.print(f"    {label:12} {bar}   {remaining:2} of {total} remaining    expires {formatted_date}")
 
 
 def _display_status_message(plan_credits: Optional[dict], purchased_credits: list, promo_credits: list) -> None:
@@ -107,7 +109,11 @@ def _display_status_message(plan_credits: Optional[dict], purchased_credits: lis
             break
 
     if not has_remaining:
-        console.print("\nNo rendering credits remaining. Upgrade to continue rendering.")
+        console.print(
+            f"\nNo rendering credits remaining. Upgrade to the PRO plan at {PLANS_URL} to continue rendering."
+        )
+    else:
+        console.print(f"\nTo manage your plan navigate to {PLANS_URL}")
 
 
 def print_status(api_key: str, api_url: str, client_version: str) -> None:
@@ -148,7 +154,7 @@ def print_status(api_key: str, api_url: str, client_version: str) -> None:
     # Display rendering credits section
     console.print("Rendering credits:")
 
-    # Display plan credits (free trial or subscription)
+    # Display plan credits (free credits or subscription)
     if plan_credits:
         _display_credit_line(plan_credits)
 
@@ -162,4 +168,3 @@ def print_status(api_key: str, api_url: str, client_version: str) -> None:
 
     # Display status messages and management link
     _display_status_message(plan_credits, purchased_credits, promo_credits)
-    console.print("\nTo manage your plan navigate to https://platform.codeplain.ai/plans")

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/codeplain_REST_api.py

@@ -11,6 +11,10 @@ from plain2code_state import RunState
 MAX_RETRIES = 4
 RETRY_DELAY = 3
 
+# A report the render does not consume must not be able to hold the process open
+# at exit, and requests waits indefinitely by default.
+REPORT_TIMEOUT_SECONDS = 5
+
 RETRY_ERROR_CODES = [
     "LLMInternalError",
 ]
@@ -125,6 +129,7 @@ class CodeplainAPI:
         run_state: Optional[RunState],
         num_retries: int = MAX_RETRIES,
         silent: bool = False,
+        timeout: Optional[int] = None,
     ):
         if run_state is not None:
             self._extend_payload_with_run_state(payload, run_state)
@@ -134,7 +139,7 @@ class CodeplainAPI:
 
         for attempt in range(num_retries + 1):
             try:
-                response = requests.post(endpoint_url, headers=headers, json=payload)
+                response = requests.post(endpoint_url, headers=headers, json=payload, timeout=timeout)
 
                 try:
                     response_json = response.json()
@@ -173,6 +178,27 @@ class CodeplainAPI:
         }
         return self.post_request(endpoint_url, headers, payload, None, num_retries=0, silent=True)
 
+    def render_finished(self, outcome: str, run_state: RunState):
+        """Report the terminal state a render reached.
+
+        Called once per render, whatever the outcome. The render state machine
+        lives here, so the API cannot tell a finished render from one still
+        going; it has to be told.
+
+        No retries and no console output: a report has no result the render
+        needs, and must not add minutes to a render that has already ended nor
+        print retry noise over the exit summary.
+        """
+        endpoint_url = f"{self.api_url}/render_finished"
+        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}
+        payload = {
+            "outcome": outcome,
+        }
+
+        return self.post_request(
+            endpoint_url, headers, payload, run_state, num_retries=0, silent=True, timeout=REPORT_TIMEOUT_SECONDS
+        )
+
     def render_functional_requirement(
         self,
         frid: str,
@@ -237,6 +263,7 @@ class CodeplainAPI:
         required_modules,
         unittests_issue,
         run_state: RunState,
+        conformance_tests_fixes: list[dict] | None = None,
     ):
         endpoint_url = f"{self.api_url}/fix_unittests_issue"
         headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}
@@ -251,6 +278,10 @@ class CodeplainAPI:
             "unittests_issue": unittests_issue,
             "unittest_batch_id": run_state.unittest_batch_id,
         }
+        # Implementation code changes made by the conformance tests fixer right before this unit tests run;
+        # only sent when unit tests are processed inside the conformance tests phase.
+        if conformance_tests_fixes is not None:
+            payload["conformance_tests_fixes"] = conformance_tests_fixes
 
         return self.post_request(endpoint_url, headers, payload, run_state)
 

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/file_utils.py

@@ -180,6 +180,20 @@ def open_from(dirs, file_name):
     return None
 
 
+def resolve_linked_resource(dirs, file_name):
+    """Return the first existing path for file_name across dirs, or None if not found.
+
+    Mirrors the search order used by open_from so that validating a linked resource and
+    loading it can never disagree.
+    """
+    for dir in dirs:
+        full_file_name = os.path.join(dir, file_name)
+        if os.path.exists(full_file_name):
+            return full_file_name
+
+    return None
+
+
 def load_linked_resources(template_dirs: list[str], resources_list, module_name: str):
     linked_resources = {}
 

codeplain-0.3.11/git_preflight.py

@@ -0,0 +1,41 @@
+"""Verify a working git is available before GitPython is imported.
+
+GitPython probes for the git executable on import and raises from module scope
+if it is missing or broken, so the CLI would crash with a traceback before
+main() could explain it.
+"""
+
+import shutil
+import subprocess
+import sys
+
+from plain2code_console import console
+
+GIT_MISSING_MESSAGE = "git is not installed. Please install git and try again."
+GIT_BROKEN_MESSAGE = "git is installed but not working. Please repair your git installation and try again."
+MACOS_BROKEN_GIT_HINT = (
+    "This usually means the Command Line Tools are missing; install them with 'xcode-select --install'."
+)
+
+
+def git_runs(git_path):
+    """Whether `git version` succeeds. A git on PATH can still be unusable: on
+    macOS without the Command Line Tools /usr/bin/git is a stub that exits with
+    an xcrun error, and GIT_PYTHON_REFRESH=quiet does not suppress that."""
+    try:
+        return subprocess.run([git_path, "version"], capture_output=True, timeout=10).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def require_git():
+    """Exit with a clean message unless a working git is available."""
+    git_path = shutil.which("git")
+    if git_path is None:
+        console.error(f"{GIT_MISSING_MESSAGE}\n")
+        sys.exit(1)
+
+    if not git_runs(git_path):
+        hint = f"\n{MACOS_BROKEN_GIT_HINT}" if sys.platform == "darwin" else ""
+        console.error(f"{GIT_BROKEN_MESSAGE}{hint}\n")
+        sys.exit(1)

codeplain-0.3.11/install/bash/examples.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# Brand Colors (use exported colors if available, otherwise define them)
+YELLOW="${YELLOW:-\033[38;2;224;255;110m}"
+GREEN="${GREEN:-\033[38;2;121;252;150m}"
+WHITE="${WHITE:-\033[38;2;255;255;255m}"
+RED="${RED:-\033[38;2;239;68;68m}"
+GRAY="${GRAY:-\033[38;2;128;128;128m}"
+BOLD="${BOLD:-\033[1m}"
+NC="${NC:-\033[0m}"
+
+# Examples configuration
+EXAMPLES_FOLDER_NAME="plainlang-examples"
+EXAMPLES_DOWNLOAD_URL="https://codeplain.ai/examples/unix"
+
+# Prompt the user, reading from the terminal when there is one. Falling back to
+# stdin keeps the script usable in non-interactive environments instead of
+# dying on an unreadable /dev/tty.
+prompt_user() {
+    local prompt="$1"
+    local varname="$2"
+
+    # Test that /dev/tty can actually be opened: it exists but fails to open
+    # when the process has no controlling terminal.
+    if { : < /dev/tty; } 2>/dev/null; then
+        read -r -p "$prompt" "$varname" < /dev/tty || true
+    else
+        read -r -p "$prompt" "$varname" || true
+    fi
+}
+
+# Make the user acknowledge that the examples were not installed. The
+# installation continues either way, but the failure must not scroll past
+# unseen - the installer clears the screen in its next step.
+confirm_continue_after_failure() {
+    echo ""
+    echo -e "  ${YELLOW}The examples were not installed.${NC} ${GRAY}The installation will continue.${NC}"
+    echo ""
+    prompt_user "$(printf '%b' "  Continue? Press ${WHITE}[Enter]${NC} to acknowledge: ")" _ACKNOWLEDGED
+    echo ""
+}
+
+# Tell the user how to get unzip on their system, then let the installer move on.
+report_missing_unzip_tool() {
+    echo -e "  ${RED}✗ Cannot extract the examples: no 'unzip' command found.${NC}"
+    echo ""
+    echo -e "  ${GRAY}Install unzip and re-run the installer to get the examples:${NC}"
+    echo ""
+    case "$OSTYPE" in
+        darwin*)
+            echo -e "  ${WHITE}${BOLD}brew install unzip${NC}"
+            ;;
+        *)
+            echo -e "  ${WHITE}${BOLD}apt-get install unzip${NC}   ${GRAY}(Debian/Ubuntu)${NC}"
+            echo -e "  ${WHITE}${BOLD}dnf install unzip${NC}       ${GRAY}(Fedora/RHEL)${NC}"
+            echo -e "  ${WHITE}${BOLD}apk add unzip${NC}           ${GRAY}(Alpine)${NC}"
+            ;;
+    esac
+    echo ""
+    echo -e "  ${GRAY}The examples are also available at:${NC}"
+    echo -e "  ${WHITE}https://github.com/Codeplain-ai/plainlang-examples${NC}"
+    echo ""
+}
+
+# Checked before anything is downloaded, so a missing unzip is reported up
+# front instead of leaving the user with an installer that just stops.
+if ! command -v unzip &> /dev/null; then
+    report_missing_unzip_tool
+    confirm_continue_after_failure
+    exit 0
+fi
+
+# Show current directory and ask for extraction path
+CURRENT_DIR=$(pwd)
+echo -e "  Current folder: ${WHITE}${CURRENT_DIR}${NC}"
+echo ""
+echo -e "  Extract examples here, or enter a different path:"
+echo ""
+prompt_user "  [Enter for current, or type path]: " EXTRACT_PATH
+echo ""
+
+# Use current directory if empty
+if [ -z "${EXTRACT_PATH:-}" ]; then
+    EXTRACT_PATH="$CURRENT_DIR"
+fi
+
+# Expand ~ to home directory
+EXTRACT_PATH="${EXTRACT_PATH/#\~/$HOME}"
+
+SKIP_DOWNLOAD=false
+
+# Check if directory exists, create if not
+if [ ! -d "$EXTRACT_PATH" ]; then
+    echo -e "  ${GRAY}Creating directory...${NC}"
+    if ! mkdir -p "$EXTRACT_PATH" 2>/dev/null; then
+        echo -e "  ${RED}✗ Failed to create directory: ${EXTRACT_PATH}${NC}"
+        confirm_continue_after_failure
+        SKIP_DOWNLOAD=true
+    fi
+fi
+
+EXAMPLES_INSTALLED=false
+
+if [ "$SKIP_DOWNLOAD" = false ]; then
+    echo -e "  ${GRAY}Downloading examples...${NC}"
+
+    # Download the zip file
+    TEMP_ZIP=$(mktemp)
+    DOWNLOAD_OK=false
+    DOWNLOAD_ERROR="Could not download ${EXAMPLES_DOWNLOAD_URL}"
+    if curl -L -s -o "$TEMP_ZIP" "$EXAMPLES_DOWNLOAD_URL" && [ -s "$TEMP_ZIP" ]; then
+        DOWNLOAD_OK=true
+    fi
+
+    # A server error page is a successful download of the wrong thing, so check
+    # for the zip magic bytes rather than handing unzip an HTML page.
+    if [ "$DOWNLOAD_OK" = true ] && [ "$(head -c 2 "$TEMP_ZIP")" != "PK" ]; then
+        DOWNLOAD_OK=false
+        DOWNLOAD_ERROR="The downloaded file is not a zip archive."
+    fi
+
+    if [ "$DOWNLOAD_OK" = true ]; then
+        echo -e "  ${GRAY}Extracting to ${EXTRACT_PATH}...${NC}"
+
+        # Extract the zip file (contents are at the zip root, so extract into the target folder)
+        EXTRACTED_DIR="${EXTRACT_PATH}/${EXAMPLES_FOLDER_NAME}"
+        rm -rf "$EXTRACTED_DIR" 2>/dev/null || true  # Remove existing if present
+
+        # Keep the extractor's own error output: it is the only clue about why
+        # extraction failed (corrupt download, no disk space, no permissions).
+        if EXTRACT_OUTPUT=$(unzip -q -o "$TEMP_ZIP" -d "$EXTRACTED_DIR" 2>&1); then
+            # Remove the .gitignore file from the root of the extracted directory
+            if [ -f "${EXTRACTED_DIR}/.gitignore" ]; then
+                rm -f "${EXTRACTED_DIR}/.gitignore"
+            fi
+
+            clear || true
+            echo ""
+            echo -e "  ${GREEN}✓ Examples downloaded successfully!${NC}"
+            echo ""
+            echo -e "  ${GRAY}Examples are in: ${EXTRACTED_DIR}${NC}"
+            echo ""
+            echo -e "  ${WHITE}${BOLD}Try the hello, world example:${NC}"
+            echo ""
+            echo -e "  ${GRAY}Example folder:${NC} ${WHITE}cd ${EXTRACTED_DIR}/hello-world/python${NC}"
+            echo ""
+            echo -e "  ${GRAY}Render the example:${NC} ${WHITE}codeplain hello-world-python.plain${NC}"
+            echo ""
+            echo -e "  ${GRAY}See hello-world/python/README.md for details.${NC}"
+            echo ""
+            EXAMPLES_INSTALLED=true
+        else
+            echo -e "  ${RED}✗ Failed to extract examples.${NC}"
+            if [ -n "$EXTRACT_OUTPUT" ]; then
+                echo -e "  ${GRAY}$(echo "$EXTRACT_OUTPUT" | tail -n 3)${NC}"
+            fi
+        fi
+
+        # Clean up temp file
+        rm -f "$TEMP_ZIP"
+    else
+        echo -e "  ${RED}✗ Failed to download examples.${NC}"
+        echo -e "  ${GRAY}${DOWNLOAD_ERROR}${NC}"
+        rm -f "$TEMP_ZIP"
+    fi
+
+    if [ "$EXAMPLES_INSTALLED" = true ]; then
+        echo ""
+        prompt_user "$(printf '%b' "  Press ${WHITE}[Enter]${NC} to continue...")" _CONTINUE
+    else
+        confirm_continue_after_failure
+    fi
+fi

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/install/bash/install.sh

@@ -425,9 +425,11 @@ else
     echo ""
 fi
 
-# Run examples download if user agrees
+# Run examples download if user agrees. The examples are a nice-to-have, so a
+# failure there must never abort the installation (set -e would otherwise take
+# the whole installer down without printing anything).
 if [[ ! "${DOWNLOAD_EXAMPLES:-}" =~ ^[Nn]$ ]]; then
-    run_script "examples.sh"
+    run_script "examples.sh" || echo -e "${GRAY}Example download did not complete. Continuing with the installation.${NC}"
 fi
 
 # Final verification: make sure the installed codeplain can actually run and

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/install/powershell/examples.ps1

@@ -19,6 +19,39 @@ $CROSS = [char]0x2717
 $EXAMPLES_FOLDER_NAME = "plainlang-examples"
 $EXAMPLES_DOWNLOAD_URL = "https://codeplain.ai/examples/windows"
 
+# Make the user acknowledge that the examples were not installed. The
+# installation continues either way, but the failure must not scroll past
+# unseen - the installer clears the screen in its next step.
+function Confirm-ContinueAfterFailure {
+    Write-Host ""
+    Write-Host "  ${YELLOW}The examples were not installed.${NC} ${GRAY}The installation will continue.${NC}"
+    Write-Host ""
+    Read-Host "  Continue? Press ${WHITE}[Enter]${NC} to acknowledge"
+    Write-Host ""
+}
+
+# Expand-Archive lives in the Microsoft.PowerShell.Archive module, shipped with
+# PowerShell 5.0 and later. Checked before anything is downloaded, so a machine
+# without it is told what to do instead of just seeing an extraction failure.
+function Show-MissingArchiveCmdletMessage {
+    Write-Host "  ${RED}${CROSS} Cannot extract the examples: Expand-Archive is not available.${NC}"
+    Write-Host ""
+    Write-Host "  ${GRAY}Expand-Archive requires PowerShell 5.0 or later. Install a newer${NC}"
+    Write-Host "  ${GRAY}PowerShell and re-run the installer to get the examples:${NC}"
+    Write-Host ""
+    Write-Host "  ${WHITE}${BOLD}https://aka.ms/powershell${NC}"
+    Write-Host ""
+    Write-Host "  ${GRAY}The examples are also available at:${NC}"
+    Write-Host "  ${WHITE}https://github.com/Codeplain-ai/plainlang-examples${NC}"
+    Write-Host ""
+}
+
+if (-not (Get-Command Expand-Archive -ErrorAction SilentlyContinue)) {
+    Show-MissingArchiveCmdletMessage
+    Confirm-ContinueAfterFailure
+    exit 0
+}
+
 # Show current directory and ask for extraction path
 $CURRENT_DIR = Get-Location
 Write-Host "  Current folder: ${WHITE}${CURRENT_DIR}${NC}"
@@ -47,11 +80,13 @@ if (-not (Test-Path $EXTRACT_PATH -PathType Container)) {
         New-Item -ItemType Directory -Path $EXTRACT_PATH -Force | Out-Null
     } catch {
         Write-Host "  ${RED}${CROSS} Failed to create directory: ${EXTRACT_PATH}${NC}"
-        Write-Host "  ${GRAY}Skipping example download.${NC}"
+        Confirm-ContinueAfterFailure
         $SKIP_DOWNLOAD = $true
     }
 }
 
+$EXAMPLES_INSTALLED = $false
+
 if (-not $SKIP_DOWNLOAD) {
     Write-Host "  ${GRAY}Downloading examples...${NC}"
 
@@ -60,7 +95,26 @@ if (-not $SKIP_DOWNLOAD) {
     try {
         Invoke-WebRequest -Uri $EXAMPLES_DOWNLOAD_URL -OutFile $TEMP_ZIP -UseBasicParsing
 
+        # Check for the zip magic bytes rather than handing Expand-Archive a
+        # server error page. Read via a stream: 'Get-Content -Encoding Byte' is
+        # Windows PowerShell 5.1 only, '-AsByteStream' is PowerShell 6+ only.
+        $IS_ZIP = $false
         if (Test-Path $TEMP_ZIP) {
+            $HEADER = New-Object byte[] 2
+            $STREAM = [System.IO.File]::OpenRead($TEMP_ZIP)
+            try {
+                $BYTES_READ = $STREAM.Read($HEADER, 0, 2)
+            } finally {
+                $STREAM.Close()
+            }
+            $IS_ZIP = ($BYTES_READ -eq 2 -and $HEADER[0] -eq 0x50 -and $HEADER[1] -eq 0x4B)
+        }
+
+        if (-not $IS_ZIP -and (Test-Path $TEMP_ZIP)) {
+            Write-Host "  ${RED}${CROSS} Failed to download examples.${NC}"
+            Write-Host "  ${GRAY}The downloaded file is not a zip archive.${NC}"
+            Remove-Item -Path $TEMP_ZIP -Force -ErrorAction SilentlyContinue
+        } elseif ($IS_ZIP) {
             Write-Host "  ${GRAY}Extracting to ${EXTRACT_PATH}...${NC}"
 
             try {
@@ -91,8 +145,12 @@ if (-not $SKIP_DOWNLOAD) {
                 Write-Host ""
                 Write-Host "  ${GRAY}See hello-world/python/README.md for details.${NC}"
                 Write-Host ""
+                $EXAMPLES_INSTALLED = $true
             } catch {
+                # Keep the cmdlet's own message: it is the only clue about why
+                # extraction failed (corrupt download, no space, no permissions).
                 Write-Host "  ${RED}${CROSS} Failed to extract examples.${NC}"
+                Write-Host "  ${GRAY}$($_.Exception.Message)${NC}"
             }
 
             Remove-Item -Path $TEMP_ZIP -Force -ErrorAction SilentlyContinue
@@ -104,6 +162,10 @@ if (-not $SKIP_DOWNLOAD) {
         Remove-Item -Path $TEMP_ZIP -Force -ErrorAction SilentlyContinue
     }
 
-    Write-Host ""
-    Read-Host "  Press ${WHITE}[Enter]${NC} to continue..."
+    if ($EXAMPLES_INSTALLED) {
+        Write-Host ""
+        Read-Host "  Press ${WHITE}[Enter]${NC} to continue..."
+    } else {
+        Confirm-ContinueAfterFailure
+    }
 }

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/install/powershell/install.ps1

@@ -526,9 +526,16 @@ if ($nonInteractive) {
     Write-Host ""
 }
 
-# Run examples download if user agrees
+# Run examples download if user agrees. The examples are a nice-to-have, so a
+# failure there must never abort the installation: examples.ps1 runs in this
+# runspace via the call operator, so a terminating error inside it would
+# otherwise propagate here and take the whole installer down.
 if ($downloadExamples -notmatch '^[Nn]$') {
-    Invoke-SubScript "examples.ps1"
+    try {
+        Invoke-SubScript "examples.ps1"
+    } catch {
+        Write-Host "${GRAY}Example download did not complete. Continuing with the installation.${NC}"
+    }
 }
 
 # Final verification: make sure the installed codeplain can actually run and

{codeplain-0.3.10.dev5 → codeplain-0.3.11}/plain2code.py

@@ -61,6 +61,11 @@ from tui.plain_module_render_choice_tui import PlainModuleRenderChoiceTUI
 DEFAULT_TEMPLATE_DIRS = "standard_template_library"
 RENDER_THREAD_SHUTDOWN_TIMEOUT = 0.7
 
+# The terminal states a render can reach, as the API names them.
+RENDER_OUTCOME_COMPLETED = "completed"
+RENDER_OUTCOME_FAILED = "failed"
+RENDER_OUTCOME_CANCELLED = "cancelled"
+
 # Exceptions that represent expected, user-facing error conditions. They are
 # reported to the user directly and must never be sent to Sentry as crashes.
 EXPECTED_EXCEPTIONS = (
@@ -177,6 +182,52 @@ def _check_connection(codeplainAPI: codeplain_api.CodeplainAPI) -> Optional[str]
     return response.get("user_email")
 
 
+def _render_outcome(run_state: RunState, interrupted: bool = False) -> str:
+    """Name the terminal state a render reached.
+
+    Ctrl-C is the user stopping the render, so it is a cancellation. It does not
+    set render_cancelled: the exit summary reads that flag, and its wording for
+    an interrupt stays as it is.
+
+    Cancellation is tested first. A cancelled render leaves render_succeeded
+    False, so asking about success first would report it as a failure.
+    """
+    if interrupted or run_state.render_cancelled:
+        return RENDER_OUTCOME_CANCELLED
+    if run_state.render_succeeded:
+        return RENDER_OUTCOME_COMPLETED
+    return RENDER_OUTCOME_FAILED
+
+
+def report_render_finished(
+    codeplainAPI: codeplain_api.CodeplainAPI, run_state: RunState, interrupted: bool = False
+) -> None:
+    """Tell the API which terminal state this render reached.
+
+    The API cannot work it out for itself - the state machine lives here - and
+    main()'s finally is the one place that sees every ending: success, failure,
+    cancellation, an unexpected crash and a keyboard interrupt alike. The state
+    machine's own completed and failed hooks see only two of the five.
+
+    Reported only once the connection check has set a user email, which is
+    exactly the condition "the API knows who we are". A missing key, an invalid
+    key and an outdated client all leave it unset, and none of them got as far
+    as a render.
+
+    Never raises. A report must not change the exit code, and must not mask the
+    error that ended the render.
+    """
+    if not run_state.user_email:
+        return
+
+    try:
+        codeplainAPI.render_finished(_render_outcome(run_state, interrupted), run_state)
+    except Exception:
+        # Deliberately silent: logging has stopped by now, and a failed report
+        # is not the user's problem.
+        pass
+
+
 def warn_if_acceptance_tests_without_conformance_script(plain_module, args) -> None:
     """Warn when any loaded module (including required modules) defines acceptance tests
     but no conformance tests script is configured.
@@ -214,6 +265,7 @@ def validate_linked_resources(plain_module) -> None:
 
 def render(  # noqa: C901
     plain_module: plain_modules.PlainModule,
+    codeplainAPI: codeplain_api.CodeplainAPI,
     args,
     run_state: RunState,
     event_bus: EventBus,
@@ -224,10 +276,6 @@ def render(  # noqa: C901
     if args.render_range or args.render_from:
         render_range = plain_spec.compute_render_range(args, plain_module.plain_source)
 
-    codeplainAPI = codeplain_api.CodeplainAPI(args.api_key, console)
-    assert args.api is not None and args.api != "", "API URL is required"
-    codeplainAPI.api_url = args.api
-
     run_state.user_email = _check_connection(codeplainAPI)
 
     stop_event = threading.Event()
@@ -419,6 +467,10 @@ def main():  # noqa: C901
     if not args.api:
         args.api = system_config.default_api_url
 
+    assert args.api is not None and args.api != "", "API URL is required"
+    codeplainAPI = codeplain_api.CodeplainAPI(args.api_key, console)
+    codeplainAPI.api_url = args.api
+
     run_state = RunState(spec_filename=args.filename, replay_with=args.replay_with)
 
     if args.headless:
@@ -431,6 +483,7 @@ def main():  # noqa: C901
 
     exc_info = None
     error_message = None
+    interrupted = False
 
     try:
         # Validate API key is present
@@ -438,10 +491,11 @@ def main():  # noqa: C901
             raise MissingAPIKey(
                 "Your API key is required. Please set the CODEPLAIN_API_KEY environment variable or provide it with the --api-key argument.\n"
             )
-        render(plain_module, args, run_state, event_bus, default_log_level)
+        render(plain_module, codeplainAPI, args, run_state, event_bus, default_log_level)
     except BaseException as e:
         if isinstance(e, KeyboardInterrupt):
             error_message = "Keyboard interrupt"
+            interrupted = True
         else:
             error_message = str(e) if str(e) else repr(e)
 
@@ -460,6 +514,8 @@ def main():  # noqa: C901
         # Remove any scratch extractions created for archive-only ("<module>.module") modules.
         for module in plain_module.all_required_modules + [plain_module]:
             module.cleanup_scratch()
+        # Last, so nothing the user is waiting for sits behind a network call.
+        report_render_finished(codeplainAPI, run_state, interrupted)
 
     if args.headless and (exc_info is not None or not run_state.render_succeeded):
         sys.exit(1)