gemstack 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30c68d4db704acae059c66f9847b0158ad178ebd7da1368c37056e5b93232306
-  data.tar.gz: 2b65b33d1e415354038e4f4bac03556196af8d95fc01f144c7a53e97d95527b1
+  metadata.gz: 3653be40ea53434b0176c572f0ecdba840c2af0b639a7d4ed64a9117037c72f4
+  data.tar.gz: 2a6fe58ab592b81ee4ecd2bbe794a9e6e94f1b693afa6963725f6ac1a0719f93
 SHA512:
-  metadata.gz: 9939a8e3bd4fb59fc2794ae86b66fc05751f8aa6463a4cd637cc8cd575ba300c2d824c02a4a245cda0a3b666e0107ab383f7e5a16499dffafda152e433b02448
-  data.tar.gz: 389c35595446d6c96ac811be7a978e019bb310e7cb03570b7e04033e1f2a3fda682cbecb1b1e513409933b18b5d6322375175ddc324ec23270a6a78308676af7
+  metadata.gz: f0059eae0a47937b5984e631adfd2430e0b261845f4d6165f3288d269b63cd3d9601b89b4b0efbde33933e678128350c4bdab767ed7cf8927d0e2272691beaee
+  data.tar.gz: 169b95e87f103a9d21a07e60b51da63da756381bdc541d9e57abf0224454e364d4d1d64c931398f3f702b545f4f5463be30eeefe7468ec899651ac1c63c04d8d

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.6
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
 ## 0.3.5
 
 See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/lib/gemstack/cli/app_generator.rb

@@ -28,16 +28,18 @@ module GemStack
         @module_name = Inflector.camelize(@name.tr("-", "_"))
         @gemstack_path = options[:gemstack_path] ? File.expand_path(options[:gemstack_path]) : detect_checkout
         @api_path = "/api"
+        self.templates = options[:templates] if options[:templates]
       end
 
-      def version = GemStack::VERSION
+      # (gemstack update renders older releases' templates with their own values.)
+      def version = @options[:version] || GemStack::VERSION
 
       # Pins the app to the Ruby that generated it, in files every version
       # manager reads (.ruby-version: rbenv, rvm, chruby, asdf, mise;
       # .tool-versions: asdf, mise), and Node.js likewise (.node-version,
       # .nvmrc, .tool-versions).
-      def ruby_version = RUBY_VERSION
-      def node_version = @node_version ||= Dev::Toolchain.pinned_node_version
+      def ruby_version = @options[:ruby_version] || RUBY_VERSION
+      def node_version = @node_version ||= @options[:node_version] || Dev::Toolchain.pinned_node_version
       def frontend? = !@options[:skip_frontend]
       def database? = !@options[:skip_database]
 

data/lib/gemstack/cli/deploy_generator.rb

@@ -77,10 +77,12 @@ module GemStack
       end
 
       def run
+        @manifest = GenerationManifest.new(@root)
         template_files("deploy", override_root: @root).sort.each do |rel, source|
           content = File.read(source)
           content = render(content, source) if rel.end_with?(".tt")
-          write(File.join(@root, output_path(rel.delete_suffix(".tt"))), content, mode: File.stat(source).mode)
+          write_tracked(File.join(@root, output_path(rel.delete_suffix(".tt"))), content,
+                        owner: "deploy:app", mode: File.stat(source).mode)
         end
         keep = File.join(@root, "vendor/.keep")
         write(keep, "") unless File.exist?(keep) # the Dockerfile copies vendor/ (e.g. vendor/cache)
@@ -88,6 +90,8 @@ module GemStack
         enable_standalone_frontend if frontend?
         warn_about_local_gems
         self
+      ensure
+        @manifest&.save
       end
 
       private

data/lib/gemstack/cli/destroy_generator/kinds.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    class DestroyGenerator < Generator
+      # What each kind owns, and what `destroy job|policy|deploy` checks beyond
+      # files and routes.
+      module Kinds
+        private
+
+        def owners_for(name)
+          case @kind
+          when "controller" then return ["controller:#{ControllerGenerator.new(name, [], root: @root).file_name}"]
+          when "job"
+            @constant = JobGenerator.class_name_for(name)
+            return ["job:#{Inflector.underscore(@constant)}"]
+          when "policy"
+            policy = PolicyGenerator.new(name, root: @root)
+            @constant = policy.class_name
+            return ["policy:#{policy.file_name}"]
+          when "migration"
+            file_name = Inflector.underscore(name.to_s)
+            raise Thor::Error, "Invalid migration name #{name.inspect}" unless file_name.match?(/\A[a-z][a-z0-9_]*\z/)
+
+            return ["migration:#{file_name}"]
+          when "deploy" then return ["deploy:app"]
+          end
+
+          @spec = ResourceSpec.new(name)
+          owners = ["model:#{@spec.file_name}"]
+          owners += ["controller:#{@spec.plural}", "resource:#{@spec.file_name}"] if @kind == "resource"
+          owners
+        end
+
+        # `gemstack generate deploy` adds exactly DeployGenerator::KAMAL_GEM; that
+        # line is removed, an edited one is left for the user.
+        def plan_gemfile
+          path = @manifest.absolute("Gemfile")
+          @gemfile_content = File.file?(path) ? File.read(path, encoding: "UTF-8") : ""
+          lines = @gemfile_content.lines
+          return unless lines.include?(DeployGenerator::KAMAL_GEM)
+
+          @gemfile_after = "#{lines.reject { |line| line == DeployGenerator::KAMAL_GEM }.join.rstrip}\n"
+        end
+
+        # A job or policy that other code still names would break it at runtime.
+        def check_constant_references
+          Dir.glob(File.join(@root, "{app,config,lib}/**/*.rb")).each do |absolute|
+            relative = Pathname.new(absolute).relative_path_from(Pathname.new(@root)).to_s
+            next if @files.key?(relative)
+
+            @manifest.absolute(relative)
+            tokens = Ripper.lex(File.read(absolute, encoding: "UTF-8"))
+            next unless tokens.any? { |_, type, text, _| type == :on_const && text == @constant.split("::").last }
+
+            @conflicts << "Remaining Ruby reference to #{@constant}: #{relative}"
+          end
+        end
+
+        def verify_gemfile!
+          return if File.read(@manifest.absolute("Gemfile"), encoding: "UTF-8") == @gemfile_content
+
+          raise Thor::Error, "Gemfile changed during confirmation; run destroy again"
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/cli/destroy_generator.rb

@@ -1,13 +1,20 @@
 # frozen_string_literal: true
 
 require "ripper"
+require_relative "destroy_generator/kinds"
 
 module GemStack
   class CLI < Thor
     # Plans the complete operation before changing anything. Only migrations
     # confirmed pending in the selected environment are eligible for removal.
     class DestroyGenerator < Generator
-      KINDS = %w[model controller resource].freeze
+      include Kinds
+
+      KINDS = %w[model controller resource job policy migration deploy].freeze
+      # Kinds that change the API, so the TypeScript contract is regenerated after them.
+      CONTRACT_KINDS = %w[model controller resource].freeze
+      # What `gemstack generate deploy` writes at the app's root.
+      DEPLOY_FILES = %w[Dockerfile .dockerignore config/deploy.yml .kamal/secrets bin/docker-entrypoint].freeze
       SHARED = (Generator::BASE_CLASSES.values + %w[
         app/controllers/application_controller.rb test/test_helper.rb
         frontend/lib/format.ts frontend/lib/gemstack/client.ts
@@ -36,7 +43,7 @@ module GemStack
           environment: options[:environment]
         )
         removal.run { options[:yes] || confirm?(cli) }
-        yield root if removal.changed? && !options[:skip_contract]
+        yield root if removal.contract_affected? && !options[:skip_contract]
       end
 
       def self.confirm?(cli)
@@ -48,8 +55,9 @@ module GemStack
       def initialize(kind, name, root:, dry_run: false, force: false, remove_migrations: false,
                      output: $stdout, environment: nil)
         super(output: output, force: force)
-        unless KINDS.include?(kind) && name && !name.empty?
-          raise Thor::Error, "Usage: gemstack destroy model|controller|resource NAME"
+        unless KINDS.include?(kind) && (kind == "deploy" || (name && !name.empty?))
+          raise Thor::Error, "Usage: gemstack destroy model|controller|resource|job|policy|migration NAME, " \
+                             "or gemstack destroy deploy"
         end
 
         @root = File.expand_path(root)
@@ -65,12 +73,13 @@ module GemStack
       end
 
       def changed? = @changed
+      def contract_affected? = @changed && CONTRACT_KINDS.include?(@kind)
 
       def run
         plan!
         preview
         raise Thor::Error, "Nothing removed:\n  #{@conflicts.join("\n  ")}" unless @conflicts.empty?
-        return self if @dry_run || (@files.empty? && @routes.empty?)
+        return self if @dry_run || (@files.empty? && @routes.empty? && !@gemfile_after)
 
         if block_given? && !yield
           @output.puts("Cancelled; no files changed.")
@@ -84,18 +93,6 @@ module GemStack
 
       private
 
-      def owners_for(name)
-        if @kind == "controller"
-          controller = ControllerGenerator.new(name, [], root: @root)
-          return ["controller:#{controller.file_name}"]
-        end
-
-        @spec = ResourceSpec.new(name)
-        owners = ["model:#{@spec.file_name}"]
-        owners += ["controller:#{@spec.plural}", "resource:#{@spec.file_name}"] if @kind == "resource"
-        owners
-      end
-
       def plan!
         @conflicts = []
         selected = @manifest.files.select { |_, entry| @owners.include?(entry["owner"]) }
@@ -105,13 +102,15 @@ module GemStack
         plan_migrations
         @files.each { |path, entry| check_file(path, entry) }
         plan_routes
+        plan_gemfile if @kind == "deploy"
         check_dependencies if @spec && @files.key?("app/models/#{@spec.file_name}.rb")
+        check_constant_references if @constant && @files.any?
       end
 
       def check_file(path, entry)
-        if SHARED.include?(path) || !path.start_with?("app/", "test/", "frontend/", "db/migrations/")
-          raise Thor::Error, "Refusing to remove shared or unsupported path: #{path}"
-        end
+        allowed = path.start_with?("app/", "test/", "frontend/", "db/migrations/") ||
+                  (@kind == "deploy" && DEPLOY_FILES.include?(path))
+        raise Thor::Error, "Refusing to remove shared or unsupported path: #{path}" if SHARED.include?(path) || !allowed
 
         absolute = @manifest.absolute(path)
         raise Thor::Error, "Expected a generated file: #{path}" if File.exist?(absolute) && !File.file?(absolute)
@@ -226,8 +225,11 @@ module GemStack
           status(@snapshots[path] ? "remove" : "missing", path)
         end
         @routes.each { |entry| status("unroute", "config/routes.rb", entry["line"].strip) }
-        if @files.empty? && @routes.empty?
-          @output.puts("No tracked files to remove. Resources generated before ownership tracking need manual removal.")
+        status("ungem", "Gemfile", "kamal") if @gemfile_after
+        if @files.empty? && @routes.empty? && !@gemfile_after
+          @output.puts("No tracked files to remove. Code generated before ownership tracking (resources, models " \
+                       "and controllers before 0.3.4; jobs, policies, migrations and deploy files before 0.3.6) " \
+                       "needs manual removal.")
         end
         @output.puts("Dry run; no files or API contracts changed.") if @dry_run
       end
@@ -235,15 +237,22 @@ module GemStack
       # Recheck after interactive confirmation, before the first mutation.
       def verify_snapshot!
         @manifest.verify!
+        verify_migrations!
+        verify_files!
+        verify_routes!
+        verify_gemfile! if @gemfile_after
+      end
 
+      def verify_migrations!
         if @pending && !@pending.empty? && @migration_status.applied != @applied
           raise Thor::Error, "Migration state changed or became unavailable; run destroy again"
         end
+        return unless @auto_removed_migrations&.any? { |path, _| @migration_git_status.committed(path) != false }
 
-        if @auto_removed_migrations&.any? { |path, _| @migration_git_status.committed(path) != false }
-          raise Thor::Error, "Migration Git state changed; run destroy again"
-        end
+        raise Thor::Error, "Migration Git state changed; run destroy again"
+      end
 
+      def verify_files!
         @snapshots.each do |relative, original|
           path = @manifest.absolute(relative)
           current = File.file?(path) ? Digest::SHA256.file(path).hexdigest : nil
@@ -252,12 +261,12 @@ module GemStack
                   "File changed during confirmation: #{relative}; run destroy again"
           end
         end
+      end
 
+      def verify_routes!
         path = @manifest.absolute("config/routes.rb")
         current = File.file?(path) ? File.read(path, encoding: "UTF-8") : ""
-        return if current == @route_content
-
-        raise Thor::Error, "Routes changed during confirmation; run destroy again"
+        raise Thor::Error, "Routes changed during confirmation; run destroy again" unless current == @route_content
       end
 
       def apply
@@ -266,10 +275,12 @@ module GemStack
           File.delete(path) if File.file?(path)
         end
         File.write(@manifest.absolute("config/routes.rb"), @route_after) unless @routes.empty?
+        File.write(@manifest.absolute("Gemfile"), @gemfile_after) if @gemfile_after
         @manifest.forget(@files.keys, @routes)
         @manifest.save
         @changed = true
         @output.puts("Removed tracked code. Database data was not changed.")
+        @output.puts("Run bundle install to update Gemfile.lock.") if @gemfile_after
       end
     end
   end

data/lib/gemstack/cli/generation_manifest.rb

@@ -12,6 +12,8 @@ module GemStack
     class GenerationManifest
       PATH = ".gemstack/generators.json"
       VERSION = 1
+      # "<generator>:<name>", e.g. "model:post", "job:send_digest", "deploy:app".
+      OWNER = %r{\A(?:model|controller|resource|job|policy|migration|deploy):[a-z][a-z0-9_]*(?:/[a-z][a-z0-9_]*)*\z}
 
       attr_reader :files, :routes
 
@@ -115,7 +117,7 @@ module GemStack
       end
 
       def owner?(owner)
-        owner.is_a?(String) && owner.match?(%r{\A(?:model|controller|resource):[a-z][a-z0-9_]*(?:/[a-z][a-z0-9_]*)*\z})
+        owner.is_a?(String) && owner.match?(OWNER)
       end
     end
   end

data/lib/gemstack/cli/generator.rb

@@ -23,7 +23,10 @@ module GemStack
         @created = []
       end
 
-      def template_root(name) = File.join(TEMPLATES, name)
+      # Another GemStack version's templates/ (gemstack update compares them).
+      attr_writer :templates
+
+      def template_root(name) = File.join(@templates || TEMPLATES, name)
 
       # Ruby core/stdlib names an app class must not reuse (a top-level class
       # named Digest or Set would collide with Ruby's own). Constants already
@@ -141,11 +144,11 @@ module GemStack
         true
       end
 
-      def write_tracked(path, content, owner:)
+      def write_tracked(path, content, owner:, mode: nil)
         relative = Pathname.new(File.expand_path(path)).relative_path_from(Pathname.new(File.expand_path(@root))).to_s
         @manifest.absolute(relative)
         existed = File.exist?(path)
-        return unless write(path, content)
+        return unless write(path, content, mode: mode)
 
         @manifest.record_file(path, owner: owner, existed: existed)
       end

data/lib/gemstack/cli/job_generator.rb

@@ -22,26 +22,35 @@ module GemStack
         generator.write(File.join(root, "db/migrations/#{stamp}_create_gemstack_jobs.rb"), Jobs::Migration::SOURCE)
       end
 
-      def initialize(name, root:, queue: nil, output: $stdout, force: false)
-        super(output: output, force: force)
-        @root = root
+      # The job class for NAME: "send_digest" → "SendDigest", "DigestJob" stays.
+      def self.class_name_for(name)
         base = Inflector.camelize(name.to_s).delete_suffix("Job")
         raise Thor::Error, "Invalid job name #{name.inspect}" unless base.match?(/\A[A-Z][A-Za-z0-9]*\z/)
 
-        @class_name = name.to_s.end_with?("Job") ? Inflector.camelize(name.to_s) : base
+        name.to_s.end_with?("Job") ? Inflector.camelize(name.to_s) : base
+      end
+
+      def initialize(name, root:, queue: nil, output: $stdout, force: false)
+        super(output: output, force: force)
+        @root = root
+        @class_name = self.class.class_name_for(name)
         @file_name = Inflector.underscore(@class_name)
         @queue_name = queue
         Generator.check_constant!(@class_name, suggestion: "#{@class_name}Job") unless name == "Placeholder"
       end
 
       def run
+        @manifest = GenerationManifest.new(@root)
         ensure_base_classes(@root, :job)
         template_files("job", override_root: @root).each do |rel, source|
           target = File.join(@root, rel.delete_suffix(".tt").gsub("%file_name%", file_name))
-          write(target, render(File.read(source), source))
+          write_tracked(target, render(File.read(source), source), owner: "job:#{file_name}")
         end
+        # The jobs table is shared by every job: not tracked, so destroy keeps it.
         self.class.install_migration(@root, output: @output) if File.directory?(File.join(@root, "db"))
         self
+      ensure
+        @manifest&.save
       end
     end
   end

data/lib/gemstack/cli/migration_generator.rb

@@ -26,11 +26,14 @@ module GemStack
       end
 
       def run
+        @manifest = GenerationManifest.new(@root)
         template_files("migration", override_root: @root).each do |rel, source|
           path = rel.delete_suffix(".tt").gsub("%timestamp%", timestamp).gsub("%file_name%", file_name)
-          write(File.join(@root, path), render(File.read(source), source))
+          write_tracked(File.join(@root, path), render(File.read(source), source), owner: "migration:#{file_name}")
         end
         self
+      ensure
+        @manifest&.save
       end
 
       private

data/lib/gemstack/cli/policy_generator.rb

@@ -24,11 +24,14 @@ module GemStack
       end
 
       def run
+        @manifest = GenerationManifest.new(@root)
         template_files("policy", override_root: @root).each do |rel, source|
           target = File.join(@root, rel.delete_suffix(".tt").gsub("%file_name%", file_name))
-          write(target, render(File.read(source), source))
+          write_tracked(target, render(File.read(source), source), owner: "policy:#{file_name}")
         end
         self
+      ensure
+        @manifest&.save
       end
     end
   end

data/lib/gemstack/cli/template_update.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "net/http"
+require "open3"
+require "rubygems/package"
+require "stringio"
+require "tempfile"
+require "tmpdir"
+
+module GemStack
+  class CLI < Thor
+    # Finds the templates/ directory of a GemStack version: this one, an
+    # installed gem, or the gem downloaded from rubygems.org.
+    module TemplateSource
+      module_function
+
+      # Releases since templates took their current layout (0.3.0).
+      FIRST = Gem::Version.new("0.3.0")
+
+      def locate(version, cache: Dir.mktmpdir("gemstack-templates"))
+        return Generator::TEMPLATES if version == GemStack::VERSION
+
+        installed(version) || download(version, cache)
+      end
+
+      # Every release before VERSION (rubygems.org's list, or the installed ones offline).
+      def releases_before(version)
+        limit = Gem::Version.new(version)
+        names = published_versions || installed_versions
+        names.map { |name| Gem::Version.new(name) }
+             .select { |v| !v.prerelease? && v >= FIRST && v < limit }.sort.map(&:to_s)
+      end
+
+      def published_versions
+        response = Net::HTTP.get_response(URI("https://rubygems.org/api/v1/versions/gemstack.json"))
+        JSON.parse(response.body).map { |release| release.fetch("number") } if response.is_a?(Net::HTTPSuccess)
+      rescue StandardError
+        nil
+      end
+
+      def installed_versions
+        gem_dirs.flat_map { |dir| Dir[File.join(dir, "gems", "gemstack-*", "templates")] }
+                .filter_map { |path| path[%r{gemstack-(\d+\.\d+\.\d+)/templates\z}, 1] }.uniq
+      end
+
+      def gem_dirs = (Gem.path + [(Bundler.bundle_path.to_s if defined?(Bundler))]).compact.uniq
+
+      def installed(version)
+        gem_dirs.map { |dir| File.join(dir, "gems", "gemstack-#{version}", "templates") }
+                .find { |path| File.directory?(path) }
+      end
+
+      def download(version, cache)
+        cache = File.join(cache, version)
+        FileUtils.mkdir_p(cache)
+        response = Net::HTTP.get_response(URI("https://rubygems.org/downloads/gemstack-#{version}.gem"))
+        return unless response.is_a?(Net::HTTPSuccess)
+
+        gem = File.join(cache, "gemstack-#{version}.gem")
+        File.binwrite(gem, response.body)
+        Gem::Package.new(gem).extract_files(cache, "templates/**/*")
+        templates = File.join(cache, "templates")
+        templates if File.directory?(templates)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # The template half of `gemstack update`: brings the files `gemstack new`
+    # wrote into line with this GemStack version. Each file is compared three
+    # ways — the app's copy, the old version's template and this version's,
+    # both rendered for this app — so only files a release changed are touched:
+    #
+    #   template unchanged            skipped (your edits are yours)
+    #   new in this version           created
+    #   you never edited the file     updated
+    #   you edited it                 you choose: overwrite, skip, diff, or save as FILE.new
+    #
+    # Apps record the templates they're on in .gemstack/version. Older apps don't,
+    # so each file is compared with every earlier release's template: matching
+    # one means you never edited it (it's just out of date). Without any old
+    # templates (offline), files that differ are offered, never updated.
+    class TemplateUpdate
+      VERSION_FILE = ".gemstack/version"
+      # Managed elsewhere: the Gemfile by `gemstack update`/Bundler.
+      MANAGED = %w[Gemfile .gemstack/version].freeze
+
+      # created/updated/saved (as FILE.new) are done; conflicts were left for you;
+      # removed are files you deleted, which stay deleted.
+      Result = Struct.new(:created, :updated, :saved, :conflicts, :removed, keyword_init: true)
+
+      def self.recorded_version(root)
+        path = File.join(root, VERSION_FILE)
+        File.read(path).strip if File.file?(path)
+      end
+
+      def initialize(root:, from: nil, output: $stdout, dry_run: false, interactive: $stdin.tty?, prompt: nil,
+                     old_templates: nil)
+        @root = root
+        @from = from || self.class.recorded_version(root)
+        @output = output
+        @dry_run = dry_run
+        @interactive = interactive && !dry_run
+        @prompt = prompt || lambda { |question|
+          @output.print("  #{question} ")
+          $stdin.gets.to_s.strip.downcase
+        }
+        @old_templates = old_templates
+        @result = Result.new(created: [], updated: [], saved: [], conflicts: [], removed: [])
+      end
+
+      def run
+        new_tree = render(Generator::TEMPLATES, version: GemStack::VERSION)
+        old_trees = old_trees_for_comparison
+        new_tree.each { |path, file| apply(path, file, old_trees.map { |tree| tree[path]&.content }) }
+        report
+        record_version unless @dry_run || @result.conflicts.any?
+        @result
+      end
+
+      private
+
+      AppFile = Struct.new(:content, :mode)
+
+      # The renders to compare with: the recorded/given version's, or every
+      # earlier release's when the app doesn't say which it came from.
+      def old_trees_for_comparison
+        trees = if @old_templates
+                  Array(@old_templates).map { |templates| render(templates, version: GemStack::VERSION) }
+                else
+                  release_trees(@from ? [@from] : TemplateSource.releases_before(GemStack::VERSION))
+                end
+        describe(trees)
+        trees
+      end
+
+      def release_trees(versions)
+        @versions = versions
+        Dir.mktmpdir("gemstack-templates") do |cache|
+          versions.filter_map do |version|
+            source = TemplateSource.locate(version, cache: cache)
+            render(source, version: version) if source
+          rescue Thor::Error
+            nil # an old template this version can't render: compare without it
+          end
+        end
+      end
+
+      def describe(trees)
+        if trees.empty?
+          @output.puts("Templates: earlier GemStack templates aren't available, so files that differ are " \
+                       "offered, never updated automatically")
+        elsif @from
+          @output.puts("Templates: comparing GemStack #{@from}'s with #{GemStack::VERSION}'s")
+        else
+          range = @versions&.any? ? " (#{@versions.first} to #{@versions.last})" : ""
+          @output.puts("Templates: the app doesn't record its templates version, so files are compared with " \
+                       "every earlier release#{range}")
+        end
+      end
+
+      # Renders `gemstack new` for this app (its name, database, frontend, pinned
+      # Ruby and Node.js) from a release's templates, as that release wrote them.
+      def render(templates, version:)
+        Dir.mktmpdir("gemstack-render") do |dir|
+          name = File.basename(@root).downcase.gsub(/[^a-z0-9_-]/, "-").sub(/\A[^a-z]+/, "")
+          destination = File.join(dir, name.empty? ? "app" : name)
+          options = app_options.merge(templates: templates, version: version)
+          AppGenerator.new(destination, options, output: StringIO.new).run
+          Dir.glob("**/*", File::FNM_DOTMATCH, base: destination).sort.filter_map do |rel|
+            full = File.join(destination, rel)
+            next unless File.file?(full) && !MANAGED.include?(rel)
+
+            [rel, AppFile.new(File.binread(full), File.stat(full).mode)]
+          end.to_h
+        end
+      rescue StandardError => e
+        raise Thor::Error, "Couldn't render the app templates (#{e.class}: #{e.message.lines.first&.strip})"
+      end
+
+      def app_options
+        database_yml = File.join(@root, "config/database.yml")
+        adapter = File.file?(database_yml) && File.read(database_yml)[/^\s+adapter:\s*(\w+)/, 1]
+        {
+          skip_install: true, skip_git: true,
+          skip_frontend: !File.file?(File.join(@root, "frontend/package.json")),
+          skip_database: !adapter, database: adapter || nil,
+          ruby_version: pinned(".ruby-version")&.delete_prefix("ruby-"),
+          node_version: pinned(".nvmrc") || pinned(".node-version")
+        }.compact
+      end
+
+      def pinned(file)
+        path = File.join(@root, file)
+        File.read(path).strip.delete_prefix("v").then { |value| value unless value.empty? } if File.file?(path)
+      end
+
+      # olds: this file's content in each compared release's render (nil where absent).
+      def apply(path, file, olds)
+        mine_path = File.join(@root, path)
+        mine = File.binread(mine_path) if File.file?(mine_path)
+        return if mine == file.content
+        return if olds.any? && olds.all?(file.content) # no release changed it: your edits are yours
+        # Missing: new to your app if some compared release didn't have it either;
+        # deleted by you if every one did (then it stays deleted).
+        return create(path, file) if mine.nil? && (olds.empty? || olds.include?(nil))
+        return @result.removed << path if mine.nil?
+        return update(path, file, :updated) if olds.include?(mine) # an unedited, older copy
+
+        conflict(path, file, mine)
+      end
+
+      def create(path, file)
+        write(path, file)
+        @result.created << path
+        status("create", path)
+      end
+
+      def update(path, file, kind)
+        write(path, file)
+        @result.public_send(kind) << path
+        status("update", path)
+      end
+
+      def conflict(path, file, mine)
+        return record_conflict(path) unless @interactive
+
+        loop do
+          case @prompt.call("#{path} changed in this version and you edited it — [o]verwrite, [s]kip, " \
+                            "[d]iff, save as [n]ew file?")
+          when "o" then return update(path, file, :updated)
+          when "n" then return save_new(path, file)
+          when "d" then @output.puts(diff(mine, file.content, path))
+          else return record_conflict(path)
+          end
+        end
+      end
+
+      def save_new(path, file)
+        write("#{path}.new", file)
+        @result.saved << path
+        status("create", "#{path}.new")
+      end
+
+      def record_conflict(path)
+        @result.conflicts << path
+        status("conflict", path)
+      end
+
+      def write(path, file)
+        return if @dry_run
+
+        target = File.join(@root, path)
+        FileUtils.mkdir_p(File.dirname(target))
+        File.binwrite(target, file.content)
+        File.chmod(file.mode & 0o777, target)
+      end
+
+      def diff(mine, theirs, path)
+        Tempfile.create("mine") do |a|
+          Tempfile.create("new") do |b|
+            a.write(mine)
+            b.write(theirs)
+            [a, b].each(&:flush)
+            labels = ["--label", "#{path} (yours)", "--label", "#{path} (new)"]
+            out, = Open3.capture2("diff", "-u", *labels, a.path, b.path)
+            out
+          end
+        end
+      rescue SystemCallError
+        "(diff isn't available on this system)"
+      end
+
+      def report
+        done = { "created" => @result.created, "updated" => @result.updated, "saved as .new" => @result.saved,
+                 "left for you" => @result.conflicts }.reject { |_, paths| paths.empty? }
+        if done.empty?
+          @output.puts("  nothing to update")
+        else
+          @output.puts("  #{done.map { |label, paths| "#{paths.size} #{label}" }.join(", ")}" \
+                       "#{" — dry run, nothing written" if @dry_run}")
+        end
+        return if @result.conflicts.empty?
+
+        @output.puts("  Review those in a terminal: gemstack update --templates#{" --from #{@from}" if @from}")
+      end
+
+      def record_version
+        target = File.join(@root, VERSION_FILE)
+        FileUtils.mkdir_p(File.dirname(target))
+        File.write(target, "#{GemStack::VERSION}\n")
+      end
+
+      def status(label, path) = @output.puts("  #{label.rjust(9)}  #{path}")
+    end
+  end
+end

data/lib/gemstack/cli/update_generator.rb

@@ -17,12 +17,20 @@ module GemStack
       VERSION_FORMAT = /\A\d+\.\d+\.\d+\z/
       LATEST_URL = "https://rubygems.org/api/v1/versions/gemstack/latest.json"
 
-      def initialize(root:, version: nil, output: $stdout, latest: nil, bundle: nil)
+      # The first version whose `gemstack update --templates` exists.
+      TEMPLATE_UPDATES_SINCE = Gem::Version.new("0.3.6")
+
+      def initialize(root:, version: nil, output: $stdout, latest: nil, bundle: nil, templates: nil)
         @root = root
         @version = version
         @output = output
         @latest = latest || -> { latest_release }
         @bundle = bundle || ->(gems) { Bundler.with_unbundled_env { system("bundle", "update", *gems, chdir: @root) } }
+        # Runs in the app's updated bundle, so the new version renders its own templates.
+        # (The lockfile's version can be newer than the app's templates, so it isn't passed on.)
+        @templates = templates || lambda {
+          Bundler.with_unbundled_env { system("bundle", "exec", "gemstack", "update", "--templates", chdir: @root) }
+        }
       end
 
       def run
@@ -71,9 +79,11 @@ module GemStack
           return failure("bundle update finished but Gemfile.lock has gemstack #{installed.inspect}, not #{target}")
         end
 
+        @output.puts("\nGemStack #{target} is installed.\n\n")
+        update_templates(target)
         @output.puts(<<~DONE)
 
-          GemStack #{target} is installed. Next:
+          Next:
             - read what changed: https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md
             - gemstack doctor
             - gemstack test
@@ -89,6 +99,12 @@ module GemStack
         end
       end
 
+      def update_templates(target)
+        return if Gem::Version.new(target) < TEMPLATE_UPDATES_SINCE
+
+        @templates.call || @output.puts("Templates weren't updated; run: gemstack update --templates")
+      end
+
       def gem_line(name) = /^\s*gem\s+["']#{Regexp.escape(name)}["']/
 
       def checkout(gemfile)

data/lib/gemstack/cli.rb

@@ -25,6 +25,7 @@ module GemStack
     require_relative "cli/deploy_generator"
     require_relative "cli/add_generator"
     require_relative "cli/update_generator"
+    require_relative "cli/template_update"
     require_relative "cli/commands/db"
     require_relative "cli/commands/jobs"
     require_relative "cli/console_methods"
@@ -188,7 +189,8 @@ module GemStack
       end
     end
 
-    desc "destroy GENERATOR NAME", "Remove tracked generated code (alias: d): model, controller, resource"
+    desc "destroy GENERATOR [NAME]",
+         "Remove generated code (alias: d): model, controller, resource, job, policy, migration, deploy"
     DestroyGenerator.configure(self)
     def destroy(generator = nil, name = nil)
       DestroyGenerator.invoke(generator, name, cli: self) { |root| refresh_contract(root) }
@@ -230,19 +232,35 @@ module GemStack
     desc "version", "Print the GemStack version"
     def version = say("GemStack #{GemStack::VERSION}")
 
-    desc "update [VERSION]", "Update this app to the latest GemStack release (or VERSION)"
+    desc "update [VERSION]", "Update this app to the latest GemStack release (or VERSION), templates included"
     long_desc <<~DESC
       Sets every GemStack gem in the Gemfile (gemstack, gemstack-auth, gemstack-realtime) to
       "~> VERSION" and runs bundle update for them. Without VERSION, uses the latest release on
-      rubygems.org.
-
-        gemstack update          # the latest release
-        gemstack update 0.3.5    # a specific version
+      rubygems.org. Then updates the files `gemstack new` wrote (config, bin/, frontend setup…):
+      files the release didn't change are left alone, new ones are created, ones you never edited
+      are updated, and for ones you edited you choose: overwrite, skip, see the diff, or FILE.new.
+
+        gemstack update                       # the latest release
+        gemstack update 0.3.6                 # a specific version
+        gemstack update --templates --dry-run # only the template step, preview
+        gemstack update --templates --from 0.3.5
     DESC
+    method_option :templates, type: :boolean, default: false, desc: "Only update the app's templates"
+    method_option :from, type: :string, desc: "--templates: the GemStack version the app's files came from"
+    method_option :dry_run, type: :boolean, default: false, desc: "--templates: show what would change"
     def update(version = nil)
+      return update_templates if options[:templates]
+
       exit(1) unless UpdateGenerator.new(root: Project.root!, version: version).run
     end
 
+    no_commands do
+      def update_templates
+        root = Project.ensure_bundle!(self.class.argv) # the app's installed GemStack renders its templates
+        TemplateUpdate.new(root: root, from: options[:from], dry_run: options[:dry_run]).run
+      end
+    end
+
     include Helpers
   end
 end

data/lib/gemstack/version.rb

@@ -2,5 +2,5 @@
 
 module GemStack
   # All GemStack gems are released together under a single version.
-  VERSION = "0.3.5"
+  VERSION = "0.3.6"
 end

data/templates/app/dot_gemstack/version.tt

@@ -0,0 +1 @@
+<%= version %>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemstack
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Adware Technologies
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.3.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.3.6
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -180,6 +180,7 @@ files:
 - lib/gemstack/cli/controller_generator.rb
 - lib/gemstack/cli/deploy_generator.rb
 - lib/gemstack/cli/destroy_generator.rb
+- lib/gemstack/cli/destroy_generator/kinds.rb
 - lib/gemstack/cli/doctor.rb
 - lib/gemstack/cli/doctor/secret_checks.rb
 - lib/gemstack/cli/doctor/upgrade_check.rb
@@ -195,6 +196,7 @@ files:
 - lib/gemstack/cli/project.rb
 - lib/gemstack/cli/resource_generator.rb
 - lib/gemstack/cli/resource_spec.rb
+- lib/gemstack/cli/template_update.rb
 - lib/gemstack/cli/update_generator.rb
 - lib/gemstack/contract.rb
 - lib/gemstack/contract/builder.rb
@@ -295,6 +297,7 @@ files:
 - templates/app/db/migrations/dot_keep
 - templates/app/db/seeds.rb
 - templates/app/dot_env.example.tt
+- templates/app/dot_gemstack/version.tt
 - templates/app/dot_gitignore
 - templates/app/dot_node-version.tt
 - templates/app/dot_nvmrc.tt