omarchy-ui 0.0.7-x86_64-linux → 0.0.8-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d389e6d9a8382cb8feec3a900ce2b4ee14001d214a069e96be8e7567e549f39e
-  data.tar.gz: 77d33296ea0cc16f08a93bb94a17607a3b50d19e036f2649304a89fcc4b9f455
+  metadata.gz: bbe75336899d8f9674166011c929469db798869f88b32f45a3b61505b0713d01
+  data.tar.gz: bb5f2e4f0dfec4578992d17d5f3fdc5530d5b2c73d4aeebcfada553355077f94
 SHA512:
-  metadata.gz: 2be91201712539398abbf26b03cc3298947d2ff040da32e7171009ef70fdb4127adb7ab5992088176a5f28d5f901cdf4bcdfec68e65c13123bcb3fc61c2206f7
-  data.tar.gz: 89953562fbc3a943290234a297e5cd0f6ecf98b9f7b17a9188a5072716cf42e39e7281c724b97d2b4926df7aabd973485dbbc012ad3285447aaf36de9a7f5514
+  metadata.gz: 9776119537e37548ea84ca4129647a6f94b64944ae75315e776db661220aefeb4cc80527ed93a1b1c9410e0b80d2a547c77a2aae6674f770decc354bdee2a505
+  data.tar.gz: 6856581d58533845967d37daae2679cbf9601f9555aa724b9a9cbf04da0a62a8b15cd146df6d3b36551dec85ad29a13189ba1bdb01a143c2a3cfed87f46d2bb4

data/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <img alt="Omarchy UI 0.0.7" src="https://img.shields.io/badge/Omarchy_UI-0.0.7-b7ff5a?style=flat-square&labelColor=111711">
+  <img alt="Omarchy UI 0.0.8" src="https://img.shields.io/badge/Omarchy_UI-0.0.8-b7ff5a?style=flat-square&labelColor=111711">
   <img alt="Ruby 3.1 or newer" src="https://img.shields.io/badge/Ruby-3.1%2B-cc342d?style=flat-square&logo=ruby&logoColor=white">
   <img alt="Zui 0.0.10" src="https://img.shields.io/badge/Zui-0.0.10-7ee14b?style=flat-square&labelColor=111711">
   <img alt="241 components" src="https://img.shields.io/badge/components-241-75d943?style=flat-square&labelColor=111711">
@@ -53,8 +53,8 @@ and the Omarchy adapter.
 
 | Build | Use it for | Primary surface | Delivery |
 | --- | --- | --- | --- |
-| Omarchy application | Full desktop tools and standalone interfaces | `app :main` | `omarchy_ui run` or `omarchy_ui bundle` |
-| Omarchy plugin | Bar widgets, panels, and shell-integrated tools | `bar_widget` and `panel` | `omarchy_ui validate` and `omarchy_ui push` |
+| Omarchy application | Full desktop tools and standalone interfaces | `app :main` | `omarchy_ui new NAME`, then `run` or `bundle` |
+| Omarchy plugin | Bar widgets, panels, and shell-integrated tools | `bar_widget` and `panel` | `omarchy_ui new NAME --plugin`, then `push` or `bundle` |
 | Portable Zui application | The same application UI outside Omarchy | `app :main` | The platform-neutral [Zui toolchain](https://github.com/AdamMusa/zui#developer-workflow) |
 
 ## Requirements
@@ -63,10 +63,11 @@ and the Omarchy adapter.
 - Ruby 3.1 or newer while installing the gem and developing applications;
 - optional Qt modules for components that use features such as Quick 3D or Multimedia.
 
-The finished Omarchy bundle includes the Omarchy adapter, mruby executable, and a Zui-generated QML
-runtime tree-shaken to the components referenced by that application. The destination does not need
-Ruby or framework gems. A component fails with an explicit error when its required Qt module or
-resource is unavailable; Omarchy UI never substitutes a different component.
+Omarchy UI generates a complete Omarchy-compatible application or plugin package from the
+developer's Ruby and assets. It owns the Omarchy metadata, entry points, adapter, validation,
+tree-shaken Zui QML, and embedded mruby runtime. The finished package does not need Ruby or framework
+gems. A component fails with an explicit error when its required Qt module or resource is unavailable;
+Omarchy UI never substitutes a different component.
 
 ## Quick start
 
@@ -78,20 +79,37 @@ gem install omarchy-ui
 
 The gem installs the compatible Zui version as a dependency.
 
-### 2. Generate an application
+### 2. Generate a complete project
 
 ```bash
 omarchy_ui new Counter
 cd counter
 ```
 
+For an integrated Omarchy plugin instead:
+
+```bash
+omarchy_ui new "System Status" --plugin
+cd system-status
+```
+
+Both commands create a ready-to-run Ruby project. Omarchy UI generates the complete compliant
+application or plugin package; developers do not write QML, shell entry points, or an Omarchy
+manifest by hand.
+
+Each project includes a Ruby-native `config.rb` containing its type, identity, release version,
+entry point, and—for plugins—public marketplace metadata. `bundle`, `validate`, and `push` read this
+single configuration when assembling the complete package.
+
 The generator creates a small, host-independent project:
 
 ```text
 counter/
+├── LICENSE
 ├── app.rb                  # reusable Zui application
 ├── components/
 │   └── welcome.rb          # application-owned Ruby UI module
+├── config.rb               # project identity and build settings
 ├── main.rb                 # Omarchy launcher
 └── README.md
 ```
@@ -228,48 +246,18 @@ QML is not required.
 
 ## Omarchy plugins
 
-A Ruby-powered plugin is an ordinary Omarchy plugin repository with `manifest.json` and `main.rb`
-at its root. Omarchy UI adds the generated service, panel, bar-widget, framework, and runtime files
-while staging the plugin; do not commit generated copies to the application source.
+Generate a complete plugin project with one command:
 
-```text
-system-status/
-├── manifest.json
-├── main.rb
-└── assets/
+```bash
+omarchy_ui new "System Status" --plugin
+cd system-status
 ```
 
-### Manifest
-
-This complete manifest declares the adapter surfaces used by the Ruby definition below:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "example.system-status",
-  "name": "System Status",
-  "version": "0.1.0",
-  "author": "Example Author",
-  "license": "MIT",
-  "description": "A Ruby-powered status panel for Omarchy.",
-  "kinds": ["service", "bar-widget", "panel"],
-  "keepLoaded": true,
-  "entryPoints": {
-    "service": "Service.qml",
-    "barWidget": "BarWidget.qml",
-    "panel": "Panel.qml"
-  },
-  "barWidget": {
-    "displayName": "System Status",
-    "description": "Open the current system status.",
-    "category": "System",
-    "allowMultiple": false,
-    "defaultSection": "right"
-  }
-}
-```
+The generated project already satisfies Omarchy's structural requirements. Developers work in Ruby
+and add their own assets; Omarchy UI owns the required plugin metadata, shell surfaces, native host,
+tree-shaken Zui package, validation, and install lifecycle.
 
-### Ruby entry point
+The Ruby entry point uses ordinary Zui components:
 
 ```ruby
 # main.rb
@@ -294,35 +282,29 @@ OmarchyUI.plugin do
 end
 ```
 
-`bar_widget` declares the shell-owned bar surface. `panel :status` declares the panel opened by
-`open_panel :status`. The manifest must declare the corresponding entry points.
+`bar_widget` and `panel :status` are the complete developer-facing surface declarations. Omarchy UI
+maps them to the required Omarchy shell entry points when it builds or stages the plugin.
 
 ### Validate and install
 
 ```bash
-omarchy_ui validate path/to/system-status
-omarchy_ui push path/to/system-status
+omarchy_ui validate
+omarchy_ui push
 ```
 
-`validate` checks a fully staged copy, including the bundled Ruby entry point and generated adapter.
-`push` then:
-
-1. stages and validates the complete plugin;
-2. backs up an existing installation when present;
-3. installs it atomically under `~/.config/omarchy/plugins/<plugin-id>`;
-4. enables the plugin; and
-5. restarts the Omarchy shell.
+`validate` generates and checks the complete plugin without mutating the Ruby project. `push` safely
+builds, validates, installs, enables, and reloads the plugin for development.
 
 During development, suppress either lifecycle action when needed:
 
 ```bash
-omarchy_ui push path/to/system-status --no-enable
-omarchy_ui push path/to/system-status --no-restart
+omarchy_ui push --no-enable
+omarchy_ui push --no-restart
 ```
 
 > [!WARNING]
 > Omarchy plugins execute as unsandboxed user code inside the shell environment. Review the Ruby,
-> assets, manifest, generated package, and provenance before installing a third-party plugin.
+> assets, generated package, and provenance before installing a third-party plugin.
 
 ## Command-line reference
 
@@ -332,9 +314,10 @@ omarchy_ui <command> [arguments]
 
 | Command | Arguments | Result |
 | --- | --- | --- |
-| `omarchy_ui new NAME` | One application name | Creates a new application directory using a URL-safe form of the name |
+| `omarchy_ui new NAME` | One project name | Creates a complete Omarchy application project |
+| `omarchy_ui new NAME --plugin` | One project name and `--plugin` | Creates a complete Omarchy-compliant plugin project |
 | `omarchy_ui run FILE` | One Ruby entry point | Runs an application through the Omarchy/Quickshell host |
-| `omarchy_ui bundle [DIRECTORY]` | Zero or one project directory | Creates `dist/<project-name>` with the application, Omarchy adapter, runtime, and tree-shaken Zui QML |
+| `omarchy_ui bundle [DIRECTORY]` | Zero or one project directory | Generates the complete distributable package and prints its location |
 | `omarchy_ui validate [DIRECTORY]` | Zero or one plugin directory | Stages the complete plugin and delegates validation to `omarchy plugin validate` |
 | `omarchy_ui push [DIRECTORY]` | Optional `--no-enable` and `--no-restart` | Atomically installs and activates a validated plugin |
 | `omarchy_ui version` | None | Prints the installed Omarchy UI version |
@@ -344,38 +327,19 @@ not forward arbitrary Ruby arguments.
 
 ## Packaging
 
-Create a distributable application from the project root:
+Create the complete distributable package from the project root:
 
 ```bash
 omarchy_ui bundle
-./dist/my-application/run
-```
-
-The bundle contains:
-
-```text
-dist/my-application/
-├── main.rb                     # bundled application source
-├── assets/                     # application-owned resources
-├── App.qml                     # Omarchy host entry point
-├── Service.qml                 # process and surface bridge
-├── Panel.qml                   # shell panel adapter
-├── BarWidget.qml               # shell bar adapter
-├── ControlNode.qml             # generated Zui protocol renderer
-├── Components/Builtins/        # only component adapters selected by Zui
-├── Controls/ Theme/ Fonts/     # generated renderer dependencies
-├── zui-tree-shake.json         # auditable selected-component report
-├── Commons@ Ui@                # links to Omarchy's shell modules
-├── omarchy-ui-runtime          # embedded mruby executable
-├── omarchy-ui-runtime.sha256
-├── RUNTIME_PROVENANCE.md
-└── run
 ```
 
-Plugin bundles use the same runtime package and are validated against their manifest before the
-bundle command succeeds. Generated packages exclude `.git`, previous `dist` output, and stale
-adapter/runtime files before regenerating the minimal QML package. Omarchy UI pins Zui 0.0.10 so the
-tree-shaken QML exactly matches the Zui core embedded in the deterministic mruby runtime.
+Omarchy UI prints the generated package location. It automatically assembles the bundled Ruby and
+assets, Omarchy metadata and entry points, native host, checksummed runtime provenance, and only the
+Zui QML components used by the project. Application packages receive a direct launcher; plugin
+packages are validated against Omarchy's requirements before the command succeeds. Omarchy UI pins
+Zui 0.0.10 so generated QML exactly matches the Zui core embedded in the deterministic mruby runtime.
+The source `config.rb` remains the authoritative build configuration; plugin manifests are generated
+from it in the distributable package and are never maintained separately by the developer.
 
 ## Component catalog
 
@@ -504,11 +468,11 @@ bodies are never recorded. Per-plugin logs rotate at 128 KiB under
 | `Ruby file not found` | Pass an existing entry point to `omarchy_ui run`, normally `main.rb` |
 | `Omarchy QML module not found` | Confirm the Omarchy shell installation provides `/usr/share/omarchy/shell/Commons` and `Ui` |
 | A component reports a missing module | Install or enable the Qt module required by that declared component |
-| Plugin validation fails | Run `omarchy_ui validate` and correct the manifest or staged project error before pushing |
+| Plugin validation fails | Run `omarchy_ui validate` and correct the reported Ruby, asset, or generated-metadata error before pushing |
 | A pushed plugin is installed but inactive | Run `omarchy plugin enable <id>` and `omarchy restart shell` after resolving the reported shell error |
-| The bundle destination already exists | Review or move the existing `dist/<project-name>` directory before bundling again |
+| The bundle destination already exists | Review or move the previously generated package before bundling again |
 
-Omarchy UI reports unsupported properties, components, events, paths, manifests, and runtime
+Omarchy UI reports unsupported properties, components, events, paths, generated metadata, and runtime
 resources directly. Preserve the original error when opening an issue.
 
 ## Development

data/lib/omarchy_ui/cli.rb

@@ -27,7 +27,7 @@ module OmarchyUI
       when "validate" then validate(arguments)
       when "version", "--version", "-v" then @out.puts(OmarchyUI::VERSION); 0
       else
-        @err.puts("Usage: omarchy_ui <new NAME|run FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
+        @err.puts("Usage: omarchy_ui <new NAME [--plugin]|run FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
         command.nil? ? 0 : 64
       end
     rescue Interrupt
@@ -67,14 +67,30 @@ module OmarchyUI
     end
 
     def new_project(arguments)
+      plugin = !arguments.delete("--plugin").nil?
       name = arguments.shift || raise(ArgumentError, "new requires a project name")
-      raise ArgumentError, "new accepts only an application name" unless arguments.empty?
+      raise ArgumentError, "new accepts a name and optional --plugin" unless arguments.empty?
       destination = File.expand_path(slug(name))
-      Generator.new(path: destination, name: name).create
-      @out.puts("Created standalone Omarchy UI app in #{destination}")
+      kind = plugin ? :plugin : :application
+      Generator.new(path: destination, name: name, kind:, author: default_author).create
+      label = plugin ? "Omarchy-compliant plugin" : "self-contained Omarchy application"
+      @out.puts("Created #{label} in #{destination}")
       0
     end
 
+    def default_author
+      configured = ENV["OMARCHY_UI_AUTHOR"].to_s.strip
+      return configured unless configured.empty?
+
+      output, _error, status = Open3.capture3("git", "config", "--get", "user.name")
+      git_author = output.to_s.strip
+      return git_author if status.success? && !git_author.empty?
+
+      ENV["USER"].to_s.strip.then { |user| user.empty? ? "Omarchy UI Developer" : user }
+    rescue SystemCallError
+      "Omarchy UI Developer"
+    end
+
     def slug(value)
       result = value.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
       raise ArgumentError, "name must contain letters or numbers" if result.empty?
@@ -83,6 +99,10 @@ module OmarchyUI
 
     def validate(arguments)
       source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "validate accepts one directory" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "validate requires a plugin project" if config&.application?
+
       with_staged_project(source) do |staging|
         system("omarchy", "plugin", "validate", staging) ? 0 : 1
       end
@@ -91,15 +111,19 @@ module OmarchyUI
     def bundle_project(arguments)
       source = File.expand_path(arguments.shift || Dir.pwd)
       raise ArgumentError, "bundle accepts one directory" unless arguments.empty?
-      raise ArgumentError, "main.rb not found: #{source}" unless File.file?(File.join(source, "main.rb"))
-      destination = File.join(source, "dist", File.basename(source))
+      config = ProjectConfig.load(source)
+      entrypoint = config&.entrypoint || "main.rb"
+      raise ArgumentError, "#{entrypoint} not found: #{source}" unless File.file?(File.join(source, entrypoint))
+      destination = File.join(source, "dist", config&.slug || File.basename(source))
       raise ArgumentError, "bundle destination already exists: #{destination}" if File.exist?(destination)
       FileUtils.mkdir_p(destination)
-      entries = application_entries(source)
+      entries = application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, destination)
-      bundle_ruby_entrypoint(source, destination)
+      config.write_manifest(destination) if config&.plugin?
+      bundle_ruby_entrypoint(source, destination, entrypoint:)
       Runtime.install_package(destination)
-      if File.file?(File.join(destination, "manifest.json"))
+      plugin = config ? config.plugin? : File.file?(File.join(destination, "manifest.json"))
+      if plugin
         raise ArgumentError, "bundled plugin validation failed" unless system("omarchy", "plugin", "validate", destination)
         @out.puts("Bundled plugin in #{destination}")
         return 0
@@ -115,7 +139,7 @@ module OmarchyUI
         app_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
         export OMARCHY_UI_RUNTIME="$app_dir/omarchy-ui-runtime"
         export OMARCHY_UI_PROJECT_DIR="$app_dir"
-        export OMARCHY_UI_RUBY_PROGRAM="$app_dir/main.rb"
+        export OMARCHY_UI_RUBY_PROGRAM="$app_dir/#{entrypoint}"
         export QT_LOGGING_RULES="${QT_LOGGING_RULES:+$QT_LOGGING_RULES;}qt.qpa.services.warning=false"
         exec quickshell --path "$app_dir/App.qml"
       SH
@@ -131,8 +155,9 @@ module OmarchyUI
       [ENV["QT_LOGGING_RULES"], "qt.qpa.services.warning=false"].compact.reject(&:empty?).join(";")
     end
 
-    def application_entries(source)
+    def application_entries(source, config: ProjectConfig.load(source))
       generated = Runtime::GENERATED_ENTRIES + Runtime::AUDIT_FILES + %w[run Commons Ui]
+      generated.concat([ProjectConfig::FILE_NAME, "manifest.json"]) if config
       Dir.children(source).reject { |entry| %w[.git dist].include?(entry) || generated.include?(entry) }
     end
 
@@ -140,8 +165,11 @@ module OmarchyUI
       enable = !arguments.delete("--no-enable")
       restart = !arguments.delete("--no-restart")
       source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "push accepts one directory" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "push requires a plugin project" if config&.application?
       manifest_path = File.join(source, "manifest.json")
-      manifest = JSON.parse(File.read(manifest_path))
+      manifest = config ? config.manifest : JSON.parse(File.read(manifest_path))
       plugin_id = manifest.fetch("id")
       raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(plugin_id)
       plugin_root = File.expand_path("~/.config/omarchy/plugins")
@@ -184,11 +212,14 @@ module OmarchyUI
 
     def stage_project(source, parent: nil, prefix: ".omarchy-ui-staging-")
       raise ArgumentError, "project directory not found: #{source}" unless File.directory?(source)
+      config = ProjectConfig.load(source)
       staging = parent ? Dir.mktmpdir(prefix, parent) : Dir.mktmpdir(prefix)
-      entries = application_entries(source)
+      entries = application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, staging) unless entries.empty?
-      if File.file?(File.join(staging, "main.rb"))
-        bundle_ruby_entrypoint(source, staging)
+      config.write_manifest(staging) if config&.plugin?
+      entrypoint = config&.entrypoint || "main.rb"
+      if File.file?(File.join(staging, entrypoint))
+        bundle_ruby_entrypoint(source, staging, entrypoint:)
         Runtime.install_package(staging)
       end
       staging
@@ -197,9 +228,11 @@ module OmarchyUI
       raise
     end
 
-    def bundle_ruby_entrypoint(source, destination)
-      entrypoint = File.join(source, "main.rb")
-      File.write(File.join(destination, "main.rb"), SourceBundle.new(entrypoint, root: source).call)
+    def bundle_ruby_entrypoint(source, destination, entrypoint: "main.rb")
+      source_entrypoint = File.join(source, entrypoint)
+      destination_entrypoint = File.join(destination, entrypoint)
+      FileUtils.mkdir_p(File.dirname(destination_entrypoint))
+      File.write(destination_entrypoint, SourceBundle.new(source_entrypoint, root: source).call)
     end
 
     def activate_plugin(plugin_id)

data/lib/omarchy_ui/generator.rb

@@ -4,9 +4,15 @@ require "fileutils"
 
 module OmarchyUI
   class Generator
-    def initialize(path:, name: nil)
+    PROJECT_KINDS = %i[application plugin].freeze
+
+    def initialize(path:, name: nil, kind: :application, plugin_id: nil, author: nil)
       @path = File.expand_path(path)
       @name = name || File.basename(@path).split(/[-_]/).map(&:capitalize).join(" ")
+      @kind = kind.to_sym
+      @plugin_id = plugin_id || "local.#{project_slug}"
+      @author = author.to_s.strip.empty? ? "Omarchy UI Developer" : author.to_s.strip
+      raise ArgumentError, "unsupported project kind: #{@kind}" unless PROJECT_KINDS.include?(@kind)
     end
 
     def create
@@ -14,9 +20,11 @@ module OmarchyUI
       created = true
       FileUtils.mkdir_p(File.join(@path, "components"))
       File.write(File.join(@path, "main.rb"), main_program)
-      File.write(File.join(@path, "app.rb"), application_program)
+      File.write(File.join(@path, "app.rb"), application_program) unless plugin?
+      File.write(File.join(@path, ProjectConfig::FILE_NAME), project_config)
       File.write(File.join(@path, "components", "welcome.rb"), welcome_component)
       File.write(File.join(@path, "README.md"), readme)
+      File.write(File.join(@path, "LICENSE"), license)
       @path
     rescue StandardError
       FileUtils.remove_entry(@path) if created && File.directory?(@path)
@@ -26,6 +34,8 @@ module OmarchyUI
     private
 
     def main_program
+      return plugin_program if plugin?
+
       <<~RUBY
         # frozen_string_literal: true
 
@@ -36,6 +46,33 @@ module OmarchyUI
       RUBY
     end
 
+    def plugin_program
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require "omarchy_ui"
+        require_relative "components/welcome"
+
+        OmarchyUI.plugin(ui: #{constant_name}::UI) do
+          bar_widget do
+            row spacing: 7 do
+              text "#{@name}"
+            end
+            on_click { open_panel :#{surface_name} }
+          end
+
+          panel :#{surface_name} do
+            scroll width: 560, height: 620 do
+              welcome_card(
+                title: "#{@name}",
+                message: "Your Omarchy plugin is ready. Build the interface with Ruby and Zui components."
+              )
+            end
+          end
+        end
+      RUBY
+    end
+
     def application_program
       <<~RUBY
         # frozen_string_literal: true
@@ -80,6 +117,8 @@ module OmarchyUI
     end
 
     def readme
+      return plugin_readme if plugin?
+
       <<~MARKDOWN
         # #{@name}
 
@@ -92,10 +131,97 @@ module OmarchyUI
         ```
 
         Reusable Ruby UI components live in `components/` and load with ordinary Ruby
-        `require_relative`. Run `omarchy_ui bundle` to create a self-contained distribution.
+        `require_relative`. Project identity and build settings live in `config.rb`.
+
+        ## Build
+
+        ```bash
+        omarchy_ui bundle
+        ```
+
+        Omarchy UI generates the complete self-contained application package required by Omarchy.
+      MARKDOWN
+    end
+
+    def plugin_readme
+      <<~MARKDOWN
+        # #{@name}
+
+        A pure Ruby Omarchy plugin built with Omarchy UI and Zui.
+
+        ## Validate
+
+        ```bash
+        omarchy_ui validate
+        ```
+
+        ## Install for development
+
+        ```bash
+        omarchy_ui push
+        ```
+
+        ## Build
+
+        ```bash
+        omarchy_ui bundle
+        ```
+
+        Write the plugin interface and behavior in Ruby under `main.rb` and `components/`.
+        Public plugin identity and release metadata live in `config.rb`. Omarchy UI uses it to
+        generate and validate the complete Omarchy-compatible plugin package.
       MARKDOWN
     end
 
+    def project_config
+      config = ProjectConfig.generate(
+        name: @name,
+        slug: project_slug,
+        kind: @kind,
+        author: @author,
+        plugin_id: @plugin_id
+      )
+      config
+    end
+
+    def license
+      <<~TEXT
+        MIT License
+
+        Copyright (c) #{Time.now.year} #{@author}
+
+        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.
+      TEXT
+    end
+
+    def plugin?
+      @kind == :plugin
+    end
+
+    def project_slug
+      File.basename(@path).downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
+    end
+
+    def surface_name
+      project_slug.tr("-", "_")
+    end
+
     def constant_name
       @name.gsub(/[^a-zA-Z0-9]+/, " ").split.map(&:capitalize).join.then do |name|
         name.empty? || name.match?(/\A\d/) ? "OmarchyApplication" : name

data/lib/omarchy_ui/project_config.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OmarchyUI
+  class ProjectConfig
+    FILE_NAME = "config.rb"
+    PROJECT_TYPES = %i[application plugin].freeze
+    SLUG = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+    SECTIONS = %i[left center right].freeze
+
+    class Builder
+      FIELDS = %i[type id name slug version author license description entrypoint].freeze
+
+      FIELDS.each do |field|
+        define_method(field) { |value| @values[field] = value }
+      end
+
+      def initialize
+        @values = {}
+      end
+
+      def bar_widget(&definition)
+        widget = WidgetBuilder.new
+        widget.instance_eval(&definition)
+        @values[:bar_widget] = widget.to_h
+      end
+
+      def build(path: FILE_NAME)
+        ProjectConfig.new(@values, path:).tap(&:validate!)
+      end
+    end
+
+    class WidgetBuilder
+      FIELDS = %i[display_name description category default_section].freeze
+
+      FIELDS.each do |field|
+        define_method(field) { |value| @values[field] = value }
+      end
+
+      def initialize
+        @values = {}
+      end
+
+      def to_h
+        @values.dup
+      end
+    end
+
+    attr_reader :path
+
+    def self.define(&definition)
+      raise ArgumentError, "project config requires a block" unless definition
+
+      Builder.new.tap { |builder| builder.instance_eval(&definition) }.build
+    end
+
+    def self.generate(name:, slug:, kind:, author:, plugin_id: nil)
+      type = kind.to_sym
+      raise ArgumentError, "unsupported project type: #{type}" unless PROJECT_TYPES.include?(type)
+
+      lines = [
+        "# frozen_string_literal: true",
+        "",
+        "OmarchyUI.configure do",
+        "  type #{type.inspect}"
+      ]
+      lines << "  id #{(plugin_id || "local.#{slug}").inspect}" if type == :plugin
+      lines.concat([
+        "  name #{name.inspect}",
+        "  slug #{slug.inspect}",
+        "  version \"0.1.0\""
+      ])
+      if type == :plugin
+        lines.concat([
+          "  author #{author.inspect}",
+          "  license \"MIT\"",
+          "  description #{"A Ruby-powered #{name} plugin generated by Omarchy UI.".inspect}",
+          "  entrypoint \"main.rb\"",
+          "",
+          "  bar_widget do",
+          "    display_name #{name.inspect}",
+          "    description #{"Open #{name}.".inspect}",
+          "    category \"System\"",
+          "    default_section :right",
+          "  end"
+        ])
+      else
+        lines << "  entrypoint \"main.rb\""
+      end
+      lines << "end"
+      lines.join("\n") + "\n"
+    end
+
+    def self.load(root)
+      path = File.join(File.expand_path(root), FILE_NAME)
+      return nil unless File.file?(path)
+
+      value = Module.new.module_eval(File.read(path), path, 1)
+      unless value.is_a?(ProjectConfig)
+        raise ArgumentError, "#{FILE_NAME} must return an OmarchyUI::ProjectConfig"
+      end
+
+      new(value.to_h, path:).tap(&:validate!)
+    rescue SyntaxError, NameError, NoMethodError => error
+      raise ArgumentError, "invalid #{FILE_NAME}: #{error.message}"
+    end
+
+    def initialize(data, path:)
+      @data = data
+      @path = path
+    end
+
+    def type
+      value = @data[:type]
+      value.respond_to?(:to_sym) ? value.to_sym : value
+    end
+    def application? = type == :application
+    def plugin? = type == :plugin
+    def name = @data.fetch(:name)
+    def slug = @data.fetch(:slug)
+    def entrypoint = @data.fetch(:entrypoint)
+
+    def to_h
+      @data.dup
+    end
+
+    def manifest
+      raise ArgumentError, "project config describes an application, not a plugin" unless plugin?
+
+      widget = @data.fetch(:bar_widget)
+      {
+        "schemaVersion" => 1,
+        "id" => @data.fetch(:id),
+        "name" => name,
+        "version" => @data.fetch(:version),
+        "author" => @data.fetch(:author),
+        "license" => @data.fetch(:license),
+        "description" => @data.fetch(:description),
+        "kinds" => ["service", "bar-widget", "panel"],
+        "keepLoaded" => true,
+        "entryPoints" => {
+          "service" => "Service.qml",
+          "barWidget" => "BarWidget.qml",
+          "panel" => "Panel.qml"
+        },
+        "barWidget" => {
+          "displayName" => widget.fetch(:display_name),
+          "description" => widget.fetch(:description),
+          "category" => widget.fetch(:category),
+          "allowMultiple" => false,
+          "defaultSection" => widget.fetch(:default_section).to_s
+        }
+      }
+    end
+
+    def write_manifest(destination)
+      File.write(File.join(destination, "manifest.json"), JSON.pretty_generate(manifest) + "\n")
+    end
+
+    def validate!
+      raise ArgumentError, "invalid project config" unless @data.is_a?(Hash)
+      raise ArgumentError, "invalid project type" unless PROJECT_TYPES.include?(type)
+      required_string!(:name)
+      required_string!(:slug)
+      raise ArgumentError, "invalid project slug" unless SLUG.match?(@data[:slug])
+      required_string!(:version)
+      required_string!(:entrypoint)
+      validate_entrypoint!
+      validate_plugin! if plugin?
+      self
+    end
+
+    private
+
+    def required_string!(key, object = @data)
+      value = object[key]
+      raise ArgumentError, "invalid project config field: #{key}" unless value.is_a?(String) && !value.strip.empty?
+
+      value
+    end
+
+    def validate_entrypoint!
+      parts = entrypoint.split(/[\\\/]/)
+      if entrypoint.start_with?("/") || parts.empty? || parts.include?("..") || !entrypoint.end_with?(".rb")
+        raise ArgumentError, "invalid project entrypoint"
+      end
+    end
+
+    def validate_plugin!
+      %i[id author license description].each { |key| required_string!(key) }
+      raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(@data[:id])
+
+      widget = @data[:bar_widget]
+      raise ArgumentError, "plugin project config is missing bar widget metadata" unless widget.is_a?(Hash)
+
+      %i[display_name description category].each { |key| required_string!(key, widget) }
+      section = widget[:default_section]
+      valid_section = section.respond_to?(:to_sym) && SECTIONS.include?(section.to_sym)
+      raise ArgumentError, "invalid default bar section" unless valid_section
+    end
+  end
+
+  def self.configure(&definition)
+    ProjectConfig.define(&definition)
+  end
+end

data/lib/omarchy_ui.rb

@@ -11,7 +11,7 @@ rescue LoadError
 end
 
 module OmarchyUI
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
   ZUI_VERSION = Zui::VERSION
   FRAMEWORK_ROOT = File.expand_path("..", __dir__)
 
@@ -126,5 +126,6 @@ module Zui
   end
 end
 
+require_relative "omarchy_ui/project_config"
 require_relative "omarchy_ui/generator"
 require_relative "omarchy_ui/runtime"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omarchy-ui
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: x86_64-linux
 authors:
 - Adam Moussa Ali
@@ -39,6 +39,7 @@ files:
 - lib/omarchy_ui.rb
 - lib/omarchy_ui/cli.rb
 - lib/omarchy_ui/generator.rb
+- lib/omarchy_ui/project_config.rb
 - lib/omarchy_ui/runtime.rb
 - vendor/runtime/x86_64-linux/RUNTIME_PROVENANCE.md
 - vendor/runtime/x86_64-linux/omarchy-ui-runtime