hamster-web 0.1.0.pre.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da9a6aefcced6e728e844a09b04ebaab4d6970b0742b9e527be34c36bcc52de1
+  data.tar.gz: f063de9bfdd15a06f17992ed6efd23cb6e3ad50fbe99195ec2e82718e11b2aef
+SHA512:
+  metadata.gz: 1a06018d216e769b046d6ec6614ff110ab61fce962de8f35d38ee96a8cccbbf67fe73c5d1c6885e225e8f76b5757ef56b5a4b8f18f6f208fc7c2570a1e3b2a3c
+  data.tar.gz: 47d17563010f3acb9f3b678dd9c2027e2ebedb38cc31b7d28c4abecab57fa994f696a8d72f8551006dc7c5d374ebb36f37431ac466e910e1b0b0cc28b66b8ae9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dillon Wyatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,61 @@
+# Hamster Web
+
+Hamster is a Spinel web framework under development. The `hamster-web` gem will
+provide the `hamster` CLI and the `hamster/web` application runtime. Spinner is
+its HTTP server dependency.
+
+The starter generates and compiles with PostgreSQL support, explicit routes,
+actions, compiled views, and SQL migrations. Database creation and migration
+commands, the console, and schema-aware records/queries are available.
+Telemetry extraction and asset delivery remain under development.
+
+Build and install the local framework preview:
+
+```sh
+gem build hamster-web.gemspec
+gem install --local hamster-web-0.1.0.pre.2.gem
+hamster new MyApp
+cd my_app
+bin/hamster setup
+# Configure PostgreSQL credentials; these defaults use your local OS role.
+export DATABASE_USERNAME="$USER"
+export DATABASE_ADMIN_USERNAME="$USER"
+export DATABASE_PASSWORD=""
+export DATABASE_ADMIN_PASSWORD=""
+bin/hamster db:create
+bin/hamster db:migrate
+bin/hamster build
+bin/hamster serve
+```
+
+Run framework tests with `ruby -Ilib -e 'Dir["test/*_test.rb"].sort.each { |file| require_relative file }'`.
+
+## Records and queries
+
+Load `hamster/data` (also loaded by the PostgreSQL adapter) and declare models
+with `Hamster::Table`, `table`, and literal `column` definitions. Columns must
+explicitly opt into writes with `write: :create`, `:update`, or `:both`.
+Creation returns a result with `success?`, `record`, and `errors`; `create!`
+returns the record or raises a typed error. Timestamps are maintained only
+when the model declares created_at or updated_at columns.
+
+`database.with_connection` binds the connection for record writes. Queries
+such as `Post.where(title: "Hello").order(:id).load` return typed rows. Explicit
+callers can also pass `connection:` to query terminal methods or scope writes
+with `Hamster::Record.with_connection(connection)`.
+
+Run `hamster manifest` after adding columns or query fields: it generates the
+static getters and setters used by Spinel. Rebuild after model changes.
+
+## Console and schema checks
+
+Run `hamster console` (or `hamster c`) in an application. The IRB session exposes
+`app`, `application`, and `database`; record operations use a connection scoped
+to that session. Exit releases the connection and shuts down the application.
+Database environment settings apply as they do to the server.
+
+Run `hamster db:validate` to compare declared tables and columns against the
+configured PostgreSQL database. It reports missing tables/columns, incompatible
+types, and unexpected nullability with a nonzero exit status. It never migrates
+or modifies the schema. Configuration is loaded through config/commands.rb,
+a CRuby-only adapter generated with new applications.

data/exe/hamster

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rbconfig"
+
+# Resolve the application's version before activating this executable's gem.
+# A global preview can otherwise supply stale source paths to Spinel even
+# when the application's Gemfile points at a newer framework checkout.
+unless ARGV.first == "new"
+  root = Dir.pwd
+  loop do
+    binstub = File.join(root, "bin/hamster")
+    if File.file?(File.join(root, "config/hamster.json")) && File.file?(binstub)
+      exec(RbConfig.ruby, binstub, *ARGV) unless File.expand_path(binstub) == File.expand_path(__FILE__)
+      break
+    end
+    parent = File.dirname(root)
+    break if parent == root
+    root = parent
+  end
+end
+
+require "hamster/cli"
+exit Hamster::CLI.run(ARGV)

data/lib/hamster/build/manifest.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "ripper"
+require_relative "../web"
+require_relative "view_compiler"
+require_relative "query_accessors"
+
+module Hamster
+  module Build
+    module Manifest
+      module_function
+
+      def outputs(root)
+        paths = Dir.glob("{app,db}/**/*.rb", base: root).sort_by do |path|
+          priority = path.start_with?("db/") ? 0 : path.start_with?("app/models/") ? 1 : 2
+          priority = 3 if path == "app/routes/mappings.rb"
+          [priority, path]
+        end
+        sources = {}
+        Dir.glob("{app/routes,app/views}/**/*.html.erb", base: root).sort.each do |path|
+          name = path.sub(%r{\Aapp/(?:routes|views)/}, "").sub(%r{/view\.html\.erb\z}, "").delete_suffix(".html.erb")
+          raise View::Error, "duplicate template #{name}" if sources.key?(name)
+          sources[name] = {path: path, source: File.read(File.join(root, path))}
+        end
+        lines = paths.map { |path| %(require_relative "../#{path.delete_suffix('.rb')}") }
+        paths.each { |path| lines.concat(QueryAccessors.lines(File.read(File.join(root, path)))) }
+        paths.each { |path| lines.concat(QueryAccessors.lines(File.read(File.join(root, path)), declaration: "column", writers: true)) }
+        lines << 'require_relative "view_registry"'
+        {
+          "config/manifest.rb" => "# frozen_string_literal: true\n# Generated by hamster manifest.\n" + lines.join("\n") + "\n",
+          "config/view_registry.rb" => ViewCompiler.compile(sources)
+        }
+      end
+
+      def generate(root)
+        outputs(root).each { |path, content| File.write(File.join(root, path), content) }
+      end
+
+      def check(root)
+        issues = outputs(root).filter_map do |path, expected|
+          actual = File.file?(File.join(root, path)) ? File.read(File.join(root, path)) : nil
+          "#{path} is missing or stale; run bin/hamster manifest" unless actual == expected
+        end
+        Dir.glob("{app,db}/**/*.rb", base: root).each do |path|
+          Ripper.lex(File.read(File.join(root, path))).each do |position, type, token, _|
+            issues << "#{path}:#{position[0]}: load files through the manifest" if type == :on_ident && token == "require_relative"
+          end
+        end
+        issues
+      end
+    end
+  end
+end

data/lib/hamster/build/postgres_compatibility.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hamster
+  module Build
+    module PostgresCompatibility
+      REVISION = "5ff0188b0e8dffc88337723411ac725ee2659ff7"
+      COPIES = [
+        'sev = PgDecode.error_field(body, "V")',
+        'sev = PgDecode.error_field(body, "S")',
+        'tag = PgDecode.command_tag(m.body)'
+      ].freeze
+
+      # The pinned driver predates its Spinel string-ownership workarounds.
+      # Apply explicit copies after vendoring, before compiling; never patch
+      # an unrecognized revision or silently accept a changed source shape.
+      def self.apply(root)
+        package = File.join(root, "vendor/packages/pg-0.2.0")
+        marker = File.join(package, ".spin-sha")
+        unless File.file?(marker) && File.read(marker).strip == REVISION
+          raise "PostgreSQL compatibility patch requires pg revision #{REVISION}; run bin/hamster setup with the supported lockfile"
+        end
+        path = File.join(package, "pg/client.rb")
+        source = File.read(path)
+        patched = source.lines.map do |line|
+          statement = line.strip
+          replacement = COPIES.find { |original| statement == original || statement == original + ".dup" }
+          replacement && statement == replacement ? line.sub(replacement, replacement + ".dup") : line
+        end.join
+        COPIES.each do |original|
+          unless patched.lines.count { |line| line.strip == original + ".dup" } == 1
+            raise "PostgreSQL compatibility patch source mismatch: #{original}"
+          end
+        end
+        File.write(path, patched) unless patched == source
+      end
+    end
+  end
+end

data/lib/hamster/build/query_accessors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "ripper"
+
+module Hamster
+  # Spinel's macro expander requires every argument to be literal. Query.field's
+  # source expression isn't, so emit ordinary getters before AOT compilation.
+  module QueryAccessors
+    module_function
+
+    def lines(source, declaration: "field", writers: false)
+      tree = Ripper.sexp(source)
+      raise "Cannot parse Ruby while generating Query getters" unless tree
+      getters = {}
+      visit(tree, [], getters, declaration)
+      getters.flat_map do |path, names|
+        ["class #{path}"] + names.uniq.flat_map { |name| ["  def #{name}; self[:#{name}]; end"] + (writers ? ["  def #{name}=(value); write_attribute(:#{name}, value); end"] : []) } + ["end"]
+      end
+    end
+
+    def constant(node)
+      return nil unless node.is_a?(Array)
+      case node[0]
+      when :@const then node[1]
+      when :const_ref, :var_ref then constant(node[1])
+      when :top_const_ref then "::#{constant(node[1])}"
+      when :const_path_ref, :const_path_field then "#{constant(node[1])}::#{constant(node[2])}"
+      end
+    end
+
+    def visit(node, scope, getters, declaration)
+      return unless node.is_a?(Array)
+      if node[0] == :class || node[0] == :module
+        name = constant(node[1])
+        return unless name
+        path = name.start_with?("::") ? name.delete_prefix("::") : (scope + [name]).join("::")
+        body = node[node[0] == :class ? 3 : 2]
+        visit(body, [path], getters, declaration)
+      elsif [:def, :defs].include?(node[0])
+        return
+      elsif (node[0] == :command && node[1][1] == declaration) ||
+            (node[0] == :method_add_arg && node[1][0] == :fcall && node[1][1][1] == declaration)
+        args = node[2]
+        args = args[1] if args && args[0] == :arg_paren
+        first = args[1][0] if args && args[0] == :args_add_block
+        literal = first[1][1] if first && first[0] == :symbol_literal && first[1][0] == :symbol
+        name = literal[1] if literal && [:"@ident", :"@op", :"@kw"].include?(literal[0])
+        if first && first[0] == :string_literal && first[1][0] == :string_content && first[1].length == 2
+          name = first[1][1][1] if first[1][1][0] == :@tstring_content
+        end
+        unless name && name.match?(/\A[a-z_][a-z0-9_]*\z/)
+          raise "#{scope.join('::')}: Query field names must be literal accessor names for Spinel"
+        end
+        unless scope.empty?
+          getters[scope.join("::")] ||= []
+          getters[scope.join("::")] << name
+        end
+      else
+        node.each { |child| visit(child, scope, getters, declaration) if child.is_a?(Array) }
+      end
+    end
+  end
+end
+
+# Standalone scripts and compiled fixtures can use the same static getter pass.
+# ruby tools/query_accessors.rb test/spinel_query_smoke.rb > /tmp/query-smoke.rb
+if $PROGRAM_NAME == __FILE__
+  abort "Usage: ruby tools/query_accessors.rb SOURCE.rb [SOURCE.rb ...]" if ARGV.empty?
+  ARGV.each do |path|
+    puts "require_relative #{File.expand_path(path).inspect}"
+    puts Hamster::QueryAccessors.lines(File.read(path))
+  end
+end

data/lib/hamster/build/view_compiler.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "ripper"
+
+module Hamster
+  module ViewCompiler
+    module_function
+
+    NAME = /\A[a-z][a-z0-9_]*(?:\/[a-z][a-z0-9_]*)*\z/
+    TAG = /<%(=|#)?(.*?)%>/m
+    RENDER = /\Arender\s*(?:\(\s*)?["']([^"']+)["']/m
+
+    def compile(sources)
+      names = sources.keys.sort
+      paths = {}
+      method_names = {}
+      names.each do |name|
+        raise View::Error, "invalid template name #{name}" unless name.match?(NAME)
+        paths[name] = sources[name].fetch(:path)
+        method = method_name(name)
+        if method_names.key?(method)
+          raise View::Error, "#{paths[name]}:1: duplicate generated method for #{name} and #{method_names[method]}"
+        end
+        method_names[method] = name
+      end
+      methods = {}
+      dependencies = {}
+      required = names.to_h { |name| [name, declared_locals(sources[name].fetch(:source), paths[name])] }
+      names.each do |name|
+        methods[name], dependencies[name] = compile_one(name, sources[name].fetch(:source), paths[name], paths, required)
+      end
+      detect_cycles!(dependencies, paths)
+      out = ["# frozen_string_literal: true", "", "# Generated by bin/hamster manifest. Edit .html.erb files instead.", "module Hamster", "  module CompiledViews", "    module_function"]
+      names.each { |name| out.concat(methods.fetch(name)) }
+      out.concat(["    def render(name, context, locals)", "      Hamster::View.instrument_compiled(name) { dispatch(name, context, locals) }", "    end", "    def dispatch(name, context, locals)"])
+      if names.empty?
+        out << "      raise Hamster::View::Error, \"missing template #{'#{name}'}\""
+      else
+        out << "      case name"
+        names.each { |name| out << "      when #{name.dump} then #{method_name(name)}(context, locals)" }
+        out.concat(["      else raise Hamster::View::Error, \"missing template #{'#{name}'}\"", "      end"])
+      end
+      out.concat(["    end", "  end", "end", "", "Hamster::View.use_compiled!"])
+      result = out.join("\n")
+      raise View::Error, "generated views contain invalid Ruby" unless Ripper.sexp(result)
+      result
+    end
+
+    def compile_one(name, source, path, paths, required)
+      locals = declared_locals(source, path)
+      body = []
+      deps = []
+      blocks = []
+      cursor = 0
+      source.to_enum(:scan, TAG).each do
+        match = Regexp.last_match
+        literal = source[cursor...match.begin(0)]
+        body << "      output << #{literal.dump}" unless literal.empty?
+        line = source[0...match.begin(0)].count("\n") + 1
+        tag = match[1]
+        code = match[2].strip
+        if tag == "#"
+          # Comments are removed before the native build.
+        elsif tag == "="
+          context = View.position(source[0...match.begin(0)].gsub(TAG, ""))
+          validate_position!(context, path, line)
+          if (partial = partial_name(code, path, line))
+            raise View::Error, "#{path}:#{line}: missing template #{partial}" unless paths.key?(partial)
+            deps << [partial, line]
+            expression = rewrite_render(code, partial, path, line, required.fetch(partial))
+          elsif code.match?(/(?:\A|[^.])\brender\b/)
+            raise View::Error, "#{path}:#{line}: render requires a literal template name"
+          elsif name.start_with?("layouts/") && (slot = yield_name(code, path, line))
+            expression = "context.slot(#{slot.dump})"
+          elsif code.match?(/\byield\b/)
+            raise View::Error, "#{path}:#{line}: yield is only supported in layouts"
+          elsif code.match?(/\Acontent_for\b/)
+            expression = rewrite_content_for(code, path, line)
+          else
+            expression = code
+          end
+          check_ruby!(expression, path, line)
+          body << "      Hamster::View.append_value(output, (#{expression}), #{path.dump}, #{line}, #{context.inspect})"
+        else
+          raise View::Error, "#{path}:#{line}: unsupported ERB code" if code.match?(/\brender\b|\byield\b/)
+          if (slot = code.match(/\Acontent_for\s*(?:\(\s*)?:(\w+)\s*(?:\)\s*)?do\s*\z/))
+            index = blocks.length
+            blocks << [:content_for, slot[1], index, line]
+            body << "      previous_output_#{index} = output"
+            body << "      output = []"
+          elsif code == "end"
+            block = blocks.pop
+            raise View::Error, "#{path}:#{line}: unexpected end" unless block
+            if block.is_a?(Array) && block[0] == :content_for
+              body << "      context.content_for(#{block[1].dump}, Hamster::HTML::Fragment.new(output.join))"
+              body << "      output = previous_output_#{block[2]}"
+            else
+              body << "      end"
+            end
+          else
+            check_ruby_fragment!(code, path, line)
+            blocks << [:ruby, line] if code.match?(/\A(?:if|unless|for)\b/) || code.match?(/\bdo\s*(?:\|[^|]*\|)?\s*\z/)
+            body << "      #{code}"
+          end
+        end
+        cursor = match.end(0)
+      end
+      tail = source[cursor..-1]
+      if tail.include?("<%")
+        line = source[0...cursor].count("\n") + tail[0...tail.index("<%")].count("\n") + 1
+        raise View::Error, "#{path}:#{line}: unterminated ERB tag"
+      end
+      body << "      output << #{tail.dump}" unless tail.empty?
+      raise View::Error, "#{path}:#{blocks.last[-1]}: unclosed ERB block" unless blocks.empty?
+      source_without_comments = source.gsub(/<%#.*?%>/m, "")
+      if (undeclared = inferred_locals(source_without_comments) - locals).any?
+        raise View::Error, "#{path}:1: undeclared locals: #{undeclared.join(', ')}"
+      end
+      lines = ["    def #{method_name(name)}(context, locals)", "      output = []"]
+      locals.each { |local| lines << "      #{local} = context.fetch(locals, #{path.dump}, #{local.dump}, #{first_use_line(source, local)})" }
+      lines.concat(body)
+      lines.concat(["      Hamster::HTML::Fragment.new(output.join)", "    end"])
+      ruby = lines.join("\n")
+      parsed = Ripper.sexp("module X\n#{ruby}\nend")
+      unless parsed
+        raise View::Error, "#{path}: invalid ERB Ruby syntax"
+      end
+      if (unknown = unresolved_identifier(parsed))
+        raise View::Error, "#{path}:1: undeclared local #{unknown}"
+      end
+      [lines, deps]
+    end
+
+    def declared_locals(source, path = "template")
+      declaration = source.match(/\A\s*<%#\s*locals:\s*([^%]*?)\s*%>/m)
+      return inferred_locals(source) unless declaration
+      names = declaration[1].split(",").map(&:strip)
+      raise View::Error, "#{path}:1: invalid locals declaration" unless names.all? { |n| n.match?(/\A[a-z_][a-z0-9_]*\z/) } && names.uniq == names
+      names
+    end
+
+    def inferred_locals(source)
+      source.scan(/<%=\s*([a-z_][a-z0-9_]*)\s*%>/).flatten.uniq.sort - %w[yield]
+    end
+
+    def first_use_line(source, local)
+      source.to_enum(:scan, TAG).each do
+        match = Regexp.last_match
+        next if match[1] == "#"
+        return source[0...match.begin(0)].count("\n") + 1 if match[2].match?(/\b#{Regexp.escape(local)}\b/)
+      end
+      1
+    end
+
+    def method_name(name)
+      "view_#{name.tr('/', '_')}"
+    end
+
+    def partial_name(code, path, line)
+      return nil unless code.match?(/\Arender\b/)
+      match = code.match(RENDER)
+      raise View::Error, "#{path}:#{line}: render requires a literal template name" unless match
+      match[1]
+    end
+
+    def rewrite_render(code, name, path, line, required)
+      rest = code.sub(RENDER, "")
+      rest = rest.sub(/\A\s*,\s*locals:\s*/, "")
+      rest = rest.sub(/\A\s*locals:\s*/, "")
+      rest = rest.sub(/\)\s*\z/, "").strip
+      locals = rest.empty? ? "{}" : rest
+      unless locals.start_with?("{") && locals.end_with?("}") && Ripper.sexp(locals)
+        raise View::Error, "#{path}:#{line}: render requires locals: { ... }"
+      end
+      keys = locals.scan(/\b([a-z_][a-z0-9_]*):/).flatten
+      missing = required - keys
+      raise View::Error, "#{path}:#{line}: #{name} missing locals: #{missing.join(', ')}" unless missing.empty?
+      "Hamster::CompiledViews.render(#{name.dump}, context, #{locals})"
+    end
+
+    def rewrite_content_for(code, path, line)
+      match = code.match(/\Acontent_for\s*(?:\(\s*)?:(\w+)\s*,\s*(.+?)\s*\)?\z/m)
+      raise View::Error, "#{path}:#{line}: content_for requires a literal slot and value" unless match
+      "context.content_for(#{match[1].dump}, #{match[2]})"
+    end
+
+    def yield_name(code, path, line)
+      return nil unless code.match?(/\Ayield\b/)
+      return "body" if code == "yield"
+      match = code.match(/\Ayield\s*(?:\(\s*)?:(\w+)\s*\)?\z/)
+      raise View::Error, "#{path}:#{line}: yield requires a literal slot name" unless match
+      match[1]
+    end
+
+    def validate_position!(context, path, line)
+      raise View::Error, "#{path}:#{line}: dynamic script or style content" if context == :script
+      raise View::Error, "#{path}:#{line}: expression must be in text or a quoted attribute" if context == :tag
+      if context.is_a?(String) && (context.start_with?("on") || %w[style srcdoc].include?(context))
+        raise View::Error, "#{path}:#{line}: dynamic event or style attribute"
+      end
+    end
+
+    def check_ruby!(code, path, line)
+      raise View::Error, "#{path}:#{line}: invalid Ruby expression" unless Ripper.sexp(code)
+    end
+
+    def check_ruby_fragment!(code, path, line)
+      return if code.match?(/\A(?:if|unless|elsif|else)\b/) || code.match?(/\A[a-z_][\w.]*\.each\s+do(?:\s*\|[^|]+\|)?\s*\z/)
+      raise View::Error, "#{path}:#{line}: unsupported ERB code"
+    end
+
+    def detect_cycles!(deps, paths)
+      visited = {}
+      visit = lambda do |name, stack|
+        return if visited[name]
+        deps.fetch(name).each do |child, line|
+          if stack.include?(child) || child == name
+            raise View::Error, "#{paths[name]}:#{line}: partial dependency cycle: #{(stack + [name, child]).join(' -> ')}"
+          end
+          visit.call(child, stack + [name])
+        end
+        visited[name] = true
+      end
+      deps.keys.each { |name| visit.call(name, []) }
+    end
+
+    def unresolved_identifier(node)
+      return nil unless node.is_a?(Array)
+      if node[0] == :vcall && node[1].is_a?(Array) && node[1][0] == :@ident
+        return node[1][1]
+      end
+      node.each do |child|
+        result = unresolved_identifier(child)
+        return result if result
+      end
+      nil
+    end
+  end
+end