yaml_smith 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7ff73d942d1f809bbac011b168ef43cd3ce7b8d193292c661e6d2d65a358498
+  data.tar.gz: 4e6fe2d3391a53d6fd9d364d0b87061342409033ba9be4e29520eb8ab75b4e20
+SHA512:
+  metadata.gz: 0da49b2b19add33c7a5137624bb6347c39c87ea6bc203c7ad416a77e026bf3c387b3ca5f0fbb10e550716f50c6729592c4ffa8b1204ef255d808e5c15782baf4
+  data.tar.gz: 241861d560bdce07bdfe246c11618f83750a00f31d338a140c820147faf9482df223ff115df8fcf0fe6b29db93f4d1544cb82efd19be7422ba304a8b59662609

data/AGENTS.md

@@ -0,0 +1,22 @@
+# Agent Guide
+
+## Commands
+
+- Install dependencies with `bundle install`.
+- Run all tests with `bundle exec rake test`.
+- Run one test file with `bundle exec ruby -Ilib:test test/test_add_key.rb` (replace the filename as needed).
+- The CI/default task is `bundle exec rake`, which runs tests followed by RuboCop.
+
+## Structure
+
+- `exe/yaml-smith` is only the executable wrapper; CLI dispatch and error handling belong in `lib/yaml_smith/cli.rb`.
+- Each command has its own class and file: `AddKey`, `SetKey`, and `DeleteKey`.
+- Shared file loading, validation, and atomic writing live in `YamlSmith::FileCommand`.
+- Commands currently operate on top-level mapping keys only; do not add nested-path behavior implicitly.
+
+## YAML Behavior
+
+- Use `Psych::Pure`, not standard `Psych`; it is required to preserve comments where possible.
+- Load existing files and values with `comments: true`.
+- Values passed on the command line are YAML and should retain their YAML types.
+- File edits are written through a same-directory temporary file and rename; preserve this atomic-write behavior.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andy Waite
+
+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,60 @@
+# YamlSmith
+
+A command-line tool for manipulating YAML files while preserving comments,
+powered by [Psych::Pure](https://github.com/kddnewton/psych-pure).
+
+## Installation
+
+Install the gem and add it to your application's Gemfile:
+
+```bash
+bundle add yaml_smith
+```
+
+If Bundler is not being used, install the gem directly:
+
+```bash
+gem install yaml_smith
+```
+
+## Usage
+
+Add a top-level key to an existing YAML file:
+
+```bash
+yaml-smith add config.yml timeout 30
+```
+
+The value is parsed as YAML, so values such as `true`, `null`, arrays, and
+objects retain their YAML types. Existing keys are not overwritten.
+
+Set or replace a top-level key:
+
+```bash
+yaml-smith set config.yml timeout 60
+```
+
+Delete a top-level key:
+
+```bash
+yaml-smith delete config.yml timeout
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `bundle exec rake test` to run the tests. You can also run `bin/console` for
+an interactive prompt.
+
+To install this gem locally, run `bundle exec rake install`. To release a new
+version, update `version.rb`, then run `bundle exec rake release`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/andyw8/yaml_smith.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/exe/yaml-smith

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'yaml_smith/cli'
+
+exit YamlSmith::CLI.call(ARGV)

data/lib/yaml_smith/add_key.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module YamlSmith
+  # Adds a top-level key to a YAML file.
+  class AddKey < FileCommand
+    def call
+      document = load_file(@path)
+      value = load(@value)
+
+      ensure_mapping(document)
+      raise Error, "key already exists: #{@key}" if document.key?(@key)
+
+      document[@key] = value
+      write(Psych::Pure.dump(document))
+    end
+  end
+end

data/lib/yaml_smith/cli.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../yaml_smith'
+
+module YamlSmith
+  # Dispatches command-line arguments to a YAML Smith command.
+  class CLI
+    COMMANDS = {
+      'add' => AddKey,
+      'set' => SetKey,
+      'delete' => DeleteKey
+    }.freeze
+    USAGE = 'Usage: yaml-smith COMMAND FILE KEY [VALUE]'
+
+    def self.call(arguments)
+      new(arguments).call
+    end
+
+    def initialize(arguments)
+      @arguments = arguments
+    end
+
+    def call
+      command = COMMANDS[@arguments.first]
+      return usage unless valid_arguments?(command)
+
+      command.call(*command_arguments)
+    rescue Error => e
+      warn e.message
+      1
+    end
+
+    private
+
+    def valid_arguments?(command)
+      return false unless command
+
+      @arguments.length == (delete_command? ? 3 : 4)
+    end
+
+    def delete_command?
+      @arguments.first == 'delete'
+    end
+
+    def command_arguments
+      @arguments.drop(1)
+    end
+
+    def usage
+      warn USAGE
+      1
+    end
+  end
+end

data/lib/yaml_smith/delete_key.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module YamlSmith
+  # Deletes a top-level key from a YAML file.
+  class DeleteKey < FileCommand
+    def call
+      document = load_file(@path)
+
+      ensure_mapping(document)
+      raise Error, "key does not exist: #{@key}" unless document.key?(@key)
+
+      document.delete(@key)
+      write(Psych::Pure.dump(document))
+    end
+  end
+end

data/lib/yaml_smith/file_command.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module YamlSmith
+  # Provides shared YAML file editing behavior for commands.
+  class FileCommand
+    def initialize(path, key, value = nil)
+      @path = path
+      @key = key
+      @value = value
+    end
+
+    def self.call(...)
+      new(...).call
+    end
+
+    private
+
+    def load_file(path)
+      load(File.read(path, encoding: 'UTF-8'))
+    rescue SystemCallError => e
+      raise Error, e.message
+    end
+
+    def load(source)
+      Psych::Pure.load(source, comments: true)
+    rescue Psych::Exception => e
+      raise Error, "invalid YAML: #{e.message}"
+    end
+
+    def ensure_mapping(document)
+      return if document.instance_of?(Psych::Pure::LoadedHash)
+
+      raise Error, 'YAML document must contain a top-level mapping'
+    end
+
+    def write(contents)
+      mode = File.stat(@path).mode & 0o7777
+
+      Tempfile.create(['.yaml-smith-', '.tmp'], File.dirname(@path)) do |file|
+        file.chmod(mode)
+        file.write(contents)
+        file.flush
+        file.fsync
+        File.rename(file.path, @path)
+      end
+    end
+  end
+end

data/lib/yaml_smith/set_key.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module YamlSmith
+  # Sets a top-level key in a YAML file, adding or replacing it.
+  class SetKey < FileCommand
+    def call
+      document = load_file(@path)
+      value = load(@value)
+
+      ensure_mapping(document)
+      document[@key] = value
+      write(Psych::Pure.dump(document))
+    end
+  end
+end

data/lib/yaml_smith/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module YamlSmith
+  VERSION = "0.1.0"
+end

data/lib/yaml_smith.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'yaml_smith/version'
+require 'psych/pure'
+require 'tempfile'
+
+module YamlSmith
+  class Error < StandardError; end
+end
+
+require_relative 'yaml_smith/file_command'
+require_relative 'yaml_smith/add_key'
+require_relative 'yaml_smith/set_key'
+require_relative 'yaml_smith/delete_key'

data/sig/yaml_smith.rbs

@@ -0,0 +1,4 @@
+module YamlSmith
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: yaml_smith
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Waite
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: psych-pure
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: YamlSmith manipulates YAML files from the command line and uses Psych::Pure
+  to preserve comments where possible.
+email:
+- andyw8@users.noreply.github.com
+executables:
+- yaml-smith
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/yaml-smith
+- lib/yaml_smith.rb
+- lib/yaml_smith/add_key.rb
+- lib/yaml_smith/cli.rb
+- lib/yaml_smith/delete_key.rb
+- lib/yaml_smith/file_command.rb
+- lib/yaml_smith/set_key.rb
+- lib/yaml_smith/version.rb
+- sig/yaml_smith.rbs
+homepage: https://github.com/andyw8/yaml_smith
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/andyw8/yaml_smith
+  source_code_uri: https://github.com/andyw8/yaml_smith
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A command-line tool for manipulating YAML files while preserving comments.
+test_files: []