feat(plugins): add exec, keymap, and CLI command APIs

- cliamp.exec.run(): allowlisted subprocess spawn for plugins,
  gated by permissions = {"exec"}
- p:bind([desc,] fn): plugin-registered TUI keybindings, gated by
  permissions = {"keymap"}; entries with a description appear in
  the Ctrl+K overlay. Core-reserved keys rejected at bind time.
- p:command(name, fn): shell-invokable plugin commands, dispatched
  over IPC via `cliamp plugins call <plugin> <command> [args...]`
  and listed via `cliamp plugins commands`.
- cliamp.fs: added mkdir/listdir; ~/Music/cliamp/ writable.

Author: bjarneo

commands.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"strconv"
 	"strings"
+	"time"
 
 	cli "github.com/urfave/cli/v3"
 
@@ -229,6 +230,48 @@ func pluginsCommand() *cli.Command {
 					return pluginmgr.Remove(c.Args().First())
 				},
 			},
+			{
+				Name:      "call",
+				Usage:     "invoke a plugin command in the running cliamp",
+				ArgsUsage: "<plugin> <command> [args...]",
+				Action: func(ctx context.Context, c *cli.Command) error {
+					args := c.Args().Slice()
+					if len(args) < 2 {
+						return fmt.Errorf("usage: cliamp plugins call <plugin> <command> [args...]")
+					}
+					resp, err := ipcSendLong(ipc.Request{
+						Cmd:  "plugin.call",
+						Name: args[0],
+						Sub:  args[1],
+						Args: args[2:],
+					}, 6*time.Minute)
+					if err != nil {
+						return err
+					}
+					if resp.Output != "" {
+						fmt.Println(resp.Output)
+					}
+					return nil
+				},
+			},
+			{
+				Name:  "commands",
+				Usage: "list plugin commands registered in the running cliamp",
+				Action: func(ctx context.Context, c *cli.Command) error {
+					resp, err := ipcSend(ipc.Request{Cmd: "plugin.commands"})
+					if err != nil {
+						return err
+					}
+					if len(resp.Items) == 0 {
+						fmt.Println("No plugin commands registered.")
+						return nil
+					}
+					for _, item := range resp.Items {
+						fmt.Println(item)
+					}
+					return nil
+				},
+			},
 		},
 	}
 }

docs/plugins.md

@@ -167,6 +167,47 @@ Plugins subscribe to events with `p:on(event, callback)`. Callbacks run asynchro
 
 The `status` field in `playback.state` is one of: `"playing"`, `"paused"`, `"stopped"`.
 
+## Plugin object methods
+
+The object returned by `plugin.register(...)` exposes additional methods beyond `:on()` / `:config()`:
+
+### `p:bind(key, [description,] callback)` — keyboard binding (requires `permissions = {"keymap"}`)
+
+```lua
+local p = plugin.register({
+    name = "my-plugin",
+    type = "hook",
+    permissions = {"keymap"},
+})
+
+-- Listed in the Ctrl+K overlay under "— plugins —":
+p:bind("x", "Extract chapters", function(key) ... end)
+
+-- Not listed (hidden binding):
+p:bind("ctrl+e", function(key) ... end)
+```
+
+Returns `true` on success, or `false, reason` if the key is already owned by cliamp's core UI or the plugin lacks the `keymap` permission. Pass a description string as the middle argument to surface the binding in the `Ctrl+K` keymap overlay; omit it for an internal-only binding.
+
+Key strings are in Bubbletea's `msg.String()` form: lowercase letters, `ctrl+` / `shift+` / `alt+` prefixes (e.g. `"x"`, `"ctrl+e"`, `"shift+f1"`). Case-insensitive.
+
+Plugin keys only fire in the main view — overlays like the file browser, theme picker, and keymap itself capture their own input. Core reserves all keys documented in `docs/keybindings.md`; trying to bind one of those logs a warning and returns `false`.
+
+Use `p:unbind(key)` to release a binding.
+
+### `p:command(name, callback)` — shell-invokable command
+
+```lua
+p:command("run", function(args)
+    -- args is an array of strings passed after the command name
+    return "done: " .. args[1]
+end)
+```
+
+The callback can return a string, which is printed by the CLI client. Commands are invoked from the shell via `cliamp plugins call <plugin-name> <command> [args...]` and dispatched to the running cliamp over IPC. Since dispatch runs in the running player, commands don't need a separate permission (they're user-initiated).
+
+List all registered commands with `cliamp plugins commands`. Commands can run for up to 5 minutes before timing out.
+
 ## Lua API
 
 All APIs are under the `cliamp` global table.
@@ -232,9 +273,11 @@ cliamp.fs.append(path, content)   -- append to file
 cliamp.fs.read(path)              --> string (max 1 MB)
 cliamp.fs.remove(path)            -- delete file
 cliamp.fs.exists(path)            --> boolean
+cliamp.fs.mkdir(path)             -- create directory (recursive)
+cliamp.fs.listdir(path)           --> {names}, err
 ```
 
-Writes are restricted to `/tmp/`, `~/.config/cliamp/`, and `~/.local/share/cliamp/`. Reads are allowed from anywhere.
+Writes are restricted to `/tmp/`, `~/.config/cliamp/`, `~/.local/share/cliamp/`, and `~/Music/cliamp/`. Reads are allowed from anywhere.
 
 ### cliamp.json
 
@@ -297,6 +340,46 @@ cliamp.notify("Song Title", "Artist Name") -- notification with title and body
 
 Sends a desktop notification via `notify-send`. Works with mako, dunst, and other notification daemons.
 
+### cliamp.exec (requires permissions)
+
+Plugins that declare `permissions = {"exec"}` can spawn subprocesses from a configurable binary allowlist. Default allowlist: `yt-dlp`, `ffmpeg`. Extend it in `config.toml`:
+
+```toml
+[plugins]
+allowed_binaries = "ffprobe, curl"   # merged with defaults
+```
+
+```lua
+local p = plugin.register({
+    name = "my-downloader",
+    type = "hook",
+    permissions = {"exec"},
+})
+
+local handle, err = cliamp.exec.run("yt-dlp", {"--dump-json", url}, {
+    on_stdout = function(line) ... end,   -- optional, called per line
+    on_stderr = function(line) ... end,   -- optional
+    on_exit   = function(code) ... end,   -- optional, fires exactly once
+    cwd       = "/tmp/work",              -- optional; must be in write allowlist
+    timeout   = 300,                       -- optional seconds, hard cap 1800
+})
+
+handle:cancel()                           -- terminate the process
+handle:alive()                            -- --> boolean
+```
+
+**Safety rails:**
+
+- Binary must be in the allowlist. Argv is argv — no shell, no expansion.
+- `args` must be a flat array of strings. Nested tables / non-strings are rejected.
+- Subprocess env is minimal (`PATH`, `HOME`, `LANG`) — secrets in the parent env are not passed through.
+- Output is capped at 4 MiB per process (stdout + stderr combined); further lines are dropped silently.
+- Concurrency capped at 4 running processes per plugin.
+- All processes owned by a plugin are killed on plugin unload and on cliamp exit.
+- Negative `on_exit` codes signal cancellation/timeout (`-1`) or spawn failure (`-2`).
+
+Without `permissions = {"exec"}`, `cliamp.exec.run` returns `nil, "exec permission required"`.
+
 ### cliamp.message
 
 ```lua
@@ -425,7 +508,7 @@ For security, plugins run with restricted access. The sandbox removes dangerous
 
 | Removed | Replacement |
 |---------|-------------|
-| `os.execute`, `os.remove`, `os.rename`, `os.exit`, `os.setlocale`, `os.tmpname` | Use `cliamp.http` or `cliamp.fs` |
+| `os.execute`, `os.remove`, `os.rename`, `os.exit`, `os.setlocale`, `os.tmpname` | Use `cliamp.fs`, `cliamp.http`, or permission-gated `cliamp.exec` |
 | `io` module (all of it) | Use `cliamp.fs` |
 | `dofile`, `loadfile` | Not available |
 
@@ -437,11 +520,12 @@ For security, plugins run with restricted access. The sandbox removes dangerous
 
 **Reads:** Allowed from any path (max 1 MB per read).
 
-**Writes/removes** are restricted to these directories only:
+**Writes/removes/mkdir** are restricted to these directories only:
 
 - `/tmp/` (and the system temp directory)
 - `~/.config/cliamp/`
 - `~/.local/share/cliamp/`
+- `~/Music/cliamp/`
 
 Attempts to write outside these directories will raise a Lua error. Directory traversal (`..`) is blocked.
 

ipc/client.go

@@ -26,6 +26,13 @@ func DefaultSocketPath() string {
 // Send connects to the IPC socket, sends a request, and returns the response.
 // The connection is closed after a single request/response exchange.
 func Send(sockPath string, req Request) (Response, error) {
+	return SendWithDeadline(sockPath, req, 5*time.Second)
+}
+
+// SendWithDeadline is like Send but lets the caller override the exchange
+// deadline. Plugin commands can legitimately run for minutes (downloads), so
+// the generic 5s cap is too short for them.
+func SendWithDeadline(sockPath string, req Request, deadline time.Duration) (Response, error) {
 	conn, err := net.DialTimeout("unix", sockPath, 3*time.Second)
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) || errors.Is(err, syscall.ECONNREFUSED) {
@@ -35,8 +42,7 @@ func Send(sockPath string, req Request) (Response, error) {
 	}
 	defer conn.Close()
 
-	// Set a deadline for the entire exchange.
-	conn.SetDeadline(time.Now().Add(5 * time.Second))
+	conn.SetDeadline(time.Now().Add(deadline))
 
 	// Encode and send the request as a single JSON line.
 	data, err := json.Marshal(req)

ipc/protocol.go

@@ -9,12 +9,14 @@ var _ Dispatcher = DispatcherFunc(nil)
 
 // Request is the JSON command sent by the client.
 type Request struct {
-	Cmd      string  `json:"cmd"`
-	Value    float64 `json:"value,omitempty"`
-	Playlist string  `json:"playlist,omitempty"`
-	Path     string  `json:"path,omitempty"`
-	Name     string  `json:"name,omitempty"`
-	Band     int     `json:"band,omitempty"`
+	Cmd      string   `json:"cmd"`
+	Value    float64  `json:"value,omitempty"`
+	Playlist string   `json:"playlist,omitempty"`
+	Path     string   `json:"path,omitempty"`
+	Name     string   `json:"name,omitempty"`
+	Band     int      `json:"band,omitempty"`
+	Sub      string   `json:"sub,omitempty"`
+	Args     []string `json:"args,omitempty"`
 }
 
 // Response is the JSON response sent by the server.
@@ -36,6 +38,16 @@ type Response struct {
 	Speed      float64    `json:"speed,omitempty"`
 	EQPreset   string     `json:"eq_preset,omitempty"`
 	Device     string     `json:"device,omitempty"`
+	Output     string     `json:"output,omitempty"`
+	Items      []string   `json:"items,omitempty"`
+}
+
+// PluginDispatcher is the hook the IPC server calls to forward plugin.call and
+// plugin.commands requests to the Lua plugin manager. Optional — if nil, those
+// subcommands return an error.
+type PluginDispatcher interface {
+	EmitCommand(plugin, command string, args []string) (string, error)
+	CommandList() []string
 }
 
 // TrackInfo is the track metadata in a status response.

ipc/server.go

@@ -27,10 +27,17 @@ type Server struct {
 	listener net.Listener
 	sockPath string
 	disp     Dispatcher
+	plugins  PluginDispatcher
 	done     chan struct{}
 	wg       sync.WaitGroup
 }
 
+// SetPluginDispatcher wires in the Lua plugin manager after the server starts.
+// Plugin dispatch is optional — without it, plugin subcommands return an error.
+func (s *Server) SetPluginDispatcher(p PluginDispatcher) {
+	s.plugins = p
+}
+
 // NewServer creates and starts the IPC server. It cleans up stale sockets
 // before binding. The socket is created with 0600 permissions (owner only).
 func NewServer(sockPath string, disp Dispatcher) (*Server, error) {
@@ -258,6 +265,25 @@ func (s *Server) dispatch(req Request) Response {
 	case "status":
 		return s.handleStatus()
 
+	case "plugin.call":
+		if s.plugins == nil {
+			return Response{OK: false, Error: "plugins not enabled"}
+		}
+		if req.Name == "" || req.Sub == "" {
+			return Response{OK: false, Error: "plugin.call requires plugin name and subcommand"}
+		}
+		out, err := s.plugins.EmitCommand(req.Name, req.Sub, req.Args)
+		if err != nil {
+			return Response{OK: false, Error: err.Error()}
+		}
+		return Response{OK: true, Output: out}
+
+	case "plugin.commands":
+		if s.plugins == nil {
+			return Response{OK: false, Error: "plugins not enabled"}
+		}
+		return Response{OK: true, Items: s.plugins.CommandList()}
+
 	default:
 		return Response{OK: false, Error: "unknown command: " + req.Cmd}
 	}

luaplugin/api_control.go

@@ -14,7 +14,7 @@ func registerControlAPI(L *lua.LState, cliamp *lua.LTable, ctrl *ControlProvider
 
 	warned := false
 	guard := func(name string) bool {
-		if !p.perms["control"] {
+		if !p.perms[PermControl] {
 			if !warned {
 				logger.log(p.Name, "warn", "%s requires permissions = {\"control\"} — further warnings suppressed", name)
 				warned = true