@tutorialkit-rb/cli 1.5.2-rb.0.1.0

package/template/src/components/RailsPathLinkHandler.tsx

@@ -0,0 +1,107 @@
+import { useStore } from '@nanostores/react';
+import type { PreviewInfo } from '@tutorialkit-rb/runtime';
+import { useEffect } from 'react';
+import tutorialStore from 'tutorialkit:store';
+
+const ensureRailsServerStarted = async (preview: PreviewInfo) => {
+  if (preview.ready) {
+    return;
+  }
+
+  const terminalConfig = tutorialStore.terminalConfig.get();
+  const terminal = terminalConfig.panels.find((panel) => panel.type === 'terminal');
+
+  if (!terminal || !terminal.process) {
+    return;
+  }
+
+  terminal.input(`bin/rails s\n`);
+
+  await new Promise<void>((resolve, reject) => {
+    const tid = setTimeout(() => {
+      clearInterval(tick);
+      reject();
+    }, 10000);
+
+    const tick = setInterval(() => {
+      if (preview.ready) {
+        clearInterval(tick);
+        clearTimeout(tid);
+        resolve();
+      }
+    }, 200);
+  });
+};
+
+export default function RailsPathLinkHandler() {
+  const previews = useStore(tutorialStore.previews);
+
+  useEffect(() => {
+    async function handleClick(event: MouseEvent) {
+      const target = event.target as HTMLElement;
+      const link = target.closest('.rails-path-link');
+
+      if (link) {
+        event.preventDefault();
+
+        const railsPath = link.getAttribute('data-rails-path');
+
+        if (railsPath) {
+          tutorialStore.setSelectedFile(`/workspace/store/${railsPath}`);
+        }
+
+        return;
+      }
+
+      if (target.tagName === 'A') {
+        const linkTarget = target as HTMLAnchorElement;
+
+        if (linkTarget.href.startsWith('http://localhost:3000')) {
+          event.preventDefault();
+
+          const railsPreview = previews.find((pr) => pr.port === 3000);
+
+          if (!railsPreview) {
+            return;
+          }
+
+          try {
+            await ensureRailsServerStarted(railsPreview);
+          } catch (error) {
+            console.error('failed to start Rails server', e);
+            return;
+          }
+
+          const input = document.querySelector(
+            'input[type="text"][name="tutorialkit-preview-navigation"]',
+          ) as HTMLInputElement;
+
+          if (!input) {
+            return;
+          }
+
+          const newPath = linkTarget.href.replace('http://localhost:3000/', '');
+
+          input.value = newPath;
+
+          const ev = new KeyboardEvent('keydown', {
+            key: 'Enter',
+            code: 'Enter',
+            keyCode: 13,
+            bubbles: true,
+            cancelable: true,
+          });
+          input.dispatchEvent(ev);
+        }
+      }
+    }
+
+    document.addEventListener('click', handleClick);
+
+    return () => {
+      document.removeEventListener('click', handleClick);
+    };
+  }, [previews]);
+
+  return null;
+}

package/template/src/components/ShellConfigurator.tsx

@@ -0,0 +1,95 @@
+import { useStore } from '@nanostores/react';
+import type { WebContainerProcess } from '@webcontainer/api';
+import { useEffect, useState } from 'react';
+import tutorialStore from 'tutorialkit:store';
+
+type ShellConfig = Partial<{
+  workdir: string;
+}>;
+
+let observedProcess: WebContainerProcess | undefined = undefined;
+let currWorkdir = '';
+
+export const ShellConfigurator: React.FC = () => {
+  const boot = useStore(tutorialStore.bootStatus);
+  const storeRef = useStore(tutorialStore.ref);
+  const terminalConfig = useStore(tutorialStore.terminalConfig);
+  const lessonLoaded = useStore(tutorialStore.lessonFullyLoaded);
+  const [state, set] = useState(0);
+
+  useEffect(() => {
+    const unlisten = tutorialStore.terminalConfig.listen(() => {
+      set(state + 1);
+    });
+    return unlisten;
+  }, [terminalConfig]);
+
+  const lesson = tutorialStore.lesson;
+  const terminal = terminalConfig.panels.find((panel) => panel.type === 'terminal');
+
+  useEffect(() => {
+    if (boot !== 'booted') {
+      return;
+    }
+
+    if (!lessonLoaded) {
+      return;
+    }
+
+    if (!lesson) {
+      return;
+    }
+
+    if (!terminal) {
+      return;
+    }
+
+    const conf = lesson?.data?.custom?.shell as ShellConfig;
+
+    if (!conf) {
+      return;
+    }
+
+    const { workdir } = conf;
+
+    if (!workdir) {
+      return;
+    }
+
+    if (currWorkdir === workdir) {
+      return;
+    }
+
+    currWorkdir = workdir;
+
+    const checkProcess = () => {
+      if (terminal.process || observedProcess) {
+        if (!observedProcess) {
+          observedProcess = terminal.process;
+        }
+
+        terminal.input(`cd /home/tutorial${workdir} && clear\n`);
+
+        return true;
+      }
+
+      return false;
+    };
+
+    // Check immediately
+    if (checkProcess()) {
+      return;
+    }
+
+    // Set up interval to wait for process
+    const interval = setInterval(() => {
+      if (checkProcess()) {
+        clearInterval(interval);
+      }
+    }, 100);
+
+    return () => clearInterval(interval);
+  }, [boot, terminalConfig, storeRef, lessonLoaded]);
+
+  return null;
+};

package/template/src/components/TopBar.astro

@@ -0,0 +1,48 @@
+---
+import path from 'node:path';
+import RailsPathLinkHandler from './RailsPathLinkHandler.tsx';
+import { ShellConfigurator } from './ShellConfigurator';
+import { FileManager } from './FileManager';
+import { HelpDropdown } from './HelpDropdown';
+import GitHubLink from './GitHubLink.astro';
+
+const logo = path.join(import.meta.env.BASE_URL, 'logo.svg');
+const logoDark = path.join(import.meta.env.BASE_URL, 'logo-dark.svg');
+---
+
+<nav
+  class="bg-tk-elements-topBar-backgroundColor transition-theme border-b border-tk-elements-app-borderColor flex max-w-full items-center p-3 px-4 min-h-[56px]"
+>
+  <div class="flex flex-1">
+    <a
+      href="/"
+      class="flex items-center text-tk-elements-topBar-logo-color hover:text-tk-elements-topBar-logo-colorHover"
+    >
+      {logo && <img class="h-5 w-auto dark:hidden" src={logo} />}
+      {logo && <img class="h-5 w-auto hidden dark:inline-block" src={logoDark} />}
+    </a>
+  </div>
+
+  <div class="mr-2">
+    <HelpDropdown client:only />
+  </div>
+  <div class="mr-2">
+    <slot name="download-button" />
+  </div>
+  <div class="mr-2">
+    <slot name="open-in-stackblitz-link" />
+  </div>
+  <div>
+    <slot name="theme-switch" />
+  </div>
+  <div>
+    <slot name="login-button" />
+  </div>
+  <div class="mr-2">
+    <GitHubLink />
+  </div>
+</nav>
+
+<RailsPathLinkHandler client:only />
+<ShellConfigurator client:only />
+<FileManager client:only />

package/template/src/content/config.ts

@@ -0,0 +1,9 @@
+import { contentSchema } from '@tutorialkit-rb/types';
+import { defineCollection } from 'astro:content';
+
+const tutorial = defineCollection({
+  type: 'content',
+  schema: contentSchema,
+});
+
+export const collections = { tutorial };

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

@@ -0,0 +1,34 @@
+---
+type: lesson
+title: Creating your first Rails app
+editor: false
+custom:
+  shell:
+    workdir: "/workspace/store"
+---
+
+Creating Your First Rails App
+-----------------------------
+
+Rails comes with several commands to make life easier. Run `rails --help` to see
+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:
+
+```bash
+$ rails new store
+```
+
+:::info
+You can customize the application Rails generates by using flags. To see
+these options, run `rails new --help`.
+:::
+
+After your new application is created, switch to its directory:
+
+```bash
+$ cd store
+```

package/template/src/content/tutorial/1-getting-started/2-rails-console/_files/.tk-config.json

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

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

@@ -0,0 +1,37 @@
+---
+type: lesson
+title: Rails Console
+custom:
+  shell:
+    workdir: "/workspace/store"
+---
+
+Rails Console
+-------------------
+
+Now that we have created our products table, we can interact with it in Rails.
+Let's try it out.
+
+For this, we're going to use a Rails feature called the *console*. The console
+is a helpful, interactive tool for testing our code in our Rails application. Run the following command in the terminal:
+
+```bash
+$ bin/rails console
+```
+
+You should see a prompt like the following:
+
+```irb
+Loading development environment (Rails 8.0.2)
+store(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
+<!-- hit Enter -->
+```
+
+If the line "8.0.2" appears, it works!

package/template/src/content/tutorial/1-getting-started/meta.md

@@ -0,0 +1,4 @@
+---
+type: part
+title: Getting Started with Rails
+---

package/template/src/content/tutorial/2-controllers/2-crud-operations/_files/.tk-config.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../../../templates/crud-products"
+}

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

@@ -0,0 +1,99 @@
+---
+type: lesson
+title: CRUD Operations
+focus: /workspace/store/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']
+custom:
+  shell:
+    workdir: '/workspace/store'
+---
+
+# CRUD Operations in Rails
+
+**CRUD** stands for Create, Read, Update, and Delete - the four basic operations you can perform on data. Rails makes CRUD operations simple and intuitive.
+
+## The Seven RESTful Actions
+
+Rails controllers typically include these seven standard actions:
+
+### Reading Data
+- **`index`** - List all products
+- **`show`** - Display a single product
+
+### Creating Data
+- **`new`** - Show form to create a product
+- **`create`** - Process form submission and save product
+
+### Updating Data
+- **`edit`** - Show form to edit a product
+- **`update`** - Process form submission and update product
+
+### Deleting Data
+- **`destroy`** - Delete a product
+
+## Try the CRUD Operations
+
+1. **View all products** - The home page shows the `index` action
+2. **Create a new product** - Click "New Product"
+3. **View a product** - Click on any product name
+4. **Edit a product** - Click "Edit" on any product
+5. **Delete a product** - Click "Delete" (with confirmation)
+
+## Routes and Actions
+
+Rails automatically creates RESTful routes for your resources:
+
+```ruby
+# In config/routes.rb
+resources :products
+```
+
+This generates these routes:
+
+| HTTP Method | URL | Controller Action | Purpose |
+|-------------|-----|-------------------|---------|
+| GET | `/products` | `index` | List all products |
+| GET | `/products/new` | `new` | Show new product form |
+| POST | `/products` | `create` | Create a product |
+| GET | `/products/1` | `show` | Show product #1 |
+| GET | `/products/1/edit` | `edit` | Show edit form for product #1 |
+| PATCH/PUT | `/products/1` | `update` | Update product #1 |
+| DELETE | `/products/1` | `destroy` | Delete product #1 |
+
+## Strong Parameters
+
+Notice how the controller uses **strong parameters** for security:
+
+```ruby
+def product_params
+  params.expect(product: [ :name, :description, :price ])
+end
+```
+
+This prevents users from submitting malicious data by only allowing specified parameters.
+
+## Forms and Validations
+
+Rails forms automatically:
+- Handle CSRF protection
+- Display validation errors
+- Maintain form state on errors
+
+Try creating a product with invalid data to see validation in action!
+
+:::tip
+Rails follows RESTful conventions, making your applications predictable and maintainable. The seven standard actions cover most use cases for managing resources.
+:::
+
+## Experiment
+
+Try modifying the controller:
+1. Add a search feature to the `index` action
+2. Add custom validations to the Product model
+3. Customize the success messages after create/update/delete
+
+CRUD operations are the foundation of most web applications!

package/template/src/content/tutorial/2-controllers/meta.md

@@ -0,0 +1,4 @@
+---
+type: part
+title: Controllers
+---

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

@@ -0,0 +1,18 @@
+---
+type: tutorial
+openInStackBlitz: false
+prepareCommands:
+  - ['npm install', 'Preparing Ruby runtime']
+previews: false
+filesystem:
+  watch: ['/*.json', '/workspace/**/*']
+terminal:
+  open: true
+  activePanel: 0
+  panels:
+    - type: terminal
+      id: 'cmds'
+      title: 'Command Line'
+      allowRedirects: true
+    - ['output', 'Setup Logs']
+---

package/template/src/env.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="@tutorialkit-rb/astro/types" />
+/// <reference types="astro/client" />

package/template/src/plugins/remarkRailsPathLinks.ts

@@ -0,0 +1,39 @@
+import type { Root, InlineCode } from 'mdast';
+import type { Plugin } from 'unified';
+import { visit } from 'unist-util-visit';
+
+// rails path patterns
+const RAILS_PATH_PATTERN = /^(app|db|config|test)\/.+$/;
+
+export interface RailsPathLinkOptions {
+  className?: string;
+}
+
+const remarkRailsPathLinks: Plugin<[RailsPathLinkOptions?], Root> = (options = {}) => {
+  const className = options.className || 'rails-path-link';
+
+  return (tree, _) => {
+    visit(tree, 'inlineCode', (node: InlineCode, index, parent) => {
+      if (!parent || typeof index !== 'number') {
+        return;
+      }
+
+      // check if the inline code content matches Rails path pattern
+      const content = node.value;
+
+      if (!RAILS_PATH_PATTERN.test(content)) {
+        return;
+      }
+
+      // replace the inline code node with an HTML node containing a link
+      const htmlNode = {
+        type: 'html',
+        value: `<button class="${className}" data-rails-path="${content}"><code>${content}</code></button>`,
+      };
+
+      parent.children[index] = htmlNode as any;
+    });
+  };
+};
+
+export default remarkRailsPathLinks;

package/template/src/templates/crud-products/.tk-config.json

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

package/template/src/templates/crud-products/workspace/store/app/controllers/products_controller.rb

@@ -0,0 +1,48 @@
+class ProductsController < ApplicationController
+  before_action :set_product, only: %i[ show edit update destroy]
+
+  def index
+    @products = Product.all
+  end
+
+  def show
+  end
+
+  def new
+    @product = Product.new
+  end
+
+  def create
+    @product = Product.new(product_params)
+    if @product.save
+      redirect_to @product
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def edit
+  end
+
+  def update
+    if @product.update(product_params)
+      redirect_to @product
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+	def destroy
+    @product.destroy
+    redirect_to products_path
+  end
+
+  private
+    def set_product
+      @product = Product.find(params[:id])
+    end
+
+    def product_params
+      params.expect(product: [ :name ])
+    end
+end

package/template/src/templates/crud-products/workspace/store/app/models/product.rb

@@ -0,0 +1,3 @@
+class Product < ApplicationRecord
+  validates :name, presence: true
+end

package/template/src/templates/crud-products/workspace/store/app/views/products/_form.html.erb

@@ -0,0 +1,10 @@
+<%= form_with model: product do |form| %>
+  <div>
+    <%= form.label :name %>
+    <%= form.text_field :name %>
+  </div>
+
+  <div>
+    <%= form.submit %>
+  </div>
+<% end %>

package/template/src/templates/crud-products/workspace/store/app/views/products/edit.html.erb

@@ -0,0 +1,4 @@
+<h1>Edit product</h1>
+
+<%= render "form", product: @product %>
+<%= link_to "Cancel", @product %>

package/template/src/templates/crud-products/workspace/store/app/views/products/index.html.erb

@@ -0,0 +1,11 @@
+<h1>Products</h1>
+
+<%= link_to "New product", new_product_path %>
+
+<div id="products">
+  <% @products.each do |product| %>
+    <div>
+      <%= link_to product.name, product_path(product.id) %>
+    </div>
+  <% end %>
+</div>

package/template/src/templates/crud-products/workspace/store/app/views/products/new.html.erb

@@ -0,0 +1,4 @@
+<h1>New product</h1>
+
+<%= render "form", product: @product %>
+<%= link_to "Cancel", products_path %>

package/template/src/templates/crud-products/workspace/store/app/views/products/show.html.erb

@@ -0,0 +1,5 @@
+<h1><%= @product.name %></h1>
+
+<%= link_to "Back", products_path %>
+<%= link_to "Edit", edit_product_path(@product) %>
+<%= button_to "Delete", @product, method: :delete, data: { turbo_confirm: "Are you sure?" } %>

package/template/src/templates/crud-products/workspace/store/config/routes.rb

@@ -0,0 +1,6 @@
+Rails.application.routes.draw do
+  resources :products
+
+  # Defines the root path route ("/")
+  root "products#index"
+end

package/template/src/templates/crud-products/workspace/store/db/migrate/20250521010850_create_products.rb

@@ -0,0 +1,9 @@
+class CreateProducts < ActiveRecord::Migration[8.0]
+  def change
+    create_table :products do |t|
+      t.string :name
+
+      t.timestamps
+    end
+  end
+end

package/template/src/templates/crud-products/workspace/store/db/schema.rb

@@ -0,0 +1,22 @@
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema[8.0].define(version: 2025_05_21_010850) do
+  # These are extensions that must be enabled in order to support this database
+  enable_extension "pg_catalog.plpgsql"
+
+  create_table "products", force: :cascade do |t|
+    t.string "name"
+    t.datetime "created_at", precision: nil, null: false
+    t.datetime "updated_at", precision: nil, null: false
+  end
+end

package/template/src/templates/crud-products/workspace/store/db/seeds.rb

@@ -0,0 +1,3 @@
+# Create products that we should have created in the previous lessons
+Product.create(name: "T-Shirt").destroy
+Product.create(name: "Pants")