Merge origin/main into node-subprocess-handling

Both sides appended a job to the E2E workflow: main added
notify-on-failure, this branch added e2e-macos. Keep both, and let the
notification cover the macOS lane too — a lane that can fail silently is
worse than no lane.

Read each job result from an env var and fold the platform list in a
loop, so the step survives `bash -e`: the previous `[ cond ] && var=...`
form exits non-zero the moment a platform passed, aborting the step
before it could report the platforms that failed.

Author: gorandodig

.github/workflows/e2e.yml

@@ -90,3 +90,35 @@ jobs:
       # in, where nothing upstream of the script has a terminal to lend it.
       - name: Run Node through the installed execute_script()
         run: nohup python tests/e2e/macos_node_smoke.py < /dev/null
+
+  notify-on-failure:
+    name: Notify Slack on failure
+    needs: [e2e-linux, e2e-windows, e2e-macos]
+    if: failure()
+    runs-on: ubuntu-latest
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_E2E_WEBHOOK_URL }}
+      LINUX_RESULT: ${{ needs.e2e-linux.result }}
+      WINDOWS_RESULT: ${{ needs.e2e-windows.result }}
+      MACOS_RESULT: ${{ needs.e2e-macos.result }}
+    steps:
+      - name: Determine failed platforms
+        id: platforms
+        run: |
+          failed=""
+          for entry in "Linux:$LINUX_RESULT" "Windows:$WINDOWS_RESULT" "macOS:$MACOS_RESULT"; do
+            if [ "${entry#*:}" = "failure" ]; then
+              name="${entry%%:*}"
+              if [ -n "$failed" ]; then failed="$failed and $name"; else failed="$name"; fi
+            fi
+          done
+          echo "failed=$failed" >> "$GITHUB_OUTPUT"
+
+      - name: Send failure notification to Slack
+        if: ${{ env.SLACK_WEBHOOK_URL != '' }}
+        uses: slackapi/slack-github-action@v1.24.0
+        with:
+          payload: |
+            {
+              "text": ${{ toJSON(format('[Codeplain Client] E2E tests FAILED on {0}. See <{1}/{2}/actions/runs/{3}|the run log>.', steps.platforms.outputs.failed, github.server_url, github.repository, github.run_id)) }}
+            }

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to Codeplain
+
+Thanks for contributing to Codeplain.
+
+## Before You Start
+
+Check existing issues and pull requests before starting work.
+
+Keep each contribution focused on one issue or a closely related set of changes.
+
+## Contribution Workflow
+
+1. Fork the Codeplain repository.
+2. Make your changes on a branch in your fork.
+3. Commit and push the changes to your fork.
+4. Open a pull request against the Codeplain `main` branch.
+
+## Configure Codeplain
+
+Use your own Codeplain API key for local development and testing.
+
+Never commit API keys, credentials, or other secrets.
+
+## Test with a Plain Example
+
+When relevant, test your change with an existing example from the `plainlang-examples` repository.
+
+This provides a real `.plain` project for verifying the change in an actual Codeplain workflow.
+
+## Run Tests
+
+Run the tests relevant to your change before opening a pull request.
+
+For changes that affect the CLI, rendering, or test execution, also test the change by running the relevant Codeplain command from the terminal.
+
+Check that:
+
+* the command returns the expected exit code,
+* errors are clear and do not expose unintended tracebacks,
+* existing Codeplain behavior still works.
+
+For platform-specific changes, test the relevant `.sh` or `.ps1` workflow.
+
+## Keep the Change Clean
+
+Before submitting:
+
+* remove temporary files and debugging output,
+* avoid unrelated changes,
+* add or update tests where needed,
+* update documentation when behavior changes,
+* verify that no secrets are included.
+
+Review your changes with:
+
+```bash
+git status
+git diff
+```
+
+## Pull Request
+
+Include:
+
+* what changed,
+* why it changed,
+* the related issue, when applicable,
+* how the change was tested,
+* the `plainlang-examples` example used, when relevant.

install/powershell/install.ps1

@@ -129,7 +129,14 @@ function Test-GitAvailable {
     }
 }
 
-# Print install instructions for the current platform and exit. codeplain uses
+# `exit` under `irm ... | iex` closes the user's shell, so exit only for file-based
+# ($PSCommandPath) or unattended runs. Callers must `return` right after this.
+function Stop-Install {
+    $global:LASTEXITCODE = 1
+    if ($PSCommandPath -or $nonInteractive) { exit 1 }
+}
+
+# Print install instructions for the current platform. codeplain uses
 # git to checkpoint the code it renders, and GitPython fails at import time
 # when the git executable is missing, so 'codeplain --status' would die with a
 # raw traceback that says nothing about the actual cause.
@@ -148,7 +155,7 @@ function Assert-Git {
     Write-Host ""
     Write-Host "  ${GRAY}Once Git is installed, restart your terminal and run this installer again.${NC}"
     Write-Host ""
-    exit 1
+    Stop-Install
 }
 
 # Verify an API key against the Codeplain API's /status endpoint.
@@ -193,9 +200,10 @@ Write-Host ""
 # before the user answers any prompts rather than at the --status check below.
 if (-not (Test-GitAvailable)) {
     Assert-Git
+    return
 }
 
-Write-Host "${GREEN}✓${NC} git detected"
+Write-Host "${GREEN}${CHECK}${NC} git detected"
 Write-Host ""
 
 try {
@@ -545,7 +553,8 @@ if ($env:CODEPLAIN_API_KEY) {
         Write-Host $verifyOutput
         Write-Host "${GRAY}Please restart your terminal and try again, or reinstall with:${NC}"
         Write-Host "  uv tool install --force codeplain"
-        exit 1
+        Stop-Install
+        return
     }
 }
 

plain_file.py

@@ -455,6 +455,19 @@ def process_imports(
     return required_concepts
 
 
+def normalize_line_endings(plain_source_text: str) -> str:
+    return plain_source_text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def restore_stripped_lines(plain_source_text: str, content: str) -> str:
+    stripped_source = plain_source_text.rstrip()
+    if not content or not stripped_source.endswith(content):
+        return content
+
+    stripped_line_count = stripped_source[: len(stripped_source) - len(content)].count("\n")
+    return "\n" * stripped_line_count + content
+
+
 def read_plain_source_metadata(plain_source_text):
     try:
         plain_source_obj = frontmatter.loads(plain_source_text)
@@ -490,6 +503,8 @@ def parse_plain_source(  # noqa: C901
     imported_modules: list[str],
     modules_trace: list[str],
 ) -> PlainFileParseResult:
+    plain_source_text = normalize_line_endings(plain_source_text)
+
     plain_source_obj = read_plain_source_metadata(plain_source_text)
 
     plain_source = PLAIN_SOURCE_TEMPLATE.copy()
@@ -508,7 +523,9 @@ def parse_plain_source(  # noqa: C901
 
     [_, loaded_templates] = file_utils.get_loaded_templates(template_dirs, plain_source_text)
 
-    plain_source_full_text = render_plain_source(plain_source_obj.content, loaded_templates, code_variables)
+    plain_source_content = restore_stripped_lines(plain_source_text, plain_source_obj.content)
+
+    plain_source_full_text = render_plain_source(plain_source_content, loaded_templates, code_variables)
 
     plain_file = mistletoe.Document(io.StringIO(plain_source_full_text))
 

tests/test_cli_output.py

@@ -1,5 +1,6 @@
 """Unit tests for cli_output module."""
 
+from datetime import datetime, timezone
 from unittest.mock import Mock, patch
 
 from cli_output.status import (
@@ -10,6 +11,14 @@
     print_status,
 )
 
+FROZEN_NOW = datetime(2025, 6, 15, 12, 0, tzinfo=timezone.utc)
+
+
+class FrozenDatetime(datetime):
+    @classmethod
+    def now(cls, tz=None):
+        return FROZEN_NOW if tz is None else FROZEN_NOW.astimezone(tz)
+
 
 class TestProgressBar:
     """Tests for _create_progress_bar function."""
@@ -52,6 +61,7 @@ def test_custom_width(self):
         assert bar == "█" * 5 + "░" * 5
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestDisplayCreditLine:
     """Tests for _display_credit_line function."""
 
@@ -132,6 +142,7 @@ def test_timezone_naive_datetime(self, mock_console):
         mock_console.print.assert_called_once()
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestDisplayBucketCreditLine:
     """Tests for _display_bucket_credit_line function."""
 
@@ -192,6 +203,7 @@ def test_timezone_naive_datetime(self, mock_console):
         mock_console.print.assert_called_once()
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestDisplayStatusMessage:
     """Tests for _display_status_message function."""
 
@@ -271,6 +283,7 @@ def test_null_plan_credits_and_empty_purchased(self, mock_console):
         assert "No rendering credits remaining" in call_args
 
 
+@patch("cli_output.status.datetime", FrozenDatetime)
 class TestPrintStatus:
     """Tests for print_status function."""
 

tests/test_plainfileparser.py

@@ -36,7 +36,7 @@ def test_unknown_section():
     with pytest.raises(
         Exception,
         match=re.escape(
-            "Syntax error at line 3: Invalid specification heading (`Unknown Section:`). Allowed headings: definitions, implementation reqs, test reqs, functional specs, acceptance tests"
+            "Syntax error at line 4: Invalid specification heading (`Unknown Section:`). Allowed headings: definitions, implementation reqs, test reqs, functional specs, acceptance tests"
         ),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])
@@ -50,7 +50,7 @@ def test_duplicate_section():
 """
     with pytest.raises(
         Exception,
-        match=re.escape("Syntax error at line 3: Duplicate specification heading (`definitions`)"),
+        match=re.escape("Syntax error at line 4: Duplicate specification heading (`definitions`)"),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])
 
@@ -64,11 +64,48 @@ def test_invalid_top_level_element():
 """
     with pytest.raises(
         Exception,
-        match=re.escape("Syntax error at line 2: Invalid source structure  (`code block`)"),
+        match=re.escape("Syntax error at line 3: Invalid source structure  (`code block`)"),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])
 
 
+def test_syntax_error_line_number_accounts_for_frontmatter():
+    plain_source = """---
+description: 'Plain file with frontmatter'
+---
+
+***definitions***
+
+***Unknown Section:***
+"""
+    with pytest.raises(
+        Exception,
+        match=re.escape("Syntax error at line 7: Invalid specification heading (`Unknown Section:`)"),
+    ):
+        plain_file.parse_plain_source(plain_source, {}, [], [], [])
+
+
+def test_syntax_error_line_number_with_windows_line_endings():
+    plain_source = (
+        "---\r\n"
+        "description: 'Plain file with frontmatter'\r\n"
+        "---\r\n"
+        "\r\n"
+        "***definitions***\r\n"
+        "\r\n"
+        "***Unknown Section:***\r\n"
+    )
+    with pytest.raises(
+        Exception,
+        match=re.escape("Syntax error at line 7: Invalid specification heading (`Unknown Section:`)"),
+    ):
+        plain_file.parse_plain_source(plain_source, {}, [], [], [])
+
+
+def test_normalize_line_endings_does_not_duplicate_newlines():
+    assert plain_file.normalize_line_endings("a\r\nb\rc\nd") == "a\nb\nc\nd"
+
+
 def test_plain_file_parser_with_comments(get_test_data_path):
     _, plain_sections, _ = plain_file.plain_file_parser(
         "plain_file_parser_with_comments.plain",
@@ -423,7 +460,7 @@ def test_acceptance_tests_top_level_rejected():
     with pytest.raises(
         PlainSyntaxError,
         match=re.escape(
-            "Syntax error at line 1: acceptance tests heading should be nested under specific functional spec."
+            "Syntax error at line 2: acceptance tests heading should be nested under specific functional spec."
         ),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])