semantic_cli 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 627cd9695ac05760271592c1a5a335bb52000c287bda4bbe320c9ef0ec9dbd84
+  data.tar.gz: 1e340edab57285e72a71b86073696df2acf77bbe395920cb7b7c4610c22f4ad0
+SHA512:
+  metadata.gz: 29baab18463488236d093243e521ced8732cec1b4d8fd0552e3fdda5eb89622e445b75671bc6fa250e4f33c4ca78fc3bc7ffc43ad488b409ee48d14202aa6641
+  data.tar.gz: 637f8f6e0f4bd6fe0d27c77c598c6d65cafbbf1b5b5e5032ccbda2e90be5dc0c30e1dbe4925980d41d344dd90f5bc9d543f7eccd07d59f4d486bc15a65951a67

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-16
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 raykin
+
+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,135 @@
+# SemanticCli
+
+A Ruby DSL for building flag-free CLIs. You define named functions that return shell commands — the framework takes care of parsing, argument resolution, and piping.
+
+```
+watch log nginx grep error
+→ Running: tail -f /var/log/nginx/access.log | grep error
+```
+
+## Installation
+
+```bash
+gem install semantic_cli
+```
+
+## Usage
+
+Create a script (e.g., `restart`):
+
+```ruby
+#!/usr/bin/env ruby
+require 'semantic_cli'
+
+fn('nginx') do
+  if macos?
+    "brew services restart nginx"
+  else
+    "sudo systemctl restart nginx"
+  end
+end
+
+fn('psql') do
+  if macos?
+    "brew services restart postgresql@15"
+  else
+    "sudo systemctl restart postgresql"
+  end
+end
+
+fn('') do
+  <<~HELP
+    Examples:
+      restart nginx → restart nginx service
+      restart psql  → restart postgresql
+  HELP
+end
+
+run
+```
+
+Then just run: `restart nginx`
+
+### DSL
+
+- `fn(name) { |arg| "shell command" }` — define a function that returns a shell command string
+- `cmd(name, command)` — shorthand when no logic is needed
+- `fn('') { "help text" }` — help text, displayed when no arguments are given
+- `macos?` / `linux?` — platform detection helpers
+
+### Argument Styles
+
+```ruby
+fn('log') { |svc| "journalctl -u #{svc} -f" }              # required arg:  watch log nginx
+fn('http') { |site='google'| "curl #{site}.com" }           # optional arg:  watch http / watch http github
+fn('dns') { |c1, *rest| "dig #{c1} #{rest.join(' ')}" }     # rest args:     dns set 8.8.8.8 8.8.4.4
+fn('status') { "kubectl get pods" }                          # no arg:        ops status
+cmd 'deploy', 'kubectl rollout restart deployment'           # static string: ops deploy
+```
+
+### Piping
+
+When multiple functions are chained, their outputs are joined with `|`:
+
+```
+watch log nginx grep error
+→ Running: journalctl -u nginx -f | grep error
+```
+
+### Key-Value Syntax
+
+Arguments can also be passed with `key:value`:
+
+```
+watch max:5
+→ Running: head -n5
+```
+
+## Use Cases
+
+### Personal Command Palette
+
+Wrap the commands you use every day into short, memorable names:
+
+```ruby
+cmd '77', 'ssh root@192.168.77.1'
+cmd '7744', 'ssh root@lzm -p 7744'
+```
+
+### DevOps Runbook
+
+Turn team runbooks into executable scripts instead of wiki pages people copy-paste from:
+
+```ruby
+fn('deploy') { |env| "kubectl rollout restart deployment/app -n #{env}" }
+fn('logs') { |svc| "kubectl logs -f deployment/#{svc} --tail=100" }
+fn('status') { "kubectl get pods -A" }
+```
+
+`ops deploy staging`, `ops logs api`, `ops status` — the team doesn't need to remember the underlying commands.
+
+### Cross-Platform Scripts
+
+Write scripts that work on both macOS and Linux:
+
+```ruby
+fn('proxy') do |c1='display'|
+  if macos?
+    "networksetup -setsocksfirewallproxystate wifi #{c1}"
+  else
+    "gsettings set org.gnome.system.proxy mode manual"
+  end
+end
+```
+
+## Development
+
+```bash
+bin/setup        # install dependencies
+rake test        # run tests
+bin/console      # interactive prompt
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/semantic_cli/dsl.rb

@@ -0,0 +1,65 @@
+module SemanticCli
+  class DSL
+    class Function
+      def initialize(block)
+        @block = block
+        @params = block.parameters
+      end
+
+      def expects_arg?
+        @params.any? { |kind, _| kind == :req || kind == :opt }
+      end
+
+      def expects_rest?
+        @params.any? { |kind, _| kind == :rest }
+      end
+
+      def call(*args)
+        args = args.compact
+        if expects_rest?
+          @block.call(*args)
+        elsif @params.any? { |kind, _| kind == :req }
+          @block.call(args.first)
+        elsif @params.any? { |kind, _| kind == :opt }
+          args.empty? ? @block.call : @block.call(args.first)
+        else
+          @block.call
+        end
+      end
+    end
+
+    def initialize
+      @functions = {}
+    end
+
+    def define(name, &block)
+      name = name.to_s.strip
+      if name != "" && name.split.size != 1
+        raise ArgumentError, "Function name must be single word or empty string"
+      end
+      @functions[name] = Function.new(block)
+    end
+
+    def exists?(name)
+      @functions.key?(name)
+    end
+
+    def expects_arg?(name)
+      fn = @functions[name]
+      return false unless fn
+      fn.expects_arg?
+    end
+
+    def expects_rest?(name)
+      fn = @functions[name]
+      return false unless fn
+      fn.expects_rest?
+    end
+
+    def call(name, *args)
+      fn = @functions[name]
+      return unless fn
+      fn.call(*args)
+    end
+  end
+end

data/lib/semantic_cli/fragment.rb

@@ -0,0 +1,3 @@
+module SemanticCli
+  Fragment = Data.define(:name, :arg, :shell)
+end

data/lib/semantic_cli/option.rb

@@ -0,0 +1,21 @@
+module SemanticCli
+  class Option
+    attr_reader :raw, :kind, :name, :arg
+
+    def initialize(raw)
+      @raw = raw
+      classify
+    end
+
+    def classify
+      if raw.include?(":")
+        key, val = raw.split(":", 2)
+        @kind, @name, @arg = :kv_function, key, val
+      elsif raw =~ /^\d+$/
+        @kind, @name, @arg = :parameter, nil, raw
+      else
+        @kind, @name, @arg = :word, raw, nil
+      end
+    end
+  end
+end

data/lib/semantic_cli/parser.rb

@@ -0,0 +1,94 @@
+module SemanticCli
+  class Parser
+    ParseResult = Data.define(:fragment, :consumed)
+
+    def initialize(argv, dsl)
+      @tokens = argv.dup
+      @dsl = dsl
+      @fragments = []
+    end
+
+    def build_fragments
+      i = 0
+      last_fn = nil
+      last_fn_consumed_arg = false
+
+      while i < @tokens.size
+        result = parse_token(i, last_fn, last_fn_consumed_arg)
+
+        if result
+          @fragments << result.fragment
+          last_fn = result.fragment.name
+          last_fn_consumed_arg = result.consumed > 1
+          i += result.consumed
+        else
+          i += 1
+        end
+      end
+
+      @fragments
+    end
+
+    private
+
+    def parse_token(index, last_fn, last_fn_consumed_arg)
+      token = @tokens[index]
+      next_token = @tokens[index + 1]
+      opt = Option.new(token)
+
+      case opt.kind
+      when :kv_function
+        return result(opt.name, opt.arg, 1) if @dsl.exists?(opt.name)
+        warn "Unknown function: #{opt.name}"
+        nil
+
+      when :parameter
+        if last_fn && @dsl.expects_arg?(last_fn) && !last_fn_consumed_arg
+          result(last_fn, opt.arg, 1)
+        else
+          warn "Orphan parameter: #{opt.arg}"
+          nil
+        end
+
+      when :word
+        if @dsl.exists?(opt.name)
+          if @dsl.expects_arg?(opt.name) && next_token && !@dsl.exists?(next_token) && !next_token.include?(":")
+            if @dsl.expects_rest?(opt.name)
+              rest_args = collect_rest(index + 1)
+              result_rest(opt.name, rest_args, 1 + rest_args.size)
+            else
+              result(opt.name, next_token, 2)
+            end
+          else
+            result(opt.name, nil, 1)
+          end
+        elsif last_fn && @dsl.expects_arg?(last_fn) && !last_fn_consumed_arg
+          result(last_fn, opt.name, 1)
+        else
+          warn "Unknown token: #{opt.name}"
+          nil
+        end
+      end
+    end
+
+    def collect_rest(start)
+      args = []
+      i = start
+      while i < @tokens.size
+        t = @tokens[i]
+        break if @dsl.exists?(t) || t.include?(":")
+        args << t
+        i += 1
+      end
+      args
+    end
+
+    def result(name, arg, consumed)
+      ParseResult.new(Fragment.new(name, arg, @dsl.call(name, arg)), consumed)
+    end
+
+    def result_rest(name, args, consumed)
+      ParseResult.new(Fragment.new(name, args.first, @dsl.call(name, *args)), consumed)
+    end
+  end
+end

data/lib/semantic_cli/runner.rb

@@ -0,0 +1,31 @@
+module SemanticCli
+  class Runner
+    def initialize(dsl)
+      @dsl = dsl
+    end
+
+    def execute(argv)
+      if argv.empty?
+        if @dsl.exists?('')
+          help_text = @dsl.call('')
+          puts help_text unless help_text.to_s.strip.empty?
+        else
+          warn "No command given."
+        end
+        return
+      end
+
+      parser = Parser.new(argv, @dsl)
+      fragments = parser.build_fragments
+
+      command = fragments.map(&:shell).compact.join(" | ")
+      if command.empty?
+        warn "No command built."
+        return
+      end
+
+      puts "→ Running: #{command}"
+      system command
+    end
+  end
+end

data/lib/semantic_cli/version.rb

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

data/lib/semantic_cli.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "semantic_cli/version"
+require_relative "semantic_cli/dsl"
+require_relative "semantic_cli/option"
+require_relative "semantic_cli/fragment"
+require_relative "semantic_cli/parser"
+require_relative "semantic_cli/runner"
+
+module SemanticCli
+  class Error < StandardError; end
+
+  class << self
+    def dsl
+      @dsl ||= DSL.new
+    end
+
+    def runner
+      @runner ||= Runner.new(dsl)
+    end
+
+    def reset!
+      @dsl = nil
+      @runner = nil
+    end
+  end
+
+  module DSLHelpers
+    def fn(name, &block)
+      SemanticCli.dsl.define(name, &block)
+    end
+
+    def cmd(name, command)
+      SemanticCli.dsl.define(name) { command }
+    end
+
+    def run
+      SemanticCli.runner.execute(ARGV)
+    end
+
+    def macos?
+      RUBY_PLATFORM.include?("darwin")
+    end
+
+    def linux?
+      RUBY_PLATFORM.include?("linux")
+    end
+  end
+end
+
+# Auto-include DSL into top-level context
+include SemanticCli::DSLHelpers

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: semantic_cli
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- raykin
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Define named functions that return shell commands, with automatic argument
+  resolution and piping
+email:
+- raykincoldxiao@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/semantic_cli.rb
+- lib/semantic_cli/dsl.rb
+- lib/semantic_cli/fragment.rb
+- lib/semantic_cli/option.rb
+- lib/semantic_cli/parser.rb
+- lib/semantic_cli/runner.rb
+- lib/semantic_cli/version.rb
+homepage: https://github.com/raykin/semantic-cli
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/raykin/semantic-cli
+  source_code_uri: https://github.com/raykin/semantic-cli
+  changelog_uri: https://github.com/raykin/semantic-cli/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: A Ruby DSL for building flag-free CLIs
+test_files: []