# 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.
- 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+.

```bash
go build -o luxtools-client .
```

## Run

```bash
./luxtools-client
```

On startup, if you don’t pass `-token`, the server generates a random token and prints it to the logs. Put that token into the Dokuwiki plugin configuration.

### Flags

- `-listen` (default `127.0.0.1:8765`): listen address (`host:port`). Must be loopback.
- `-token` (default empty): shared secret token. If empty, a token is generated and logged at startup.
- `-allow` (repeatable): allowed path prefix. If you specify one or more, the requested path must start with one of them.

Examples:

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

# Use an explicit token (recommended for stable config)
./luxtools-client -token "your-shared-secret"

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

## Install as a service

The scripts below install (or update) the client as a service that starts automatically with the system.
They assume the client binary already exists in the same folder as the scripts.
During install/update, the scripts prompt you for the shared token (press Enter to keep the current token, if already configured).

### Linux (systemd)

Install / update:

```bash
./install-linux.sh
```

Optional flags:

```bash
# Change listen address (still must be loopback)
./install-linux.sh --listen 127.0.0.1:9000

# Restrict allowed folders (repeatable)
./install-linux.sh --allow "$HOME" --allow "/mnt/data"
```

Uninstall:

```bash
./uninstall-linux.sh
```

Keep token/config on uninstall:

```bash
./uninstall-linux.sh --keep-config
```

Notes:

- Installs to `~/.local/share/luxtools-client/luxtools-client`
- Creates a systemd *user* unit at `~/.config/systemd/user/luxtools-client.service`
- Stores config (including the token) 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:

```bat
install-windows-task.bat
```

Optional flags:

```bat
install-windows-task.bat --listen 127.0.0.1:9000

REM Restrict allowed folders (repeatable)
install-windows-task.bat --allow "%USERPROFILE%" --allow "D:\Data"
```

Uninstall:

```bat
uninstall-windows-task.bat
```

Keep token/config on uninstall:

```bat
uninstall-windows-task.bat --keep-config
```

Notes:

- Installs to `%LOCALAPPDATA%\luxtools-client\luxtools-client.exe`
- Stores config (including the token) in `%LOCALAPPDATA%\luxtools-client\config.json`
- Re-running the install script updates the EXE in place and restarts the task.

## API

### Auth

Requests must include the token using the `X-Luxtools-Token` header.

- Header: `X-Luxtools-Token: <token>`
- For `GET /open`, a `token=...` query parameter is also accepted as a fallback.

### `GET /health`

Returns JSON:

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

### `POST /open`

Request body:

```json
{"path": "/absolute/path"}
```

Response:

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

Example:

```bash
curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Luxtools-Token: your-shared-secret' \
  --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:

```bash
curl -i \
  -H 'X-Luxtools-Token: your-shared-secret' \
  'http://127.0.0.1:8765/open?path=/tmp'
```

## 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.