story-teller 1.1.3

data/lib/story_teller/snapshots.rb

@@ -0,0 +1,412 @@
+# lib/story_teller/snapshots.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'json'
+require 'zlib'
+require 'time'
+require 'date'
+require 'base64'
+
+begin
+  # Helps Postgres JSON/JSONB accept Hash/Array inserts in many setups.
+  require 'sequel/extensions/pg_json'
+rescue LoadError
+  nil
+end
+
+# The StoryTeller module
+module StoryTeller
+  # The Snapshots module
+  module Snapshots
+    GzipMagicBytes = [0x1F, 0x8B].freeze
+
+    # Adjust exclusions as needed
+    TableExclusions = %i[
+      schema_migrations
+      ar_internal_metadata
+      sequel_migrations
+    ].freeze
+
+    # Snapshot JSON schema:
+    # {
+    #   version: 1,
+    #   created_at: "ISO8601",
+    #   tables: [
+    #     {
+    #       name: "object",
+    #       primary_key: "id",
+    #       self_foreign_key: "parent_id", # optional
+    #       rows: [ { col: val, ... }, ... ]
+    #     },
+    #     ...
+    #   ]
+    # }
+
+    module_function
+
+    def gzipped?(filename)
+      File.binread(filename, 2).bytes == GzipMagicBytes
+    end
+
+    def read_snapshot_file(filename)
+      data = if gzipped?(filename)
+        Zlib::GzipReader.open(filename, &:read)
+      else
+        File.read(filename)
+      end
+
+      JSON.parse(data, symbolize_names: true)
+    end
+
+    def world_tables(db)
+      db.tables.reject { |t| TableExclusions.include?(t) }
+    end
+
+    def ordered_world_tables(db, only_tables: nil)
+      tables = only_tables ? only_tables.map(&:to_sym) : world_tables(db)
+      deps = table_dependencies(db, tables)
+      topo_sort_tables(tables, deps)
+    end
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/CyclomaticComplexity
+    # rubocop: disable Metrics/MethodLength
+    # rubocop: disable Metrics/PerceivedComplexity
+    def table_dependencies(db, tables)
+      table_set = tables.to_h { |t| [t, true] }
+      deps = {}
+      tables.each { |t| deps[t] = {} }
+
+      tables.each do |table|
+        fks = safe_foreign_key_list(db, table)
+        fks.each do |fk|
+          parent = fk[:table]&.to_sym
+          next unless parent
+          next unless table_set[parent]
+          next if parent == table # self-FK handled at row ordering level
+
+          deps[table][parent] = true
+        end
+      end
+
+      deps
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/CyclomaticComplexity
+    # rubocop: enable Metrics/MethodLength
+    # rubocop: enable Metrics/PerceivedComplexity
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/CyclomaticComplexity
+    # rubocop: disable Metrics/MethodLength
+    # rubocop: disable Metrics/PerceivedComplexity
+    def topo_sort_tables(tables, deps)
+      remaining = tables.to_h { |t| [t, true] }
+      incoming = deps.transform_values(&:dup)
+
+      ordered = []
+      loop do
+        roots = remaining.keys.select { |t| incoming[t].empty? }.sort_by(&:to_s)
+        break if roots.empty?
+
+        roots.each do |root|
+          ordered << root
+          remaining.delete(root)
+          incoming.delete(root)
+          incoming.each_value { |parents| parents.delete(root) }
+        end
+      end
+
+      return ordered if remaining.empty?
+
+      cycle = remaining.keys.sort_by(&:to_s)
+      raise "Foreign key table dependency cycle detected among: #{cycle.join(', ')}"
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/CyclomaticComplexity
+    # rubocop: enable Metrics/MethodLength
+    # rubocop: enable Metrics/PerceivedComplexity
+
+    def safe_foreign_key_list(db, table)
+      db.foreign_key_list(table)
+    rescue Sequel::NotImplemented
+      []
+    end
+
+    def primary_key_for_table(db, table)
+      pk = db.primary_key(table)
+      return pk if pk.is_a?(Symbol)
+
+      # Fallback: detect first PK column from schema
+      schema = db.schema(table)
+      pk_cols = schema.map { |name, info| info[:primary_key] ? name : nil }.compact
+      pk_cols.length == 1 ? pk_cols.first : nil
+    end
+
+    def self_fk_column(db, table)
+      fks = safe_foreign_key_list(db, table)
+      self_fk = fks.find { |fk| fk[:table].to_sym == table.to_sym }
+      return nil unless self_fk
+
+      cols = Array(self_fk[:columns])
+      cols.length == 1 ? cols.first : nil
+    end
+
+    # rubocop: disable Metrics/MethodLength
+    def normalize_value(value)
+      case value
+      when Time
+        value.utc.iso8601
+      when DateTime
+        value.to_time.utc.iso8601
+      when Date
+        value.iso8601
+      when BigDecimal
+        value.to_s("F")
+      when Sequel::SQL::Blob
+        { __blob__: Base64.strict_encode64(value) }
+      else
+        value
+      end
+    end
+    # rubocop: enable Metrics/MethodLength
+
+    def normalize_row(row)
+      row.transform_values { |v| normalize_value(v) }
+    end
+
+    # rubocop: disable Metrics/CyclomaticComplexity
+    # rubocop: disable Metrics/MethodLength
+    def parse_value(value, type)
+      return nil if value.nil?
+
+      if value.is_a?(Hash) && value.key?(:__blob__)
+        return Sequel::SQL::Blob.new(Base64.decode64(value[:__blob__]))
+      end
+
+      case type
+      when :datetime, :timestamp
+        value.is_a?(String) ? Time.iso8601(value) : value
+      when :date
+        value.is_a?(String) ? Date.iso8601(value) : value
+      else
+        value
+      end
+    rescue ArgumentError
+      # If parsing fails, keep original value to avoid hard failure.
+      value
+    end
+    # rubocop: enable Metrics/CyclomaticComplexity
+    # rubocop: enable Metrics/MethodLength
+
+    def denormalize_row(db, table, row)
+      schema = db.schema(table)
+      types = schema.to_h.transform_values { |info| info[:type] }
+
+      out = {}
+      row.each do |k, v|
+        type = types[k.to_sym]
+        out[k.to_sym] = parse_value(v, type)
+      end
+      out
+    end
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/CyclomaticComplexity
+    # rubocop: disable Metrics/MethodLength
+    # rubocop: disable Metrics/PerceivedComplexity
+    def order_rows_by_self_fk(rows, pk_col, parent_col)
+      return rows if rows.empty?
+      return rows unless pk_col && parent_col
+
+      by_id = {}
+      rows.each { |r| by_id[r[pk_col]] = r }
+
+      in_degree = Hash.new(0)
+      children = Hash.new { |h, k| h[k] = [] }
+
+      rows.each do |r|
+        id = r[pk_col]
+        parent_id = r[parent_col]
+        next if parent_id.nil?
+        next unless by_id.key?(parent_id)
+
+        in_degree[id] += 1
+        children[parent_id] << id
+      end
+
+      queue = rows.select { |r| in_degree[r[pk_col]].zero? }.map { |r| r[pk_col] }.sort
+
+      ordered = []
+      until queue.empty?
+        id = queue.shift
+        row = by_id[id]
+        ordered << row if row
+
+        children[id].sort.each do |child_id|
+          in_degree[child_id] -= 1
+          queue << child_id if in_degree[child_id].zero?
+        end
+      end
+
+      # If cycle or missing nodes, append remaining deterministically.
+      remaining_ids = by_id.keys - ordered.map { |r| r[pk_col] }
+      remaining_ids.sort.each { |id| ordered << by_id[id] }
+
+      ordered
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/CyclomaticComplexity
+    # rubocop: enable Metrics/MethodLength
+    # rubocop: enable Metrics/PerceivedComplexity
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/CyclomaticComplexity
+    # rubocop: disable Metrics/MethodLength
+    def export_to_file(filename)
+      db = Sequel::Model.db
+      tables = ordered_world_tables(db)
+
+      tables_payload = tables.map do |table|
+        pk = primary_key_for_table(db, table)
+        s_fk = self_fk_column(db, table)
+
+        rows = db[table].all
+        # Stable base order, then parent-first for self-FK if applicable.
+        rows = rows.sort_by { |r| r[pk] || 0 } if pk
+        rows = order_rows_by_self_fk(rows, pk, s_fk)
+        rows = rows.map { |r| normalize_row(r) }
+
+        {
+          name: table.to_s,
+          primary_key: pk&.to_s,
+          self_foreign_key: s_fk&.to_s,
+          rows: rows
+        }
+      end
+
+      data = {
+        version: 1,
+        created_at: Time.now.utc.iso8601,
+        tables: tables_payload
+      }
+
+      File.open(filename, 'wb') do |file|
+        Zlib::GzipWriter.wrap(file) { |gz| gz.write(JSON.generate(data)) }
+      end
+
+      filename
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/CyclomaticComplexity
+    # rubocop: enable Metrics/MethodLength
+
+    # rubocop: disable Metrics/MethodLength
+    def truncate_tables(db, tables)
+      if db.database_type == :postgres
+        existing = tables.select { |t| db.table_exists?(t) }
+        return if existing.empty?
+
+        table_list = existing.map { |t| db.literal(t) }.join(", ")
+        db.run("TRUNCATE TABLE #{table_list} RESTART IDENTITY CASCADE")
+        return
+      end
+
+      # For other DBs, truncate/delete children first (reverse dependency order).
+      tables.reverse_each do |table|
+        next unless db.table_exists?(table)
+        db[table].truncate
+      end
+    end
+    # rubocop: enable Metrics/MethodLength
+
+    # rubocop: disable Metrics/AbcSize
+    # rubocop: disable Metrics/CyclomaticComplexity
+    # rubocop: disable Metrics/MethodLength
+    # rubocop: disable Metrics/PerceivedComplexity
+    def import_from_file(filename)
+      db = Sequel::Model.db
+      data = read_snapshot_file(filename)
+
+      unless data[:version] == 1
+        raise "Unsupported snapshot version: #{data[:version].inspect}"
+      end
+
+      snapshot_tables = Array(data[:tables])
+      table_rows_by_name = snapshot_tables.to_h do |t|
+        [t[:name].to_s, Array(t[:rows])]
+      end
+
+      table_syms = snapshot_tables.map { |t| t[:name].to_sym }
+      ordered = ordered_world_tables(db, only_tables: table_syms)
+
+      db.transaction do
+        truncate_tables(db, ordered)
+
+        ordered.each do |table|
+          rows = table_rows_by_name[table.to_s] || []
+          next if rows.empty?
+          next unless db.table_exists?(table)
+
+          denorm = rows.map { |r| denormalize_row(db, table, r) }
+          db[table].multi_insert(denorm) unless denorm.empty?
+        end
+
+        reseed_sequences(db, ordered)
+      end
+
+      filename
+    end
+    # rubocop: enable Metrics/AbcSize
+    # rubocop: enable Metrics/CyclomaticComplexity
+    # rubocop: enable Metrics/MethodLength
+    # rubocop: enable Metrics/PerceivedComplexity
+
+    SelectSerialSequence = 'SELECT pg_get_serial_sequence(?, ?) AS seq'.freeze
+    SelectSetvalTemplate = 'SELECT setval(%<sequence>s, %<max_id>s, true)'.freeze
+
+    # rubocop: disable Metrics/CyclomaticComplexity
+    # rubocop: disable Metrics/MethodLength
+    def reseed_sequences(db, tables)
+      return unless db.database_type == :postgres
+
+      tables.each do |table|
+        next unless db.table_exists?(table)
+
+        pk = primary_key_for_table(db, table)
+        next unless pk
+
+        max_id = db[table].max(pk)
+        next unless max_id
+
+        seq_row = db.fetch(SelectSerialSequence, table.to_s, pk.to_s).first
+        seq_name = seq_row && seq_row[:seq]
+        next unless seq_name
+
+        db.run(format(SelectSetvalTemplate, sequence: db.literal(seq_name), max_id: max_id))
+      end
+    end
+    # rubocop: enable Metrics/CyclomaticComplexity
+    # rubocop: enable Metrics/MethodLength
+  end
+  # module Snapshots
+end
+# module StoryTeller

data/lib/story_teller/terminal.rb

@@ -0,0 +1,58 @@
+# lib/story_teller/terminal.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'io/console'
+
+# module StoryTeller
+module StoryTeller
+  # module Terminal
+  module Terminal
+    module_function
+
+    MINIMUM_WORD_WRAP = 1
+
+    def word_wrap(output = $stdout)
+      terminal_columns = columns(output)
+      return default_word_wrap if terminal_columns.nil? || terminal_columns.to_i <= 0
+
+      [terminal_columns.to_i - 1, MINIMUM_WORD_WRAP].max.tap do |n|
+        log.debug "word_wrap: #{n}"
+      end
+    end
+
+    def default_word_wrap
+      StoryTeller::Config.defaults[:default_word_wrap]
+    end
+
+    def columns(output = $stdout)
+      return output.winsize[1] if output.respond_to?(:winsize) && output.tty?
+
+      console = ::IO.console
+      return console.winsize[1] if console.respond_to?(:winsize)
+
+      nil
+    rescue IOError, SystemCallError
+      nil
+    end
+  end
+  # module Terminal
+end
+# module StoryTeller

data/lib/story_teller/version.rb

@@ -0,0 +1,24 @@
+# lib/story_teller/version.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2026 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+module StoryTellerCli
+  VERSION = '1.1.3'.freeze
+end

data/lib/story_teller_cli.rb

@@ -0,0 +1,34 @@
+# lib/story_teller_cli.rb
+# encoding: utf-8
+# frozen_string_literal: false
+
+# Copyright Nels Nelson 2008-2025 but freely usable (see license)
+#
+# This file is part of the StoryTeller.
+#
+# The StoryTeller is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The StoryTeller is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the StoryTeller.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'story_teller'
+
+require_relative 'story_teller/application'
+require_relative 'story_teller/config'
+require_relative 'story_teller/options'
+require_relative 'story_teller/privileges'
+require_relative 'story_teller/runtime'
+require_relative 'story_teller/game'
+require_relative 'story_teller/persistence'
+require_relative 'story_teller/inform/models'
+require_relative 'story_teller/snapshots'
+require_relative 'story_teller/terminal'
+require_relative 'story_teller/cli'

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: story-teller
+version: !ruby/object:Gem::Version
+  version: 1.1.3
+platform: ruby
+authors:
+- Nels Nelson
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: curses
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+- !ruby/object:Gem::Dependency
+  name: inform-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.1
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.2
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.58.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.58.0
+description: The Story Teller is a command-line interface software runtime program
+  for playing interactive-fiction games which use the Inform 6 Ruby Port.
+email: nels@nelsnelson.org
+executables:
+- inform.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- config/database.yml
+- exe/inform.rb
+- game/config.yml
+- game/example.inf
+- game/example.rb
+- game/forms/example_form.rb
+- game/grammar/admin.inf.rb
+- game/grammar/builder.inf.rb
+- game/grammar/game_grammar.inf.rb
+- game/grammar/meta.inf.rb
+- game/languages/english.rb
+- game/models/example_model.rb
+- game/modules/example_module.rb
+- game/modules/parser_extensions.rb
+- game/rules/example_state.rb
+- game/scripts/example_script.rb
+- game/topics/example_topic.rb
+- game/verbs/game_verbs.rb
+- game/verbs/metaverbs.rb
+- lib/story_teller/application.rb
+- lib/story_teller/cli.rb
+- lib/story_teller/color.rb
+- lib/story_teller/config.rb
+- lib/story_teller/curses_adapter.rb
+- lib/story_teller/database.rb
+- lib/story_teller/game.rb
+- lib/story_teller/game/loader.rb
+- lib/story_teller/inform/models.rb
+- lib/story_teller/inform/relational/link.rb
+- lib/story_teller/inform/relational/module.rb
+- lib/story_teller/inform/relational/object.rb
+- lib/story_teller/inform/relational/tag.rb
+- lib/story_teller/options.rb
+- lib/story_teller/persistence.rb
+- lib/story_teller/player_character.rb
+- lib/story_teller/privileges.rb
+- lib/story_teller/runtime.rb
+- lib/story_teller/snapshots.rb
+- lib/story_teller/terminal.rb
+- lib/story_teller/version.rb
+- lib/story_teller_cli.rb
+homepage: https://rubygems.org/gems/story-teller
+licenses:
+- GPL-3.0-or-later
+metadata:
+  source_code_uri: https://gitlab.com/nelsnelson/story-teller
+  bug_tracker_uri: https://gitlab.com/nelsnelson/story-teller/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Story Teller for playing Inform 6 Ruby games
+test_files: []