luxtools-client/README.md

luxtools-client

Small local HTTP helper that lets the Dokuwiki plugin luxtools open folders on the same machine.

This program runs on the user’s machine and listens on a loopback address only (defaults to 127.0.0.1:8765). The plugin calls it to open a folder in the OS file manager.

What it does

• Exposes GET /health for a simple health check.
• Exposes GET /open?path=... and POST /open to open a folder.
• Exposes GET /control (HTML) and GET /logs (text) to view recent logs.
• Normalizes and validates the requested path:
  • Accepts absolute paths only.
  • If a file path is provided, it opens the containing directory.
  • Accepts file://... URLs (handy when the caller passes a file URL).
• Optionally restricts which folders can be opened via -allow prefixes.

Build

Requires Go 1.22+.

make build

Output:

• dist/luxtools-client (or dist/luxtools-client.exe on Windows)

Cross-compile

# Linux (amd64)
make build-linux

# Windows (amd64)
make build-windows

# Both
make build-all

Run

./luxtools-client

Flags

• -listen (default 127.0.0.1:8765): listen address (host:port). Must be loopback.
• -allow (repeatable): allowed path prefix. If you specify one or more, the requested path must start with one of them.

Examples:

# Listen on a different local port
./luxtools-client -listen 127.0.0.1:9000

# Restrict opens to your home directory (repeat -allow as needed)
./luxtools-client -allow "$HOME"

Install as a service

Use the built-in install / uninstall commands to install (or update) the client as a per-user service that starts automatically. The install command copies the currently-running binary into the appropriate per-user install location.

Linux (systemd)

Install / update:

./luxtools-client install

Optional flags:

# Change listen address (still must be loopback)
./luxtools-client install -listen 127.0.0.1:9000

# Restrict allowed folders (repeatable)
./luxtools-client install -allow "$HOME" -allow "/mnt/data"

# Validate only (no files written, no service changes)
./luxtools-client install -dry-run

Uninstall:

./luxtools-client uninstall

Keep config on uninstall:

./luxtools-client uninstall -keep-config

# Validate only (no files removed, no service changes)
./luxtools-client uninstall -dry-run

Notes:

• Installs to ~/.local/share/luxtools-client/luxtools-client
• Creates a systemd user unit at ~/.config/systemd/user/luxtools-client.service
• Enables the unit under graphical-session.target (so it starts with the GUI session)
• Stores config in ~/.config/luxtools-client/luxtools-client.env

Windows (Scheduled Task at logon)

Because this tool needs to open File Explorer (a GUI app) in the current user session, it should run as a per-user Scheduled Task triggered “At log on” (similar to a systemd user service).

Install / update:

luxtools-client.exe install

Optional flags:

luxtools-client.exe install -listen 127.0.0.1:9000

REM Restrict allowed folders (repeatable)
luxtools-client.exe install -allow "%USERPROFILE%" -allow "D:\Data"

REM Validate only (no files written, no task changes)
luxtools-client.exe install -dry-run

Uninstall:

luxtools-client.exe uninstall

Keep config on uninstall:

luxtools-client.exe uninstall -keep-config

REM Validate only (no files removed, no task changes)
luxtools-client.exe uninstall -dry-run

Notes:

• Installs to %LOCALAPPDATA%\luxtools-client\luxtools-client.exe
• Stores config in %LOCALAPPDATA%\luxtools-client\config.json
• Re-running install updates the EXE in place and refreshes the task.
• Windows builds use the GUI subsystem, so the app starts without a console window.
• Logs are written next to config.json and can be viewed at http://127.0.0.1:8765/control or http://127.0.0.1:8765/logs.

API

GET /health

Returns JSON:

{"ok": true, "time": "2026-01-05T12:34:56Z"}

POST /open

Request body:

{"path": "/absolute/path"}

Response:

{"ok": true, "message": "opened"}

Example:

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data '{"path":"/tmp"}' \
  http://127.0.0.1:8765/open

GET /open?path=...

For GET callers, success returns 204 No Content (to reduce console noise in certain callers).

Example:

curl -i \
  'http://127.0.0.1:8765/open?path=/tmp'

GET /logs

Returns recent log output as plain text.

GET /control

Shows a simple HTML page with recent log output.

OS support

• Linux: uses xdg-open.
• Windows: uses explorer.exe.

Notes / security

• The server refuses to bind to non-loopback addresses.
• Use -allow to prevent opening arbitrary folders if other local processes can reach the port.