feat(log): log.format=json|text with emoji-strip production handler

New log.format config key (default "text"; DOCSIQ_LOG_FORMAT env).
Precedence is --log-format > env > config > default. The json handler
is wrapped in obs.NewProductionHandler, which strips a leading emoji
from slog Record.Message so log aggregators do not have to special-
case multi-byte sequences. The text handler keeps emoji for human
readers. Adds config-level defaults + env binding and three load-
level tests covering default, YAML, and env-var precedence.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: aksOps

cmd/logformat_test.go

@@ -3,7 +3,10 @@ package cmd
 import (
 	"bytes"
 	"encoding/json"
+	"io"
 	"log/slog"
+	"os"
+	"path/filepath"
 	"testing"
 )
 
@@ -28,3 +31,73 @@ func TestLogFormatJSON(t *testing.T) {
 		t.Errorf("k = %v, want v", decoded["k"])
 	}
 }
+
+// TestBuildLogHandler_JSONStripsEmoji confirms buildLogHandler returns
+// a handler chain that strips emoji from the message when format=json.
+// buildLogHandler writes to os.Stderr so we redirect it through a pipe
+// for the test (NOT parallel — shares global os.Stderr).
+func TestBuildLogHandler_JSONStripsEmoji(t *testing.T) {
+	origStderr := os.Stderr
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("pipe: %v", err)
+	}
+	os.Stderr = w
+	t.Cleanup(func() { os.Stderr = origStderr })
+
+	h := buildLogHandler(slog.LevelInfo, "json")
+	slog.New(h).Info("✅ ready", "k", "v")
+	_ = w.Close()
+
+	out, err := io.ReadAll(r)
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+
+	var rec map[string]any
+	if err := json.Unmarshal(bytes.TrimSpace(out), &rec); err != nil {
+		t.Fatalf("not JSON: %v — raw=%q", err, out)
+	}
+	msg, _ := rec["msg"].(string)
+	if msg != "ready" {
+		t.Errorf("msg=%q want 'ready' (emoji stripped)", msg)
+	}
+}
+
+// TestInitConfig_LogFormatFromConfigFile asserts the config file is
+// consulted when neither --log-format nor DOCSIQ_LOG_FORMAT is set.
+// NOT parallel — mutates env + HOME + package-level flags.
+func TestInitConfig_LogFormatFromConfigFile(t *testing.T) {
+	origHome := os.Getenv("HOME")
+	origLogFormat := os.Getenv("DOCSIQ_LOG_FORMAT")
+	t.Cleanup(func() {
+		logLevel = "info"
+		logFormat = ""
+		cfgFile = ""
+		cfg = nil
+		os.Setenv("HOME", origHome)
+		if origLogFormat != "" {
+			os.Setenv("DOCSIQ_LOG_FORMAT", origLogFormat)
+		}
+	})
+
+	dir := t.TempDir()
+	os.Setenv("HOME", dir)
+	os.Unsetenv("DOCSIQ_LOG_FORMAT")
+
+	yaml := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(yaml, []byte("log:\n  format: json\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfgFile = yaml
+	logFormat = ""
+
+	initConfig()
+
+	if cfg == nil {
+		t.Fatal("initConfig produced nil cfg")
+	}
+	if cfg.Log.Format != "json" {
+		t.Errorf("cfg.Log.Format=%q want json", cfg.Log.Format)
+	}
+}

cmd/root.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 
 	"github.com/RandomCodeSpace/docsiq/internal/config"
+	"github.com/RandomCodeSpace/docsiq/internal/obs"
 	"github.com/spf13/cobra"
 )
 
@@ -41,7 +42,7 @@ func init() {
 }
 
 func initConfig() {
-	// Set up structured logger
+	// Set up structured logger. Level comes from --log-level only.
 	var level slog.Level
 	switch logLevel {
 	case "debug":
@@ -53,32 +54,51 @@ func initConfig() {
 	default:
 		level = slog.LevelInfo
 	}
-	// Log format: --log-format wins, else DOCSIQ_LOG_FORMAT, else "text".
+
+	// Format resolution order (highest wins):
+	//   1. --log-format flag
+	//   2. DOCSIQ_LOG_FORMAT env var
+	//   3. config file log.format
+	//   4. default "text"
+	// (3) requires config.Load() to have run; install a temporary
+	// handler first so config-load errors land somewhere, then
+	// upgrade once the final format is known.
 	format := strings.ToLower(strings.TrimSpace(logFormat))
 	if format == "" {
 		format = strings.ToLower(strings.TrimSpace(os.Getenv("DOCSIQ_LOG_FORMAT")))
 	}
-	handlerOpts := &slog.HandlerOptions{Level: level}
-	var handler slog.Handler
-	switch format {
-	case "json":
-		handler = slog.NewJSONHandler(os.Stderr, handlerOpts)
-	default:
-		handler = slog.NewTextHandler(os.Stderr, handlerOpts)
-	}
-	slog.SetDefault(slog.New(handler))
+
+	slog.SetDefault(slog.New(buildLogHandler(level, format)))
 
 	var err error
 	cfg, err = config.Load(cfgFile)
 	if err != nil {
 		slog.Error("❌ config error", "err", err)
 		os.Exit(1)
 	}
-	if err := os.MkdirAll(cfg.DataDir, 0755); err != nil {
+	if err := os.MkdirAll(cfg.DataDir, 0o755); err != nil {
 		slog.Error("❌ failed to create data directory", "path", cfg.DataDir, "err", err)
 		os.Exit(1)
 	}
-}
-
 
+	// If neither flag nor env specified format, use the value from
+	// the loaded config (falls back to default "text").
+	if format == "" && cfg.Log.Format != "" {
+		format = strings.ToLower(strings.TrimSpace(cfg.Log.Format))
+		slog.SetDefault(slog.New(buildLogHandler(level, format)))
+	}
+}
 
+// buildLogHandler assembles the slog handler chain. For "json" format
+// we wrap the JSON handler in obs.NewProductionHandler to strip emoji
+// prefixes from the message field (keeping them is harmless but noisy
+// for log aggregators). "text" keeps emoji for human readability.
+func buildLogHandler(level slog.Level, format string) slog.Handler {
+	opts := &slog.HandlerOptions{Level: level}
+	switch format {
+	case "json":
+		return obs.NewProductionHandler(slog.NewJSONHandler(os.Stderr, opts))
+	default:
+		return slog.NewTextHandler(os.Stderr, opts)
+	}
+}

internal/config/config.go

@@ -17,6 +17,7 @@ type Config struct {
 	Indexing       IndexingConfig  `mapstructure:"indexing"`
 	Community      CommunityConfig `mapstructure:"community"`
 	Server         ServerConfig    `mapstructure:"server"`
+	Log            LogConfig       `mapstructure:"log"`
 
 	// Phase-5: per-project LLM overrides. Keyed by project slug.
 	// When a slug is missing from the map, callers fall back to the
@@ -25,6 +26,16 @@ type Config struct {
 	LLMOverrides map[string]LLMConfig `mapstructure:"llm_overrides"`
 }
 
+// LogConfig controls structured-log emission format. Lowest-priority
+// source of truth — `--log-format` flag and `DOCSIQ_LOG_FORMAT` env
+// var both outrank this value in cmd/root.go.
+type LogConfig struct {
+	// Format chooses the slog handler. "text" (default) emits a
+	// human-readable single-line format with emoji prefixes; "json"
+	// strips emoji and emits machine-parseable JSON objects.
+	Format string `mapstructure:"format"`
+}
+
 // LLMConfigForProject returns the override for slug if present, otherwise
 // the root LLM config. A missing or empty slug yields the root config.
 // The Provider field is treated as the presence sentinel — a YAML block
@@ -219,6 +230,9 @@ func Load(cfgFile string) (*Config, error) {
 	v.SetDefault("server.workq_depth", 64)
 	v.SetDefault("server.hsts_enabled", false)
 
+	// Log format: "text" for human dev output, "json" for production.
+	v.SetDefault("log.format", "text")
+
 	// Config file search paths. Only ~/.docsiq and CWD are consulted.
 	newCfgDir := filepath.Join(home, ".docsiq")
 	if cfgFile != "" {
@@ -244,6 +258,7 @@ func Load(cfgFile string) (*Config, error) {
 	_ = v.BindEnv("server.workq_workers", "DOCSIQ_SERVER_WORKQ_WORKERS")
 	_ = v.BindEnv("server.workq_depth", "DOCSIQ_SERVER_WORKQ_DEPTH")
 	_ = v.BindEnv("server.hsts_enabled", "DOCSIQ_SERVER_HSTS_ENABLED")
+	_ = v.BindEnv("log.format", "DOCSIQ_LOG_FORMAT")
 
 	if err := v.ReadInConfig(); err != nil {
 		if _, ok := err.(viper.ConfigFileNotFoundError); ok {

internal/config/config_test.go

@@ -670,3 +670,52 @@ func captureSlog(t *testing.T) *syncBuffer {
 	t.Cleanup(func() { slog.SetDefault(prev) })
 	return buf
 }
+
+func TestLoad_LogFormatDefaultText(t *testing.T) {
+	// NOT parallel — mutates env + HOME.
+	dir := t.TempDir()
+	isolateEnv(t, dir)
+	// Empty cfgFile → Load searches ~/.docsiq (empty) + cwd, falls
+	// through to defaults.
+	cfg, err := Load("")
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.Log.Format != "text" {
+		t.Errorf("default Log.Format=%q want text", cfg.Log.Format)
+	}
+}
+
+func TestLoad_LogFormatFromYAML(t *testing.T) {
+	// NOT parallel — mutates env + HOME.
+	dir := t.TempDir()
+	isolateEnv(t, dir)
+	f := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(f, []byte("log:\n  format: json\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(f)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.Log.Format != "json" {
+		t.Errorf("Log.Format=%q want json", cfg.Log.Format)
+	}
+}
+
+func TestLoad_LogFormatFromEnv(t *testing.T) {
+	// NOT parallel — mutates env + HOME.
+	dir := t.TempDir()
+	isolateEnv(t, dir)
+	if err := os.Setenv("DOCSIQ_LOG_FORMAT", "json"); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Unsetenv("DOCSIQ_LOG_FORMAT")
+	cfg, err := Load("")
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.Log.Format != "json" {
+		t.Errorf("env Log.Format=%q want json", cfg.Log.Format)
+	}
+}

internal/obs/slogfmt.go

@@ -0,0 +1,81 @@
+package obs
+
+import (
+	"context"
+	"log/slog"
+	"strings"
+	"unicode/utf8"
+)
+
+// NewProductionHandler wraps an inner slog.Handler and strips a
+// leading emoji + trailing space from each record's Message. docsiq
+// uses emoji prefixes (OK KO WARN etc.) as visual cues in dev text
+// format; in JSON these collide with log-aggregator indexing
+// (Elasticsearch tokeniser, fluentd grep rules) and obscure the actual
+// message string. The handler mutates only Message — attrs pass
+// through.
+func NewProductionHandler(inner slog.Handler) slog.Handler {
+	return &prodHandler{inner: inner}
+}
+
+type prodHandler struct{ inner slog.Handler }
+
+func (h *prodHandler) Enabled(ctx context.Context, lvl slog.Level) bool {
+	return h.inner.Enabled(ctx, lvl)
+}
+
+func (h *prodHandler) Handle(ctx context.Context, r slog.Record) error {
+	r.Message = stripLeadingEmoji(r.Message)
+	return h.inner.Handle(ctx, r)
+}
+
+func (h *prodHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return &prodHandler{inner: h.inner.WithAttrs(attrs)}
+}
+
+func (h *prodHandler) WithGroup(name string) slog.Handler {
+	return &prodHandler{inner: h.inner.WithGroup(name)}
+}
+
+// stripLeadingEmoji removes the first rune from msg if it is in a
+// Unicode emoji-like range, plus any immediately-following whitespace.
+// Also strips a VS16 variation selector (U+FE0F) that often follows
+// warning signs etc. We intentionally do NOT use a dependency like
+// mattn/go-emoji; docsiq ships under air-gap rules (see build.md).
+func stripLeadingEmoji(msg string) string {
+	if msg == "" {
+		return msg
+	}
+	r, size := utf8.DecodeRuneInString(msg)
+	if r == utf8.RuneError {
+		return msg
+	}
+	if !isEmojiLike(r) {
+		return msg
+	}
+	rest := msg[size:]
+	rest = strings.TrimLeft(rest, " \t")
+	if len(rest) > 0 {
+		r2, size2 := utf8.DecodeRuneInString(rest)
+		if r2 == 0xFE0F {
+			rest = strings.TrimLeft(rest[size2:], " \t")
+		}
+	}
+	return rest
+}
+
+// isEmojiLike is a conservative test for the emoji-range runes that
+// appear in docsiq log messages today. Covers BMP symbols
+// (U+2600-U+27BF), miscellaneous pictographs (U+1F300-U+1F6FF), and
+// supplemental symbols (U+1F900-U+1F9FF).
+func isEmojiLike(r rune) bool {
+	switch {
+	case r >= 0x2600 && r <= 0x27BF:
+		return true
+	case r >= 0x1F300 && r <= 0x1F6FF:
+		return true
+	case r >= 0x1F900 && r <= 0x1F9FF:
+		return true
+	}
+	return false
+}