Merge pull request #33 from automagik-dev/fix/headless-keyring-setup

fix(auth): probe SecretService + headless-first docs

Author: namastex888

install.sh

@@ -415,7 +415,8 @@ if [ ! -t 0 ]; then
     printf "\n"
     printf "Next steps:\n"
     printf "  1. wk auth status                              → check existing accounts\n"
-    printf "  2. wk auth manage                              → connect Google account (prints URL)\n"
+    printf "  2. wk auth add user@example.com --headless     → prints auth URL, polls for token\n"
+    printf "     (keyring auto-configured on headless Linux — no manual setup needed)\n"
     printf "  3. wk gmail search 'newer_than:1d' --json      → first query\n"
     printf "\n"
     printf "Available services: Gmail, Calendar, Drive, Sheets, Docs, Slides,\n"

internal/setup/keyring.go

@@ -4,14 +4,17 @@ package setup
 
 import (
 	"bufio"
+	"context"
 	"crypto/rand"
 	"encoding/hex"
 	"fmt"
 	"io"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
 	"strings"
+	"time"
 
 	"github.com/automagik-dev/workit/internal/config"
 	"github.com/automagik-dev/workit/internal/secrets"
@@ -41,8 +44,9 @@ var (
 // NeedsFileBackendSetup reports whether the current environment will use
 // the keyring file backend and therefore needs automatic password setup.
 //
-// Returns true on Linux when the resolved backend is "auto" and no
-// DBUS_SESSION_BUS_ADDRESS is set (headless environment).
+// Returns true on Linux when the resolved backend is "auto" and either
+// no DBUS_SESSION_BUS_ADDRESS is set, or D-Bus is present but the
+// org.freedesktop.secrets service (gnome-keyring/KeePassXC) is not available.
 func NeedsFileBackendSetup(goos string, dbusAddr string) (bool, error) {
 	if goos != "linux" {
 		return false, nil
@@ -59,19 +63,52 @@ func NeedsFileBackendSetup(goos string, dbusAddr string) (bool, error) {
 		return false, nil
 	}
 
-	// D-Bus present means SecretService/gnome-keyring is likely available.
-	if dbusAddr != "" {
-		return false, nil
+	// No D-Bus at all → definitely needs file backend.
+	if dbusAddr == "" {
+		return true, nil
+	}
+
+	// D-Bus is present, but SecretService might not be running
+	// (common on headless servers with systemd but no gnome-keyring).
+	// Probe for the org.freedesktop.secrets name on the session bus.
+	if !isSecretServiceAvailable() {
+		return true, nil
 	}
 
-	return true, nil
+	return false, nil
+}
+
+// secretServiceProbeTimeout is the maximum time to wait for dbus-send to respond.
+const secretServiceProbeTimeout = 2 * time.Second
+
+// isSecretServiceAvailable checks whether the org.freedesktop.secrets D-Bus
+// service is registered on the session bus. Returns false if dbus-send is not
+// installed or the service is not available.
+var isSecretServiceAvailable = func() bool {
+	ctx, cancel := context.WithTimeout(context.Background(), secretServiceProbeTimeout)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "dbus-send",
+		"--session",
+		"--dest=org.freedesktop.DBus",
+		"--type=method_call",
+		"--print-reply",
+		"/org/freedesktop/DBus",
+		"org.freedesktop.DBus.NameHasOwner",
+		"string:org.freedesktop.secrets",
+	)
+	out, err := cmd.Output()
+	if err != nil {
+		return false
+	}
+	return strings.Contains(string(out), "true")
 }
 
 // SetupKeyringIfNeeded detects whether the file keyring backend will be used
 // and, if so, generates a random password, saves it to keyring.key, writes
 // credentials.env, and configures the user's shell profile to source it.
 //
-// On macOS or Linux with D-Bus present, this is a no-op.
+// On macOS or Linux with a working SecretService, this is a no-op.
 // If keyring.key already exists, the existing password is reused.
 //
 // Status messages are written to w (typically os.Stderr).

internal/setup/keyring_test.go

@@ -11,24 +11,31 @@ import (
 )
 
 func TestNeedsFileBackendSetup(t *testing.T) {
-	// Save and restore the original resolveBackendInfo.
+	// Save and restore the original stubs.
 	origResolve := resolveBackendInfo
+	origProbe := isSecretServiceAvailable
 
-	t.Cleanup(func() { resolveBackendInfo = origResolve })
+	t.Cleanup(func() {
+		resolveBackendInfo = origResolve
+		isSecretServiceAvailable = origProbe
+	})
 
 	// Mock: return "auto" backend with "default" source (typical fresh install).
 	resolveBackendInfo = func() (secrets.KeyringBackendInfo, error) {
 		return secrets.KeyringBackendInfo{Value: "auto", Source: "default"}, nil
 	}
 
+	// Mock: SecretService is available (for dbus-present cases).
+	isSecretServiceAvailable = func() bool { return true }
+
 	tests := []struct {
 		name     string
 		goos     string
 		dbusAddr string
 		want     bool
 	}{
 		{"linux headless", "linux", "", true},
-		{"linux with dbus", "linux", "/run/user/1000/bus", false},
+		{"linux with dbus and secret service", "linux", "/run/user/1000/bus", false},
 		{"darwin", "darwin", "", false},
 		{"darwin with dbus", "darwin", "/tmp/bus", false},
 		{"windows", "windows", "", false},
@@ -46,6 +53,20 @@ func TestNeedsFileBackendSetup(t *testing.T) {
 			}
 		})
 	}
+
+	// D-Bus present but SecretService NOT running → needs file backend.
+	t.Run("linux with dbus but no secret service", func(t *testing.T) {
+		isSecretServiceAvailable = func() bool { return false }
+
+		got, err := NeedsFileBackendSetup("linux", "/run/user/1000/bus")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+
+		if !got {
+			t.Error("expected true when D-Bus present but SecretService unavailable")
+		}
+	})
 }
 
 func TestNeedsFileBackendSetup_ExplicitBackend(t *testing.T) {
@@ -371,11 +392,13 @@ func TestSetupKeyringIfNeeded_NoOp_LinuxWithDBus(t *testing.T) {
 	origGOOS := runtimeGOOS
 	origResolve := resolveBackendInfo
 	origGetenv := getenv
+	origProbe := isSecretServiceAvailable
 
 	t.Cleanup(func() {
 		runtimeGOOS = origGOOS
 		resolveBackendInfo = origResolve
 		getenv = origGetenv
+		isSecretServiceAvailable = origProbe
 	})
 
 	runtimeGOOS = "linux"
@@ -389,6 +412,8 @@ func TestSetupKeyringIfNeeded_NoOp_LinuxWithDBus(t *testing.T) {
 
 		return ""
 	}
+	// Mock SecretService as available so setup is a no-op.
+	isSecretServiceAvailable = func() bool { return true }
 
 	var buf bytes.Buffer
 	if err := SetupKeyringIfNeeded(&buf); err != nil {

plugins/workit/skills/setup.md

@@ -19,30 +19,28 @@ Check: `wk version` and `wk auth status`
 
 ## Auth flows by environment
 
-### Desktop / laptop
+### Agent / automation / headless server (recommended)
 ```bash
-wk auth manage   # opens browser, auto-closes after login
+wk auth add user@example.com --headless
+# Prints a Google login URL → user opens it in any browser
+# CLI polls auth.automagik.dev until token arrives, then stores it
+# Keyring auto-configured on headless Linux — no manual setup needed
 ```
 
-### Remote server / VPS (SSH headless)
+### Two-step (scripting / no-poll)
 ```bash
-wk auth manage   # detects no TTY, prints URL with server outbound IP
-# Open printed URL in your browser — auth completes automatically
+wk auth add user@example.com --headless --no-poll
+# Prints URL + state, returns immediately
+wk auth poll <state>
+# Polls and stores token when ready
 ```
 
-### Agent / automation (fully unattended)
-```bash
-wk auth add user@example.com --headless --no-input
-# Prints a Google login URL. User (or automation) opens it.
-# CLI polls auth.automagik.dev until token arrives, then stores it.
-```
-
-### Get just the URL (for scripting)
+### Desktop / laptop
 ```bash
-wk auth manage --print-url   # prints JSON: {"url":"https://...","state":"..."}
+wk auth manage   # opens browser, auto-closes after login
 ```
 
-**Linux headless keyring:** auto-configured. No manual setup or `source` needed after v2.260227.4+.
+**Linux headless keyring:** auto-configured. No manual setup or `source` needed after v2.260303.2+.
 
 ---
 
@@ -101,7 +99,7 @@ wk auth service-account unset
 
 ## 8) Recommended pattern in agents
 1. `wk auth status` — check if account already exists
-2. If not: `wk auth manage` — opens auth (prints URL on headless, browser otherwise)
+2. If not: `wk auth add user@example.com --headless` — prints auth URL, polls until done
 3. `wk auth services` — verify services are authorized
 4. Read operations: add `--read-only`
 5. Write operations: `--dry-run` first, then without after confirmation