Add --scratch flag for experimental demos

.gitignore

@@ -41,6 +41,9 @@ vendor/bundle/
 /demos/*/public/packs-test
 /demos/*/yarn-error.log
 
+# Scratch demos (experimental/temporary demos)
+/demos-scratch/
+
 # Testing
 /demos/*/coverage/
 /demos/*/test/reports/

.new-demo-versions

@@ -10,10 +10,10 @@
 RAILS_VERSION="8.0.3"
 
 # Shakapacker version (use ~> for compatibility range, or specific version)
-SHAKAPACKER_VERSION="~> 8.0"
+SHAKAPACKER_VERSION="github:shakacode/shakapacker"
 
 # React on Rails version (use ~> for compatibility range, or specific version)
-REACT_ON_RAILS_VERSION="~> 16.0"
+REACT_ON_RAILS_VERSION="~> 16.1"
 
 # ═══════════════════════════════════════════════════════════════════════
 # Version Management Workflows
@@ -32,4 +32,4 @@ REACT_ON_RAILS_VERSION="~> 16.0"
 # Updating existing demos to new versions:
 #   ./scripts/update-all-demos.sh --react-on-rails-version '~> 16.1'
 #
-# For detailed workflows, see: docs/VERSION_MANAGEMENT.md
+# For detailed workflows, see: docs/VERSION_MANAGEMENT.md

bin/new-demo

@@ -12,7 +12,8 @@ options = {
   react_on_rails_args: [],
   dry_run: false,
   shakapacker_prerelease: false,
-  react_on_rails_prerelease: false
+  react_on_rails_prerelease: false,
+  scratch: false
 }
 
 parser = OptionParser.new do |opts|
@@ -66,6 +67,10 @@ parser = OptionParser.new do |opts|
     options[:react_on_rails_prerelease] = true
   end
 
+  opts.on('--scratch', 'Create demo in gitignored /demos-scratch directory for experimentation') do
+    options[:scratch] = true
+  end
+
   opts.on('-h', '--help', 'Show this help message') do
     puts opts
     puts ''
@@ -87,6 +92,9 @@ parser = OptionParser.new do |opts|
     puts '  bin/new-demo my-demo --react-on-rails-args="--redux,--node"'
     puts '  bin/new-demo my-demo --rails-args="--skip-test" --react-on-rails-args="--redux"'
     puts ''
+    puts '  # Create experimental demo in gitignored directory'
+    puts '  bin/new-demo my-demo --scratch'
+    puts ''
     puts 'After creation, run E2E tests with:'
     puts '  cd demos/my-demo && npx playwright test'
     exit

lib/demo_scripts/demo_creator.rb

@@ -19,10 +19,13 @@ def initialize(
       dry_run: false,
       skip_pre_flight: false,
       shakapacker_prerelease: false,
-      react_on_rails_prerelease: false
+      react_on_rails_prerelease: false,
+      scratch: false
     )
       @demo_name = demo_name
-      @demo_dir = File.join('demos', demo_name)
+      @scratch = scratch
+      demos_base_dir = scratch ? 'demos-scratch' : 'demos'
+      @demo_dir = File.join(demos_base_dir, demo_name)
       @config = Config.new(
         shakapacker_version: shakapacker_version,
         react_on_rails_version: react_on_rails_version,
@@ -47,6 +50,8 @@ def create!
       end
       puts ''
 
+      @creation_start_time = Time.now
+
       create_rails_app
       setup_database
       add_gems
@@ -58,6 +63,7 @@ def create!
       build_github_npm_packages if using_github_sources?
       create_readme
       cleanup_unnecessary_files
+      create_metadata_file
 
       print_completion_message
     end
@@ -303,13 +309,13 @@ def copy_built_package(temp_dir, gem_name)
     def install_shakapacker
       puts ''
       puts '📦 Installing Shakapacker...'
-      @runner.run!('bin/rails shakapacker:install', dir: @demo_dir)
+      @runner.run!('bin/rails shakapacker:install --force', dir: @demo_dir)
     end
 
     def install_react_on_rails
       puts ''
       puts '📦 Installing React on Rails (skipping git check)...'
-      base_args = ['--ignore-warnings']
+      base_args = ['--ignore-warnings', '--force']
       all_args = (base_args + @react_on_rails_args).join(' ')
       @runner.run!(
         "bin/rails generate react_on_rails:install #{all_args}",
@@ -320,7 +326,7 @@ def install_react_on_rails
     def install_demo_common_generator
       puts ''
       puts '📦 Installing demo common tools (Playwright, linting, git hooks)...'
-      @runner.run!('bin/rails generate shakacode_demo_common:install', dir: @demo_dir)
+      @runner.run!('bin/rails generate shakacode_demo_common:install --force', dir: @demo_dir)
     end
 
     def create_readme
@@ -399,6 +405,55 @@ def generate_readme_content
       README
     end
 
+    def create_metadata_file
+      puts ''
+      puts '📝 Creating demo metadata file...'
+
+      return if @dry_run
+
+      shakapacker_github = @config.shakapacker_version&.start_with?('github:')
+      react_on_rails_github = @config.react_on_rails_version&.start_with?('github:')
+
+      metadata = {
+        demo_name: @demo_name,
+        demo_directory: @demo_dir,
+        scratch_mode: @scratch,
+        created_at: @creation_start_time.iso8601,
+        versions: {
+          rails: @config.rails_version,
+          shakapacker: @config.shakapacker_version,
+          react_on_rails: @config.react_on_rails_version
+        },
+        options: {
+          rails_args: @rails_args,
+          react_on_rails_args: @react_on_rails_args,
+          shakapacker_prerelease: shakapacker_github ? false : nil,
+          react_on_rails_prerelease: react_on_rails_github ? false : nil
+        }.compact,
+        command: reconstruct_command,
+        ruby_version: RUBY_VERSION,
+        bundler_version: Gem::Version.new(Bundler::VERSION).to_s
+      }
+
+      metadata_path = File.join(@demo_dir, '.demo-metadata.json')
+      File.write(metadata_path, JSON.pretty_generate(metadata))
+      puts "   Created #{metadata_path}"
+    end
+
+    def reconstruct_command
+      cmd_parts = ["bin/new-demo #{@demo_name}"]
+      cmd_parts << '--scratch' if @scratch
+      if @config.shakapacker_version != Config::DEFAULT_SHAKAPACKER_VERSION
+        cmd_parts << "--shakapacker-version=\"#{@config.shakapacker_version}\""
+      end
+      if @config.react_on_rails_version != Config::DEFAULT_REACT_ON_RAILS_VERSION
+        cmd_parts << "--react-on-rails-version=\"#{@config.react_on_rails_version}\""
+      end
+      cmd_parts << "--rails-args=\"#{@rails_args.join(',')}\"" if @rails_args.any?
+      cmd_parts << "--react-on-rails-args=\"#{@react_on_rails_args.join(',')}\"" if @react_on_rails_args.any?
+      cmd_parts.join(' ')
+    end
+
     def print_completion_message
       puts ''
       if @dry_run

spec/demo_scripts/demo_creator_spec.rb

@@ -18,6 +18,27 @@
 
       expect(creator).to be_a(described_class)
     end
+
+    it 'uses demos directory by default' do
+      creator = described_class.new(
+        demo_name: demo_name,
+        dry_run: true,
+        skip_pre_flight: true
+      )
+
+      expect(creator.instance_variable_get(:@demo_dir)).to eq("demos/#{demo_name}")
+    end
+
+    it 'uses demos-scratch directory when scratch flag is true' do
+      creator = described_class.new(
+        demo_name: demo_name,
+        scratch: true,
+        dry_run: true,
+        skip_pre_flight: true
+      )
+
+      expect(creator.instance_variable_get(:@demo_dir)).to eq("demos-scratch/#{demo_name}")
+    end
   end
 
   describe '#create!' do
@@ -521,4 +542,119 @@
       dry_run_creator.send(:cleanup_unnecessary_files)
     end
   end
+
+  describe '#create_metadata_file' do
+    subject(:creator) do
+      described_class.new(
+        demo_name: demo_name,
+        shakapacker_version: 'github:shakacode/shakapacker@main',
+        react_on_rails_version: '~> 16.0',
+        rails_args: ['--skip-test'],
+        react_on_rails_args: ['--redux', '--typescript'],
+        scratch: true,
+        dry_run: false,
+        skip_pre_flight: true
+      )
+    end
+
+    it 'creates metadata JSON file with correct structure' do
+      creator.instance_variable_set(:@creation_start_time, Time.now)
+      scratch_demo_dir = 'demos-scratch/test-demo'
+      metadata_path = File.join(scratch_demo_dir, '.demo-metadata.json')
+
+      expect(File).to receive(:write).with(metadata_path, anything)
+
+      creator.send(:create_metadata_file)
+    end
+
+    it 'includes all required metadata fields' do
+      creator.instance_variable_set(:@creation_start_time, Time.new(2025, 1, 1, 12, 0, 0, '+00:00'))
+      scratch_demo_dir = 'demos-scratch/test-demo'
+      metadata_path = File.join(scratch_demo_dir, '.demo-metadata.json')
+
+      allow(File).to receive(:write) do |path, content|
+        expect(path).to eq(metadata_path)
+        metadata = JSON.parse(content)
+
+        expect(metadata['demo_name']).to eq('test-demo')
+        expect(metadata['demo_directory']).to eq('demos-scratch/test-demo')
+        expect(metadata['scratch_mode']).to be true
+        expect(metadata['created_at']).to match(/2025-01-01T12:00:00/)
+        expect(metadata['versions']['shakapacker']).to eq('github:shakacode/shakapacker@main')
+        expect(metadata['versions']['react_on_rails']).to eq('~> 16.0')
+        expect(metadata['options']['rails_args']).to eq(['--skip-test'])
+        expect(metadata['options']['react_on_rails_args']).to eq(['--redux', '--typescript'])
+        expect(metadata['command']).to include('--scratch')
+        expect(metadata['ruby_version']).to eq(RUBY_VERSION)
+      end
+
+      creator.send(:create_metadata_file)
+    end
+
+    it 'does not create file in dry-run mode' do
+      dry_run_creator = described_class.new(
+        demo_name: demo_name,
+        dry_run: true,
+        skip_pre_flight: true
+      )
+      dry_run_creator.instance_variable_set(:@creation_start_time, Time.now)
+
+      expect(File).not_to receive(:write)
+
+      dry_run_creator.send(:create_metadata_file)
+    end
+  end
+
+  describe '#reconstruct_command' do
+    it 'reconstructs basic command' do
+      creator = described_class.new(
+        demo_name: demo_name,
+        dry_run: true,
+        skip_pre_flight: true
+      )
+
+      command = creator.send(:reconstruct_command)
+      expect(command).to eq('bin/new-demo test-demo')
+    end
+
+    it 'includes scratch flag when enabled' do
+      creator = described_class.new(
+        demo_name: demo_name,
+        scratch: true,
+        dry_run: true,
+        skip_pre_flight: true
+      )
+
+      command = creator.send(:reconstruct_command)
+      expect(command).to include('--scratch')
+    end
+
+    it 'includes custom version arguments' do
+      creator = described_class.new(
+        demo_name: demo_name,
+        shakapacker_version: 'github:shakacode/shakapacker@main',
+        react_on_rails_version: '~> 16.1',
+        dry_run: true,
+        skip_pre_flight: true
+      )
+
+      command = creator.send(:reconstruct_command)
+      expect(command).to include('--shakapacker-version="github:shakacode/shakapacker@main"')
+      expect(command).to include('--react-on-rails-version="~> 16.1"')
+    end
+
+    it 'includes rails and react-on-rails args' do
+      creator = described_class.new(
+        demo_name: demo_name,
+        rails_args: ['--skip-test', '--api'],
+        react_on_rails_args: ['--redux', '--typescript'],
+        dry_run: true,
+        skip_pre_flight: true
+      )
+
+      command = creator.send(:reconstruct_command)
+      expect(command).to include('--rails-args="--skip-test,--api"')
+      expect(command).to include('--react-on-rails-args="--redux,--typescript"')
+    end
+  end
 end