### Preview the documentation site Source: https://github.com/navbytes/vee/blob/main/CONTRIBUTING.md Commands to install dependencies and start the development server for the documentation site. ```sh cd docs-site && npm install && npm run dev ``` -------------------------------- ### Install the Vee Go SDK Source: https://github.com/navbytes/vee/blob/main/plugins/go/README.md Use the go get command to add the SDK as a module dependency. ```sh go get github.com/navbytes/vee/plugins/go@v0.2.0 # or @latest ``` -------------------------------- ### Install and import Go SDK Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md Go plugins use standard module dependencies as they compile to binaries. ```sh go get github.com/navbytes/vee/plugins/go ``` ```go import vee "github.com/navbytes/vee/plugins/go" ``` -------------------------------- ### Install Vee with custom options Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md Installs Vee with specific configuration flags for application directory, binary path, or version pinning. ```sh # Install per-user instead of system-wide curl -fsSL https://vee.navbytes.io/install.sh | bash -s -- --app-dir ~/Applications # Put the CLI somewhere else on your PATH curl -fsSL https://vee.navbytes.io/install.sh | bash -s -- --bin-dir /opt/homebrew/bin # Pin a specific release rather than the latest curl -fsSL https://vee.navbytes.io/install.sh | bash -s -- --version v0.2.0 ``` -------------------------------- ### Example preference declarations Source: https://github.com/navbytes/vee/blob/main/docs/_content/preferences.md Common examples of preference declarations for different data types. ```python # string(CITY=London): Which city's weather to show. # number(REFRESH_COUNT=5): How many items to display. # boolean(SHOW_ICON=true): Show an icon in the menu bar. # select(UNITS=metric): Measurement units. [metric, imperial] # string(API_TOKEN=): Your service API token. ``` -------------------------------- ### Accessing guide page source Source: https://github.com/navbytes/vee/blob/main/docs/_content/writing-plugins-with-an-llm.md Individual guide pages can be retrieved in Markdown format by changing the file extension. ```text https://vee.navbytes.io/guide/plugin-authoring.html ← the page you read https://vee.navbytes.io/guide/plugin-authoring.md ← the source a model reads ``` -------------------------------- ### Create Hello World Plugin Source: https://github.com/navbytes/vee/blob/main/plugins/python/README.md Example of a plugin script defining a menu with a title, dropdown items, and a submenu. ```python #!/usr/bin/env python3 from vee import Menu # vee.py sits beside this file menu = Menu() menu.title("CPU 12%", color="green", sfimage="cpu") d = menu.dropdown d.item("Top processes", href="https://example.com/procs") d.separator() details = d.submenu("Details") details.item("Load: 1.20") details.item("Cores: 8") d.item("Refresh", refresh=True) menu.print() ``` -------------------------------- ### Create a Hello World plugin Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md A basic example of a plugin script that defines a menu with a title, dropdown items, and a submenu. ```ts #!/usr/bin/env node import { Menu } from "./vee.ts"; const menu = new Menu(); menu.title("CPU 12%", { color: "green", sfimage: "cpu" }); const d = menu.dropdown; d.item("Top processes", { href: "https://example.com/procs" }); d.separator(); const details = d.submenu("Details"); details.item("Load: 1.20"); details.item("Cores: 8"); d.item("Refresh", { refresh: true }); menu.print(); ``` -------------------------------- ### Install Vee via Homebrew Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md Installs the Vee application and CLI using the Homebrew package manager. ```sh brew install --cask navbytes/tap/vee ``` -------------------------------- ### Install Vee SDK Source: https://github.com/navbytes/vee/blob/main/plugins/python/README.md Command to generate the vee.py SDK file in the specified plugins directory. ```sh vee sdk py --out ~/path/to/your/plugins # writes vee.py there ``` -------------------------------- ### Download and run the kitchen sink plugin Source: https://github.com/navbytes/vee/blob/main/plugins/showcase/README.md Downloads the kitchen-sink example plugin to the Vee plugins directory and makes it executable. ```sh curl -o ~/Library/Application\ Support/Vee/plugins/kitchen-sink.1m.sh \ https://raw.githubusercontent.com/navbytes/vee/main/plugins/showcase/kitchen-sink.1m.sh chmod +x ~/Library/Application\ Support/Vee/plugins/kitchen-sink.1m.sh ``` -------------------------------- ### Install Vee SDK via CLI Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md Use the CLI to write the SDK file directly to your plugins directory. ```sh vee sdk ts --out ~/path/to/your/plugins # writes vee.ts there ``` -------------------------------- ### Install Vee SDK via npm Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md Install the SDK as a dependency in projects that already use npm. ```sh npm install @navbytes/vee ``` -------------------------------- ### Settings form layout example Source: https://github.com/navbytes/vee/blob/main/docs/_content/preferences.md Visual representation of how the declared preferences appear in the settings pane. ```text City [ London ] Which city's weather to show. Refresh count [ 5 ] How many items to display. Show icon ( ●) on Show an icon in the menu bar. Units [ metric ▾ ] Measurement units. API token [ •••••••••••• ] Your service API token. ``` -------------------------------- ### Install Vee via curl Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md Installs Vee using the provided shell script. ```sh curl -fsSL https://vee.navbytes.io/install.sh | bash ``` -------------------------------- ### Install Vee CLI via mise Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md Installs only the Vee CLI tool using the mise version manager. ```sh mise use github:navbytes/vee ``` -------------------------------- ### Preview a plugin with vee show Source: https://github.com/navbytes/vee/blob/main/docs/_content/debugging.md Use this command to render a plugin's output in the terminal, either by file path or by installed plugin name. ```sh $ vee show ./cpu.10s.sh # or an installed plugin by name: vee show cpu ``` -------------------------------- ### Install a plugin manually Source: https://github.com/navbytes/vee/blob/main/plugins/showcase/README.md Sets the executable bit on a plugin file and copies it to the Vee plugins directory. ```sh chmod +x hello-world.10s.sh cp hello-world.10s.sh "" ``` -------------------------------- ### Install and import TypeScript SDK via npm Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md Use npm for plugins that are part of a larger project with node_modules. ```sh npm install @navbytes/vee ``` ```ts import { Menu } from "@navbytes/vee"; ``` -------------------------------- ### Triggering an actionable notification Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md Example of an actionable notification using the open command and the $VEE_PLUGIN_ID variable. ```bash open "vee://notify?plugin=$VEE_PLUGIN_ID&title=Build%20failed&body=exit%201" ``` -------------------------------- ### Import SDK from npm package Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md Import the Menu class from the installed npm package. ```ts import { Menu } from "@navbytes/vee"; ``` -------------------------------- ### Create a streamable plugin Source: https://github.com/navbytes/vee/blob/main/docs/_content/plugin-authoring.md Use the streamable type to push updates continuously. The ~~~ separator defines the start of a new menu render. ```bash #!/bin/bash # streamable while true; do echo "~~~" echo "⏱ $(date +%T)" sleep 1 done ``` -------------------------------- ### Define menu items with options Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md Examples of adding menu items with various options like shell commands, badges, markdown, and SF symbols across different languages. ```typescript d.item("Open build", { shell: "/usr/bin/open", params: ["-a", "Xcode"], terminal: false }); d.item("Inbox", { badge: "12" }); d.item("**Bold** text", { md: true }); d.item("Status :checkmark.circle:", { symbolize: true }); ``` ```python d.item("Open build", shell="/usr/bin/open", params=["-a", "Xcode"], terminal=False) d.item("Inbox", badge="12") d.item("**Bold** text", md=True) d.item("Status :checkmark.circle:", symbolize=True) ``` ```go d.Item("Open build", &vee.Options{Shell: vee.Str("/usr/bin/open"), Params: []string{"-a", "Xcode"}, Terminal: vee.Bool(false)}) d.Item("Inbox", &vee.Options{Badge: vee.Str("12")}) d.Item("**Bold** text", &vee.Options{MD: vee.Bool(true)}) d.Item("Status :checkmark.circle:", &vee.Options{Symbolize: vee.Bool(true)}) ``` -------------------------------- ### Define a Vee menu with rich controls in JSON Source: https://github.com/navbytes/vee/blob/main/docs/_content/json-output.md Example structure demonstrating various inline controls including sparklines, toggles, sliders, progress bars, and a donut chart. ```json { "vee": 1, "title": [{ "text": "System" }], "items": [ { "text": "Load history", "sparkline": [1, 2, 3, 5, 8, 13], "sparklineWidth": 120, "sparklineHeight": 18, "sparklineColor": "teal" }, { "text": "Notifications", "toggle": true }, { "text": "Volume", "slider": { "min": 0, "max": 100, "value": 40 } }, { "text": "Disk usage", "color": "green", "progress": 0.72, "progressTrackColor": "#333333", "progressWidth": 80, "progressHeight": 6 }, { "text": "By category", "chart": { "kind": "donut", "values": [45, 30, 25], "labels": ["Documents", "Photos", "Apps"] } } ] } ``` -------------------------------- ### Initialize and build the project Source: https://github.com/navbytes/vee/blob/main/CONTRIBUTING.md Commands to clone the repository, build the libraries, run tests, and execute the menu-bar app. ```sh git clone https://github.com/navbytes/vee.git cd vee swift build # build the libraries + the dev `vee` executable swift test # run the XCTest suites (TDD — keep these green) swift run vee # run the menu-bar app for local development ``` -------------------------------- ### Create a Hello World Plugin Source: https://github.com/navbytes/vee/blob/main/plugins/go/README.md Construct a menu with a title, dropdown items, and a submenu using the Vee builder pattern. ```go package main import "vee" func main() { m := &vee.Menu{} m.Title("CPU 12%", &vee.Options{Color: vee.Str("green"), SFImage: vee.Str("cpu")}) d := m.Dropdown() d.Item("Top processes", &vee.Options{Href: vee.Str("https://example.com/procs")}) d.Separator() details := d.Submenu("Details", nil) details.Item("Load: 1.20", nil) details.Item("Cores: 8", nil) d.Item("Refresh", &vee.Options{Refresh: vee.Bool(true)}) m.Print() } ``` -------------------------------- ### Create a hello world plugin Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md A basic shell script that displays a menu bar title and a dropdown menu item. ```bash #!/bin/bash echo "Hello 👋" echo "---" echo "It works!" echo "Refresh | refresh=true" ``` -------------------------------- ### Build and run Vee from source Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md Use these commands to build the project, run tests, and launch the menu-bar application during development. ```sh swift build # build the libraries + dev executable swift test # run the test suites swift run vee # launch the menu-bar app for development ``` -------------------------------- ### Configure Share Charts Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md Examples of using the chart builder for pie and donut visualizations. ```ts d.item("By category", { chart: { kind: "pie", values: [45, 30, 25], labels: ["Documents", "Photos", "Apps"] } }); d.item("By volume", { chart: { kind: "donut", values: [512, 256, 128], colors: ["blue", "teal", "orange"] } }); ``` ```python d.item("By category", chart={"kind": "pie", "values": [45, 30, 25], "labels": ["Documents", "Photos", "Apps"]}) d.item("By volume", chart={"kind": "donut", "values": [512, 256, 128], "colors": ["blue", "teal", "orange"]}) ``` ```go d.Item("By category", &vee.Options{Chart: &vee.Chart{ Kind: "pie", Values: []float64{45, 30, 25}, Labels: []string{"Documents", "Photos", "Apps"}, }}) d.Item("By volume", &vee.Options{Chart: &vee.Chart{ Kind: "donut", Values: []float64{512, 256, 128}, Colors: []string{"blue", "teal", "orange"}, }}) ``` -------------------------------- ### Initialize GitHubCatalogClient with StoreConfig Source: https://github.com/navbytes/vee/blob/main/docs/design/custom-plugin-store.md Initializes the client with a configuration object, optional token provider, and URL session. ```swift public init(config: StoreConfig, tokenProvider: StoreTokenProviding? = nil, session: URLSession = .shared) ``` -------------------------------- ### Regenerate shared fixtures Source: https://github.com/navbytes/vee/blob/main/plugins/README.md Updates the golden output files using the TypeScript examples. ```sh cd plugins/typescript && npm run build:fixtures ``` -------------------------------- ### Plugin Management Actions Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md Actions to refresh, enable, disable, toggle, or install plugins. ```APIDOC ## [GET] vee://[action] ### Description Perform management operations on plugins using the vee:// or swiftbar:// URL schemes. ### Endpoint vee://[action]?name=[plugin_name] ### Parameters #### Query Parameters - **name** (string) - Required - The name or path of the plugin. - **src** (string) - Required (for addplugin) - The URL source to download and install a plugin. ### Actions - **refreshallplugins** / **refreshall**: Re-run every plugin. - **refreshplugin**: Re-run one plugin by name. - **enableplugin**: Enable a plugin. - **disableplugin**: Disable a plugin. - **toggleplugin**: Toggle a plugin's enabled state. - **addplugin**: Download and install a plugin from a URL. ``` -------------------------------- ### Build and Test Commands Source: https://github.com/navbytes/vee/blob/main/ARCHITECTURE.md Standard commands for building libraries, running tests, and executing the menu-bar application. ```sh swift build # libraries + the dev `vee` executable swift test # all XCTest suites (keep green; TDD) swift run vee # run the menu-bar app for local development ``` -------------------------------- ### Declare a preference using xbar.var Source: https://github.com/navbytes/vee/blob/main/docs/_content/preferences.md Use this syntax within a plugin source to define a configuration setting. ```text TYPE(NAME=DEFAULT): Description [option1, option2, …] ``` -------------------------------- ### Triggering a notification via URL Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md Example of a basic notification URL using the vee:// scheme. ```text vee://notify?title=Backup&subtitle=Nightly&body=Completed%20successfully&href=https://example.com ``` -------------------------------- ### Create a Go plugin Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md Implements a menu plugin in Go. Requires Go 1.21 or later and must be compiled into a binary. ```go package main import "vee" func main() { m := &vee.Menu{} m.Title("CPU 12%", &vee.Options{Color: vee.Str("green"), SFImage: vee.Str("cpu")}) d := m.Dropdown() d.Item("Top processes", &vee.Options{Href: vee.Str("https://example.com/procs")}) d.Separator() details := d.Submenu("Details", nil) details.Item("Load: 1.20", nil) details.Item("Cores: 8", nil) d.Item("Refresh", &vee.Options{Refresh: vee.Bool(true)}) m.Print() } ``` ```sh go build -o cpu.5s ./... ``` -------------------------------- ### Configure Inline Controls Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md Examples of using typed builders for inline visual controls across supported languages. ```ts d.item("Load history", { sparkline: [1, 2, 3, 5, 8, 13], sparklineW: 120, sparklineH: 18, sparklineColor: "teal" }); d.item("Notifications", { toggle: true }); d.item("Volume", { slider: { min: 0, max: 100, value: 40 } }); d.item("Disk usage", { color: "green", progress: 0.72, progressTrackColor: "#333333", progressW: 80, progressH: 6 }); // progress also accepts a value/max pair, emitted as `progress=72,100`: d.item("Budget", { progress: { value: 72, max: 100 } }); // and any width takes "full": d.item("Requests", { sparkline: [12, 40, 31, 55], sparklineW: "full" }); ``` ```python d.item("Load history", sparkline=[1, 2, 3, 5, 8, 13], sparkline_w=120, sparkline_h=18, sparkline_color="teal") d.item("Notifications", toggle=True) d.item("Volume", slider={"min": 0, "max": 100, "value": 40}) d.item("Disk usage", color="green", progress=0.72, progress_track_color="#333333", progress_w=80, progress_h=6) d.item("Budget", progress={"value": 72, "max": 100}) d.item("Requests", sparkline=[12, 40, 31, 55], sparkline_w="full") ``` ```go d.Item("Load history", &vee.Options{Sparkline: []float64{1, 2, 3, 5, 8, 13}, SparklineW: vee.Float(120), SparklineH: vee.Float(18), SparklineColor: vee.Str("teal")}) d.Item("Notifications", &vee.Options{Toggle: vee.Bool(true)}) d.Item("Volume", &vee.Options{Slider: &vee.Slider{Min: 0, Max: 100, Value: 40}}) d.Item("Disk usage", &vee.Options{Color: vee.Str("green"), Progress: vee.Float(0.72), ProgressTrackColor: vee.Str("#333333"), ProgressW: vee.Float(80), ProgressH: vee.Float(6)}) d.Item("Budget", &vee.Options{ProgressValue: vee.Float(72), ProgressMax: vee.Float(100)}) d.Item("Requests", &vee.Options{Sparkline: []float64{12, 40, 31, 55}, SparklineFullWidth: true}) ``` -------------------------------- ### Build and run Vee from source Source: https://github.com/navbytes/vee/blob/main/README.md Commands to compile the libraries, run tests, and generate the Xcode project for the distributable app bundle. ```sh swift build # build the libraries + dev executable swift test # run the test suites swift run vee # run the menu-bar app for development # Build the distributable app bundle: xcodegen generate xcodebuild -project Vee.xcodeproj -scheme Vee build ``` -------------------------------- ### Preview menu structure with --text Source: https://github.com/navbytes/vee/blob/main/docs/_content/debugging.md Treats a file as static output to preview menu formatting without executing code. ```sh $ cat menu.txt CPU 42% | color=red --- Open dashboard | href=https://example.com $ vee dev --text menu.txt ``` -------------------------------- ### Build and verify generated documentation partials Source: https://github.com/navbytes/vee/blob/main/CONTRIBUTING.md Scripts to generate documentation partials from the parameter JSON or verify if existing partials are up to date. ```sh python3 docs/scripts/build_reference.py # write the generated partials python3 docs/scripts/build_reference.py --check # fails if a partial is stale ``` -------------------------------- ### Accessing full plugin documentation Source: https://github.com/navbytes/vee/blob/main/docs/_content/writing-plugins-with-an-llm.md The complete plugin documentation is available as a single Markdown file for LLM context. ```text https://vee.navbytes.io/llms-full.txt ``` -------------------------------- ### JSON Output Schema Example Source: https://github.com/navbytes/vee/blob/main/docs/_content/json-output.md A sample JSON structure conforming to the Vee output schema. The $schema property is ignored by the engine. ```json { "$schema": "https://vee.navbytes.io/schemas/json-output.schema.json", "vee": 1, "title": [{ "text": "System" }], "items": [{ "text": "Hello" }] } ``` -------------------------------- ### MDM Configuration Profile Payload Source: https://github.com/navbytes/vee/blob/main/docs/_content/enterprise-store.md An example XML payload for configuring managed stores and disabling the public catalog via MDM. ```xml vee.managedStores idacme-internal displayNameAcme Internal Tools kindgithubEnterprise apiHosthttps://ghe.acme.corp/api/v3 rawHosthttps://ghe.acme.corp/raw ownerplatform repovee-plugins requireSignature pinnedSigningKeyMCowBQYDK2VwAyEA… vee.disablePublicStore ``` -------------------------------- ### Run tests and build fixtures Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md Commands to run the drift guard tests and regenerate fixtures. ```sh cd plugins/typescript npm test # fixture drift guard (node --test) npm run build:fixtures # regenerate ../fixtures from the examples ``` -------------------------------- ### Build menus using SDKs Source: https://github.com/navbytes/vee/blob/main/docs/_content/json-output.md Demonstrates how to use the typed builders in TypeScript, Python, and Go to generate the same JSON menu structure. ```ts import { JSONMenu } from "./vee.ts"; const menu = new JSONMenu(); menu.title("JSON ✓", { color: "green", sfimage: "curlybraces" }); const d = menu.dropdown; d.item("Structured item", { href: "https://example.com" }); d.separator(); d.submenu("Submenu").item("Child", { color: "blue" }); menu.print(); ``` ```python from vee import JSONMenu menu = JSONMenu() menu.title("JSON ✓", color="green", sfimage="curlybraces") d = menu.dropdown d.item("Structured item", href="https://example.com") d.separator() d.submenu("Submenu").item("Child", color="blue") menu.print() ``` ```go m := &vee.JSONMenu{} m.Title("JSON ✓", &vee.JSONOptions{Color: vee.Str("green"), SFImage: vee.Str("curlybraces")}) d := m.Dropdown() d.Item("Structured item", &vee.JSONOptions{Href: vee.Str("https://example.com")}) d.Separator() d.Submenu("Submenu", nil).Item("Child", &vee.JSONOptions{Color: vee.Str("blue")}) m.Print() ``` -------------------------------- ### Define Store Identification and Trust Policies Source: https://github.com/navbytes/vee/blob/main/docs/design/custom-plugin-store.md Core types for identifying stores, defining their kind, and setting trust policies for installation. ```swift public struct StoreID: Hashable, Codable, Sendable { public let rawValue: String // e.g. "com.vee.store.xbar", "acme-internal" } public enum StoreKind: String, Codable, Sendable { case github, githubEnterprise, http, local } /// How loudly the install gate frames a store. Never changes enforcement — /// provenance + trust scan always run; this only reframes and sets the default /// button posture. public enum StoreTrustPolicy: String, Codable, Sendable { case publicUntrusted // current behavior: full warnings, no default action case internalReviewed // "Reviewed internal source"; warnings still shown } ``` -------------------------------- ### Push ephemeral plugin to menu bar Source: https://github.com/navbytes/vee/blob/main/docs/_content/debugging.md Sends plugin output directly to the running Vee app for real-time previewing without installing the file. ```sh $ vee dev --push ./cpu.10s.sh ``` -------------------------------- ### Create the plugins directory Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md Ensures the default plugins directory exists before adding new scripts. ```sh mkdir -p ~/Library/Application\ Support/Vee/plugins ``` -------------------------------- ### Import SDK from local file Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md Import the Menu class from the local SDK file. ```ts import { Menu } from "./vee.ts"; ``` -------------------------------- ### Provide JSON Schemas for Plugin Generation Source: https://github.com/navbytes/vee/blob/main/docs/_content/writing-plugins-with-an-llm.md Use these schema URLs to guide the LLM in generating structured plugin output that adheres to Vee's requirements. ```text https://vee.navbytes.io/schemas/widget-card.schema.json https://vee.navbytes.io/schemas/json-output.schema.json ``` -------------------------------- ### Import the Vee SDK Source: https://github.com/navbytes/vee/blob/main/plugins/go/README.md Import the package to access the Menu, Section, and Options builders. ```go import vee "github.com/navbytes/vee/plugins/go" ```