codeplain 0.3.9__tar.gz → 0.3.10.dev2__tar.gz

{codeplain-0.3.9 → codeplain-0.3.10.dev2}/.github/workflows/e2e.yml

@@ -59,4 +59,31 @@ jobs:
       - name: Run E2E tests
         env:
           CODEPLAIN_API_KEY: ${{ secrets.CODEPLAIN_API_KEY }}
-        run: pytest tests/e2e/ -v --tb=short
+        run: pytest tests/e2e/ -v --tb=short
+
+  notify-on-failure:
+    name: Notify Slack on failure
+    needs: [e2e-linux, e2e-windows]
+    if: failure()
+    runs-on: ubuntu-latest
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_E2E_WEBHOOK_URL }}
+    steps:
+      - name: Determine failed platforms
+        id: platforms
+        run: |
+          failed=""
+          [ "${{ needs.e2e-linux.result }}" = "failure" ] && failed="Linux"
+          if [ "${{ needs.e2e-windows.result }}" = "failure" ]; then
+            [ -n "$failed" ] && failed="$failed and Windows" || failed="Windows"
+          fi
+          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)) }}
+            }

codeplain-0.3.10.dev2/.github/workflows/lint-powershell.yml

@@ -0,0 +1,124 @@
+name: PowerShell Install Scripts
+
+on:
+  push:
+    paths:
+      - 'install/powershell/*.ps1'
+      - '.github/workflows/lint-powershell.yml'
+  pull_request:
+    paths:
+      - 'install/powershell/*.ps1'
+      - '.github/workflows/lint-powershell.yml'
+  workflow_dispatch:
+
+jobs:
+  parse-windows-powershell-51:
+    name: Parse under Windows PowerShell 5.1
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The install scripts are fetched over HTTP and executed on stock Windows,
+      # where powershell.exe (5.1) is the default shell. 5.1 reads BOM-less files
+      # as ANSI (CP1252), so a non-ASCII glyph such as U+2713 decodes into a smart
+      # quote that silently terminates the enclosing string. The resulting parse
+      # errors point at unrelated lines far below the real cause, so parse every
+      # script with 5.1 explicitly rather than relying on PowerShell 7.
+      - name: Parse each script with 5.1
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Write-Host "PowerShell $($PSVersionTable.PSVersion) / ANSI codepage $([System.Text.Encoding]::Default.WebName)"
+
+          $failed = $false
+          Get-ChildItem 'install/powershell' -Filter *.ps1 | Sort-Object Name | ForEach-Object {
+              $errors = $null
+              [System.Management.Automation.Language.Parser]::ParseFile(
+                  $_.FullName, [ref]$null, [ref]$errors) | Out-Null
+
+              if ($errors -and $errors.Count -gt 0) {
+                  $failed = $true
+                  Write-Host "FAIL $($_.Name): $($errors.Count) parse error(s)"
+                  $errors | Sort-Object { $_.Extent.StartLineNumber } | ForEach-Object {
+                      Write-Host "     L$($_.Extent.StartLineNumber): $($_.Message)"
+                  }
+              } else {
+                  Write-Host "OK   $($_.Name)"
+              }
+          }
+
+          if ($failed) { exit 1 }
+
+      # A BOM would fix file-based parsing but break `irm ... | iex`: PowerShell 5.1
+      # decodes an HTTP text/* body with no charset as ISO-8859-1, turning the BOM
+      # into literal "i>>?" text and failing with
+      # "The term 'i>>?$ErrorActionPreference' is not recognized".
+      # Keeping the sources pure ASCII is what makes both paths safe, so enforce it.
+      - name: Require pure ASCII and no BOM
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $failed = $false
+
+          Get-ChildItem 'install/powershell' -Filter *.ps1 | Sort-Object Name | ForEach-Object {
+              $fileBad = $false
+              $bytes = [System.IO.File]::ReadAllBytes($_.FullName)
+
+              if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
+                  $failed = $true
+                  $fileBad = $true
+                  Write-Host "FAIL $($_.Name): has a UTF-8 BOM (breaks 'irm | iex'); remove it"
+              }
+
+              # Report line/column of any byte outside ASCII so the fix is obvious.
+              $text = [System.Text.Encoding]::UTF8.GetString($bytes)
+              $lineNo = 0
+              foreach ($line in ($text -split "`r?`n")) {
+                  $lineNo++
+                  for ($i = 0; $i -lt $line.Length; $i++) {
+                      if ([int]$line[$i] -gt 127) {
+                          $failed = $true
+                          $fileBad = $true
+                          $cp = "U+{0:X4}" -f [int]$line[$i]
+                          Write-Host "FAIL $($_.Name) L${lineNo} C$($i + 1): non-ASCII $cp"
+                          Write-Host "     build it from its code point instead, e.g. `$CHECK = [char]0x2713"
+                          break
+                      }
+                  }
+              }
+
+              if (-not $fileBad) { Write-Host "OK   $($_.Name)" }
+          }
+
+          if ($failed) { exit 1 }
+
+  parse-powershell-7:
+    name: Parse under PowerShell 7
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Parse each script with 7
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Write-Host "PowerShell $($PSVersionTable.PSVersion)"
+
+          $failed = $false
+          Get-ChildItem 'install/powershell' -Filter *.ps1 | Sort-Object Name | ForEach-Object {
+              $errors = $null
+              [System.Management.Automation.Language.Parser]::ParseFile(
+                  $_.FullName, [ref]$null, [ref]$errors) | Out-Null
+
+              if ($errors -and $errors.Count -gt 0) {
+                  $failed = $true
+                  Write-Host "FAIL $($_.Name): $($errors.Count) parse error(s)"
+                  $errors | Sort-Object { $_.Extent.StartLineNumber } | ForEach-Object {
+                      Write-Host "     L$($_.Extent.StartLineNumber): $($_.Message)"
+                  }
+              } else {
+                  Write-Host "OK   $($_.Name)"
+              }
+          }
+
+          if ($failed) { exit 1 }

codeplain-0.3.10.dev2/.github/workflows/publish-dev-to-pypi.yml

@@ -0,0 +1,147 @@
+name: Publish dev build to PyPI
+
+# Every merge to main publishes a PEP 440 dev release (e.g. 0.3.10.dev7) to
+# PyPI, so the latest main is always installable from the real index with real
+# dependency resolution. Dev releases are pre-releases: pip and uv skip them
+# unless asked, so ordinary installs keep getting the latest stable.
+#
+# Tagged releases (including rc/beta/alpha) are handled by publish-to-pypi.yml.
+on:
+  push:
+    branches: [main]
+  # Ad-hoc runs, e.g. re-publishing after a PyPI outage.
+  workflow_dispatch:
+
+# Least privilege by default: jobs get no GITHUB_TOKEN scopes unless they
+# opt in below.
+permissions: {}
+
+# Serialize publishes so versions land in merge order. Queued runs are not
+# cancelled — each merge should still get its own dev build.
+concurrency:
+  group: publish-dev-to-pypi
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build dev distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      should-publish: ${{ steps.version.outputs.should-publish }}
+      version: ${{ steps.version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, so we need full history.
+          fetch-depth: 0
+
+      - name: Install uv
+        # uv provisions its own Python (honoring requires-python), so no
+        # separate actions/setup-python step is needed.
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Compute dev version
+        id: version
+        # Between releases hatch-vcs produces something like
+        # "0.3.10.dev16+gb710c2982". The "+g..." local version segment is valid
+        # PEP 440 but is rejected by PyPI on upload, so it has to go. We keep
+        # setuptools-scm's own next-version guess (0.3.10 — the patch bump
+        # after the latest tag) rather than re-deriving it here, and use the
+        # run number as the dev counter: it is strictly increasing, so each
+        # merge sorts after the last and re-runs never collide.
+        run: |
+          RAW=$(uvx --from setuptools-scm python -c \
+            "from setuptools_scm import get_version; print(get_version())")
+          echo "setuptools-scm reports: $RAW"
+
+          # On a commit that IS a release tag, setuptools-scm returns a clean
+          # version with no .dev component (e.g. "0.3.9" or "0.4.0rc1").
+          # Appending ".dev<run>" to that yields 0.3.9.dev42, which sorts BELOW
+          # the released 0.3.9 — newer code would look older. A tagged commit
+          # is a real release and is published by publish-to-pypi.yml, so there
+          # is no dev build to make here.
+          case "$RAW" in
+            *.dev*) ;;
+            *)
+              echo "::notice::$RAW is a tagged release; skipping dev build."
+              echo "should-publish=false" >> $GITHUB_OUTPUT
+              exit 0
+              ;;
+          esac
+
+          BASE=${RAW%%+*}
+          BASE=${BASE%%.dev*}
+          VERSION="${BASE}.dev${GITHUB_RUN_NUMBER}"
+          echo "Derived version: $RAW -> $VERSION"
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=$VERSION" >> $GITHUB_ENV
+          echo "should-publish=true" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Build package
+        if: steps.version.outputs.should-publish == 'true'
+        # hatch-vcs reads SETUPTOOLS_SCM_PRETEND_VERSION in place of the tag.
+        run: |
+          uv build
+          echo "Built distributions:"
+          ls -l dist/
+
+      - name: Store the distribution packages
+        if: steps.version.outputs.should-publish == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+  publish-dev:
+    name: Publish dev build to PyPI
+    needs: build
+    if: needs.build.outputs.should-publish == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codeplain
+    permissions:
+      # Mint a short-lived OIDC token so PyPI Trusted Publishing can
+      # authenticate this run — no long-lived API token needed.
+      id-token: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # PyPI uploads are immutable, so a re-run of an already-published
+          # version should be a no-op, not a red build.
+          skip-existing: true
+
+      - name: Notify Slack (success)
+        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          # Spell out the --pre install: a plain "pip install codeplain" will
+          # NOT pick this up, which otherwise reads as a broken publish.
+          TEXT="*Codeplain Client*: dev build \`$VERSION\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre codeplain==$VERSION\`. Pre-release builds talk to \`api.test.codeplain.ai\` by default."
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Publishing dev build to PyPI FAILED :x: (commit \`${{ github.sha }}\`). See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"

{codeplain-0.3.9 → codeplain-0.3.10.dev2}/.github/workflows/publish-to-pypi.yml

@@ -91,10 +91,23 @@ jobs:
 
       - name: Notify Slack (success)
         if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        env:
+          # GitHub marks the release itself as a pre-release; the tag
+          # (v0.4.0rc1) carries the same intent for PEP 440.
+          IS_PRERELEASE: ${{ github.event.release.prerelease }}
+          TAG: ${{ github.ref_name }}
         run: |
+          VERSION="${TAG#v}"
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            # pip and uv skip pre-releases by default, so "--upgrade" would
+            # NOT pick this up. Tell people the command that actually works.
+            TEXT="*Codeplain Client*: pre-release \`$TAG\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre codeplain==$VERSION\`."
+          else
+            TEXT="*Codeplain Client*: \`$TAG\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade codeplain\`."
+          fi
           curl -s -X POST "$SLACK_WEBHOOK_URL" \
             -H 'Content-type: application/json' \
-            --data "{\"text\":\"*Codeplain Client*: \`${{ github.ref_name }}\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade codeplain\`.\"}"
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
 
       - name: Notify Slack (failure)
         if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}

{codeplain-0.3.9 → codeplain-0.3.10.dev2}/CLAUDE.md

@@ -14,14 +14,14 @@ The codebase serves two audiences:
 - **End users**: developers who write `***plain` specs and run `plain2code.py` to generate code
 - **Internal devs**: maintaining the renderer itself (this codebase)
 
-### Related Repository: plain2code_rest_api
+### Related Repository: codeplain-api
 
-This repository has a sibling repository **`plain2code_rest_api`** which contains the backend API service that this client communicates with. The two repositories are typically cloned as siblings:
+This repository has a sibling repository **`codeplain-api`** which contains the backend API service that this client communicates with. The two repositories are typically cloned as siblings:
 
 ```
 parent-directory/
-├── codeplain/              # This repository (client)
-└── plain2code_rest_api/    # Backend API service
+├── codeplain/          # This repository (client)
+└── codeplain-api/      # Backend API service
 ```
 
 **When to work across both repositories:**

codeplain-0.3.10.dev2/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# 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.
+
+## Pre-Releases
+
+Everything below happens on real PyPI — there is no separate test index.
+Pre-releases are invisible to ordinary installs: pip and uv skip them during
+resolution, so `pip install codeplain` and `pip install --upgrade codeplain`
+always serve the latest *stable* release.
+
+### Dev builds (automatic)
+
+Every merge to `main` publishes a dev release such as `0.3.10.dev7`, so the tip
+of main is always installable from the real index:
+
+```bash
+pip install --pre codeplain==0.3.10.dev7
+uv tool install --prerelease allow codeplain
+```
+
+Versions are `<next-patch>.dev<run-number>`, so they sort after the last
+release and before the next one. See `.github/workflows/publish-dev-to-pypi.yml`.
+If that workflow is ever dispatched against a commit that is itself a release
+tag, it skips rather than publishing a dev build that would sort below the
+release.
+
+### Release candidates (manual)
+
+To get a specific build in front of people before it becomes the default
+install, cut a PEP 440 pre-release.
+
+Tag and publish a GitHub release as usual, but with a pre-release version and
+the release marked "pre-release":
+
+```
+v0.4.0a1    alpha
+v0.4.0b1    beta
+v0.4.0rc1   release candidate
+```
+
+`publish-to-pypi.yml` handles these with no special casing: hatch-vcs reads the
+version straight off the tag (`v0.4.0rc1` -> `0.4.0rc1`).
+
+Opt in the same way:
+
+```bash
+pip install --pre codeplain==0.4.0rc1
+```
+
+### Which API a build talks to
+
+Pre-release builds default to the **test** API, so an unreleased client is
+exercised against the unreleased backend:
+
+| build | default API |
+| --- | --- |
+| stable release (`0.3.9`) | `https://api.codeplain.ai` |
+| dev build (`0.3.10.dev7`) | `https://api.test.codeplain.ai` |
+| alpha/beta/rc (`0.4.0rc1`) | `https://api.test.codeplain.ai` |
+
+`--api` always overrides this. Resolution lives in
+`system_config._resolve_default_api_url`, keyed off the version baked into the
+package at build time — so nothing needs configuring at install time.
+
+A source checkout reports the nearest git tag as its version, so it is treated
+as stable and keeps pointing at production; use `--api` to aim it elsewhere.
+
+Because every build above goes to real PyPI, dependency resolution and the
+install path are exactly what an end user gets — the main reason this is
+preferred over publishing to TestPyPI.

{codeplain-0.3.9 → codeplain-0.3.10.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codeplain
-Version: 0.3.9
+Version: 0.3.10.dev2
 Summary: Transform plain language specifications into working code
 License-File: LICENSE
 Classifier: Environment :: Console
@@ -8,15 +8,15 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: ==3.11.*
-Requires-Dist: gitpython==3.1.52
-Requires-Dist: mistletoe==1.5.1
+Requires-Dist: gitpython==3.1.55
+Requires-Dist: mistletoe==1.6.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.66.0
+Requires-Dist: sentry-sdk==2.66.1
 Requires-Dist: textual>=7.5.0
 Requires-Dist: tiktoken==0.13.0
 Requires-Dist: transitions==0.9.3
@@ -52,6 +52,7 @@ macOS and Linux:
 
 ```bash
 curl -fsSL https://codeplain.ai/install.sh | bash
+# re-run to update to the latest version
 ```
 
 Windows PowerShell:
@@ -74,12 +75,39 @@ export CODEPLAIN_API_KEY="your_actual_api_key_here"
 
 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:
+If you didn't install it during step 1, run it any time using your favorite Node package runner:
 
 ```bash
 npx plain-forge install
 ```
 
+The same command works with any other runner — pick whichever matches your toolchain:
+
+```bash
+# npm (bundled with Node.js)
+npx plain-forge install
+
+# pnpm
+pnpm dlx plain-forge install
+
+# Bun
+bunx plain-forge install
+
+# Yarn (Berry, v2+)
+yarn dlx plain-forge install
+
+# Deno (npm: specifier, needs permissions to write the skills directory)
+deno run -A npm:plain-forge install
+```
+
+Every runner downloads `plain-forge` on demand and runs it without adding it to your project's dependencies. The package exposes a `plain-forge` binary, so no runner needs an extra `--package` flag.
+
+`install` fails if plain-forge is already installed at the target — to refresh an existing installation to the latest skills, rules, and docs, use `update` instead (swap in your runner of choice):
+
+```bash
+npx plain-forge update
+```
+
 ### 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.
@@ -101,9 +129,9 @@ You can immediately test the system with a simple "Hello World" example:
 
   _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:
+- The system will generate a Python application in the `dist` directory. You can run it with:
   ```bash
-  cd build
+  cd dist
   python hello_world.py
   ```
 

{codeplain-0.3.9 → codeplain-0.3.10.dev2}/README.md

@@ -22,6 +22,7 @@ macOS and Linux:
 
 ```bash
 curl -fsSL https://codeplain.ai/install.sh | bash
+# re-run to update to the latest version
 ```
 
 Windows PowerShell:
@@ -44,12 +45,39 @@ export CODEPLAIN_API_KEY="your_actual_api_key_here"
 
 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:
+If you didn't install it during step 1, run it any time using your favorite Node package runner:
 
 ```bash
 npx plain-forge install
 ```
 
+The same command works with any other runner — pick whichever matches your toolchain:
+
+```bash
+# npm (bundled with Node.js)
+npx plain-forge install
+
+# pnpm
+pnpm dlx plain-forge install
+
+# Bun
+bunx plain-forge install
+
+# Yarn (Berry, v2+)
+yarn dlx plain-forge install
+
+# Deno (npm: specifier, needs permissions to write the skills directory)
+deno run -A npm:plain-forge install
+```
+
+Every runner downloads `plain-forge` on demand and runs it without adding it to your project's dependencies. The package exposes a `plain-forge` binary, so no runner needs an extra `--package` flag.
+
+`install` fails if plain-forge is already installed at the target — to refresh an existing installation to the latest skills, rules, and docs, use `update` instead (swap in your runner of choice):
+
+```bash
+npx plain-forge update
+```
+
 ### 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.
@@ -71,9 +99,9 @@ You can immediately test the system with a simple "Hello World" example:
 
   _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:
+- The system will generate a Python application in the `dist` directory. You can run it with:
   ```bash
-  cd build
+  cd dist
   python hello_world.py
   ```
 

{codeplain-0.3.9 → codeplain-0.3.10.dev2}/concept_utils.py

@@ -12,8 +12,14 @@ from plain2code_exceptions import PlainSyntaxError
 DEFAULT_CONCEPTS = {
     ":ConformanceTests:",
     ":UnitTests:",
+    ":AcceptanceTest:",
     ":AcceptanceTests:",
     ":Implementation:",
+    ":plainDefinitions:",
+    ":plainImplementationReqs:",
+    ":plainFunctionality:",
+    ":plainTestReqs:",
+    ":plainImplementationCode:",
 }
 
 

{codeplain-0.3.9 → codeplain-0.3.10.dev2}/docs/plain2code_cli.md

@@ -118,9 +118,9 @@ options:
                         If set, render the state machine graph.
   --logging-config-path LOGGING_CONFIG_PATH
                         Path to the logging configuration file.
-  --headless            Run in headless mode: no TUI, no terminal output
-                        except a single render-started message. All logs are
-                        written to the log file.
+  --headless            Run in headless mode: no TUI. Progress is written to
+                        the log file and streamed to stdout as it happens; the
+                        specification text itself stays in the log file only.
   --status              Display account status including user information, API
                         key label, and rendering credits. Does not render any
                         code.