{"id":18837068,"url":"https://github.com/bkuhlmann/runcom","last_synced_at":"2025-08-22T10:16:54.646Z","repository":{"id":45695627,"uuid":"72698904","full_name":"bkuhlmann/runcom","owner":"bkuhlmann","description":"A XDG enhanced run command manager for command line interfaces.","archived":false,"fork":false,"pushed_at":"2025-08-08T17:18:42.000Z","size":672,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-08T19:26:27.244Z","etag":null,"topics":["cli","configuration-management","runcom","xdg"],"latest_commit_sha":null,"homepage":"https://alchemists.io/projects/runcom","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bkuhlmann.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.adoc","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["bkuhlmann"]}},"created_at":"2016-11-03T02:00:23.000Z","updated_at":"2025-08-08T17:18:45.000Z","dependencies_parsed_at":"2023-10-16T08:57:01.418Z","dependency_job_id":"944cd51a-4f6d-4795-8996-fb92f432ccb1","html_url":"https://github.com/bkuhlmann/runcom","commit_stats":{"total_commits":558,"total_committers":1,"mean_commits":558.0,"dds":0.0,"last_synced_commit":"ddbdc6e8a318378b99e43825d5b97cdf9a7a6c2d"},"previous_names":[],"tags_count":93,"template":false,"template_full_name":null,"purl":"pkg:github/bkuhlmann/runcom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fruncom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fruncom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fruncom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fruncom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkuhlmann","download_url":"https://codeload.github.com/bkuhlmann/runcom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fruncom/sbom","scorecard":{"id":241756,"data":{"date":"2025-08-11","repo":{"name":"github.com/bkuhlmann/runcom","commit":"7d4a7c636281ef5f280b3c7a070ed790bf9b6898"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.5,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Maintained","score":7,"reason":"9 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 7","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE.adoc:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}}]},"last_synced_at":"2025-08-17T06:47:29.163Z","repository_id":45695627,"created_at":"2025-08-17T06:47:29.164Z","updated_at":"2025-08-17T06:47:29.164Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271620946,"owners_count":24791632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","configuration-management","runcom","xdg"],"created_at":"2024-11-08T02:33:42.739Z","updated_at":"2025-08-22T10:16:54.619Z","avatar_url":"https://github.com/bkuhlmann.png","language":"Ruby","funding_links":["https://github.com/sponsors/bkuhlmann"],"categories":["Ruby"],"sub_categories":[],"readme":":toc: macro\n:toclevels: 5\n:figure-caption!:\n\n:xdg_link: link:https://alchemists.io/projects/xdg[XDG]\n:etcher_link: link:https://alchemists.io/projects/etcher[Etcher]\n\n= Runcom\n\nRuncom is a link:https://en.wikipedia.org/wiki/Run_commands[Run Command] portmanteau (i.e. `run + [com]mand = runcom`) which provides common functionality for Command Line Interfaces (CLIs) in which to manage global/local caches, configurations, data, and/or state. This is done by leveraging the https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification] built atop the {xdg_link} implementation. In other words, Runcom is an enhanced version of {xdg_link} which specializes in dynamic global and local detection.\n\ntoc::[]\n\n== Features\n\n* Wraps the {xdg_link} implementation which provides access to the following environment variables:\n** `+$XDG_CACHE_HOME+`\n** `+$XDG_CONFIG_HOME+`\n** `+$XDG_CONFIG_DIRS+`\n** `+$XDG_DATA_HOME+`\n** `+$XDG_DATA_DIRS+`\n** `+$XDG_STATE_HOME+`\n* Enhances the {xdg_link} cache, config, data, and state implementations with dynamic global and local detection.\n\n== Requirements\n\n. https://www.ruby-lang.org[Ruby]\n\n== Setup\n\nTo install _with_ security, run:\n\n[source,bash]\n----\n# 💡 Skip this line if you already have the public certificate installed.\ngem cert --add \u003c(curl --compressed --location https://alchemists.io/gems.pem)\ngem install runcom --trust-policy HighSecurity\n----\n\nTo install _without_ security, run:\n\n[source,bash]\n----\ngem install runcom\n----\n\nYou can also add the gem directly to your project:\n\n[source,bash]\n----\nbundle add runcom\n----\n\nOnce the gem is installed, you only need to require it:\n\n[source,ruby]\n----\nrequire \"runcom\"\n----\n\n== Usage\n\nThe following describes the enhancements built atop the {xdg_link} implementation.\n\n=== Overview\n\nWhile there isn’t a sole convenience object as found with the `XDG` gem, you can instantiate each object individually:\n\n[source,ruby]\n----\ncache = Runcom::Cache.new \"demo/data.json\"\nconfig = Runcom::Config.new \"demo/configuration.yml\"\ndata = Runcom::Data.new \"demo/store.dat\"\nstate = Runcom::State.new \"demo/history.log\"\n----\n\nBy default, each Runcom object expects a relative file path but you can also use a fully qualified path when constructing a new instance.\n\nEach of the above objects share the same Object API:\n\n* `#initial`: Answers the initial path -- which can be a relative or absolute path -- from which the object was constructed.\n* `#namespace`: Answers the namespace as a pathname object from which the instance was constructed. The namespace must be unique and identical across the cache, config, data, and state objects since this is what identifies and organizes all files associated with your program.\n* `#file_name`: Answers the file name from which the object was constructed.\n* `#active`: Answers first _existing file path_ as computed by `+$XDG_*_HOME+` followed by each computed `+$XDG_*_DIRS+` path in order defined. Otherwise, `nil` is answered back when no path exists.\n* `#passive`: Answers first path as computed by `+$XDG_*_HOME+` followed by each computed `+$XDG_*_DIRS+` path in order defined which _may_ or _may not_ exist. This behaves like `#active`  but doesn't care if the path exists. Handy for situations where you'd like the active path but can  fallback to creating the global path if otherwise.\n* `#global`: Answers the first _existing_ or _non-existing_ global path.\n* `#local`: Answers the first _existing_ or _non-existing_ local path.\n* `#all`: Answers all paths which is the combined `+$XDG_*_HOME+` and `+$XDG_*_DIRS+` values in order defined. These paths _may_ or _may not_ exist.\n* `#to_s`: Answers an _explicit_ string cast for the current environment.\n* `#to_str`: Answers an _implicit_ string cast for the current environment.\n* `#inspect`: Answers object inspection complete with object type, object ID, and all environment variables.\n\n=== Examples\n\nThe following are examples of what you will see when exploring the Runcom objects within an IRB console:\n\n[source,ruby]\n----\n# Initialization\n\ncache = XDG::Cache.new \"demo/projects.json\"\nconfig = XDG::Config.new \"demo/settings.yml\"\ndata = XDG::Data.new \"demo/vault.store\"\nstate = XDG::State.new \"demo/history.log\"\n\n# Paths\n\ncache.initial     # \"#\u003cPathname:demo/projects.json\u003e\"\ncache.namespace   # \"#\u003cPathname:demo\u003e\"\ncache.file_name   # \"#\u003cPathname:projects.json\u003e\"\ncache.active      # nil\ncache.passive     # \"#\u003cPathname:/Users/demo/.cache/demo/projects.json\u003e\"\ncache.global      # \"#\u003cPathname:/Users/demo/.cache/demo/projects.json\u003e\"\ncache.local       # \"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.cache/demo/projects.json\u003e\"\ncache.all         # [\"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.cache/demo/projects.json\u003e\", \"#\u003cPathname:/Users/demo/.cache/demo/projects.json\u003e\"]\n\nconfig.initial    # \"#\u003cPathname:demo/settings.yml\u003e\"\nconfig.namespace  # \"#\u003cPathname:demo\u003e\"\nconfig.file_name  # \"#\u003cPathname:settings.yml\u003e\"\nconfig.active     # nil\nconfig.passive    # \"#\u003cPathname:/Users/demo/.config/demo/settings.yml\u003e\"\nconfig.global     # \"#\u003cPathname:/Users/demo/.config/demo/settings.yml\u003e\"\nconfig.local      # \"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.config/demo/settings.yml\u003e\"\nconfig.all        # [\"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.config/demo/settings.yml\u003e\", \"#\u003cPathname:/Users/demo/.config/demo/settings.yml\u003e\", \"#\u003cPathname:/etc/xdg/demo/settings.yml\u003e\"]\n\ndata.initial      # \"#\u003cPathname:demo/vault.store\u003e\"\ndata.namespace    # \"#\u003cPathname:demo\u003e\"\ndata.file_name    # \"#\u003cPathname:vault.store\u003e\"\ndata.active       # nil\ndata.passive      # \"#\u003cPathname:/Users/demo/.local/share/demo/vault.store\u003e\"\ndata.global       # \"#\u003cPathname:/Users/demo/.local/share/demo/vault.store\u003e\"\ndata.local        # \"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.local/share/demo/vault.store\u003e\"\ndata.all          # [\"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.local/share/demo/vault.store\u003e\", \"#\u003cPathname:/Users/demo/.local/share/demo/vault.store\u003e\", \"#\u003cPathname:/usr/local/share/demo/vault.store\u003e\", \"#\u003cPathname:/usr/share/demo/vault.store\u003e\"]\n\nstate.initial     # \"#\u003cPathname:demo/history.log\u003e\"\nstate.namespace   # \"#\u003cPathname:demo\u003e\"\nstate.file_name   # \"#\u003cPathname:history.log\u003e\"\nstate.active      # nil\nstate.passive     # \"#\u003cPathname:/Users/demo/.local/state/demo/history.log\u003e\"\nstate.global      # \"#\u003cPathname:/Users/demo/.local/state/demo/history.log\u003e\"\nstate.local       # \"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.local/state/demo/history.log\u003e\"\nstate.all         # [\"#\u003cPathname:/Users/demo/Engineering/OSS/runcom/.local/state/demo/history.log\u003e\", \"#\u003cPathname:/Users/demo/.local/state/demo/history.log\u003e\"]\n\n# Casts (explicit and implicit)\n\ncache.to_s        # \"XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Users/demo/.cache\"\nconfig.to_s       # \"XDG_CONFIG_HOME=/Users/demo/Engineering/OSS/runcom/.config:/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg\"\ndata.to_s         # \"XDG_DATA_HOME=/Users/demo/Engineering/OSS/runcom/.local/share:/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share\"\nstate.to_s        # \"XDG_STATE_HOME=/Users/demo/Engineering/OSS/runcom/.local/state:/Users/demo/.local/state\"\n\ncache.to_str      # \"XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Users/demo/.cache\"\nconfig.to_str     # \"XDG_CONFIG_HOME=/Users/demo/Engineering/OSS/runcom/.config:/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg\"\ndata.to_str       # \"XDG_DATA_HOME=/Users/demo/Engineering/OSS/runcom/.local/share:/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share\"\nstate.to_str      # \"XDG_STATE_HOME=/Users/demo/Engineering/OSS/runcom/.local/state:/Users/demo/.local/state\"\n\n# Inspection\n\ncache.inspect     # \"#\u003cRuncom::Cache:2040 XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Users/demo/.cache\u003e\"\nconfig.inspect    # \"#\u003cRuncom::Config:2060 XDG_CONFIG_HOME=/Users/demo/Engineering/OSS/runcom/.config:/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg\u003e\"\ndata.inspect      # \"#\u003cRuncom::Data:2080 XDG_DATA_HOME=/Users/demo/Engineering/OSS/runcom/.local/share:/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share\u003e\"\nstate.inspect     # \"#\u003cRuncom::State:2100 XDG_STATE_HOME=/Users/demo/Engineering/OSS/runcom/.local/state:/Users/demo/.local/state\u003e\"\n----\n\n=== Variable Priority\n\nPath precedence is determined in the following order (with the first taking highest priority):\n\n. *Local Configuration*: If a `+$XDG_*_HOME+` or `+$XDG_*_DIRS+` path relative to the\n  current working directory is detected, it will take precedence over the global configuration.\n  This is the same behavior as found in Git where the local `.git/config` takes precedence over the\n  global `$HOME/.gitconfig`.\n. *Global Configuration*: When a local configuration isn’t found, the global configuration is used\n  as defined by the _XDG Base Directory Specification_.\n\n=== Building Blocks\n\nWhile {xdg_link} and Runcom are powerful in their own right, a great building block you can add on top of this gem is the {etcher_link} gem which loads, transforms, validates, and produces structured data from raw Runcom information. For more sophisticated applications, this synergetic coupling of `XDG + Runcom + Etcher` makes for nicely designed architectures.\n\n=== Examples\n\nExamples of gems built atop this gem are:\n\n* link:https://alchemists.io/projects/rubysmith[Rubysmith]: A command line interface for\n  smithing Ruby projects.\n* link:https://alchemists.io/projects/gemsmith[Gemsmith]: A command line interface for smithing\n  new Ruby gems.\n* link:https://alchemists.io/projects/hanamismith[Hanamismith]: A command line interface for smithing link:https://hanamirb.org[Hanami] projects.\n* link:https://alchemists.io/projects/git-lint[Git Lint]: Enforces consistent Git commits.\n* link:https://alchemists.io/projects/milestoner[Milestoner]: A command line interface for\n  releasing Git repository milestones.\n* link:https://alchemists.io/projects/pennyworth[Pennyworth]: A command line interface that\n  enhances and extends link:https://www.alfredapp.com[Alfred] with Ruby support.\n* link:https://alchemists.io/projects/pragmater[Pragmater]: A command line interface for\n  managing/formatting source file pragma comments.\n* link:https://alchemists.io/projects/sublime_text_kit[Sublime Text Kit]: A command line\n  interface for managing Sublime Text metadata.\n* link:https://alchemists.io/projects/tocer[Tocer]: A command line interface for generating\n  Markdown table of contents.\n\n== Development\n\nTo contribute, run:\n\n[source,bash]\n----\ngit clone https://github.com/bkuhlmann/runcom\ncd runcom\nbin/setup\n----\n\nYou can also use the IRB console for direct access to all objects:\n\n[source,bash]\n----\nbin/console\n----\n\nLastly, there is a `bin/demo` script which displays default functionality for quick visual reference. This is the same script used to generate the usage examples shown at the top of this document.\n\n[source,bash]\n----\nbin/demo\n----\n\n== Tests\n\nTo test, run:\n\n[source,bash]\n----\nbin/rake\n----\n\n== link:https://alchemists.io/policies/license[License]\n\n== link:https://alchemists.io/policies/security[Security]\n\n== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]\n\n== link:https://alchemists.io/policies/contributions[Contributions]\n\n== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]\n\n== link:https://alchemists.io/projects/runcom/versions[Versions]\n\n== link:https://alchemists.io/community[Community]\n\n== Credits\n\n* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].\n* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Fruncom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkuhlmann%2Fruncom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Fruncom/lists"}