@tutorialkit-rb/cli 0.1.5 → 0.1.7

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 |

package/template/.claude/skills/tutorial-content-structure/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: tutorial-content-structure
+description: |
+  Use this skill whenever organizing tutorial content into parts, chapters, and lessons.
+  Trigger when the user says 'create a lesson', 'create a chapter', 'create a part', 'add
+  a lesson', 'tutorial structure', 'content.md', 'meta.md', 'lesson ordering', 'callout',
+  ':::tip', ':::info', ':::warn', 'code import', 'expressive code', or asks about the
+  content hierarchy, directory naming, or markdown features — even if they don't explicitly
+  mention content structure. This skill documents TutorialKit's specific directory conventions,
+  metadata file roles (meta.md vs content.md), numeric prefix ordering, the recommended
+  tutorial root config for Rails, callout syntax with all attributes, code block file imports,
+  and expressive code features. These are framework-specific patterns that cannot be inferred
+  from general knowledge. Do NOT use for frontmatter option reference (use
+  tutorial-lesson-config) or file/template organization (use rails-file-management).
+---
+
+# Tutorial Content Structure
+
+How to organize interactive Ruby on Rails tutorials using TutorialKit's content hierarchy.
+
+## Content Hierarchy
+
+Tutorials use a directory-based hierarchy under `src/content/tutorial/`:
+
+```
+src/content/tutorial/
+  meta.md                          # Tutorial root config (type: tutorial)
+  1-getting-started/               # Part
+    meta.md                        # Part config (type: part)
+    1-first-rails-app/             # Lesson (or Chapter, if it contains lessons)
+      content.md                   # Lesson content (type: lesson)
+      _files/                      # Initial code files
+      _solution/                   # Solution code files
+    2-rails-console/
+      content.md
+      _files/
+```
+
+The full hierarchy is **Tutorial > Parts > Chapters > Lessons**, but you can skip levels:
+
+| Structure | When to Use |
+|-----------|-------------|
+| Parts > Chapters > Lessons | Large tutorials with major sections and subsections |
+| Parts > Lessons | Medium tutorials grouped by topic |
+| Lessons only | Small tutorials or quick guides |
+
+## Directory Naming
+
+Directories use **numeric prefixes** for ordering: `1-basics/`, `2-controllers/`, `3-views/`.
+
+- The number determines display order in navigation
+- The text after the number becomes part of the URL slug
+- Use kebab-case: `1-creating-your-first-rails-app/`
+
+## Metadata Files
+
+### `meta.md` — Tutorial Root
+
+Every tutorial needs a root `meta.md` at `src/content/tutorial/meta.md`. This sets **inherited defaults** for all lessons:
+
+```yaml
+---
+type: tutorial
+prepareCommands:
+  - ['npm install', 'Preparing Ruby runtime']
+terminalBlockingPrepareCommandsCount: 1
+previews: false
+filesystem:
+  watch: ['/*.json', '/workspace/**/*']
+terminal:
+  open: true
+  activePanel: 0
+  panels:
+    - type: terminal
+      id: 'cmds'
+      title: 'Command Line'
+      allowRedirects: true
+    - ['output', 'Setup Logs']
+---
+```
+
+**Important for Rails tutorials:** The config above is the recommended baseline. It sets up `npm install` as a blocking prepare command (downloads the ~80MB WASM runtime), watches `/workspace/**/*` for file changes, and configures a persistent terminal with setup log output.
+
+### `meta.md` — Parts and Chapters
+
+Parts and chapters each get a `meta.md`:
+
+```yaml
+---
+type: part
+title: Getting Started with Rails
+---
+```
+
+```yaml
+---
+type: chapter
+title: Models and Databases
+---
+```
+
+Parts and chapters can also set inherited configuration (same options as tutorial root). Any setting here overrides the tutorial default for all lessons within.
+
+### `content.md` — Lessons
+
+Each lesson directory contains a `content.md` with frontmatter and markdown body:
+
+```yaml
+---
+type: lesson
+title: Creating your first Rails app
+editor: false
+custom:
+  shell:
+    workdir: "/workspace"
+---
+
+# Your lesson content here
+
+Write instructions, explanations, and code examples in standard markdown.
+```
+
+## Explicit Ordering
+
+Instead of relying on numeric prefixes, you can explicitly order children in `meta.md`:
+
+```yaml
+---
+type: tutorial
+parts:
+  - getting-started        # matches folder name (without numeric prefix)
+  - controllers
+  - views
+---
+```
+
+```yaml
+---
+type: part
+title: Getting Started
+lessons:
+  - creating-your-first-rails-app
+  - rails-console
+---
+```
+
+When using explicit ordering, folder names don't need numeric prefixes.
+
+## Markdown Features
+
+### Callouts
+
+```markdown
+:::tip
+Rails follows RESTful conventions, making your applications predictable.
+:::
+
+:::info
+You can customize the application Rails generates by using flags.
+:::
+
+:::warn
+This operation will reset the database.
+:::
+
+:::danger
+Never expose your secret_key_base in production.
+:::
+
+:::success
+Your Rails app is running!
+:::
+```
+
+Callouts support optional attributes:
+
+```markdown
+:::tip{title="Pro Tip"}
+Custom title for the callout.
+:::
+
+:::info{noBorder=true}
+Borderless callout style.
+:::
+
+:::warn{hideTitle=true}
+Only the message, no title bar.
+:::
+
+:::danger{hideIcon=true}
+Title shown but no icon.
+:::
+
+:::tip{class="my-custom-class"}
+Custom CSS class on the callout container.
+:::
+```
+
+| Attribute | Effect |
+|-----------|--------|
+| `title` | Custom title text (replaces default like "Tip", "Info") |
+| `noBorder` | `"true"` removes the left border |
+| `hideTitle` | `"true"` hides the entire title bar |
+| `hideIcon` | `"true"` hides the icon but keeps the title |
+| `class` | Additional CSS classes on the callout container |
+
+### Code Block File Imports
+
+Inline the contents of lesson files directly in your markdown:
+
+~~~markdown
+```file:/workspace/app/controllers/products_controller.rb
+```
+~~~
+
+This renders the contents of the file from the lesson's `_files/` directory. For solution files:
+
+~~~markdown
+```solution:/workspace/app/controllers/products_controller.rb
+```
+~~~
+
+### Expressive Code Attributes
+
+Code blocks support highlighting, line annotations, and framing:
+
+~~~markdown
+```ruby title="app/models/product.rb" showLineNumbers
+class Product < ApplicationRecord
+  validates :name, presence: true     # [!code highlight]
+  validates :price, numericality: { greater_than: 0 }
+end
+```
+~~~
+
+Available attributes:
+
+| Attribute | Example | Effect |
+|-----------|---------|--------|
+| `title` | `title="config/routes.rb"` | Shows filename header |
+| `showLineNumbers` | `showLineNumbers` | Display line numbers |
+| `ins={lines}` | `ins={2-3}` | Mark lines as inserted (green) |
+| `del={lines}` | `del={5}` | Mark lines as deleted (red) |
+| `{lines}` | `{1,3-5}` | Highlight specific lines |
+| `collapse={range}` | `collapse={1-5}` | Collapse line range |
+| `frame="terminal"` | `frame="terminal"` | Terminal-style frame |
+
+### Rails path links
+
+Inline code matching Rails path patterns (`app/`, `db/`, `config/`, `test/`) is automatically converted into clickable buttons that open the file in the editor:
+
+```markdown
+Open `app/models/user.rb` to see the User model.
+```
+
+This is handled by the `remarkRailsPathLinks` plugin. Only paths starting with `app/`, `db/`, `config/`, or `test/` are matched.
+
+### Links
+
+Standard markdown links work. For linking to the running app preview:
+
+```markdown
+Visit [the home page](http://localhost:3000) to see the result.
+```
+
+### MDX Support
+
+Rename `content.md` to `content.mdx` to use MDX features (component imports, JSX in markdown).
+
+## Styling Rails Views in Lessons
+
+The `rails-app` template includes a CSS design system with BEM components and CSS custom properties. When writing ERB views in `_files/` or `_solution/`, use these classes for consistent styling without adding custom CSS.
+
+### Common Patterns
+
+**Page with a list (index view):**
+
+```erb
+<div class="page-header">
+  <h1>Tickets</h1>
+  <%= link_to "New Ticket", new_ticket_path, class: "btn btn--primary" %>
+</div>
+
+<div class="card">
+  <table class="table">
+    <thead>
+      <tr>
+        <th>Title</th>
+        <th>Status</th>
+        <th></th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @tickets.each do |ticket| %>
+        <tr>
+          <td><%= link_to ticket.title, ticket %></td>
+          <td><span class="badge badge--primary"><%= ticket.status %></span></td>
+          <td class="inline-actions">
+            <%= link_to "Edit", edit_ticket_path(ticket), class: "btn btn--small" %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+```
+
+**Detail page (show view):**
+
+```erb
+<div class="page-header">
+  <h1><%= @ticket.title %></h1>
+  <div class="inline-actions">
+    <%= link_to "Edit", edit_ticket_path(@ticket), class: "btn btn--small" %>
+    <%= link_to "Back", tickets_path, class: "btn btn--small" %>
+  </div>
+</div>
+
+<div class="card mb-md">
+  <div class="card__body">
+    <p><%= @ticket.description %></p>
+    <p class="text-muted text-sm">
+      Created by <%= @ticket.user.name %> &middot;
+      <span class="badge badge--primary"><%= @ticket.status %></span>
+    </p>
+  </div>
+</div>
+```
+
+**Form:**
+
+```erb
+<div class="card">
+  <div class="card__header">
+    <h2>New Ticket</h2>
+  </div>
+  <div class="card__body">
+    <%= form_with model: @ticket do |form| %>
+      <div class="form__group">
+        <%= form.label :title, class: "form__label" %>
+        <%= form.text_field :title, class: "input" %>
+      </div>
+
+      <div class="form__group">
+        <%= form.label :description, class: "form__label" %>
+        <%= form.text_area :description, class: "input" %>
+      </div>
+
+      <div class="form__actions">
+        <%= form.submit "Create", class: "btn btn--primary" %>
+        <%= link_to "Cancel", tickets_path, class: "btn" %>
+      </div>
+    <% end %>
+  </div>
+</div>
+```
+
+**Flash messages** are handled automatically by the layout. Controllers just use `redirect_to ..., notice: "..."` or `alert: "..."`.
+
+### Quick Reference
+
+| Need | Classes |
+|------|---------|
+| Primary action button | `btn btn--primary` |
+| Destructive action | `btn btn--danger` |
+| Small inline button | `btn btn--small` |
+| Text input / textarea / select | `input` |
+| Wrap content in a box | `card` > `card__body` |
+| Box with title | `card` > `card__header` + `card__body` |
+| Status label | `badge badge--primary` (or `--success`, `--danger`, `--warning`) |
+| Data table | `table` |
+| Title + action row | `page-header` |
+| Form field wrapper | `form__group` > `form__label` + `input` |
+| Muted helper text | `text-muted text-sm` |
+| Row of buttons/links | `inline-actions` |
+
+See the `tutorial-quickstart` skill for the full CSS custom properties reference and the complete component list.