rosh-lang 0.9.3__tar.gz

rosh_lang-0.9.3/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --dev --frozen
+      - run: uv run pytest -q
+
+  release-artifacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv build --no-sources
+      - name: Reject private or generated release files
+        run: |
+          if tar -tf dist/rosh_lang-*.tar.gz | grep -E '(\.uv-cache|\.venv|\.pytest_cache|test-verify|\.env|\.sb3|rosh-dev|rosh-corporate)'; then
+            echo "Unexpected file found in source distribution"
+            exit 1
+          fi
+          if python3 -m zipfile -l dist/rosh_lang-*.whl | grep -E '(\.uv-cache|\.venv|\.pytest_cache|test-verify|\.env|\.sb3|rosh-dev|rosh-corporate)'; then
+            echo "Unexpected file found in the wheel"
+            exit 1
+          fi
+      - run: uv tool run --from dist/rosh_lang-*.whl rosh --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Publishes to PyPI via Trusted Publishing (OIDC) — no stored token.
+  # Requires this workflow's environment to be registered as a trusted
+  # publisher at https://pypi.org/manage/project/rosh-lang/settings/publishing/
+  # (one-time setup, after the first manual `uv publish`).
+  publish-pypi:
+    needs: [test, release-artifacts]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Verify tag matches package version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          wheel_version=$(ls dist/*.whl | sed -E 's/.*rosh_lang-([0-9.]+)-.*/\1/')
+          if [ "$tag_version" != "$wheel_version" ]; then
+            echo "Tag v$tag_version does not match package version $wheel_version — refusing to publish." >&2
+            exit 1
+          fi
+      - uses: pypa/gh-action-pypi-publish@release/v1

rosh_lang-0.9.3/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+
+# UV
+.uv-cache/
+
+# Generated
+*.rosh.html
+*.sb3
+test-verify.rosh

rosh_lang-0.9.3/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to `rosh-lang` are documented here.
+
+The core grammar (parser/runtime statement surface) is treated as stable
+once documented in [LANGUAGE.md](LANGUAGE.md) — see CONTRIBUTING.md's rule
+that new keywords require discussion first. Undocumented internals (e.g.
+widget-specific properties like `.material`) may change without a version
+bump until they're promoted into the public spec.
+
+## 0.9.3 - 2026-08-12
+
+### Fixed
+
+- `normalise`: a quoted multi-word value passed to `set X.material to "..."`
+  or `turn X into '...'` left a stray trailing quote baked into the material
+  noun (e.g. `ivory"`). Quotes are now stripped before the material/desc
+  split.
+- `normalise`: a trailing `# comment` on an otherwise-valid line (e.g.
+  `play laser # once`) was never stripped, so the comment text was parsed
+  as real arguments instead of being ignored. Inline comments are now
+  stripped, respecting quoted strings (so `background "#1a1a2e"` and
+  `print "score #1"` are unaffected).
+- `after <seconds> send <event>`: payload support was documented
+  (`after 0.5 send scored value=5`) but never implemented — the model had
+  no payload field and any extra tokens after the event name were silently
+  dropped on every target. `AfterStatement` now carries a `payload` dict,
+  parsed the same way as `send`, and emitted correctly in compiled JS
+  (web/Phaser/Three.js targets).
+- `normalise`: the inline-comment stripper above treated any bare apostrophe
+  as opening a quoted string, so a possessive or contraction with no actual
+  quotes (`say Rosh's world # note`, `say don't stop # note`) made the
+  scanner think it was still "inside a string" for the rest of the line —
+  the trailing comment was never stripped. A `'` now only opens a quote when
+  it's preceded by whitespace or starts the line, which a real quote always
+  is and a contraction never is.
+
+### Docs
+
+- LANGUAGE.md's Scenes section documented `create scene ... end` as if it
+  scoped the statements inside it to that scene. It doesn't — `create scene`
+  only registers the scene, and everything between it and its `end` executes
+  immediately and unconditionally like any other top-level code. The section
+  now documents the real, tested pattern: register scenes, set properties
+  (`room_description`, `exits`), and gate per-scene behavior with a global
+  `when scene_enter` handler checked against the `scene` payload value.
+- LANGUAGE.md documented `repeat items as item` for iterating a captured
+  list. `repeat` only accepts a numeric count (or `as <var>` for a counter);
+  it silently no-ops on a list. The working, tested mechanism is
+  `for each item in items`, which is now what's documented.
+- The corrected `for each` example also fixed a second inaccuracy: captured
+  list items from `get all into items` have the shape
+  `{key, value, type}`, not `{name, ...}` — `{item.name}` never resolved.
+  The example now uses `{item.key}`.
+- `send`/`after` payload examples used a bare positional value
+  (`send scored 10`) implying it binds to the event's declared payload
+  field. It doesn't — only `key=value` tokens are read into the payload; a
+  bare value is parsed but silently dropped. Examples now use
+  `send scored value=10`.
+- The `event`/`when`/`send` example had the `send` before the matching
+  `when` block in program order. Handler registration happens as the
+  runtime scans forward through top-level statements, so a `send` that
+  fires before its `when` is reached has no handler to call — the example
+  now declares `when scored` before `send`ing it.
+- The Web target section claimed `--target web` "generates a self-contained
+  HTML file... share it as a single `.html`". It doesn't — the CLI only
+  serves the rendered page from a local HTTP server; nothing is written to
+  disk. The section now describes the real behavior and points to
+  `rosh_lang.targets.web.render_html()` for anyone who wants the raw string
+  to save themselves.
+- The Asset Registry section claimed `"ancient carved stone"`, `"carving"`,
+  and `"stone"` all fuzzy-match to the `stone` manifest. `"carving"` alone
+  actually resolves to the separate `carved_relief` manifest (it's a tag
+  there, not on `stone`). Swapped the example for `"pictish stone"`, which
+  does resolve to `stone`, and noted the near-miss.
+
+### Release process
+
+- Added a `publish-pypi` job to `.github/workflows/ci.yml`: on a `v*` tag
+  push, it downloads the exact wheel/sdist the `release-artifacts` job
+  already built and verified (not a fresh rebuild), checks the tag matches
+  the wheel's version (refuses to publish on a mismatch), then publishes to
+  PyPI via Trusted Publishing (OIDC) — no stored token.
+- The private/generated-file leak check now scans the built wheel as well
+  as the sdist; previously only the sdist was checked.
+- Removed a stale, contradictory `uv.lock` entry from `.gitignore` — the
+  lockfile is (correctly) tracked in git, so ignoring it had no effect.
+
+## 0.9.2 and earlier
+
+Not tracked retroactively in this file.

rosh_lang-0.9.3/CLAUDE.md

@@ -0,0 +1,263 @@
+# Rosh Language — Agent Context
+
+Everything an AI agent needs to write `.rosh` files and work on `rosh-lang/`.
+
+## What Rosh Is
+
+A plain-English language: `print "hello"` runs on terminal, browser, and game engine. Same source, different targets. "One script, many worlds."
+
+## How to Run
+
+```bash
+rosh hello.rosh                        # terminal
+rosh hello.rosh --target web --run     # browser
+rosh hello.rosh --target phaser --run  # Phaser game
+rosh                                   # REPL
+rosh new game my-game                  # scaffold a starter file
+```
+
+## How to Test
+
+```bash
+cd rosh-lang && uv run pytest -q       # expect the full suite to pass
+```
+
+After code changes, reinstall:
+```bash
+uv tool install --from /path/to/rosh-lang rosh-lang --force
+```
+
+## Complete Syntax Forms
+
+```
+print "text"                          # output ({var} interpolation)
+print                                 # blank line (no arguments)
+create object player                  # create object/number/string/list
+set player.x to 0.5                   # assign value (arithmetic: score + 1)
+set x to random                       # random 0.0–1.0 (or: random 0.1 0.9)
+set x to clamp x 0.02 0.8             # constrain to [min, max]
+get player                            # query state
+get score into saved                  # capture result into state variable
+get all into items                    # capture all visible state as structured list
+get count of visitors into n          # capture list length as integer
+look                                  # inspect scene
+look player into info                 # capture inspection result into state
+look programme into stmts             # capture statement list (iterate with for each)
+say hello                             # broadcast text
+when click                            # event handler block
+  set count to count + 1
+end                                   # end block
+on update set x to x + 0.01          # one-line reactive listener
+on keydown when key == " " play sfx  # conditional listener
+event scored value                    # declare named event
+send scored 10                        # emit event
+if score > 10                         # branching
+  print "win!"
+else if score > 5                     # else-if chain (single end)
+  print "close!"
+else
+  print "keep going"
+end
+use score label "Points"              # compose widget with config
+go level2                             # scene navigation
+connect server wss://...              # register connection
+destroy enemy                         # remove object
+sprite ship "blue spaceship"          # procedural pixel art
+sprite ship "https://example.com/ship.png"  # URL sprite (any image)
+sound laser "laser shoot"             # procedural sound
+play laser                            # play sound (once/loop/stop)
+animate obj sheet "run.png" frames 4  # spritesheet animation
+after 3 send timeout                  # delayed event
+background "#1a1a2e"                  # canvas/scene background (colour or image)
+create scene level1                   # scene definition
+define fire_bullet                    # user-defined function
+  set bullet._fire to 1
+end
+do fire_bullet                        # call a function
+on keydown when key == " " do fire_bullet  # call from event
+repeat 5                              # counted loop
+  print "hello"
+end
+repeat 3 as i                         # loop with variable (1, 2, 3)
+  print "Round {i}"
+end
+```
+
+`into` capture for `get` and `look` is terminal/REPL-first. Browser, Phaser,
+Three.js, Scratch, and world target capture semantics are deferred until those
+targets have explicit `get`/`look` command-state paths.
+
+## Object Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `x` | float | Position (0.0–1.0 = %, >1 = px) |
+| `y` | float | Position (0.0–1.0 = %, >1 = px) |
+| `width` | float | Size (default 0.1) |
+| `height` | float | Size (default 0.1) |
+| `color` | string | Hex or named color |
+| `label` | string | Text on object (empty by default) |
+| `sprite` | string | Procedural sprite description or image URL |
+| `rotation` | float | Rotation in degrees (0=up, clockwise positive) |
+| `visible` | int | 0 hides, any other shows (cascades to children) |
+| `vx`, `vy` | float | Velocity (per second) |
+| `text_color` | string | Text color (default #fff) |
+| `font_size` | string | Font size (default 14px) |
+| `_max_output` | int | Max console lines (excess trimmed from top) |
+
+## Events
+
+`start`, `update` (dt), `click` (x,y), `click_<name>` (x,y), `keydown` (key), `keyup` (key), `collision` (a,b), `scene_enter` (scene), `scene_exit` (scene), `destroy` (name), `timer_done` (name), `game_start`, `game_over`, `game_restart`.
+
+Key-hold: `_keys.ArrowLeft == 1` inside `when update`.
+
+## Game-Building Pattern
+
+```
+# Minimal game: player moves, shoots, scores
+set _max_output to 3
+use score
+use lives count 3
+use player speed 0.03 move x
+sprite player "green spaceship"
+
+use bullet count 3 vy -0.5 color "#ffff00"
+
+create object enemy
+set enemy.x to 0.45
+set enemy.y to 0.1
+set enemy.width to 0.08
+set enemy.height to 0.06
+sprite enemy "red alien"
+
+sound laser "laser shoot"
+sound hit "explosion hit"
+
+on keydown when key == " " set bullet._x to player.x
+on keydown when key == " " set bullet._y to player.y
+on keydown when key == " " set bullet._fire to 1
+on keydown when key == " " play laser
+
+when collision bullet.* enemy
+  set score.value to score.value + 1
+  play hit
+end
+
+# game_over auto-fires when lives.count hits 0
+when game_over
+  print "GAME OVER — Score: {score.value}"
+end
+```
+
+Run: `rosh game.rosh --target web --run`
+
+## Widget Library (22 Widgets)
+
+| Widget | Type | Config | Purpose |
+|--------|------|--------|---------|
+| `score` | .py | `anchor theme label x y bg text_color font_size` | Score display (HUD) |
+| `player` | .py | `speed keys move x y width height color clamp_*` | Keyboard ship with auto-movement |
+| `controller` | .py | `target keys touch touch_style speed move help fire fire_key fire_event clamp` | Universal input (keyboard + touch) |
+| `counter` | .rosh | — | Click counter |
+| `timer` | .py | `total running x y bg text_color font_size` | Auto-tick countdown (fires timer_done) |
+| `health-bar` | .py | `max current x y bg text_color font_size` | Health display |
+| `lives` | .py | `count auto_gameover x y bg text_color font_size` | Lives counter (auto game-over at 0) |
+| `button` | .rosh | — | Clickable button |
+| `label` | .rosh | `text x y bg text_color font_size` | Text label |
+| `fps` | .py | `x y bg text_color font_size` | FPS counter |
+| `message` | .rosh | `text x y bg text_color font_size` | Overlay message |
+| `title-screen` | .rosh | `title subtitle bg text_color font_size` | Title screen |
+| `coin` | .rosh | — | Collectible |
+| `grid` | .py | `rows cols size gap color` | Cell grid |
+| `enemy-grid` | .py | `rows cols size gap color` | Enemy formation |
+| `starfield` | .py | `count` | Background stars |
+| `bullet` | .py | `count vx vy color` | Pooled projectiles |
+| `explosion` | .py | `count color` | Pooled explosions |
+| `animation` | .py | `target sheet frames speed mode` | Spritesheet |
+| `game-lifecycle` | .rosh | `title subtitle bg text_color font_size` | Title → playing → over flow |
+| `ball` | .py | `x y size color vx vy walls` | Bouncing ball with wall bounce |
+| `hazard` | .py | `count vx vy color width height sprite spawn_rate` | Auto-spawning obstacle pool |
+
+Use: `use <widget> [key value ...]` — config pairs override defaults.
+
+## Architecture
+
+```
+core/model.py     → statement dataclasses + Programme
+core/parser.py    → text → Programme
+core/runtime.py   → execute Programme, state dict, events, if/else, scenes
+core/widgets.py   → widget loader: find, namespace-prefix, configure
+media/sprites.py          → name + description → data:image/png;base64 (7×9 grid)
+media/sounds.py           → name + description → Web Audio synthesis params
+media/sheets.py           → PNG spritesheet → list of frame data URIs
+media/assets.py           → resolve asset file paths (legacy)
+media/asset_registry.py   → semantic registry; find() by name/alias/tag, visibility-gated
+media/asset_providers.py  → provider connectors: MockAssetProvider + SketchfabAssetProvider (metadata-only)
+media/asset_requests.py   → load unknown-object request queue from generated _assetRequests state
+media/asset_reviews.py    → CandidateReview dataclass; validate_review(); review_to_draft_manifest(); candidates_to_review_template()
+media/asset_manifests/    → bundled seed manifests (18 JSON files, MIT-licensed, review_status=featured)
+cli/scaffolder.py         → rosh new templates
+cli/cloud.py              → rosh.cloud login/create/publish commands
+cli/library_cli.py        → rosh library list/info (widget inspector)
+cli/assets_cli.py         → rosh assets search [--save review.json] | rosh assets register <review.json> [--output-dir DIR]
+library/          → bundled widgets
+targets/
+  terminal.py     → print to stdout
+  web.py          → self-contained HTML page (CSS divs + JS)
+  phaser.py       → Phaser 3.70.0 game (canvas rendering)
+  threejs.py      → Three.js 3D scene
+  scratch.py      → Scratch 3 .sb3 export
+  _js_runtime.py  → JS_RUNTIME_CORE (state, events) + JS_RUNTIME_DOM (CSS sync)
+  _js_runtime_phaser.py → JS_RUNTIME_PHASER (Phaser renderer, replaces DOM)
+  _js_runtime_threejs.py → JS_RUNTIME_THREEJS (Three.js renderer)
+  _js_codegen.py  → compile Programme → JavaScript
+```
+
+## Rules
+
+1. **Don't add keywords** unless they are documented in the public syntax reference or agreed in an issue first
+2. **Test after every change**: `cd rosh-lang && uv run pytest -q`
+3. **Rebuild showcase** after completing build steps: `cd rosh-lang && uv run python tools/build_showcase.py`
+4. **Licence**: MIT. All widgets must declare `# licence: MIT`
+5. **Spec before code**: check the README and https://rosh.cloud/docs/syntax before implementing language behavior
+6. **Commits**: use `type: Short description`, with types like `feat`, `fix`, `docs`, `test`, `refactor`, or `chore`
+7. **Reinstall after changes**: `uv tool install --from .../rosh-lang rosh-lang --force`
+
+## Sprite Descriptions
+
+Two modes:
+
+1. **Procedural** — description keywords generate 7×9 pixel art. Color keywords (red, blue, green, etc.) and shape keywords (spaceship, alien, ball, bullet, crystal, star). Example: `sprite ship "blue spaceship"`
+
+2. **URL** — any `http://` or `https://` URL loads the image directly. Works on all targets (web, phaser, threejs). Example: `sprite ship "https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/72x72/1f680.png"`
+
+URL sprites and procedural sprites can be mixed in the same program. If a URL fails to load, the object falls back to a colored rectangle.
+
+**Rendering differences:**
+- Procedural sprites: fill the entire width×height box, pixelated upscaling (crisp edges)
+- URL sprites: `contain` fit (preserves aspect ratio), smooth rendering
+- `rotation` property: degrees, 0=up, clockwise positive (all targets)
+
+## Sound Families
+
+9 preset families matched by keyword: `laser`, `explosion`, `coin`, `jump`, `hit`, `powerup`, `gameover`, `click`, `win`.
+
+## Bullet Pool Pattern
+
+```
+use bullet count 3 vy -0.5 color "#ffff00"
+
+# Fire: set position then flag
+on keydown when key == " " set bullet._x to player.x
+on keydown when key == " " set bullet._y to player.y
+on keydown when key == " " set bullet._fire to 1
+
+# Collision: bullet.* matches all pool members
+when collision bullet.* enemy
+  set score.value to score.value + 1
+end
+```
+
+## Collision Wildcard
+
+`when collision bullet.* enemy` — the `*` matches any suffix. Works in either position.

rosh_lang-0.9.3/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to Rosh
+
+Thanks for your interest in contributing to Rosh.
+
+## Licence
+
+Rosh is released under the [MIT License](LICENSE). By contributing, you agree that your contributions will be licensed under MIT.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Setup
+
+```bash
+git clone https://github.com/rosh-studio/rosh-lang.git
+cd rosh-lang
+uv sync --all-extras
+```
+
+### Running Tests
+
+```bash
+uv run pytest -q
+```
+
+All tests must pass before submitting a pull request.
+
+The standalone public repository also builds wheel and source-distribution
+artifacts in CI to prevent local caches or generated files entering a release.
+
+### Installing Locally
+
+```bash
+uv tool install --from . rosh-lang --force
+```
+
+Then run with `rosh`.
+
+## What You Can Contribute
+
+- **Bug reports** — open an issue with reproduction steps
+- **Example programs** — new `.rosh` files in `examples/`
+- **Widget improvements** — enhancements to existing widgets in `src/rosh_lang/library/`
+- **Documentation** — improvements to README, inline comments, or examples
+- **Test coverage** — new test cases for edge cases or uncovered paths
+- **Editor support** — syntax and snippet updates in `editor/vscode/`
+
+## What Requires Discussion First
+
+- **New keywords** — language additions must be discussed and documented in the public syntax reference before implementation
+- **New targets** — adding a new compilation target (e.g. Unity, Godot) is a significant change
+- **Architecture changes** — changes to the parser, model, or code generation pipeline
+
+Please open an issue to discuss before submitting a PR for these.
+
+## Code Style
+
+- Use `pathlib.Path` over `os.path`
+- Use f-strings over `.format()` or `%`
+- Use type hints
+- Keep it simple — no over-engineering
+
+## Commit Messages
+
+```text
+type: Short description
+
+Co-Authored-By: Your Name <your@email.com>
+```
+
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`.
+
+## Questions?
+
+- Discord: [discord.gg/gevBPucznD](https://discord.gg/gevBPucznD)
+- Email: [info@rosh.cloud](mailto:info@rosh.cloud)