@tutorialkit-rb/cli 0.1.5 → 0.1.8

package/template/.claude/skills/rails-lesson-recipes/SKILL.md

@@ -0,0 +1,415 @@
+---
+name: rails-lesson-recipes
+description: |
+  Use this skill whenever creating a new lesson, choosing a lesson pattern, or validating
+  lesson structure. Trigger on: 'create a lesson', 'lesson recipe', 'lesson pattern',
+  'terminal-only lesson', 'code editing lesson', 'database lesson', 'console lesson',
+  'lesson sequence', 'multi-step lesson', 'validate lesson', 'check lesson', or asking
+  how to structure a Rails lesson — even without mentioning recipes. Provides five tested
+  blueprints (terminal-only, code-editing, database, full-app, console/IRB) with correct
+  frontmatter, directory layouts, content examples, and a post-creation validation
+  checklist. Do NOT create lessons without this skill — incorrect structure causes silent
+  failures. Do NOT use for frontmatter reference (use tutorial-lesson-config) or file
+  organization (use rails-file-management).
+---
+
+# Rails Lesson Recipes
+
+Ready-to-use patterns for common Rails tutorial lesson types.
+
+## Recipe 1: Terminal-Only Lesson
+
+**Use for:** Running generators, using the console, exploring CLI tools.
+**Example:** `rails new`, `rails console`, `rails generate`.
+
+### Directory Structure
+
+```
+1-creating-your-first-rails-app/
+  content.md
+  _files/
+    workspace/
+      .keep
+```
+
+### Frontmatter
+
+```yaml
+---
+type: lesson
+title: Creating your first Rails app
+editor: false
+custom:
+  shell:
+    workdir: "/workspace"
+---
+```
+
+### Key Decisions
+
+- `editor: false` — the user only interacts via terminal
+- `previews: false` — inherited from tutorial root (no server running)
+- Empty `workspace/.keep` — user creates the app from scratch
+- `workdir: "/workspace"` — terminal starts at the workspace root (before app exists)
+
+### Content Pattern
+
+```markdown
+# Creating Your First Rails App
+
+Run the following command to generate a new Rails application:
+
+\`\`\`bash
+$ rails new store
+\`\`\`
+
+:::info
+This may take a moment as Rails generates the application structure.
+:::
+
+After your new application is created, switch to its directory:
+
+\`\`\`bash
+$ cd store
+\`\`\`
+```
+
+---
+
+## Recipe 2: Code-Editing Lesson (with Preview)
+
+**Use for:** Writing controllers, models, views, routes — any lesson where the user edits code and sees results.
+**Example:** Adding a new action, modifying a view, updating routes.
+
+### Directory Structure
+
+```
+3-adding-a-controller/
+  content.md
+  _files/
+    .tk-config.json
+    workspace/
+      app/
+        controllers/
+          pages_controller.rb       ← starter/skeleton code
+      config/
+        routes.rb
+  _solution/
+    workspace/
+      app/
+        controllers/
+          pages_controller.rb       ← completed code
+        views/
+          pages/
+            home.html.erb           ← new file the user creates
+      config/
+        routes.rb
+```
+
+### Frontmatter
+
+```yaml
+---
+type: lesson
+title: Adding a Controller
+focus: /workspace/app/controllers/pages_controller.rb
+previews: [3000]
+mainCommand: ['node scripts/rails.js server', 'Starting Rails server']
+custom:
+  shell:
+    workdir: '/workspace'
+---
+```
+
+### `.tk-config.json`
+
+```json
+{
+  "extends": "../../../../../templates/rails-app"
+}
+```
+
+### Key Decisions
+
+- `focus` opens the file the user will edit
+- `previews: [3000]` shows the Rails app in a preview pane
+- `mainCommand` starts the Rails server after prepare commands finish
+- `_solution/` includes both modified files and new files the user was asked to create
+- Inherits `prepareCommands` (npm install) from tutorial root
+
+### Content Pattern
+
+```markdown
+# Adding a Controller
+
+Open `app/controllers/pages_controller.rb` in the editor. Add a `home` action:
+
+\`\`\`ruby title="app/controllers/pages_controller.rb" ins={2-4}
+class PagesController < ApplicationController
+  def home
+    @message = "Welcome to our store!"
+  end
+end
+\`\`\`
+
+Now create the view at `app/views/pages/home.html.erb`:
+
+\`\`\`erb title="app/views/pages/home.html.erb"
+<h1><%= @message %></h1>
+\`\`\`
+
+:::tip
+Click **Solve** to see the completed code if you get stuck.
+:::
+```
+
+---
+
+## Recipe 3: Database Lesson
+
+**Use for:** Migrations, models, seeds, ActiveRecord queries.
+**Example:** Creating a model, running migrations, seeding data.
+
+### Directory Structure
+
+```
+1-creating-a-model/
+  content.md
+  _files/
+    .tk-config.json
+    workspace/
+      db/
+        migrate/
+          20240101000000_create_products.rb
+        seeds.rb
+      app/
+        models/
+          product.rb
+```
+
+### Frontmatter
+
+```yaml
+---
+type: lesson
+title: Creating a Product Model
+focus: /workspace/app/models/product.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 development database']
+terminalBlockingPrepareCommandsCount: 2
+custom:
+  shell:
+    workdir: '/workspace'
+---
+```
+
+### Key Decisions
+
+- `prepareCommands` includes `db:prepare` — this runs migrations and seeds **before** the lesson becomes interactive
+- Migration files must have timestamps in filenames (Rails convention)
+- Seeds provide starting data so the user sees something immediately
+- Override `prepareCommands` at the lesson level (doesn't inherit the tutorial root's single command)
+
+### Content Pattern
+
+```markdown
+# Creating a Product Model
+
+Your Product model is defined in `app/models/product.rb`. Let's add validations:
+
+\`\`\`ruby title="app/models/product.rb"
+class Product < ApplicationRecord
+  validates :name, presence: true
+  validates :price, numericality: { greater_than: 0 }
+end
+\`\`\`
+
+The migration has already been run. Try it in the console:
+
+\`\`\`bash
+$ bin/rails console
+\`\`\`
+
+\`\`\`irb
+store(dev)> Product.create(name: "Widget", price: 9.99)
+store(dev)> Product.all
+\`\`\`
+```
+
+---
+
+## Recipe 4: Full-App Lesson (Pre-Built State)
+
+**Use for:** Teaching concepts that require a fully scaffolded app — CRUD, associations, authentication.
+**Example:** CRUD operations on an existing scaffold.
+
+### Directory Structure
+
+```
+2-crud-operations/
+  content.md
+  _files/
+    .tk-config.json
+    workspace/
+      .keep
+```
+
+### Frontmatter
+
+```yaml
+---
+type: lesson
+title: CRUD Operations
+focus: /workspace/app/controllers/products_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 development database']
+terminalBlockingPrepareCommandsCount: 2
+custom:
+  shell:
+    workdir: '/workspace'
+---
+```
+
+### `.tk-config.json`
+
+```json
+{
+  "extends": "../../../../../templates/crud-products"
+}
+```
+
+### Key Decisions
+
+- Uses `crud-products` template which provides a complete scaffolded app
+- `_files/` only contains `.tk-config.json` and a `.keep` — the template provides everything
+- `focus` points to the file being discussed in the lesson
+- No `_solution/` needed — this is an exploration/explanation lesson, not a coding exercise
+
+---
+
+## Recipe 5: Console/IRB Lesson
+
+**Use for:** Interactive Ruby exploration, testing models, querying the database.
+
+### Directory Structure
+
+```
+2-rails-console/
+  content.md
+  _files/
+    .tk-config.json
+    workspace/
+      .keep
+```
+
+### Frontmatter
+
+```yaml
+---
+type: lesson
+title: Rails Console
+custom:
+  shell:
+    workdir: "/workspace"
+---
+```
+
+### Key Decisions
+
+- No `editor`, no `previews`, no `mainCommand` — user works entirely in the terminal
+- Inherits `editor: true` by default but doesn't need to set `editor: false` since the user can still browse files
+- Uses a pre-built template via `.tk-config.json` so there's an app to explore
+
+---
+
+## Building Lesson Sequences
+
+### Progressive State Pattern
+
+For a series of lessons that build on each other, use **template layering**:
+
+```
+src/templates/
+  default/                  ← Base WASM runtime
+  rails-app/                ← Empty Rails app (extends default)
+  blog-base/                ← Blog app with Post model (extends rails-app)
+  blog-with-comments/       ← Blog app + Comment model (extends blog-base)
+
+src/content/tutorial/
+  1-blog/
+    meta.md                 ← type: part
+    1-setup/
+      content.md            ← Uses rails-app template
+      _files/.tk-config.json → ../../../../../templates/rails-app
+    2-posts/
+      content.md            ← Uses blog-base template
+      _files/.tk-config.json → ../../../../../templates/blog-base
+    3-comments/
+      content.md            ← Uses blog-with-comments template
+      _files/.tk-config.json → ../../../../../templates/blog-with-comments
+```
+
+Each template captures the **expected state** at the start of that lesson. This way:
+- Users can jump to any lesson without completing previous ones
+- Each lesson starts from a known-good state
+- Template inheritance keeps file duplication minimal
+
+### When to Create a New Template vs. Use `_files/`
+
+| Create a Template | Use `_files/` |
+|-------------------|---------------|
+| State is reused by 3+ lessons | Only this lesson needs these files |
+| State is complex (many files) | Just 1-3 files differ from the template |
+| You want users to jump to this lesson directly | Sequential lessons where order matters |
+
+### Lesson-to-Lesson Expectations
+
+**Always assume each lesson starts fresh.** The WASM runtime reinstalls on lesson navigation. Design each lesson to be self-contained:
+
+1. Use `prepareCommands` for setup (npm install, db:prepare) and `terminalBlockingPrepareCommandsCount: <number of commands>` to ensure terminal is not used before the prepare commands finish.
+2. Use templates or `_files/` for starting code state
+3. Don't rely on user actions from a previous lesson
+
+## Post-Creation Checklist
+
+After creating a lesson, verify these structural requirements. Violations cause silent failures at runtime.
+
+### Required
+
+- [ ] `content.md` exists in the lesson directory and has `type: lesson` in frontmatter
+- [ ] `content.md` has a `title` in frontmatter
+- [ ] All file paths in `_files/` start with `workspace/` (not `/workspace/`)
+- [ ] All file paths in `_solution/` start with `workspace/` (not `/workspace/`)
+- [ ] If `.tk-config.json` exists in `_files/`, its `extends` path resolves to an existing template directory under `src/templates/`
+- [ ] `_solution/` mirrors the `_files/` directory structure (paths must match for "Solve" to replace correctly)
+- [ ] `custom.shell.workdir` is set on the lesson itself (it does NOT inherit from parent `meta.md`)
+
+### If previews are enabled
+
+- [ ] `previews` is set (e.g., `previews: [3000]`)
+- [ ] `mainCommand` is set to start the server (e.g., `['node scripts/rails.js server', 'Starting Rails server']`)
+- [ ] `prepareCommands` includes `npm install` (either inherited from tutorial root or set explicitly)
+
+### If database is used
+
+- [ ] `prepareCommands` includes **both** `npm install` and `node scripts/rails.js db:prepare` (remember: arrays replace, not merge)
+- [ ] Migration files have timestamp prefixes in filenames
+- [ ] Seeds file exists if the lesson needs starting data
+
+### If focus is set
+
+- [ ] `focus` path is absolute from WebContainer root (e.g., `/workspace/app/...`)
+- [ ] The file at `focus` path exists in `_files/` or in the referenced template
+- [ ] `editor` is not set to `false` (focus is silently ignored when editor is hidden)
+
+### Path verification
+
+- [ ] `.tk-config.json` `extends` uses correct `../` count: 4 + number of intermediate levels above the lesson (typically 5 for `tutorial/part/lesson/_files/`)
+- [ ] `focus` paths use `/workspace/...` (absolute), while `_files/` paths use `workspace/...` (relative, no leading slash)
+- [ ] `scope` paths use `/workspace/...` (absolute)

package/template/.claude/skills/rails-wasm-author-constraints/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: rails-wasm-author-constraints
+description: |
+  Use this skill whenever checking if a Rails feature or gem works in WASM, or understanding
+  what's real vs. conceptual in lessons. Trigger on: 'does X work in WASM', 'can I use this
+  gem', 'gem compatibility', 'WASM limitation', 'what works', 'supported features', 'PGLite',
+  'threading', 'Net::HTTP', 'ActionCable', 'background jobs', 'can I teach X', 'bundle
+  install in WASM', 'conceptual vs real', or any Rails capability question — even without
+  mentioning WASM. Authoritative compatibility matrix: which features work, which are shimmed,
+  which are impossible, plus gem tiers, PGLite behavior, boot timing, and conceptual-vs-real
+  operations. General Rails knowledge is insufficient here. Do NOT use for file organization
+  (use rails-file-management) or frontmatter (use tutorial-lesson-config).
+---
+
+# Rails WASM Author Constraints
+
+What works, what doesn't, and how to design lessons around the WASM environment.
+
+## Quick Reference: What Can I Teach?
+
+| Rails Feature | Works? | Notes |
+|---------------|--------|-------|
+| ActiveRecord (CRUD, queries, scopes) | Yes | Full support via PGLite |
+| Migrations & schema management | Yes | Standard `rails db:migrate` |
+| Controllers & routing | Yes | Full support |
+| Views (ERB templates) | Yes | Full support |
+| Form helpers & validations | Yes | Full support |
+| Model associations | Yes | `has_many`, `belongs_to`, etc. |
+| Scaffolding & generators | Yes | `rails generate scaffold`, etc. |
+| Asset pipeline (Propshaft) | Yes | Importmaps, Stimulus, Turbo |
+| Rails console | Yes | Interactive IRB via custom bridge |
+| Authentication (basic) | Yes | `has_secure_password`, session-based |
+| ActionMailer (define mailers) | Partial | Can define/configure but delivery is a no-op |
+| Active Storage (upload) | Partial | Upload works but image processing is a no-op |
+| Background jobs | No | Single-threaded; Solid Queue won't process |
+| ActionCable / WebSockets | No | No `IO.select`, no real socket support |
+| External HTTP requests | No | No outbound networking from Ruby — sockets are unimplemented at the WASI level |
+| Threads / parallel processing | No | `Thread.new` uses fibers (cooperative, single-threaded) |
+| System commands from Ruby | No | `system()`, backticks, `Open3` are non-functional |
+
+## Hard Limitations
+
+These are **impossible to work around** in the WASM environment. Do not write lessons that depend on them:
+
+### No Outbound Networking
+
+Socket operations (`TCPSocket`, `UDPSocket`, and all socket classes) fail because the underlying WASI syscalls are unimplemented. `Net::HTTP` and `open-uri` will raise errors when attempting connections. You cannot:
+- Call external APIs from Ruby
+- Download files from the internet
+- Connect to external databases or services
+
+**Workaround for lessons:** If you want to teach API consumption, focus on the controller/model patterns and mock the responses. Show the code structure without executing real HTTP calls.
+
+### No Process Spawning
+
+`system()`, backticks, `exec`, `fork`, and `Open3` are non-functional. The `rails new` generator works because it's been patched, but arbitrary shell commands from tutorial code will not work.
+
+### No Threading
+
+`Thread.new` is shimmed to use `Fiber.new` (cooperative, single-threaded). Code that relies on parallel execution behaves differently. Background job processing and concurrent operations don't work as expected.
+
+### No IO.select
+
+The `poll_oneoff` WASI syscall is unimplemented. This breaks gems like nio4r, Puma, and ActionCable's EventMachine adapter.
+
+### No chmod/fchmod
+
+POSIX permission calls are stubbed. Avoid `FileUtils.chmod` in tutorial code. The `rails new` generator is pre-patched to handle this.
+
+## Gem Compatibility
+
+### Adding Gems
+
+Authors **can add gems** to their tutorial by editing `ruby-wasm/Gemfile` and running `bin/build-wasm` to rebuild the WASM binary. This bakes all gems into the binary at build time.
+
+### Compatibility Tiers
+
+| Tier | Description | Examples |
+|------|-------------|---------|
+| **Works** | Pure Ruby gems, no native extensions | `devise`, `friendly_id`, `pagy`, `pundit`, `draper`, `kaminari` |
+| **Shimmed** | Has native extensions but already patched | `nokogiri` (stub), `io-console` (stub), `bcrypt` |
+| **Needs testing** | May work if extension compiles for WASM | Test with `bin/build-wasm` |
+| **Won't work** | Requires unsupported syscalls or networking | `pg` (native), `mysql2`, `redis`, `sidekiq`, `puma` |
+
+### Pre-Shimmed Gems
+
+These gems are already handled by the WASM runtime:
+
+| Gem | Behavior |
+|-----|----------|
+| `nokogiri` | 165-line minimal stub; CSS selectors return `[]`; sufficient for sanitization but not real HTML parsing |
+| `io-console` | Stubbed; `winsize` returns `[80, 24]`; `raw` yields without change |
+| `nio4r` | `.so` stripped; loads as empty shim |
+| `date`, `psych`, `bigdecimal` | `.so` stripped; Ruby falls back to pure-Ruby stdlib |
+| `sqlite3` (native) | Replaced by PGLite adapter |
+
+### Gem Build Workflow
+
+```bash
+# 1. Edit the Gemfile
+vim ruby-wasm/Gemfile
+
+# 2. Rebuild the WASM binary (takes several minutes)
+bin/build-wasm
+
+# 3. Test your tutorial locally
+npm run dev
+```
+
+## Database: PGLite
+
+The database is **PGLite** — an in-browser PostgreSQL implementation compiled to WASM.
+
+### What Works
+
+- Standard ActiveRecord operations: `create`, `find`, `where`, `update`, `destroy`
+- Migrations: `rails db:migrate`, `rails db:rollback`
+- Seeds: `rails db:seed`
+- PostgreSQL-compatible SQL syntax
+- Multiple databases (development, test)
+- Associations, joins, aggregations
+- Indexes and constraints
+
+### What to Know
+
+| Behavior | Detail |
+|----------|--------|
+| **Data does not survive page reloads** | WebContainer filesystem is in-memory; refreshing the browser resets everything |
+| **Database adapter** | `pglite` (auto-configured by wasmify-rails; authors don't need to set this up) |
+| **Setup command** | `node scripts/rails.js db:prepare` in `prepareCommands` |
+| **Location** | `pgdata/<dbname>/` in WebContainer filesystem |
+| **Performance** | Slower than native PostgreSQL; acceptable for tutorial-sized datasets |
+
+### Lesson Design Implications
+
+- Always include `['node scripts/rails.js db:prepare', 'Prepare development database']` in `prepareCommands` for lessons that use the database
+- Provide seeds in templates so users start with data
+- Don't rely on data from a previous lesson persisting — each lesson should set up its own state via migrations + seeds
+
+## Boot Timing
+
+The WASM runtime takes time to load. Set expectations for tutorial users:
+
+| Phase | Typical Duration | What Happens |
+|-------|-----------------|--------------|
+| `npm install` | 10-30s | Downloads ~80MB WASM binary + dependencies |
+| WASM compile | 2-5s | Browser compiles the binary |
+| Rails bootstrap | 2-5s | Loads Rails framework from embedded VFS |
+| Command execution | Varies | User's command runs |
+
+**Total first-load time: 15-40 seconds** depending on network and browser.
+
+### Author Tips for Boot Experience
+
+- Include a note in early lessons: "The Ruby runtime takes a moment to load — this is normal!"
+- Use `prepareCommands` with descriptive labels so users see progress
+- The `['output', 'Setup Logs']` terminal panel shows boot details
+- Subsequent lesson navigation is faster if the WebContainer is already booted
+
+## Auto-Authentication
+
+The runtime includes an auto-login patch: if `tmp/authenticated-user.txt` exists in the Rails app root, the first HTTP request auto-authenticates the user found by `User.find_by(email_address: <file contents>)`. The file should contain a single email address (e.g., `admin@example.com`).
+
+**To use:** Place `workspace/tmp/authenticated-user.txt` in `_files/` or a template, containing the email of a seeded user. The first request calls `start_new_session_for(user)`, creating a session cookie for all subsequent requests. Runs once per VM lifetime (the `$__pre_authenticated` global flag prevents repeat attempts).
+
+This requires the Rails 8 `Authentication` concern and a `User` model with an `email_address` column.
+
+## Filesystem Boundaries
+
+Ruby code can only access `/workspace` (the WASI preopen). Attempting to access paths outside this boundary raises `Errno::ENOENT`. Tutorial code should never navigate above `/workspace` with `Dir.chdir("..")` or absolute paths outside the preopen.
+
+## Conceptual vs. Real Operations
+
+Some tutorial operations are **conceptual** — they teach the correct pattern but the actual execution requires something different in the WASM environment:
+
+| Operation in lesson content | Reality | What the author must do |
+|-----------------------------|---------|------------------------|
+| "Add `gem 'devise'` to your Gemfile" | Gems are baked into the WASM binary at build time | The gem must already be in `ruby-wasm/Gemfile` and rebuilt with `bin/build-wasm` **before** the tutorial is published |
+| "Run `bundle install`" | `bundle install` is a no-op in WASM — all gems come from the binary | Include it for pedagogical completeness; it will appear to succeed |
+| "Run `rails server`" | The Rails server runs through `node scripts/rails.js server` | Use `node scripts/rails.js server` in frontmatter `mainCommand`; in lesson content, show `rails server` since that's what the terminal wrapper understands |
+| "Edit `database.yml`" | Database adapter is PGLite, auto-configured by wasmify-rails | Pre-configure in the template; showing a `database.yml` edit is fine for teaching but won't change the runtime behavior |