feat(examples): use npm/PyPI packages by default, local builds in CI

.github/workflows/js.yml

@@ -10,6 +10,7 @@ on:
       - "crates/bashkit-js/**"
       - "crates/bashkit/src/**"
       - "examples/*.mjs"
+      - "examples/package.json"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/js.yml"
@@ -19,6 +20,7 @@ on:
       - "crates/bashkit-js/**"
       - "crates/bashkit/src/**"
       - "examples/*.mjs"
+      - "examples/package.json"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/js.yml"
@@ -66,35 +68,32 @@ jobs:
         run: npm test
         working-directory: crates/bashkit-js
 
-      - name: Link package for examples
+      - name: Install example dependencies and link local build
+        working-directory: examples
         run: |
+          npm install
+          rm -rf node_modules/@everruns/bashkit
           mkdir -p node_modules/@everruns
           ln -s ${{ github.workspace }}/crates/bashkit-js node_modules/@everruns/bashkit
 
       - name: Run examples (self-contained)
+        working-directory: examples
         run: |
-          node examples/bash_basics.mjs
-          node examples/data_pipeline.mjs
-          node examples/llm_tool.mjs
-
-      - name: Install AI SDK dependencies and re-link
-        run: |
-          echo '{"type":"module","private":true}' > package.json
-          npm install --no-save openai ai @ai-sdk/openai @langchain/core @langchain/langgraph @langchain/openai zod
-          rm -rf node_modules/@everruns/bashkit
-          mkdir -p node_modules/@everruns
-          ln -s ${{ github.workspace }}/crates/bashkit-js node_modules/@everruns/bashkit
+          node bash_basics.mjs
+          node data_pipeline.mjs
+          node llm_tool.mjs
 
       - name: Install Doppler CLI
         if: env.DOPPLER_TOKEN != ''
         uses: dopplerhq/cli-action@v3
 
       - name: Run AI examples
         if: env.DOPPLER_TOKEN != ''
+        working-directory: examples
         run: |
-          doppler run -- node examples/openai_tool.mjs
-          doppler run -- node examples/vercel_ai_tool.mjs
-          doppler run -- node examples/langchain_agent.mjs
+          doppler run -- node openai_tool.mjs
+          doppler run -- node vercel_ai_tool.mjs
+          doppler run -- node langchain_agent.mjs
 
   # Gate job for branch protection
   js-check:

.github/workflows/python.yml

@@ -10,6 +10,7 @@ on:
     paths:
       - "crates/bashkit-python/**"
       - "crates/bashkit/**"
+      - "examples/*.py"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/python.yml"
@@ -18,6 +19,7 @@ on:
     paths:
       - "crates/bashkit-python/**"
       - "crates/bashkit/**"
+      - "examples/*.py"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/python.yml"
@@ -100,6 +102,8 @@ jobs:
         with:
           python-version: "3.12"
 
+      - uses: astral-sh/setup-uv@v7
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
 
@@ -113,11 +117,13 @@ jobs:
           rust-toolchain: stable
           working-directory: crates/bashkit-python
 
-      - name: Install wheel
+      - name: Install local wheel
         run: pip install bashkit --no-index --find-links crates/bashkit-python/dist --force-reinstall
 
       - name: Run examples
-        run: python crates/bashkit-python/examples/bash_basics.py
+        run: |
+          python crates/bashkit-python/examples/bash_basics.py
+          python crates/bashkit-python/examples/k8s_orchestrator.py
 
   # Verify wheel builds and passes twine check
   build-wheel:

crates/bashkit-python/examples/bash_basics.py

@@ -1,11 +1,19 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.9"
+# dependencies = [
+#     "bashkit",
+# ]
+# ///
 """Basic usage of the Bash interface.
 
 Demonstrates core Bash features: command execution, pipelines, variables,
 loops, virtual filesystem persistence, and resource limits.
 
-Run directly:
-    cd crates/bashkit-python && maturin develop && python examples/bash_basics.py
+Run:
+    uv run crates/bashkit-python/examples/bash_basics.py
+
+uv automatically installs bashkit from PyPI (pre-built wheels, no Rust needed).
 """
 
 from __future__ import annotations

crates/bashkit-python/examples/k8s_orchestrator.py

@@ -1,12 +1,18 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.9"
+# dependencies = [
+#     "bashkit",
+# ]
+# ///
 """Kubernetes API orchestrator using Bashkit ScriptedTool.
 
 Demonstrates composing 12 fake k8s API tools into a single ScriptedTool that
 an LLM agent can call with bash scripts. Each tool becomes a bash builtin;
 the agent writes one script to orchestrate them all.
 
-Run directly:
-    cd crates/bashkit-python && maturin develop && python examples/k8s_orchestrator.py
+Run:
+    uv run crates/bashkit-python/examples/k8s_orchestrator.py
 
 With LangChain (optional):
     pip install 'bashkit[langchain]'

examples/README.md

@@ -15,6 +15,15 @@ bash examples/realfs_mount.sh
 Python examples use [PEP 723](https://peps.python.org/pep-0723/) inline script metadata.
 `uv run` resolves dependencies automatically — bashkit installs from PyPI as a pre-built wheel (no Rust toolchain needed).
 
+### bash_basics.py / k8s_orchestrator.py
+
+Core features and ScriptedTool orchestration:
+
+```bash
+uv run crates/bashkit-python/examples/bash_basics.py
+uv run crates/bashkit-python/examples/k8s_orchestrator.py
+```
+
 ### treasure_hunt_agent.py
 
 LangChain agent with Bashkit sandbox.
@@ -35,15 +44,11 @@ uv run examples/deepagent_coding_agent.py
 
 ## JavaScript / TypeScript
 
-JS examples import `@everruns/bashkit`. Install from npm or build locally:
+JS examples install `@everruns/bashkit` from npm. All dependencies are in
+`examples/package.json`:
 
 ```bash
-# From npm
-npm install @everruns/bashkit
-
-# Or build locally
-cd crates/bashkit-js && npm install && npm run build
-# Then run with NODE_PATH=crates/bashkit-js
+cd examples && npm install
 ```
 
 ### bash_basics.mjs
@@ -75,7 +80,6 @@ node examples/llm_tool.mjs
 OpenAI function calling with manual tool-call loop.
 
 ```bash
-npm install openai
 export OPENAI_API_KEY=sk-...
 node examples/openai_tool.mjs
 ```
@@ -85,7 +89,6 @@ node examples/openai_tool.mjs
 Vercel AI SDK `tool()` + `generateText()` with automatic tool-call loop.
 
 ```bash
-npm install ai @ai-sdk/openai zod
 export OPENAI_API_KEY=sk-...
 node examples/vercel_ai_tool.mjs
 ```
@@ -95,7 +98,6 @@ node examples/vercel_ai_tool.mjs
 LangChain.js ReAct agent with `DynamicStructuredTool`.
 
 ```bash
-npm install @langchain/core @langchain/langgraph @langchain/openai zod
 export OPENAI_API_KEY=sk-...
 node examples/langchain_agent.mjs
 ```

examples/bashkit-pi/package.json

@@ -5,6 +5,6 @@
   "type": "module",
   "description": "Pi coding agent with bashkit virtual bash + VFS",
   "dependencies": {
-    "@everruns/bashkit": "file:../../crates/bashkit-js"
+    "@everruns/bashkit": "latest"
   }
 }