codeplain 0.3.4__tar.gz → 0.3.6__tar.gz

{codeplain-0.3.4 → codeplain-0.3.6}/CLAUDE.md

@@ -179,7 +179,7 @@ black . --check && isort . --check-only && flake8 . && mypy . --check-untyped-de
 - `plain2code_logger.py` - Custom logging with elapsed time timestamps
 - `plain2code_console.py` - Rich console wrapper with custom styles
 - `plain2code_state.py` - Runtime state (render ID, counters, timing)
-- `standard_template_library/` - Built-in code templates
+- `standard_template_library/` - Built-in `.plain` templates (git subtree from `plainlang-examples`)
 - `examples/` - Sample `.plain` projects
 
 ### Testing Architecture
@@ -223,6 +223,26 @@ Two logging modes:
 ### Running Plain2Code from Another Directory
 The tool can be run from any directory by providing an absolute or relative path to the `.plain` file. All paths (build folder, log file, templates) are resolved relative to the `.plain` file's directory, not the current working directory, unless explicitly overridden via CLI arguments.
 
+### Standard Template Library
+
+`standard_template_library/` is a git subtree sourced from the `plainlang-examples` repository. It is **not** updated automatically — you must pull changes manually when the templates change upstream:
+
+```bash
+git subtree pull --prefix=standard_template_library git@github.com:Codeplain-ai/plainlang-examples.git subtree/standard-template-library --squash
+```
+
+The subtree does not track a branch pointer. The branch (`main` above) is just an argument passed at pull time — git uses the `git-subtree-split` hash embedded in the commit history to determine what's new since the last sync.
+
+**Important:** You must pull from the `subtree/standard-template-library` branch, not `main`. This is a split branch containing only the `standard_template_library/` subdirectory contents at root level. Pulling from `main` would bring in the entire `plainlang-examples` repo.
+
+If the split branch is outdated, regenerate it first in `plainlang-examples`:
+
+```bash
+# In plainlang-examples/
+git subtree split --prefix=standard_template_library -b subtree/standard-template-library
+git push origin subtree/standard-template-library
+```
+
 ### Windows Support
 Windows users must use WSL (Windows Subsystem for Linux). The codebase has some platform-specific script handling (`.ps1` for Windows, `.sh` for Unix).
 

codeplain-0.3.6/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: codeplain
+Version: 0.3.6
+Summary: Transform plain language specifications into working code
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: ==3.11.*
+Requires-Dist: gitpython==3.1.50
+Requires-Dist: mistletoe==1.3.0
+Requires-Dist: networkx==3.6.1
+Requires-Dist: python-frontmatter==1.3.0
+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.63.0
+Requires-Dist: textual>=7.5.0
+Requires-Dist: tiktoken==0.13.0
+Requires-Dist: transitions==0.9.3
+Provides-Extra: dev
+Requires-Dist: black==26.3.1; extra == 'dev'
+Requires-Dist: flake8==7.3.0; extra == 'dev'
+Requires-Dist: isort==5.13.2; extra == 'dev'
+Requires-Dist: mypy==2.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# *codeplain renderer
+
+## What is \*codeplain?
+
+\*codeplain platform makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+This repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the *codeplain API.
+
+The result is a software development workflow centered on specifications, which are faster and more efficient for AI to produce and easier for developers to review and maintain than raw code.
+
+Schematic overview of the *codeplain's code rendering:
+
+<img src="https://raw.githubusercontent.com/Codeplain-ai/plain2code_client/main/resources/codeplain_overview.png">
+
+## Getting started
+
+Get started in 15 minutes.
+
+### 1. Install \*codeplain in the terminal
+
+macOS and Linux:
+
+```bash
+curl -fsSL https://codeplain.ai/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://codeplain.ai/install.ps1 | iex
+```
+
+**Windows users:** Please install WSL (Windows Subsystem for Linux) as this is currently the supported environment for running plain code on Windows.
+
+Follow the installation instructions to complete setup. The installer installs the `codeplain` CLI, walks you through setting your `CODEPLAIN_API_KEY`, and offers to set up [plain-forge](#2-let-your-agent-work-in-specs-not-code) and the [plyn editor extension](#vs-code--cursor-extension) for you in the same session.
+
+If you'd rather not run the installer, sign up at [platform.codeplain.ai](https://platform.codeplain.ai) to get your API key and export it yourself:
+
+```bash
+export CODEPLAIN_API_KEY="your_actual_api_key_here"
+```
+
+### 2. Let your agent work in specs, not code
+
+You describe what you want in plain English, an agent helps you write a spec in \*\*\*plain language, and \*codeplain renders the actual code. This is what [plain-forge](https://github.com/Codeplain-ai/plain-forge) sets up: a toolkit of skills, rules, and docs that plugs into your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, or any other agent that reads from a standard skills directory — and turns a conversation into a complete `.plain` spec, then keeps maintaining it across the lifetime of the project.
+
+If you didn't install it during step 1, run it any time:
+
+```bash
+npx plain-forge install
+```
+
+### 3. Convert specs into tested and validated code
+
+\*codeplain extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+```bash
+codeplain your-project.plain
+```
+
+### Try it now
+
+You can immediately test the system with a simple "Hello World" example:
+
+- Change to the example folder and run the example:
+
+  ```bash
+  cd examples/example_hello_world_python
+  codeplain hello_world_python.plain
+  ```
+
+  _Note: Rendering will take a few minutes to complete._
+
+- The system will generate a Python application in the `build` directory. You can run it with:
+  ```bash
+  cd build
+  python hello_world.py
+  ```
+
+### VS Code / Cursor extension
+
+If you're using Visual Studio Code or Cursor IDE, we also recommend installing the [plyn extension](https://marketplace.visualstudio.com/items?itemName=Codeplain.plyn) for `***plain` syntax highlighting. The installer in step 1 offers to install it automatically if it detects `code` or `cursor` on your `PATH`.
+
+### Community and support
+
+Share what you're building! Join the [\*codeplain Discord](https://discord.gg/cgbynb9hFq) if you have questions, ideas, or want to share what you built.
+
+Hit an edge case or have feedback? Reach us at [support@codeplain.ai](mailto:support@codeplain.ai).
+
+## Abstracting Away Code Generation Complexity with \*\*\*plain
+
+\*\*\*plain is the language of spec-driven development — a specification language that combines the efficiency of natural language with the control and precision of code.
+
+Structured sections for definitions, functional specs, implementation requirements, test requirements, and acceptance tests let your specs (not scattered docs or ad hoc prompts) become the source of truth for your software's behavior, abstracting away the complexity of using large language models for code generation.
+
+Specs are plain text, so they fit into the workflows you already use — version control, pull requests, and code review.
+
+See the [\*\*\*plain language guide](https://www.plainlang.org/docs/language-guide/) to learn the full syntax.
+
+An example application in \*\*\*plain
+
+<img src="resources/plain_example.png" width="70%" height="70%">
+
+## Additional Resources
+
+### Examples and Sample Projects
+
+- See the [examples](examples) folder for sample projects in Golang, Python, React, and Flutter.
+- For an example of how to implement Pong in \*\*\*plain, see the [pong](https://github.com/Codeplain-ai/plainlang-examples/tree/main/pong) example.
+- For an example of how to implement a task manager in \*\*\*plain, see the [task-manager](https://github.com/Codeplain-ai/plainlang-examples/tree/main/task-manager) example.
+
+### Documentation
+
+- For more details on the ***plain format, see the [***plain language specification](https://www.plainlang.org/docs/).

codeplain-0.3.6/README.md

@@ -0,0 +1,114 @@
+# *codeplain renderer
+
+## What is \*codeplain?
+
+\*codeplain platform makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+This repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the *codeplain API.
+
+The result is a software development workflow centered on specifications, which are faster and more efficient for AI to produce and easier for developers to review and maintain than raw code.
+
+Schematic overview of the *codeplain's code rendering:
+
+<img src="https://raw.githubusercontent.com/Codeplain-ai/plain2code_client/main/resources/codeplain_overview.png">
+
+## Getting started
+
+Get started in 15 minutes.
+
+### 1. Install \*codeplain in the terminal
+
+macOS and Linux:
+
+```bash
+curl -fsSL https://codeplain.ai/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://codeplain.ai/install.ps1 | iex
+```
+
+**Windows users:** Please install WSL (Windows Subsystem for Linux) as this is currently the supported environment for running plain code on Windows.
+
+Follow the installation instructions to complete setup. The installer installs the `codeplain` CLI, walks you through setting your `CODEPLAIN_API_KEY`, and offers to set up [plain-forge](#2-let-your-agent-work-in-specs-not-code) and the [plyn editor extension](#vs-code--cursor-extension) for you in the same session.
+
+If you'd rather not run the installer, sign up at [platform.codeplain.ai](https://platform.codeplain.ai) to get your API key and export it yourself:
+
+```bash
+export CODEPLAIN_API_KEY="your_actual_api_key_here"
+```
+
+### 2. Let your agent work in specs, not code
+
+You describe what you want in plain English, an agent helps you write a spec in \*\*\*plain language, and \*codeplain renders the actual code. This is what [plain-forge](https://github.com/Codeplain-ai/plain-forge) sets up: a toolkit of skills, rules, and docs that plugs into your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, or any other agent that reads from a standard skills directory — and turns a conversation into a complete `.plain` spec, then keeps maintaining it across the lifetime of the project.
+
+If you didn't install it during step 1, run it any time:
+
+```bash
+npx plain-forge install
+```
+
+### 3. Convert specs into tested and validated code
+
+\*codeplain extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+```bash
+codeplain your-project.plain
+```
+
+### Try it now
+
+You can immediately test the system with a simple "Hello World" example:
+
+- Change to the example folder and run the example:
+
+  ```bash
+  cd examples/example_hello_world_python
+  codeplain hello_world_python.plain
+  ```
+
+  _Note: Rendering will take a few minutes to complete._
+
+- The system will generate a Python application in the `build` directory. You can run it with:
+  ```bash
+  cd build
+  python hello_world.py
+  ```
+
+### VS Code / Cursor extension
+
+If you're using Visual Studio Code or Cursor IDE, we also recommend installing the [plyn extension](https://marketplace.visualstudio.com/items?itemName=Codeplain.plyn) for `***plain` syntax highlighting. The installer in step 1 offers to install it automatically if it detects `code` or `cursor` on your `PATH`.
+
+### Community and support
+
+Share what you're building! Join the [\*codeplain Discord](https://discord.gg/cgbynb9hFq) if you have questions, ideas, or want to share what you built.
+
+Hit an edge case or have feedback? Reach us at [support@codeplain.ai](mailto:support@codeplain.ai).
+
+## Abstracting Away Code Generation Complexity with \*\*\*plain
+
+\*\*\*plain is the language of spec-driven development — a specification language that combines the efficiency of natural language with the control and precision of code.
+
+Structured sections for definitions, functional specs, implementation requirements, test requirements, and acceptance tests let your specs (not scattered docs or ad hoc prompts) become the source of truth for your software's behavior, abstracting away the complexity of using large language models for code generation.
+
+Specs are plain text, so they fit into the workflows you already use — version control, pull requests, and code review.
+
+See the [\*\*\*plain language guide](https://www.plainlang.org/docs/language-guide/) to learn the full syntax.
+
+An example application in \*\*\*plain
+
+<img src="resources/plain_example.png" width="70%" height="70%">
+
+## Additional Resources
+
+### Examples and Sample Projects
+
+- See the [examples](examples) folder for sample projects in Golang, Python, React, and Flutter.
+- For an example of how to implement Pong in \*\*\*plain, see the [pong](https://github.com/Codeplain-ai/plainlang-examples/tree/main/pong) example.
+- For an example of how to implement a task manager in \*\*\*plain, see the [task-manager](https://github.com/Codeplain-ai/plainlang-examples/tree/main/task-manager) example.
+
+### Documentation
+
+- For more details on the ***plain format, see the [***plain language specification](https://www.plainlang.org/docs/).

codeplain-0.3.6/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.6"

{codeplain-0.3.4 → codeplain-0.3.6}/file_utils.py

@@ -8,8 +8,9 @@ from liquid2.exceptions import UndefinedError
 
 import plain_spec
 from plain2code_console import console
-from plain2code_exceptions import UnsupportedResourceType
+from plain2code_exceptions import UnsupportedBase64Content, UnsupportedResourceType
 from plain2code_nodes import Plain2CodeIncludeTag, Plain2CodeLoaderMixin
+from plain2code_utils import find_large_base64_blob
 from plain_modules import CODEPLAIN_MEMORY_SUBFOLDER, CODEPLAIN_METADATA_FOLDER
 
 BINARY_FILE_EXTENSIONS = [".pyc"]
@@ -157,7 +158,7 @@ def store_response_files(target_folder, response_files, existing_files):
 
         os.makedirs(os.path.dirname(full_file_name), exist_ok=True)
 
-        with open(full_file_name, "w") as f:
+        with open(full_file_name, "w", encoding="utf-8") as f:
             f.write(response_files[file_name])
 
         if file_name not in existing_files:
@@ -206,6 +207,16 @@ def load_linked_resources(template_dirs: list[str], resources_list, module_name:
                 Please ensure that the resource exists in one of these locations, or specify the correct --template-dir if using custom templates.
                 """)
 
+        blob = find_large_base64_blob(content)
+        if blob is not None:
+            raise UnsupportedBase64Content(
+                f"Referenced resource '{file_name}' in module '{module_name}' contains a large "
+                f"base64-encoded blob ({len(blob)} characters), such as an embedded image. Inline "
+                "base64 data is not supported. Remove the data from the resource. "
+                "If the data should be used by the end software, "
+                "save the data to a separate file and include the file path in the specification without it being a reference file."
+            )
+
         linked_resources[file_name] = content
 
     return linked_resources

{codeplain-0.3.4 → codeplain-0.3.6}/install/bash/examples.sh

@@ -5,6 +5,7 @@ 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}"
@@ -16,9 +17,9 @@ EXAMPLES_DOWNLOAD_URL="https://github.com/Codeplain-ai/plainlang-examples/archiv
 
 # Show current directory and ask for extraction path
 CURRENT_DIR=$(pwd)
-echo -e "  current folder: ${YELLOW}${CURRENT_DIR}${NC}"
+echo -e "  Current folder: ${WHITE}${CURRENT_DIR}${NC}"
 echo ""
-echo -e "  extract examples here, or enter a different path:"
+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 ""
@@ -35,24 +36,24 @@ SKIP_DOWNLOAD=false
 
 # Check if directory exists, create if not
 if [ ! -d "$EXTRACT_PATH" ]; then
-    echo -e "  ${GRAY}creating directory...${NC}"
+    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}"
+        echo -e "  ${RED}✗ Failed to create directory: ${EXTRACT_PATH}${NC}"
+        echo -e "  ${GRAY}Skipping example download.${NC}"
         SKIP_DOWNLOAD=true
     fi
 fi
 
 if [ "$SKIP_DOWNLOAD" = false ]; then
-    echo -e "  ${GRAY}downloading examples...${NC}"
+    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}"
+        echo -e "  ${GRAY}Extracting to ${EXTRACT_PATH}...${NC}"
 
         # Extract the zip file
         unzip -q -o "$TEMP_ZIP" -d "$EXTRACT_PATH" 2>/dev/null
@@ -71,22 +72,32 @@ if [ "$SKIP_DOWNLOAD" = false ]; then
                 rm -f "${EXTRACTED_DIR}/.gitignore"
             fi
 
+            clear
             echo ""
-            echo -e "  ${GREEN}✓${NC} examples downloaded successfully!"
+            echo -e "  ${GREEN}✓ Examples downloaded successfully!${NC}"
             echo ""
-            echo -e "  examples are in: ${YELLOW}${EXTRACTED_DIR}${NC}"
+            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 ""
         else
-            echo -e "  ${RED}✗${NC} failed to extract examples."
+            echo -e "  ${RED}✗ Failed to extract examples.${NC}"
         fi
 
         # Clean up temp file
         rm -f "$TEMP_ZIP"
     else
-        echo -e "  ${RED}✗${NC} failed to download examples."
+        echo -e "  ${RED}✗ Failed to download examples.${NC}"
         rm -f "$TEMP_ZIP"
     fi
 
     echo ""
-    read -r -p "  press [Enter] to continue..." < /dev/tty
+    PROMPT=$(printf '%b' "  Press ${WHITE}[Enter]${NC} to continue...")
+    read -r -p "$PROMPT" < /dev/tty
 fi