codeplain 0.2.3__tar.gz → 0.2.5__tar.gz

codeplain-0.2.5/.github/workflows/publish-install-script.yml

@@ -0,0 +1,39 @@
+name: Publish Install Scripts to R2
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'install/*.sh'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Upload to Cloudflare R2
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Upload install scripts to R2
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+        run: |
+          aws s3 cp install/install.sh s3://${R2_BUCKET}/install/install.sh \
+            --endpoint-url "${R2_ENDPOINT}" \
+            --content-type "text/plain"
+          echo "✓ install.sh uploaded to R2"
+
+          aws s3 cp install/walkthrough.sh s3://${R2_BUCKET}/install/walkthrough.sh \
+            --endpoint-url "${R2_ENDPOINT}" \
+            --content-type "text/plain"
+          echo "✓ walkthrough.sh uploaded to R2"
+
+          aws s3 cp install/examples.sh s3://${R2_BUCKET}/install/examples.sh \
+            --endpoint-url "${R2_ENDPOINT}" \
+            --content-type "text/plain"
+          echo "✓ examples.sh uploaded to R2"

{codeplain-0.2.3 → codeplain-0.2.5}/.gitignore

@@ -1,7 +1,7 @@
 __pycache__
 .DS_Store
 
-# Plain
+
 examples/**/build*/
 examples/**/conformance_tests/
 examples/**/conformance_tests.backup/
@@ -23,8 +23,10 @@ examples/**/node_plain_modules/
 *.log
 
 .venv
-build
 dist
 *.egg-info
 
-.env
+.env
+
+.coverage
+logging_config.yaml

{codeplain-0.2.3 → codeplain-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeplain
-Version: 0.2.3
+Version: 0.2.5
 Summary: Transform plain language specifications into working code
 License-File: LICENSE
 Classifier: Environment :: Console
@@ -14,13 +14,13 @@ Requires-Dist: networkx==3.6.1
 Requires-Dist: python-frontmatter==1.1.0
 Requires-Dist: python-liquid2==0.3.0
 Requires-Dist: pyyaml==6.0.2
-Requires-Dist: requests==2.32.3
+Requires-Dist: requests==2.32.4
 Requires-Dist: rich==14.2.0
 Requires-Dist: textual==1.0.0
 Requires-Dist: tiktoken==0.12.0
 Requires-Dist: transitions==0.9.3
 Provides-Extra: dev
-Requires-Dist: black==24.2.0; extra == 'dev'
+Requires-Dist: black==24.3.0; extra == 'dev'
 Requires-Dist: flake8==7.0.0; extra == 'dev'
 Requires-Dist: isort==5.13.2; extra == 'dev'
 Requires-Dist: mypy==1.11.2; extra == 'dev'

{codeplain-0.2.3 → codeplain-0.2.5}/codeplain_REST_api.py

@@ -2,7 +2,6 @@ import time
 from typing import Optional
 
 import requests
-from requests.exceptions import ConnectionError, RequestException, Timeout
 
 import plain2code_exceptions
 from plain2code_state import RunState
@@ -10,6 +9,22 @@ from plain2code_state import RunState
 MAX_RETRIES = 4
 RETRY_DELAY = 3
 
+# TODO: Handle connection errors
+RETRY_ERROR_CODES = [
+    "LLMInternalError",
+]
+
+# Mapping from API error codes to exception classes
+ERROR_CODE_EXCEPTIONS = {
+    "FunctionalRequirementTooComplex": plain2code_exceptions.FunctionalRequirementTooComplex,
+    "ConflictingRequirements": plain2code_exceptions.ConflictingRequirements,
+    "CreditBalanceTooLow": plain2code_exceptions.CreditBalanceTooLow,
+    "LLMInternalError": plain2code_exceptions.LLMInternalError,
+    "MissingResource": plain2code_exceptions.MissingResource,
+    "PlainSyntaxError": plain2code_exceptions.PlainSyntaxError,
+    "InternalServerError": plain2code_exceptions.InternalServerError,
+}
+
 
 class CodeplainAPI:
 
@@ -29,12 +44,31 @@ class CodeplainAPI:
         run_state.increment_call_count()
         payload["render_state"] = run_state.to_dict()
 
-    def post_request(self, endpoint_url, headers, payload, run_state: Optional[RunState]):  # noqa: C901
+    def _raise_for_error_code(self, response_json):
+        """Raise appropriate exception based on error code in response."""
+        error_code = response_json.get("error_code")
+        if error_code not in ERROR_CODE_EXCEPTIONS:
+            return
+
+        exception_class = ERROR_CODE_EXCEPTIONS[error_code]
+        message = response_json.get("message", "")
+
+        # FunctionalRequirementTooComplex has an extra parameter
+        if error_code == "FunctionalRequirementTooComplex":
+            raise exception_class(message, response_json.get("proposed_breakdown"))
+
+        raise exception_class(message)
+
+    def post_request(
+        self, endpoint_url, headers, payload, run_state: Optional[RunState], num_retries: int = MAX_RETRIES
+    ):
         if run_state is not None:
             self._extend_payload_with_run_state(payload, run_state)
 
         retry_delay = RETRY_DELAY
-        for attempt in range(MAX_RETRIES + 1):
+        response_json = None
+
+        for attempt in range(num_retries + 1):
             try:
                 response = requests.post(endpoint_url, headers=headers, json=payload)
 
@@ -45,53 +79,33 @@ class CodeplainAPI:
                     raise
 
                 if response.status_code == requests.codes.bad_request and "error_code" in response_json:
-                    if response_json["error_code"] == "FunctionalRequirementTooComplex":
-                        raise plain2code_exceptions.FunctionalRequirementTooComplex(
-                            response_json["message"], response_json.get("proposed_breakdown")
-                        )
-
-                    if response_json["error_code"] == "ConflictingRequirements":
-                        raise plain2code_exceptions.ConflictingRequirements(response_json["message"])
-
-                    if response_json["error_code"] == "CreditBalanceTooLow":
-                        raise plain2code_exceptions.CreditBalanceTooLow(response_json["message"])
-
-                    if response_json["error_code"] == "LLMInternalError":
-                        raise plain2code_exceptions.LLMInternalError(response_json["message"])
-
-                    if response_json["error_code"] == "MissingResource":
-                        raise plain2code_exceptions.MissingResource(response_json["message"])
-
-                    if response_json["error_code"] == "PlainSyntaxError":
-                        raise plain2code_exceptions.PlainSyntaxError(response_json["message"])
-
-                    if response_json["error_code"] == "OnlyRelativeLinksAllowed":
-                        raise plain2code_exceptions.OnlyRelativeLinksAllowed(response_json["message"])
-
-                    if response_json["error_code"] == "LinkMustHaveTextSpecified":
-                        raise plain2code_exceptions.LinkMustHaveTextSpecified(response_json["message"])
-
-                    if response_json["error_code"] == "NoRenderFound":
-                        raise plain2code_exceptions.NoRenderFound(response_json["message"])
-
-                    if response_json["error_code"] == "MultipleRendersFound":
-                        raise plain2code_exceptions.MultipleRendersFound(response_json["message"])
+                    self._raise_for_error_code(response_json)
 
                 response.raise_for_status()
                 return response_json
 
-            except (ConnectionError, Timeout, RequestException) as e:
-                if attempt < MAX_RETRIES:
-                    self.console.info(f"Connection error on attempt {attempt + 1}/{MAX_RETRIES + 1}: {e}")
+            except Exception as e:
+                if response_json is not None and "error_code" in response_json:
+                    if response_json["error_code"] not in RETRY_ERROR_CODES:
+                        raise e
+
+                if attempt < num_retries:
+                    self.console.info(f"Error on attempt {attempt + 1}/{num_retries + 1}: {e}")
                     self.console.info(f"Retrying in {retry_delay} seconds...")
                     time.sleep(retry_delay)
-                    # Exponential backoff
-                    retry_delay *= 2
+                    retry_delay *= 2  # Exponential backoff
                 else:
-                    self.console.error(f"Max retries ({MAX_RETRIES}) exceeded. Last error: {e}")
-                    raise RequestException(
-                        f"Connection error: Unable to reach the Codeplain API at {self.api_url}. Please try again or contact support."
-                    )
+                    self.console.error(f"Max retries ({num_retries}) exceeded. Last error: {e}")
+                    raise e
+
+    def connection_check(self, client_version):
+        endpoint_url = f"{self.api_url}/connection_check"
+        headers = {"Content-Type": "application/json"}
+        payload = {
+            "api_key": self.api_key,
+            "client_version": client_version,
+        }
+        return self.post_request(endpoint_url, headers, payload, None, num_retries=0)
 
     def render_functional_requirement(
         self,

codeplain-0.2.5/config/system_config.yaml

@@ -0,0 +1,12 @@
+client_version: "0.17.0"
+
+error_messages:
+  template_not_found:
+    message: |
+      The required template could not be found. Templates are searched in the following order (highest to lowest precedence):
+
+        1. The directory containing your .plain file
+        2. The directory specified by --template-dir (if provided)
+        3. The built-in 'standard_template_library' directory
+
+      Please ensure that the missing template exists in one of these locations, or specify the correct --template-dir if using custom templates.

{codeplain-0.2.3 → codeplain-0.2.5}/examples/example_hello_world_golang/hello_world_golang.plain

@@ -4,7 +4,7 @@ import:
   - golang-console-app-template
 ---
 
-***technical specs***
+***implementation reqs***
 
 - :MainExecutableFile: of :App: should be called "hello_world.go".
 

{codeplain-0.2.3 → codeplain-0.2.5}/examples/example_hello_world_python/hello_world_python.plain

@@ -4,7 +4,7 @@ import:
   - python-console-app-template
 ---
 
-***technical specs***
+***implementation reqs***
 
 - :MainExecutableFile: of :App: should be called "hello_world.py".
 

codeplain-0.2.5/examples/example_hello_world_react/config.yaml

@@ -0,0 +1,2 @@
+conformance-tests-script: ../../test_scripts/run_conformance_tests_cypress.sh
+verbose: true

{codeplain-0.2.3 → codeplain-0.2.5}/file_utils.py

@@ -43,6 +43,8 @@ FILE_EXTENSION_MAPPING = {
     ".bat": "Batch File",
 }
 
+SYSTEM_FOLDERS = [".git", CODEPLAIN_METADATA_FOLDER, CODEPLAIN_MEMORY_SUBFOLDER]
+
 
 def get_file_type(file_name):
 
@@ -55,10 +57,9 @@ def get_file_type(file_name):
 
 def list_all_text_files(directory):
     all_files = []
-    skip_dirs = [".git", CODEPLAIN_METADATA_FOLDER, CODEPLAIN_MEMORY_SUBFOLDER]
     for root, dirs, files in os.walk(directory, topdown=True):
         # Skip directories that should not be traversed
-        for skip_dir in skip_dirs:
+        for skip_dir in SYSTEM_FOLDERS:
             if skip_dir in dirs:
                 dirs.remove(skip_dir)
 
@@ -322,5 +323,5 @@ def copy_folder_to_output(source_folder, output_folder):
     if os.path.exists(output_folder):
         delete_files_and_subfolders(output_folder)
 
-    # Copy source folder contents directly to output folder (excluding .git)
-    copy_folder_content(source_folder, output_folder, ignore_folders=[".git"])
+    # Copy source folder contents directly to output folder (excluding SYSTEM_FOLDERS)
+    copy_folder_content(source_folder, output_folder, ignore_folders=SYSTEM_FOLDERS)

{codeplain-0.2.3 → codeplain-0.2.5}/git_utils.py

@@ -4,6 +4,7 @@ from typing import Optional, Union
 from git import Repo
 
 import file_utils
+from plain2code_exceptions import InvalidGitRepositoryError
 
 FUNCTIONAL_REQUIREMENT_IMPLEMENTED_COMMIT_MESSAGE = (
     "[Codeplain] Implemented code and unit tests for functional requirement {}"
@@ -25,12 +26,6 @@ MODULE_NAME_MESSAGE = "Module name: {}"
 RENDER_ID_MESSAGE = "Render ID: {}"
 
 
-class InvalidGitRepositoryError(Exception):
-    """Raised when the git repository is in an invalid state."""
-
-    pass
-
-
 def _get_full_commit_message(message, module_name, frid, render_id) -> str:
     full_message = message
 
@@ -252,7 +247,10 @@ def diff(repo_path: Union[str, os.PathLike], previous_frid: str = None) -> dict:
 
 def _get_commit(repo: Repo, frid: Optional[str]) -> str:
     if frid:
-        return _get_commit_with_frid(repo, frid)
+        commit_with_frid = _get_commit_with_frid(repo, frid)
+        if not commit_with_frid:
+            raise InvalidGitRepositoryError(f"No commit with frid {frid} found.")
+        return commit_with_frid
 
     base_folder_commit = _get_base_folder_commit(repo)
     initial_commit = _get_initial_commit(repo)
@@ -261,12 +259,44 @@ def _get_commit(repo: Repo, frid: Optional[str]) -> str:
     return initial_commit
 
 
-def _get_commit_with_frid(repo: Repo, frid: str) -> str:
-    """Finds commit with given frid mentioned in the commit message."""
-    commit = _get_commit_with_message(repo, FUNCTIONAL_REQUIREMENT_FINISHED_COMMIT_MESSAGE.format(frid))
-    if not commit:
-        raise InvalidGitRepositoryError(f"No commit with frid {frid} found.")
-    return commit
+def _get_commit_with_frid(repo: Repo, frid: str, module_name: Optional[str] = None) -> str:
+    """
+    Finds commit with given frid mentioned in the commit message.
+
+    Args:
+        repo (Repo): Git repository object
+        frid (str): Functional requirement ID
+        module_name (Optional[str]): Module name to filter by. If provided, only returns
+                                      commits that have both the FRID and module name.
+
+    Returns:
+        str: Commit SHA if found, empty string otherwise
+    """
+    commit_message_pattern = FUNCTIONAL_REQUIREMENT_FINISHED_COMMIT_MESSAGE.format(frid)
+
+    # If no module name filtering is needed, use the original logic
+    if not module_name:
+        return _get_commit_with_message(repo, commit_message_pattern)
+
+    # Use multiple grep patterns with --all-match for AND condition
+    escaped_frid_message = commit_message_pattern.replace("[", "\\[").replace("]", "\\]")
+    module_name_pattern = MODULE_NAME_MESSAGE.format(module_name)
+    escaped_module_message = module_name_pattern.replace("[", "\\[").replace("]", "\\]")
+
+    return repo.git.rev_list(
+        repo.active_branch.name,
+        "--grep",
+        escaped_frid_message,
+        "--grep",
+        escaped_module_message,
+        "--all-match",
+        "-n",
+        "1",
+    )
+
+
+def has_commit_for_frid(repo_path: Union[str, os.PathLike], frid: str, module_name: Optional[str] = None) -> bool:
+    return bool(_get_commit_with_frid(Repo(repo_path), frid, module_name))
 
 
 def _get_base_folder_commit(repo: Repo) -> str:

codeplain-0.2.5/install/examples.sh

@@ -0,0 +1,92 @@
+#!/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}"
+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://github.com/Codeplain-ai/plainlang-examples/archive/refs/tags/0.1.zip"
+
+# Show current directory and ask for extraction path
+CURRENT_DIR=$(pwd)
+echo -e "  current folder: ${YELLOW}${CURRENT_DIR}${NC}"
+echo ""
+echo -e "  extract examples here, or enter a different path:"
+echo ""
+read -r -p "  [Enter for current, or type path]: " EXTRACT_PATH < /dev/tty
+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}"
+    mkdir -p "$EXTRACT_PATH" 2>/dev/null
+    if [ $? -ne 0 ]; then
+        echo -e "  ${RED}✗${NC} failed to create directory: ${EXTRACT_PATH}"
+        echo -e "  ${GRAY}skipping example download.${NC}"
+        SKIP_DOWNLOAD=true
+    fi
+fi
+
+if [ "$SKIP_DOWNLOAD" = false ]; then
+    echo -e "  ${GRAY}downloading examples...${NC}"
+
+    # Download the zip file
+    TEMP_ZIP=$(mktemp)
+    curl -L -s -o "$TEMP_ZIP" "$EXAMPLES_DOWNLOAD_URL"
+
+    if [ $? -eq 0 ] && [ -s "$TEMP_ZIP" ]; then
+        echo -e "  ${GRAY}extracting to ${EXTRACT_PATH}...${NC}"
+
+        # Extract the zip file
+        unzip -q -o "$TEMP_ZIP" -d "$EXTRACT_PATH" 2>/dev/null
+
+        if [ $? -eq 0 ]; then
+            # Find and rename extracted directory to remove version number
+            EXTRACTED_DIR="${EXTRACT_PATH}/${EXAMPLES_FOLDER_NAME}"
+            VERSIONED_DIR=$(find "$EXTRACT_PATH" -maxdepth 1 -type d -name "${EXAMPLES_FOLDER_NAME}-*" | head -1)
+            if [ -n "$VERSIONED_DIR" ]; then
+                rm -rf "$EXTRACTED_DIR" 2>/dev/null  # Remove existing if present
+                mv "$VERSIONED_DIR" "$EXTRACTED_DIR"
+            fi
+
+            # Remove the .gitignore file from the root of the extracted directory
+            if [ -f "${EXTRACTED_DIR}/.gitignore" ]; then
+                rm -f "${EXTRACTED_DIR}/.gitignore"
+            fi
+
+            echo ""
+            echo -e "  ${GREEN}✓${NC} examples downloaded successfully!"
+            echo ""
+            echo -e "  examples are in: ${YELLOW}${EXTRACTED_DIR}${NC}"
+            echo ""
+        else
+            echo -e "  ${RED}✗${NC} failed to extract examples."
+        fi
+
+        # Clean up temp file
+        rm -f "$TEMP_ZIP"
+    else
+        echo -e "  ${RED}✗${NC} failed to download examples."
+        rm -f "$TEMP_ZIP"
+    fi
+
+    echo ""
+    read -r -p "  press [Enter] to continue..." < /dev/tty
+fi

{codeplain-0.2.3 → codeplain-0.2.5/install}/install.sh

@@ -2,6 +2,9 @@
 
 set -euo pipefail
 
+# Base URL for additional scripts
+CODEPLAIN_SCRIPTS_BASE_URL="${CODEPLAIN_SCRIPTS_BASE_URL:-https://codeplain.ai}"
+
 # Brand Colors (True Color / 24-bit)
 YELLOW='\033[38;2;224;255;110m'    # #E0FF6E
 GREEN='\033[38;2;121;252;150m'     # #79FC96
@@ -16,6 +19,10 @@ GRAY_LIGHT='\033[38;2;211;211;211m' # #D3D3D3
 BOLD='\033[1m'
 NC='\033[0m' # No Color / Reset
 
+# Export colors for child scripts
+export YELLOW GREEN GREEN_LIGHT GREEN_DARK BLUE BLACK WHITE RED GRAY GRAY_LIGHT BOLD NC
+
+clear
 echo -e "started ${YELLOW}${BOLD}*codeplain CLI${NC} installation..."
 
 # Install uv if not present
@@ -54,17 +61,36 @@ else
     echo -e "installing codeplain...${NC}"
     echo -e ""
     uv tool install codeplain
+    clear
     echo -e "${GREEN}✓ codeplain installed successfully!${NC}"
 fi
 
-echo -e "${GREEN}✓${NC} the latest version of *codeplain CLI is now installed."
-echo ""
-echo -e "go to ${YELLOW}https://platform.codeplain.ai${NC} and sign up to get your API key."
-echo ""
-read -p "paste your API key here: " API_KEY
-echo ""
+# Check if API key already exists
+SKIP_API_KEY_SETUP=false
+if [ -n "${CODEPLAIN_API_KEY:-}" ]; then
+    echo -e "  you already have an API key configured."
+    echo ""
+    echo -e "  would you like to log in and get a new one?"
+    echo ""
+    read -r -p "  [y/N]: " GET_NEW_KEY < /dev/tty
+    echo ""
 
-if [ -z "$API_KEY" ]; then
+    if [[ ! "$GET_NEW_KEY" =~ ^[Yy]$ ]]; then
+        echo -e "${GREEN}✓${NC} using existing API key."
+        SKIP_API_KEY_SETUP=true
+    fi
+fi
+
+if [ "$SKIP_API_KEY_SETUP" = false ]; then
+    echo -e "go to ${YELLOW}https://platform.codeplain.ai${NC} and sign up to get your API key."
+    echo ""
+    read -r -p "paste your API key here: " API_KEY < /dev/tty
+    echo ""
+fi
+
+if [ "$SKIP_API_KEY_SETUP" = true ]; then
+    : # API key already set, nothing to do
+elif [ -z "${API_KEY:-}" ]; then
     echo -e "${GRAY}no API key provided. you can set it later with:${NC}"
     echo -e "  export CODEPLAIN_API_KEY=\"your_api_key\""
 else
@@ -74,15 +100,10 @@ else
     # Detect user's default shell from $SHELL (works even when script runs in different shell)
     case "$SHELL" in
         */zsh)
-            SHELL_RC="$HOME/.zprofile"
+            SHELL_RC="$HOME/.zshrc"
             ;;
         */bash)
-            if [[ "$OSTYPE" == "darwin"* ]]; then
-                # macOS uses .bash_profile for login shells
-                SHELL_RC="$HOME/.bash_profile"
-            else
-                SHELL_RC="$HOME/.bashrc"
-            fi
+            SHELL_RC="$HOME/.bashrc"
             ;;
         *)
             SHELL_RC="$HOME/.profile"
@@ -105,12 +126,11 @@ else
         else
             sed -i "s|export CODEPLAIN_API_KEY=.*|export CODEPLAIN_API_KEY=\"$API_KEY\"|" "$SHELL_RC"
         fi
-        echo -e "${GREEN}✓${NC} API key added to ${SHELL_RC}"
     fi
-
 fi
 
 # ASCII Art Welcome
+clear
 echo ""
 echo -e "${NC}"
 echo -e "${GRAY}────────────────────────────────────────────${NC}"
@@ -124,6 +144,8 @@ cat << 'EOF'
                       |_|
 EOF
 echo ""
+echo -e "${GREEN}✓${NC} Sign in successful."
+echo ""
 echo -e "  ${YELLOW}welcome to *codeplain!${NC}"
 echo ""
 echo -e "  spec-driven, production-ready code generation"
@@ -131,6 +153,79 @@ echo ""
 echo ""
 echo -e "${GRAY}────────────────────────────────────────────${NC}"
 echo ""
+echo -e "  would you like to get a quick intro to ***plain specification language?"
+echo ""
+read -r -p "  [Y/n]: " WALKTHROUGH_CHOICE < /dev/tty
+echo ""
+
+# Determine script directory for local execution
+SCRIPT_DIR=""
+if [ -n "${BASH_SOURCE[0]:-}" ] && [ -f "${BASH_SOURCE[0]}" ]; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+fi
+
+# Helper function to run a script (local or remote)
+run_script() {
+    local script_name="$1"
+    local script_path=""
+
+    # Check possible local paths
+    if [ -n "$SCRIPT_DIR" ] && [ -f "${SCRIPT_DIR}/${script_name}" ]; then
+        script_path="${SCRIPT_DIR}/${script_name}"
+    elif [ -f "./install/${script_name}" ]; then
+        script_path="./install/${script_name}"
+    elif [ -f "./${script_name}" ]; then
+        script_path="./${script_name}"
+    fi
+
+    if [ -n "$script_path" ]; then
+        # Run locally
+        bash "$script_path" < /dev/tty
+    else
+        # Download and run
+        bash <(curl -fsSL "${CODEPLAIN_SCRIPTS_BASE_URL}/${script_name}") < /dev/tty
+    fi
+}
+
+# Run walkthrough if user agrees
+if [[ ! "$WALKTHROUGH_CHOICE" =~ ^[Nn]$ ]]; then
+    run_script "walkthrough.sh"
+fi
+
+# Download examples step
+clear
+echo ""
+echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo -e "  ${YELLOW}${BOLD}Example Projects${NC}"
+echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo ""
+echo -e "  we've prepared some example Plain projects for you"
+echo -e "  to explore and experiment with."
+echo ""
+echo -e "  would you like to download them?"
+echo ""
+read -r -p "  [Y/n]: " DOWNLOAD_EXAMPLES < /dev/tty
+echo ""
+
+# Run examples download if user agrees
+if [[ ! "${DOWNLOAD_EXAMPLES:-}" =~ ^[Nn]$ ]]; then
+    run_script "examples.sh"
+fi
+
+# Final message
+clear
+echo ""
+echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo -e "  ${YELLOW}${BOLD}You're all set!${NC}"
+echo -e "${GRAY}────────────────────────────────────────────${NC}"
+echo ""
 echo -e "  thank you for using *codeplain!"
 echo ""
-echo -e "  run '${YELLOW}${BOLD}codeplain <path_to_plain_file>${NC}' to get started."
+echo -e "  learn more at ${YELLOW}https://plainlang.org/${NC}"
+echo ""
+echo -e "  ${GREEN}happy development!${NC} 🚀"
+echo ""
+
+# Replace this subshell with a fresh shell that has the new environment
+# Reconnect stdin to terminal (needed when running via curl | bash)
+exec "$SHELL" < /dev/tty