squared 0.1.11 → 0.2.0

data/README.ruby.md

@@ -0,0 +1,384 @@
+# squared 0.2
+
+* [source](https://github.com/anpham6/squared)
+* [manifest](https://github.com/anpham6/squared-repo)
+* [docs](https://squared.readthedocs.io)
+
+## Version Compatibility
+
+| Date       | squared |    Min |    Max |
+| :--------: | ------: | -----: | -----: |
+| 2024-12-07 |   0.1.0 |  2.4.0 |  3.3.6 |
+| 2025-01-07 |   0.2.0 |  2.4.0 |  3.4.0 |
+
+The range chart indicates the latest Ruby tested against at the time of release.
+
+## Installation
+
+```sh
+gem install squared
+```
+
+### Optional
+
+* [Repo](https://source.android.com/docs/setup/reference/repo)
+* Python 3.6
+* Not compatible with Windows
+
+```sh
+mkdir -p ~/.bin
+PATH="${HOME}/.bin:${PATH}"
+curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
+chmod a+rx ~/.bin/repo
+```
+
+## Example - Rakefile
+
+Projects from any accessible folder can be added relative to the parent directory (e.g. *REPO_ROOT*) or absolutely. The same Rakefile can also manage other similarly cloned `Repo` repositories remotely by setting the `REPO_ROOT` environment variable to the location. Missing projects will simply be excluded from the task runner.
+
+```ruby
+require "squared"
+
+require "squared/workspace"
+require "squared/workspace/repo"                     # Optional
+require "squared/workspace/project/node"             #
+require "squared/workspace/project/python"           #
+require "squared/workspace/project/ruby"             #
+# OR
+require "squared/app"                                # All workspace related modules
+
+# NODE_ENV  = production
+
+# REPO_ROOT = /workspaces                            #
+# REPO_HOME = /workspaces/squared                    # Dir.pwd
+# rake      = /workspaces/squared/Rakefile           # main?
+# OR
+# REPO_ROOT = /workspaces                            # Dir.pwd
+# rake      = /workspaces/Rakefile                   #
+# REPO_HOME = /workspaces/squared                    # main: "squared"
+
+# pathname  = /workspaces/pathname
+# optparse  = /workspaces/optparse
+# log       = /workspaces/logger
+# emc       = /workspaces/e-mc
+# pir       = /workspaces/pi-r
+# squared   = /workspaces/squared
+# cli       = /workspaces/squared/publish/sqd-cli
+# sqd-serve = /workspaces/squared/publish/sqd-serve
+# sqd       = /workspaces/squared/sqd
+
+Workspace::Application
+  .new(Dir.pwd, main: "squared") # Dir.pwd? (main? is implicitly basename)
+  .banner("group", "project", styles: ["yellow", "black"], border: "bold") # name | project | path | ref | group? | parent? | version?
+  .repo("https://github.com/anpham6/squared-repo", "nightly", script: ["build:dev", "build:prod"], ref: :node) # Repo (optional)
+  .run("rake install", ref: :ruby)
+  .depend(false, group: "default")
+  .clean("rake clean", group: "default")
+  .clean(["build/"], group: "app")
+  .log({ file: "tmp/%Y-%m-%d.log", level: "debug" }, group: "app")
+  .add("pathname", run: "rake compile", copy: "rake install", test: "rake test", group: "default", env: { # Ruby (with C extensions)
+    "CFLAGS" => "-fPIC -O1"
+  })
+  .add("optparse", doc: "rake rdoc", group: "default") # Uses bundler/gem_tasks (without C extensions)
+  .add("logger", copy: { from: "lib", glob: "**/*.rb", into: "~/.rvm/gems/ruby-3.4.0/gems/logger-1.6.1" }, clean: ["tmp/"]) # autodetect: true
+  .add("e-mc", "emc", copy: { from: "publish", scope: "@e-mc", also: [:pir, "squared-express/"] }, ref: :node) # Node
+  .add("pi-r", "pir", copy: { from: "publish", scope: "@pi-r" }, clean: ["publish/**/*.js", "tmp/"]) # Trailing slash required for directories
+  .add("squared", script: ["build:stage1", "build:stage2"], group: "app") do # Copy target (main)
+    add("publish/sqd-cli", "cli", exclude: [:git]) # rake cli:build
+    add("publish/sqd-serve")                       # rake sqd-serve:build
+    add("publish/sqd-admin", group: "sqd", exclude: [:base])
+    # OR
+    with(exclude: [:base]) { add("publish/*", "packages") } # rake packages:sqd-serve:build
+    # OR
+    add(["publish/sqd-cli", "publish/sqd-serve", "publish/sqd-admin"], true, exclude: [:base]) # rake squared:sqd-serve:build
+  end
+  .add("squared/sqd", exclude: :git, pass: [:node, 'checkout', 'bump']) do # Skip initialize(:node) + squared:checkout:* + squared:bump:*
+    variable_set :script, "build:sqd"   # Override detection
+    variable_set :depend, false
+    variable_set :clean, ["build/sqd/"]
+  end
+  .style("banner", 255.255) # 256 colors (fg | fg.bg | -0.bg)
+  .build(default: "build", parallel: ["pull", "fetch", "rebase", "copy", "clean", /^outdated:/]) do |workspace|
+    workspace
+      .enable_aixterm
+      .style({
+        banner: ["bright_cyan", "bold", "bright_black!"],
+        border: "bright_white"
+      })
+  end
+
+# default   = /workspaces/ruby/*
+# pathname  = /workspaces/ruby/pathname
+# optparse  = /workspaces/ruby/optparse
+# logger    = /workspaces/ruby/logger
+# android   = /workspaces/android-docs
+# chrome    = /workspaces/chrome-docs
+
+Workspace::Application
+  .new(ENV["SQUARED_HOME"], prefix: "rb", common: false)        # Local styles
+  .group("ruby", "default", run: "rake build", copy: "rake install", clean: "rake clean", ref: :ruby, override: {
+    pathname: {
+      run: "rake compile"                                       # rake rb:pathname:build
+    }
+  })
+  .with(:python) do                                             # ref=Symbol | group=String
+    banner([:name, ": ", :version], "path")                     # chrome-docs: 0.1.0 | /workspaces/chrome-docs
+    doc("make html")                                            # rake rb:doc:python
+    run(false)                                                  # rake rb:build:python (disabled)
+    exclude(%i[base git])                                       # Project::Git.ref (superclass)
+    add("android-docs", "android")                              # rake rb:android:doc
+    add("chrome-docs", "chrome")                                # rake rb:chrome:doc
+  end
+  .style("inline", "bold")
+  .build
+```
+
+**NOTE**: The use of "**ref**" (class name) is only necessary when initializing an empty directory (e.g. *rake repo:init*).
+
+### Clone
+
+The task is only active when the project directory is empty or does not exist.
+
+```ruby
+Workspace::Application
+  .new(main: "squared")
+  .git(
+    "emc": "https://github.com/anpham6/e-mc",                    # rake emc:clone
+    "pir": {                                                     # rake pir:clone
+      uri: "https://github.com/anpham6/pi-r",                    #
+      options: {                                                 #
+        "origin": "github",                                      # --origin='github'
+        "recurse-submodules": false,                             # --no-recurse-submodules
+        "shallow-exclude": ["v0.0.1", "v0.0.2"]                  # --shallow-exclude='v0.0.1' --shallow-exclude='v0.0.2'
+      }
+    }
+  )
+  .git("squared", "/path/to/squared", options: { local: true })  # Relative paths resolve from workspace root
+  .git(
+    {
+      emc: { uri: "e-mc", options: { "depth": 2 } },             # https://github.com/anpham6/e-mc
+      pir: "pi-r"                                                # Maps task alias to repository folder
+    },
+    base: "https://github.com/anpham6",                          # Required
+    repo: ["squared", "android-docs", "chrome-docs"],            # https://github.com/anpham6/squared
+    options: {                                                   # Only "repo"
+      "depth": 1,
+      "quiet": true
+    }
+  )
+  .with(:node) do                                                # rake clone:node
+    add("e-mc", "emc")                                           # https://github.com/anpham6/e-mc
+    add("pi-r", "pir")                                           # https://github.com/anpham6/pi-r
+    add("squared")                                               # https://github.com/anpham6/squared
+  end
+  .with(:python) do                                              # rake clone:python
+    add("android-docs")
+    add("chrome-docs")
+  end
+  .git("https://github.com/anpham6")                             # Uses already defined root projects
+  .git("https://github.com/anpham6", ["emc", "pir"])             # Targets any defined project
+  .build(parallel: ["clone"])                                    # rake clone + rake clone:sync
+```
+
+### Graph
+
+```ruby
+Workspace::Application
+  .new(main: "squared")
+  .graph(["depend"], ref: :git) # Optional
+  .with(:python) do
+    add("android-docs", "android")
+    add("chrome-docs", "chrome", graph: "android")
+  end
+  .with(:node) do
+    graph(["build", "copy"], on: {                               # Overrides "git"
+      first: proc { puts "1" },
+      last: proc { puts "2" }
+    })
+    add("e-mc", "emc") do
+      first("build", "emc:clean", "emc:depend")                  # rake emc:clean; rake emc:depend; rake emc:build; puts "123";
+      last("build", out: "123") { |out: nil| puts out }          #
+      error("build") { |err: nil| log.debug err }                #
+    end
+    add("pi-r", "pir", graph: "emc", first: {
+      build: proc { puts self.name }                             # puts "pir"
+    })
+    add("squared-express", "express", graph: "pir")
+    add("squared", graph: ["chrome", "express"]) do
+      first("git:ls-files") { puts path }
+      last("git:ls-files") { puts workspace.root }
+    end
+  end
+  .with(:ruby) do
+    add("pathname")
+    add("fileutils", graph: "pathname")
+    add("optparse")
+    add("rake", graph: ["fileutils", "optparse"])
+    banner(command: false)                                       # Always hide banner
+  end
+  .build
+```
+
+```sh
+rake pir:graph      # emc + pir
+rake express:graph  # emc + pir + express
+rake chrome:graph   # android + chrome
+rake graph:python   # same
+rake squared:graph  # android + chrome + emc + pir + express + squared
+rake graph:node     # same
+rake rake:graph     # pathname + fileutils + optparse + rake
+rake graph:ruby     # same
+rake graph          # graph:node + graph:ruby
+```
+
+### Batch
+
+```ruby
+Workspace::Series.batch(:ruby, :node, {
+  stage: %i[graph test],
+  reset: %i[stash pull]
+})
+```
+
+### Rename
+
+```ruby
+Workspace::Series.rename("depend", "install")
+```
+
+## Usage
+
+```sh
+rake -T               # List tasks
+rake                  # rake status (usually "build")
+
+# GIT_OPTIONS=rebase
+rake pull             # All except "default" + "app"
+rake pull:ruby        # pathname + optparse + logger
+rake pull:default     # pathname + optparse
+rake pull:app         # squared
+rake pull:node        # emc + pir + squared
+
+rake build            # All except "android"
+rake doc              # optparse + android
+rake depend           # All except "default"
+
+rake build:ruby       # rake compile + rake install + rake install
+
+rake clean            # All except "default" + "app"
+rake clean:ruby       # rake clean + rake clean + ["tmp/"]
+rake clean:default    # rake clean + rake clean + skip
+rake clean:app        # none + skip + ["build/"]
+rake clean:node       # none + ["publish/**/*.js", "tmp/"] + ["build/"]
+
+rake squared:run[#]   # List scripts (node)
+rake squared:rake[#]  # List tasks (ruby)
+```
+
+```sh
+rake build:app                   # squared + cli + sqd-serve
+rake squared:build:workspace     # cli + sqd-serve
+rake pull:sqd                    # sqd-admin
+rake squared:pull:workspace      # sqd-serve + sqd-admin
+rake squared:outdated:workspace  # cli + sqd-serve + sqd-admin
+```
+
+## Methods
+
+Task:
+
+* run
+* depend
+* graph
+* test
+* doc
+* clean
+
+Non-task:
+
+* log
+* exclude
+
+## Styles
+
+* banner
+* border
+* header
+* active
+* inline
+* current
+* major
+* red
+* yellow
+* green
+
+## Environment
+
+### Path
+
+All project executable programs can have their binary path set to a non-global alias.
+
+```ruby
+Common::PATH.merge!({
+  GIT: '/usr/bin/git',
+  GEM: '~/.rvm/rubies/ruby-3.4.0/bin/gem',
+  BUNDLE: '~/.rvm/gems/ruby-3.4.0/bin/bundle',
+  RAKE: '~/.rvm/gems/ruby-3.4.0/bin/rake',
+  NPM: '/opt/node/v22.0.0/bin/npm',
+  PYTHON: "#{ENV['PYTHONPATH']}/bin/python"
+})
+```
+
+### Build
+
+```ruby
+# :env                                         :run           :opts
+# LD_LIBRARY_PATH="path/to/lib" CFLAGS="-Wall" gcc a.c -o a.o -c
+BUILD_${NAME}      # gcc a.c -o a.o
+BUILD_OPTS_${NAME} # -c
+BUILD_ENV_${NAME}  # {"LD_LIBRARY_PATH":"path/to/lib","CFLAGS":"-Wall"} (hash/json)
+
+# :env                                       :opts                               :script
+# NODE_ENV="production" NO_COLOR="1" npm run --loglevel=error --workspaces=false build:dev
+BUILD_${NAME}      # build:dev
+BUILD_OPTS_${NAME} # --loglevel=error --workspaces=false
+BUILD_ENV_${NAME}  # {"NODE_ENV":"production","NO_COLOR":"1"} (hash/json)
+BUILD_DEV_${NAME}  # pattern,0,1 (:dev)
+BUILD_PROD_${NAME} # pattern,0,1 (:prod)
+
+BUILD_${NAME}=0    # skip project
+```
+
+These options also support the project specific suffix `${NAME}`. (e.g. LOG_FILE_SQUARED)
+
+### Logger
+
+```ruby
+LOG_FILE           # %Y-%m-%d.log
+# OR
+LOG_AUTO           # year,y,month,m,day,d,1
+# Optional
+LOG_DIR            # exist?
+LOG_LEVEL          # See gem "logger"
+LOG_COLUMNS        # terminal width (default: 80)
+```
+
+### Repo
+
+```ruby
+REPO_ROOT          # parent dir
+REPO_HOME          # project dir (main)
+REPO_BUILD         # run,script
+REPO_GROUP         # string
+REPO_REF           # e.g. ruby,node
+REPO_DEV           # pattern,0,1
+REPO_PROD          # pattern,0,1
+REPO_WARN          # 0,1
+REPO_SYNC          # 0,1
+REPO_MANIFEST      # e.g. latest,nightly,prod
+REPO_TIMEOUT       # confirm dialog (seconds)
+```
+
+## LICENSE
+
+BSD 3-Clause

data/lib/squared/app.rb

@@ -6,5 +6,3 @@ require_relative 'workspace/project/node'
 require_relative 'workspace/project/python'
 require_relative 'workspace/project/ruby'
 require_relative 'config'
-
-Common = Squared::Common

data/lib/squared/common/base.rb

@@ -2,6 +2,7 @@
 
 module Squared
   module Common
+    PATH = {}
     ARG = {
       PIPE: 1,
       OUT: nil,
@@ -11,6 +12,7 @@ module Squared
       BANNER: true,
       SPACE: ' => ',
       GRAPH: ['│', '─', '├', '└', '┬'],
+      VIEW: 'view',
       COLOR: ENV.fetch('NO_COLOR', '').empty?
     }
     VAR = {
@@ -35,30 +37,31 @@ module Squared
       },
       theme: {
         workspace: {
-          header: %i[bold],
-          active: %i[bold],
-          inline: %i[bold],
-          major: %i[bold]
+          header: [:bold],
+          active: [:bold],
+          inline: [:bold],
+          current: nil,
+          major: [:bold]
         },
         project: {},
         viewer: {
-          banner: %i[blue bold],
-          key: %i[bold],
-          value: %i[green],
-          string: %i[yellow],
+          banner: [:bold],
+          border: [:blue],
+          key: nil,
+          value: [:green],
+          string: [:yellow],
           hash: %i[green black!],
           array: %i[blue black!],
-          number: %i[magenta],
-          boolean: %i[magenta],
+          number: [:magenta],
           undefined: %i[red italic]
         },
         logger: {
-          unknown: %i[cyan],
+          unknown: [:cyan],
           fatal: %i[white bold red!],
           error: %i[red bold],
           warn: %i[yellow bold],
-          info: %i[blue],
-          debug: %i[green]
+          info: [:blue],
+          debug: [:green]
         }
       }
     }.compare_by_identity
@@ -77,29 +80,29 @@ module Squared
     end
 
     def __freeze__
+      PATH.freeze
       ARG.freeze
       VAR.each_value(&:freeze)
-      VAR[:theme].each_value { |val| val.freeze.each_value(&:freeze) }
+      VAR[:theme].each_value(&:freeze)
       VAR.freeze
     end
 
     module_function
 
-    def as_a(obj, meth = nil, flat: nil, compact: false)
+    def as_a(obj, meth = nil, flat: nil, compact: false, &blk)
       return [] if obj.nil?
 
       unless obj.is_a?(::Array)
-        obj = if obj.respond_to?(:to_ary)
-                obj.to_ary
-              elsif obj.respond_to?(:to_a) && !obj.is_a?(::Hash) && (val = obj.to_a).is_a?(::Array)
+        obj = if obj.respond_to?(:to_a) && !obj.is_a?(::Hash) && (val = obj.to_a).is_a?(::Array)
                 val
               else
                 [obj]
               end
       end
-      obj = flat.is_a?(::Numeric) ? obj.flatten(flat) : obj.flatten if flat
+      obj = obj.flatten(flat.is_a?(::Numeric) ? flat : nil) if flat
       obj = obj.compact if compact
-      meth ? obj.map(&meth) : obj
+      obj = obj.map(&meth) if meth
+      block_given? ? obj.select(&blk) : obj
     end
   end
 end

data/lib/squared/common/class.rb

@@ -34,11 +34,28 @@ module Squared
         super.match(/[^:]+\z/)[0]
       end
 
+      attr_reader :delim
+
       def initialize(data = [], delim: ' ')
         super(data.compact)
         @delim = delim
       end
 
+      def pass(&blk)
+        ret = to_a.map!(&:to_s).reject(&:empty?)
+        block_given? ? ret.reject(&blk) : ret
+      end
+
+      def temp(*args, &blk)
+        args.compact!
+        ret = pass(&blk)
+        unless args.empty?
+          ret += args
+          ret = Set.new(ret).to_a
+        end
+        ret.join(@delim)
+      end
+
       def done
         ret = to_s
         clear
@@ -46,7 +63,7 @@ module Squared
       end
 
       def to_s
-        to_a.map!(&:to_s).reject(&:empty?).join(@delim)
+        pass.join(@delim)
       end
     end
   end

data/lib/squared/common/format.rb

@@ -53,7 +53,7 @@ module Squared
         end
         wrap = ->(s, n) { "\x1B[#{n.join(';')}m#{s}\x1B[0m" }
         code = []
-        args.concat(as_a(styles)).flatten.each_with_index do |type, i|
+        args.concat(as_a(styles)).each_with_index do |type, i|
           next unless type
 
           if index == -1
@@ -114,7 +114,7 @@ module Squared
           if !val.is_a?(::Numeric)
             val = val.to_sym
             ret << val if colors.key?(val) || TEXT_STYLE.include?(val)
-          elsif val.between?(0, 256)
+          elsif val >= 0 && val <= 256
             ret << val
           elsif val < 0 && (b = val.to_s.split('.')[1])
             b = b[0..2]
@@ -127,26 +127,26 @@ module Squared
       def apply_style(data, key, args, empty: true)
         return if data.is_a?(::Symbol) && (data = __get__(:theme)[data]).nil?
 
-        set = ->(k, v) { data[k.to_sym] = check_style(v, empty: empty) }
+        set = ->(k, v) { data[k] = check_style(v, empty: empty) }
         if key.is_a?(::Hash)
           key.each { |k, v| set.(k, v || args) }
         else
-          set.(key, args)
+          set.(key.to_sym, args)
         end
       end
 
       def log_sym(level)
         if level.is_a?(::Numeric)
           case level
-          when ::Logger::DEBUG
+          when Logger::DEBUG
             :debug
-          when ::Logger::INFO
+          when Logger::INFO
             :info
-          when ::Logger::WARN
+          when Logger::WARN
             :warn
-          when ::Logger::ERROR
+          when Logger::ERROR
             :error
-          when ::Logger::FATAL
+          when Logger::FATAL
             :fatal
           else
             :unknown
@@ -171,20 +171,24 @@ module Squared
         if args.size > 1
           title = log_title(level, color: false)
           sub = { pat: /^(#{title})(.+)$/, styles: __get__(:theme)[:logger][log_sym(level)] } if color
-          emphasize(args, title: title + (subject ? " #{subject}" : ''), sub: sub, pipe: -1)
+          emphasize(args, title: title + (subject ? " #{subject}" : ''), sub: sub)
         else
           msg = [log_title(level, color: color)]
-          msg << (color ? sub_style(subject, :underline) : subject) if subject
-          msg << args.shift if msg.size == 1
+          if subject
+            msg << (color ? sub_style(subject, :underline) : subject)
+          else
+            msg += args
+            args.clear
+          end
           message(msg.join(' '), *args, hint: hint)
         end
       end
 
       def puts_oe(*args, pipe: 1)
-        if pipe.is_a?(::Pathname)
+        if pipe.is_a?(Pathname)
           begin
-            ::File.open(pipe, 'a') do |f|
-              br = ::File::SEPARATOR == '\\' ? "\r\n" : "\n"
+            File.open(pipe, 'a') do |f|
+              br = File::SEPARATOR == '\\' ? "\r\n" : "\n"
               args.flatten.each { |val| f.write("#{strip_style(val.chomp)}#{br}") }
             end
             return
@@ -257,8 +261,6 @@ module Squared
           yield out
         elsif pipe
           case pipe
-          when -1
-            return out
           when 0
             pipe = $stdin
           when 2
@@ -276,12 +278,8 @@ module Squared
         val.gsub(/\x1B\[(\d+;?)+m/, '')
       end
 
-      def stripext(val)
-        File.basename(val, File.extname(val))
-      end
-
       def raise_error(*args, hint: nil, kind: ArgumentError)
-        raise kind, message(*args, hint: hint, empty: true)
+        raise kind, message(*args, hint: hint, empty: true), caller_locations(1)
       end
     end
   end

data/lib/squared/common/prompt.rb

@@ -21,7 +21,7 @@ module Squared
                 return false
               end
               attempts -= 1
-              exit 1 unless attempts > 0
+              exit 1 unless attempts >= 0
             end
           rescue Interrupt
             puts