DevBuddy Workbench

A minimal local workbench. Express serves both the interface and API, and manages local project scripts.

Run

npm install
npm run build
npm start

Open http://localhost:3100. To use another port, run PORT=4000 npm start. Startup attempts to stop any process currently using the selected port.

When using the devbuddy CLI, pass the port directly with --port:

devbuddy start --port 4000
devbuddy restart --port 4000

Update the globally installed CLI from npm:

devbuddy self-update
devbuddy self-update 0.1.32

Running on macOS

Double-click Launcher (Terminal)

A pre-configured macOS launcher Start Buddy.command is available in the root directory.

1. Simply double-click Start Buddy.command in Finder to start the workbench.
2. A terminal window will open showing the server logs.
3. Close the terminal window to stop the workbench and all of its running service processes.

Background App (Automator)

To run the workbench in the background without leaving a terminal window open:

1. Open the Automator app on your Mac.
2. Create a new document and choose Application.
3. Search for the Run Shell Script action and drag it into the workflow.
4. Set the Shell option to /bin/bash (or /bin/zsh).
5. Paste the following script:

    # Load user shell profile to inherit full terminal PATH (like nvm, fnm, npm-global, etc.)
    if [ -f "$HOME/.zprofile" ]; then source "$HOME/.zprofile"; fi
    if [ -f "$HOME/.zshrc" ]; then source "$HOME/.zshrc"; fi
       
    # Fallbacks for standard paths and npm global binaries
    export PATH="$HOME/.npm-global/bin:/usr/local/bin:/opt/homebrew/bin:$PATH"
       
    cd "/Users/lynan/Documents/GitHub/buddy"
    npm start

   (Note: Adjust the path if the directory moves.)
6. Save (Cmd + S) the document as Buddy.app in your Applications folder or Desktop.
7. Custom Icon:
   • Copy the icon file ui/public/devbuddy.icns (Cmd + C).
   • Select Buddy.app, press Cmd + I (Get Info), click the small icon at the top-left of the info panel, and press Cmd + V.

UI development

The UI is an independent React + Vite project in ui/, built with Ant Design. Run npm run build to build it, then run npm start to start Express. For UI development, use npm run dev in one terminal and npm run dev:ui in another; Vite proxies API and plugin requests to Express.

Plugins

Create a manifest at plugins/<plugin-name>/plugin.json to add an item to the sidebar:

{ "name": "My feature", "icon": "✦", "view": "view.html" }

Plugins are discovered automatically. view points to an HTML fragment in the plugin directory. Place your HTML, scripts, and styles in an isolated plugin folder. Add API routes as needed for server-side capabilities.

Scripts and logs

Each service can have multiple named scripts. Run, stop, and view the last 1,000 lines of output for each script from the launcher. Logs are retained in memory until the workbench is restarted and refresh in the browser every second while the log window is open.