@tutorialkit-rb/cli 0.1.5 → 0.1.7

package/template/src/components/FileManager.tsx

@@ -9,6 +9,28 @@ const GEMFILE_HASH_URL = `/ruby.wasm.hash`;
 const WC_WASM_LOG_PATH = `/ruby.wasm.log.txt`;
 const WC_WASM_PATH = `/ruby.wasm`;
 
+async function clearWasmCache(): Promise<void> {
+  const opfsRoot = await navigator.storage.getDirectory();
+  let count = 0;
+
+  for await (const [name] of opfsRoot.entries()) {
+    if (name.includes('ruby') && name.endsWith('.wasm')) {
+      await opfsRoot.removeEntry(name);
+      console.log(`Deleted: ${name}`);
+      count++;
+    }
+  }
+
+  if (count === 0) {
+    console.log('No cached WASM files found.');
+  } else {
+    console.log(`Cleared ${count} cached WASM file(s). Hard-refresh the page (Cmd+Shift+R) to download a fresh binary.`);
+  }
+}
+
+// Expose to browser console: type clearWasmCache() to purge cached WASM binaries
+(window as any).clearWasmCache = clearWasmCache;
+
 export function FileManager() {
   const lessonLoaded = useStore(tutorialStore.lessonFullyLoaded);
   const files = useStore(tutorialStore.files);
@@ -70,6 +92,7 @@ export function FileManager() {
       const opfsRoot = await navigator.storage.getDirectory();
       const fileHandle = await opfsRoot.getFileHandle(cacheFileName, { create: true });
       const writable = await fileHandle.createWritable();
+      // @ts-ignore
       await writable.write(wasmData);
       await writable.close();
       console.log(`Ruby WASM file ${cacheFileName} cached`);
@@ -134,6 +157,16 @@ export function FileManager() {
         }
       });
 
+      // Also ensure template workspace bin files are executable
+      try {
+        const templateBins = await wc.fs.readdir('workspace/bin');
+        templateBins.forEach((bin) => {
+          chmodx(wc, `/home/tutorial/workspace/bin/${bin}`);
+        });
+      } catch {
+        // workspace/bin may not exist for all templates
+      }
+
       if (!wasmCached.current) {
         await wc.fs.writeFile(WC_WASM_LOG_PATH, 'status: init');
 

package/template/src/components/HeadTags.astro

@@ -16,7 +16,7 @@
   }
 
   :global(.rails-path-link code) {
-    color: #0969da;
+    color: var(--tk-rails-path-color, #3B82F6);
     background-color: #f6f8fa;
     padding: 0.2em 0.4em;
     border-radius: 0.25rem;
@@ -27,20 +27,20 @@
 
   /* Dark mode support */
   :global(.dark .rails-path-link code) {
-    color: #58a6ff;
+    color: var(--tk-rails-path-color-dark, #60A5FA);
     background-color: #161b22;
   }
 
   /* Hover state */
   :global(.rails-path-link:hover code) {
-    color: #0860ca;
+    color: var(--tk-rails-path-hover-color, #2563EB);
     background-color: #e7f1ff;
     text-decoration: underline;
     text-underline-offset: 0.2em;
   }
 
   :global(.dark .rails-path-link:hover code) {
-    color: #79c0ff;
+    color: var(--tk-rails-path-hover-color-dark, #93C5FD);
     background-color: #1f2937;
   }
 
@@ -55,11 +55,11 @@
   }
 
   :global(.rails-path-link:focus-visible code) {
-    outline: 2px solid #0969da;
+    outline: 2px solid var(--tk-rails-path-color, #3B82F6);
     outline-offset: 2px;
   }
 
   :global(.dark .rails-path-link:focus-visible code) {
-    outline-color: #58a6ff;
+    outline-color: var(--tk-rails-path-color-dark, #60A5FA);
   }
 </style>

package/template/src/components/HelpDropdown.tsx

@@ -60,7 +60,7 @@ export function HelpDropdown() {
             </div>
             <button
               onClick={handleReload}
-              className="w-full bg-blue-600 hover:bg-blue-700 text-white font-medium py-2 px-4 rounded transition-colors"
+              className="w-full bg-accent-600 hover:bg-accent-700 text-white font-medium py-2 px-4 rounded transition-colors"
             >
               Reload
             </button>

package/template/src/components/RailsPathLinkHandler.tsx

@@ -47,7 +47,7 @@ export default function RailsPathLinkHandler() {
         const railsPath = link.getAttribute('data-rails-path');
 
         if (railsPath) {
-          tutorialStore.setSelectedFile(`/workspace/store/${railsPath}`);
+          tutorialStore.setSelectedFile(`/workspace/${railsPath}`);
         }
 
         return;
@@ -68,7 +68,7 @@ export default function RailsPathLinkHandler() {
           try {
             await ensureRailsServerStarted(railsPreview);
           } catch (error) {
-            console.error('failed to start Rails server', e);
+            console.error('failed to start Rails server', error);
             return;
           }
 

package/template/src/components/ShellConfigurator.tsx

@@ -15,6 +15,7 @@ export const ShellConfigurator: React.FC = () => {
   const storeRef = useStore(tutorialStore.ref);
   const terminalConfig = useStore(tutorialStore.terminalConfig);
   const lessonLoaded = useStore(tutorialStore.lessonFullyLoaded);
+  const isPreparing = useStore(tutorialStore.isPreparing);
   const [state, set] = useState(0);
 
   useEffect(() => {
@@ -40,6 +41,10 @@ export const ShellConfigurator: React.FC = () => {
       return;
     }
 
+    if (isPreparing) {
+      return;
+    }
+
     if (!terminal) {
       return;
     }
@@ -89,7 +94,7 @@ export const ShellConfigurator: React.FC = () => {
     }, 100);
 
     return () => clearInterval(interval);
-  }, [boot, terminalConfig, storeRef, lessonLoaded]);
+  }, [boot, terminalConfig, storeRef, isPreparing, lessonLoaded]);
 
   return null;
 };

package/template/src/content/tutorial/1-getting-started/1-creating-your-first-rails-app/content.md

@@ -4,7 +4,7 @@ title: Creating your first Rails app
 editor: false
 custom:
   shell:
-    workdir: "/workspace/store"
+    workdir: "/workspace"
 ---
 
 Creating Your First Rails App
@@ -16,10 +16,10 @@ all of the commands.
 `rails new` generates the foundation of a fresh Rails application for you, so
 let's start there.
 
-To create our `store` application, run the following command in your terminal:
+To create our application, run the following command in your terminal:
 
 ```bash
-$ rails new store
+$ rails new demo_app
 ```
 
 :::info
@@ -30,5 +30,5 @@ these options, run `rails new --help`.
 After your new application is created, switch to its directory:
 
 ```bash
-$ cd store
+$ cd demo_app
 ```

package/template/src/content/tutorial/1-getting-started/2-rails-console/content.md

@@ -3,13 +3,13 @@ type: lesson
 title: Rails Console
 custom:
   shell:
-    workdir: "/workspace/store"
+    workdir: "/workspace"
 ---
 
 Rails Console
 -------------------
 
-Now that we have created our products table, we can interact with it in Rails.
+Now that we have our demo app set up, we can interact with it using Rails.
 Let's try it out.
 
 For this, we're going to use a Rails feature called the *console*. The console
@@ -23,14 +23,14 @@ You should see a prompt like the following:
 
 ```irb
 Loading development environment (Rails 8.0.2)
-store(dev)>
+demo_app(dev)>
 ```
 
 Now we can type code that will be executed when we hit `Enter`. Try
 printing out the Rails version:
 
 ```irb
-store(dev)> Rails.version
+demo_app(dev)> Rails.version
 <!-- hit Enter -->
 ```
 

package/template/src/content/tutorial/2-controllers/2-crud-operations/content.md

@@ -1,7 +1,7 @@
 ---
 type: lesson
 title: CRUD Operations
-focus: /workspace/store/app/controllers/products_controller.rb
+focus: /workspace/app/controllers/products_controller.rb
 previews: [3000]
 mainCommand: ['node scripts/rails.js server', 'Starting Rails server']
 prepareCommands:
@@ -9,7 +9,7 @@ prepareCommands:
   - ['node scripts/rails.js db:prepare', 'Prepare development database']
 custom:
   shell:
-    workdir: '/workspace/store'
+    workdir: '/workspace'
 ---
 
 # CRUD Operations in Rails

package/template/src/content/tutorial/9-outbound-http/1-making-http-requests/_files/.tk-config.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../../../templates/rails-app"
+}

package/template/src/content/tutorial/9-outbound-http/1-making-http-requests/_files/workspace/app/controllers/http_demo_controller.rb

@@ -0,0 +1,65 @@
+require "net/http"
+require "json"
+
+class HttpDemoController < ApplicationController
+  # ── CORS proxy configuration ─────────────────────────────────
+  # Deploy your own Cloudflare Worker (see cors-proxy/ in the
+  # project source), then paste your worker URL below.
+  #
+  # The proxy is needed because most APIs don't set CORS headers,
+  # and this Rails app runs inside the browser.
+  PROXY_URL = "https://cors-proxy.YOUR-SUBDOMAIN.workers.dev/proxy?"
+  PROXY_HOSTS = ["httpbin.org"]
+  # ─────────────────────────────────────────────────────────────
+
+  before_action :configure_proxy
+
+  def index
+  end
+
+  def fetch_get
+    uri = URI("https://httpbin.org/get?tutorial=rails-wasm&lesson=outbound-http")
+    response = Net::HTTP.get_response(uri)
+
+    render json: {
+      status: response.code.to_i,
+      headers: response.each_header.to_h,
+      body: safe_parse_json(response.body)
+    }
+  rescue => e
+    render json: { error: "#{e.class}: #{e.message}" }, status: 500
+  end
+
+  def fetch_post
+    uri = URI("https://httpbin.org/post")
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+
+    request = Net::HTTP::Post.new(uri.path)
+    request["Content-Type"] = "application/json"
+    request.body = { message: "Hello from Rails WASM!", timestamp: Time.now.iso8601 }.to_json
+
+    response = http.request(request)
+
+    render json: {
+      status: response.code.to_i,
+      headers: response.each_header.to_h,
+      body: safe_parse_json(response.body)
+    }
+  rescue => e
+    render json: { error: "#{e.class}: #{e.message}" }, status: 500
+  end
+
+  private
+
+  def configure_proxy
+    WasmHTTP::Connection.proxy_url = PROXY_URL
+    WasmHTTP::Connection.proxy_hosts = PROXY_HOSTS
+  end
+
+  def safe_parse_json(str)
+    JSON.parse(str)
+  rescue JSON::ParserError
+    str
+  end
+end

package/template/src/content/tutorial/9-outbound-http/1-making-http-requests/_files/workspace/app/views/http_demo/index.html.erb

@@ -0,0 +1,172 @@
+<% content_for(:title) { "Outbound HTTP Demo" } %>
+
+<div class="http-demo">
+  <h1>Outbound HTTP from Rails WASM</h1>
+  <p class="subtitle">
+    These buttons make real HTTP requests from Ruby to
+    <a href="https://httpbin.org" target="_blank">httpbin.org</a>
+    — routed through a CORS proxy.
+  </p>
+
+  <div class="actions">
+    <button id="btn-get" class="btn btn--primary" onclick="makeRequest('get')">
+      Fetch from httpbin.org
+    </button>
+    <button id="btn-post" class="btn btn--secondary" onclick="makeRequest('post')">
+      Post to httpbin.org
+    </button>
+  </div>
+
+  <div id="status" class="status" style="display: none;"></div>
+
+  <pre id="result" class="result"><span class="placeholder">Click a button above to make a request...</span></pre>
+</div>
+
+<script>
+  async function makeRequest(type) {
+    const resultEl = document.getElementById("result");
+    const statusEl = document.getElementById("status");
+    const btnGet = document.getElementById("btn-get");
+    const btnPost = document.getElementById("btn-post");
+    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
+
+    // Disable buttons
+    btnGet.disabled = true;
+    btnPost.disabled = true;
+
+    // Show loading
+    statusEl.style.display = "block";
+    statusEl.className = "status status--loading";
+    statusEl.textContent = "Sending request...";
+    resultEl.textContent = "";
+
+    try {
+      const url = type === "get" ? "/http_demo/fetch_get" : "/http_demo/fetch_post";
+      const options = {
+        method: "POST",
+        headers: {
+          "X-CSRF-Token": csrfToken || "",
+          "Content-Type": "application/x-www-form-urlencoded"
+        }
+      };
+
+      const response = await fetch(url, options);
+      const data = await response.json();
+
+      if (data.error) {
+        statusEl.className = "status status--error";
+        statusEl.textContent = "Error";
+        resultEl.textContent = data.error;
+      } else {
+        statusEl.className = "status status--success";
+        statusEl.textContent = `${type.toUpperCase()} request succeeded (HTTP ${data.status})`;
+        resultEl.textContent = JSON.stringify(data.body, null, 2);
+      }
+    } catch (err) {
+      statusEl.className = "status status--error";
+      statusEl.textContent = "Request failed";
+      resultEl.textContent = err.message;
+    } finally {
+      btnGet.disabled = false;
+      btnPost.disabled = false;
+    }
+  }
+</script>
+
+<style>
+  .http-demo {
+    max-width: 48rem;
+    margin: 0 auto;
+    padding: var(--space-lg) var(--space-md);
+  }
+
+  .http-demo h1 {
+    margin-bottom: var(--space-xs);
+  }
+
+  .subtitle {
+    color: var(--color-text-muted);
+    margin-bottom: var(--space-lg);
+  }
+
+  .subtitle a {
+    color: var(--color-primary);
+  }
+
+  .actions {
+    display: flex;
+    gap: var(--space-sm);
+    margin-bottom: var(--space-md);
+  }
+
+  .btn {
+    padding: var(--space-sm) var(--space-md);
+    border: none;
+    border-radius: var(--radius-md);
+    font-size: var(--font-size-base);
+    cursor: pointer;
+    transition: opacity 0.15s;
+  }
+
+  .btn:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+
+  .btn--primary {
+    background: var(--color-primary);
+    color: var(--color-text-inverse);
+  }
+
+  .btn--secondary {
+    background: var(--color-bg-white);
+    color: var(--color-text);
+    border: 1px solid var(--color-border);
+  }
+
+  .status {
+    padding: var(--space-sm) var(--space-md);
+    border-radius: var(--radius-md);
+    margin-bottom: var(--space-md);
+    font-size: var(--font-size-sm);
+    font-weight: 500;
+  }
+
+  .status--loading {
+    background: #fff3cd;
+    color: #856404;
+    border: 1px solid #ffc107;
+  }
+
+  .status--success {
+    background: #d4edda;
+    color: #155724;
+    border: 1px solid #28a745;
+  }
+
+  .status--error {
+    background: #f8d7da;
+    color: #721c24;
+    border: 1px solid #dc3545;
+  }
+
+  .result {
+    background: var(--color-bg-white);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    padding: var(--space-md);
+    overflow-x: auto;
+    font-size: var(--font-size-sm);
+    line-height: 1.6;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    min-height: 8rem;
+    max-height: 24rem;
+    overflow-y: auto;
+  }
+
+  .placeholder {
+    color: var(--color-text-muted);
+    font-style: italic;
+  }
+</style>

package/template/src/content/tutorial/9-outbound-http/1-making-http-requests/_files/workspace/config/routes.rb

@@ -0,0 +1,8 @@
+Rails.application.routes.draw do
+  root "http_demo#index"
+
+  post "http_demo/fetch_get"
+  post "http_demo/fetch_post"
+
+  get "up" => "rails/health#show", as: :rails_health_check
+end

package/template/src/content/tutorial/9-outbound-http/1-making-http-requests/content.md

@@ -0,0 +1,97 @@
+---
+type: lesson
+title: "Making HTTP Requests"
+focus: /workspace/app/controllers/http_demo_controller.rb
+previews: [3000]
+mainCommand: ['node scripts/rails.js server', 'Starting Rails server']
+prepareCommands:
+  - ['npm install', 'Preparing Ruby runtime']
+  - ['node scripts/rails.js db:prepare', 'Prepare database']
+custom:
+  shell:
+    workdir: '/workspace'
+---
+
+# Making Outbound HTTP Requests from Rails
+
+Ruby on Rails running in WebAssembly can make **outbound HTTP requests** to external APIs — just like a normal Rails app. This lesson shows how it works.
+
+## How it works
+
+```
+Ruby Net::HTTP  ->  JS fetch bridge  ->  CORS proxy  ->  External API
+```
+
+Since the Rails app runs inside your browser, outbound requests go through the browser's `fetch()` API. Most server APIs don't include CORS headers, so a **CORS proxy** is needed to relay requests.
+
+The HTTP bridge automatically intercepts `Net::HTTP` calls (and anything built on top of it, like Faraday) and routes them through the proxy.
+
+## Deploy your own CORS proxy
+
+This tutorial includes a ready-to-deploy Cloudflare Worker that acts as a CORS proxy. You'll find it in the `cors-proxy/` directory of this project's source code.
+
+### Steps
+
+1. **Install Wrangler** (Cloudflare's CLI):
+
+   ```bash
+   npm install -g wrangler
+   wrangler login
+   ```
+
+2. **Navigate to the proxy directory** in the tutorialkit.rb source:
+
+   ```bash
+   cd packages/template/cors-proxy
+   ```
+
+3. **Edit `wrangler.toml`** to set your allowed hosts:
+
+   ```toml
+   [vars]
+   ALLOWED_HOSTS = "httpbin.org,api.example.com"
+   ```
+
+   This is a comma-separated list of hostnames the proxy will forward requests to. Keep it restrictive — only add hosts your tutorial lessons actually need.
+
+4. **Deploy**:
+
+   ```bash
+   npm install
+   wrangler deploy
+   ```
+
+   Wrangler will print your worker URL, e.g. `https://cors-proxy.<your-subdomain>.workers.dev`.
+
+## Try it out
+
+1. Open `http_demo_controller.rb` in the editor and replace `YOUR-SUBDOMAIN` in `PROXY_URL` with your actual Cloudflare Workers subdomain
+2. Click **Fetch from httpbin.org** to make an outbound GET request
+3. Click **Post to httpbin.org** to make an outbound POST request
+
+The proxy configuration lives at the top of the controller as constants. Since the controller is reloaded on each request, you can edit `PROXY_URL` and your changes take effect immediately — no server restart needed.
+
+## The code
+
+**Controller** (`http_demo_controller.rb`): Configures the CORS proxy via a `before_action`, then makes outbound requests using `Net::HTTP` — the same standard library you'd use in any Rails app.
+
+```ruby
+PROXY_URL = "https://cors-proxy.<your-subdomain>.workers.dev/proxy?"
+PROXY_HOSTS = ["httpbin.org"]
+
+before_action :configure_proxy
+
+def fetch_get
+  uri = URI("https://httpbin.org/get")
+  response = Net::HTTP.get_response(uri)
+  render json: { status: response.code.to_i, body: JSON.parse(response.body) }
+end
+```
+
+The `configure_proxy` callback sets `WasmHTTP::Connection.proxy_url` and `proxy_hosts` before each request, so the HTTP bridge knows which hosts to route through the proxy.
+
+**View** (`http_demo/index.html.erb`): Buttons trigger requests and the JSON response is displayed in a `<pre>` block.
+
+:::note
+Responses are synchronous — the browser waits for the full response before rendering. This is because the Ruby WASM runtime processes requests through a single-threaded queue.
+:::

package/template/src/content/tutorial/9-outbound-http/meta.md

@@ -0,0 +1,4 @@
+---
+type: part
+title: Outbound HTTP
+---

package/template/src/content/tutorial/meta.md

@@ -1,8 +1,13 @@
 ---
 type: tutorial
 openInStackBlitz: false
+meta:
+  image: /cover.png
+  title: My Rails Tutorial
+  description: An interactive Ruby on Rails tutorial powered by WebAssembly
 prepareCommands:
   - ['npm install', 'Preparing Ruby runtime']
+terminalBlockingPrepareCommandsCount: 1
 previews: false
 filesystem:
   watch: ['/*.json', '/workspace/**/*']

package/template/src/middleware.ts

@@ -0,0 +1,14 @@
+import { defineMiddleware } from 'astro:middleware';
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const response = await next();
+
+  // Required for WebContainer (SharedArrayBuffer)
+  response.headers.set('Cross-Origin-Embedder-Policy', 'require-corp');
+  response.headers.set('Cross-Origin-Opener-Policy', 'same-origin');
+
+  // Allow embedding in cross-origin pages
+  response.headers.set('Cross-Origin-Resource-Policy', 'cross-origin');
+
+  return response;
+});

package/template/src/templates/default/lib/boot-progress.js

@@ -0,0 +1,49 @@
+/**
+ * Boot progress reporting for Rails WASM initialization.
+ * Allows consumers to track the boot sequence stages.
+ */
+
+export class BootProgress {
+  constructor() {
+    this.listeners = new Set();
+    this.currentStep = "Initializing...";
+    this.currentValue = 0;
+  }
+
+  addListener(listener) {
+    this.listeners.add(listener);
+    listener({ step: this.currentStep, value: this.currentValue });
+  }
+
+  removeListener(listener) {
+    this.listeners.delete(listener);
+  }
+
+  updateStep(step) {
+    this.currentStep = step;
+    this.currentValue = 0;
+    this.notifyListeners();
+  }
+
+  updateProgress(value) {
+    this.currentValue = Math.min(100, Math.max(0, value));
+    this.notifyListeners();
+  }
+
+  notifyListeners() {
+    const state = { step: this.currentStep, value: this.currentValue };
+    for (const listener of this.listeners) {
+      try {
+        listener(state);
+      } catch (e) {
+        console.error("Boot progress listener error:", e);
+      }
+    }
+  }
+
+  log(message) {
+    console.log(`[boot] ${message}`);
+  }
+}
+
+export const bootProgress = new BootProgress();